OpenAI API: проверка JSON Schema ответа

Начните с минимального контракта результата

Опишите не «всё, что когда-либо может вернуть модель», а малый объект, который реально нужен следующему шагу. Например, классификатор может вернуть category и confidence, а не произвольный текст, ссылку, идентификатор пользователя и скрытую служебную информацию. У каждого поля должны быть понятные тип, диапазон, обязательность и владелец. Такая схема делает изменение заметным: новый параметр не проскользнёт в бизнес-логику только потому, что JSON технически распарсился.

Не переносите пример из документации или старого ответа в production как вечное обещание. Возможности зависят от выбранного маршрута, версии SDK, модели и текущего контракта. Перед релизом проверьте доступный каталог и выполните синтетический staging-тест. Если функция не подтверждена, приложение должно выбрать честную ветку: ручная проверка, обычный текстовый ответ или отказ от автоматического действия, а не догадку о поведении API.

Запрещайте неизвестные поля и неявные преобразования

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

Не исправляйте спорные данные угадыванием. Преобразование «12%» в число, подстановка отсутствующего tenant или выбор первой подходящей записи способны создать неверное действие. Допустимы только детерминированные нормализации, задокументированные вашим приложением: например, trim безопасной строки до проверки длины. Для каждого автоматического преобразования нужен тест и понятная причина. Всё остальное отправляйте в локальную ветку разбора без полного prompt и без секретов.

После формы проверьте бизнес-смысл и доступ

JSON Schema отвечает на вопрос о форме, но не подтверждает, что объект относится к текущему пользователю или допустим в данном состоянии. Если ответ содержит orderId, сервер обязан проверить, что заказ существует, принадлежит текущему tenant и может быть изменён. Если поле содержит URL, проверяйте допустимый домен, формат и назначение отдельно. Модель не получает право выбирать чужой объект только потому, что назвала корректный идентификатор.

Семантическую проверку полезно разделить на независимые маленькие функции: авторизация, существование объекта, состояние, лимит и подтверждение действия. Тогда лог показывает только локальную категорию отказа и operation ID, а не весь входной ответ. Такой подход защищает также при обновлении prompt или SDK: даже если синтаксис остался прежним, изменения правил доступа и данных не будут спрятаны внутри одного parse JSON.

Сохраняйте наблюдаемость без содержимого ответа

Для расследования достаточно времени, версии схемы, версии адаптера, локального request ID, статуса проверки и безопасной категории ошибки. Не записывайте Authorization, ключ RussiaAPI, ключи поставщиков, полный ответ, полный prompt или персональные поля «на всякий случай». Если для отладки нужен пример, создайте синтетический fixture с вымышленными значениями и храните его отдельно от журнала production.

Счётчики валидации помогают отличить проблему данных от регрессии интеграции: полезны доля неизвестных ключей, несоответствий типов и отказов бизнес-правил. Но эти метрики не доказывают доступность модели, лимиты или SLA. При неожиданном всплеске остановите rollout конкретного адаптера, сохраните безопасные признаки и повторите тест после уточнения контракта. Не расширяйте схему автоматически только ради снижения числа ошибок.

Покройте негативные сценарии до выпуска

В CI добавьте fixtures с отсутствующим обязательным полем, лишним ключом, неверным типом, пустым значением, чужим tenant и устаревшим состоянием объекта. Проверка должна доказать, что приложение не совершает сетевой side effect, не выдаёт успех и не раскрывает вход в сообщении об ошибке. Такой тест не требует рабочего API-ключа и не подтверждает поддержку external endpoint; он проверяет только вашу границу доверия.

После изменения модели, маршрута, schema, middleware или SDK заново выполните staging-проверку на обезличенном сценарии. Зафиксируйте дату, версию теста и результат. Если внешняя структура стала иной, отнеситесь к ней как к неизвестной до обновления контракта и ревью. Такой rollback находится в приложении клиента; он не является обещанием автоматического переключения со стороны RussiaAPI или другого провайдера.

Пример безопасной server-side проверки

Пример ниже иллюстрирует только логику приложения. Он не делает сетевой вызов, не содержит реальных ключей и не доказывает поддержку конкретного endpoint. Проверьте актуальный договор и API-контракт перед подключением рабочего маршрута.

function parseClassification(value, viewer) {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return { ok: false };
  const keys = Object.keys(value).sort().join(',');
  if (keys !== 'category,confidence') return { ok: false };
  if (typeof value.category !== 'string' || value.category.length > 40) return { ok: false };
  if (typeof value.confidence !== 'number' || value.confidence < 0 || value.confidence > 1) return { ok: false };
  if (!viewer.canClassify) return { ok: false, reason: 'forbidden' };
  return { ok: true, category: value.category, confidence: value.confidence };
}

// This local check sends no network request and never logs response content or keys.

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

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

Контроль перед выпуском

Перед release проверьте синтетический сценарий, запреты на секреты и персональные данные в логах, роли и tenant boundary, понятное сообщение для пользователя и ручную ветку для неизвестного результата. Сохраните дату, версию адаптера и результат теста. При обновлении SDK, модели, schema или маршрута повторите проверку; не переносите выводы старого теста на новый контракт.

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

Полезные материалы

JSON Schema: документация · OWASP: Input Validation Cheat Sheet

FAQ

Достаточно ли JSON.parse для ответа модели?

Нет. JSON.parse подтверждает лишь синтаксис. После него приложению нужны проверка разрешённых полей, типов, диапазонов, бизнес-правил, tenant и прав текущего пользователя. Неизвестный или неполный объект должен попасть в безопасную ветку обработки.

Нужно ли сохранять полный ответ для отладки?

Обычно нет. Сохраняйте локальный request ID, версию схемы, время и категорию результата. Полный ответ, prompt, ключи и персональные данные увеличивают риск утечки. Для воспроизведения используйте отдельный синтетический fixture.

Доказывает ли пример поддержку structured output?

Нет. Это application-side проверка результата. Поддержка конкретного формата зависит от текущего API-контракта, выбранного маршрута, модели и версии SDK, поэтому её нужно отдельно подтвердить на staging.

Следующий шаг

Продолжите с материалами: Контрактные тесты OpenAI-compatible API · Проверка JSON перед отправкой · Проверка tool call перед действием. Затем проверьте текущие условия и безопасно протестируйте интеграцию на staging перед production-трафиком.