Redundância e failover
A API Completions pode fazer failover automaticamente de um modelo para outro quando uma chamada de provedor falha. Você define uma cadeia ordenada – um modelo primário mais até dois substitutos – e o SecureAI tenta cada um deles até obter sucesso. Isso oferece resiliência contra interrupções do provedor, limites de taxa e tempos limite sem qualquer lógica de nova tentativa em seu próprio código. A redundância está disponível no endpoint clássico/chat/completions e no endpoint compatível com OpenAI /v1/chat/completions.
Como uma cadeia é definida
Existem três maneiras de solicitar uma cadeia, em ordem de precedência:
Uma rede pode conter no máximo 3 modelos distintos. As entradas duplicadas são recolhidas. Cada entrada da cadeia pode ser uma string de modelo simples ou um objeto com tempos limite por tentativa:
models e fallback_models na mesma solicitação.
Opções para toda a cadeia (redundancy)
Os tempos limite por tentativa (definidos dentro de uma entrada
models[]) substituem os valores de toda a cadeia para essa tentativa.
Gatilhos de failover
Uma tentativa fracassada é classificada em um destes motivos; o failover acontece apenas se o motivo estiver na sua listaon e houver outro modelo restante na cadeia:
Falhas que não podem ser repetidas nunca acionam failover — por exemplo, um bloco intencional de limite de taxa/orçamento de token do gateway, um disjuntor aberto ou uma rejeição de política/validação. Um substituto falharia de forma idêntica ou o bloqueio seria deliberado.
Comportamento de streaming
Para solicitações de streaming, o failover só é possível antes da chegada do primeiro token de conteúdo. SecureAI puxa o fluxo upstream até o primeiro token (delimitado porfirst_token_timeout_ms); se isso falhar, ele fará failover para o próximo modelo. Depois que o primeiro token for enviado ao seu cliente, o modelo de serviço será bloqueado — uma interrupção posterior no meio do fluxo aparecerá como um quadro error, não como um failover.
O que você recebe de volta
Quando uma cadeia multimodelo é executada, a resposta inclui um relatório de failover:- Endpoint clássico:
metadata.failover - Endpoint compatível com OpenAI:
secureai.failover
metadata.served_model / secureai.served_model informa qual modelo realmente respondeu e requested_model é o primeiro modelo da cadeia. Uma solicitação de modelo único (legado) não produz nenhum relatório de failover.
Quando toda a cadeia falha
Se todas as tentativas falharem, a solicitação retornará um erro listando todas as tentativas:- 429 se cada falha fosse um limite de taxa.
- 502 caso contrário.
code: "all_models_failed".
Padrões de administrador (failoverDefaults)
Um administrador pode anexar uma cadeia padrão a uma chave de API para que os chamadores obtenham failover sem enviar uma cadeia em cada solicitação. Configurada em Admin → Chaves de API, a carga útil é validada e fixada:
models: até 3 nomes de modelos distintos.timeout_ms: 1.000–300.000.first_token_timeout_ms: 500–60000.on: qualquer subconjunto dos quatro gatilhos.
model: "a" e a está presente em failoverDefaults.models, a cadeia começa na posição de a e continua através dos padrões restantes.
Segurança e cobrança por tentativa
Cada tentativa é uma chamada completa e independente por meio do wrapper SMLTP - aplicação de política, governança de saída/residência e o Signed Entitlement Token mint, todos executados novamente por tentativa, vinculados ao modelo dessa tentativa e aos bytes de solicitação exatos. O faturamento reflete o modelo que realmente atendeu à resposta. Cada failover também emite um evento de segurançaapi:model_failover (entregue a qualquer webhooks inscrito) e uma entrada de log de auditoria.
Relacionado
- Conclusão do bate-papo
- Endpoint compatível com OpenAI
- Policy Check — visualize o acesso de toda a rede sem gastar pontos.
- Webhooks — inscreva-se em
api:model_failover.