Миграция с OpenAI SDK на TheRouter: Base URL, Model ID и чеклист отката

Пошаговая миграция: измените две строки в OpenAI SDK, чтобы маршрутизировать запросы через TheRouter, настройте model ID mapping, fallback chains и сохраните чистый путь отката.

2026-06-09· TheRouter

Миграция с OpenAI SDK на TheRouter

Переход с OpenAI API на TheRouter требует двух изменений: base URL и API key. Ваш существующий код с OpenAI SDK — Python, TypeScript, cURL — продолжает работать, потому что TheRouter предоставляет OpenAI-compatible endpoint /v1/chat/completions. В этом guide мы разбираем точный diff, model ID mapping, fallback configuration, streaming behavior, rollback path и cost considerations.

Мы маршрутизируем OpenAI-совместимые запросы через настроенных провайдеров и поддерживаем provider/model routing и fallback там, где это реализовано в продуктовом пути. Мы предоставляем единый биллинг и учётные поверхности там, где это реализовано. Мы не заявляем нулевые простои, универсальную поддержку моделей или гарантированно самые низкие цены.

Диф кода до/после

Миграция — это замена base URL и API key. Всё остальное — message format, streaming, function calling — остаётся прежним.

Python (OpenAI SDK)

# Before: прямой вызов OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-openai-key",
    # base_url по умолчанию https://api.openai.com/v1
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

# After: через TheRouter
from openai import OpenAI

client = OpenAI(
    base_url="https://api.therouter.ai/v1",
    api_key="<THEROUTER_API_KEY>",
)

response = client.chat.completions.create(
    model="openai/gpt-4o",  # формат provider/model
    messages=[{"role": "user", "content": "Hello"}],
)

TypeScript (OpenAI SDK)

// Before: прямой вызов OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-openai-key',
});

// After: через TheRouter
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.therouter.ai/v1',
  apiKey: '<THEROUTER_API_KEY>',
});

Environment variables

Если приложение читает OPENAI_BASE_URL и OPENAI_API_KEY из environment, миграция — это zero code changes:

# Before
export OPENAI_API_KEY="sk-your-openai-key"
# OPENAI_BASE_URL по умолчанию https://api.openai.com/v1

# After
export OPENAI_BASE_URL="https://api.therouter.ai/v1"
export OPENAI_API_KEY="<THEROUTER_API_KEY>"

OpenAI Python SDK автоматически читает OPENAI_BASE_URL, если base_url не передан в constructor. Source: OpenAI Python SDK, OpenAI API reference, retrieved 2026-06-09.

cURL

# Before
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-openai-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

# After
curl https://api.therouter.ai/v1/chat/completions \
  -H "Authorization: Bearer <THEROUTER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Маппинг Model ID

TheRouter использует формат provider/model-name. При миграции с OpenAI добавьте prefix openai/ к model ID. Для routing на другого provider используйте его prefix.

OpenAI model ID	TheRouter model ID	Примечания
`gpt-4o`	`openai/gpt-4o`	Та же model, routing через TheRouter
`gpt-4o-mini`	`openai/gpt-4o-mini`	Та же model, routing через TheRouter
`gpt-4o`	`anthropic/claude-sonnet-4.5`	Другой provider, тот же request shape
`gpt-4o`	`deepseek/deepseek-v4-flash`	Routing на DeepSeek

Все доступные models на странице Models. Для provider-specific setup смотрите guides по SiliconFlow, DeepSeek и Alibaba Cloud Model Studio.

Ключевой момент: после миграции вы не привязаны к OpenAI models. Один base_url и api_key дают доступ к models от нескольких providers через single endpoint.

Fallback без обещания zero downtime

TheRouter поддерживает model fallback chains. Передайте models array вместо одного model — TheRouter пробует первую model, а при failure (downtime, rate limits, moderation refusal) автоматически переходит к следующей. Source: TheRouter Model Fallbacks, retrieved 2026-06-09.

import requests

response = requests.post(
    "https://api.therouter.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer <THEROUTER_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "models": [
            "openai/gpt-4o",
            "anthropic/claude-sonnet-4.5",
            "deepseek/deepseek-v4-flash",
        ],
        "messages": [{"role": "user", "content": "Суммируй этот документ."}],
    },
)

С OpenAI SDK: оставьте primary model и передайте fallback через extra_body:

const completion = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  extra_body: {
    models: ['anthropic/claude-sonnet-4.5', 'deepseek/deepseek-v4-flash'],
  },
  messages: [{ role: 'user', content: 'Суммируй этот документ.' }],
});

Fallback не гарантирует zero downtime. Если все models в chain недоступны, request fails. Стройте error handling соответственно. Подробнее о fallback patterns, retries и cost guardrails — в нашем LLM API Fallback Routing Guide.

Streaming и response field behavior

Streaming работает идентично. Добавьте stream=True (Python) или stream: true (TypeScript) — TheRouter forward Server-Sent Events от upstream provider.

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Расскажи историю"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content or ""
    print(content, end="")

Что нужно учитывать в response fields:

Поле model в response показывает model, которая фактически обработала request. При fallback оно отличается от запрошенной model.
Provider-specific response fields (например, system_fingerprint от OpenAI) сохраняются только если upstream provider их возвращает. Не полагайтесь на их наличие при routing через разные models.
Token usage fields (usage.prompt_tokens, usage.completion_tokens) транслируются от upstream provider. Разные providers могут считать tokens по-разному для одного и того же input.

Путь отката

Откат на прямой OpenAI — обратная операция: верните оригинальный base_url (или удалите его для default) и восстановите OpenAI API key.

Чеклист отката

Верните environment variables:

export OPENAI_BASE_URL="https://api.openai.com/v1"  # или unset
export OPENAI_API_KEY="sk-your-openai-key"

Верните model IDs: Измените openai/gpt-4o обратно на gpt-4o. Уберите provider prefixes.
Удалите fallback arrays: Замените models: [...] на один model. Удалите extra_body.models.
Проверьте TheRouter-specific fields: Если вы добавляли provider.order, provider.allow_fallbacks или другие TheRouter-specific request fields — удалите их. OpenAI отклонит unknown fields.
Убедитесь, что OpenAI API key активен. Если вы rotated или revoked его во время миграции, создайте новый на platform.openai.com/api-keys.
Запустите tests. Проверьте, что response format и latency соответствуют ожиданиям.

Rollback безопасен, потому что миграция затрагивает только transport layer. Prompts, message history и application logic не изменены.

Соображения по стоимости

TheRouter применяет собственное pricing поверх upstream provider costs. Общая стоимость request зависит от provider и model, которые фактически обслужили request.

Что меняется:

Вы платите по тарифам TheRouter, а не по прямым тарифам provider. Актуальные тарифы — на TheRouter pricing.
Fallback chains могут routing на более дорогие models. Request, который fallback с дешёвой model на дорогую, стоит больше прямого вызова дешёвой model.
Unified billing — один invoice вместо отдельных accounts у каждого provider.

Что не меняется:

Token counting определяется upstream model, не routing layer.
Длина prompt и completion остаётся прежней.

Мы не утверждаем, что guaranteed cheapest. Сравните тарифы TheRouter с вашими текущими direct-provider costs перед переводом production traffic. При высокой cost sensitivity рекомендуем запускать оба пути параллельно в trial period.

Чеклист миграции

Используйте этот чеклист для отслеживания миграции:

FAQ

Нужно менять версию OpenAI SDK?

Нет. TheRouter работает со стандартным OpenAI SDK. Меняются только base_url и api_key. Source: TheRouter Quickstart, retrieved 2026-06-09.

Работает ли TheRouter с tools, которые принимают custom base URL?

Да. Coding tools вроде Cursor, Claude Code и OpenCode, поддерживающие custom OpenAI-compatible base URL, могут pointing на TheRouter. Конкретные конфигурации — в Coding Tools Setup.

Что произойдёт, если TheRouter недоступен?

Запросы завершатся ошибкой. TheRouter не обещает нулевые простои. Держите прямые учётные данные провайдера готовыми для отката. Рекомендуем проверять работоспособность endpoint TheRouter перед маршрутизацией production-трафика.

Можно мигрировать постепенно?

Да. Route часть traffic через TheRouter, остальное — напрямую в OpenAI. Сравнивайте error rates, latency и costs. Увеличивайте долю, когда уверены в routing layer.

TheRouter поддерживает все OpenAI models?

TheRouter поддерживает models, перечисленные на странице Models. Не каждая OpenAI model может быть доступна. Проверяйте models page перед миграцией workloads, зависящих от конкретных models.

Где узнать больше о доступных providers?

Смотрите наши provider guides: OpenAI-compatible API providers, Chinese OpenAI-compatible APIs, SiliconFlow guide, DeepSeek guide и Alibaba Cloud Bailian guide.