Матрица совместимости OpenAI API: что проверить до интеграции

Соберите строки и статусы матрицы

Разместите в строках только нужные вашему продукту возможности: базовый текстовый запрос, список моделей, streaming, структурированный ответ, tools и асинхронная задача. В столбцах укажите маршрут, model ID, SDK-версию, тестовый аккаунт, дату проверки и статус «подтверждено», «не подтверждено» или «вне scope». Не заполняйте пустую ячейку словом «да»: отсутствие теста — это отсутствие знания, а не поддержка.

Сначала спросите, какой пользовательский результат зависит от функции. Для каталога моделей проверьте чтение разрешённого списка; для streaming — начало, конец и обрыв; для tools — серверную проверку аргументов. Не переносите подтверждение между моделями или аккаунтами. Текущий каталог и доступы проекта являются источником факта, поэтому полезно связать матрицу с проверкой /v1/models.

Определите минимальные тесты

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

Все ключи остаются на сервере в окружении. Frontend вызывает собственный backend и никогда не получает Authorization header. Храните только агрегированный результат прогона, дату, версию адаптера и безопасный request ID. Полный prompt, тело ответа, cookie и ключи других поставщиков не являются частью матрицы. Такая дисциплина позволяет повторить тест после изменения SDK, не создавая новый риск данных.

Разделите формат и функциональность

OpenAI-совместимый JSON может принимать знакомые поля, но это не означает поддержку каждой функции SDK. Отдельно тестируйте допустимый model ID, параметры, stop reason, лимит, streaming и tools. Если endpoint вернул ответ на базовый запрос, не делайте вывод о JSON Schema, изображениях, stateful API или фоновой обработке. В матрице полезнее одна честная ячейка «не проверено», чем маркетинговая обещание, которое клиент не может воспроизвести.

Для function calling модельный текст и аргументы остаются недоверенным входом. Ваш сервер применяет allowlist инструментов, JSON-проверку, права пользователя и лимиты до любого вызова. Формат параметров не даёт модели разрешения выполнять действие. Обратите внимание на контрактные тесты и добавляйте новые строки матрицы только вместе с автоматическим негативным кейсом.

Пересматривайте матрицу при изменениях

Срок годности матрицы ограничен: каталог, права, SDK и продуктовый адаптер меняются. Добавьте дату проверки и назначьте пересмотр после обновления SDK, смены model ID, новой функции или заметной ошибки. Не превращайте внутреннюю таблицу в публичный SLA. Она описывает наблюдение конкретной команды на конкретной среде и не гарантирует цену, доступность, время ответа или поведение другого поставщика.

Когда ячейка перестаёт проходить, сначала отключите зависимый feature flag и вернитесь к известному рабочему сценарию. Не делайте бесконечные retry и не молча подменяйте модель без evals. Контролируемый fallback и условия остановки нужно определить отдельно; полезный контекст — canary rollout и rollback.

Server-side пример

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

const required = ['baseText', 'models'];
export function verifyCapabilityMatrix(results) {
  const checkedToday = results.filter(row => row.checkedAt === new Date().toISOString().slice(0, 10));
  const missing = required.filter(capability => !checkedToday.some(row => row.capability === capability && row.status === 'verified'));
  return {
    readyForPilot: missing.length === 0,
    missing,
    note: 'Матрица подтверждает только проверенные сценарии этого проекта.'
  };
}

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

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

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

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