Projetar circuit breakers para APIs de IA

Projetar circuit breakers para APIs de IA: guia de produção com decisão explícita, artefato reutilizável, testes de falha, sinais operacionais e limites com fontes.

Projetar circuit breakers para APIs de IA: guia de produção com decisão explícita, artefato reutilizável, testes de falha, sinais operacionais e limites com fontes.

Resposta direta

Implemente Projetar circuit breakers para APIs de IA como contrato de controle de confiabilidade, não como configuração isolada. Fixe protocolo, owner, evidência e rollback antes de mover tráfego. Pontos de controle: closed, open, half_open, failure_window.

A conclusão é fixada pela tabela de contrato e pelo exemplo determinístico. ai-api-circuit-breaker não entra em rollout se um controle obrigatório não tiver evidência de wire, releitura persistente ou owner.

Escopo e responsabilidades

Separe a tarefa do cliente do plano de controle. O cliente controla arquivo ou variável; o gateway controla autenticação, rotas, limites, contabilidade e tentativas; o provedor controla protocolo nativo e capacidades voláteis. Uma resposta de texto comprova apenas um caminho.

O artigo possui decisão, riscos e verificação; a documentação viva mantém comandos e passos de interface voláteis. Isso cria uma árvore de capacidades sem duplicar o owner da intenção.

O registro owner desta página é ai-api-circuit-breaker; os controles fixos são closed, open, half_open, failure_window. Cada valor é verificado no limite de wire ou estado persistente, nunca inferido de marketing.

Artefato prático: Projetar circuit breakers para APIs de IA

Este registro de revisão é o artefato entregável. Valores técnicos explícitos permitem comparar configuração, evidência de wire e estado persistente sem depender de captura de tela.

Controle Decisão fixa Evidência
breaker_key provider_route_plus_protocol_plus_failure_class route_id + endpoint + normalized_error_class
closed_state rolling_window_with_minimum_sample eligible_attempts + failures + window_bounds
open_state fail_fast_without_upstream_attempt decision_timestamp + reopen_at + returned_error
half_open_state bounded_probe_concurrency probe_count + outcomes + state_transition
fallback same_contract_eligible_route_only eligibility_reason + route_choice + terminal_state
operator_override time_bounded_and_audited actor + reason + expiry + restored_policy

Exemplo determinístico

O exemplo usa placeholders e entradas determinísticas. Troque apenas identificadores revisados, nunca segredos ou conteúdo de clientes, e preserve o snapshot exato.

state = CLOSED
if eligible_failures(window) >= threshold and samples >= minimum:
  state = OPEN
  reopen_at = now + cool_down
if state == OPEN and now < reopen_at:
  return fail_fast
if state == OPEN and now >= reopen_at:
  state = HALF_OPEN
if bounded_probe_succeeds():
  state = CLOSED
else:
  state = OPEN

Escada de verificação

Execute as etapas em ordem. Um teste posterior não compensa um limite anterior ausente; toda tentativa deve ligar-se a uma solicitação lógica.

  1. Congele cliente, política do gateway, alias de modelo, rotas e baseline observável. Registro de evidência para breaker_key: aplicar provider_route_plus_protocol_plus_failure_class e manter route_id + endpoint + normalized_error_class.
  2. Execute prova positiva determinística e guarde resposta, request ID, rota, estado final e uso. Registro de evidência para closed_state: aplicar rolling_window_with_minimum_sample e manter eligible_attempts + failures + window_bounds.
  3. Execute o caso negativo, limite ou desconexão e confirme a camada de falha. Registro de evidência para open_state: aplicar fail_fast_without_upstream_attempt e manter decision_timestamp + reopen_at + returned_error.
  4. Repita pelo protocolo real; não deduza suporte nativo de outro endpoint compatível. Registro de evidência para half_open_state: aplicar bounded_probe_concurrency e manter probe_count + outcomes + state_transition.
  5. Faça rollout para coorte limitada com owner, expiração, limite de parada e rollback. Registro de evidência para fallback: aplicar same_contract_eligible_route_only e manter eligibility_reason + route_choice + terminal_state.
  6. Releia configuração e contabilidade persistentes; remova acesso e dados temporários. Registro de evidência para operator_override: aplicar time_bounded_and_audited e manter actor + reason + expiry + restored_policy.

Falhas a evitar

Cada item abaixo bloqueia a publicação. HTTP 200, dashboard ou demonstração não substituem esses controles.

  • global_breaker — Se ocorrer global_breaker, interrompa o rollout e use owner, evidência e rollback definidos; uma prova positiva não anula a falha.
  • mixed_denominator — Se ocorrer mixed_denominator, interrompa o rollout e use owner, evidência e rollback definidos; uma prova positiva não anula a falha.
  • half_open_stampede — Se ocorrer half_open_stampede, interrompa o rollout e use owner, evidência e rollback definidos; uma prova positiva não anula a falha.
  • fallback_cascade — Se ocorrer fallback_cascade, interrompa o rollout e use owner, evidência e rollback definidos; uma prova positiva não anula a falha.

Sinais e condições de parada

Observe sucesso e dano juntos. O limite pertence à política do workload; fixe SLO e denominador antes da janela.

Sinal Limite Ação
eligible_failure_ratio reviewed_window_and_minimum_sample open_route_breaker
open_fail_fast_latency <_caller_remaining_deadline repair_local_decision_path
half_open_probe_concurrency <=_configured_probe_limit reject_extra_probes
fallback_headroom >=_required_reserved_capacity shed_load_instead_of_failover

Limites do Modelflare

Modelflare centraliza rotas compatíveis e nativas, chaves limitadas, grupos, uso e falhas. Um canal não prova todos os campos, aliases, retenção, regiões ou fallbacks. Verifique pelo protocolo nativo e use a liquidação persistente como verdade financeira.

É um método de implementação, não certificação, conclusão legal, histórico de uptime ou benchmark universal. Revalide contrato, modelos, preços, retenção e regiões em T-1; altere a data se um fato central mudar.

Continuar pelo cluster temático

O artigo pai cobre a decisão ampla, o irmão o próximo passo e a documentação a configuração atual. Links no corpo são necessários porque o CMS gerenciado não possui related-slug.

Perguntas frequentes

Projetar circuit breakers para APIs de IA: Uma solicitação correta aprova o rollout?

Não. Caso negativo, rollout limitado, releitura persistente e parada são gates separados.

Projetar circuit breakers para APIs de IA: Fixar modelos e preços meses antes?

Não. Use placeholders ou snapshots e revalide em T-1.

Projetar circuit breakers para APIs de IA: Que evidência guardar?

IDs sem conteúdo sensível, versão, horários, estado, uso, cobrança final e decisão.

Fontes e data de verificação

Fontes verificadas em 2026-08-07. Elas definem contratos e princípios, não rotas sem teste ou estados futuros.