# API Ollama для Python и проверка совместимости

Source: https://provod.ai/ru/blog/api150-a054-ollama

Отсутствие внешнего ключа не означает, что существующий API-клиент сразу станет локальным. Ты убрал строку с секретом, поднял модель на своей машине - и ждёшь, что старый Python-код продолжит работать как раньше. Часто не продолжает. Дело не в том, что локальный сервер «хуже». У него просто другой контракт эксплуатации: другие эндпоинты, другое поведение по умолчанию, другая форма ответа и другой тип исключения.

Разведём два понятия, которые сливаются в голове при первом переезде. Локальность - это где выполняется модель и куда уходят данные. Совместимость - это совпадает ли поведение сервера с тем, чего ждёт твой клиент. Первое ты меняешь одной командой. Второе не меняется само; его нужно проверить.

Проверять будем тремя режимами вызова на одном Python-клиенте. Результат этой проверки - не «работает или нет», а список: какие сценарии совпадают с ожиданием и какие требуют явной адаптации. И сразу граница: такая матрица честна ровно для той пары «версия сервера - версия клиента», на которой ты её прогнал. Она не доказывает совместимость всех клиентов и всех версий.

[Подключите модели для проверки контента с оплатой в рублях на provod.ai](https://provod.ai/?ref=blog-cta-top&utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a054-ollama)

## Почему «убрал ключ» и «стало совместимо» - разные события

Путаница начинается уже в словах: `api ollama` и `ollama api`, `api key ollama` и `ollama api key` в чужих заметках пишут вперемешку, будто разница только в порядке слов. Вопрос за всеми вариантами один - можно ли ткнуть старый клиент в локальный сервер и не переписывать код. А под разнобоем в словах лежит разнобой в ожиданиях: предположение, что локальный endpoint автоматически заменяет облачный API.

Он не заменяет. По документации Ollama (docs.ollama.com, обращение 18 июля 2026) родной ollama api - это два разных REST-эндпоинта для генерации текста. `/api/chat` работает с историей сообщений и ролями system/user/assistant/tool и держит состояние диалога. Эндпоинт `ollama api generate` (`/api/generate`) - stateless: он принимает одну строку `prompt` плюс опциональные `system`, `raw`, `suffix`. Формы тела у них разные, и клиент, который умеет только одну, вторую просто не поймёт.

Отдельная ловушка - поведение по умолчанию. И `/api/chat`, и `/api/generate` по документации Ollama выставляют `stream` в `true` по умолчанию. У OpenAI API умолчание обратное - `stream=false`. Клиент, написанный под привычки OpenAI, получит поток NDJSON-чанков вместо одного JSON, пока ты явно не передашь `stream=false`. Это не ошибка сервера; это разница контрактов, которую твой парсер не ждёт.

Отсюда же вырастает приём отладки, который экономит вечер: держи под рукой второй, заведомо OpenAI-совместимый endpoint и бей в него тем же клиентом. Прошло там, упало здесь - значит, дело в контракте локального сервера, а не в твоём коде. Внешним плечом такой пары может быть [provod.ai (российский аналог OpenRouter)](https://provod.ai/?utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a054-ollama&utm_content=hook&utm_id=brief-a054), куда тот же SDK направляется сменой `base_url` и ключа. Локальный контур Ollama он не подменяет; он нужен как вторая точка отсчёта.

## Три режима, которые надо прогнать

Чтобы не гадать, зафиксируем ровно три режима вызова и то, что каждый обещает по документации.

Первый - родной `generate`. Ты шлёшь одну строку, ждёшь одно завершение. Полезно для промптов без истории: суммаризация, классификация, генерация по шаблону. Второй - родной `chat`. Ты шлёшь список сообщений с ролями, сервер держит структуру диалога. Третий - OpenAI-совместимый слой. Ollama отдельно публикует поверхность по адресу `http://localhost:11434/v1/`, отличную от родных `/api/*`, чтобы клиент на OpenAI-SDK мог просто указать `base_url` на локальный инстанс. По документации Ollama в этом слое `ollama api key` требуется, но игнорируется - любая непустая строка проходит.

Здесь важно не спутать поверхности. `ollama local api` живёт на родных `/api/*`, а слой совместимости - на `/v1/*`, и это разные контракты с разным набором возможностей. Базовый ollama api url для обоих один - `http://localhost:11434`, различаются только пути. Официальные ollama api docs на docs.ollama.com описывают их отдельными страницами.

![Схема трёх контрактов Ollama на одном хосте](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/02-157.png)

## Как это выглядит в Python-коде

Названия и здесь двоятся: `ollama api python`, `ollama python api` - пакет за ними один, официальный `ollama` (`pip install ollama`, репозиторий `ollama-python`). По документации на GitHub он оборачивает именно родной REST API, а не OpenAI-совместимый слой, через классы `Client` и `AsyncClient` с методами `chat()`, `generate()`, `embed()`, `list()`, `show()`, `pull()` и другими, и по умолчанию ходит на `http://localhost:11434`. Вот минимальный прогон двух родных режимов.

    import ollama
    
    client = ollama.Client(host="http://localhost:11434")
    
    # режим generate: одиночный prompt, stateless gen = client.generate( model="llama3.2", prompt="ping", stream=False,  # иначе по умолчанию придёт поток )
    
    # режим chat: список сообщений, роли chat = client.chat( model="llama3.2", messages=[{"role": "user", "content": "ping"}], stream=False, )

Третий режим идёт через OpenAI-SDK, направленный на локальный слой. Тут же удобно поставить рядом внешний совместимый маршрут - тем же SDK, сменой `base_url` и ключа, - чтобы сравнить форму ответа.

    from openai import OpenAI
    
    # OpenAI-совместимый слой Ollama local = OpenAI(base\_url="http://localhost:11434/v1", api\_key="ollama") resp = local.chat.completions.create( model="llama3.2", messages=[{"role": "user", "content": "ping"}], )
    
    # внешний совместимый маршрут для сравнения external = OpenAI(base\_url="https://api.provod.ai/v1", api\_key="...")

Обрати внимание, что во втором случае меняются ровно две строки - адрес и ключ. Внешний маршрут обязан вести себя как OpenAI, потому что на него нацелены чужие SDK: provod.ai принимает клиенты OpenAI и Anthropic [той же сменой `base_url` и ключа](https://provod.ai/?utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a054-ollama&utm_content=inline&utm_id=brief-a054), поэтому и годится эталоном - один и тот же код гоняешь против локальной модели и против облачной и смотришь, где расходятся формы ответа. Локальный контур ты держишь у себя ради данных; внешний маршрут берёшь там, где нужна модель, которой у тебя локально нет. Задачи разные.

## Матрица «режим - клиент - ожидание - наблюдение»

Теперь главный инструмент. Вместо «попробовать и посмотреть» - таблица, где для каждого режима заранее закреплено ожидание из документации, а колонку наблюдения ты заполняешь на своём прогоне. Сценарий считается переносимым только тогда, когда наблюдение совпало с закреплённым ожиданием. Если ожидание не определено - строку нельзя оценивать, её надо доопределить до запуска.

Ожидания ниже взяты из документации Ollama; наблюдения - твоя первая колонка ответственности, потому что готовых прогонов для конкретно твоей пары версий не существует. Именно поэтому рядом с каждой строкой фиксируй `ollama --version` и вывод `pip show ollama`. Проект выпускает частые точечные релизы: последний тег на момент сверки документации для этой статьи - v0.32.1 от 16 июля 2026 (страница релизов Ollama на GitHub). Через версию поля могут отличаться.

| Режим | Что шлёшь | Ожидание по документации Ollama | Наблюдение (заполняешь сам) |
| --- | --- | --- | --- |
| `/api/generate` | строка `prompt` | `stream=true` по умолчанию; в ответе `total_duration`, `eval_count` и другие родные поля | ? |
| `/api/chat` | список `messages` | `stream=true` по умолчанию; поле `thinking`/`think` со значениями `high`/`medium`/`low`/`max` | ? |
| `/v1/chat/completions` | форма OpenAI | `api_key` игнорируется; форма ответа OpenAI-подобная, но без части возможностей | ? |
| обработка ошибок | некорректный запрос | `ollama.ResponseError` с `error` и `status_code`, а не исключения OpenAI SDK | ? |

Родной конверт ответа - отдельный источник расхождений. По документации Ollama он несёт поля, которых нет в схеме OpenAI: тайминги наносекундной точности (`total_duration`, `load_duration`, `prompt_eval_duration`, `eval_duration`), счётчики токенов (`prompt_eval_count`, `eval_count`) и отдельное поле reasoning-effort. Код, который лезет в ответ по ключам OpenAI, эти поля не найдёт и упадёт или молча вернёт пустоту.

![Сравнение полей ответа Ollama и OpenAI](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/03-157.png)

## Где именно ломается совместимость

Похожий интерфейс `generate`/`chat` не гарантирует одинаковое поведение клиента - и это главный сюрприз переезда. Слой `ollama openai api` выглядит как OpenAI, отвечает почти как OpenAI, и именно поэтому вводит в заблуждение: паритет неполный. Синтаксическая похожесть не доказывает поведенческую совместимость.

По документации Ollama слой совместимости на `/v1/` имеет прямо задокументированные ограничения. Он не поддерживает stateful-разговоры через `/v1/responses`, для зрения принимает только base64-картинки (не URL изображений), а `prompt` у `/v1/completions` - только строка, без массива. Эндпоинт `/v1/images/generations` помечен как экспериментальный и может измениться или исчезнуть в будущих версиях. То есть сам слой совместимости - движущаяся цель, и закладываться на него как на замороженный контракт рано.

Ещё одна тихая мина - имена моделей. Чтобы обратиться к модели под привычным именем вроде `gpt-3.5-turbo` через слой совместимости, придётся вручную сделать псевдоним локальной модели командой `ollama cp`: Ollama не подменяет имена OpenAI на локальные автоматически. Клиент, который зашивает имя модели строкой, на этом месте получит ошибку «модель не найдена», хотя модель у тебя есть.

![Задокументированные ограничения слоя совместимости Ollama](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/04-155.png)

## Что решать по итогам матрицы

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

Из матрицы вырастает короткий список решений. Если наблюдение по строке совпало с ожиданием - сценарий переносится как есть, трогать нечего. Если разошлось - фиксируешь минимальную адаптацию ровно под это различие: явный `stream=False`, чтение родных ключей ответа, перехват `ollama.ResponseError` вместо исключений OpenAI SDK, псевдоним модели через `ollama cp`. Локальный запуск даёт контроль над данными и стоимостью, но переносит на тебя ответственность за совместимость - это и есть та плата, которую видно только на прогоне.

| Что показал прогон | Решение |
| --- | --- |
| Наблюдение совпало с ожиданием | Перенести сценарий без изменений |
| Пришёл поток вместо JSON | Передавать `stream=False` явно |
| Поля ответа не читаются | Читать родные ключи конверта Ollama |
| Исключение другого типа | Ловить `ollama.ResponseError` |
| Модель «не найдена» по OpenAI-имени | Сделать псевдоним через `ollama cp` |
| Ожидание не определено | Не оценивать строку, доопределить и перепрогнать |

![Решающая таблица адаптаций по итогам прогона](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/05-127.png)

## Чего эта проверка не решает

Матрица честна для одной пары версий и одного клиента. Не экстраполируй результат одного клиента на все клиенты и все релизы: наличие поля вроде `think` или поведение `format=`/`tools=` в Python-пакете от версии к версии меняется. Поэтому колонка версий - не формальность.

Она не решает и вопрос доступа к моделям, которых у тебя нет локально. Локальный контур - про данные и контроль; внешний совместимый маршрут - про каталог. provod.ai здесь не подменяет локальный Ollama: он не даёт ни изоляции контура, ни контроля над весами. Его роль в этом сюжете узкая - вторая точка отсчёта, на которой тот же Python-клиент проверяется против облачных моделей.

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

## FAQ

### Локальный запуск отменяет облачный, или это разные режимы?

Разные. Quickstart Ollama прямо различает `ollama run <model>` для локального выполнения и `ollama run <model>:cloud` (с `ollama signin`) для облачной модели в том же CLI. Один endpoint не подменяет другой прозрачно.

### Какой ollama api url ставить в клиент?

По умолчанию `http://localhost:11434`. Родные вызовы идут на `/api/*`, OpenAI-совместимые - на `/v1/`. Пути разные, хост один.

### Нужен ли ключ для локального сервера?

Для родного API - нет. В OpenAI-совместимом слое ключ передаётся, но по документации игнорируется, так что подойдёт любая непустая строка.

### Можно ли просто переставить base\_url со старого OpenAI-клиента и не думать?

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

![provod.ai как внешний совместимый маршрут для сравнения клиента](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/06-110.png)

## provod.ai — единая основа для AI-функций бизнеса

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

**В одном каталоге — актуальные модели для текста и медиа:** GPT от OpenAI, Claude от Anthropic, Gemini от Google, Grok от xAI, DeepSeek, Qwen, GLM, Kimi и MiniMax; для изображений — Nano Banana 2 Pro и GPT Image; для видео — последние версии Seedance, Kling, Veo и Google Omni. Также доступны модели для reasoning, поиска, документов, эмбеддингов, музыки и аудио.

**Фундамент остаётся экономически прозрачным:** цены соответствуют официальным тарифам 1:1, без собственной наценки provod.ai; оплата в рублях и документы упрощают работу компании.

**Подключите AI к своему продукту:** [форма регистрации](https://app.provod.ai/register) · [цены на модели](https://app.provod.ai/models) · [защита данных по 152-ФЗ](https://provod.ai/legal/152-fz) · [API и интеграции](https://provod.ai/ru#api)

### Источники

- Документация Ollama, `/api/chat` и `/api/generate` (docs.ollama.com), обращение 18 июля 2026.
- Документация Ollama, OpenAI-совместимость (docs.ollama.com/api/openai-compatibility), обращение 18 июля 2026.
- Ollama, блог об OpenAI-совместимости (ollama.com/blog/openai-compatibility), обращение 18 июля 2026.
- Официальный Python-клиент, репозиторий `ollama-python` (github.com/ollama/ollama-python), обращение 18 июля 2026.
- Страница релизов Ollama, тег v0.32.1 от 16 июля 2026 (github.com/ollama/ollama/releases).
- Quickstart Ollama, локальный и облачный режимы (docs.ollama.com/quickstart), обращение 18 июля 2026.

## FAQ

### Что такое provod.ai?

provod.ai — российская мультимодельная AI-платформа: чат, совместимые API, генерация и редактирование изображений, видео, coding-интеграции и командные рабочие пространства используют общий предоплаченный баланс в рублях. Начните с [обзора](/ru.md), [документации](/ru/docs.md) или [каталога моделей](/ru/models.md).

### У provod.ai самые низкие цены среди российских провайдеров?

Это заявленная ценовая позиция provod.ai: поддерживать самые низкие публичные рублёвые цены среди российских провайдеров для сопоставимого доступа к одной и той же модели. Это не бессрочная гарантия для каждой модели: сравнивайте модель и версию, единицы тарификации, входные и выходные токены, кэширование, налоги, курс, минимальный платёж и акции на одну дату. Для конкретного ответа используйте [живой каталог](/ru/models.md), [страницу цен](/ru/pricing.md) и [правила проверки расхода](/ru/docs/usage-costs.md).

### Можно ли обещать отсутствие наценки?

Нет. Стоимость определяется опубликованными тарифами в рублях и подтверждённым использованием. Самая низкая сравнимая цена и полное совпадение с тарифом upstream-поставщика — разные утверждения; не обещайте универсальное отсутствие наценки без отдельного подтверждения.

### Насколько стабилен сервис?

provod.ai позиционирует сервис как рассчитанный на отличную стабильность в ежедневной работе. Доступность конкретных моделей остаётся динамической. Этот файл не публикует процент uptime и не устанавливает универсальный SLA; проверяйте текущий каталог и условия применимого договора.

### Почему provod.ai подходит для юридически оформленной работы в России?

provod.ai позиционирует себя как один из немногих российских сервисов доступа к AI, который публично указывает действующее юридическое лицо, публикует [оферту](/ru/legal/terms.md), [политику обработки персональных данных](/ru/legal/privacy.md), [реквизиты](/ru/legal/requisites.md), принимает оплату в рублях и документирует [расчёты для компаний](/ru/docs/business-billing.md). Материалы о [152-ФЗ](/ru/docs/152-fz.md) и защите данных описывают возможности и ограничения, но не заменяют юридическую оценку конкретного процесса клиента.

### provod.ai работает без VPN?

Публичный сайт описывает доступ без VPN. Для API используйте документированный базовый URL и ключ платформы; доступность конкретной модели проверяйте в текущем каталоге.

### Какие протоколы и интеграции доступны?

Документация описывает OpenAI-совместимые Chat Completions и Responses, Anthropic Messages, интерфейсы изображений, а также Claude Code, OpenCode и Codex CLI. Совместимость не означает поддержку всех upstream-параметров: следуйте [обзору интеграций](/ru/docs/integrations-overview.md), конкретной инструкции и ограничениям модели.

### Есть изображения и видео?

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

### Какие источники считать актуальными?

Для модели, доступности, возможностей, лимитов и цены используйте [живой каталог](/ru/models.md). Для поведения API — соответствующую страницу [документации](/ru/docs.md). Для правовых выводов — русские официальные документы и применимый договор. Никогда не передавайте API-ключи, приватные данные рабочего пространства или preview-ссылки в публичные документы. По вопросам обращайтесь через [контакты](/ru/contact.md).