Миграция с Chat Completions на Responses API: план проверки

Опишите проверяемый scope

Составьте короткую карточку миграции: прежний маршрут, целевой маршрут, версия SDK, разрешённый model ID, обязательные поля, ожидаемый формат ответа и нормализованные ошибки. Отдельно пометьте функции вне scope: фоновые операции, изображения, tool calls, JSON Schema и сохранённое состояние. Такая карточка превращает расплывчатое «совместимо» в набор проверяемых допущений и позволяет честно остановить rollout, если хотя бы одно обязательное утверждение не подтверждено.

Не переносите клиентский ключ в браузер ради быстрого эксперимента. Backend принимает пользовательский запрос, применяет собственные лимиты и только затем вызывает разрешённый маршрут с RUSSIAAPI_API_KEY из окружения. Это даёт одну точку для аутентификации, аудита и controlled rollback. До теста сверяйте текущий каталог и права проекта в консоли: доступный сегодня model ID нельзя выводить из старого примера или чужого аккаунта.

Сравните контракт, а не названия полей

Для каждого тестового сценария фиксируйте вход, допустимый выход и действие при отклонении. Сравнивайте не литературный текст модели, а наблюдаемые свойства: HTTP-класс, наличие идентификатора ответа, тип текстового блока, обработку пустого результата и безопасный код ошибки. Модельный ответ может меняться даже при неизменном контракте; поэтому точное совпадение строк — плохой регрессионный критерий.

Streaming тестируйте отдельно. Клиенту важно знать, как распознать начало, частичные данные, завершение и обрыв; шлюз не обязан поддерживать ту же последовательность событий, что другой поставщик. Укажите deadline, максимальный размер буфера и правило для неполного результата. Если поток оборвался, не показывайте «готово» и не запускайте повтор автоматически. Практика отмены и cleanup описана в руководстве по SSE-отмене.

Запустите тесты на небольшой выборке

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

Полезно разделить smoke test и contract test. Smoke test подтверждает, что выбранный маршрут отвечает в текущей среде. Contract test проверяет только обещанный вашему приложению набор полей и ошибок. Если функция не подтверждена, отметьте её как «не проверена», а не как «поддерживается». Связанный шаблон проверок есть в статье о контрактных тестах.

Переключайте трафик с обратимым планом

Новый адаптер включайте feature flag для небольшой внутренней доли и только для сценариев, прошедших тесты. Сохраняйте агрегированную долю ошибок, latency и безопасный request ID, но не содержимое запросов. Заранее задайте rollback-условия: рост нормализованных ошибок, отсутствие обязательного поля, неизвестный формат stream или превышение собственного бюджета. Rollback означает возврат маршрутизации приложения, а не попытку обойти ограничение или повторить неизвестную операцию.

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

Server-side пример

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

export async function smokeResponses(input) {
  if (!process.env.RUSSIAAPI_API_KEY || typeof input !== 'string') throw new Error('invalid_input');
  const response = await fetch('https://russiaapi.com/v1/responses', {
    method: 'POST',
    headers: { authorization: `Bearer ${process.env.RUSSIAAPI_API_KEY}`, 'content-type': 'application/json' },
    body: JSON.stringify({ model: process.env.RUSSIAAPI_TEST_MODEL, input }),
    signal: AbortSignal.timeout(15_000)
  });
  if (!response.ok) return { ok: false, status: response.status };
  const data = await response.json();
  return { ok: true, hasId: typeof data.id === 'string', outputType: typeof data.output };
}

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

Что фиксировать в рабочем контуре

Перед изменением назначьте владельца, внутренний идентификатор операции, версию адаптера, разрешённый модельный ID и критерий успеха. В безопасный журнал обычно достаточно записать время, HTTP-класс, нормализованный код, latency и request ID, если он предоставлен. Не записывайте Authorization, полный prompt, ответ пользователя, временные URL или экспорт заголовков. Эти данные редко нужны для базовой диагностики и повышают риск утечки.

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