Projetar timeouts de API de IA por fase

Guia de produção: Projetar timeouts de API de IA por fase. Inclui artefato determinístico, limites de falha, controles de rollout e fontes verificadas.

Guia de produção: Projetar timeouts de API de IA por fase. Inclui artefato determinístico, limites de falha, controles de rollout e fontes verificadas.

Decisão primeiro

Projetar timeouts de API de IA por fase é um contrato explícito de produção, não uma mudança isolada. Defina sucesso, falha terminal e rollback antes de mover tráfego; o artefato separa evidência de suposição.

Comece por connect, prove headers com um caso determinístico e transforme cancel em gate de release.

Artefato reutilizável

Uma linha só passa quando a evidência vem da mesma requisição, janela de teste ou versão de configuração.

Checkpoint Evidência Condição de aprovação
connect DNS,TCP,TLS_budget_and_failure_class O limite é explícito e falha de modo fechado.
headers request_sent->response_headers O limite é explícito e falha de modo fechado.
first_output headers->first_meaningful_output,separate_from_first_SSE_frame O registro une uma requisição lógica e uma tentativa.
idle maximum_gap_between_meaningful_stream_events O limite é explícito e falha de modo fechado.
total absolute_request_deadline_inherited_by_all_child_work O limite é explícito e falha de modo fechado.
cancel client_cancel_reaches_queue,gateway,upstream,and_tool_work O registro une uma requisição lógica e uma tentativa.

Exemplo resolvido

O exemplo é sintético e determinístico. Use valores revisados do seu workload; nunca inclua segredos ou dados de clientes.

total_deadline_ms: 60000
phases:
  connect_ms: 3000
  response_headers_ms: 10000
  first_meaningful_output_ms: 25000
  stream_idle_ms: 15000
rules:
  - child_deadline_must_not_exceed_total
  - client_cancel_propagates_immediately
  - timeout_records_phase_and_attempt

Procedimento de implementação

  1. Congele requisição, resposta, configuração e baseline observável.
  2. Execute um caso positivo determinístico e preserve o resultado completo.
  3. Execute o caso negativo ou limite correspondente.
  4. Una tentativas por um request ID lógico e registre tempo, estado final e uso sem conteúdo sensível.
  5. Faça rollout em coorte limitada com critérios de parada.
  6. Releia estado durável e comportamento público; reverta se uma invariante falhar.

Modos de falha

Estas falhas invalidam o resultado mesmo quando o HTTP externo parece correto:

  • O cancelamento não chega à fila nem ao upstream e continua consumindo capacidade.
  • A rota é tratada como se guardasse estado oculto.
  • Retries sem orçamento amplificam a carga.
  • Prompts, chaves ou argumentos sensíveis entram na telemetria.

Limite do Modelflare

Modelflare centraliza routing compatível com OpenAI, chaves, grupos, uso e falhas, mas uma rota configurada não prova capacidades opcionais. Verifique modelo e canal pelo protocolo nativo, preserve zeros explícitos e use a liquidação durável como verdade de billing.

Use o guia principal para a decisão mais ampla e a documentação para a configuração atual.

Checklist de publicação

  • Responder primeiro à pergunta principal.
  • Definir owner para cada campo, estado, métrica e fórmula.
  • Usar apenas identificadores sintéticos.
  • Preservar estrutura, código, limites e avisos em todos os idiomas.
  • Revalidar contratos, suporte e preços em T-1; mover a data se algo mudar.
  • Antes do horário, excluir de API pública, rotas e sitemap.

Fontes e data de verificação

Fontes verificadas em 2026-08-07; elas não provam uma rota não testada.