ЦАРЬ РОУТЕР

Выбор провайдера и надёжность

Как tsarrouter выбирает провайдера, fallback-цепочка models, объект provider, заголовки X-TsarRouter-* и тест отказоустойчивости X-Simulate-Fail

У одной модели может быть несколько провайдеров. Запрос уходит к одному из работающих, а при сбое автоматически переключается на следующий - это failover. Кто ответил на самом деле, всегда видно в заголовках ответа.

Что уходит в failover, а что нет

  • Уходит: 429 и 5xx провайдера, таймауты, обрывы соединения, пустой ответ с кодом 200.
  • Не помогает: клиентские ошибки 4xx (кроме 429) - другой провайдер отверг бы тот же запрос. В обычном запросе такая ошибка возвращается сразу, с исходным кодом и текстом провайдера.

Fallback-цепочка моделей: models

Если недоступны все провайдеры модели, запрос можно продолжить на резервной модели - перечислите их в models в порядке предпочтения:

{
  "model": "deepseek/deepseek-v4.1-flash",
  "models": ["Qwen/Qwen3.6-35B-A3B", "sber/gigachat-3-pro"],
  "messages": [{"role": "user", "content": "Привет!"}]
}
  • Кандидаты перебираются по порядку: все провайдеры основной модели, затем все провайдеры первой резервной и так далее.
  • Основная модель обязана существовать и быть включённой (иначе 400/503); несуществующая или отключённая резервная просто пропускается.
  • Частотные лимиты считаются по основной модели.
  • В отличие от обычного запроса, клиентская 4xx здесь не прерывает перебор. Если не ответил никто, придёт 502 All providers failed for model chain [...]; когда последней была клиентская ошибка 4xx - она отдаётся с исходным кодом и текстом.
  • Какая модель ответила фактически - в заголовке X-TsarRouter-Model.

Управление выбором провайдера: provider

{
  "model": "Qwen/Qwen3.6-35B-A3B",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {"sort": "throughput", "ignore": ["mts"]}
}
ПолеДействие
only: ["cloudru"]только перечисленные провайдеры
ignore: ["mts"]исключить перечисленных
order: ["yandex", "cloudru"]пробовать в этом порядке; allow_fallbacks: false запрещает добавлять остальных провайдеров после перечисленных
sortдетерминированная сортировка вместо случайного выбора: "price" (дешёвые вперёд), "throughput" (токены/с), "latency" (мс); перекрывает order
max_price: {"prompt": 500, "completion": 1000}жёсткий потолок цены, ₽ за 1M токенов - провайдеры дороже исключаются
preferred_min_throughput: 30мягкий фильтр: провайдеры медленнее 30 токенов/с уходят в конец очереди, но не исключаются
preferred_max_latency: 2000мягкий фильтр по задержке, мс

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

Стриминг: переключение до первого чанка

В потоковом режиме HTTP 200 приходит вместе с первым чанком - все переключения между провайдерами происходят до этого и незаметны. После первого чанка failover уже невозможен - как выглядит сбой в середине потока, см. список ошибок.

Заголовки трассировки

ЗаголовокЧто в нём
X-TsarRouter-Providerпровайдер, который реально исполнил запрос
X-TsarRouter-Modelмодель, которая реально ответила (важно при цепочке models)
X-Model-Deprecated: true + Sunsetответившая модель объявлена устаревшей; Sunset - дата отключения (2026-05-12)

На итоговых ошибках (502 после перебора всех) заголовков X-TsarRouter-* нет.

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

Провайдеры иногда объявляют, что перестанут отдавать модель. ЦАРЬ РОУТЕР показывает дату заранее, чтобы вы успели переключиться.

Уходит один провайдер, модель остаётся. У этого провайдера в providers[] появляется поле deprecated с датой отключения. До этой даты провайдер работает как обычно. С этой даты запросы к нему не идут: модель отвечает через других провайдеров, и делать вам ничего не нужно. Если вы закрепили провайдера через provider.only или provider.order с allow_fallbacks: false, уберите его до даты отключения.

Уходит модель целиком. Если дата отключения стоит у всех провайдеров модели, у самой модели тоже появляется поле deprecated с датой. До этой даты модель работает и остаётся в списках. С этой даты модель пропадает из GET /v1/models, а запросы к ней получают 503. Переключитесь заранее на другую модель. Цепочка models пропустит отключённую модель сама.

ПолеГдеЧто в нём
deprecatedу модели и в providers[]дата отключения, YYYY-MM-DD, по московскому времени

Поле у модели есть в GET /v1/models, GET /v1/models/{id} и GET /v1/models/info. Поле провайдера в providers[] есть в GET /v1/models/{id} и GET /v1/models/info.

{
  "id": "deepseek/deepseek-v4-flash",
  "deprecated": "2026-11-15",
  "providers": [
    {
      "provider": "yandex",
      "deprecated": "2026-11-15"
    }
  ]
}

Пока модель уходящая, к каждому её ответу добавляются заголовки X-Model-Deprecated: true и Sunset (см. таблицу выше). Отключение одного провайдера заголовков не добавляет: модель продолжает работать.

На странице моделей такие модели и провайдеры отмечены значком «!». При наведении значок становится красным и показывает дату отключения.

Проверить failover без сбоя: X-Simulate-Fail

Заголовок для теста отказоустойчивости, доступен любому ключу. Перечислите через запятую модели, которые нужно искусственно «уронить», - их провайдеры будут помечены сбойными без обращения к ним (и без списаний):

curl https://api.tsarrouter.ru/v1/chat/completions \
 -H "Authorization: Bearer sk-tsar-ваш-ключ" \
 -H "X-Simulate-Fail: deepseek/deepseek-v4.1-flash" \
 -H "Content-Type: application/json" \
 -d '{
    "model": "deepseek/deepseek-v4.1-flash",
    "models": ["sber/gigachat-3-pro"],
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

Ответ придёт от резервной модели - это видно по X-TsarRouter-Model. Работает на /v1/chat/completions в потоковом режиме или при заданной цепочке models; если «уронить» все модели запроса, придёт обычный 502 - как при реальном отказе.

На этой странице

Редактировать на GitVerse