API-шлюз не видит локальную модель: диагностика адресов Ollama и Docker
Различайте адреса хоста, шлюза и модели в контейнерах. Проверьте прослушивание, сеть, протокол и доступ с помощью запроса без генерации и с ограничением времени.
Если Ollama отвечает на компьютере, а API-шлюз в Docker не может подключиться, сначала выясните, откуда отправляется запрос. Обычно localhost внутри контейнера шлюза означает сам этот контейнер, а не компьютер с браузером и не соседний контейнер модели. Замена имени модели, ключа или пополнение баланса не исправляет такую сетевую ошибку.
В статье используется локальный сервер Ollama и обычная мостовая сеть Docker. Проверяем четыре уровня: адрес, прослушивание порта, протокол и доступ. Названия полей конкретного шлюза могут отличаться; совместимые интерфейсы не обязательно поддерживают одинаковые функции. При использовании сети host или общего сетевого пространства имён значение loopback нужно определять по реальной схеме.
1. Определите расположение клиента, шлюза и модели
Запишите цепочку: клиент → внешний вход шлюза → сервер модели. Адреса и учётные данные на двух участках могут различаться. Клиент использует адрес и ключ шлюза, а шлюз — адрес upstream, доступный из собственной среды. Не передавайте браузеру административные учётные данные сервера модели.
| Схема размещения | Возможный адрес upstream со стороны шлюза | Что проверить |
|---|---|---|
| Шлюз и Ollama запущены напрямую в одной ОС | 127.0.0.1:11434 | Одинаковое сетевое окружение и прослушивание этого порта |
| Контейнер шлюза в Docker Desktop обращается к Ollama на хосте | host.docker.internal:11434 | Разрешение имени, адрес прослушивания и межсетевой экран |
| Контейнер в Linux Docker Engine обращается к хосту | Подтверждённый доступный адрес хоста или имя с настройкой host-gateway | Имя из Docker Desktop не обязательно существует автоматически |
| Шлюз и Ollama находятся в двух контейнерах одной пользовательской сети | Имя контейнера модели, например ollama:11434 | Реальное имя, общая сеть и внутренний порт контейнера |
| Шлюз находится на облачном сервере, Ollama — на домашнем компьютере | Разрешённый адрес в частной сети или VPN | Облачный localhost не указывает на домашнюю машину |
Документация Docker указывает, что контейнеры пользовательской сети могут обращаться друг к другу по имени. Для стандартной сети bridge такое разрешение имён нельзя предполагать.[2] Docker Desktop автоматически разрешает host.docker.internal. В Docker Engine параметр --add-host поддерживает специальное значение host-gateway, позволяющее добавить соответствие при создании контейнера.[3] Это определяет только адрес назначения: не меняет прослушивание службы, правила межсетевого экрана или аутентификацию.
Если порт 11434 контейнера опубликован на хосте как 18080, с хоста проверяют 18080. Шлюз в общей контейнерной сети обычно обращается к внутреннему порту 11434 сервера модели. Различайте опубликованный и внутренний порты. Не фиксируйте IP контейнера, который может измениться после пересоздания.
2. Проверяйте соединение из среды самого шлюза
По умолчанию Ollama привязывается к 127.0.0.1:11434; адрес прослушивания изменяется через OLLAMA_HOST.[1] Успешный запрос из браузера на хосте доказывает работоспособность только этого маршрута, но не доступа из контейнера шлюза.
Действуйте по порядку, меняя по одному условию:
- В среде сервера модели проверьте запуск службы, порт и журналы. Исключите остановленный процесс и ошибочный порт.
- Разрешите имя целевого хоста внутри контейнера, который отправляет запросы upstream. Если в образе нет диагностических средств, администратор может использовать временный контейнер с тем же сетевым пространством имён. Отметьте отличия прокси, DNS и разрешений от исходного процесса.
- Из той же сети запросите список моделей. Если хост получает ответ, а контейнер нет, сначала проверяйте адрес назначения, прослушивание, маршрутизацию и межсетевой экран.
- Если требуется изменить
OLLAMA_HOST, сначала ограничьте доступные интерфейсы и источники соединений, затем перезапустите службу по инструкции для своей ОС. Переменная, изменённая в терминале, не обязательно попала в уже работающую фоновую службу. - Повторите проверку из контейнера и отдельно убедитесь, что запрещённый источник не может подключиться.
0.0.0.0 означает прослушивание всех IPv4-интерфейсов. Это не адрес назначения для клиента и не настройка безопасности. Не открывайте порт 11434 всему интернету только ради диагностики.
3. Отделите получение списка моделей от успешной генерации
Следующая команда запрашивает нативный список моделей Ollama. Она не запускает генерацию, не передаёт API Key и не следует перенаправлениям. Требуется curl. Если Windows PowerShell трактует curl как псевдоним, используйте curl.exe.
curl --fail --silent --show-error --connect-timeout 3 --max-time 10 --noproxy '*' http://127.0.0.1:11434/api/tags
Этот адрес подходит для проверки на одной машине. В контейнере шлюза замените имя хоста и порт согласно первой таблице, сохранив /api/tags. Параметр --noproxy '*' направляет напрямую только этот диагностический запрос, чтобы внутренний адрес случайно не ушёл через исходящий прокси. Используйте его лишь для проверенной внутренней цели; это не рекомендация постоянно отключать обязательный прокси организации.
Ожидание соединения ограничено 3 секундами, весь запрос — 10 секундами. Обычно HTTP 4xx/5xx приводит к ненулевому коду, но curl предупреждает: в некоторых сценариях аутентификации, включая 401/407, нельзя полагаться только на --fail.[5] Этот параметр скрывает тело ответов, которые он признаёт ошибочными: при необходимости получите описание из контролируемого журнала службы. Пустой вывод сам по себе не означает отсутствие ответа. HTTP 3xx не обязательно даёт ненулевой код. Даже код 0 не доказывает правильность конечной точки: при HTML или неожиданно пустом ответе изучите статус и заголовки, не переходя вслепую на страницу входа.
| Результат | Следующее действие |
|---|---|
| Код curl 6: имя не разрешается | Проверить имя службы, сеть и соответствие host-gateway |
| Код 7: соединение не установлено | Проверить адрес прослушивания, порт, процесс и правила отклонения |
| Код 28: истекло время | Проверить маршруты, отбрасывание пакетов, прокси и нагрузку; тайм-аут не доказывает остановку сервиса |
| Код 22: ошибка HTTP | Посмотреть статус и обезличенные журналы; при 404 проверить путь, при 401/403 — уровень контроля доступа |
| HTML, перенаправление или JSON другого формата | Проверить, не выбран ли веб-интерфейс, стандартная страница прокси или другой сервер |
JSON с массивом models | Список получен; ещё нужно проверить реальные имена и способность выполнить генерацию |
Метод Ollama GET /api/tags возвращает список моделей.[4] Пустой массив не означает сетевой сбой. Наличие модели в списке не доказывает, что она загружена, памяти достаточно или все параметры поддерживаются. Для этой статьи команда проверена на локальном имитаторе HTTP-сервера: успешный ответ, ошибка HTTP, перенаправление и тайм-аут. Тестов производительности реальных моделей или поставщиков не проводилось.
4. После проверки сети уточните протокол и отображение модели
Нативный путь Ollama /api/tags не является универсальным адресом для клиентов шлюза. Нативный чат Ollama использует /api/chat и по умолчанию возвращает потоковый ответ.[6] Если выбран другой адаптер совместимости, сверьте полный путь запроса и формат сообщений с его документацией. Обещание поддержки локальных моделей само по себе недостаточно.
Запишите версию шлюза, тип канала, имя и порт upstream, окончательный путь запроса, клиентский псевдоним модели, реальное имя после преобразования и настройку потока. Проверяйте именно конечный адрес: один слой мог уже добавить префикс, а другой — повторить его.
Затем проверьте короткий текстовый запрос на установленной модели, которая точно выполняется локально. Убедитесь, что клиент и шлюз не переключаются автоматически на платное облако. Сначала проверьте обычный ответ, затем потоковый и подтвердите выбранный upstream по журналу. Не загружайте огромную модель только ради проверки и не используйте чувствительные производственные данные. Вызовы инструментов, изображения и структурированный вывод проверяются отдельно: успешный обычный чат не подтверждает эти функции.
Если сбой возникает только при потоковой передаче, переходите к диагностике потокового вывода. При ошибке имени модели или пути используйте разбор model not found и 404. Эти уровни имеет смысл проверять после подтверждения сетевой доступности.
5. Сохраните аутентификацию шлюза и закройте обходной маршрут
Согласно документации Ollama, локальные API-запросы не требуют API Key.[7] Проверка ключа на шлюзе не означает, что сервер модели проверяет тот же ключ при прямом обращении. Если порт модели доступен извне, клиент может обойти ограничения бюджета, скорости и журналирование шлюза.
Проведите три проверки с учётом своей схемы:
- Разрешённый клиент выполняет короткий запрос через шлюз; отсутствующий или неправильный ключ шлюза приводит к отказу.
- Шлюз достигает модели, а недоверенный сетевой источник не может обратиться к её порту напрямую.
- После перезапуска или пересоздания контейнеров адреса, ограничения доступа и отображение модели остаются рабочими.
Перед изменением публикации портов Docker уточните интерфейс хоста. Без явного ограничения публикация порта может сделать его доступным из внешней сети.[2] В частной сети или VPN также нужно контролировать участников и разрешения. Через недоверенную сеть используйте аутентифицированный зашифрованный канал: внутренний HTTP-пример нельзя переносить в интернет без защиты. OLLAMA_ORIGINS регулирует браузерные источники CORS и не заменяет серверную аутентификацию или межсетевой экран.[1]
Если шлюз и модель используют одну машину, дополнительно проверьте конкуренцию за ресурсы по руководству об оценке ресурсов API-шлюза. Здесь рассматриваются сетевой маршрут и границы доступа; статья не обещает фиксированную параллельность для какой-либо конфигурации.
Официальные источники и границы проверки
- [1] Ollama FAQ: адрес прослушивания, переменные окружения и источники.
- [2] Docker Engine: сети, разрешение имён и публикация портов.
- [3] Docker run: host-gateway и дополнительные имена хостов.
- [4] Ollama: список моделей.
- [5] Официальное руководство curl.
- [6] Ollama: интерфейс чата.
- [7] Ollama: введение в API и аутентификация локальных запросов.
Документация проверена 2026-10-11. Пример относится к обычной мостовой сети и локальному Ollama. Для другой ОС, сетевого режима, адаптера или версии повторно проверьте условия. Платные API не вызывались, производительность реального развёртывания не измерялась.