Allowlist моделей в OpenAI-совместимом API

Короткий ответ и граница сценария

Allowlist моделей в OpenAI-совместимом API — это правило вашего backend, которое разрешает только проверенные model ID для конкретного окружения и tenant. Такой список уменьшает случайные изменения маршрута, но не обещает доступность модели: перед релизом приложение всё равно сверяет актуальный каталог, контракт и права.

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

Практический план

Эта инструкция предназначена для backend-разработчиков и владельцев AI-функций, которые переводят интеграцию из тестового режима в production. Начните с инвентаря: какие сценарии действительно нужны продукту, какие model ID были проверены на synthetic fixtures, кто утверждает смену и как быстро выключить новый маршрут. Не переносите весь каталог в клиент и не принимайте model ID из браузера без server-side проверки.

Храните allowlist отдельно для development, staging и production. В development допустим небольшой набор экспериментальных записей, но production должен содержать только версии, прошедшие контрактный тест. Для каждой записи фиксируйте дату проверки, назначение, тестовый набор и владельца. Если каталог вернул неизвестный ID или доступ изменился, безопасное действие — остановить вызов с понятной ошибкой, а не выбрать похожее имя автоматически.

Перед rollout выполните минимальный smoke test с собственным ключом RussiaAPI, синтетическим текстом и лимитом времени приложения. Проверьте, что выбранная модель есть в текущем каталоге, запрос возвращает ожидаемую форму, а ошибки имеют безопасный request ID. Нельзя считать такой тест гарантией будущей доступности, цены или совместимости SDK: это наблюдение для вашей конфигурации на дату запуска.

Изменяйте список через review и feature flag. Сначала включите новую запись для отдельного synthetic tenant либо малого сегмента, отслеживайте классы ошибок и ручные проверки, затем расширяйте трафик. Держите предыдущий список и условия остановки рядом с изменением. В техническом журнале достаточно версии policy, обезличенного tenant, model alias, статуса и request ID; не сохраняйте Authorization, полный prompt или ответ модели. Добавьте отдельную проверку для удаления модели: она должна вернуть управляемый отказ, зафиксировать причину и не переключить пользователя на неподтверждённый маршрут.

Server-side граница и данные

Клиент передаёт только необходимый для продукта ввод. Backend получает tenant и права из своей сессии, применяет allowlist полей, формирует минимальный вызов и проверяет результат как недоверенные данные. Секрет RussiaAPI хранится только в окружении или защищённом server-side secret store.

Не записывайте ключи, cookies, Authorization, полный текст prompt, полный ответ модели, файлы или временные ссылки в обычную телеметрию. Для поддержки обычно достаточно request ID, версии адаптера, класса результата, времени и обезличенного идентификатора tenant. Политику хранения и доступ к журналам определяет ваша организация.

Наблюдаемость и доказательства

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

Разделяйте факт, предположение и действие. Фактом является проверенный ответ конкретного теста и его request ID; предположением — причина отклонения; действием — ограничение трафика, откат или задача на проверку. Это помогает не превращать временную ошибку, неизвестный контракт или отсутствие данных в неподтверждённое обещание пользователю.

Проверка и обратимый rollout

Проверьте позитивный и негативный набор на synthetic test tenant: корректный сценарий, пустой ввод, неизвестный параметр, отсутствие прав, timeout и отмену. Фиксируйте дату, версию правила и ожидаемое безопасное действие. Тест показывает только поведение вашего сценария на момент проверки, а не постоянную характеристику модели или сети.

Включайте изменение на ограниченном сегменте через server-side feature flag. До rollout определите метрики, порог остановки и предыдущий проверенный путь. При аномалии выключите новый маршрут, сохраните минимальную техническую трассу и разберите причину без расширения логов пользовательским содержимым. Техническая проверка не отменяет ответственность за данные, пользовательские уведомления и допустимый сценарий.

Server-side пример

Пример показывает локальную защиту приложения. Ключи берутся только из окружения; перед запуском подтвердите маршрут, model ID и параметры в актуальном каталоге RussiaAPI.

export function resolveProductionModel({ requested, environment, policy, catalog }) {
  const allowed = policy[environment] ?? new Set();
  if (!allowed.has(requested)) throw new Error('model_not_allowed');
  if (!catalog.has(requested)) throw new Error('model_not_in_current_catalog');
  return requested;
}
// policy and catalog are server-side inputs. Verify live endpoint shape separately.

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