# Ollama: установка, модели, API и Modelfile. Полный гайд

> Как установить Ollama на macOS, Windows и Linux, выбрать модель под память, работать через CLI, REST и OpenAI-совместимый API и собрать Modelfile.
> Author: Roman Belov · Published: 2026-10-05 · Source: https://futurecraft.pro/ru/blog/ollama-guide/

Ollama - open-source программа под лицензией MIT для запуска языковых моделей на своём компьютере. Она скачивает модели из библиотеки ollama.com, управляет ими через CLI и поднимает локальный сервер на порту 11434: нативный REST API, OpenAI-совместимый `/v1` и Anthropic-совместимый `/v1/messages`. У репозитория [ollama/ollama](https://github.com/ollama/ollama) больше 186 тысяч звёзд, последний релиз на 6 ноября 2026 года - v0.40.15.

Установка занимает одну команду, первая модель запускается второй. Сложности начинаются потом: модель не помещается в память, агент теряет начало промпта, потому что на машине с видеопамятью меньше 24 GiB контекст по умолчанию всего 4k, `num_ctx` в Modelfile молча обрезается, а «кодовая» модель печатает вызовы инструментов текстом вместо того, чтобы их выполнить.

Статья о том, как поставить Ollama на macOS, Windows, Linux и в Docker, выбрать модель под объём памяти, работать с ней через CLI, `/api` и `/v1`, настроить контекст и собрать свой Modelfile. Цифры скорости и памяти сняты на Mac с Apple M4 Max и 36 ГБ памяти на Ollama 0.40.14. Где проверки не было (Windows, Linux, NVIDIA), это сказано прямо, команды взяты из документации.

## Что такое Ollama и когда она нужна

Ollama закрывает три задачи. Скачивает веса моделей из своей библиотеки (или берёт ваш GGUF-файл). Запускает модель на GPU, а если видеопамяти не хватает, частично на CPU. И держит HTTP-сервер, к которому обращаются CLI, приложение Ollama, ваш код и сторонние инструменты. Если выбираете между Ollama и LM Studio, сравнение с замерами на одной модели есть в статье [LM Studio или Ollama](https://futurecraft.pro/ru/blog/lm-studio-vs-ollama/).

Чем локальная модель отличается от облачного API:

| | Ollama (локально) | Облачный API (Claude, GPT) |
|---|---|---|
| Данные | Не покидают машину | Уходят провайдеру |
| Стоимость | Железо и электричество | Оплата за токены |
| Качество | Ниже фронтирных моделей, зависит от размера | Фронтирные модели |
| Скорость | Зависит от GPU и размера модели | Зависит от провайдера и нагрузки |
| Доступность | Работает офлайн после загрузки модели | Нужны сеть, аккаунт, оплата |

Про приватность в [FAQ](https://docs.ollama.com/faq) сказано прямо: при локальном запуске Ollama не видит ваши промпты и данные. Это частый аргумент за локальную модель: классификация личных данных, разбор логов, эксперименты без счёта за токены. Пример такого применения разобран в [постмортеме Ambient AI для macOS](https://futurecraft.pro/ru/blog/ambient-ai-mac-tauri-swift-ollama-postmortem/): там llama3.2:3b через Ollama анализирует паттерны работы, и данные не уходят в облако.

В production-архитектуре локальная модель обычно становится одним из провайдеров, а не заменой облаку. Как роутить задачи между моделями и держать fallback, разобрано в статье [Production LLM Stack](https://futurecraft.pro/ru/blog/production-llm-stack/).

## Как установить Ollama

Команды ниже взяты из [README](https://github.com/ollama/ollama) и [документации](https://docs.ollama.com) на ноябрь 2026. На macOS установка проверена, остальные платформы описаны по документации.

### macOS

Требования: macOS Sonoma (14) или новее. На Apple Silicon работают CPU и GPU, на Intel-Маках только CPU ([docs.ollama.com/macos](https://docs.ollama.com/macos)).

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

Второй вариант: скачать Ollama.dmg и перетащить приложение в Applications. При первом запуске приложение предложит создать ссылку на CLI в `/usr/local/bin`.

В Homebrew есть формула `ollama` в homebrew-core. Официальная документация этот способ не описывает. Формула ставит CLI и сервер без GUI-приложения, фоновый сервис запускается через `brew services start ollama`:

```bash
brew install ollama
brew services start ollama
```

### Windows

По [документации](https://docs.ollama.com/windows): Windows 10 22H2 или новее либо Windows 11, для NVIDIA нужен драйвер 551.61+, для AMD - стек с поддержкой ROCm v7 или Vulkan-драйвер Radeon. Права администратора не нужны, установщик ставит Ollama в домашнюю папку.

```powershell
irm https://ollama.com/install.ps1 | iex
```

Или скачать OllamaSetup.exe. Для запуска Ollama как службы есть архив `ollama-windows-amd64.zip`.

### Linux

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

Скрипт создаёт пользователя `ollama` и systemd-сервис. Для ручной установки на [странице Linux](https://docs.ollama.com/linux) есть архивы `.tar.zst` под amd64, arm64 и отдельный ROCm-пакет для AMD. Управление сервисом:

```bash
sudo systemctl status ollama
journalctl -e -u ollama          # логи сервера
sudo systemctl edit ollama       # переменные окружения
```

Обновление на Linux - повторный запуск того же скрипта.

### Docker

```bash
# Только CPU
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

# NVIDIA GPU (нужен NVIDIA Container Toolkit)
docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

docker exec -it ollama ollama run llama3.2
```

Для AMD есть образ `ollama/ollama:rocm` ([docs.ollama.com/docker](https://docs.ollama.com/docker)). На macOS Docker-вариант бесполезен для скорости: в [FAQ](https://docs.ollama.com/faq) указано, что в Docker Desktop на macOS GPU-ускорения нет. На Маке Ollama ставят нативно.

### Проверка установки

```bash
ollama --version
curl http://localhost:11434/api/version
# {"version":"0.40.14"}
```

Если CLI пишет `could not connect to a running Ollama instance`, сервер не запущен. Его поднимает приложение, systemd-сервис, `brew services` или команда `ollama serve` в отдельном терминале.

## Модели Ollama: как выбрать под железо

Главное ограничение - память. Модель должна целиком поместиться в видеопамять (на Apple Silicon - в ту часть unified memory, которую видит GPU), иначе часть слоёв уйдёт на CPU и скорость упадёт. Память уходит и на веса, и на KV-кэш контекста. Общий расчёт памяти, сравнение семейств моделей и замеры на 27B-моделях собраны в [гайде по локальным LLM](https://futurecraft.pro/ru/blog/local-llm-guide/).

Замер на Ollama 0.40.14 показывает разницу:

| Модель | Файл | В памяти (`ollama ps`, контекст 32768) |
|---|---|---|
| qwen2.5-coder:7b | 4.7 GB | 6.6 GB |
| qwen3:8b | 5.2 GB | 9.9 GB |

На macOS GPU доступна не вся память. На машине с 36 ГБ сервер Ollama в логе отчитался о `total_vram=28.1 GiB`.

Ориентиры по размерам ниже собраны по страницам тегов [ollama.com/library](https://ollama.com/library) на 6 ноября 2026. Это размеры файлов, к ним прибавляется память под контекст. Таблица даёт отправную точку, последнее слово за `ollama ps` на вашей машине.

| Память для GPU | Что разумно запускать | Примеры (размер файла) |
|---|---|---|
| 8 ГБ | 1-4B | qwen3:4b (2.5 GB), qwen3.5:4b (3.3-4.0 GB) |
| 16 ГБ | 7-9B | qwen2.5-coder:7b (4.7 GB), qwen3:8b (5.2 GB), qwen3.5:9b (6.6-7.6 GB) |
| 24-36 ГБ | 14-20B, MoE около 30B | qwen3:14b (9.3 GB), gpt-oss:20b (14 GB), qwen3:30b (19 GB) |
| 48 ГБ и больше | 27-35B | qwen3.8:27b (18 GB), qwen3.6:35b (23 GB) |
| Серверы, 80+ ГБ | 100B+ | gpt-oss:120b (65 GB), qwen3.5:122b (81 GB) |

### Теги и квантизация

Имя модели состоит из семейства и тега: `qwen3:8b`, `qwen3.6:27b-q4_K_M`. Тег без суффикса - вариант по умолчанию. Суффиксы `q4_K_M`, `q8_0`, `bf16` обозначают квантизацию: чем меньше бит на вес, тем меньше файл и расход памяти и тем заметнее потеря качества. У qwen3.8:27b это 18 GB в `q4_K_M`, 30 GB в `q8_0` и 56 GB в `bf16`. У части свежих моделей есть теги `-mlx` под Apple Silicon.

На странице каждой модели стоят метки возможностей:

- `tools` - модель обучена вызывать инструменты (function calling);
- `thinking` - умеет выдавать рассуждение перед ответом, его включают и выключают параметром `think`;
- `vision` - принимает картинки;
- `embedding` - модель для векторов, а не для чата (nomic-embed-text, bge-m3, qwen3-embedding);
- `cloud` - у модели есть облачный вариант, который работает на серверах Ollama.

Метка `tools` не гарантирует, что модель справится с агентом: у qwen2.5-coder:7b метка есть, а в OpenCode она печатала вызовы инструментов текстом.

### Ollama и Qwen

Модели Qwen в библиотеке занимают заметную часть верхних строк по загрузкам. На 6 ноября 2026 там есть:

| Модель | Размеры | Контекст | Метки |
|---|---|---|---|
| qwen2.5-coder | 0.5b-32b | 32K | tools |
| qwen3 | 0.6b-235b | 40K или 256K, зависит от размера | tools, thinking |
| qwen3-coder | 30b, 480b | 256K (30b) | tools |
| qwen3.5 | 0.8b-122b | 256K | vision, tools, thinking |
| qwen3.6 | 27b, 35b (35b-a3b) | 256K | vision, tools, thinking |
| qwen3.8 | 27b | 256K | vision, tools, thinking |

Для машины с 16 ГБ подходят qwen3:8b и qwen3.5:9b. qwen2.5-coder:7b справляется с короткими задачами на код в чате, но страница модели обновлялась больше года назад, а как агент она не работает. Нативный контекст у qwen3:8b - 40960 токенов, у qwen3.5 - 256K. Для агента это существенно: системный промпт OpenCode в тесте разрастался примерно до 53 тысяч токенов.

Нумерация семейств и состав библиотеки меняются каждые несколько недель: на момент проверки qwen3.8 обновлялась шесть дней назад, qwen3.6 - неделю назад. Перед выбором откройте страницу модели и проверьте дату обновления и теги.

## Команды Ollama CLI

| Команда | Что делает |
|---|---|
| `ollama run qwen3:8b` | Интерактивный чат; с аргументом-строкой выполняет один промпт |
| `ollama pull qwen3:8b` | Скачивает модель, обрыв докачивается при повторном запуске |
| `ollama ls` | Список скачанных моделей с размерами |
| `ollama ps` | Загруженные в память модели: память, PROCESSOR, CONTEXT, время до выгрузки |
| `ollama stop qwen3:8b` | Выгружает модель из памяти сразу |
| `ollama rm qwen3:8b` | Удаляет модель с диска |
| `ollama show qwen3:8b` | Параметры, нативный контекст, возможности; `--modelfile` выводит Modelfile |
| `ollama create name -f Modelfile` | Собирает модель из Modelfile |
| `ollama cp src dst` | Копирует модель под другим именем |
| `ollama serve` | Запускает сервер в текущем терминале |
| `ollama launch [интеграция]` | Настраивает и запускает внешний инструмент с Ollama |

Флаг `--verbose` у `ollama run` печатает статистику после ответа:

```bash
ollama run qwen2.5-coder:7b --verbose "Write a Python function is_prime(n)."
# total duration:  ...
# load duration:   ...   # загрузка модели в память
# prompt eval rate: ...  # скорость обработки промпта, tok/s
# eval count:       ...  # сколько токенов сгенерировано
# eval rate:        ...  # скорость генерации, tok/s
```

Для сравнения моделей смотрят `eval rate`, это скорость генерации ответа. `load duration` показывает, сколько ушло на загрузку модели: при первом запросе это секунды, у уже загруженной модели доли миллисекунды. У моделей с меткой `thinking` для коротких ответов рассуждение лучше выключить: `ollama run qwen3:8b --think=false`.

## Замер: qwen2.5-coder:7b и qwen3:8b на M4 Max

Стенд: Mac с Apple M4 Max, 36 ГБ памяти, macOS 27.2, Ollama 0.40.14 из Homebrew (релиз 0.40.15 на момент замера в формулу не попал). Сервер с настройками по умолчанию.

| Модель | Загрузка (load / total) | Генерация, первый запрос | Генерация, прогретая модель | `ollama ps` |
|---|---|---|---|---|
| qwen2.5-coder:7b | 2.11 с / 4.0 с | 69.5 tok/s | 68.9 tok/s | 6.6 GB, CONTEXT 32768, 100% GPU |
| qwen3:8b (`--think=false`) | 3.78 с / 6.5 с | 59.5 tok/s | 59.4 tok/s | 9.9 GB, CONTEXT 32768, 100% GPU |

Как читать цифры:

- Время загрузки снято, когда файлы модели уже лежали в кэше файловой системы macOS. Загрузку с холодного диска этот замер не показывает, она дольше.
- Скорость генерации у 7-8B моделей на этом железе держится около 60-70 токенов в секунду и почти не зависит от того, первый это запрос или нет.
- Скачивание qwen2.5-coder:7b (4.7 GB) на стабильном канале заняло около полутора минут. Время целиком определяется сетью.

Версия Ollama влияет на память. На Ollama 0.24.0 та же qwen2.5-coder:7b с тем же контекстом 32768 занимала 8.2 GB, на 0.40.14 - 6.6 GB, а скорость генерации почти не изменилась (72 и 70 tok/s против 69.5 и 68.9). Цифры из старых гайдов поэтому лучше перепроверять на своей версии.

## REST API Ollama

Нативный API живёт по адресу `http://localhost:11434/api`. Ключ локально не нужен ([docs.ollama.com/api](https://docs.ollama.com/api/introduction)). Полный список эндпоинтов есть в справочнике:

| Эндпоинт | Назначение |
|---|---|
| `POST /api/generate` | Ответ на один промпт |
| `POST /api/chat` | Ответ на историю сообщений, с tools |
| `POST /api/embed` | Эмбеддинги |
| `GET /api/tags` | Скачанные модели |
| `GET /api/ps` | Загруженные модели, `context_length`, `size_vram` |
| `POST /api/show` | Параметры и возможности модели |
| `POST /api/pull`, `/api/create`, `/api/copy`, `DELETE /api/delete` | Управление моделями |
| `GET /api/version` | Версия сервера |

Запрос к `/api/generate`:

```bash
curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen2.5-coder:7b",
  "prompt": "Write a one-line Python lambda that squares a number. Code only.",
  "stream": false,
  "options": {"num_predict": 60}
}' | jq -r .response
# ```python
# square = lambda x: x ** 2
# ```
```

На прогретой модели такой запрос отработал за 0.27 с. `/api/chat` принимает массив `messages` вместо `prompt`:

```bash
curl -s http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [{"role": "user", "content": "Explain a Python decorator in one sentence."}],
  "think": false,
  "stream": false
}' | jq -r .message.content
```

Параметры, которые нужны чаще других:

- `stream` по умолчанию `true`: ответ приходит потоком частей. Для скриптов и curl ставят `false`.
- `options` - параметры генерации: `temperature`, `top_k`, `top_p`, `seed`, `stop`, `num_predict`, `num_ctx`.
- `keep_alive` задаёт, сколько модель держится в памяти после запроса (`"10m"`, `0` - выгрузить сразу).
- `think: false` выключает рассуждение у моделей с `thinking`. Без него qwen3 тратит токены на размышления даже на однострочный ответ.
- `format` принимает `"json"` или JSON-схему для структурированного ответа.

В ответе есть метрики `total_duration`, `load_duration`, `prompt_eval_count`, `eval_count`, `eval_duration`. Длительности указаны в наносекундах, так что скорость генерации считается как `eval_count / eval_duration * 1e9`.

Для Python и JavaScript есть официальные библиотеки `pip install ollama` и `npm i ollama`:

```python
from ollama import chat

response = chat(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "Name three uses of embeddings."}],
    think=False,
)
print(response.message.content)
```

## OpenAI-совместимый API Ollama

Адрес `http://localhost:11434/v1`. Готовый клиент OpenAI подключается сменой `base_url`, ключ передаётся любой: SDK требует значение, Ollama его не проверяет ([docs.ollama.com/openai](https://docs.ollama.com/openai)).

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1/", api_key="ollama")

resp = client.chat.completions.create(
    model="qwen2.5-coder:7b",
    messages=[{"role": "user", "content": "Write a one-line Python lambda that squares a number."}],
    max_tokens=60,
)
print(resp.choices[0].message.content)
```

Поддерживаются эндпоинты `/v1/chat/completions`, `/v1/completions`, `/v1/models`, `/v1/embeddings`, `/v1/responses` (только без хранения состояния) и аудио-эндпоинты. В chat completions работают streaming, JSON mode, `seed`, картинки в base64, `tools` и `reasoning_effort`. Для qwen3 короткий ответ без рассуждения даёт `"reasoning_effort": "none"`.

Чего в `/v1` нет:

- `tool_choice`, `logit_bias`, `user`, `n`, logprobs;
- картинок по URL (только base64);
- параметра размера контекста. Если нужен другой `num_ctx`, создают модель через Modelfile и обращаются к ней по имени.

Инструменту, который ждёт конкретное имя модели вроде `gpt-3.5-turbo`, отдают копию: `ollama cp qwen3:8b gpt-3.5-turbo`.

Оба API отвечают одинаково быстро: на прогретой qwen2.5-coder:7b `/v1/chat/completions` ответил за 0.23 с против 0.27 с у `/api/generate`. Выбор между ними - вопрос формата. Если код уже написан под OpenAI SDK или инструмент умеет только OpenAI-совместимых провайдеров, берите `/v1`. Если нужны `num_ctx`, `keep_alive` и управление моделями, берите `/api`.

## Контекст и память в Ollama

Размер контекста определяет, сколько токенов модель видит за раз, и сколько памяти уходит на KV-кэш. Значение по умолчанию зависит от видеопамяти ([docs.ollama.com/context-length](https://docs.ollama.com/context-length)):

| VRAM | Контекст по умолчанию |
|---|---|
| меньше 24 GiB | 4k |
| 24-48 GiB | 32k |
| 48 GiB и больше | 256k |

На тестовой машине сервер увидел 28.1 GiB и выставил 32768, что подтверждает строка лога `vram-based default context ... default_num_ctx=32768`. На странице про Modelfile при этом указано значение `num_ctx` по умолчанию 2048. Документация расходится, поэтому реальное значение смотрят в колонке CONTEXT у `ollama ps`.

Для агентов, веб-поиска и инструментов для кода документация рекомендует не меньше 64000 токенов. На машине с 16 ГБ по умолчанию будет 4k, и системный промпт агента туда не поместится: Ollama обрежет вход, а модель потеряет инструкции.

Как поменять контекст:

```bash
# для всего сервера
OLLAMA_CONTEXT_LENGTH=65536 ollama serve

# для одного запроса к /api
curl -s http://localhost:11434/api/generate -d '{"model":"qwen3:8b","prompt":"hi","options":{"num_ctx":32768}}'
```

В приложении Ollama контекст настраивается ползунком в Settings. Третий способ, через Modelfile, разобран в следующем разделе.

У увеличения контекста два ограничения:

1. **Нативное окно модели.** `num_ctx` выше него не работает. У qwen3:8b окно 40960 токенов, и при запросе 65536 любым из трёх способов `ollama ps` показал `CONTEXT 40960`. У gemma4:e4b нативное окно 131072, и на ней 65536 выставились без урезания. Нативное окно показывает `ollama show <модель>`.
2. **Память.** Контекст растёт, растёт и KV-кэш. qwen3:8b при контексте 40960 заняла 11 GB против 9.9 GB при 32768. Если памяти не хватит, часть модели уйдёт на CPU, и в PROCESSOR вместо `100% GPU` появится разделение между CPU и GPU.

Сэкономить память на кэше помогают две переменные из [FAQ](https://docs.ollama.com/faq). `OLLAMA_KV_CACHE_TYPE=q8_0` вдвое уменьшает KV-кэш относительно `f16` с очень небольшой потерей качества, `q4_0` уменьшает вчетверо с небольшой или средней потерей. Квантизованный кэш работает только с Flash Attention: `OLLAMA_FLASH_ATTENTION=1`. Формула Homebrew в подсказке после установки предлагает именно эту пару переменных.

## Modelfile: своя модель в Ollama

Modelfile - текстовый файл, который описывает производную модель: базовые веса, параметры и системный промпт ([docs.ollama.com/modelfile](https://docs.ollama.com/modelfile)). Проверенный пример:

```dockerfile
FROM qwen3:8b
PARAMETER num_ctx 65536
PARAMETER temperature 0.2
SYSTEM You are a concise Python code assistant. Answer with code first.
```

```bash
ollama create fc-qwen3-64k -f Modelfile
ollama show fc-qwen3-64k         # num_ctx 65536, temperature 0.2, System, Capabilities
ollama run fc-qwen3-64k --think=false "Reverse a string in Python."
ollama ps                        # CONTEXT 40960: урезано до нативного окна
```

`ollama show` показывает `num_ctx 65536`, а `ollama ps` после запуска выдаёт 40960. Сработал потолок нативного окна модели.

Инструкции Modelfile:

| Инструкция | Назначение |
|---|---|
| `FROM` | Обязательная: модель из библиотеки, папка safetensors или GGUF-файл |
| `PARAMETER` | Параметры генерации и контекста |
| `SYSTEM` | Системный промпт |
| `TEMPLATE` | Шаблон промпта (синтаксис Go templates) |
| `MESSAGE` | Пример диалога в истории (system, user, assistant) |
| `LICENSE` | Текст лицензии |
| `REQUIRES` | Минимальная версия Ollama для модели |
| `CAPABILITY` | Добавляет возможность GGUF- или MLX-модели |

Частые параметры и значения по умолчанию из документации: `temperature` 0.8, `top_k` 40, `top_p` 0.9, `min_p` 0.0, `repeat_penalty` 1.0, `num_predict` -1 (без ограничения), `seed` 0. `stop` можно задать несколько раз. Посмотреть Modelfile любой модели, включая шаблон из библиотеки, можно через `ollama show --modelfile qwen3:8b`.

Кроме контекста для OpenAI API, Modelfile нужен для системного промпта под задачу (код-ревьюер, классификатор тикетов) и фиксированной температуры. Ещё один сценарий - упаковать собственный GGUF под понятным именем.

## Настройки сервера Ollama и безопасность

Сервер настраивается переменными окружения:

| Переменная | По умолчанию | Что меняет |
|---|---|---|
| `OLLAMA_HOST` | `127.0.0.1:11434` | Адрес и порт сервера |
| `OLLAMA_MODELS` | `~/.ollama/models` (macOS) | Папка с моделями |
| `OLLAMA_KEEP_ALIVE` | 5 минут | Сколько модель держится в памяти после запроса |
| `OLLAMA_CONTEXT_LENGTH` | по VRAM | Контекст по умолчанию |
| `OLLAMA_NUM_PARALLEL` | 1 | Параллельные запросы на модель |
| `OLLAMA_MAX_LOADED_MODELS` | 3 × число GPU (3 на CPU) | Сколько моделей одновременно в памяти |
| `OLLAMA_MAX_QUEUE` | 512 | Очередь запросов, сверх неё сервер отвечает 503 |
| `OLLAMA_ORIGINS` | 127.0.0.1, 0.0.0.0 | Разрешённые CORS-источники |

Параллельные запросы стоят памяти: по документации она растёт пропорционально `OLLAMA_NUM_PARALLEL × OLLAMA_CONTEXT_LENGTH`.

Где задавать переменные, зависит от способа установки. В приложении на macOS это `launchctl setenv` и перезапуск приложения, на Linux - `systemctl edit ollama` и строки `Environment=` в секции `[Service]`, на Windows - переменные окружения пользователя и перезапуск Ollama. Если сервер запущен вручную через `ollama serve`, переменные задают в том же терминале.

По умолчанию Ollama слушает только localhost. `OLLAMA_HOST=0.0.0.0:11434` открывает её для локальной сети, но локальный API работает без ключа. Любой, кто достучится до порта, сможет запускать модели, скачивать новые и удалять существующие. Наружу Ollama открывают только через reverse proxy с аутентификацией, VPN или SSH-туннель (`ssh -L 11434:localhost:11434 host`).

Облачные функции (облачные модели и веб-поиск) выключаются переменной `OLLAMA_NO_CLOUD=1` или настройкой `"disable_ollama_cloud": true` в `~/.ollama/server.json`.

## Интеграции: Ollama для агентов и IDE

Команда `ollama launch` настраивает внешний инструмент на работу с локальной моделью и запускает его. В версии 0.40.14 `ollama launch --help` перечисляет 18 интеграций, среди них claude, codex, opencode, copilot, droid, cline, vscode, openclaw, hermes и qwen. В разделе Integrations [документации](https://docs.ollama.com/integrations) есть ещё страницы про JetBrains, Zed, Xcode, Goose, n8n и другие инструменты. Флаг `--model` выбирает модель, `--config` настраивает интеграцию без запуска, `--restore` возвращает инструменту исходный профиль. Сам `launch` в рамках подготовки статьи не запускался, потому что он меняет конфиги установленных инструментов.

**Claude Code.** Ollama [с версии 0.14.0](https://github.com/ollama/ollama/releases/tag/v0.14.0) поддерживает Anthropic Messages API (`/v1/messages`), поэтому Claude Code можно направить на локальную модель:

```bash
ollama launch claude --model qwen3.5
# или вручную
export ANTHROPIC_AUTH_TOKEN=ollama      # обязательна, но не проверяется
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3.5
```

[Документация интеграции](https://docs.ollama.com/integrations/claude-code) требует для локальных моделей контекст от 64k. Anthropic [не поддерживает](https://code.claude.com/docs/en/llm-gateway) работу Claude Code с моделями, отличными от Claude, так что такая связка на ваш риск. Подробности и ограничения разобраны в разделе про альтернативных провайдеров статьи [Claude Code в России](https://futurecraft.pro/ru/blog/claude-code-russia/).

**OpenCode.** Open-source агент для терминала подключается командой `ollama launch opencode` или вручную через провайдер `@ai-sdk/openai-compatible` с адресом `http://localhost:11434/v1`. Конфиг и результаты теста локальных моделей разобраны в [гайде по OpenCode](https://futurecraft.pro/ru/blog/opencode-guide/).

**Расширения IDE.** Для Cline, Roo Code, VS Code, JetBrains и Zed в документации Ollama есть отдельные страницы интеграций. Для бесплатного стека это частый вариант, его место среди платных инструментов показано в обзоре [нейросетей для кода](https://futurecraft.pro/ru/blog/best-ai-coding-tools/).

**Свой код и RAG.** Для эмбеддингов есть модели nomic-embed-text, bge-m3, qwen3-embedding и эндпоинты `/api/embed` и `/v1/embeddings`. Эмбеддинги при подготовке статьи не проверялись. Как устроен retrieval поверх них, разобрано в [гайде по RAG](https://futurecraft.pro/ru/blog/rag-system-guide/).

## Ограничения и подводные камни Ollama

### Хорошая модель для кода ≠ хороший агент

Агенту нужна модель, которая стабильно вызывает инструменты в правильном формате и держит длинный системный промпт. Код в чате - другая задача. В тесте с OpenCode на задаче «добавить функцию и тест к ней» результаты локальных моделей вышли такими:

| Модель | Контекст | Результат |
|---|---|---|
| qwen2.5-coder:7b | 32768 | Печатала вызовы инструментов текстом JSON, файлы не менялись. Повторилось на двух версиях Ollama |
| qwen3:8b | 32768 и 40960 | Нативные tool calls, но результат нестабилен: один чистый прогон на старой версии Ollama, на новой из четырёх запусков ни одного чистого (удалённая соседняя функция, дубли `return`, таймауты) |
| gemma4:e4b | 65536 | Задача за 79 с, но агент удалил существующую функцию и её тест |

Метка `tools` в библиотеке не гарантирует рабочих tool calls в конкретном агенте. Локальные 8B-модели в агентном режиме могут сработать, но их правки нужно проверять, а проект держать под git. Полная методика и логи теста - в [гайде по OpenCode](https://futurecraft.pro/ru/blog/opencode-guide/).

### Контекст по умолчанию мал для агентов

На машинах с видеопамятью меньше 24 GiB по умолчанию стоит 4k, на 24-48 GiB - 32k. Системный промпт агента вместе с описаниями инструментов легко превышает и то и другое: в тесте OpenCode, который подхватил навыки других агентов из домашней папки, промпт вырос примерно до 53 тысяч токенов, и Ollama обрезала его до 32768 (`truncating input prompt` в логе сервера). Перед подключением агента проверьте CONTEXT в `ollama ps` и нативное окно модели.

### `num_ctx` упирается в нативное окно

Modelfile, переменная окружения и `options.num_ctx` не поднимают контекст выше того, на что обучена модель. Ошибки нет: `ollama show` показывает заданное значение, а реальное видно только в `ollama ps`.

### Версии меняются быстро

Между 0.24.0 и 0.40.14 расход памяти у одной и той же модели снизился на 1.6 GB. В библиотеке за неделю до проверки обновились qwen3.6 и qwen3.8. Цифры из любого гайда, включая этот, привязаны к версии Ollama и дате.

### Качество и скорость не облачные

В проверках для этой статьи 7-8B модели правильно отвечали на короткие задачи вроде однострочной lambda, а многошаговую задачу агента с правкой двух файлов стабильно не решила ни одна. 60-70 токенов в секунду на M4 Max - скорость для одного пользователя. Для нескольких параллельных клиентов понадобятся `OLLAMA_NUM_PARALLEL` и память под каждый поток.

### Docker на Mac и холодный старт

В Docker Desktop на macOS GPU-ускорения нет, модели там работают на CPU. Первый запрос после простоя ждёт загрузки модели (по умолчанию её выгружают через 5 минут без запросов). Если важна задержка, увеличьте `OLLAMA_KEEP_ALIVE` или передавайте `keep_alive` в запросе.

## С чего начать

1. Установите Ollama для своей ОС и проверьте `curl http://localhost:11434/api/version`.
2. Выберите модель по таблице памяти: для 16 ГБ - qwen3:8b или qwen3.5:9b, для 8 ГБ - модели на 4B.
3. Запустите `ollama run <модель> --verbose` и посмотрите `eval rate`, затем `ollama ps`: модель должна быть на `100% GPU`.
4. Подключите код через `/v1` с OpenAI SDK или через библиотеку `ollama`.
5. Для агента поднимите контекст до 64k, если модель это позволяет (`ollama show`), и проверьте результат в `ollama ps`.
6. Перед `OLLAMA_HOST=0.0.0.0` поставьте перед сервером прокси с аутентификацией.