К содержимому
Блог

Как перенести приложение с OpenAI SDK на Relay

Как перенести приложение с 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-режима.

Как проверить связь за две минуты?

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

bash
curl https://relay-llm.ru/v1/models

Второй шаг проверяет ключ и модель. Флаг -i покажет заголовки ответа:

bash
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.

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.