View a markdown version of this page

Roteamento e fallback de modelos - Rocha da Amazônia AgentCore

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Roteamento e fallback de modelos

Quando você roteia o tráfego de inferência por meio de um gateway, uma solicitação pode falhar quando o destino que atende ao modelo solicitado está limitado, fora de capacidade ou inacessível. Com o modelo fallback, você define uma cadeia ordenada de destinos alternativos e o gateway tenta automaticamente o próximo quando o principal falha. O Fallback oferece maior disponibilidade e mais controle sobre a cobertura de custo e modelo, sem que cada cliente de chamada implemente sua própria lógica de fallback.

Você configura o roteamento do modelo e o fallback em um regra de gateway, e eles se aplicam a alvos de inferência. Este tópico começa com uma regra de roteamento e, em seguida, adiciona uma cadeia alternativa a ela.

Encaminhe um modelo para um alvo

Comece com uma regra que direcione um modelo para um alvo específico, sem recuo. Use um routeToTarget regra para substituir o padrão do gateway roteamento baseado em modelo para os modelos que combina. UM matchModels condição especifica a quais solicitações a regra se aplica e uma routeToTarget ação com um staticRoute especifica o destino que atende às solicitações correspondentes. Quando vários alvos correspondem ao mesmo modelo, o roteamento padrão pode enviar a solicitação para qualquer um deles; uma regra a atribui ao alvo escolhido.

O seguinte AWS O comando CLI cria uma regra que roteia gpt-5.5 para o bedrock-mantle alvo:

aws bedrock-agentcore-control create-gateway-rule \ --gateway-identifier my-gateway-abc1234567 \ --priority 100 \ --description "Route gpt-5.5 to bedrock-mantle" \ --conditions '[ { "matchModels": { "anyOf": [ {"value": "gpt-5.5"} ] } } ]' \ --actions '[ { "routeToTarget": { "staticRoute": { "targetName": "bedrock-mantle" } } } ]'

O staticRoute também pode fixar um servido model, então o alvo atende a um modelo diferente daquele solicitado pelo chamador; omitir model para atender ao modelo solicitado. Para o completo matchModels e routeToTarget referência, consulte Adicionar regras a um gateway.

Adicionar uma cadeia alternativa

Para proteger essa rota, adicione um fallback bloquear para o routeToTarget ação. O bloco declara uma lista ordenada de destinos alternativos e as condições para deixar um destino. Um destino é um alvo, opcionalmente com um modelo específico.

  • Primário — O staticRoute (ou cada weightedRoute perna). Opcionalmente, fixa um model, portanto, o modelo servido pode ser diferente do solicitado; omitir model para servir o modelo solicitado nesse alvo. As condições de licença do próprio primário estão no fallback bloquear.

  • targetFallback — Uma lista ordenada de 1 a 2 destinos alternativos para tentar, em ordem, quando o principal falhar. Cada entrada nomeia um targetName e um opcional model, e tem suas próprias condições de licença opcionais.

  • triggerOn — As condições sob as quais o gateway deixa um destino e tenta o próximo. Uma resposta que não corresponda a nenhuma delas retorna inalterada para o chamador.

  • firstByteTimeoutMilliseconds — Quanto tempo esperar pelo primeiro byte de resposta de um destino antes de desistir e passar para o próximo destino. Isso faz com que o fallback funcione quando um provedor para em vez de retornar um erro limpo.

  • circuitBreaker — Liga ou desliga o disjuntor para esta rota (ENABLED por padrão). O disjuntor ignora um destino que está falhando no momento, de modo que as solicitações vão direto para um destino saudável. Para obter mais informações, consulte Disjuntor.

O portal percorre a cadeia em ordem. Para cada destino, ele verifica o disjuntor, tenta o destino uma vez e retorna a resposta ao chamador ou, se um gatilho disparar, avança para o próximo destino. Se cada destino falhar, o chamador receberá o último erro.

Depois que uma resposta de streaming é iniciada, o gateway não pode mais recuar; o chamador recebe a resposta parcial e um erro e deve tentar novamente.

O seguinte AWS O comando CLI cria uma regra que roteia gpt-5.5 para bedrock-mantle e adiciona uma cadeia alternativa. Ele tenta gpt-5.5 em bedrock-mantle primeiro. Se isso falhar, ele tenta gpt-5.5 em openai. Somente se nenhum deles puder atender à solicitação, ela se degradará para gpt-5.4 em bedrock-mantle. O primário recai sobre 429 e 5XX, em um erro de conexão ou tempo limite do primeiro byte e em um destino não roteável, com um tempo limite de 5 segundos no primeiro byte. Os dois destinos alternativos assumem os padrões do serviço.

aws bedrock-agentcore-control create-gateway-rule \ --gateway-identifier my-gateway-abc1234567 \ --priority 100 \ --description "Prefer gpt-5.5 on bedrock-mantle, fall back to OpenAI, then degrade to gpt-5.4" \ --conditions '[ { "matchModels": { "anyOf": [ {"value": "gpt-5.5"} ] } } ]' \ --actions '[ { "routeToTarget": { "staticRoute": { "targetName": "bedrock-mantle", "model": "gpt-5.5", "fallback": { "circuitBreaker": {"mode": "ENABLED"}, "triggerOn": { "statusCodes": ["5XX", "429"], "errors": ["CONNECTION_ERROR", "FIRST_BYTE_TIMEOUT", "UNROUTABLE"] }, "firstByteTimeoutMilliseconds": 5000, "targetFallback": [ {"targetName": "openai"}, {"targetName": "bedrock-mantle", "model": "gpt-5.4"} ] } } } } ]'
nota

Os nomes do alvo e do modelo neste exemplo são ilustrativos. Use os nomes de destino configurados em seu gateway e os IDs de modelo que seus alvos atendem. Para criar os alvos de inferência aos quais uma regra faz referência, consulte Alvos de inferência. Os fornecedores de modelos podem descontinuar ou remover um modelo ao longo do tempo.

Gatilhos de fallback

O triggerOn o objeto lista as condições que causam o fallback. Você pode configurá-lo no fallback bloco (para o primário) e em cada targetFallback entrada (para esse destino). Tem dois campos:

Códigos de status

1 a 10 códigos de status de erro HTTP ou padrões de classe. Cada valor é um código exato ou uma classe no formulário NXX, limitado às faixas 4xx e 5xx — por exemplo, 429, 503, ou 5XX. O fallback se aplica somente às respostas de erro; 2xx e 3xx as respostas nunca são elegíveis como substitutas.

erros

1 a 3 condições de roteamento ou nível de conexão, a partir dos seguintes valores:

  • CONNECTION_ERROR — O gateway não conseguiu estabelecer uma conexão com o destino (conexão recusada, redefinida ou expirada). A tentativa nunca chegou ao provedor.

  • FIRST_BYTE_TIMEOUT — O destino aceitou a conexão, mas não retornou o primeiro byte de resposta firstByteTimeoutMilliseconds.

  • UNROUTABLE — O gateway não conseguiu rotear para um destino de atendimento (o destino está ausente ou não é compatível com o caminho da API da solicitação). Essa é uma condição determinística do lado do gateway: ela avança a corrente, mas não alimenta o disjuntor.

Disjuntor

O disjuntor ignora um destino que está falhando no momento, então as solicitações vão direto para um destino saudável, em vez de pagar primeiro por uma tentativa fracassada. Isso reduz a latência e o custo durante uma interrupção. O disjuntor está ativado por padrão. Para desligá-lo, defina circuitBreaker.mode para DISABLED — por exemplo, continuar usando um primário mais barato em vez de passar rapidamente para um secundário mais caro. Com o disjuntor desligado, a corrente ainda anda na ordem que você declarou.

O disjuntor se move automaticamente por três estados. A tabela a seguir mostra como cada estado afeta uma solicitação e quanto você é cobrado. Cada tentativa de saída feita pelo gateway é cobrada como uma invocação de gateway (consulte Observabilidade e cobrança).

Estado do disjuntor O que acontece com uma solicitação Faturamento

Fechado (saudável)

O gateway envia a solicitação para o primário. Se o primário retornar um gatilho alternativo (por exemplo, um 500 resposta), o gateway volta para o próximo destino na cadeia.

Cada tentativa é cobrada como uma invocação do gateway, incluindo a tentativa primária que falhou antes do fallback.

Aberto (falhando)

O gateway ignora a primária e envia a solicitação diretamente para o próximo destino na cadeia, para que a solicitação evite a tentativa fracassada e retorne mais rapidamente.

O gateway não fatura o primário ignorado. Cada destino que o gateway tenta é cobrado como uma invocação do gateway.

Half-open (recuperando)

O gateway permite que uma pequena parte das solicitações chegue ao primário para verificar se ele foi recuperado; o restante ignora o primário e vai para o próximo destino. Se as solicitações permitidas forem bem-sucedidas, o disjuntor será fechado e todo o tráfego retornará ao primário. Se falharem, o disjuntor permanece aberto.

Uma solicitação permitida até o primário é cobrada como uma invocação de gateway para essa tentativa. Outras solicitações são cobradas como no estado aberto.

Fallback com rotas ponderadas

Quando o primário é um weightedRoute, você configura o fallback para cada etapa: cada entrada dividida em tráfego carrega sua própria opção fallback bloco, e o weightedRoute em si não tem nenhum substituto no nível da rota. Uma perna sem fallback retorna o erro para o chamador quando ele falha. O disjuntor é por destino e independente dos pesos.

Regras de validação para cadeias alternativas

  • Cada destino em uma regra deve ser distinto. O destino principal e cada destino alternativo devem nomear uma combinação diferente de alvo e modelo; o gateway rejeita uma regra que repete uma.

  • UM fallback o bloco deve listar pelo menos um targetFallback entrada.

  • UM matchModels a condição deve listar pelo menos uma entrada, e cada entrada value não deve estar em branco.

  • O fallback se aplica aos alvos de inferência.

Observabilidade e cobrança

O gateway registra as decisões de fallback e roteamento nos registros de roteamento que vende. Esses registros atribuem o destino que realmente atendeu a cada solicitação e observam quando o disjuntor ignorou um destino, para que você possa confirmar o roteamento e ver por que um destino está sendo ignorado.

Importante

Cada tentativa de saída feita pelo gateway conta como uma invocação do gateway e é cobrada de acordo com as taxas do gateway. Uma solicitação que passa por vários destinos, portanto, conta como uma invocação de gateway para cada tentativa, e o disjuntor reduz esse custo ignorando destinos que já estão falhando. O modelo e o custo de inferência de cada tentativa são cobrados separadamente pela Amazon Bedrock ou pelo fornecedor do modelo, não pelo gateway.

Do ponto de vista do cliente chamador, o fallback é transparente: o cliente envia uma solicitação e recebe uma resposta, de qualquer destino atendido. O gateway não adiciona nenhum indicador voltado para o chamador de qual destino foi usado.