Миграция с OpenAI на RouteAPI

Это руководство поможет вам перенести существующие приложения OpenAI на RouteAPI. В большинстве случаев вам нужно изменить только базовый URL и ключ API, остальной код остается без изменений.

Почему стоит перейти на RouteAPI

RouteAPI предоставляет расширенные возможности при сохранении совместимости с OpenAI:

• Единый доступ к нескольким провайдерам - Используйте Claude, Gemini, Azure, AWS Bedrock и другие модели в дополнение к OpenAI без изменения кода
• Управление затратами и контроль бюджета - Централизованное управление использованием и квотами для нескольких моделей для предотвращения перерасхода
• Улучшенная наблюдаемость - Унифицированные журналы запросов, статистика использования и мониторинг производительности
• Высокая доступность и балансировка нагрузки - Автоматическое переключение при сбоях и распределение нагрузки по нескольким каналам
• Гибкие разрешения и квоты - Создавайте независимые токены и лимиты для разных команд, проектов или сред

Оценка сложности миграции

Сценарий	Требуемые изменения	Примерное время
Использование SDK OpenAI (Python/Node.js)	Изменение только конфигурации инициализации (2 строки)	< 5 минут
Использование фреймворков типа LangChain/LiteLLM	Изменение параметров конфигурации	< 10 минут
Использование клиентов типа Cursor/Claude Code	Обновление базового URL и ключа в настройках	< 5 минут
Прямые HTTP-запросы	Изменение URL запроса и заголовка аутентификации	< 10 минут

Основные изменения конфигурации

Основные шаги миграции включают изменение двух элементов конфигурации:

1. Изменение базового URL

Замените базовый URL OpenAI на RouteAPI:

# Исходный URL OpenAI
https://api.openai.com/v1

# URL RouteAPI
https://api.routeapi.ai/v1

2. Замена ключа API

Используйте токен RouteAPI вместо ключа API OpenAI:

1. Войдите в консоль RouteAPI
2. Создайте новый токен на странице API Keys
3. Скопируйте и сохраните токен (формат: sk-...)

3. Управление переменными окружения

Рекомендуется управлять учетными данными с помощью переменных окружения:

# Файл .env
ROUTEAPI_KEY=sk-your-routeapi-token

Совет по безопасности: Не коммитьте токены в систему контроля версий. Используйте .gitignore для исключения файлов .env.

Миграция Python SDK

SDK OpenAI

Измените только параметры base_url и api_key:

# До миграции - OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-proj-...",  # Ключ OpenAI
)

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

# После миграции - RouteAPI
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],  # Используйте токен RouteAPI
    base_url="https://api.routeapi.ai/v1",  # Укажите на RouteAPI
)

response = client.chat.completions.create(
    model="gpt-4",  # Или используйте другие модели, например claude-3-5-sonnet-20241022
    messages=[{"role": "user", "content": "Hello"}],
)

Изменения:

• Добавление параметра base_url
• Замена api_key, предпочтительно из переменной окружения
• Опционально: изменение model на другие модели, поддерживаемые RouteAPI

Конфигурация LangChain

# До миграции
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key="sk-proj-...",
)

# После миграции
from langchain_openai import ChatOpenAI
import os

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

Конфигурация LiteLLM

# До миграции
import litellm

response = litellm.completion(
    model="gpt-4",
    api_key="sk-proj-...",
    messages=[{"role": "user", "content": "Hello"}],
)

# После миграции
import litellm
import os

response = litellm.completion(
    model="gpt-4",
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
    messages=[{"role": "user", "content": "Hello"}],
)

Миграция Node.js SDK

SDK OpenAI

Измените только конфигурацию инициализации:

// До миграции - OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-proj-...',  // Ключ OpenAI
});

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

// После миграции - RouteAPI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,  // Используйте токен RouteAPI
  baseURL: 'https://api.routeapi.ai/v1',  // Укажите на RouteAPI
});

const response = await client.chat.completions.create({
  model: 'gpt-4',  // Или используйте другие модели, например claude-3-5-sonnet-20241022
  messages: [{ role: 'user', content: 'Hello' }],
});

Изменения:

• Добавление параметра baseURL
• Замена apiKey, предпочтительно из переменной окружения
• Опционально: изменение model на другие модели, поддерживаемые RouteAPI

Миграция клиентских инструментов

Если вы используете IDE-клиенты или агенты кодирования, просто обновите конфигурацию на панели настроек:

Клиент	Руководство по настройке
Cursor	Настройка Cursor
Claude Code	Настройка Claude Code
OpenCode	Настройка OpenCode
Codex (oh-my-codex)	Настройка Codex

Обычно нужно изменить только два элемента:

1. Base URL / API Endpoint → https://api.routeapi.ai/v1
2. API Key → Ваш токен RouteAPI

Проверка совместимости параметров

Неизменные параметры

Следующие параметры ведут себя в RouteAPI идентично OpenAI:

• model - ID модели
• messages - Массив сообщений беседы
• temperature - Контроль случайности (0-2)
• max_tokens - Максимальное количество токенов для генерации
• top_p - Параметр nucleus sampling
• frequency_penalty - Штраф за частоту
• presence_penalty - Штраф за присутствие
• stop - Последовательности остановки
• stream - Включить ли потоковый ответ
• user - Идентификатор конечного пользователя
• n - Количество возвращаемых завершений

Параметры, требующие внимания

Поддержка некоторых параметров зависит от возможностей выбранной модели:

Параметр	Описание	Зависимость
tools / tool_choice	Вызов инструментов (Function Calling)	Модель должна поддерживать вызов инструментов
response_format	Структурированный вывод (режим JSON)	Модель должна поддерживать вывод JSON
seed	Детерминированное семя выборки	Поддерживается некоторыми моделями
logprobs / top_logprobs	Возврат вероятностей токенов	Поддерживается некоторыми моделями

Рекомендация: для расширенных параметров сначала проверьте в тестовой среде, поддерживает ли целевая модель эту функцию.

Обработка явных нулевых значений

RouteAPI следует соглашению Rule 5:

• Если клиент явно передает temperature=0, top_p=0 или max_tokens=0, эти значения передаются как есть в upstream-модель
• Они не обрабатываются как “не установленные” и не игнорируются

Это означает, что вы можете уверенно использовать temperature=0 для получения детерминированного вывода.

Имена моделей

Запрос доступных моделей

После миграции вы можете получить доступ к большему количеству моделей помимо OpenAI. Используйте эндпоинт /v1/models для запроса:

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Пример ответа:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1677610602,
      "owned_by": "anthropic"
    },
    {
      "id": "gemini-2.0-flash-exp",
      "object": "model",
      "created": 1677610602,
      "owned_by": "google"
    }
    // ...больше моделей
  ]
}

Использование ID моделей

Важно: используйте поле id модели в запросах (например, claude-3-5-sonnet-20241022), а не отображаемые имена (например, “Claude 3.5 Sonnet”).

# ✅ Правильно - Использование ID модели
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[...],
)

# ❌ Неправильно - Использование отображаемого имени
response = client.chat.completions.create(
    model="Claude 3.5 Sonnet",  # Вызовет ошибку
    messages=[...],
)

Переключение моделей между провайдерами

После миграции на RouteAPI вы можете легко пробовать модели от разных провайдеров:

# Модели OpenAI
model="gpt-4"
model="gpt-4o"

# Модели Anthropic Claude
model="claude-3-5-sonnet-20241022"
model="claude-3-5-haiku-20241022"

# Модели Google Gemini
model="gemini-2.0-flash-exp"
model="gemini-1.5-pro-002"

# Модели AWS Bedrock (через RouteAPI)
model="anthropic.claude-3-5-sonnet-20241022-v2:0"

Просто измените параметр model, никаких других изменений кода не требуется.

Тестирование и проверка

Контрольный список тестирования

После миграции рекомендуется проверить по следующему контрольному списку:

• Тест аутентификации - Подтвердите, что токен действителен и может успешно вызвать /v1/models
• Базовые вызовы - Проверьте, что chat.completions.create возвращает результат нормально
• Потоковый ответ - Если используется stream=True, проверьте, что потоковый вывод работает
• Вызов инструментов - Если используется Function Calling, проверьте поток вызова инструментов
• Обработка ошибок - Протестируйте сценарии ошибок, такие как недостаточный баланс, ограничение скорости, недействительные параметры
• Статистика использования - Проверьте в консоли RouteAPI, что журналы использования записываются правильно

Общие проблемы и их решение

Код ошибки	Частые причины	Решение
401 Unauthorized	Недействительный или отсутствующий токен	Проверьте формат заголовка Authorization: Bearer sk-...
402 Payment Required	Недостаточный баланс или исчерпанная квота	Войдите в консоль для пополнения баланса или увеличения квоты токена
404 Not Found	Неправильный базовый URL или опечатка в пути	Подтвердите, что базовый URL - https://api.routeapi.ai/v1
429 Too Many Requests	Достигнут лимит скорости	Снизьте частоту запросов или свяжитесь с администратором для увеличения лимита
500 Internal Server Error	Проблема с upstream-сервисом модели	Повторите запрос или переключитесь на резервную модель

Советы по отладке:

• Используйте cURL для прямого тестирования API, исключая проблемы конфигурации SDK
• Проверьте журналы использования консоли RouteAPI для конкретных сообщений об ошибках
• Сравните различия параметров между исходными запросами OpenAI и запросами RouteAPI

Пример: Тестирование с cURL

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Если запрос cURL успешен, конфигурация токена и базового URL правильна, и проблема может быть на уровне SDK.

Рекомендации по поэтапной миграции

Для производственных сред рекомендуется стратегия постепенной миграции:

1. Сначала проверьте в тестовой среде

• Полностью протестируйте мигрированный код в среде разработки или тестирования
• Проверьте основную функциональность, пограничные случаи и обработку ошибок
• Сравните содержимое ответов и производительность между OpenAI и RouteAPI

2. Постепенное развертывание

• Используйте feature flags для управления переключением базового URL
• Сначала включите RouteAPI для небольшого процента трафика
• Наблюдайте за частотой ошибок, задержкой и отзывами пользователей

Пример: Управление через переменные окружения

import os

# Управление использованием RouteAPI через переменную окружения
USE_ROUTEAPI = os.getenv("USE_ROUTEAPI", "false").lower() == "true"

if USE_ROUTEAPI:
    base_url = "https://api.routeapi.ai/v1"
    api_key = os.environ["ROUTEAPI_KEY"]
else:
    base_url = "https://api.openai.com/v1"
    api_key = os.environ["OPENAI_API_KEY"]

client = OpenAI(api_key=api_key, base_url=base_url)

3. Мониторинг журналов использования и частоты ошибок

После миграции внимательно отслеживайте:

• Коэффициент успешности запросов - Проверьте наличие аномальных ошибок 4xx/5xx
• Задержка ответа - Распределение задержки P50, P95, P99
• Использование токенов - Проверьте, что биллинг соответствует ожиданиям
• Доступность моделей - Коэффициент успешности и задержка для разных моделей

Подробные записи доступны на странице “Журналы использования” консоли RouteAPI.

4. План отката

Подготовьте план быстрого отката на OpenAI:

• Сохраните исходный ключ API OpenAI, не удаляйте его сразу
• Используйте центр конфигурации или переменные окружения для управления базовым URL для быстрого переключения
• Установите пороги оповещений в мониторинге для автоматического запуска отката

# Пример отката: Переключение простым изменением переменной окружения
# USE_ROUTEAPI=false -> Использовать OpenAI
# USE_ROUTEAPI=true -> Использовать RouteAPI

Рекомендации по оптимизации после миграции

1. Использование возможностей мультимодельности

RouteAPI поддерживает модели от нескольких провайдеров. Выбирайте наиболее подходящую модель для каждого сценария:

• Сценарии, чувствительные к задержке - Используйте gemini-2.0-flash-exp или gpt-4o-mini
• Сложные задачи рассуждения - Используйте claude-3-5-sonnet-20241022 или gpt-4
• Оптимизация затрат - Сравните соотношение цена-качество разных моделей и выберите оптимальное решение

2. Настройка независимых токенов

Создавайте отдельные токены для разных проектов, сред или команд:

• Среда разработки - Токен с низкой квотой для предотвращения чрезмерных затрат при тестировании
• Производственная среда - Токен с высокой квотой с настроенными оповещениями
• Разные команды - Независимые токены для атрибуции затрат и аудита

3. Включение журналов запросов

Просматривайте подробные журналы запросов в консоли RouteAPI:

• Модель, использование токенов и задержка для каждого запроса
• Причины ошибок и трассировки стека для неудачных запросов
• Тренды использования и анализ затрат

Эти журналы помогают оптимизировать затраты и решать проблемы.

Получение помощи

Если вы столкнулись с проблемами во время миграции:

• Обратитесь к справочной документации API
• Посетите консоль RouteAPI для проверки журналов использования
• Свяжитесь с технической поддержкой для получения помощи

---

Связанная документация:

• Обзор API
• Аутентификация
• API Chat Completions
• Интеграция SDK OpenAI