# Изменение контракта inference API: deprecation и миграционные проверки

Как менять публичный контракт inference API: diff схемы, совместимость клиентов, смысл Deprecation и проверяемая миграция JSON и SSE fixtures.

Автор: Команда Retrivium
Обновлено: 2026-11-01
Канонический URL: https://retrivium.ai/ru/journal/provider-api-contract-deprecation-migration/
Language: ru

## Инвентаризировать наблюдаемый контракт

Публичный контракт inference API включает не только JSON поля, но и HTTP поведение, streaming-порядок, terminal states и семантику параметров. Изменение движка может затронуть этот слой даже без изменения пути endpoint. Перед выпуском сохраняют описание текущей версии и примеры клиентских сценариев. [OpenAPI 3.1.1](https://spec.openapis.org/oas/v3.1.1.html) помогает закрепить описание интерфейса, однако временные свойства SSE требуют дополнительных fixtures. Задача миграции — показать конкретный diff и последствия для потребителя. Фраза «API совместимый» без перечисления проверенных свойств не объясняет, почему старый парсер продолжит работать и какие изменения клиент должен обработать самостоятельно после обновления сервиса.

## Разобрать типы изменений

Удаление обязательного поля, смена типа и новое значение enum могут нарушить клиентов с жёсткой валидацией. Добавление поля тоже не всегда безвредно, если клиент запрещает дополнительные свойства. [Справочник объектов JSON Schema](https://json-schema.org/understanding-json-schema/reference/object) поясняет required и правила дополнительных свойств; эти настройки важны для оценки фактической совместимости. Отсутствие значения и null также различаются. Для каждого изменения записывают старый ответ, новый ответ и класс затронутых клиентов. Утверждение о совместимости должно относиться к определённой модели потребителя, а не ко всем возможным библиотекам. Семантическая смена значения при неизменном типе заслуживает такого же внимания, как заметное изменение схемы.

## Использовать Deprecation по назначению

[RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html) определяет заголовок Deprecation и способы указать связанную информацию. Само уведомление не означает немедленного изменения поведения ресурса. Его следует отделять от даты фактического отключения и от конкретных инструкций переноса. В собственной политике описывают затронутую версию, причину, замену и канал документации. Это проектирование политики сервиса, а не утверждение о наличии такой практики у OpenRouter. Дата в уведомлении без объяснения области действия мало помогает клиенту. Если меняется только один режим streaming, формулировка должна позволять понять это без предположения, что прекращается весь API или каждая модель одновременно.

## Прогнать обе стороны миграции

Небольшой корпус проверяет старый клиент со старым ответом, старый клиент с новым ответом и обновлённый клиент с обеими допустимыми формами. Для SSE отдельно проверяют добавленный кадр, изменение порядка и неизвестные поля. Fixtures содержат ожидаемые свойства, а не дословную генерацию. Диагностическая развилка начинается с места отказа: schema validation, разбор события или интерпретация terminal state. Затем определяют, нужна ли версия endpoint, период перекрытия или клиентская адаптация. Нельзя просто обновить golden-файлы и объявить миграцию успешной: это может удалить свидетельство несовместимости, ради выявления которой и запускалась проверка перед изменением публичного интерфейса.

## Сохранить решение и область проверки

Артефакт выпуска содержит diff контракта, матрицу клиентов, утверждённые исключения, миграционный пример и условия отката. Полезны [canary обновления модели](/ru/journal/model-update-canary/) и [паспорт программного стека](/ru/journal/software-stack-reproducibility/). Canary показывает поведение выбранной выборки, но не заменяет протокольную проверку редких сценариев. Успешная миграция означает прохождение перечисленных клиентов и fixtures в указанной среде. Она не даёт универсальной гарантии для неизвестных интеграций. После выпуска продолжают наблюдать ошибки разбора и распределение старых версий, не помещая идентификаторы пользователей в метрики. Это позволяет проверять последствия изменения по фактам, сохраняя понятные границы собственного обещания совместимости.