Автоматический выключатель LLM API gateway останавливает приложение от повторной отправки трафика в маршрут, который уже дает сбой. Без этого предохранителя тайм-аут может запускать повторные попытки, повторные попытки могут запускать попытки резервного перехода, попытки резервного перехода могут вызывать новые ошибки у провайдера, и приложение может превратить один инцидент на стороне upstream в петлю отказов провайдера.
Цель не в том, чтобы заменить повторные попытки или резервную подстановку модели. Цель — определить, когда маршрут настолько нездоров, что gateway должен на короткое время перестать пытаться использовать его, позже отправить контролируемый пробный запрос и выбрать более безопасный результат, пока выключатель открыт: резервный переход, постановку в очередь, деградацию или жесткий отказ.
Flatkey здесь уместен, потому что flatkey.ai публично позиционирует продукт вокруг одного API-ключа, совместимого с OpenAI базового URL-адреса https://router.flatkey.ai/v1, маршрутизации, единого биллинга, аналитики использования, управления через панель, автоматического переключения, балансировки нагрузки и ограничений квот. Это полезные центральные точки для работы над надежностью. Но они не устраняют необходимость определить четкую политику автоматического выключателя LLM API gateway для рабочих процессов вашего приложения.
Краткий ответ: что должен делать автоматический выключатель шлюза API LLM
Практический автоматический выключатель шлюза API LLM имеет три состояния маршрута и один путь fail-closed. Делайте политику достаточно простой, чтобы дежурные инженеры могли объяснить её во время инцидента.
| Состояние | Поведение шлюза | Что переводит его в это состояние | Какие данные логировать |
|---|---|---|---|
| Закрыт | Трафик может использовать провайдера, модель, семейство конечных точек, аккаунт или группу маршрутов. | Уровень ошибок, уровень таймаутов, задержка, ответы перегрузки или неудачные проверки здоровья превышают порог. | ID политики маршрута, выбранная модель, провайдер, семейство конечных точек, задержка, код статуса, число повторных попыток и стоимость. |
| Открыт | Шлюз перестаёт отправлять обычный трафик на проблемный маршрут на окно охлаждения. | Окно охлаждения истекает, или оператор вручную разрешает пробный запрос. | Причина срабатывания выключателя, время открытия, число заблокированных попыток, маршрут запасного варианта, решение очереди или причина fail-closed. |
| Полуоткрыт | Шлюз позволяет ограниченное число пробных запросов перед возобновлением трафика. | Успешные пробы закрывают выключатель; неудачные пробы снова открывают его. | Размер выборки проб, рабочий процесс пробы, результат пробы, задержка, использование и согласование владельца маршрута. |
| Fail closed | Шлюз отказывает в маршрутизации запроса, потому что проблема не связана со здоровьем провайдера. | Auth, policy, quota, safety, data-boundary, invalid request или риск побочного эффекта tool. | Причина остановки, владелец, сообщение для пользователя и путь устранения. |
Почему повторные попытки создают петли отказов у провайдера
Повторные попытки полезны, когда запрос не удаётся по временной причине. Они становятся опасными, когда каждый пользовательский запрос порождает ещё несколько обращений вверх по цепочке, особенно во время сбоя или перегрузки у провайдера. Петля повторных попыток может расходовать лимиты запросов, тратить квоту, увеличивать задержку и скрывать исходный сбой за финальной ошибкой.
Предохранитель меняет вопрос о повторных попытках. Вместо того чтобы спрашивать: «Должен ли этот один запрос повториться ещё раз?», шлюз спрашивает: «Достаточно ли здорова эта маршрутизация, чтобы сейчас принимать ещё трафик?» Такой взгляд на уровне маршрута важен для нагрузок LLM, потому что каждый запрос может быть дорогим, длительным, потоковым, использовать инструменты и быть видимым для клиента.
Облачный шаблон проектирования Microsoft для предохранителей описывает ту же базовую идею для удалённых служб: после повторяющихся сбоев цепь размыкается, чтобы приложение не продолжало пытаться выполнить операцию, которая, вероятно, завершится неудачей. Для маршрута AI тот же шаблон нуждается в границах, специфичных для LLM: поведение модели, семейство конечных точек, расход токенов, состояние потока, побочные эффекты инструментов, класс данных и согласование fallback.
Классифицируйте ошибки до того, как они дойдут до breaker
Самый быстрый способ создать плохой AI API circuit breaker — считать каждый сбой признаком здоровья провайдера. Это создаёт ложные срабатывания. Кроме того, это может скрыть проблемы, которые должен исправить владелец приложения.
| Ошибка или событие | Решение breaker | Причина | Действие по умолчанию |
|---|---|---|---|
| Provider 500, 503, overload, unavailable, connection failure, repeated upstream timeout | Учитывать в health маршрута. | Это правдоподобные сигналы здоровья провайдера, маршрута, ёмкости или сети. | Повторить запрос в рамках жёсткого бюджета, затем открыть breaker маршрута, если пороги превышены. |
| 429 request-rate limit | Классифицировать внимательно. | Сигнал перегрузки на уровне провайдера и всплеск, созданный приложением, требуют разной обработки. | Ограничить скорость, сделать back off или открыть только тот scoped route, который реально насыщен. |
| 429 monthly quota, exhausted credits, or spend limit | Не учитывать как здоровье провайдера. | Это состояние бюджета или аккаунта владельца. | Fail closed, уведомить владельца бюджета или маршрутизировать только если существует заранее одобренный бюджет. |
| 401 auth, incorrect key, organization membership, IP allowlist, unsupported region | Не учитывать как здоровье провайдера. | Запросу не разрешено использовать маршрут. | Fail closed и исправить учётные данные, аккаунт, IP или политику региона. |
| Invalid request, unsupported parameter, unsupported model, malformed schema | Не учитывать как здоровье провайдера. | Приложение отправило форму запроса, которую маршрут не может обслужить. | Исправить запрос или выбрать совместимую модель до маршрутизации. |
| Safety, moderation, DLP, compliance, or unapproved data-class block | Никогда не обходить через fallback. | Маршрутизация к другой модели может нарушить границу политики. | Fail closed и зафиксировать решение политики. |
| Tool already executed, partial stream already shown, user cancelled request | Не воспроизводить молча. | Приложение может создать дублирующиеся побочные эффекты или объединить два вывода модели. | Пометить как incomplete, потребовать явный повторный запрос пользователя или использовать idempotent recovery path. |
Руководство OpenAI по кодам ошибок — полезный пример того, почему эта таксономия важна: в нём разделяются проблемы аутентификации и IP allowlist, проблемы unsupported-region, rate limits, quota exhaustion, server errors, overload и внезапные замедления request-rate. Документация Anthropic и Google Gemini проводит похожие различия между rate limits, состояниями overload/unavailable, invalid requests и проблемами разрешений или quota. Ваш LLM API gateway circuit breaker должен держать эти классы отдельно, прежде чем откроет маршрут.
Ограничьте защиту-выключатель до самого узкого маршрута, который объясняет сбой
Слишком широкий выключатель вызывает ненужные простои. Слишком узкий выключатель позволяет тому же циклу сбоя у провайдера продолжаться по соседним путям. Ограничьте выключатель самой узкой размерностью маршрута, которая объясняет инцидент.
| Область | Когда использовать | Риск при неправильной области |
|---|---|---|
| Провайдер | Недоступны или перегружены несколько моделей одного и того же провайдера. | Слишком широко, если сбой затрагивает только одну модель, учетную запись или семейство конечных точек. |
| Модель | У одного семейства моделей повторяются ошибки 5xx, таймауты или ошибки неподдерживаемого маршрута. | Слишком узко, если насыщены учетная запись upstream или провайдер. |
| Семейство конечных точек | Chat работает, но Responses, image, video, Anthropic Messages или маршруты Gemini ведут себя иначе. | Смешивание семейств конечных точек может скрыть сбои, зависящие от протокола. |
| Учетная запись, группа, регион или путь вендора | Сбой наблюдается только у одной upstream-учетной записи, группы маршрутизации, региона или пути вендора. | Если не изолировать, можно исчерпать здоровую емкость в других местах. |
| Рабочий процесс | Вызовы инструментов, потоковая передача, пакетные задания или чат с клиентом имеют разные правила безопасности и повтора. | Маршрут, безопасный для пакетного обогащения, может быть небезопасен для живых пользовательских потоков. |
Для пользователей Flatkey это означает, что вам следует тестировать именно тот рабочий процесс и маршрут, которые вы действительно планируете использовать. Текущий снимок API цен Flatkey для этой статьи вернул 638 строк моделей, 23 вендора и семейства конечных точек для OpenAI chat completions, OpenAI Responses, Anthropic messages, Gemini generateContent, генерации изображений и OpenAI video. Рассматривайте это как устаревшее подтверждение от 18 июня 2026 года, а не как постоянный контракт маршрута.
Установите пороги, соответствующие трафику LLM
Предохранитель (circuit breaker) шлюза API LLM не должен срабатывать из-за одного изолированного сбоя. Он также не должен ждать, пока начнут сбоить все запросы клиентов. Используйте пороги, которые объединяют минимальный объем трафика, долю сбоев, задержку и период охлаждения.
| Порог | Практическая отправная точка | Почему это важно |
|---|---|---|
| Минимальный размер выборки | Открывать только после наблюдения достаточного числа запросов или проверок. | Не позволяет одному дорогому завершению открыть глобальный маршрут. |
| Доля сбоев | Отслеживать повторно обрабатываемые сбои upstream отдельно от сбоев, принадлежащих приложению. | Не дает ошибкам аутентификации, квот и некорректных запросов загрязнять состояние маршрута. |
| Порог задержки или таймаута | Использовать бюджеты таймаута, специфичные для endpoint, для путей чата, потоковой передачи, изображений и видео. | Хороший порог для чата может быть неверным для видео или пакетной генерации. |
| Период охлаждения при открытом состоянии | Держать маршрут открытым достаточно долго, чтобы остановить штормы повторных попыток, затем выполнить проверку. | Защищает и поставщика, и собственную очередь запросов. |
| Лимит проверок в полуоткрытом состоянии | Разрешить небольшое, контролируемое число тестовых запросов перед закрытием. | Предотвращает полный всплеск трафика, когда поставщик восстановился лишь частично. |
| Потолок затрат | Установить максимальный предполагаемый расход на повторные попытки, резервный переход и проверки. | Не позволяет восстановлению надежности превратиться в инцидент по биллингу. |
Ограничения скорости — часть обсуждения порогов. Руководство OpenAI по ограничениям скорости объясняет, что ограничения скорости защищают от злоупотреблений, обеспечивают справедливый доступ и помогают управлять общей нагрузкой. Если ваше приложение продолжает повторять попытки в маршрут с ограничением скорости, собственный шаблон трафика может стать инцидентом. Предохранитель (circuit breaker) шлюза API LLM должен работать вместе с клиентским регулированием темпа, очередями и контролем квот, а не против них.
Решите, что происходит, пока прерыватель открыт
Открытие прерывателя полезно только в том случае, если у шлюза есть определённое следующее действие. Не позволяйте каждому открытому маршруту автоматически откатываться к любой доступной модели.
| Действие в открытом состоянии | Когда использовать | Необходимый контроль |
|---|---|---|
| Резервный маршрут | Резервная модель или поставщик уже одобрены для этого рабочего процесса. | Перед запуском в production выполните те же проверки eval, схемы, инструментов, границ данных и затрат. |
| Очередь | Задача асинхронная или пользовательский опыт может выдержать задержку. | Сохраняйте данные об ответственном, клиенте, модели, стоимости и повторных попытках. |
| Деградация | Допустим частичный результат с меньшим риском, например кешированный ответ или урезанная функция. | Сделайте состояние деградации видимым для приложения и журналов. |
| Закрыть при отказе | Запрос несёт риск, связанный с политиками, бюджетом, безопасностью, аутентификацией, регионом или побочными эффектами. | Верните понятную ошибку и оповестите нужного ответственного вместо попытки использовать другую модель. |
Публичная документация Vercel AI Gateway описывает model fallbacks как шаблон шлюза с упорядоченными резервными моделями. Используйте это только как подтверждение категории. В вашем собственном стеке fallback — это отдельное решение об одобрении. Прерыватель решает, является ли маршрут сейчас здоровым; fallback решает, разрешено ли другому маршруту обслужить тот же запрос.
Потоковая передача и вызовы инструментов требуют дополнительных остановок
Потоковая передача упрощает сокрытие цикла сбоя у провайдера. Если приложение молча перезапускает запрос после частичного вывода, пользователь может увидеть объединённый ответ из двух попыток. Вызовы инструментов добавляют вторую проблему: повторная попытка или fallback могут дублировать возврат средств, обновление тикета, письмо, запись в базу данных или внешнее действие.
Используйте эти правила в политике circuit breaker шлюза API LLM:
- До первого вывода: повторная попытка или fallback могут быть разрешены, если маршрут одобрен, а breaker закрыт или находится в полуу открытом состоянии.
- После первого вывода: пометьте поток как незавершённый и требуйте явного повторного запроса от пользователя вместо молчаливого fallback.
- После выполнения инструмента: не воспроизводите повторно, если только инструмент не идемпотентен и операция не имеет ключа повторного воспроизведения.
- После блокировки по политике: fail closed. Не перенаправляйте на другую модель, чтобы обойти блокировку.
Это дополняет руководства стратегия повторных попыток для AI API, чек-лист fallback для моделей и балансировка нагрузки и failover для AI API. Breaker должен использовать ту же таксономию сбоев, что и эти плейбуки.
Поля наблюдаемости для обзора circuit breaker
Если запрос выполняется только потому, что gateway молча пропустил неисправный маршрут, этот инцидент всё равно должен быть видимым. Документация Cloudflare AI Gateway содержит публичный пример паттернов наблюдаемости AI gateway: журналы запросов могут включать провайдера, статус, токены, стоимость и длительность, а пользовательские метаданные могут помечать запросы для последующей фильтрации. Журналы вашего gateway должны давать тот же уровень подтверждения маршрута для решений breaker.
| Поле | Почему оно нужно операторам |
|---|---|
| Идентификатор и версия политики breaker | Показывает, какое правило открыло, закрыло или обошло маршрут. |
| Состояние breaker на момент принятия решения | Объясняет, был ли маршрут закрыт, открыт, в полуоткрытом состоянии или с fail-closed. |
| Запрошенная модель, выбранная модель, провайдер, аккаунт, группа и семейство endpoint | Отделяет намерение пользователя от решения gateway по маршруту. |
| Класс ошибки по каждой попытке | Различает сбои upstream, auth, quota, invalid request, policy и tool. |
| Задержка, timeout, число повторов и результат probe | Показывает, провалился ли маршрут медленно, быстро или восстановился во время полуоткрытого probing. |
| Флаг частичного вывода и статус side-effect у tool | Предотвращает скрытые инциденты смешанного вывода или дублирования действий. |
| Использование, стоимость, владелец квоты и итоговое решение | Связывает восстановление надёжности с расходами, бюджетами и ответственностью. |
В сопутствующей статье журналы наблюдаемости AI API подробнее рассматривается ведение журналов инцидентов. Для circuit breakers в первую очередь фиксируйте состояние маршрута и точную причину, по которой запрос был заблокирован, проверен, маршрутизирован, поставлен в очередь или завершился fail closed.
План внедрения Flatkey для политик автоматического отключения
Используйте этот поэтапный подход, прежде чем полагаться на LLM API gateway circuit breaker для клиентского трафика через Flatkey или любой совместимый с OpenAI шлюз.
- Создайте staging-ключ: держите тесты автоматического отключения отдельно от производственного клиентского трафика.
- Подтвердите базовый маршрут: направьте совместимый с OpenAI клиент на
https://router.flatkey.ai/v1и проверьте модель, семейство endpoint, строку использования и видимость в панели управления. - Снимите снимок каталога маршрутов: сохраните страницу с ценами Flatkey и ответ API с ценами в дату внедрения, чтобы допущения по маршрутам и стоимости можно было проверить.
- Определите таксономию ошибок: решите, какие ошибки учитываются при оценке здоровья маршрута, а какие завершаются с отказом до того, как их увидит автоматическое отключение.
- Начните с одного workflow: примените автоматическое отключение к одному маршруту модели, одному семейству endpoint и одному классу трафика, прежде чем расширять использование.
- Принудительно выполните тесты отказов: симулируйте тайм-аут провайдера, 500, 503, 429 по скорости запросов, исчерпание квоты, сбой аутентификации, некорректный запрос, частичный поток и побочный эффект инструмента.
- Проверьте поведение в открытом состоянии: убедитесь, что действия fallback, queue, degrade или fail-closed соответствуют матрице утверждения.
- Проверьте логи и биллинг: убедитесь, что состояние автоматического отключения, выбранный маршрут, использование, стоимость и владелец квоты видны после каждого теста.
- Настройте откат: отключите политику, если она открывается слишком широко, скрывает ошибки, принадлежащие приложению, или приводит к неожиданным расходам.
Шаблон политики Circuit Breaker
Этот шаблон не является контрактом API Flatkey. Рассматривайте его как материал для ревью для владельцев инженерии, продукта, финансов и безопасности.
{
"policy_id": "support-chat-provider-breaker-v1",
"workflow": "customer-support-chat",
"environment": "production",
"route_scope": {
"provider": "primary-provider",
"model": "primary-approved-model",
"endpoint_family": "openai-chat-completions",
"traffic_class": "customer-visible-stream"
},
"count_toward_breaker": [
"upstream_5xx",
"provider_overloaded",
"provider_unavailable",
"upstream_timeout",
"connection_reset"
],
"fail_closed_before_breaker": [
"auth_error",
"ip_allowlist_error",
"unsupported_region",
"quota_exhausted",
"invalid_request",
"schema_incompatible",
"safety_or_policy_block",
"unapproved_data_class",
"tool_side_effect_already_committed"
],
"thresholds": {
"window_seconds": 60,
"minimum_requests": 20,
"failure_ratio_to_open": 0.5,
"timeout_ratio_to_open": 0.4,
"open_cooldown_seconds": 90,
"half_open_probe_requests": 3,
"max_total_attempts_per_request": 2
},
"open_state_action": {
"default": "fail_closed",
"allowed_fallback_policy_ids": [
"support-chat-fallback-v1"
],
"allow_after_partial_output": false,
"allow_after_tool_side_effect": false
},
"logging": {
"record_breaker_state": true,
"record_route_scope": true,
"record_error_class_per_attempt": true,
"record_probe_results": true,
"record_usage_cost_and_quota_owner": true
}
}Часто задаваемые вопросы
Что такое автоматический выключатель шлюза API LLM?
Автоматический выключатель шлюза API LLM — это политика состояния маршрута, которая останавливает обычный трафик от попадания на нездоровую модель, провайдера, учетную запись или семейство конечных точек после повторяющихся сбоев, подлежащих повторной попытке. Он открывается на период охлаждения, разрешает ограниченные проверки в полуоткрытом состоянии и закрывается только после того, как маршрут снова выглядит здоровым.
Какие ошибки API LLM должны открывать автоматический выключатель?
Типичными кандидатами являются ошибки 5xx на стороне провайдера, перегрузка, ответы о недоступности, сбои подключения и повторяющиеся тайм-ауты на стороне вышестоящего сервиса. Ошибки аутентификации, сбои allowlist IP, неподдерживаемые регионы, исчерпанная квота, некорректно сформированные запросы, блокировки политик и побочные эффекты инструментов обычно должны завершаться сбоем без открытия автоматического выключателя состояния провайдера.
Чем автоматический выключатель отличается от повторной попытки или резервного варианта?
Повторная попытка решает, следует ли попробовать один запрос еще раз. Резервный вариант решает, может ли другой одобренный маршрут обслужить запрос. Автоматический выключатель решает, должен ли маршрут вообще получать обычный трафик, пока он выглядит нездоровым.
Следует ли применять автоматические выключатели к потоковым ответам LLM?
Да, но с более строгими границами. Автоматический выключатель может защитить маршрут до появления первого видимого токена. После частичного вывода или побочного эффекта инструмента приложение не должно молча повторять запрос или переключаться на резервный вариант, если только рабочий процесс не спроектирован явно для идемпотентного восстановления.
Финальная проверка перед включением автоматического выключателя
Перед тем как включить автоматический выключатель шлюза API LLM, задайте один вопрос: если этот маршрут откроется во время инцидента у провайдера, сможет ли команда объяснить, что вышло из строя, почему остановился обычный трафик, куда он пошёл дальше, во сколько это обошлось и как закрыть или откатить политику?
Если ответ «нет», оставьте выключатель в staging. Если ответ «да», используйте централизованный доступ к моделям, маршрутизацию, видимость использования, биллинг и контроль квот Flatkey как часть цикла проверки. Когда вы будете готовы проверить маршруты за одним шлюзом, совместимым с OpenAI, получите ключ и начните с одного рабочего процесса, одного маршрута к модели и одной политики автоматического выключателя.
