Выбор провайдера и надёжность
Как 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здесь не прерывает перебор. Если не ответил никто, придёт502All 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 - как при реальном отказе.