Как перенести приложение с OpenAI SDK на Relay
Начните перенос с отдельного экземпляра клиента: задайте ключ Relay и https://relay-llm.ru/v1, выберите доступную модель и выполните тот же короткий запрос, который используете в проверке работоспособности приложения. Перенос всей нагрузки делайте после сравнения ответов.
Найдите фактический клиент
В приложении может быть несколько объектов SDK: основной чат, фоновый обработчик и тестовый помощник. Найдите место создания каждого клиента. Изменение одной переменной не затронет объект, у которого адрес записан в коде или передан другим конфигурационным файлом.
Создайте отдельный ключ в кабинете Relay. Секреты среды разработки и рабочего сервиса не должны совпадать. Тогда тест миграции можно остановить отзывом одного ключа без вмешательства в остальные приложения.
Сверьте операцию и модель
Клиент Chat Completions отправляет messages, а Responses использует другой контракт. Не меняйте обе операции за один шаг. Идентификатор выберите в каталоге. В ответе GET https://relay-llm.ru/api/public/models найдите соответствующий public_id и проверьте protocols: для Chat Completions нужен openai_chat, для Responses нужен openai_responses. Отсутствующее поле не подтверждает совместимость.
Идентификатор старой модели нельзя переносить автоматически. Скопируйте действующий идентификатор Relay. Сходство названий не доказывает одинаковое окно контекста, поддержку инструментов или JSON-режима.
Как проверить связь за две минуты?
Три шага: список моделей, один запрос, запись в журнале. Список отдаётся без ключа, поэтому первый шаг проверяет только адрес:
curl https://relay-llm.ru/v1/modelsВторой шаг проверяет ключ и модель. Флаг -i покажет заголовки ответа:
curl -i https://relay-llm.ru/v1/chat/completions \
-H "Authorization: Bearer $RELAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Ответь одним словом: готово"}]}'Код 200 значит, что адрес, ключ, модель и обычный текстовый ответ работают. Потоки, инструменты, лимиты ключа и баланс проверяются отдельно. Значение x-request-id из заголовков найдёт запись в журнале запросов и пригодится в обращении в поддержку.
Что меняется, что остаётся и где ломается?
| Что | Что происходит | Где ломается |
|---|---|---|
| Адрес и ключ | Меняются: https://relay-llm.ru/v1 и ключ из RELAY_API_KEY | Адрес записан в коде в нескольких местах: найдите api.openai.com поиском по репозиторию |
| Формат запроса Chat Completions | Остаётся | Поля, которых модель не знает, Relay передаёт без изменений, и отказ зависит от модели |
| Идентификатор модели | Меняется на ID из каталога | 404 model_not_found при неверном ID, 403 model_not_allowed, если ключ ограничен списком моделей |
| Потоковый ответ | Остаётся, события SSE | Фрагмент usage в конце потока приходит, только если запрос просит stream_options.include_usage |
Заголовки x-ratelimit-* | Не передаются | Код адаптивного троттлинга, который их читает, получит пустое значение |
previous_response_id и background в Responses | Не поддерживаются: значение resp_… в первом и background: true дают 400 | Историю передавайте в input |
| Идемпотентность запросов | Не поддерживается | Повторная отправка создаёт новый платный запрос |
| Идентификаторы ответов | Шлюз подменяет | Не используйте их как ключи к данным у прежнего провайдера |
Проверьте поведение, которое нужно приложению
Для обычного чата сравните извлечение текста, пустой ответ и код ошибки. Для потока проверьте завершение, отмену и обрыв соединения по руководству streaming. Для tools отдельно выполните один безопасный вызов инструмента с проверкой аргументов.
Сохраните имеющиеся тесты обработки отказов. Если SDK сам повторяет запросы, проверьте его настройки: вместе с повтором на уровне приложения они могут умножить количество платных операций. Правила Relay описаны в документации ошибок.
Переключите нагрузку и оставьте способ возврата
Перед переключением убедитесь, что конфигурация содержит адрес, ключ и модель из одной среды. Изменяйте конфигурацию штатным деплоем. Не редактируйте секрет в нескольких местах вручную: при следующем запуске одно из них может вернуть старое значение.
Сначала направьте ограниченный рабочий сценарий и проверьте его статус в журнале запросов. Условия возврата к прежней конфигурации задайте заранее: повторяющиеся ошибки протокола, несовместимый формат ответа или невозможность завершить нужный инструментальный цикл.
Полная совместимость всех методов SDK из названия «OpenAI-совместимый» не следует. Перед переносом редко используемого метода откройте матрицу совместимости и руководство по переходу с OpenAI.