Что такое OpenAI-совместимый роутер? Руководство по AI Gateway для разработчиков

Большинство команд начинают с одного LLM-провайдера. OpenAI SDK, один API key, один вызов POST /v1/chat/completions, и всё работает. Потом требования растут: второй провайдер для снижения стоимости или задержки, третий на случай rate limit у основного. В коде появляются клиенты под каждого провайдера, отдельная обработка ошибок и три панели биллинга.

OpenAI-совместимый роутер решает эту задачу, встав между приложением и всеми провайдерами. Вы продолжаете использовать OpenAI SDK. Меняются две строки кода: base_url и API key. Роутер транслирует запрос выбранному провайдеру, при недоступности модели включает fallback и выдаёт один счёт и один журнал.

Это руководство разбирает, что именно делает слой совместимости, на что смотреть при выборе роутера и как отправить первый маршрутизированный запрос за минуту.

OpenAI-совместимость означает, что провайдер предоставляет endpoint chat-completions, чей контракт запроса и ответа достаточно близок к API OpenAI, чтобы немодифицированный вызов OpenAI SDK работал после замены трёх значений: API key, base URL, название модели. Минимальная поверхность на практике —POST /v1/chat/completions с messages, model и потоковым ответом в форме OpenAI.

Как работает OpenAI-совместимость

OpenAI Chat Completions API стал стандартом де-факто для LLM-запросов. Контракт прост: отправить JSON body с model, messages и опциональными параметрами (temperature, max_tokens, tools, stream) на endpoint /v1/chat/completions. Получить в ответ JSON с choices, usage и метаданными.

OpenAI-совместимый роутер принимает этот же контракт. Под капотом он делает три вещи:

1. Разрешение модели. Поле model содержит префикс провайдера, например anthropic/claude-sonnet-4.5 или deepseek/deepseek-chat. Роутер сопоставляет его с endpoint и аутентификацией upstream-провайдера.

2. Трансляция запроса. Большинство провайдеров принимают запросы в формате OpenAI, но в деталях расходятся: названия параметров reasoning effort, бюджеты thinking token, форматы multimodal-ввода, схемы tool calling. Роутер нормализует всё перед пересылкой.

3. Нормализация ответа. Ответ возвращается в стандартной структуре choices[0].message.content, какой бы провайдер его ни обработал. Специфичные для провайдера поля (например, reasoning_content от DeepSeek) сохраняются, если они верифицированы.

Итог: код приложения не меняется ни при добавлении провайдера, ни при замене модели, ни при настройке fallback.

Что роутер даёт помимо совместимости

Трансляция форматов запросов — базовый минимум. Практическая ценность уровня маршрутизации проявляется в пяти областях.

Fallback и retry

Когда провайдер возвращает 429 (rate limit), 503 (перегрузка) или не отвечает, роутер пробует следующую модель в fallback-цепочке. Ваше приложение получает успешный ответ, а поле model сообщает, кто фактически обработал запрос.

Учёт расходов

Все запросы проходят через один endpoint. Роутер считает input tokens, output tokens и cached tokens в разрезе модели, команды и API key. Вместо сверки трёх панелей провайдеров — один обзор расходов.

Observability

Задержки, error rate, подсчёт токенов, fallback-события фиксируются в одном месте. Всё, что нужно для мониторинга и алертов, без отдельной инструментации для каждого провайдера.

Контроль доступа

Один API key на команду или приложение с allowlist моделей, rate limit и лимитом расходов на уровне ключа. Роутер аутентифицируется у каждого провайдера серверными credentials, которые не покидают сервер.

Совместимость streaming

SSE streaming ведёт себя одинаково вне зависимости от провайдера. Роутер транслирует chunk-формат каждого провайдера в стандартный data: {"choices":[...]}. Подробности — в руководстве по cross-provider streaming.

Пять вещей, которые нужно проверить перед выбором роутера

Не все роутеры одинаковы. В production важны эти параметры:

1. Глубина совместимости. Корректно ли роутер обрабатывает tool calling, structured output (response_format), streaming, vision-ввод и параметры reasoning effort у разных провайдеров? Поверхностная совместимость ломается сразу за рамками базового чата.

2. Накладные расходы на задержку. Любой прокси добавляет round-trip time. Измерьте добавленную задержку на P50 и P99 при вашем профиле трафика. Хорошие роутеры добавляют однозначные миллисекунды, плохие — сотни.

3. Модель ценообразования. Одни роутеры берут плату за запрос, другие — процент к стоимости провайдера, третьи — фиксированную плату за платформу. Посчитайте суммарную стоимость при ожидаемом объёме, включая плату провайдера, которую роутер пропускает. Подробное сравнение — в обзоре цен AI model router.

4. Покрытие провайдеров. Убедитесь, что роутер поддерживает нужные вам модели и провайдеров прямо сейчас и что добавление новых требует правки конфигурации, а не кода.

5. Observability-поверхность. Логи, дашборды и webhook-алерты важнее списка фич. Если не видно, какие запросы ушли в fallback, какие модели тормозят и куда уходят деньги — роутер не оправдывает себя.

Быстрый старт: первый маршрутизированный запрос за 60 секунд

Пример использует TheRouter в качестве gateway. TheRouter маршрутизирует OpenAI-совместимые запросы через настроенных провайдеров и поддерживает fallback на уровне провайдера и модели.

Python

from openai import OpenAI

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

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Объясни в двух предложениях, что делает LLM-роутер."}],
)
print(response.choices[0].message.content)

Node.js

import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "Объясни в двух предложениях, что делает LLM-роутер." }],
});
console.log(completion.choices[0].message.content);

cURL

curl https://api.therouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $THEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-chat",
    "messages": [{"role": "user", "content": "Что такое LLM-роутер?"}]
  }'

По сравнению с прямым вызовом OpenAI изменились две вещи: base URL и API key. SDK, структура запроса, формат ответа — всё остаётся прежним.

Добавление fallback-цепочки

Маршрутизация нужна ради надёжности. Передайте массив models, чтобы задать fallback-цепочку. TheRouter перебирает модели по порядку и останавливается на первой успешной:

const completion = await client.chat.completions.create({
  model: "openai/gpt-5",
  extra_body: {
    models: ["anthropic/claude-sonnet-4.5", "deepseek/deepseek-chat"],
  },
  messages: [{ role: "user", content: "Классифицируй эту заявку в поддержку." }],
});

Если gpt-5 вернёт ошибку rate limit, роутер попробует claude-sonnet-4.5. Если и она не сработает — fallback на deepseek-chat. Поле model в ответе покажет, кто фактически обработал запрос. Полная документация по fallback API — в руководстве по model fallbacks.

Типичные сценарии

Multi-provider failover

Самая частая причина использовать роутер. Сбои провайдера, rate limit, отказ модерации — не гипотетика, а еженедельная реальность. Fallback-цепочка превращает ошибку на стороне пользователя в прозрачный retry.

Оптимизация стоимости

Простые запросы направляются на дешёвые модели, сложные — на дорогие frontier-модели, где качество оправдывает затраты. Конкретные стратегии — в руководстве по оптимизации стоимости через routing.

Routing для coding agent

Cursor, Claude Code, Windsurf принимают кастомный base_url. Направьте их на роутер, чтобы контролировать выбор моделей, ставить лимиты расходов на разработчика и логировать каждый запрос. Пошаговые инструкции — в сравнении API-routing для coding agent.

A/B-тестирование моделей

Разделите трафик между двумя моделями по атрибуту запроса и сравните качество, задержку и стоимость. Роутер логирует оба пути, код приложения не меняется.

Как работает TheRouter в качестве OpenAI-совместимого роутера

TheRouter маршрутизирует OpenAI-совместимые запросы через настроенных провайдеров. Поддерживает routing и fallback на уровне провайдера и модели, предоставляет единый биллинг и учётные панели, поддерживает асинхронные media-задачи через /v1/jobs/:id.

Это не единственный вариант. OpenRouter, LiteLLM, Portkey и Cloudflare AI Gateway тоже предлагают OpenAI-совместимый routing с разными компромиссами. Развёрнутое сравнение — в обзоре gateway.

Что конкретно делает TheRouter:

• Единый endpoint https://api.therouter.ai/v1 принимает любой вызов OpenAI SDK
• Модели с префиксом провайдера anthropic/claude-sonnet-4.5, deepseek/deepseek-chat, openai/gpt-5, dashscope/qwen3.8-max
• Fallback-цепочки через массив models с приоритетным порядком
• Streaming SSE-совместимый streaming через всех маршрутизированных провайдеров
• Tool calling пересылается провайдерам с поддержкой, при необходимости с трансляцией формата

FAQ

Streaming через роутер работает так же? Да. Роутер транслирует chunk-формат каждого провайдера в стандартный OpenAI streaming. Код с stream: true работает без изменений.

Tool calling и function calling поддерживаются? Tool calling пересылается upstream-провайдеру. При различиях в формате роутер транслирует tool schemas. Различия между провайдерами — в сравнении function calling.

Специфичные для провайдера поля ответа сохраняются? Верифицированные поля (например, reasoning_content от DeepSeek) сохраняются. Роутер не удаляет расширения провайдера, но и не гарантирует каждое недокументированное поле.

Что будет, если все модели в fallback-цепочке откажут? Роутер вернёт ошибку последней попытки. Приложение получит стандартный error response и обработает его так же, как при прямом вызове провайдера.

Добавляется ли задержка? Любой прокси добавляет задержку. Хорошо реализованный роутер добавляет однозначные миллисекунды на routing-решение. Основной фактор — время инференса провайдера, обычно от сотен миллисекунд до секунд.

Можно ли использовать с Cursor, Claude Code и другими coding agent? Да. Оба принимают кастомный base URL. Направьте их на endpoint роутера, и запросы пойдут через уровень маршрутизации. Пошаговая настройка — в руководстве по настройке coding tools.

---

Источники: OpenAI API documentation, OpenRouter — LLM Gateway explainer, TheRouter quickstart, TheRouter model fallbacks, LiteLLM GitHub, Cloudflare AI Gateway docs