# Модели и маршрутизация

ID моделей, регионы Глобальный и Россия, резервные модели и объект provider.

## ID моделей

Запрос указывает модель, а не сервер. Все доступные модели перечислены в [каталоге](/models) и в `GET /api/v1/models`.

| ID                 | Регион                               | Пример                                       |
| ------------------ | ------------------------------------ | -------------------------------------------- |
| `vendor/model`     | Глобальный: провайдеры по всему миру | `google/gemma-3-4b-it`, `openai/gpt-4o-mini` |
| `ru-1/…`, `ru-2/…` | Россия: размещены в России           | `ru-1/openai/gpt-oss-120b`                   |

ID точные: нет ни псевдонимов, ни суффиксов вариантов. Неизвестный ID — это `400` с сообщением `model … is not available`.

Каждая модель работает только в одном регионе. Одна и та же открытая модель может быть в каталоге дважды, например `openai/gpt-oss-120b` (Глобальный) и `ru-1/openai/gpt-oss-120b` (Россия): это две разные модели со своими ценами.

## Как маршрутизируется запрос

Для каждой модели запроса роутер выбирает маршрут, а затем:

1. пропускает маршруты, которые не поддерживают нужное запросу: `tools` требует вызова инструментов, `response_format` с `json_schema` — структурированного вывода;
2. применяет настройки `provider`, описанные ниже;
3. ставит в конец маршруты, которые недавно давали сбой.

Если у модели не осталось маршрутов, роутер переходит к следующей модели из `models`; если моделей не осталось, он отвечает `400` с сообщением `no route of … satisfies the provider constraints and parameters`.

## Резервные модели

`models` перечисляет модели, которые пробуются по порядку после `model`:

```json
{
  "model": "openai/gpt-4o-mini",
  "models": ["google/gemma-3-4b-it", "ru-1/openai/gpt-oss-120b"],
  "messages": [{ "role": "user", "content": "Hello" }]
}
```

- Следующая модель пробуется, если у модели нет маршрута или ее провайдер дал сбой **до первого токена**: тайм-аут, `5xx`, `429` или `404`.
- Всего запрос делает не больше **3 попыток**.
- Когда ответ уже начался, роутер никогда не переключает модель.
- `model` в ответе показывает, какая модель ответила; `GET /api/v1/generation` перечисляет все попытки.
- Попытки, которые провайдер отклонил с ошибкой, не оплачиваются. Средства резервируются по самой дорогой модели списка, поэтому длинный список требует большего баланса.

> **Внимание:** Список `models` может включать модели разных регионов. Добавьте `"provider": {"ignore": ["ru"]}`, чтобы остаться в регионе Глобальный, или `"provider": {"zdr": true}`, чтобы использовать только провайдеров, которые не хранят данные.

## Объект provider

| Поле                        | Действие                                                                                                       |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `"only": ["ru"]`            | Только регион Россия: запрос никогда не покидает Россию.                                                       |
| `"ignore": ["ru"]`          | Никогда не использовать регион Россия.                                                                         |
| `"order": [...]`            | Порядок, в котором пробуются провайдеры; `ru` ставит регион Россия на это место.                               |
| `"allow_fallbacks": false`  | Один маршрут на модель: без переключения между маршрутами модели. Список `models` при этом работает.           |
| `"zdr": true`               | Только модели с эндпоинтом без хранения данных. См. [Без хранения данных (ZDR)](/docs/ru/zero-data-retention). |
| `"data_collection": "deny"` | Только провайдеры, которые не хранят данные и не обучаются на них; исключает регион Россия.                    |

Другие slug в `only`, `ignore` и `order`, а также другие ключи объекта (например, `sort` или `max_price`) передаются в регион Глобальный как есть, без гарантий.

## Данные только в России

Чтобы ничего не покидало страну, используйте модель `ru-1/…` или `ru-2/…` и добавьте `"provider": {"only": ["ru"]}`: тогда даже список `models` с глобальными моделями не выведет запрос за пределы России.

```json
{
  "model": "ru-1/openai/gpt-oss-120b",
  "provider": { "only": ["ru"] },
  "messages": [{ "role": "user", "content": "Привет" }]
}
```

Поля, которые работают только в регионе Глобальный, для моделей региона Россия удаляются; см. [Параметры](/docs/ru/parameters#как-роутер-обрабатывает-параметры).