Canary rollout модели AI API: как сменить модель без резкого риска

Почему model ID нельзя менять одним коммитом

Одинаковый endpoint не делает две модели взаимозаменяемыми. Одна может по-другому обрабатывать системное сообщение, возвращать невалидный JSON, иначе выбирать инструмент или требовать меньшего контекста. Для видео меняются асинхронные статусы и поддерживаемые параметры. Нельзя заранее обещать, что новая модель будет быстрее, дешевле или доступна постоянно: это определяется текущим каталогом, договором, правилами и вашим измерением, а не названием модели в статье.

Полная подмена особенно опасна, когда downstream выполняет действие на основе ответа. Вначале убедитесь, что сервер валидирует JSON, аргументы tools и права независимо от модели. Сохраните прежнюю рабочую конфигурацию с датой проверки, а новую заведите как отдельную версию. Тогда rollback — это осознанное переключение feature flag, а не спешный поиск model ID в production во время инцидента.

Соберите контрактный набор до трафика

Набор должен представлять реальные классы задач, но не содержать секреты, персональные данные, запрещённые документы или чужой контент. Включите короткий диалог, длинный допустимый контекст, строгий JSON, безопасный отказ, timeout и сценарий с tool calling, если он используется. Для каждой задачи опишите ожидаемую форму результата и серверное правило проверки, а не один «правильный» текст. Оценка качества может быть ручной, автоматической или смешанной, но критерии нужно зафиксировать до сравнения.

Отдельно проверьте негативные случаи: неверный model ID, 429, 5xx, сетевой timeout и отмену клиентом. Эти сценарии не должны создавать дубли или переключать пользователя на непроверенную модель. Используйте собственный ключ только на сервере и журналируйте request ID, версию конфигурации, класс ответа и агрегированные метрики. Полный prompt и Authorization не нужны, чтобы понять, какая версия дала регрессию. Основы контрактного теста описаны в руководстве по тестированию совместимого API.

Определите явные условия canary

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

До запуска назначьте окна наблюдения и пороги: например, увеличение доли ошибок относительно базовой версии, нарушение JSON-валидации, рост отмен или выход за ваш внутренний бюджет. Это не публичный SLA и не универсальные числа; конкретные границы выбирает команда по задаче. Если порог сработал, canary останавливается, новые запросы возвращаются к предыдущей разрешённой версии, а существующие асинхронные задачи завершаются по сохранённой конфигурации.

Пример выбора версии через feature flag

Пример Node.js показывает принцип: приложение выбирает только ID из allowlist, закрепляет версию за пользователем и сохраняет неопасную метку конфигурации. Проценты, model ID и хранение закрепления — лишь шаблон и должны быть подтверждены вашим каталогом и продуктовым решением. Не переносите этот код в клиент и не используйте выбор версии как способ обойти правила поставщика.

const stable = process.env.RUSSIAAPI_STABLE_MODEL;
const canary = process.env.RUSSIAAPI_CANARY_MODEL;
const allowed = new Set([stable, canary]);

export function chooseModel(userId, rolloutPercent = 5) {
  const bucket = stableHash(userId) % 100;
  const selected = bucket < rolloutPercent ? canary : stable;
  if (!allowed.has(selected)) throw new Error('unapproved_model_config');
  return { model: selected, configVersion: selected === canary ? 'canary-v1' : 'stable-v1' };
}

// Persist configVersion with every long-running job; do not switch it mid-task.
// Verify both IDs against the current RussiaAPI catalog before enabling rollout.

При ошибке не меняйте модель на лету без анализа. Разделите ошибки клиента, лимиты и временные сбои: 400/422 требуют исправления payload, 401/403 — проверки собственной конфигурации, 429 — очереди и ограниченного ожидания. Fallback допустим лишь к заранее разрешённой и протестированной модели. Подробные границы собраны в материале о status page и fallback.

Измеряйте продукт, а не только HTTP 200

Успешный HTTP-статус не доказывает, что функция полезна. Смотрите на долю валидного структурированного результата, процент серверных отказов, длину и стоимость успешной операции, время до ответа, отмены пользователя и безопасную выборочную оценку качества. Сравнивайте одинаковые типы задач и одинаковое окно времени. Если новая модель экономит токены, но чаще требует повторной обработки, считайте стоимость успешной задачи, а не цену одного запроса.

Не отправляйте сырой контент в систему наблюдаемости ради удобства сравнения. Достаточно версии конфигурации, агрегированного класса задачи, размера и безопасного внутреннего ID. Если для оценки всё же нужен образец, согласуйте основание, доступ, минимальный объём и срок хранения. Для финансового среза используйте контроль стоимости AI API; для таймаутов — политику deadline и отмены.

Rollback должен быть подготовлен заранее

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

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

Чек-лист canary-выпуска

1. Новая и предыдущая конфигурации существуют отдельно, model ID подтверждены текущим каталогом.
2. Контрактный набор не содержит чувствительных данных и проверяет форму ответа, ошибки и отмену.
3. Feature flag закрепляет пользователя за версией и начинается с малой контролируемой доли.
4. Есть продуктовые метрики, окно наблюдения, внутренние пороги и владелец решения.
5. Rollback возвращает только новые подходящие запросы к предыдущей версии и не меняет чужие задачи.

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