Управление gpt2giga из внешних систем

• Дата: 3 августа 2026 года
• Статус: принято для gpt2giga 0.3
• Ответственное направление: интеграция
• Схемы: gpt2giga.inspect.v1, gpt2giga.readiness.v1, gpt2giga.bridge-models.v2, gpt2giga.route-support-matrix.v1, gpt2giga.model-catalog.v1, gpt2giga.effective-capabilities.v1, gpt2giga.error.v1

Контекст

Внешняя система, например GigaLoom, должна запускать и останавливать gpt2giga как обычное установленное приложение. Ей не нужно импортировать внутренние Python-модули или разбирать текст логов. Для этого gpt2giga предоставляет стабильный командный интерфейс и HTTP API.

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

Решение

Запуск и предварительная проверка

Обычный запуск:

gpt2giga --config <path>

Проверка конфигурации без запуска сервера:

gpt2giga --config <path> --inspect-config

Обе команды используют один разборщик конфигурации. В режиме --inspect-config шлюз не открывает порт и не обращается к провайдерам. Если профили, ссылки на учётные данные, адреса, алиасы, возможности и ревизии матрицы корректны, команда печатает в stdout один очищенный JSON-документ и завершается с кодом 0.

При ошибке она печатает gpt2giga.error.v1 и возвращает код 2. Логи идут в stderr. Значения учётных данных не попадают в диагностический документ и не печатаются.

HTTP API для управления

Метод	Успех	Ошибка	Назначение
GET /health	200 без тела	Процесс недоступен	Проверка, что процесс работает.
GET /ready	200 JSON	503 JSON	Готовность маршрутов, клиентов и каталога моделей.
GET /models	200 JSON	Ошибка публичного протокола	Представление общего каталога в формате выбранного API.
GET /bridge/models	200 JSON	503 JSON	Машиночитаемый снимок того же каталога.
GET /bridge/capabilities	200 gpt2giga.route-support-matrix.v1	503 JSON	Матрица из 16 маршрутов без пользовательского содержимого.
GET /bridge/capabilities?model=...&protocol=...&api_mode=...	200 gpt2giga.effective-capabilities.v1	400/404/503 JSON	Возможности выбранной модели и маршрута.

Предварительная проверка, /health и общая матрица маршрутов не вызывают внешние API. Методы каталога моделей используют ModelCatalog, который может обновлять данные через API провайдера и сообщает, свежий ли текущий снимок.

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

Формат ошибок

Методы управления и --inspect-config используют общий формат:

{
  "schema_version": "gpt2giga.error.v1",
  "error": {
    "code": "gateway_not_ready",
    "message": "Gateway routes are not ready.",
    "details": [{"reason_id": "registry_not_loaded"}]
  }
}

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

Завершение процесса

После SIGTERM или сигнала прерывания шлюз:

1. помечает себя как неготовый и перестаёт принимать новые запросы к моделям;
2. прекращает принимать новые соединения;
3. ждёт завершения активных запросов до заданного срока;
4. отменяет оставшиеся операции провайдеров;
5. закрывает созданные им клиенты, приёмники событий и хранилища;
6. возвращает ненулевой код, если не удалось освободить ресурсы за отведённое время.

Внешняя система может отправить SIGKILL только после документированного срока. Ни один этап завершения не записывает промпты или секреты в управляющий API.

Миграция и откат

• /health и существующие публичные маршруты сохраняют прежнее поведение.
• Трафик следует направлять только после успешного ответа /ready; /health для этого недостаточно.
• Без --config работает только встроенный нативный маршрут GigaChat.
• После отката на 0.2.x новые методы API исчезнут, но преобразование постоянных данных не потребуется.