Стратегия резервирования API ИИ: матрица отказов поставщиков
Поэтапная политика выбора повторной попытки, маршрута с тем же контрактом, остановки, сверки побочных эффектов или расследования.

Повтор вызова API ИИ, переключение маршрута и замена модели — разные действия. Повтор запускает ещё одну попытку в рамках того же контракта. Переключение маршрута отправляет запрошенную модель и протокол по другому допустимому пути. Замена меняет модель, а вместе с ней может изменить качество, цену, задержку, работу инструментов, ограничения контекста и формат вывода.
Надёжная политика определяет допустимые действия до инцидента. Решение зависит от класса сбоя, стадии ответа, идемпотентности всей операции и числа попыток, которые ещё помещаются в срок ожидания пользователя.
Разделяйте повтор, переключение маршрута и замену модели
Используйте разные термины в конфигурации, журналах и инструкциях для дежурной команды.
| Действие | Что меняется | Подходящая задача | Главный риск |
|---|---|---|---|
| Повтор на том же маршруте | Время и номер попытки | Восстановление после короткого временного сбоя того же маршрута | Дополнительная нагрузка на неисправную зависимость |
| Резервный маршрут с тем же контрактом | Канал поставщика, учётная запись или упорядоченная группа | Сохранение модели и протокола при отказе одного пути | Скрытая несовместимость формально равных маршрутов |
| Замена модели | ID модели или именованная политика моделей | Одобренный продуктом компромисс качества, цены и доступности | Незаметное изменение поведения и расчёта стоимости |
Не называйте все три действия «повтором». Операторы должны видеть, был ли запрос повторён, перемещён на другой путь или обслужен другой моделью. Для пользователя замена модели должна быть явным продуктовым контрактом, а не скрытым способом восстановления.
Некоторые шлюзы поддерживают последовательность шагов по поставщикам или моделям. Например, документация Cloudflare по резервным маршрутам показывает успешный шаг. Важно не копировать конкретную политику поставщика, а сохранять доказательства каждой попытки при любом изменении маршрута.
Проверяйте четыре условия перед повтором запроса
Одного кода состояния недостаточно для политики повторов.
- Класс сбоя: ошибка временная, постоянная, вызвана инициатором запроса или имеет неопределённый результат?
- Стадия ответа: она произошла до заголовков, до содержательного вывода или после передачи результата?
- Идемпотентность: можно ли повторить всю операцию без дублирования внешнего эффекта?
- Бюджет попыток: остаётся ли достаточно реального времени и свободная попытка?
Стратегия повторов Google Cloud использует те же базовые критерии для обычных API: ответ показывает, может ли повтор помочь, а идемпотентность — безопасен ли он. Ошибки 408, 429, 5xx, истечение времени ожидания сокета и разрыв соединения часто являются временными, но для неидемпотентных операций нужны более строгие условия.
В рабочем процессе ИИ идемпотентность не заканчивается на HTTP-запросе к модели. Повтор инструкции может заново предложить отправку письма, возврат средств, развёртывание или запись в базу данных. Поэтому для каждого запуска инструмента нужен стабильный ключ идемпотентности и сохранённый результат, даже если сама модель только читает данные.
Начинайте с матрицы сбоев
Ниже приведена консервативная политика приложения. Шлюз может внутри переключиться на другой канал с тем же контрактом до выдачи конечного результата, поэтому действия двух уровней должны быть согласованы.
| Ошибка или стадия | Повтор на том же маршруте | Резервный маршрут с тем же контрактом | Остановить или исследовать | Причина |
|---|---|---|---|---|
| Ошибка проверки клиента, неподдерживаемое поле или неверно составленный запрос | Нет | Нет | Исправить запрос | Повтор того же неверного контракта не поможет |
| Ошибка аутентификации, авторизации, квоты или политики шлюза | Нет | Нет | Исправить учётную запись или политику | Другой маршрут поставщика не должен обходить решение шлюза |
| Ошибка учётных данных или аккаунта поставщика до вывода | Не на неисправном пути | Да, при наличии проверенного канала | Изолировать и исследовать канал | Можно убрать неисправные учётные данные, сохранив контракт |
Сбой сети или 408 до вывода |
Не более одной ограниченной попытки при идемпотентности | Да | Остановиться по сроку | Сбой может быть временным, но после разрыва соединения итог неоднозначен |
429 до вывода |
Отложенный повтор с учётом Retry-After |
Да, если у равного пути есть свободная ёмкость | Остановиться при исчерпании бюджета | Немедленные повторы усиливают ограничение частоты |
500, 502, 503, 504 до вывода |
Ограниченно, с увеличивающейся задержкой | Да | Исследовать повторяющиеся сбои | Обычно временно, но не доказывает безопасность всех маршрутов |
| Ответ поставщика не соответствует схеме до передачи вывода клиенту | Обычно нет | Только на маршрут, проверенный с той же схемой | Изолировать или исследовать совместимость | Повтор несовместимой реализации редко помогает |
| Отказ модели или ответ, соответствующий политике безопасности | Нет | Нет | Вернуть результат | Корректный отказ не является сбоем инфраструктуры |
Отмена инициатором запроса или 499 на принимающей стороне |
Нет | Нет | Немедленно остановить | Инициатор больше не ожидает результат |
| Частичный поток после видимого текста или аргументов инструмента | Без прозрачного повтора | Без прозрачного переключения | Отметить частичный результат; решение принимает приложение | Второй поток может повторить уже выданный результат или противоречить ему |
| Неизвестен итог внешнего действия инструмента | Нет до сверки | Нет до сверки | Проверить запись идемпотентности или целевую систему | Повторный вывод модели может снова предложить то же действие |
503 до любого вывода и обрыв после 400 видимых токенов — принципиально разные ситуации.
Считайте начало потока границей фиксации
До начала вывода клиенту шлюз может отбросить неудачную попытку и выбрать другой путь, не показывая два ответа. После первого содержательного байта прозрачный повтор становится небезопасным.
Перезапуск потока может:
- повторить начало ответа;
- создать другое продолжение;
- выдать дублирующий вызов функции с новым ID вызова;
- изменить объём использования и стоимость без ясной границы;
- лишить клиента возможности сопоставить события и попытки.
Если поток оборвался после начала вывода, верните конечную ошибку частичного результата или транспорта с исходным ID запроса. Приложение может предложить явный повтор, продолжение с безопасной контрольной точки или удаление частичного результата. Нельзя незаметно соединять новый поток модели со старым.
Для вызовов функций граница строже: до повтора сохраните принятые ID вызовов инструмента и результаты их внешних действий. Сравнение форматов вызовов функций объясняет связь ID вызовов и идемпотентности приложения.
Ограничивайте задержку числом попыток и общим временем
Экспоненциально растущая задержка распределяет попытки по времени, а случайный разброс не позволяет множеству клиентов синхронно повторять запросы после общего сбоя.
delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)
Соблюдайте корректный Retry-After, если он помещается в общий срок. Сама задержка не разрешает повтор: сначала должны быть выполнены условия по классу сбоя и идемпотентности.
Определите общий бюджет, а не только число повторов:
- максимум попыток на одно действие пользователя;
- максимум прошедшего времени с учётом очереди и задержек;
- предел попыток до и после выбора резервной группы;
- минимальное оставшееся время для полезного ответа;
- распространение отмены инициатором на все активные попытки.
Три попытки по 10 секунд не являются выполнимой политикой для интерактивного запроса со сроком 15 секунд. Пакетная задача может иметь больший бюджет, но тоже требует конечного срока и постоянного ID задания.
Не допускайте усиления повторов между слоями
Если SDK выполняет три попытки, шлюз проверяет по три маршрута для каждой, а вышестоящий прокси делает по два вызова поставщика:
3 попытки клиента × 3 попытки шлюза × 2 попытки к поставщику = 18 вызовов поставщика
Одно действие пользователя превращается в 18 вызовов. Во время сбоя растут очереди, ограничения частоты, стоимость и время восстановления.
Распределите ответственность за повторы:
- шлюз отвечает за немедленное переключение на другой канал с тем же контрактом;
- приложение решает, можно ли целиком повторить действие пользователя;
- автоматические повторы SDK отключаются или ограничиваются, если повтор уже делает шлюз;
- асинхронные задания используют один постоянный ID и журнал попыток;
- после отмены инициатором ни один слой не начинает новую попытку.
Записывайте номер попытки текущего слоя и стабильный сквозной ID запроса. Иначе каждый компонент покажет всего две-три попытки, скрывая суммарное усиление.
Докажите сохранение контракта на резервном маршруте
Одинаковое публичное имя модели не означает одинакового поведения маршрутов. Перед включением канала в прозрачный набор резервных маршрутов проверьте:
| Область контракта | Необходимое доказательство |
|---|---|
| Идентичность модели | Запрошенная модель доступна без незаметного сопоставления с другой моделью |
| Конечная точка | Настроенный запрос Responses или Chat Completions принимается |
| Потоковая передача | Типы событий, завершение, учёт использования и отмена работают |
| Структурированный вывод | Требуемое подмножество JSON Schema и строгий режим работают |
| Вызовы функций | Инструменты, ID вызовов, потоковая передача аргументов и результаты проходят в обе стороны |
| Ограничения | Контекст, вывод, частота и параллельность соответствуют нагрузке |
| Ошибки | Состояния и тела ошибок классифицируются без раскрытия секретов |
| Использование и стоимость | Понятны токены, поля кэша, уровень обслуживания и политика цен |
| Безопасность и регион | Политика, путь данных и требования к месту хранения остаются соблюдены |
Если маршрут не проходит обязательную проверку, он не является прозрачным резервным вариантом для этой нагрузки. Его можно использовать только в рамках отдельной явной продуктовой политики.
Смена модели всегда является продуктовым решением. Определите разрешённые модели, минимальное качество, предельную цену, контракт инструментов и уведомление пользователя. Ошибка маршрута не оправдывает незаметный переход на более дешёвую или слабую модель.
Понимайте текущую семантику Modelflare
Modelflare ищет допустимые пути для модели, которую запросил клиент API. Обычный ключ API имеет основную группу и может иметь упорядоченные резервные группы. Умный ключ API оценивает доступные группы согласно стратегии маршрутизации. Оба механизма не должны незаметно менять запрошенную модель.
Допуск по RPM на уровне группы выполняется до расчёта стоимости и запроса поставщику. Если выбранная группа заполнена, проверяется упорядоченная резервная группа или кандидат умной маршрутизации; при отсутствии допустимых групп возвращается 429.
Внутри группы приоритет каналов задаёт порядок переключения учётных записей. После ошибки поставщика неисправный канал исключается, а выбор продолжается. Текущее переключение каналов не зависит от RetryTimes и AutomaticRetryStatusCodes; оно прекращается при успехе, исчерпании маршрутов, отмене инициатором или после начала вывода клиенту.
Это внутренние решения о пути для одной и той же модели, а не разрешение на бесконечный цикл повторов на стороне клиента. Для проектирования групп и каналов используйте Надёжную маршрутизацию API ИИ, а для разделения ошибок политики шлюза и сбоев поставщика — Диагностику ошибок API ИИ.
Сохраняйте доказательства каждой попытки
Финальный 200 не доказывает успех первого маршрута. Финальный ID канала не описывает неудачные попытки. Сохраняйте как минимум:
- стабильный ID запроса и видимый инициатору ID корреляции;
- последовательность попыток и ссылки на группу и канал;
- модель и контракт конечной точки каждой попытки;
- состояние сбоя, класс ошибки и стадия потока;
- факт начала вывода клиенту;
- временные отметки и состояние отмены;
- доступные объёмы входных, выходных и кэшированных токенов;
- распределение стоимости по завершённым или оплачиваемым попыткам;
- конечную причину: успех, исчерпание маршрутов, отмену, частичный результат или остановку по политике.
Не храните ключи API, исходные инструкции, исходные ответы или учётные данные поставщика только ради диагностики переключения маршрутов. Обычно достаточно очищенных классов ошибок и временных метаданных; архивы запросов должны быть ограниченными, краткосрочными и включаться явно.
Проверьте политику до подачи рабочего трафика
Используйте реальные границы протокола и безопасные детерминированные входные данные:
- отключите основной канал до заголовков и проверьте следующий путь для той же модели;
- верните ошибку ограничения частоты и проверьте пределы попыток и
Retry-After; - отмените запрос и докажите, что новая попытка не начинается;
- оборвите поток после начала вывода и исключите прозрачный повтор;
- отправьте неверный запрос и убедитесь, что переключение маршрута его не скрывает;
- повторите рабочий процесс инструмента и подтвердите только один внешний эффект;
- исчерпайте все маршруты и получите одну ясную конечную ошибку;
- проверьте журнал попыток и согласуйте объём использования и стоимость.
Сначала включите политику для небольшой нагрузки. Отдельно наблюдайте число попыток, долю успеха после переключения и исходную долю успешных запросов; сохраняйте быстрый способ удалить неисправный маршрут. Цель — не максимальное число переключений, а безопасное восстановление в ограниченный срок при неизменном контракте модели и полной доказательной цепочке.