Подключение AI-провайдера и регистрация модели

Три уровня, которые не следует смешивать

Подключение модели в Sapphire I.C.D.S. состоит из трёх отдельных записей. Провайдер описывает внешний сервис: его устойчивый ключ, базовый URL, установленный адаптер и секрет доступа. Модель хранит идентификатор модели у этого провайдера и её технические пределы. Профиль задаёт уже рабочее поведение: системную инструкцию, бюджет контекста, объём ответа и дополнительные параметры. Такое разделение позволяет использовать одну модель в нескольких режимах, не дублировать API-ключ и не подменять реальные ограничения модели настройками отдельной задачи.

Настройка выполняется в административном разделе AI Settings. Доступ к нему должен быть выдан через Helix. Перед началом получите у провайдера актуальные значения base URL, model ID и лимитов выбранной модели, а также убедитесь, что соответствующий адаптер уже установлен в серверном контуре Sapphire. Строка в форме не устанавливает библиотеку сама по себе.

Шаг 1. Создание провайдера

Откройте раздел провайдеров и создайте новую запись. Поле Vendor key должно содержать короткий стабильный машинный идентификатор, например acme_ai. Используйте строчные латинские буквы, цифры и подчёркивание. Не включайте сюда домен, тариф, регион или версию модели: ключ связывает настройки и должен переживать обычные изменения продукта.

Display name предназначен для операторов и может быть человекочитаемым. В Base URL укажите документированный базовый HTTPS-адрес API провайдера, без пути конкретной модели и без токена в query string. Не копируйте URL из браузерной консоли и не добавляйте к нему случайный завершающий маршрут. Если поставщик предлагает разные совместимые API, используйте вариант, для которого установлен адаптер.

Vendor key должен совпадать с variant установленного провайдера, который обнаруживает штатный загрузчик платформы. Поле Provider library в текущем runtime является совместимым fallback metadata и при непустом vendor key обычно не определяет адаптер. Это не путь к файлу и не механизм установки новой библиотеки. Если нужный provider variant не установлен, передайте задачу администратору развёртывания.

В Secret name обычно оставляют принятое для данного адаптера имя секрета, а в Secret value вводят выданный API-ключ. Секрет не следует помещать в название, URL, описание, скриншот, тикет или JSON профиля. После сохранения интерфейс показывает только факт наличия секрета, а не его исходное значение. При редактировании оставьте поле значения пустым, если ключ менять не требуется; новое непустое значение означает ротацию секрета. Практичный порядок такой: сначала создать провайдера выключенным, сохранить секрет, проверить остальные поля и только затем включать запись.

Шаг 2. Регистрация модели

Перейдите в раздел моделей и выберите только что созданного провайдера. Model key должен в точности совпадать с идентификатором, который принимает API, включая дефисы, точки и суффикс версии. Это не произвольный псевдоним. Для удобного названия существует отдельное поле Display name.

Затем перенесите три ограничения из официальной карточки модели. Maximum context — полный предел контекстного окна. Maximum input — максимально допустимый вход. Maximum output — предел генерируемого ответа. Все значения задаются положительными целыми числами в токенах. Вход и выход по отдельности не могут быть больше полного контекста. Не подставляйте рекламное значение контекста, если выбранный API или тариф допускает меньше.

Tokenizer variant определяет способ оценки токенов. Укажите точный поддерживаемый вариант, если он известен. Если для нового семейства пока доступна только консервативная оценка, используйте согласованное имя такого варианта, а не название модели наугад. Поле обязательно: неверный токенизатор приводит не к косметической погрешности, а к неправильному расчёту момента компактирования и допустимого размера запроса.

Безопасный порядок включения

1. Создайте провайдера с правильным HTTPS URL и установленным адаптером.
2. Сохраните секрет и убедитесь, что в списке отображается признак его наличия.
3. Создайте модель с точным model key и подтверждёнными лимитами.
4. Создайте отдельный профиль для этой модели; без профиля рабочая политика не определена.
5. Сначала включите модель и провайдера для ограниченной проверки, затем назначайте профиль по умолчанию.

Для проверки откройте новую AI-сессию, явно выберите созданный профиль и выполните короткий запрос без инструментов, например просьбу вернуть одну строку текста. Новая сессия исключает влияние старого выбора профиля и накопленной истории. После базового ответа проверьте потоковый режим и только потом сценарии с инструментами. Доступность инструментов управляется каталогом и правами групп, а не записью провайдера или модели.

Типичные ошибки

• Ошибка авторизации: проверьте наличие секрета, его срок действия и принадлежность нужному проекту, затем ротируйте только при необходимости.
• Model not found: сравните model key посимвольно с документацией API и убедитесь, что модель разрешена аккаунту.
• Неверный маршрут: проверьте base URL, выбранный адаптер и отсутствие пути модели в базовом адресе.
• Отказ при сохранении лимитов: все три значения должны быть положительными, а input и output не должны превышать context.
• Модель не появляется в работе: провайдер, модель и профиль должны быть включены; профиль должен ссылаться на ту же пару и быть доступен текущему пользователю.

Не меняйте одновременно секрет, URL, model key и лимиты на действующем профиле. Делайте изменения по одному и фиксируйте результат проверки. Для смены поколения модели безопаснее зарегистрировать новую модель и новый профиль, проверить их отдельно, а затем переключить профиль по умолчанию. Это оставляет понятный путь возврата без подмены смысла существующих записей.

Приёмка и сопровождение

После успешного минимального запроса зафиксируйте в рабочей документации vendor key, model key, назначение профиля, источник лимитов и дату проверки. Сам секрет не записывайте. Отдельно проверьте поведение при временно выключенном провайдере: пользователь должен получить понятную ошибку, а не бесконечное ожидание. Если сервис имеет несколько регионов или тарифных маршрутов, оформляйте их как осознанные конфигурации, а не меняйте base URL во время диагностики.

Периодически пересматривайте лимиты по актуальной документации поставщика. Изменение коммерческого названия модели не всегда означает новый API-идентификатор, а новый идентификатор не гарантирует прежний tokenizer variant. Любое такое изменение проходит тот же цикл: отдельная запись, профиль, тестовая сессия, проверка ответа и только затем переключение пользователей.