Ollama Cloud API отличается от локального сервера тремя вещами: адрес https://ollama.com/api, ключ в заголовке Authorization и имя модели, которое берут из списка облачных моделей. Остальное знакомо по локальному Ollama: те же запросы вроде POST /api/chat, тот же формат сообщений. Модель работает на серверах Ollama, поэтому всё, что уходит в запрос, покидает ваш контур. Вариант уместен для обезличенных и безобидных данных, когда мощности локального сервера для нужной модели недостаточно.
Адрес и ключ
Ключ создают на странице ollama.com/settings/keys, передают в заголовке Authorization: Bearer, а запросы отправляют на https://ollama.com/api.
Документация Ollama описывает короткий путь: создать ключ в настройках аккаунта, положить его в переменную окружения серверного процесса и вызывать облачный адрес так же, как локальный. Требование к хранению сформулировано прямо: держите ключ вне браузерного кода и вне системы контроля версий. Для внутреннего сервиса это означает серверный маршрут, который сам добавляет заголовок, а до браузера сотрудника ключ дойти бессилен.
Заведите отдельный ключ под каждый сервис, чтобы при подозрении на утечку отозвать один ключ и сохранить остальные. Название ключа должно подсказывать назначение, а срок замены войдёт в регулярный календарь команды. Общие принципы выдачи и отзыва доступа разобраны в материале про токены и отзыв прав.
Эта статья посвящена вызову из кода. Сравнение облачного и локального режимов по данным, скорости и доступности вынесено в отдельный разбор: облако против локального запуска. Локальный интерфейс на своём сервере описан в статье про Ollama API.
Какую задачу отправить в облачную модель, а какую оставить у себя?
Точное имя модели
Самая частая причина сбоя при первом вызове — имя модели. Документация различает два контекста. В командной строке и приложении к имени добавляют суффикс -cloud, например gemma4:cloud. В запросах к API используют точное имя, которое возвращает /api/tags, например gemma4:31b. Копировать пример из чужой статьи рискованно: перечень моделей меняется, а часть моделей снимают с поддержки.
| Контекст | Как называть модель | Откуда брать имя |
|---|---|---|
| Командная строка и приложение | Имя с суффиксом -cloud | Каталог моделей Ollama |
| Запрос к ollama.com/api | Точное имя из ответа сервера | Вызов /api/tags с вашим ключом |
| Конфигурация сервиса | Одно значение в настройках | Копия из ответа /api/tags |
| Журнал вызовов | Имя вместе с датой проверки | Автоматически из настройки |
Имя модели выносят в настройки сервиса и записывают в каждую строку журнала. Документация Ollama также советует следить в настройках аккаунта за предстоящим выводом моделей из эксплуатации: когда модель исчезнет, сервис должен упасть с понятным сообщением, а команда уже иметь замену, проверенную на тестовом наборе.
Перед заменой модели прогоните одни и те же обезличенные примеры через старую и новую и сравните результаты глазами владельца процесса. Запись о замене с датой и версией набора вернёт вас к предыдущему состоянию, если качество просело.
Первый вызов
Тест выполняют на вымышленном тексте, далёком от клиентов. Задача сводится к проверке трёх вещей: доступ по ключу есть, имя модели принято, ответ читается кодом.
- Создайте ключ в настройках аккаунта Ollama и положите его в переменную OLLAMA_API_KEY на сервере.
- Запросите список моделей через /api/tags и выберите точное имя для настройки сервиса.
- Отправьте POST на https://ollama.com/api/chat с полями model, messages и stream, заголовок Authorization с Bearer-ключом.
- Проверьте код ответа и наличие текста в сообщении модели, затем сохраните идентификатор вызова в журнале.
- Сравните ответ с исходным текстом: факты, формулировки, лишние обещания. Отметьте результат в журнале теста.
Успешный код ответа доказывает доступ, и только. Запишите также время ответа, версию инструкции и размер текста: при смене модели эти показатели первыми покажут заметное изменение поведения. Смысл ответа проверяет человек на тестовом наборе, а запись во внутренней системе проходит через сервер с проверкой прав. Ответ модели остаётся черновиком до подтверждения сотрудником с нужным правом.
Для режима потоковой выдачи потребуется читать ответ порциями. На первых порах хватит ответа целиком: код проще, а ошибки очевиднее. Потоковый режим подключают, когда сотрудник ждёт текст на экране и задержка заметна. Сначала измерьте время полного ответа на типичном запросе: если оно укладывается в ожидания сотрудников, усложнение кода окажется лишним, а команда выиграет в простоте отладки и сопровождения.
Данные и сбои
Облачный вызов переносит текст запроса на сторону Ollama. По документации, Ollama исключает использование промптов и ответов для обучения моделей; юридическую сторону передачи данных решает ваша политика, и оговорка вендора её заменить бессильна. Скрипт заранее отсекает лишнее: полные карточки клиентов, телефоны, адреса и вложения остаются в исходной системе, наружу уходит очищенный фрагмент. Если политика компании запрещает выносить такие данные, этот путь подходит лишь для обезличенных задач, а остальное идёт на локальный сервер.
- Ответ 401 или 403: проверьте ключ, окружение и срок действия.
- Ответ с отказом по модели: сверьте имя с актуальным ответом /api/tags.
- Превышение лимитов: повторите запрос с паузой и ограничьте число попыток, расход смотрите в разделе использования аккаунта.
- Сетевой сбой или таймаут: передайте задачу в ручной маршрут и запишите технический статус.
По документации, облачный режим сейчас лишён поддержки структурированного вывода. Сервису, который ждёт JSON по схеме, нужна либо локальная модель (её подключение показано в статье про n8n и Ollama), либо разбор свободного текста с проверкой в коде.
Условия лимитов и доступности из вашей страны проверяйте на сайте Ollama и в условиях сервиса на дату запуска: обещаний о стабильной работе из России документация лишена, поэтому готовьте запасной путь на локальную модель.
Запасной путь
Перед пилотом опишите, что происходит при отказе облака. Рабочая схема содержит три ветки: повтор с паузой, переход на локальную модель с проверенным набором или передача задачи сотруднику. Переключение между ветками выполняет код сервиса, а модель остаётся в неведении о переключении.
Журнал хранит имя модели, версию инструкции, время вызова, технический статус и идентификатор карточки. Тексты запросов остаются в исходной системе. Расход по аккаунту сверяйте с журналом сервиса раз в неделю, а итоги обсуждайте на коротком созвоне владельца процесса и инженера: расхождение показывает забытые вызовы или чужое использование ключа.
Порог перехода на запасной путь задайте числом попыток и временем ожидания, например после третьего сбоя подряд или после превышения лимита ожидания ответа. Возврат на облако выполняйте после серии успешных проверочных вызовов, а переключение записывайте в журнал с причиной. Так руководитель процесса видит, как часто облако подводит, и принимает решение о смене схемы на данных. Решение о записи ответа в CRM, письме клиенту или смене статуса принимает серверная логика с подтверждением человека. Автоматическая отправка допустима позже и только для узкого класса безобидных ответов, одобренного владельцем процесса.
Создайте ключ, получите список моделей и отправьте один вымышленный запрос. Запишите, что вернулось, и покажите ответ владельцу процесса. Если нужен маршрут с запасным путём, правами и журналом, обсудите с нами внедрение ИИ во внутренний сервис; состав работ определим после разбора вашей задачи.