РУКОВОДСТВО · ОБНОВЛЕНО 2026-10-19
Как менять JSON-схему ответа LLM без поломки приложения
План изменения контракта между моделью, валидатором и потребителем результата.
Схема ответа LLM — это контракт нескольких компонентов: запроса к модели, валидатора и кода, который использует результат. При изменении поля обновляйте их согласованно и сохраняйте версию контракта рядом с ответом. Корректный JSON по новой схеме может оказаться несовместимым со старым обработчиком. Например, переход от одной категории к списку категорий меняет не только тип, но и бизнес-логику. До выпуска проверьте сохранённые ответы, фоновые задания и возможность возврата к прежнему контракту.
1. Опишите изменение на примерах
Запишите старый и новый объект рядом с ожидаемым действием потребителя. Если раньше status означал успешность извлечения, не используйте его в новой версии для состояния заказа без явной миграции. Перечислите клиентов и задачи, которые читают результат: интерфейс, экспорт, очередь и повторная обработка истории. Для каждой пары определите допустимую версию схемы. Не рассчитывайте, что добавление поля всегда безопасно: потребитель может отклонять неизвестные ключи или проверять объект целиком.
2. Задайте явную валидацию
В JSON Schema свойства описываются отдельно от списка required; запрет дополнительных свойств тоже задаётся явно. Отсутствующее поле и поле со значением null не тождественны. В приложении определите значение каждого состояния и проверяйте его до выполнения действия. Возможности строгого структурированного вывода зависят от выбранной модели и поддерживаемого подмножества схемы. Поэтому локальная валидность полной схемы ещё не подтверждает, что API примет её в текущем маршруте.
3. Разделите переход и постоянный контракт
При необходимости используйте временный адаптер старого ответа в новую внутреннюю структуру. Он должен быть детерминированным, с понятными правилами и ошибкой при потере смысла. Не заменяйте отсутствующее решение модели выдуманной категорией ради прохождения проверки. Сохраняйте исходный объект вместе с версией и результатом преобразования, соблюдая правила хранения данных. Ограничьте срок поддержки переходного формата, чтобы старые ветви не оставались незаметно в приложении годами.
4. Проверьте выпуск и возврат
Соберите контрольный набор: старый ответ, новый ответ, неизвестный ключ, отсутствующее обязательное поле, null и неожиданный вариант enum. Добавьте ответы из задач, которые ещё стоят в очереди, и повторно открытые сохранённые записи. Сначала проверьте валидатор и потребителя без платного обращения к модели. При интеграционной приёмке отдельно оцените качество содержимого. План возврата должен объяснять, сможет ли прежний код прочитать данные, которые новая версия уже успела сохранить.
Частые вопросы
Можно ли менять схему без смены модели?
Да. Это отдельный контракт приложения. Поэтому сохраняйте обе версии независимо и проверяйте их сочетание на контрольных примерах.
Добавить optional-поле всегда безопасно?
Нет. Это зависит от валидатора и потребителей. Строгий обработчик дополнительных свойств может отклонить новый объект, даже если поле необязательное.
Нужно ли разрешать null для всех полей?
Нет. Используйте null только с определённым смыслом. Для неизвестного значения и неприменимого поля могут понадобиться разные состояния, если от них зависит действие.
Достаточно ли одного ответа новой модели?
Нет. Проверьте варианты ошибок, сохранённые объекты и незавершённые задачи. Один успешный пример не доказывает совместимость всей обработки.