Ollama API: как подключить к своим программам

Ollama API – это HTTP-интерфейс, который запускается вместе с Ollama на вашем компьютере. Адрес по умолчанию – http://localhost:11434/api, ключ для локальных запросов не нужен. Чтобы подключить Ollama к своей программе, достаточно отправить POST-запрос с JSON на /api/chat (диалог), /api/generate (одиночный запрос) или /api/embed (векторы для поиска). Если у вас уже написан код под OpenAI, менять почти ничего не нужно: Ollama поддерживает часть OpenAI API по адресу http://localhost:11434/v1. Ниже – рабочие примеры, параметры и ограничения. Данные взяты из официальной документации docs.ollama.com/api и страницы FAQ по состоянию на октябрь 2026.

Адреса и что нужно для запуска

Перед запросом должна быть установлена Ollama и скачана модель. Установка описана в статьях «Ollama: установка и первые шаги» и «Ollama на Windows», выбор модели – в «Лучшие модели для Ollama». По документации, базовые адреса такие:

API	Облако напрямую	Локальный сервер
Ollama	https://ollama.com/api	http://localhost:11434/api
Совместимость с OpenAI	https://ollama.com/v1	http://localhost:11434/v1
Клиент Anthropic (базовый URL)	https://ollama.com	http://localhost:11434

Облачные запросы требуют API-ключа, локальные – нет. Чтобы использовать облачные модели через локальный сервер, выполните в терминале ollama signin. Создавать и удалять модели через API можно только на локальном сервере.

Условия работы облака Ollama из России и оплату мы не проверяли: ниже разбираем в основном локальный вариант, который не зависит от внешних сервисов.

Первый запрос: /api/chat

Проверьте, что сервер отвечает, и отправьте вопрос. Название модели подставьте ту, что вы скачали (посмотреть список можно командой ollama list или запросом GET /api/tags):

curl http://localhost:11434/api/chat -d '{
  "model": "gpt-oss:20b",
  "messages": [{"role": "user", "content": "Why is the sky blue?"}],
  "stream": false
}'

Название модели в примере взято из документации Ollama, это только пример. Текст ответа лежит в поле message.content. Для диалога передавайте в messages всю историю: сервер сам её не хранит, поэтому добавляйте в массив и реплики пользователя, и ответы модели.

Основные поля запроса /api/chat по спецификации:

Поле	Назначение
model	Имя модели (обязательно)
messages	История чата: объекты с role и content; можно прикладывать изображения в base64 для мультимодальных моделей
tools	Список функций, которые модель может вызвать
format	json или JSON-схема – чтобы получить структурированный ответ
options	Параметры генерации: temperature, top_p, top_k, seed, stop, num_ctx, num_predict и другие
stream	По умолчанию true
think	Включает вывод «рассуждений» модели в отдельное поле, если модель это поддерживает
keep_alive	Сколько держать модель в памяти, например 5m, или 0, чтобы выгрузить сразу

Если вам нужен одиночный запрос без истории, есть POST /api/generate: в нём вместо messages поле prompt, а текст ответа лежит в поле response.

Потоковый ответ

Некоторые эндпоинты, например /api/generate, по умолчанию отдают ответ потоком в формате NDJSON (application/x-ndjson): каждая строка – JSON с очередным кусочком текста, последняя содержит "done": true. Это удобно, когда нужно показывать ответ пользователю по мере генерации. Чтобы получить один JSON целиком, укажите "stream": false.

• Стриминг: ниже задержка до первого слова, лучше для длинных ответов, но код сложнее.
• Без стриминга: проще обрабатывать, подходит для коротких ответов и структурированных данных.

Последний фрагмент потока содержит метрики: total_duration, load_duration, prompt_eval_count, eval_count и другие. Время измеряется в наносекундах. По ним удобно считать скорость генерации и нагрузку.

Векторы для поиска: /api/embed

Эндпоинт создаёт векторные представления текста – основу поиска по смыслу и RAG. В запросе нужны model и input (строка или массив строк):

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": ["Why is the sky blue?", "Why is the grass green?"]
}'

Дополнительно доступны truncate (по умолчанию true: слишком длинный текст обрезается; при false вернётся ошибка) и dimensions – число измерений вектора. В ответе массив embeddings. Как использовать векторы в работе агента, объясняет статья «RAG для AI-агента».

Подключение через клиент OpenAI

Если ваша программа уже использует библиотеку OpenAI, укажите другой базовый адрес. Пример из документации для локального сервера:

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # требуется клиентом, но Ollama его игнорирует
)

response = client.chat.completions.create(
    model='gpt-oss:20b',
    messages=[{'role': 'user', 'content': 'Say this is a test'}],
)
print(response.choices[0].message.content)

Ollama поддерживает подмножество OpenAI API. По документации, для /v1/chat/completions отмечены поддержка потоковых ответов и инструментов (tools), параметр tool_choice не поддерживается. Есть и /v1/responses. Для облака в документации отдельно указано: не поддерживаются stateful Responses, встроенный веб-поиск через /v1/responses и повтор пользовательских tool-call. Полный список параметров смотрите на странице «OpenAI compatibility».

Полезная деталь: если инструмент требует названия моделей OpenAI вроде gpt-3.5-turbo, документация советует скопировать модель под этим именем командой ollama cp.

Для Python и JavaScript есть официальные библиотеки Ollama (репозитории ollama/ollama-python и ollama/ollama-js на GitHub); они работают и с локальным сервером, и с облаком. Для прямого доступа к облаку укажите хост https://ollama.com и ключ в заголовке Authorization: Bearer.

Настройки, которые влияют на ответы

• Размер контекста. Размер окна по умолчанию, по документации Ollama, зависит от видеопамяти: меньше 24 ГиБ – 4 тыс. токенов, от 24 до 48 ГиБ – 32 тыс., от 48 ГиБ – 256 тыс. Изменить глобально можно переменной OLLAMA_CONTEXT_LENGTH при запуске сервера, в запросе – через options.num_ctx. Для длинных документов и памяти агента 4 тыс. может быть мало, но большее окно увеличивает расход памяти.
• Время жизни модели в памяти. Параметр keep_alive в запросе (строка длительности, число секунд, отрицательное число – держать всегда, 0 – выгрузить сразу). Глобально – переменная OLLAMA_KEEP_ALIVE; параметр запроса её перекрывает.
• Параллельные запросы. Переменная OLLAMA_NUM_PARALLEL задаёт, сколько запросов модель обрабатывает одновременно; по умолчанию 1. Нужная память растёт пропорционально этому числу и длине контекста.

Если модель слишком тяжела для вашего компьютера, подумайте об аренде сервера: см. «Аренда сервера с GPU».

Доступ по сети и безопасность

По умолчанию Ollama слушает только 127.0.0.1:11434, то есть доступна только вашему компьютеру. Чтобы открыть её в сети, измените адрес привязки переменной OLLAMA_HOST (например, 0.0.0.0:11434); способ установки переменных зависит от системы: на Linux это правка службы systemd, на macOS – launchctl setenv, на Windows – переменные среды учётной записи.

Важное предупреждение. В документации для локального API сказано, что он не требует авторизации. Значит, любой, кто достучится до открытого порта, сможет пользоваться вашей моделью и нагружать компьютер. Поэтому:

• не выставляйте порт 11434 в интернет напрямую;
• ограничьте доступ файрволом или VPN до нужных адресов;
• если нужен доступ извне, поставьте перед Ollama обратный прокси с авторизацией; в FAQ показан пример конфигурации Nginx (proxy_pass http://localhost:11434);
• для запросов из браузера добавьте нужные источники через OLLAMA_ORIGINS: по умолчанию разрешены запросы только с 127.0.0.1 и 0.0.0.0;
• не храните API-ключ облака в браузерном коде и репозитории (на этом настаивает документация).

Если вы запускаете сервер на VPS и хотите закрыть его от посторонних, пригодится статья «Как защитить AI-агента на VPS».

Про приватность: по FAQ Ollama, при локальном запуске разработчики ваши запросы и данные не видят; при использовании облачных моделей запросы обрабатываются для оказания услуги. Облачные функции можно отключить: параметр disable_ollama_cloud в ~/.ollama/server.json или переменная OLLAMA_NO_CLOUD=1.

Ошибки

Код	Что означает по документации
200	Успех
400	Неверный запрос: нет параметров, неправильный JSON
404	Не найдено, например модели не существует
429	Слишком много запросов, например превышен лимит
500	Внутренняя ошибка сервера
502	Плохой шлюз, например облачная модель недоступна

Сообщение об ошибке приходит в JSON в поле error. Если ошибка случилась уже во время потока, статус ответа изменить нельзя, и в потоке появится объект с полем error: проверяйте это поле в каждой строке.

Частые причины проблем: сервер не запущен (запрос на localhost:11434 не отвечает), модель не скачана (ответ 404), не хватает памяти для выбранной модели. Если модель нужно выгружать, используйте keep_alive: 0.

Как это использовать в агенте

Локальная модель через API – это «мозг» агента: ваша программа отправляет запрос, получает ответ или вызов функции и выполняет его. Ключевые возможности для этого есть в API: tools в /api/chat для вызова функций, format для структурированных ответов и /api/embed для поиска по документам. Для простых задач обычно хватает одной модели и скрипта; для сложных агентов понадобится фреймворк.

Не рассчитывайте, что малая локальная модель сравнится с облачными флагманами: качество ответов и надёжность вызова функций зависят от модели. Проверяйте на своих задачах, а не по рекламе.

Частые вопросы

Какой адрес у Ollama API?

Локально – http://localhost:11434/api (OpenAI-совместимый – http://localhost:11434/v1). Облако напрямую – https://ollama.com/api.

Нужен ли API-ключ?

Для локального сервера – нет. Для прямых запросов к облаку на ollama.com – да, его создают в настройках аккаунта Ollama и передают в заголовке Authorization: Bearer. Ключи не истекают, но их можно отозвать.

Чем /api/chat отличается от /api/generate?

/api/chat принимает историю сообщений с ролями и подходит для диалога и вызова функций. /api/generate – один запрос с полем prompt, ответ в поле response.

Можно ли использовать код, написанный под OpenAI?

Часто да: замените базовый адрес на http://localhost:11434/v1 и укажите имя вашей модели. Но поддерживается только часть OpenAI API, поэтому сверьтесь со страницей совместимости.

Как отключить потоковый ответ?

Добавьте в тело запроса "stream": false, и сервер вернёт один JSON.

Как изменить размер контекста?

В запросе – "options": {"num_ctx": 8192}, для всего сервера – переменная OLLAMA_CONTEXT_LENGTH. По умолчанию размер зависит от видеопамяти: 4 тыс. токенов на картах меньше 24 ГиБ.

Как открыть Ollama для других компьютеров в сети?

Задайте OLLAMA_HOST, например 0.0.0.0:11434, но обязательно ограничьте доступ файрволом или прокси с авторизацией: у локального API собственной авторизации нет.

Хранит ли Ollama мои запросы?

По FAQ Ollama, при локальном запуске разработчики ваши запросы не видят. Для облачных моделей запросы обрабатываются сервисом; детали и политику смотрите на официальном сайте.