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

Резервные модели позволяют автоматически переключить запрос на другую языковую модель, если основная вернула ошибку или не ответила вовремя.

Для каждого API-ключа AI Gateway можно выбрать до двух резервных моделей и задать порядок их вызова.

Основная модель определяется в каждом запросе — это модель, указанная в поле model. В настройках ключа выбираются только резервные модели. Одна и та же цепочка применяется ко всем запросам с этим ключом.

Настройка резервных моделей

Чтобы добавить резервные модели:

1. Перейдите в раздел «ИИ-сервисы» → «AI Gateway» → «API-ключи» и кликните на нужный ключ.

2. Перейдите на вкладку «Управление».

3. В строке «Резервные модели» нажмите «Выбрать». Если модели уже настроены, нажмите «Изменить».

4. В поле «Модель 2» выберите первую резервную модель.

5. При необходимости выберите вторую резервную модель в поле «Модель 3». Это поле станет доступно после выбора «Модели 2».

6. Нажмите «Сохранить».

После сохранения  в строке «Резервные модели» отобразится выбранная цепочка.

В качестве резервных доступны только текстовые модели. Локальные модели выбрать нельзя. Одну и ту же модель нельзя добавить в цепочку дважды.

Изменение и отключение

Чтобы изменить цепочку, нажмите «Изменить» в строке «Резервные модели», выберите другие модели и сохраните изменения.

Чтобы удалить модель из цепочки, нажмите на крестик в ее поле. Если удалить «Модель 2», выбранная «Модель 3» переместится на ее место.

Для отключения автоматического переключения очистите оба поля и нажмите «Сохранить». В строке «Резервные модели» отобразится «Не выбраны».

Как работает переключение

AI Gateway обрабатывает запрос в следующем порядке:

1. Отправляет запрос основной модели из поля model.

2. Если основная модель не ответила успешно, отправляет запрос первой резервной модели — «Модели 2».

3. Если первая резервная модель также вернула ошибку, отправляет запрос «Модели 3», если она выбрана.

4. Если ни одна модель не ответила успешно, возвращает ошибку.

Если резервная модель совпадает с основной моделью запроса, AI Gateway пропускает ее и переходит к следующей. Повторно вызывать основную модель в резервной цепочке он не будет. Каждая резервная модель вызывается не более одного раза за запрос.

Когда запрос передается резервной модели

Переключение срабатывает, если:

• провайдер модели недоступен или вернул ошибку 5xx;

• истекло время ожидания ответа;

• провайдер ограничил частоту запросов — ошибка 429;

• запрос превышает объем контекста модели;

• провайдер отклонил запрос как некорректный — ошибка 400.

Когда переключение не срабатывает

• Модель вернула успешный ответ, в том числе отказ отвечать. Например, сообщение «Я не могу обсуждать эту тему» не считается ошибкой и не запускает резервную цепочку.

• Исчерпан лимит ключа на запрошенную модель. Лимит проверяется до обращения к модели. API вернет ошибку 422, даже если лимит резервной модели еще не исчерпан. Чтобы продолжить работу, увеличьте лимит на запрашиваемую модель или укажите другую модель в запросе.

• Потоковый ответ уже начал поступать. После первого фрагмента ответа переключение на другую модель не выполняется.

Поддерживаемые запросы

Резервные модели работают для запросов к /v1/chat/completions и /v1/responses. При потоковой передаче переключение возможно только до получения первого фрагмента ответа.

Резервные модели не поддерживаются для:

• эмбеддингов;

• генерации изображений;

• генерации речи и транскрибации;

• запросов в формате Anthropic к /v1/messages;

• устаревшего эндпоинта /completions.

Тарификация

Запрос оплачивается по стоимости модели, которая сформировала ответ. Неудачная попытка основной модели не оплачивается и не расходует ее лимит.

Расход токенов учитывается в лимите ответившей модели и в общем лимите ключа.

Определение модели, которая ответила

Поле model в ответе API содержит имя модели, которая фактически обработала запрос.

Дополнительно проверьте HTTP-заголовок x-timeweb-attempted-fallbacks: значение больше нуля означает, что выполнялось переключение на резервную модель. Это признак переключения, а не количество пройденных шагов цепочки.

Например, при запросе к gemini/gemini-3.1-flash-lite ответ может сформировать резервная Claude 4.5 Haiku. Cокращенный пример ответа:

    

      

    
    HTTP/1.1 200 OK
x-timeweb-attempted-fallbacks: 1

{
  "model": "claude-haiku-4-5-20251001",
  "choices": [
    {
      "message": {
        "content": "Да"
      }
    }
  ]
}