# Golden fixtures для inference API: проверять контракт, а не красивый ответ

Небольшой набор версионированных JSON и SSE fixtures для проверки inference API: обязательные поля, terminal states, приватность и правила обновления эталонов.

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

## Что считать эталоном

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

## Разделить уровни утверждений

Первый слой проверяет HTTP envelope, второй — JSON schema, третий — последовательность событий и terminal state. [OpenAPI 3.1.1](https://spec.openapis.org/oas/v3.1.1.html) позволяет зафиксировать версию описания интерфейса, но одного описания недостаточно для всех временных инвариантов потока. Например, отсутствие обязательного свойства отличается от значения null; это поясняет [справочник JSON Schema](https://json-schema.org/understanding-json-schema/reference/object). Для streaming дополнительно проверяют, что содержимое не появляется после завершения. Семантическое качество ответа выносят в отдельную оценку. Иначе ошибка модели в арифметике неожиданно блокирует выпуск прокси, хотя проверяемый контракт транспорта остался корректным.

## Собрать небольшой корпус

Начальный набор может включать обычный ответ, достижение лимита вывода, вызов инструмента, структурированный результат и контролируемый отказ до отправки заголовков. Это примеры отбора, а не обязательный перечень возможностей любого движка. Каждый fixture содержит только синтетические сообщения без персональных данных и секретов. В [обзоре API OpenRouter](https://openrouter.ai/docs/api_reference/overview) можно сверить публичные схемы, однако внешнюю схему нельзя автоматически объявить полным upstream-контрактом подключения. При сохранении ответа удаляют случайные идентификаторы по явному правилу. Полностью стирать неизвестные поля опасно: так нормализатор может скрыть именно то изменение, ради которого существует тест.

## Обновлять эталоны через diff

Артефакт корпуса включает manifest, версию схемы, хеш исходного запроса и ожидаемые утверждения. При изменении движка тест сначала показывает diff: добавленное поле, новый finish_reason, иной порядок учётных кадров. Редактор принимает изменение только после объяснения его смысла и совместимости. Команда «перезаписать все эталоны» не должна автоматически превращать новый дефект в норму. Для необязательных расширений можно задать отдельную политику допуска. Если расширение разрешено, тест всё равно сохраняет его появление в отчёте, чтобы незаметное изменение ответа не потерялось за зелёным статусом общей проверки.

## Поставить ограниченный release gate

Корпус запускают с максимальным временем, числом попыток и объёмом вывода. В отчёте фиксируют версию клиента, движка, tokenizer и список реально выполненных проверок. Неподдерживаемая функция получает явный статус, а не пропускается как успешная. Полезны [методика benchmark](/ru/journal/inference-benchmark-method/) и [воспроизводимость стека](/ru/journal/software-stack-reproducibility/). Прохождение fixtures подтверждает перечисленные свойства на этом корпусе и окружении. Оно не доказывает полную совместимость со всеми клиентами, отсутствие гонок под нагрузкой или сохранение качества модели; эти границы должны быть видны рядом с результатом, а не спрятаны в примечании к выпуску.