РУКОВОДСТВО · ОБНОВЛЕНО 2026-09-15
OpenAI-совместимый API: что совместимо на практике
Совместимый API позволяет сохранить привычный SDK и форму основных запросов, но не гарантирует одинаковое поведение каждой модели и функции.
Для переноса обычно меняют base URL, API-ключ и model ID, затем повторно проверяют используемые endpoints и параметры. Совместимость чаще всего относится к формату Chat Completions или Responses; tools, structured output, streaming, usage, ошибки и лимиты могут отличаться.
1. Зафиксируйте контракт приложения
Перед переносом выпишите SDK, endpoint, обязательные поля, роли сообщений, формат контента и способ чтения ответа. Отдельно отметьте images, tools, JSON schema, embeddings и streaming. Это превращает обещание совместимости в конечный перечень проверок. Если приложение обращается только к chat completions, перенос проще; несколько разных API требуют отдельных адаптеров и тестов.
2. Поменяйте три точки конфигурации
Ключ не вшивают в клиентский JavaScript: сервер получает его из секретного хранилища. В конфигурации задают base URL провайдера, новый bearer token и точный model ID из каталога. Таймауты, retries и лимит ответа лучше сделать явными. Алиас latest удобен для эксперимента, а закреплённая версия делает production-поведение воспроизводимее.
3. Проверьте несовпадающие возможности
Одинаковый метод может принимать не все параметры. Проверьте tool choice, parallel tool calls, response format, seed, reasoning, изображения и системную роль. Неизвестное поле провайдер может отклонить или проигнорировать. Приложение должно читать документированный usage и finish reason, а не предполагать, что все ответы повторяют пример одного поставщика.
4. Протестируйте поток и ошибки
Для streaming убедитесь, что клиент собирает SSE-фрагменты, обрабатывает завершение и закрытие соединения. Искусственно вызовите неверный ключ, неизвестную модель, rate limit, timeout и обрыв. Retry допустим только для подходящих ошибок и с ограничением попыток. Действия с побочным эффектом снабжают idempotency, иначе повтор может создать дубликат.
5. Переносите через контролируемый rollout
Прогоните одинаковую выборку через старый и новый маршрут, сравните task success, latency, usage и стоимость. Сначала направьте малую долю неопасного трафика и сохраните возможность вернуться. В логах фиксируйте внутреннее имя задачи, provider, model id и request id без содержимого секретов. Совместимый интерфейс уменьшает стоимость миграции, но не отменяет приёмочные тесты.
Частые вопросы
Можно оставить официальный OpenAI SDK?
Да, если провайдер документирует совместимый endpoint и SDK позволяет задать base URL.
Достаточно изменить только URL?
Обычно нужны также новый ключ и model ID, после чего проверяются параметры и ответы.
Все модели поддерживают tools?
Нет, это свойство конкретного маршрута, а не общего формата API.
Почему streaming ломается после переноса?
Могут отличаться события, завершающий фрагмент, прокси-буферизация или обработка ошибок.
Как безопасно откатиться?
Держите конфигурационный adapter и проверенный старый маршрут до завершения rollout.