Estratégia de comutação por falha para API de IA: matriz de falhas
Política por fases para decidir quando repetir, usar uma rota com o mesmo contrato, parar, reconciliar efeitos secundários ou investigar.

Repetir um pedido de uma API de IA, mudar de rota e substituir o modelo são ações diferentes. A repetição faz uma nova tentativa sob o mesmo contrato. A mudança de rota envia o modelo e o protocolo solicitados por outro caminho elegível. A substituição altera o modelo e pode mudar a qualidade, o preço, a latência, o comportamento das ferramentas, os limites de contexto e o formato de saída.
Uma política fiável define as ações permitidas antes do incidente. A decisão considera a classe da falha, a fase da resposta, a idempotência da operação completa e quantas tentativas ainda cabem no prazo do utilizador.
Separar repetição, mudança de rota e substituição de modelo
Use nomes diferentes na configuração, nos registos e nos manuais de operação.
| Ação | O que muda | Uso adequado | Risco principal |
|---|---|---|---|
| Repetição na mesma rota | Tempo e número da tentativa | Recuperar de uma falha transitória curta na mesma rota | Aumentar a carga sobre uma dependência com problemas |
| Rota alternativa com o mesmo contrato | Canal do fornecedor, conta ou grupo ordenado | Preservar o modelo e o protocolo quando um caminho falha | Incompatibilidade oculta entre rotas consideradas equivalentes |
| Substituição de modelo | ID do modelo ou política de modelos com nome | Compromisso de qualidade, custo ou disponibilidade aprovado pelo produto | Alteração silenciosa de comportamento e faturação |
Não chame «repetição» às três ações. A equipa de operações precisa de saber se o pedido foi repetido, encaminhado por outra rota ou respondido por outro modelo. Para o utilizador, a substituição de modelo deve ser um contrato de produto explícito, não um atalho de recuperação invisível.
Alguns gateways oferecem etapas ordenadas por fornecedor ou modelo. A documentação da Cloudflare sobre rotas alternativas identifica, por exemplo, a etapa que produziu a resposta final. A lição não é copiar uma política específica, mas preservar provas de cada tentativa sempre que a rota muda.
Aplicar quatro verificações antes de repetir o pedido
Um código de estado, por si só, não é uma política de repetição. Avalie:
- Classe da falha: a falha é transitória, permanente, causada por quem chama ou de resultado ambíguo?
- Fase da resposta: ocorreu antes dos cabeçalhos, antes de uma saída efetiva ou depois de entregar conteúdo?
- Idempotência: a operação completa pode ser repetida sem duplicar um efeito externo?
- Orçamento de tentativas: ainda há tempo real e uma tentativa disponível?
A estratégia de repetição da Google Cloud usa as mesmas distinções para APIs gerais: a resposta indica se repetir pode ajudar; a idempotência determina se é seguro. Os erros 408, 429, 5xx, os tempos limite do socket e as desconexões costumam ser transitórios, mas as operações não idempotentes exigem condições mais rigorosas.
Num fluxo de trabalho de IA, a idempotência vai além do pedido HTTP ao modelo. Repetir uma instrução pode voltar a propor um e-mail, um reembolso, uma publicação ou uma escrita na base de dados. Cada execução de ferramenta precisa de uma chave de idempotência estável e de um resultado persistido, mesmo que a inferência seja apenas de leitura.
Começar por uma matriz de falhas
Esta matriz é uma política de aplicação conservadora. O gateway pode mudar internamente para outro canal com o mesmo contrato antes de entregar o resultado final; coordene as duas camadas para não multiplicar tentativas.
| Falha ou fase | Repetição na mesma rota | Rota alternativa com o mesmo contrato | Parar ou investigar | Motivo |
|---|---|---|---|---|
| Erro de validação, campo não suportado ou pedido malformado | Não | Não | Corrigir o pedido | Repetir o mesmo contrato inválido não pode funcionar |
| Erro de autenticação, autorização, quota ou política no gateway | Não | Não | Corrigir a conta ou a política | Outra rota não deve contornar a decisão do gateway |
| Falha de credencial ou conta do fornecedor antes da saída | Não na rota com falha | Sim, com um canal verificado | Isolar e investigar o canal | O contrato mantém-se ao remover uma credencial com problemas |
Falha de rede ou 408 antes da saída |
No máximo uma tentativa limitada se for idempotente | Sim | Parar ao chegar ao prazo | Pode ser transitória, mas o resultado fica ambíguo após uma desconexão |
429 antes da saída |
Repetição diferida respeitando Retry-After |
Sim, se outra rota equivalente tiver capacidade | Parar ao esgotar o orçamento | A repetição imediata agrava a limitação de pedidos |
500, 502, 503 ou 504 antes da saída |
Limitada, com espera progressiva | Sim | Investigar falhas repetidas | Geralmente transitória, sem provar que todas as rotas são seguras |
| Resposta do fornecedor incompatível com o esquema antes da saída para o cliente | Geralmente não | Apenas para uma rota validada com o mesmo esquema | Isolar ou investigar a compatibilidade | Repetir uma implementação incompatível raramente ajuda |
| Recusa do modelo ou resposta conforme à política de segurança | Não | Não | Devolver o resultado | Uma recusa válida não é uma falha de infraestrutura |
Cancelamento por quem chama ou 499 no destinatário |
Não | Não | Parar imediatamente | Quem chamou já não pretende o trabalho |
| Fluxo parcial depois de entregar conteúdo ou argumentos de ferramenta | Sem repetição transparente | Sem mudança de rota transparente | Marcar como parcial e delegar à aplicação | Outro fluxo pode duplicar ou contradizer a saída já entregue |
| Efeito de ferramenta com conclusão desconhecida | Não até reconciliar | Não até reconciliar | Consultar o registo idempotente ou o sistema externo | Outra inferência pode propor novamente o mesmo efeito |
Um 503 antes de qualquer saída é diferente de uma ligação encerrada após 400 tokens visíveis.
Tratar o início do fluxo como ponto de compromisso
Antes da saída para o cliente, o gateway pode descartar a tentativa com falha e escolher outra rota sem expor duas respostas. Depois do primeiro byte significativo, a repetição transparente deixa de ser segura.
Reiniciar o fluxo pode:
- repetir o início da resposta;
- produzir continuação diferente;
- emitir uma chamada de função duplicada com um novo ID de chamada;
- alterar a utilização e o custo sem uma fronteira clara;
- impedir o cliente de identificar a tentativa a que pertence cada evento.
Se o fluxo for interrompido depois do início da saída, devolva um erro de resultado parcial ou de transporte com o ID do pedido original. A aplicação pode oferecer «tentar novamente», continuar a partir de um ponto de controlo seguro ou descartar a saída parcial. Não deve juntar um novo fluxo do modelo ao anterior como se nada tivesse acontecido.
Nas chamadas de funções, persista os identificadores aceites e os resultados dos respetivos efeitos antes que uma repetição possa recriá-los. A comparação dos formatos de chamadas de funções explica a relação entre os identificadores de chamada e a idempotência da aplicação.
Limitar a espera progressiva por tentativas e tempo total
A espera exponencial distribui as tentativas no tempo; uma variação aleatória evita que muitos clientes repitam ao mesmo tempo após uma falha comum.
delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)
Respeite um Retry-After válido quando couber no prazo. A espera progressiva não concede permissão para repetir: as verificações de falha e idempotência têm de ser satisfeitas primeiro.
Defina um orçamento total, não apenas um contador:
- máximo de tentativas por ação do utilizador;
- tempo máximo decorrido, incluindo fila e espera progressiva;
- tentativas antes e depois de escolher um grupo alternativo;
- tempo mínimo restante para gerar resposta útil;
- propagação do cancelamento de quem chama para todas as tentativas ativas.
Para um pedido interativo com um prazo de 15 segundos, três tentativas de 10 segundos não formam uma política executável. Um trabalho em lote pode ter um orçamento maior, mas também precisa de um prazo final e de um identificador persistente da tarefa.
Evitar a amplificação de repetições entre camadas
Se o SDK faz três tentativas, o gateway tenta três rotas por tentativa e o proxy do fornecedor faz duas chamadas por rota:
3 tentativas do cliente × 3 tentativas do gateway × 2 tentativas ao fornecedor = 18 chamadas ao fornecedor
Uma ação gera 18 chamadas ao fornecedor. Durante um incidente, isso aumenta as filas, os limites de pedidos, o custo e o tempo de recuperação.
Distribua a responsabilidade pelas repetições:
- o gateway trata da mudança imediata para outro canal com o mesmo contrato;
- a aplicação decide se a ação completa do utilizador pode ser repetida;
- as repetições automáticas do SDK são desativadas ou limitadas se o gateway já repete;
- os trabalhos assíncronos usam um ID persistente e um registo de tentativas;
- nenhuma camada inicia uma tentativa depois do cancelamento por quem chama.
Registe o número da tentativa dessa camada e um ID de pedido estável de ponta a ponta. Sem isso, cada componente parece ter feito apenas duas ou três tentativas enquanto a amplificação total fica oculta.
Verificar se a rota alternativa preserva o contrato
O mesmo nome público de modelo não prova um comportamento idêntico. Antes de incluir um canal numa mudança de rota transparente, exija provas:
| Área do contrato | Evidência necessária |
|---|---|
| Identidade do modelo | O modelo solicitado está disponível sem associação silenciosa a outro modelo |
| Endpoint | O pedido de Responses ou Chat Completions é aceite tal como está configurado |
| Transmissão | Os tipos de evento, a terminação, a utilização e o cancelamento funcionam |
| Saída estruturada | O subconjunto necessário de JSON Schema e o modo estrito funcionam |
| Chamadas de funções | As ferramentas, os ID de chamada, os argumentos transmitidos e os resultados completam o percurso de ida e volta |
| Limites | O contexto, a saída, a taxa e a concorrência correspondem à carga de trabalho |
| Erros | Os estados e corpos de erro podem ser classificados sem expor segredos |
| Utilização e custo | Estão definidos os tokens, os campos de cache, o nível de serviço e a política de preços |
| Segurança e região | A política, o percurso dos dados e os requisitos de residência mantêm-se conformes |
Se uma rota falhar em qualquer requisito, não é uma alternativa transparente para essa carga de trabalho. Pode ser usada ao abrigo de uma política de produto separada e explícita.
Mudar de modelo é sempre uma decisão de produto. Defina os modelos permitidos, a qualidade mínima, o preço máximo, o contrato das ferramentas e a informação visível para o utilizador. Um erro de rota não justifica uma troca silenciosa para um modelo mais barato ou menos capaz.
Compreender como a Modelflare muda de rota
A Modelflare procura caminhos elegíveis para o modelo solicitado pelo cliente da API. Uma chave de API normal tem um grupo principal e pode ter grupos alternativos ordenados. Uma chave de API inteligente avalia os grupos disponíveis de acordo com a sua estratégia de encaminhamento. Nenhum mecanismo deve substituir silenciosamente o modelo solicitado.
A admissão por RPM ao nível do grupo ocorre antes da faturação e do pedido ao fornecedor. Se o grupo estiver cheio, pode ser avaliado outro grupo alternativo ou um candidato do encaminhamento inteligente; sem um grupo elegível, a resposta é 429.
Dentro do grupo, a prioridade do canal define a ordem de mudança de conta. Após um erro do fornecedor, o canal com falha é excluído e a seleção continua. A mudança de canal atual não depende de RetryTimes nem de AutomaticRetryStatusCodes; termina com sucesso, com o esgotamento das rotas, com o cancelamento por quem chama ou quando a saída para o cliente já começou.
Estas decisões internas de caminho para o mesmo modelo não autorizam um ciclo ilimitado no cliente. Consulte Encaminhamento fiável de APIs de IA para grupos e canais e Diagnóstico de erros de APIs de IA para distinguir erros de política do gateway de falhas do fornecedor.
Preservar evidência de cada tentativa
Um 200 final não prova o sucesso da primeira rota. O ID do canal final também não descreve as tentativas anteriores. Preserve pelo menos:
- ID de pedido estável e ID de correlação visível para quem chama;
- sequência de tentativas e referências de grupo/canal;
- modelo e contrato do endpoint em cada tentativa;
- estado da falha, classe do erro e fase do fluxo;
- se a saída para o cliente já tinha começado;
- marcos temporais e estado do cancelamento;
- utilização de entrada, saída e tokens em cache, quando disponível;
- atribuição de custos por tentativa concluída ou faturável;
- motivo final: sucesso, rotas esgotadas, cancelamento, resultado parcial ou paragem por política.
Não guarde chaves de API, instruções ou respostas em bruto nem credenciais do fornecedor apenas para diagnosticar mudanças de rota. Classes de erro sem dados sensíveis e metadados temporais costumam bastar; os arquivos de pedidos devem ser restritos, breves e explicitamente ativados.
Ensaiar a política antes da produção
Use os limites reais do protocolo e entradas seguras e determinísticas:
- desative o canal principal antes dos cabeçalhos e verifique a rota seguinte para o mesmo modelo;
- devolva uma limitação de pedidos e valide os limites de tentativas e
Retry-After; - cancele a chamada e prove que nenhuma tentativa posterior começa;
- interrompa o fluxo depois da saída e impeça uma repetição transparente;
- envie um pedido inválido e confirme que a mudança de rota não o esconde;
- repita um fluxo de ferramentas e confirme apenas um efeito externo;
- esgote todas as rotas e verifique um erro final claro;
- examine o registo de tentativas e reconcilie a utilização e o custo.
Implemente primeiro numa carga de trabalho pequena. Monitorize separadamente o número de tentativas, o sucesso após a mudança de rota e a taxa bruta de sucesso, e mantenha uma forma rápida de remover rotas com problemas. O objetivo não é maximizar as mudanças de rota, mas recuperar em segurança dentro de um prazo limitado, preservando o contrato do modelo e as provas de cada tentativa.