Гайд · TNWS AI
Как проверить готовность llama.cpp server через /health перед запросом к модели
Разбираем ответ /health при загрузке модели и после неё; Python-проверка различает 503, 200 и сетевую ошибку.
Задача и применимость
Поисковый вопрос: «как проверить готовность llama.cpp server health 503». Отделить неготовую модель от недоступного процесса, прежде чем отправлять пользовательский запрос. Актуальная документация llama.cpp server на 20 сентября 2026 года; локальный сервер на 127.0.0.1:8080 с GGUF-моделью. Поведение фиксируйте для своей сборки командой llama-server --version. Это не Ollama API.
Пример рассчитан на уже имеющийся файл модели, полученный законным способом по условиям его лицензии. Здесь не утверждается, что любая GGUF-модель одинаково понимает русский язык или имеет один и тот же чат-шаблон. Фактический номер сборки узнавайте локально через llama-server --version и повторяйте контрольный опыт после обновления бинарника.
Что подтверждено документацией
Официальная документация указывает для GET /health публичный endpoint без проверки API-ключа. Во время загрузки модели ожидается HTTP 503 с типом unavailable_error и сообщением Loading model; после загрузки — HTTP 200 и JSON {"status":"ok"}. Аналогом служит /v1/health. Открывать адрес здоровья в интернет только ради мониторинга не требуется.
Порядок действий
- Проверьте, что GGUF-файл существует и запускается сервер; запишите идентификатор сборки.
- Запустите локальный процесс приведённой командой и убедитесь, что порт 8080 не занят.
- Вызовите /health в коротком цикле, отдельно разбирая HTTPError 503 и сетевую ошибку.
- Отправляйте рабочие запросы лишь при коде 200 и поле status=ok.
- Повторите проверку после рестарта, не считая единичный успех гарантией будущей доступности.
Локальный запуск для описанного сценария (замените путь к файлу на ваш):
./build/bin/llama-server -m /models/your-chat-model.gguf --host 127.0.0.1 --port 8080
Готовый шаблон запроса и проверки
import json, time, urllib.error, urllib.request
url = "http://127.0.0.1:8080/health"
for attempt in range(12):
try:
with urllib.request.urlopen(url, timeout=3) as reply:
payload = json.load(reply)
if reply.status == 200 and payload.get("status") == "ok":
print("READY", attempt)
break
except urllib.error.HTTPError as error:
if error.code != 503:
raise
print("LOADING", attempt)
except urllib.error.URLError as error:
print("UNREACHABLE", str(error.reason))
time.sleep(1)
else:
raise TimeoutError("Модель не стала готовой за отведённое время")
Входные данные и ожидаемый результат
Вход: процесс запущен и ещё читает GGUF. Первые попытки могут дать LOADING; после завершения загрузки появляется READY и номер попытки. Если процесс не слушает порт, появится UNREACHABLE. Скрипт не обещает конкретное число секунд или попыток: оно зависит от модели и компьютера.
Почему важна именно эта проверка
Статус 503 означает, что HTTP-сервер уже ответил, но модель ещё загружается; это не тождественно Connection refused, когда по адресу вообще некому принимать соединение. Различие важно для диагностики: в первом случае уместно подождать в пределах дедлайна и просмотреть журнал загрузки, во втором — проверить команду запуска, порт и адрес. Если вы соединяетесь с сервером из другого контейнера, 127.0.0.1 означает сам контейнер, а не компьютер с моделью. В таком случае сетевую схему надо проектировать отдельно и ограничивать доступ к модельному API.
Работа с реальными данными
Здоровье процесса не доказывает правильность ответа языковой модели. После READY выполните маленький контрольный запрос с известным текстом и проверьте структуру результата. Если ваш балансировщик начал слать рабочий трафик на живой сервер, но затем тот потерял модель или память, health-check должен повторяться, а не использоваться единожды при деплое. Установите тайм-аут как решение приложения; не маскируйте бесконечной петлёй ошибку загрузки несовместимого GGUF. Сохраняйте код состояния и время ожидания в журнале, но не логируйте исходные приватные промпты.
Проверка после изменения модели или нагрузки
Для проверки регрессии полезно три сценария: выключенный сервер, загрузка крупной модели и нормальный прогретый запуск. Код 200 без ожидаемого поля status при нестандартной прокси-конфигурации нельзя трактовать как доказательство работоспособности llama.cpp. Не вводите API-ключ в health-проверку ради этого маршрута: документация говорит, что он публичный. При публикации порта вовне /health сам по себе не защищает остальные маршруты; обсуждение авторизации и сетевой сегментации — отдельная задача. Не увеличивайте тайм-аут до бесконечности, чтобы скрыть постоянно повторяющуюся ошибку.
Если применяется режим сна при простое, проверка здоровья сама по себе не должна восприниматься как полноценный разогрев модели: README отдельно указывает, что GET /health не запускает пробуждение. В такой конфигурации после первого рабочего запроса возможна дополнительная задержка на возврат модели в память. Оцените её на тестовом клиенте и сообщайте пользователю о запуске обработки, не утверждая, что короткий health-check гарантирует мгновенное получение ответа. Это особенно важно после длительного периода без запросов.
Критерии приёмки
- После загрузки есть одновременно HTTP 200 и status=ok.
- Во время загрузки 503 не превращается в ложный сигнал готовности.
- При недоступном порте зафиксирована сетевая ошибка, а не «модель думает».
Частые ошибки и чего не делать
- Не отправлять пользовательский трафик по одному признаку открытого TCP-порта.
- Не путать 503 при загрузке с сетевым отказом.
- Не открывать весь локальный API в публичную сеть ради проверки здоровья.
Краткие ответы на вопросы
Требуется ли ключ для /health?
В документации маршрут обозначен как публичный.
Что означает 503?
Сервер отвечает, но модель ещё загружается.
Достаточен ли 200 для оценки качества модели?
Нет, это только сигнал готовности.
Официальные источники
Частые вопросы
Требуется ли ключ для /health?
В документации маршрут обозначен как публичный.
Что означает 503?
Сервер отвечает, но модель ещё загружается.
Достаточен ли 200 для оценки качества модели?
Нет, это только сигнал готовности.
Читайте также
Как ограничить генерацию llama.cpp через n_predict и проверить причину остановки
Используем native /completion и поля остановки, чтобы отличить заданный лимит от нормального конца ответа.
Как переранжировать найденные документы через llama.cpp /v1/rerank
Запускаем reranker GGUF, подаём список кандидатов и проверяем порядок и связь результата с исходными документами.
Как получить embeddings через llama.cpp /v1/embeddings и проверить pooling
Запускаем специализированную embedding-модель, кодируем две строки и проверяем размерность и числовой формат.
Комментарии
Пока тихо. Скажите первое слово