Provider Routing (Маршрутизация провайдеров)

Сервис автоматически направляет каждый запрос к лучшему доступному провайдеру выбранной модели. По умолчанию запросы балансируются между провайдерами с приоритетом более низкой цены и учётом их доступности.

Поведение маршрутизации настраивается через объект provider в теле запроса. Объект поддерживается текстовыми эндпоинтами: chat/completions, completions, Responses API, Anthropic Messages API и rerank.

Объект provider

Объект provider передаётся в теле запроса и управляет тем, кто и как обрабатывает запрос:

Все поля необязательны. Поля можно комбинировать — например, задать order вместе с allow_fallbacks: false.

Пример запроса с настройками маршрутизации:

curl https://api.ru-openrouter.ru/v1/chat/completions \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/llama-3.3-70b-instruct",
    "messages": [{"role": "user", "content": "Привет!"}],
    "provider": {
      "order": ["deepinfra", "together"],
      "allow_fallbacks": true
    }
  }'

Балансировка нагрузки по умолчанию

Если объект provider не задан (или в нём нет sort и order), запрос балансируется между провайдерами модели по следующей стратегии:

1. Исключаются провайдеры, у которых за последние 30 секунд наблюдались значительные сбои.
2. Среди стабильных провайдеров выбирается один из самых дешёвых — вероятность выбора взвешивается обратным квадратом цены.
3. Остальные провайдеры используются как резервные.

Пример. Провайдер A стоит $1/M токенов, провайдер B — $2/M, провайдер C — $3/M, при этом у провайдера B недавно были сбои. Запрос будет направлен к провайдеру A — он в 9 раз вероятнее выбирается, чем C (вес 1/1² против 1/3²). Если A недоступен, запрос уйдёт к C, затем к B.

При запросе с tools / tool_choice роутер старается направлять запрос провайдерам, поддерживающим вызов инструментов. Если задан max_tokens, выбираются только провайдеры, способные вернуть ответ такой длины.

Если в запросе указан sort или order, балансировка нагрузки отключается — провайдеры перебираются в заданном порядке.

Сортировка провайдеров (sort)

Поле sort отключает балансировку и задаёт явный приоритет:

{
  "model": "meta-llama/llama-3.3-70b-instruct",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "sort": "throughput"
  }
}

Суффиксы :nitro и :floor

Вместо объекта provider можно добавить суффикс к имени модели:

{
  "model": "openai/gpt-4o-mini:nitro",
  "messages": [{"role": "user", "content": "Быстрый ответ, пожалуйста!"}]
}

Суффикс перекрывает provider.sort, если он задан в запросе явно.

Порядок провайдеров (order)

Поле order задаёт список провайдеров в порядке приоритета. Роутер пробует их по очереди; если ни один не работает — переходит к остальным доступным провайдерам модели (если не запрещены fallback'и).

{
  "model": "mistralai/mixtral-8x7b-instruct",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "order": ["together", "deepinfra"]
  }
}

Чтобы запретить всех остальных провайдеров, добавьте allow_fallbacks: false:

{
  "model": "mistralai/mixtral-8x7b-instruct",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "order": ["together"],
    "allow_fallbacks": false
  }
}

В этом случае, если together недоступен, запрос завершится ошибкой вместо маршрутизации к другому провайдеру.

Подсказка: список провайдеров, доступных для конкретной модели, можно посмотреть в личном кабинете — на странице Правила провайдеров и на странице статистики запросов.

Таргетинг конкретных эндпоинтов провайдера

Один провайдер может обслуживать модель через несколько эндпоинтов: основной, специализированный «turbo»-вариант или региональные эндпоинты (например, google-vertex/us-east5).

Базовый slug матчит все эндпоинты провайдера, включая варианты и регионы. Чтобы выбрать конкретный эндпоинт — укажите полный slug с суффиксом:

{
  "model": "deepseek/deepseek-r1",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "order": ["deepinfra/turbo"],
    "allow_fallbacks": false
  }
}

Подсказка: чтобы направлять запросы ко всем эндпоинтам провайдера (во всех регионах и вариантах), используйте базовый slug без суффикса.

Отключение резервных провайдеров (allow_fallbacks)

По умолчанию allow_fallbacks = true: при недоступности приоритетного провайдера запрос направляется резервным. Значение false гарантирует, что запрос обслужит только самый приоритетный провайдер — либо вернётся ошибка.

{
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "allow_fallbacks": false
  }
}

Комбинируется с order: без fallback'ов список order становится исчерпывающим перечнем провайдеров.

Разрешение только выбранных провайдеров (only)

Поле only ограничивает маршрутизацию заданным списком провайдеров:

{
  "model": "openai/gpt-4o",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "only": ["azure"]
  }
}

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

Игнорирование провайдеров (ignore)

Поле ignore исключает провайдеров из маршрутизации для запроса:

{
  "model": "meta-llama/llama-3.3-70b-instruct",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "ignore": ["deepinfra"]
  }
}

Внимание: игнорирование нескольких провайдеров также сокращает резервные варианты.

Slug'и в order и ignore автоматически приводятся к нижнему регистру, пустые значения и дубликаты удаляются — регистр написания не влияет на результат.

Требование поддержки параметров (require_parameters)

По умолчанию (require_parameters: false) провайдер, не поддерживающий какой-то параметр запроса, всё равно может получить запрос и проигнорирует неизвестный параметр. Значение true исключает таких провайдеров из маршрутизации — запрос пойдёт только тем, кто поддерживает все переданные параметры.

{
  "messages": [{"role": "user", "content": "Привет!"}],
  "response_format": { "type": "json_object" },
  "provider": {
    "require_parameters": true
  }
}

Даже без require_parameters небольшая группа параметров используется как мягкое предпочтение при выборе между провайдерами одной модели: tools, response_format (включая structured outputs) и verbosity. Если часть провайдеров модели поддерживает такой параметр, а часть — нет, запрос направляется только поддерживающим. Если не поддерживает никто, запрос всё равно выполняется, а параметр игнорируется.

Политики обработки данных (data_collection)

Поле data_collection ограничивает маршрутизацию провайдерами в соответствии с их политикой обработки данных:

• allow (по умолчанию) — разрешены провайдеры, которые могут сохранять данные неограниченно долго и использовать их для обучения;
• deny — только провайдеры, которые не собирают пользовательские данные.

{
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "data_collection": "deny"
  }
}

Zero Data Retention (zdr)

Параметр zdr ограничивает маршрутизацию эндпоинтами с политикой Zero Data Retention (нулевое хранение промптов):

{
  "model": "openai/gpt-4o",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "zdr": true
  }
}

При zdr: true запрос направляется только на эндпоинты, не сохраняющие промпты. Значение false или отсутствие параметра не влияет на маршрутизацию.

Дистилляция текста (enforce_distillable_text)

Параметр enforce_distillable_text ограничивает маршрутизацию моделями, для которых автор явно разрешил дистилляцию текста:

{
  "model": "meta-llama/llama-3.3-70b-instruct",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "enforce_distillable_text": true
  }
}

Полезно при создании датасетов для файнтюнинга и дистилляции: запросы будут использовать только модели, допускающие такое использование.

Квантизация (quantizations)

Поле quantizations фильтрует провайдеров по уровню квантизации открытых моделей. По умолчанию запросы балансируются между всеми доступными провайдерами.

Доступные уровни:

{
  "model": "meta-llama/llama-3.1-8b-instruct",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "quantizations": ["fp8"]
  }
}

Внимание: квантизованные модели могут показывать деградацию качества на отдельных промптах в зависимости от метода квантизации.

Ограничение цены (max_price)

Поле max_price задаёт максимальную цену провайдера, которую вы готовы принять (в USD за миллион токенов):

{
  "model": "meta-llama/llama-3.3-70b-instruct",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "max_price": {
      "prompt": 1,
      "completion": 2
    }
  }
}

Значение {"prompt": 1, "completion": 2} направит запрос любому провайдеру с ценой ≤ $1/M prompt-токенов и ≤ $2/M completion-токенов.

Дополнительно доступны поля:

• request — максимальная цена за запрос (для провайдеров с per-request тарификацией);
• image — максимальная цена за изображение.

Обычно max_price комбинируют с sort — например: «использовать провайдера с максимальной скоростью, если он не дороже $X/M токенов». Если подходящей цены нет, запрос не выполняется.

Пороговые значения производительности

Поля preferred_min_throughput и preferred_max_latency задают предпочтительные пороги скорости и задержки. Эндпоинты, не попадающие в пороги, не исключаются, а деприоритизируются — перемещаются в конец списка и используются как резерв.

Перцентили

Метрики скорости и задержки каждого провайдера отслеживаются перцентилями по скользящему 5-минутному окну:

Высокие перцентили (p90, p99) отражают worst-case производительность, низкие (p50) — типичную. При указании нескольких перцентилей должны выполняться все указанные пороги.

Когда использовать:

• Real-time приложения — пороги p90/p99 по задержке для стабильного времени отклика;
• Batch-обработка — пороги p50 по скорости, когда важнее средняя производительность;
• SLA — несколько перцентилей для контроля разных уровней производительности;
• Оптимизация стоимости — комбинация с sort: "price": самый дешёвый провайдер, удовлетворяющий требованиям к скорости.

{
  "model": "deepseek/deepseek-v3.2",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "preferred_max_latency": {
      "p50": 1,
      "p90": 3,
      "p99": 5
    },
    "preferred_min_throughput": {
      "p50": 100,
      "p90": 50
    }
  }
}

Важно: пороги предпочтительны, а не гарантированы. Запрос никогда не блокируется из-за preferred_min_throughput / preferred_max_latency — в отличие от max_price, который может остановить запрос, если подходящей цены нет.

Настройки правил провайдеров в личном кабинете

Помимо per-request настроек, в личном кабинете доступна страница «Правила» (/provider-preferences), где можно задать для каждой модели:

• Порядок провайдеров — предпочтительная последовательность; роутер в первую очередь пробует их в указанном порядке;
• Игнорируемые провайдеры — провайдеры, которые никогда не будут использоваться для этой модели.

Правила применяются автоматически к запросам генерации текста (chat/completions, Responses API, Anthropic Messages API), если в запросе не заданы provider.order / provider.ignore явно. Значения из запроса всегда имеют приоритет над правилами из кабинета; остальные поля provider (например, sort и allow_fallbacks) правилами из кабинета не затрагиваются.

Быстрое добавление правил: на странице статистики нажмите на имя провайдера в истории запросов — в тултипе появятся кнопки «В приоритет» и «Игнорировать».

Sticky Routing

Для максимизации попаданий в кэш провайдера используется sticky routing — последующие запросы одной сессии направляются к тому же провайдер-эндпоинту, сохраняя кэш «тёплым».

Передайте session_id в теле запроса (до 256 символов), чтобы связать запросы одной сессии:

{
  "model": "anthropic/claude-sonnet-4",
  "messages": [{"role": "user", "content": "Привет!"}],
  "session_id": "my-agent-session-abc123"
}

При включённом переключателе «Кэширование промптов» в личном кабинете session_id генерируется автоматически.

Надёжность маршрутизации

Прокси добавляет уровень отказоустойчивости поверх маршрутизации провайдеров:

• Автоматические повторы. Временные ошибки (таймаут, HTTP 5xx, rate limit, недоступность провайдера) автоматически повторяются в пределах настроенного количества попыток.
• Переключение каналов. Если основной канал недоступен (ошибки авторизации или исчерпание попыток), запрос автоматически направляется через резервный канал.
• Детекция некорректных ответов. Ответы, в которых провайдер потребил токены, но не вернул контент, распознаются и запрос повторяется — клиент не получает «пустую» генерацию.
• Тарификация по факту. Списание выполняется по фактическому usage из ответа провайдера, а не по резервированию.

Если все доступные каналы обработки исчерпаны, возвращается ошибка с понятным описанием. ID генерации возвращается в заголовке X-Generation-Id и доступен в логах использования /v1/generation.

Заголовки атрибуции

Заголовки атрибуции пробрасываются провайдеру и позволяют вашему приложению отображаться в статистике:

Если заголовки не заданы, подставляются значения, настроенные в сервисе.

Провайдер в ответе

Ответ содержит информацию о том, какой провайдер обработал запрос:

{
  "id": "gen-abc123",
  "model": "meta-llama/llama-3.3-70b-instruct",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Привет! Чем могу помочь?"
      },
      "finish_reason": "stop",
      "provider": "DeepInfra"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "cost": 0.0521
  }
}

• choices[].provider — имя провайдера, обработавшего запрос (присутствует, если доступен);
• usage.cost — итоговая стоимость запроса в рублях;
• в streaming-режиме поле provider передаётся в чанках потока.

Условия использования провайдеров

Запросы обрабатываются сторонними провайдерами моделей. Используя сервис, вы соглашаетесь соблюдать условия обслуживания и политики этих провайдеров. Актуальные условия публикуются на страницах соответствующих провайдеров.