Выбор провайдера и надёжность
Как tsarrouter выбирает провайдера, fallback-цепочка models, объект provider, заголовки X-TsarRouter-* и тест отказоустойчивости X-Simulate-Fail
У одной модели может быть несколько провайдеров. Запрос уходит к одному из работающих, а при сбое автоматически переключается на следующий - это failover. Кто ответил на самом деле, всегда видно в заголовках ответа.
Что уходит в failover, а что нет
- Уходит:
429и5xxпровайдера, таймауты, обрывы соединения, пустой ответ с кодом 200. - Не помогает: клиентские ошибки
4xx(кроме 429) - другой провайдер отверг бы тот же запрос. В обычном запросе такая ошибка возвращается сразу, с исходным кодом и текстом провайдера.
Fallback-цепочка моделей: models
Если недоступны все провайдеры модели, запрос можно продолжить на резервной модели -
перечислите их в models в порядке предпочтения:
{
"model": "deepseek/deepseek-v4-flash",
"models": ["Qwen/Qwen3.6-35B-A3B", "sber/gigachat-2-max"],
"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-*
нет.
Признак устаревания есть и в GET /v1/models: поле deprecated с датой
отключения у затронутых моделей.
Проверить failover без сбоя: X-Simulate-Fail
Заголовок для теста отказоустойчивости, доступен любому ключу. Перечислите через запятую модели, которые нужно искусственно «уронить», - их провайдеры будут помечены сбойными без обращения к ним (и без списаний):
curl https://api.tsarrouter.ru/v1/chat/completions \
-H "Authorization: Bearer sk-tsar-ваш-ключ" \
-H "X-Simulate-Fail: deepseek/deepseek-v4-flash" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek/deepseek-v4-flash",
"models": ["sber/gigachat-2-max"],
"messages": [{"role": "user", "content": "Привет!"}]
}'Ответ придёт от резервной модели - это видно по X-TsarRouter-Model. Работает на /v1/chat/completions в потоковом
режиме или при заданной цепочке models; если «уронить» все модели запроса,
придёт обычный 502 - как при реальном отказе.