Программный доступ к Ollama REST API

После установки Ollama предоставляет полный REST API на локальном порту 11434, охватывающий генерацию текста, чат, векторные эмбеддинги и управление моделями, а также два совместимых протокола: OpenAI и Anthropic.

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

---

Два базовых URL и методы аутентификации

API Ollama имеет две конечные точки: локальную и облачную, с разными правилами аутентификации.

Конечная точка	Базовый URL	Аутентификация
Локальный сервис	http://localhost:11434/api	Аутентификация не требуется
Локальный сервис (совместимый протокол)	http://localhost:11434/v1	Аутентификация не требуется, api_key можно заполнить произвольно
Ollama Cloud	https://ollama.com/api	Authorization: Bearer + API Key

Локальные сервисы по умолчанию не требуют аутентификации и работают сразу из коробки; при прямом подключении к облачному API Ollama по адресу ollama.com сначала создайте API-ключ на странице настроек официального сайта и укажите его в заголовке запроса.

---

Генерация текста: /api/generate

generate — самый базовый API генерации с одним ходом; достаточно передать имя модели и prompt:

Когда stream имеет значение false, возвращается один JSON-объект:

{
  "model": "qwen3.5",
  "created_at": "2026-08-29T03:20:00.499127Z",
  "response": "Example是一个面向编程初学者的免费中文教程网站。",
  "done": true,
  "total_duration": 10706818083,
  "load_duration": 6338219291,
  "prompt_eval_count": 26,
  "prompt_eval_duration": 130079000,
  "eval_count": 42,
  "eval_duration": 4232710000
}

Общие параметры следующие:

Параметр	Описание
model	Обязательный, имя модели
prompt	Prompt; можно оставить пустым, чтобы предзагрузить модель
stream	По умолчанию true возвращает потоковую передачу; при false возвращает полный результат сразу
system	Временно указать системный промпт, переопределив настройку в Modelfile
options	Объект параметров генерации, например, temperature, num_ctx (как в параметрах Modelfile)
format	"json" или полная JSON Schema, принудительно задаёт структурированный вывод
keep_alive	Продолжительность, в течение которой модель остаётся в памяти после запроса, например, "10m", -1 для постоянного нахождения в памяти, 0 для немедленной выгрузки
raw	Когда true, пропускает сборку шаблона и напрямую использует полный промпт, который вы предоставляете
suffix	Текст, добавляемый после вывода модели, для сценариев дополнения текста
images	Массив изображений в Base64, используется с мультимодальными моделями

Два практических совета: отправка пустого промпта может предварительно загрузить модель в память, устраняя ожидание загрузки при первом запросе; установка keep_alive в 0 вместе с пустым промптом может немедленно выгрузить модель и освободить VRAM.

---

Генерация чата: /api/chat

chat — это API многоходового диалога; история сообщений поддерживается вызывающей стороной, что является ключевым отличием от generate.

Поля, поддерживаемые объектом message:

Поле	Описание
role	Четыре роли: system / user / assistant / tool
content	Содержимое сообщения
images	Необязательно, список изображений в base64 (мультимодальные модели)
thinking	Необязательно, процесс рассуждения thinking-моделей (используется с параметром think)
tool_calls	Необязательно: список инструментов, которые модель запрашивает вызвать (см. раздел о вызове инструментов для практики)

Правильный способ многоходового диалога: добавляйте сообщение ассистента, возвращённое моделью на каждом раунде, обратно в массив messages, затем отправляйте его с новым вопросом; тогда модель сможет "запомнить" весь контекст.

Поскольку сообщения полностью управляются вами, историю можно сохранять в базе данных, сжимать с помощью суммаризации или восстанавливать между сессиями — проблема, упомянутая в части 5 "выход из командной строки теряет память", теперь имеет инженерное решение здесь.

---

Векторные эмбеддинги: /api/embed

API embed преобразует текст в векторы, служа мастерской сырья для RAG и семантического поиска.

Эмбеддинги в ответе — это двумерный массив, каждый вектор в котором уже L2-нормализован (единичной длины), поэтому для сравнения можно напрямую использовать косинусное сходство.

Два параметра, заслуживающих внимания: dimensions может задавать размерность выходного вектора (когда это поддерживается моделью, уменьшение размерности экономит место при хранении); truncate по умолчанию имеет значение true и автоматически обрезает слишком длинный текст, а установка false вызовет ошибку, если текст слишком длинный.

---

Потоковая передача или без неё: как обрабатывать ответы

API генерации по умолчанию возвращают потоковый ответ в формате NDJSON: каждая строка — независимый объект JSON.

{"model":"qwen3.5","created_at":"...","response":"EXAMPLE","done":false}
{"model":"qwen3.5","created_at":"...","response":"（Example）","done":false}
{"model":"qwen3.5","created_at":"...","response":"是编程初学者的入门网站。","done":false}
{"model":"qwen3.5","created_at":"...","response":"","done":true,"done_reason":"stop"}

Клиент читает построчно и объединяет поля ответа, чтобы сформировать полный ответ; процесс объединения можно отображать в интерфейсе в реальном времени.

Плюсы и минусы двух режимов:

Mode	Преимущество	Сценарий использования
Потоковая передача (по умолчанию)	Низкое время до первого токена, можно отображать в реальном времени	Интерфейсы чатов, генерация длинных текстов
Непотоковый режим stream:false	Получить полный результат сразу, просто обрабатывать	Пакетная обработка, структурированный вывод, вызовы из скриптов

В потоковом режиме ошибки могут возникнуть в середине вывода; в этот момент код состояния HTTP уже нельзя изменить. Ошибка появится в виде строки {"error": "..."} в конце потока данных, и клиент должен проверять эту строку при разборе.

---

Статистика использования и обработка ошибок

Каждый ответ генерации заканчивается полями статистики производительности, предоставляя первичные данные для оценки накладных расходов на инференс.

Поле	Значение
total_duration	Общее время запроса (наносекунды)
load_duration	Время загрузки модели (заметно при первом запросе)
prompt_eval_count	Количество токенов, потреблённых входом
prompt_eval_duration	Время обработки входных данных
eval_count	Количество токенов, сгенерированных в выводе
eval_duration	Время генерации вывода

Формула скорости генерации (токенов/с): eval_count / eval_duration * 10^9; все единицы времени — наносекунды.

С точки зрения обработки ошибок API использует стандартные HTTP-коды состояния для представления результатов:

Код состояния	Значение
200	Успех
400	Ошибка запроса (отсутствующие параметры, неверный JSON и т. д.)
404	Модель не существует (сначала выполните ollama pull или проверьте имя)
429	Ограничение скорости из-за слишком частых запросов
500	Внутренняя ошибка сервера
502	Ошибка шлюза (например, облачная модель недоступна)

Тело ответа с ошибкой имеет фиксированную структуру {"error": "error description"}; клиенты могут просто единообразно извлекать поле error.

---

Обзор API управления моделями

API предоставляет аналог для каждой операции управления моделями, доступной в командной строке, что подходит для создания административных панелей или сценариев автоматизации.

Конечная точка	Метод	Назначение
/api/tags	GET	Список локальных моделей (включая количество параметров, уровень квантования)
/api/show	POST	Просмотр сведений о модели, возможностей, шаблона
/api/pull	POST	Загрузка модели, возвращает потоковый прогресс загрузки
/api/push	POST	Отправить модель в библиотеку моделей
/api/copy	POST	Копировать модель (источник / назначение)
/api/delete	DELETE	Удалить модель
/api/create	POST	Создать модель (включая квантование, соответствующее возможностям Modelfile)
/api/ps	GET	Просмотр текущих загруженных моделей и использования VRAM
/api/version	GET	Запрос версии Ollama

На примере /api/tags ответ содержит сведения о спецификации для каждой модели:

{
  "models": [
    {
      "name": "qwen3.5:latest",
      "size": 6600000000,
      "details": {
        "family": "qwen3.5",
        "parameter_size": "9B",
        "quantization_level": "Q4_K_M"
      }
    }
  ]
}

Такие поля, как quantization_level и parameter_size, можно напрямую использовать для создания интерфейса выбора модели.

---

Интерфейс, совместимый с OpenAI

Чтобы существующие приложения OpenAI переключились на локальные модели, обычно достаточно изменить только base_url.

Clúdaíonn an chomhoiriúnacht cúig chríochphointe:

Конечная точка	Описание
/v1/chat/completions	Comhlántaí comhrá, ag tacú le sruthú, fís, uirlisí, agus mód JSON
/v1/completions	Comhlántaí téacs
/v1/responses	API Freagraí (mód neamhstáit)
/v1/embeddings	Leabuithe veicteora
/v1/models	Список моделей

Обратите внимание на два распространённых различия:

Во-первых, в протоколе OpenAI нет понятия num_ctx. Когда нужно изменить контекст, сначала создайте модель с PARAMETER num_ctx, а затем вызывайте её под новым именем (можно использовать Modelfile из части 7 или позаимствовать имя с помощью cp).

Во-вторых, некоторые поля пока не поддерживаются: tool_choice, logit_bias, n, logprobs и т. д. Перед миграцией рекомендуется проверить список поддержки в руководстве.

---

Интерфейс, совместимый с Anthropic

Ollama также предоставляет слой совместимости с Anthropic Messages API, позволяющий таким инструментам, как Claude Code, напрямую использовать локальные модели.

При интеграции таких инструментов, как Claude Code, достаточно задать две переменные окружения:

Обратите внимание на границы возможностей: такие функции Anthropic, как принудительный tool_choice, кэширование промптов, пакетный интерфейс и ввод PDF, пока не поддерживаются; количество токенов приблизительно.

Другие расширения