Ollama OpenAI Compatible API: доступ, цены, интеграция и руководство для продакшена

Ollama OpenAI Compatible API: доступ, цены, интеграция и руководство для продакшена

Ollama OpenAI compatible API позволяет приложению сохранять привычную структуру OpenAI SDK, отправляя запросы либо на локальный сервер Ollama, либо напрямую в Ollama Cloud. Это полезно, но не означает полного паритета функций: Ollama документирует поддержку подмножества OpenAI API, а некоторые возможности зависят от выбранных конечной точки и модели.

В этом руководстве показано, как получить доступ к этому интерфейсу, настроить его в существующем приложении на Python или JavaScript, разобраться в стоимости облачного и локального использования и установить реальные границы для продакшена.

Краткий ответ: для локального сервера Ollama используйте http://localhost:11434/v1/ и ключ-заглушку, который требуется SDK, но игнорируется Ollama. Для прямого доступа к облаку используйте https://ollama.com/v1 вместе с OLLAMA_API_KEY. Прежде чем полагаться на потоковую передачу, vision, инструменты, структурированный вывод или поведение Responses API, проверьте точные конечную точку и модель.

Что означает «совместимость с OpenAI» для Ollama?

Это интерфейс интеграции с клиентами OpenAI, а не API, размещённый OpenAI. Он позволяет направлять совместимые клиенты на базовые URL Ollama и использовать поддерживаемые маршруты, такие как chat completions, embeddings, обнаружение моделей и запросы Responses без сохранения состояния.

Справочник совместимости Ollama является источником истины для поддерживаемого подмножества. В частности:

• /v1/chat/completions поддерживает такие возможности, как потоковая передача, режим JSON, vision, инструменты, воспроизводимые результаты, logprobs и элементы управления, применимые только к совместимым моделям.
• /v1/embeddings поддерживает строковые входные данные и массивы.
• /v1/models и /v1/models/{model} поддерживают обнаружение моделей, однако некоторые возвращаемые поля имеют специфичные для Ollama значения.
• POST /v1/responses доступен, но работает без сохранения состояния: не полагайтесь на previous_response_id или conversation.

Перед включением возможности в продакшене ознакомьтесь с актуальным справочником совместимости Ollama с OpenAI. «Совместимость» следует воспринимать как повод повторно использовать ваш клиент и формат запросов, а не как причину пропустить тестирование функций.

Доступ к Ollama OpenAI compatible API: локально или в облаке

Самый простой выбор при реализации — выполнять ли инференс на собственной машине или обращаться к облачной конечной точке Ollama.

Это разделение описано во введении в API Ollama и руководстве по аутентификации. Для прямых облачных вызовов требуется API-ключ. Для локальных — нет.

Локальная настройка

Установите Ollama, затем загрузите модель, которую планируете использовать. В документации Ollama показан общий шаблон:

ollama pull gpt-oss:20b
ollama serve

Теперь проверьте, что локальная конечная точка может перечислить модели:

curl http://localhost:11434/v1/models

Если подключение не удаётся, устраните проблему с локальным сервером, прежде чем изменять код приложения. Миграцию клиента гораздо проще отлаживать, когда базовый URL API и список моделей уже независимо работают.

Настройка прямого доступа к облаку

Для прямого использования облака создайте API-ключ в аккаунте Ollama и поместите его в переменную окружения:

export OLLAMA_API_KEY="replace-with-your-key"

Базовый URL облака — https://ollama.com/v1. Ollama документирует, что её хостинг API использует Authorization: Bearer; не помещайте долгоживущий ключ в браузерный код, репозиторий или файл клиентской конфигурации.

Интеграция Ollama OpenAI compatible API с OpenAI SDK

Точка миграции — конфигурация клиента. Оставьте сообщения приложения и обработку ошибок за собственным интерфейсом, а затем замените только базовый URL, ключ и конфигурацию модели.

Python: локальный сервер

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # required by the SDK; ignored by the local server
)

response = client.chat.completions.create(
    model="gpt-oss:20b",
    messages=[
        {"role": "user", "content": "Summarize the production risks of exposing a local API."}
    ],
)

print(response.choices[0].message.content)

Локальная конечная точка не аутентифицирует запросы. Ключ-заглушка существует только потому, что клиент OpenAI ожидает значение; он не защищает локальный сервер.

Python: прямое обращение к облаку

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ollama.com/v1",
    api_key=os.environ["OLLAMA_API_KEY"],
)

response = client.chat.completions.create(
    model="gemma4:31b",
    messages=[
        {"role": "user", "content": "Give one sentence on safe API key storage."}
    ],
)

print(response.choices[0].message.content)

Структура кода намеренно похожа. Операционное различие — нет: прямые обращения к облаку зависят от API-ключа и выбранной облачной модели; локальные обращения зависят от загруженной модели и ресурсов, доступных на хосте.

JavaScript: сохраняйте возможность настройки конечной точки

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1/",
  apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
});

const completion = await client.chat.completions.create({
  model: process.env.OLLAMA_MODEL ?? "gpt-oss:20b",
  messages: [{ role: "user", content: "Return a concise health-check message." }],
});

console.log(completion.choices[0].message.content);

Задавайте переменные окружения для каждого развёртывания:

# Local
OLLAMA_BASE_URL=http://localhost:11434/v1/
OLLAMA_API_KEY=ollama
OLLAMA_MODEL=gpt-oss:20b

# Direct cloud
OLLAMA_BASE_URL=https://ollama.com/v1
OLLAMA_API_KEY=replace-with-your-key
OLLAMA_MODEL=gemma4:31b

Такая конфигурация делает последующее изменение маршрута или модели явным и доступным для проверки. Она также предотвращает превращение URL-адреса базовой среды в скрытое поведение приложения.

Матрица совместимости: что проверить перед выпуском

Совместимый с OpenAI API Ollama наиболее полезен, когда совместимость становится планом тестирования, а не предположением.

Команды часто удивляют две детали:

1. Состояние принадлежит вашему приложению. Приложение должно хранить необходимые ему сообщения или состояние диалога, а не ожидать от Ollama поведения Responses с сохранением состояния.
2. Имя модели не гарантирует возможности. Запрос может использовать совместимую конечную точку, но при этом не обеспечивать качество или поведение инструментов, необходимые рабочему процессу. Тестируйте вместе модель, размер промпта, ограничения вывода и инструменты.

Если существующая интеграция жёстко задаёт имя модели OpenAI по умолчанию, Ollama документирует ollama cp как способ создать временный локальный псевдоним модели. Используйте это только как преднамеренный слой совместимости, документируйте псевдоним и удалите его, когда конфигурация станет явной.

Цены Ollama: совокупная стоимость владения локальным решением и облачные тарифы за токены

Стоимость совместимого с OpenAI API Ollama зависит от маршрута.

Локальный инференс — это не счёт за токены, но он не бесплатен

Запуск локальной модели не создаёт облачный счёт Ollama за каждый токен. Однако он формирует профиль операционных затрат:

• Мощности GPU или CPU, RAM/VRAM, хранилище и амортизация оборудования
• Электроэнергия и охлаждение
• Время загрузки модели и хранение образов
• Планирование мощностей, мониторинг, установка патчей и реагирование на инциденты
• Альтернативная стоимость поддержания модели в готовности для запросов с низкой задержкой

Для одного разработчика это может быть отличным компромиссом. Для продукта с неравномерным трафиком или несколькими моделями рассчитывайте загрузку оборудования и затраты на обеспечение надежности наряду с прямой стоимостью инференса.

Прямые облачные цены публикуются за миллион токенов

На странице актуальных цен Ollama указаны облачные тарифы за один миллион токенов, включая отдельные цены на входные, кэшированные входные и выходные токены. Приведенные ниже примеры были проверены 22 октября 2026 года; для решений о закупках и развертывании используйте актуальный прайс-лист.

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

Практическая ежемесячная оценка:

monthly_cloud_cost =
  (input_tokens / 1,000,000 × input_rate)
+ (cached_input_tokens / 1,000,000 × cached_input_rate)
+ (output_tokens / 1,000,000 × output_rate)

Например, по опубликованным выше тарифам gpt-oss:20b, 1 миллион некэшированных входных токенов плюс 250 000 выходных токенов дают расчетную стоимость $0.145 до любых изменений цен или кредитов, привязанных к конкретному аккаунту. Для прогноза в продакшене используйте наблюдаемые данные телеметрии токенов, а не предполагаемую длину чата.

Руководство для продакшена: защитите локальный сервер перед его публикацией

Самое важное правило для продакшена при использовании Ollama OpenAI compatible API простое: локальный сервер Ollama по умолчанию не требует аутентификации.

По умолчанию Ollama привязывается к 127.0.0.1:11434. В документации указано, что OLLAMA_HOST может изменить адрес привязки, а прокси, например Nginx, может перенаправлять трафик на сервер. Это варианты реализации, а не аутентификация. Если вы выводите сервис за пределы localhost, настройте для него продуманные меры контроля.

Чек-лист для продакшена

1. Сохраняйте привязку к loopback по умолчанию, если у вас нет определенного пути доступа. Не открывайте порт 11434 напрямую в интернет.
2. Настройте TLS и аутентификацию на периметре. Используйте обратный прокси, частную сеть, идентификацию сервиса и авторизацию для каждого клиента в соответствии с вашей средой. Фиктивный ключ OpenAI SDK не является средством контроля доступа.
3. Строго ограничивайте разрешенные browser origins. Ollama документирует OLLAMA_ORIGINS для дополнительных разрешенных источников. Добавляйте только точные origins веб-приложений или расширений, которым необходим доступ; не превращайте это в полный обход междоменных ограничений.
4. Используйте allow-list моделей. Рассматривайте запрошенный model как входные данные, которые вы валидируете. Вызывающие стороны в продакшене не должны иметь возможность загружать произвольные модели или выбирать непроверенные.
5. Задайте политику очереди и обрабатывайте перегрузки. В документации Ollama указано, что перегруженный сервер может возвращать HTTP 503, а также описана переменная OLLAMA_MAX_QUEUE. Используйте ограниченное число повторных попыток с экспоненциальной задержкой и джиттером, затем сообщайте вызывающей стороне контролируемую ошибку.
6. Планируйте емкость VRAM и параллелизм совместно. OLLAMA_NUM_PARALLEL увеличивает параллелизм для каждой модели, но вместе с ним растут требования к памяти. OLLAMA_MAX_LOADED_MODELS и OLLAMA_KEEP_ALIVE определяют, насколько агрессивно модели занимают память.
7. Инструментируйте важные пути. Отслеживайте задержку, время в очереди, HTTP 503, перечень активных моделей, размер запросов, разрывы потоковой передачи, ошибки вызовов инструментов и нагрузку на память GPU/CPU. ollama ps помогает проверить, где выполняются загруженные модели.
8. Тестируйте перезапуски и холодные старты. Локальной модели может потребоваться время на загрузку после развертывания или выгрузки. Проведите тесты нагрузки, отката и тайм-аутов до того, как API начнет поддерживать клиентский рабочий процесс.
9. Не храните секреты в клиентах. В облачном режиме храните OLLAMA_API_KEY в менеджере секретов на стороне сервера или защищенной среде выполнения, а не во frontend-бандле.
10. Фиксируйте набор приемочных тестов, а не только версию зависимости. Повторно запускайте тесты чата, потоковой передачи, инструментов, JSON, зрения и состояния ответа при каждом обновлении Ollama, смене модели или изменении слоя маршрутизации.

В FAQ Ollama документированы адрес привязки, конфигурация CORS, поведение очереди, настройки параллелизма и локальные/облачные средства управления, лежащие в основе этих рекомендаций.

Более безопасный путь внедрения

Используйте эту последовательность для приложения, которое начинает работу локально и позднее может использовать хостируемые модели:

1. Проверьте локальный endpoint. Загрузите одну модель, выведите список моделей и отправьте нестриминговый запрос на завершение чата.
2. Стабилизируйте конфигурацию клиента OpenAI. Вынесите базовый URL, API-ключ и переменные окружения модели — не используйте литералы, разбросанные по кодовой базе.
3. Создайте набор тестов совместимости. Включите вывод JSON, стриминг, все схемы инструментов, входные данные для vision там, где это применимо, поведение при тайм-аутах и некорректные запросы.
4. Проведите нагрузочное тестирование хоста. Запишите задержку, глубину очереди, VRAM/RAM и момент, когда начинают появляться 503.
5. Добавьте аутентифицированный периметр перед удалённым доступом. Оставьте Ollama приватной за сервисом приложения или доверенным прокси.
6. Оценивайте облачный режим отдельно. Используйте выделенный облачный ключ, модели из списка разрешённых, оповещения о бюджете и тестовые случаи, покрывающие специфичные для облака ограничения Responses.
7. Отделите выбор провайдера от бизнес-логики. Если продукту нужно сравнивать хостируемые модели или добавлять маршрут резервного переключения, сохраните контракт клиента OpenAI за небольшим адаптером.

Для последнего шага чек-лист миграции API-шлюза, совместимого с OpenAI поможет отделить интеграцию клиента от выбора провайдера моделей. Если вы хотите оценить нескольких хостируемых провайдеров, не добавляя новый шаблон клиента для каждого, ознакомьтесь с кратким руководством по Flatkey API и руководством о том, когда полезен AI API gateway.

Распространённые ошибки при работе с API Ollama, совместимым с OpenAI

Отношение к серверу localhost как к защищённому сервису

Локальный запрос может работать потому, что процесс находится на той же машине, а не потому, что доступ аутентифицирован. Как только меняется адрес привязки, туннель, прокси или порт контейнера, пересмотрите идентификацию, сетевую политику, TLS и журналирование аудита.

Предположение о полном паритете функций с OpenAI

Ollama явно поддерживает подмножество OpenAI API. Встройте проверку возможностей в CI и тестируйте семантику, а не только ответ 200. Определение инструмента, которое разбирается локально, может вести себя иначе после смены модели.

Использование облачных ценников в качестве бюджета

Тарифы на входные, кэшированные входные и выходные токены могут существенно различаться. Логируйте поля токенов, рассчитывайте фактическую стоимость успешной задачи и повторно проверяйте страницу цен, прежде чем фиксировать бюджет.

Повышение параллелизма без модели использования памяти

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

Передача облачного ключа браузеру

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

FAQ

Совпадает ли API Ollama, совместимый с OpenAI, с OpenAI API?

Нет. Слой совместимости Ollama поддерживает документированное подмножество OpenAI API, чтобы совместимые клиенты могли подключаться к Ollama. Прежде чем считать функцию переносимой, проверьте отдельные endpoints и поля в справочнике совместимости Ollama.

Нужен ли локальному Ollama API ключ API?

Нет. Ollama заявляет, что локальный API не требует аутентификации. Значение api_key="ollama" в примерах SDK — это требование клиента к непустому значению, а не учётные данные. Оставляйте локальный сервер на localhost или добавьте реальные средства защиты перед удалённым доступом.

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

Да. Прямой облачный доступ к https://ollama.com/v1 требует ключа API, передаваемого как Bearer-токен. Храните его на стороне сервера.

Можно ли использовать /v1/responses?

Да, для Responses-запросов без состояния. Не полагайтесь на previous_response_id или conversation. В облачной документации также отмечены ограничения, связанные со встроенным веб-поиском и повторным воспроизведением пользовательских/freeform вызовов инструментов.

Бесплатен ли API Ollama, совместимый с OpenAI?

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

Когда вместо этого следует использовать шлюз?

Используйте Ollama напрямую, когда локальный или облачный маршрут соответствует требованиям нагрузки к модели, конфиденциальности и эксплуатации. Рассмотрите шлюз, если вашему продукту нужна единообразная интеграция с несколькими хостируемыми провайдерами, процесс оценки моделей или отдельный путь резервного переключения. Начните с чёткого решения по unified AI API, затем сохраните тот же адаптер клиента на уровне приложения.

Заключение

API Ollama, совместимый с OpenAI даёт разработчикам практичный способ повторно использовать OpenAI SDK с локальными или облачными моделями. Безопасная реализация — это не просто изменение базового URL: она требует протестированной матрицы возможностей, чёткой модели затрат для локального и облачного режимов, приватной границы развёртывания локального сервиса и протестированного под нагрузкой плана для очередей и памяти модели.

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