Миграция Chat Completions на Responses: безопасный smoke test

Определите один сценарий и стоп-условие

Начните с короткого, обезличенного сценария без инструментов и побочных эффектов: например, пользователь задаёт тестовый вопрос, а сервер возвращает текст с ограниченной длиной. В карточке smoke test зафиксируйте вход, разрешённый model ID из текущего каталога, ожидаемый внутренний результат и владельца решения. Не называйте этот набор универсальным: он проверяет только наблюдаемый маршрут в конкретном окружении. До вызова договоритесь о стоп-условиях. Отсутствующее обязательное поле, новый тип события, ошибка валидации или рост timeout должны останавливать rollout. Без такой границы команда легко принимает единичный успешный ответ за подтверждение совместимости и обнаруживает проблему уже на реальном трафике.

Разделите сетевой адаптер и бизнес-логику

Переход легче контролировать, когда API-ответ не попадает сразу в интерфейс или платежный процесс. Сделайте маленький server-side адаптер: он отправляет разрешённый запрос, проверяет тип и размер полученного значения, затем возвращает приложению стабильный внутренний объект. Лишнее поле, пустой идентификатор или неожиданный массив должны стать contract_error, а не неявной подстановкой. Так можно отдельно тестировать миграционный слой и не менять всю бизнес-логику. Ключ берётся только из защищённой переменной окружения, например RUSSIAAPI_API_KEY; браузер получает лишь безопасный статус вашей операции. В журнале достаточно request ID, версии адаптера, класса ошибки и длительности, но не нужно сохранять Authorization, полный prompt или ответ целиком.

Сверьте SDK и fixture до сетевого вызова

Зафиксируйте версию SDK и минимальный fixture в репозитории. Fixture содержит синтетический вход и ожидаемую схему после нормализации, а не данные клиента. При обновлении сравнивайте сериализацию, обязательные поля, лимит размера и обработку null. Проверяйте также, что base URL берётся из конфигурации окружения, а не из пользовательского параметра. Это уменьшает риск случайно направить часть запросов на неизвестный адрес. Если ваш прежний Chat Completions слой добавлял системное сообщение или собственную проверку JSON, не переносите поведение на глаз: опишите его отдельным тестом. Задача smoke test — показать, что разрешённый контракт сохранён, а не доказать одинаковость всех возможностей, моделей, цен или ограничений.

Проверьте streaming как отдельный контракт

Поток нельзя считать обычным текстовым ответом, разбитым на части. Отдельный тест должен покрыть пустой первый фрагмент, отмену клиентом, закрытие соединения, повтор фрагмента и превышение времени ожидания. Сервер собирает результат только в пределах установленного размера и не пишет сырые части в лог. Если событие не соответствует ожидаемой схеме, интерфейс показывает нейтральное состояние, а приложение помечает запрос для review. Не пытайтесь автоматически продолжить незавершённый поток новым вызовом без понятной идемпотентности: так появляются дубли и двойные расходы. Проверьте, что пользователь может отменить локальное ожидание, а оператор видит собственный request ID. Внешний формат событий, доступность и задержка всегда требуют отдельной сверки с актуальным контрактом.

Соберите отрицательные тесты и классификацию ошибок

Полезный smoke test обязан доказывать безопасный отказ. Включите отсутствующую конфигурацию, неизвестный model ID, некорректный JSON, 401 или 403, rate limit, timeout и ответ с неожиданным полем. Для каждой группы заранее выберите действие: ошибка схемы и прав требует review; временный сетевой сбой допускает ограниченный retry только для идемпотентной операции; rate limit показывает пользователю честную паузу. Не повторяйте циклом все 4xx и не скрывайте ошибку пустым успешным сообщением. Карта ошибок делает поддержку предсказуемой и помогает не смешивать проблему приложения с возможным изменением внешнего маршрута. Для диагностики храните минимальные технические признаки, а не пользовательские тексты или секреты.

Выпустите изменение малой долей и подготовьте rollback

После локального и CI smoke test включите новый адаптер для внутреннего проекта либо малой разрешённой группы. Наблюдайте долю valid_response, contract_error, timeout, отмен и ручных review; сравнивайте их с прежним маршрутом на одинаковом синтетическом наборе. Назначьте владельца rollback до запуска, храните предыдущее значение конфигурации и ограничьте время эксперимента. При новом обязательном поле или заметном росте ошибок остановите расширение, верните прежний адаптер и изучите fixture. Не переключайте маршрут по содержанию ответа модели и не передавайте чувствительные данные в запасной путь без отдельной policy. Успехом считается обратимое, измеримое изменение, а не рекламное утверждение о полной совместимости.

Server-side пример

Пример рассчитан на Node.js 18+ и защищённый server-side запуск. В нём нет реального ключа: это логика приложения, а не текущая спецификация внешнего API. До интеграции подтвердите маршрут, схему и ограничения в документации.

export function normalizeMigrationResponse(payload) {
  if (!payload || typeof payload !== 'object') return { ok: false, reason: 'invalid_payload' };
  if (typeof payload.id !== 'string') return { ok: false, reason: 'missing_id' };
  const text = typeof payload.output_text === 'string' ? payload.output_text : '';
  if (text.length > 8000) return { ok: false, reason: 'response_too_large' };
  return { ok: true, value: { requestId: payload.id, text } };
}
// Server-side adapter only; load RUSSIAAPI_API_KEY from protected configuration.

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

Граница ответственности и данных

Это инженерное руководство для вашего приложения, а не описание гарантированной функции внешнего поставщика. Не помещайте в браузер, тикет, статью или журнал API-ключи, заголовок Authorization, cookie, ключи поставщиков, полный prompt или персональные данные. Для регулируемых данных, договорных условий и прав на контент проверяйте применимые требования с ответственным специалистом.

Материалы для сверки

Внешние источники объясняют общие инженерные принципы. Они не подтверждают функции, тарифы, доступность или SLA RussiaAPI и сторонних моделей.

• OpenAI: справочник Responses API
• OWASP: риски LLM-приложений