Миграция SDK поставщиков
Подключите существующее приложение на OpenAI, Anthropic или Gemini SDK к AGTCloud и системно проверьте границы совместимости.
Если приложение уже использует OpenAI, Anthropic или Gemini SDK, обычно можно сохранить SDK и архитектуру, подключив клиента к одноимённому совместимому протоколу AGTCloud. Миграция — не только смена адреса: вместе проверяйте аутентификацию, ID модели, автоматическое добавление пути, поля запроса и разбор ответа.
Сохраняйте тот же протокол
OpenAI, Anthropic Messages и Gemini Generate Content — три разных протокола. Меняйте адрес сервиса внутри одного протокола; если меняете и протокол, планируйте и проверяйте полноценный рефакторинг интерфейса.
Инвентаризация перед миграцией
Сначала запишите реально используемые возможности приложения, чтобы не ограничиваться простейшим текстовым запросом.
| Проверка | Что записать |
|---|---|
| SDK | Пакет, язык, версию и синхронный или асинхронный Client |
| Протокол | Chat Completions, Responses, Messages или Generate Content |
| Модель | Текущий ID и наличие списка разрешённых моделей в коде |
| Вход | Текст, изображения, файлы, системные инструкции и историю сообщений |
| Выход | Свойства для удобного доступа к тексту, полный объект ответа и собственный разбор |
| Streaming | Типы событий, сборку приращений и условие завершения |
| Инструменты | Определения, ID вызовов, разбор аргументов и передачу результатов |
| Надёжность | Тайм-ауты, повторы, ограничения частоты, журналы и резервные стратегии |
Минимальные изменения
Для всех трёх SDK проверьте следующие настройки, но способ задания определяет SDK.
| Настройка | Действие при миграции |
|---|---|
| Адрес API | Origin или Base URL из соответствующего руководства; проверка автоматического добавления пути версии SDK |
| Ключ API | Чтение ключа AGTCloud из окружения, а не из исходников или репозитория |
| ID модели | Модель, видимая текущему ключу API и поддерживающая целевой протокол |
| Метод запроса | Сохранение метода Client исходного протокола, например chat.completions.create или messages.create |
| Чтение ответа | Проверка текста, инструментов, Usage и ошибок по AGTCloud Reference |
Миграция по SDK
OpenAI SDK вызывает Chat Completions и Responses. Base URL AGTCloud содержит /v1.
| До миграции | После миграции |
|---|---|
| Ключ API прежнего сервиса | Переменная окружения AGTCLOUD_API_KEY |
| Base URL прежнего сервиса или адрес SDK по умолчанию | https://api.agtcloud.cn/v1 |
| Прежнее название модели | MODEL_ID, видимый текущему ключу API |
| Прежний метод Chat или Responses | Тот же метод Client |
Не добавляйте /v1 повторно
https://api.agtcloud.cn/v1 уже содержит версию. Не задавайте https://api.agtcloud.cn/v1/v1 и не указывайте полный эндпоинт /chat/completions или /responses.
Установка, инициализация Client и примеры Python и TypeScript приведены в OpenAI SDK.
Когда недостаточно трёх настроек
В следующих случаях требуется изменение кода, а не только Base URL, ключа и модели:
- Переход с Chat Completions на Responses;
- Миграция между протоколами OpenAI, Anthropic и Gemini;
- Прямая зависимость от классов ответа, вспомогательных свойств или событий SDK;
- Протокольно-специфические определения инструментов и передача результатов;
- Изменение мультимодальных блоков, системных инструкций или названий ролей;
- Автоматическое добавление пути SDK, если проект передавал полный URL эндпоинта;
- Зависимость от обнаружения моделей, загрузки файлов или размещённых инструментов прежнего сервиса.
Проверка результата миграции
Проверка минимального текстового запроса
Сначала отправьте запрос без Streaming, инструментов и мультимодальности. Подтвердите ожидаемый адрес API и возможность чтения текстового ответа.
Восстановление необходимых возможностей
Последовательно восстанавливайте Streaming, инструменты, структурированный вывод, мультимодальность и состояние многошагового диалога. Добавляйте по одной возможности, чтобы проще найти различия.
Проверка неуспешных сценариев
Как минимум проверьте неверный ключ API, ID модели, тайм-аут, ограничение частоты и обрыв соединения. Приложение должно читать код статуса и ошибку и не повторять запрос бесконечно.
Сравнение результатов приложения
Не ограничивайтесь HTTP 200. Сравнивайте текст, аргументы инструментов, причины завершения, Usage, условия конца потока и Request ID в журналах.
Поэтапное переключение и откат
- Храните отдельные настройки старого и нового Provider, не разбрасывая адреса и модели по коду.
- Сначала направьте на AGTCloud трафик разработки или тестов, затем постепенно расширяйте область.
- Записывайте успешность, задержку, типы ошибок и функциональные различия каждого этапа.
- Сохраняйте прежний Provider и управляемое переключение обратно; очищайте старые настройки после подтверждения стабильности.
Не полагайтесь на молчаливое игнорирование
Совместимый интерфейс иногда принимает неизвестные поля, не выполняя соответствующие возможности. Проверяйте реальные результаты и структуру ответа: одного статуса недостаточно для подтверждения действия поля.
Следующие шаги
- Выберите руководство в Обзоре SDK;
- Прочитайте Ключ API, Base URL и аутентификация;
- Для перехода с Chat на Responses прочитайте Chat Completions → Responses;
- При ошибках статуса или запроса прочитайте Ошибки и устранение неполадок.