Переход на gpt2giga 0.3

В версии 0.3 можно подключить несколько провайдеров без миграции постоянных данных. Если вы работаете только с GigaChat, обновление не требует файла профилей или дополнительного флага: нативная реализация Responses продолжит работать как раньше.

Эта страница также описывает запуск gpt2giga из внешней системы управления, например GigaLoom. Такая система использует только публичные команды и HTTP API, не импортируя внутренние модули шлюза.

Выбор режима

Режим	Конфигурация	Поведение
Только GigaChat	Нет --config и GPT2GIGA_CONFIG	Встроенный маршрут читает существующие GIGACHAT_* и настройки прокси. Нативные Responses, встроенные инструменты, вложения, API v1/v2 и остальные публичные маршруты сохраняются. Список моделей запрашивается у GigaChat.
Несколько провайдеров	--config <path> или GPT2GIGA_CONFIG=<path>	Файл профилей задаёт адреса, учётные данные, алиасы и политики маршрутов. Каталог GigaChat остаётся динамическим, а клиентские запросы не могут менять маршруты.

Дополнительного флага совместимости Responses в 0.3 нет. Обработчик, маршрут и модель выбираются до обращения к провайдеру. Ошибка после начала операции или отправки первых байтов клиенту не приводит к переключению на другой маршрут.

Путь к файлу можно передать двумя способами:

gpt2giga --config /etc/gpt2giga/providers.yaml
GPT2GIGA_CONFIG=/etc/gpt2giga/providers.yaml gpt2giga

Если указаны оба варианта, пути должны совпадать. Файлы не объединяются. Описание схемы и безопасный пример находятся в разделе «Настройка провайдеров и моделей».

Совместимость файлов профилей

Существующие файлы gpt2giga.provider-profiles.v1 остаются рабочими. Каждый алиас по-прежнему связан с одним точным маршрутом и одной моделью провайдера. Шлюз не исправляет алиасы автоматически и не пытается подобрать похожий.

Для GigaChat список models задаёт явные алиасы и модель по умолчанию, но не ограничивает полный каталог. Общий каталог всё равно возвращает все модели, которые видны выбранной учётной записи.

В схеме v1 список models обязателен. Оставьте его, если профиль должен работать с ранними предварительными сборками 0.3. Схема gpt2giga.provider-profiles.v2 поддерживает model_inventory: dynamic, поэтому в профиле GigaChat можно не перечислять все модели.

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

Проверка перед запуском

Проверьте тот же файл, с которым будет запущен сервер:

gpt2giga --config /etc/gpt2giga/providers.yaml --inspect-config

Команда использует обычный разборщик конфигурации, но не открывает порт и не обращается к провайдеру. При успехе она печатает в stdout один JSON-документ gpt2giga.inspect.v1 и завершается с кодом 0.

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

При ошибке команда печатает gpt2giga.error.v1 и возвращает код 2; логи идут в stderr. Считайте проверку неуспешной, если stdout содержит данные не в формате JSON, в details появились пользовательские данные или команда завершилась с нулевым кодом при valid != true.

API для внешней системы управления

После успешной проверки запустите тот же установленный пакет с тем же файлом профилей.

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

Предварительная проверка, /health и общая матрица не вызывают API провайдеров. Методы каталога моделей могут обновить снимок и сообщают, свежие ли данные. При кэшировании сохраняйте config_revision, inventory_revision, matrix_revision и capability_revision: после смены ревизии прежнее решение о маршруте нужно пересчитать. Подробнее — в разделе «Совместимость провайдеров».

/ready строже, чем /health. Например, причины registry_not_loaded, provider_clients_not_ready и gateway_shutting_down означают, что процесс работает, но принимать трафик ещё нельзя. Его можно оставить запущенным для диагностики до истечения отведённого на запуск времени.

Запуск рядом с управляющей системой

Для GigaLoom или другой внешней системы:

1. установите зафиксированную версию wheel-пакета в отдельное окружение, а не из соседней рабочей копии в editable-режиме;
2. сохраните файл профилей в защищённом пути и передайте секреты через защищённое окружение процесса;
3. выполните --inspect-config и продолжайте только при коде 0 и корректном очищенном JSON;
4. запустите gpt2giga --config <same-path>, не подставляя секреты в командную строку;
5. дождитесь /health, затем потребуйте /ready.ready == true до истечения заданного срока;
6. получите /bridge/models и /bridge/capabilities для выбранной модели, проверьте версии схем и ревизии, затем направьте трафик;
7. сохраняйте только ревизии и статусы без пользовательского содержимого, если отдельная политика явно не разрешает его запись.

GigaLoom управляет проектами, сессиями и процессом. gpt2giga проверяет профили, обслуживает публичные протоколы, принимает решения о маршруте и управляет клиентами провайдеров. Продукты не должны импортировать внутренние Python-модули друг друга.

Корректное завершение

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

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

Отправляйте SIGKILL только после истечения срока корректного завершения. Завершение не должно повторять запрос с другим алиасом, провайдером, аккаунтом, набором учётных данных или моделью.

Откат

Профили не изменяют состояние приложения или диалога, поэтому отдельная миграция данных для отката не нужна:

1. остановите новый трафик и корректно завершите процесс 0.3;
2. уберите путь к профилям и перезапустите 0.3 со встроенным маршрутом GigaChat либо установите зафиксированную версию 0.2.x;
3. восстановите прежние адреса клиентов и переменные окружения;
4. проверьте /health и нативный публичный маршрут, затем верните трафик.

Файлы YAML/JSON не действуют, пока не выбраны при запуске; версия 0.2.x их не читает. Удалённый или отключённый алиас после перезапуска должен вернуть unknown_model_alias, а не незаметно переключиться на другую модель. Если запуск 0.3 не прошёл проверку, достаточно исправить файл и перезапустить процесс.

После отката на 0.2.x исчезнут предварительная проверка, /ready, /bridge/models и /bridge/capabilities. Внешней системе нужно вернуться к процедуре запуска и маршрутизации, принятой для 0.2.x.