Перейти к основному содержимому

Конфигурация провайдеров и каталог моделей

  • Дата: 3 августа 2026 года
  • Статус: принято для gpt2giga 0.3
  • Ответственные направления: профили провайдеров и интеграция
  • Схемы профилей: gpt2giga.provider-profiles.v1, gpt2giga.provider-profiles.v2
  • Схема контекста исполнения: gpt2giga.execution-context.v1

Контекст​

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

Решение​

Как выбирается файл конфигурации​

Шлюз принимает один файл профилей:

gpt2giga --config <path>
GPT2GIGA_CONFIG=<path> gpt2giga

Параметр --config имеет приоритет над GPT2GIGA_CONFIG. Если оба источника указывают разные пути, шлюз завершает запуск с ошибкой invalid_profile.

Без файла конфигурации gpt2giga 0.3 создаёт встроенный маршрут GigaChat из существующих переменных GIGACHAT_*. Так сохраняется привычный сценарий запуска, но другие провайдеры автоматически не включаются.

Если файл указан, только он определяет адреса провайдеров, ссылки на учётные данные, алиасы, доступность маршрутов и их политики. Тело запроса и заголовки не могут изменить эти настройки. Список моделей GigaChat по-прежнему запрашивается у провайдера, даже если в профиле заданы алиасы или модель по умолчанию.

Единый каталог моделей​

Один ModelCatalog хранит снимок, который используют:

  • публичные варианты /models;
  • GET /bridge/models;
  • проверка выбранной модели;
  • проверка её возможностей.

Для GigaChat каталог получает список через API моделей с авторизацией. Алиас из профиля задаёт точный маршрут к модели, но не ограничивает полный список, который вернул провайдер.

GIGACHAT_MODEL задаёт модель по умолчанию или явно описанную принудительную модель. Переменная не заменяет и не фильтрует каталог. Новая модель остаётся видимой, даже если её возможности пока имеют состояние unknown.

Версии схемы​

Версия 1 сохраняет прежнюю схему со статическим списком алиасов. Версия 2 добавляет динамический каталог:

schema_version: gpt2giga.provider-profiles.v2
profiles:
  - profile_id: gigachat-main
    provider_kind: gigachat
    base_url: https://api.giga.chat/v1
    credential_env: GIGACHAT_CREDENTIALS
    network_policy_ref: public-gigachat
    tls_policy_ref: system-default
    model_inventory: dynamic

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

В версии 1 и в статических профилях версии 2 нужен хотя бы один алиас. Значение model_inventory: dynamic разрешено только для одного профиля GigaChat; алиасы в нём необязательны и не фильтруют результат обнаружения моделей.

Секреты нельзя записывать в профиль открытым текстом. Значения profile_id и public_alias должны быть уникальны после проверки Unicode и пробелов. Регистр в алиасах важен: шлюз не пытается угадывать похожие имена.

Ревизия конфигурации​

После проверки профиль без секретов сериализуется в канонический JSON UTF-8: ключи объектов сортируются, лишние пробелы удаляются, порядок элементов массивов сохраняется. Ревизия имеет вид sha256:<lowercase-hex>. Загруженная конфигурация не меняется до перезапуска процесса; автоматического обновления в 0.3 нет.

Контекст исполнения gpt2giga.execution-context.v1 хранит config_revision, profile_id, public_alias, provider_kind, upstream_model, capability_profile и loss_matrix_revision. В диагностике можно показать имя переменной окружения, но не её значение, хеш значения или заголовок авторизации.

Выбор маршрута и модели​

До проверки возможностей и обращения к провайдеру шлюз выполняет цепочку:

публичная модель или алиас -> точный маршрут провайдера -> фактическая модель
                           -> ревизия каталога -> ревизия возможностей

Неизвестный, неоднозначный, отключённый или устаревший алиас не заменяется другим. То же правило действует для временно недоступной модели. /bridge/models и все варианты /models строятся из одного снимка каталога и публикуют его безопасную ревизию.

При запуске и предварительной проверке используются коды invalid_profile_schema, duplicate_profile_id, duplicate_model_alias, invalid_destination, credential_unavailable и invalid_policy_reference. Во время обработки запроса неизвестный алиас даёт unknown_model_alias. Ни одна из этих ошибок не содержит значение учётных данных.

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

  • Без файла конфигурации продолжает работать встроенный маршрут GigaChat.
  • Существующие алиасы сохраняют свои маршруты и не сужают динамический каталог GigaChat.
  • После удаления --config следующий запуск снова использует встроенный маршрут.
  • Версия 0.2.x игнорирует отдельный файл профилей; миграция данных не нужна.