Руководство API Migration: безопасная смена поставщика LLM
Это руководство по миграции API описывает перенос приложения, которое уже взаимодействует с чат-эндпоинтом в стиле OpenAI, на другого поставщика. Большая часть работы заключается не в двух строках, которые вы меняете, а в поиске того, что случайно зависело от старого поставщика.
Последнее обновление

Итоги
- Для целевого API, совместимого с OpenAI, вы меняете базовый URL, ключ и идентификатор модели, а затем проверяете поведение.
- Сначала составьте перечень функций: эмбеддинги, изображения и дообучение не перейдут в текстовый API.
- Внедряйте по процентам с помощью флага, чтобы откат занял одно изменение конфигурации.
- Оцените новый счет на основе собственных подсчетов токенов перед переключением.
План из шести шагов
- Инвентаризируйте все функции API, которые вызывает ваше приложение.
- Переместите настройки поставщика в конфигурацию.
- Сопоставьте параметры и имена моделей.
- Добавьте обработку ошибок и лимитов запросов, соответствующую новым ограничениям.
- Направьте небольшую долю трафика на нового поставщика и сравните результаты.
- Проверьте стоимость, переключитесь и оставьте старый маршрут на некоторое время.
Цель в примерах — https://api.apimigration.com/v1 с идентификатором модели uncensored. Те же шаги применимы к любому провайдеру, совместимому с OpenAI, поэтому воспринимайте их как чек-лист, а не рецепт от конкретного поставщика. Если что-то сломается, статья по устранению неполадок по распространённым ошибкам интеграции LLM охватывает основные причины.
Шаг 1: Инвентаризация того, что использует ваше приложение
Ищите в коде все вызовы старого поставщика и перечислите функции, а также эндпоинты. Один вызов чата часто скрывает несколько зависимостей: системный промпт, который полагается на определенный стиль, схему инструмента, формат ответа JSON, большой контекст.
| Функция в вашем приложении | В этом API |
|---|---|
Завершения чата, /v1/responses | Поддерживается |
| Потоковая передача через SSE | Поддерживается, использование отправляется в конце |
| Вызов функций | Поддерживается, включая потоковую передачу tool_calls |
| JSON-режим | Поддерживается через response_format |
| Контекст | 100 000 токенов, промпт плюс завершение |
| Эмбеддинги, изображения, аудио, дообучение | Не предлагается, оставьте это у другого поставщика |
Если старый провайдер также обрабатывал эмбеддинги или генерацию изображений, разделите миграцию: переместите только текстовые вызовы, а остальное оставьте как есть.
Шаг 2: Вынесите настройки поставщика в конфигурацию
Жёстко заданные URL — это то, что превращает миграцию в изменение кода. Получайте базовый URL, ключ и модель из окружения, чтобы можно было переключаться без деплоя.
export LLM_BASE_URL="https://api.apimigration.com/v1"
export LLM_API_KEY="YOUR_KEY"
export LLM_MODEL="uncensored"
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ["LLM_BASE_URL"],
api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")
Аутентификация — это стандартный заголовок Authorization: Bearer, который SDK устанавливает за вас. Чтобы подтвердить ключ и узнать, что предлагает сервер, вызовите GET /v1/models.
curl https://api.apimigration.com/v1/models \
-H "Authorization: Bearer $LLM_API_KEY"Шаг 3: Сопоставьте параметры и промпты
Параметры, которые проходят через это API: temperature, top_p, stop, seed и штрафы за частоту и наличие. max_tokens является необязательным. Если ваш старый код устанавливает его для защиты от неконтролируемых расходов, сохраните его.
Три вещи заслуживают тщательной проверки.
- Поля, специфичные для поставщика. Всё, что выходит за рамки формата запроса OpenAI, может быть проигнорировано или отклонено. Отправьте один запрос с вашей точной боевой полезной нагрузкой (payload) и прочитайте ответ.
- Поведение модели. Другая модель по-разному интерпретирует один и тот же промпт. Системные промпты, настроенные под старую модель, часто требуют небольших правок. Протестируйте их, не делайте предположений.
- Отказы. Если ваши старые промпты содержали обходные пути для избежания отказов, вы обычно можете удалить их здесь, что сократит промпт.
Модель также отличается тем, на что она отвечает. Она настроена на законное использование взрослыми без отказов по контенту, а контент сексуального характера с участием несовершеннолетних блокируется.
Шаг 4: Настройте обработку ошибок под новые ограничения
Полный ключ позволяет 8 одновременных запросов и 300 в минуту. Пробный ключ позволяет 2 и 60. При превышении лимита вы получаете HTTP 429 с кодом ошибки rate_limited или concurrency. При временной перегрузке вы также получаете 429, с Retry-After: 5.
import time
from openai import RateLimitError
def chat(messages, retries=4):
for attempt in range(retries):
try:
return client.chat.completions.create(model=MODEL, messages=messages)
except RateLimitError:
time.sleep(5 * (attempt + 1))
raise RuntimeError("still rate limited after retries")
Потоковые запросы удерживают слот параллельности до завершения потока, поэтому застрявший клиент может лишить ресурсов остальных. Закрывайте потоки в блоке finally. Если ваш старый провайдер позволял больше параллельных вызовов, добавьте семафор, ограниченный новым лимитом. Неудачные запросы не оплачиваются, поэтому повторные попытки безопасны для вашего бюджета.
Шаг 5: Внедряйте по процентам
Не переключайте всё сразу. Направьте небольшую стабильную долю пользователей на нового провайдера и оставьте старый в качестве резервного. Хэширование идентификатора пользователя удерживает каждого пользователя на одной стороне, поэтому контекст не меняется посередине разговора.
import hashlib
def use_new(user_id: str, percent: int) -> bool:
bucket = int(hashlib.sha256(user_id.encode()).hexdigest(), 16) % 100
return bucket < percent
# 5 percent, then 25, 50, 100 as metrics hold
new_client = OpenAI(base_url="https://api.apimigration.com/v1", api_key=os.environ["NEW_KEY"])
old_client = OpenAI(base_url=os.environ["OLD_BASE_URL"], api_key=os.environ["OLD_KEY"])
def pick(user_id):
return new_client if use_new(user_id, int(os.environ.get("ROLLOUT_PERCENT", "0"))) else old_client
Повышайте процент только после того, как этап отработал чисто в течение примерно дня. Откат в таком случае — это просто сброс переменной окружения обратно в 0.
Что обычно удивляет команды после переключения
Смена базового URL работает с первого раза. Сюрпризы ждут вас позже.
- Смещение тона и формата. Тот же промпт даёт ответ с другим формулированием. Механизмы, которые парсят свободный текст, например регулярные выражения для префиксов «Answer:», ломаются в первую очередь. Для любых данных, которые читает программа, предпочтительнее JSON-режим или вызовы функций.
- Разное количество токенов. Каждая модель токенизирует текст по-своему. Ваша оценка стоимости на основе подсчёта токенов у старого провайдера будет неточной, поэтому пересчитайте расходы по полю
usage. - Длина вывода. Без
max_tokensгенерация может использовать оставшуюся часть контекстного окна в 100 000 токенов. Если в вашей старой настройке был лимит по умолчанию, установите его целенаправленно. - Таймауты. Таймаут вашего клиента был настроен под старого провайдера. Длинные ответы на новом могут превысить его. Используйте потоковую передачу (streaming), где это возможно, и увеличьте таймаут для запросов без потоковой передачи.
- Изменение поведения тихих отказов. Если ваш продукт раньше перехватывал сообщения об отказах и показывал запасной вариант, этот код может перестать срабатывать. Решите, хотите ли вы его и дальше.
Краткий чек-лист перед переключением
- Каждая функция в вашем перечне имеет протестированный аналог или задокументированное ограничение.
- Базовый URL, ключ и модель берутся из конфигурации в каждом сервисе, который обращается к API.
- Лимит запросов и ограничения параллельных запросов в вашем коде соответствуют новым лимитам.
- Потоки закрываются при отключении клиента.
- В логах присутствует заголовок
X-Request-Id, чтобы вы могли сослаться на запрос при обращении за помощью. - Баланс контролируется через
X-Balance-USDилиGET /v1/balance, с предупреждением, когда он начинает заканчиваться. - Старый провайдер всё ещё оплачен и настроен для отката.
- Ответственность за решение об откате несёт конкретное лицо.
Последний пункт кажется нелепым, пока не произойдёт инцидент в 2 часа ночи. Кто-то должен иметь возможность переключить флаг.
Шаг 6: Проверьте стоимость, затем переключайтесь
Рассчитайте новый счёт на основе собственного трафика. Цены составляют $0,15 за 1 млн входных токенов и $0,50 за 1 млн выходных токенов.
Пример: 10 000 запросов в день, каждый с 1 500 входными токенами и 400 выходными токенами.
- Вход: 15 000 000 токенов × $0,15 / 1 000 000 = $2,25.
- Выход: 4 000 000 токенов × $0,50 / 1 000 000 = $2,00.
- Итого: $4,25 в день.
Сравните это со старым счётом, используя текущую страницу ценообразования старого провайдера. Биллинг здесь — предоплаченный баланс без подписки, и кредит не сгорает. Пополнения от $20 до $500 целыми суммами, с бонусом 5% от $50, 10% от $100 и 15% от $200, оплачиваются криптовалютой (USDT в сети TRC20 или USDC в сети Base). Баланс отображается в заголовке ответа X-Balance-USD, поэтому вы можете настроить на него оповещение.
Новые аккаунты могут получить $0,50 пробного кредита для первых тестов. См. стоимость, затем получите API-ключ и держите документацию открытой, пока вы сопоставляете параметры.
Дополнительные руководства
Частые вопросы
Могу ли я мигрировать, изменив только базовый URL?
Для API, совместимого с OpenAI, необходимы изменения базового URL, ключа и идентификатора модели. Вам всё равно следует протестировать промпты, так как другая модель отвечает иначе.
Будут ли по-прежнему работать вызовы функций и JSON-режим?
Вызов функций и JSON-режим (response_format json_object) поддерживаются. Проверьте свои схемы с реальными промптами перед переключением.
Что если моё приложение использует эмбеддинги?
Это API работает только с текстом и не предлагает эмбеддинги, генерацию изображений или дообучение. Оставьте эти вызовы у текущего провайдера.
Как быстро откатиться?
Маршрутизируйте запросы с помощью флага среды, например процента развертывания, и сохраняйте старого клиента настроенным, пока новый маршрут не проработает чисто несколько дней.
Получите API-ключ
Зарегистрируйтесь, скопируйте ключ, обновите базовый URL. Настройка завершена.