ЦАРЬ ROUTER

Маршрутизация

ЦАРЬ ROUTER автоматически маршрутизирует запросы к оптимальному провайдеру. Для моделей, доступных у нескольких провайдеров, при сбое одного — автоматическое переключение на другого.

Поведение по умолчанию

Без дополнительных параметров работает Smart Routing:

  1. Health Tracking — скользящее окно 30 сек отслеживает ошибки. Провайдер считается unhealthy при ≥ 3 ошибках. Unhealthy-провайдеры не исключаются, а перемещаются в конец (лучше попытаться, чем отказать).
  2. Weighted Random — среди healthy-провайдеров случайный выбор с весом 1/(price+1)². Бесплатные и дешёвые модели получают приоритет.
  3. Retry — при ошибке провайдера автоматически пробуется следующий.

Model Fallbacks

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

response = client.chat.completions.create(
    model="Qwen/Qwen3-235B-A22B-Instruct-2507",  # основная
    messages=[{"role": "user", "content": "Привет!"}],
    extra_body={
        "models": [                       # fallback-цепочка
            "openai/gpt-oss-120b",
            "sber/gigachat-2-max",
        ]
    },
)
 
# response.model — имя модели, которая реально ответила
print(response.model)

Управление провайдерами

Через объект provider в extra_body можно управлять маршрутизацией:

response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": "Привет!"}],
    extra_body={
        "provider": {
            "order": ["cloudru", "yandex"],
            "allow_fallbacks": True
        }
    },
)

Параметры provider

ПараметрТипПо умолчаниюОписание
orderarray-Приоритет провайдеров: ["yandex", "cloudru"]
allow_fallbacksbooleantrueЕсли false — только провайдеры из order
onlyarray-Allowlist: только указанные провайдеры
ignorearray-Blocklist: исключить указанных
sortstring / object-Сортировка: "price", "throughput", "latency"
max_priceobject-Жёсткий фильтр по цене: {"prompt": 10, "completion": 20} (₽/1M)
preferred_min_throughputnumber / object-Мягкий фильтр: мин. скорость (tok/s)
preferred_max_latencynumber / object-Мягкий фильтр: макс. задержка (ms)

Провайдеры: yandex, cloudru, sber, mts

Примеры

# Только Cloud.ru
extra_body={"provider": {"only": ["cloudru"]}}
 
# По цене (дешёвые первыми)
extra_body={"provider": {"sort": "price"}}
 
# По скорости генерации (на основе live-метрик)
extra_body={"provider": {"sort": "throughput"}}
 
# Предпочитать провайдеров с latency p50 ≤ 2000ms
extra_body={"provider": {"preferred_max_latency": {"p50": 2000, "p99": 5000}}}
 
# Жёсткий фильтр: только провайдеры ≤ 10₽/1M
extra_body={"provider": {"max_price": {"prompt": 10, "completion": 20}}}

Pipeline фильтров

Когда задан provider, запрос проходит через pipeline:

  1. only → жёсткий allowlist
  2. ignore → жёсткий blocklist
  3. max_price → жёсткий фильтр по цене
  4. sort / order / random → определение порядка
  5. preferred_min_throughput / preferred_max_latency → мягкие фильтры (не прошедших в конец)

Мониторинг

Каждый ответ содержит заголовок X-TsarRouter-Attempts с логом попыток:

[
  {"provider": "yandex", "model": "Qwen/Qwen3-235B-A22B-Instruct-2507", "status": "error", "latency_ms": 2340.5, "error": "timeout"},
  {"provider": "cloudru", "model": "Qwen/Qwen3-235B-A22B-Instruct-2507", "status": "ok", "latency_ms": 1120.8}
]

Live Metrics

Метрики собираются в реальном времени (rolling window 5 минут) per-provider:

  • Latency — время от запроса до ответа, ms
  • Throughput — скорость генерации, tok/s (только non-streaming)
  • Перцентили — p50, p90, p99

Доступны через GET /health и влияют на sort: "throughput" / "latency".