Mapeamento e Fallback de Modelos

Não deixe que uma indisponibilidade do upstream se torne a sua indisponibilidade.

• Mapeamento de modelo é o recurso da camada de gateway que reescreve o alias do modelo em uma requisição do cliente para o modelo upstream real.
• Fallback de erro é o recurso pelo qual, quando a chamada ao modelo principal falha, o gateway tenta automaticamente os modelos reserva em uma ordem de prioridade pré-configurada, de forma transparente para o cliente.

​

1. Mapeamento de nome de modelo

Depois que um canal é selecionado para o modelo de destino, a plataforma realiza internamente outro mapeamento, no nível do canal, para o modelo upstream real. Essa camada é transparente para você e não requer configuração. Você só precisa se preocupar com a camada “alias → modelo de destino”.

Todos os nomes de modelo da tabela acima podem ser consultados na página de modelos da AIHubMix.

• O cliente restringe o formato do nome do modelo. Por exemplo, o Claude Desktop exige nomes de modelo no estilo Claude (veja a Seção 5).
• Definir um alias mais curto e estável para um Model ID complexo.
• Manter a configuração do cliente inalterada enquanto troca o modelo real no backend da AIHubMix.
• Várias plataformas compartilham um único esquema de nomes de conexão, mas roteiam para modelos diferentes com base na Key.

Correspondência caractere a caractere: O nome do modelo que o cliente envia deve corresponder ao lado esquerdo do mapeamento caractere a caractere. Por exemplo, my-gpt-5.5 e my-gpt-5-5 são duas strings diferentes; se não corresponderem, o mapeamento não será acionado.

​

2. Fallback de erro

​

2.1 Condições de acionamento

1. A Key está configurada com uma lista não vazia de modelos reserva.
2. Todos os canais do modelo principal foram tentados e todos falharam com um “erro recuperável” (canais esgotados).
3. A resposta ainda não começou a ser retornada (o primeiro byte / cabeçalho ainda não foi enviado ao cliente).
4. O erro não é um erro no nível da Key / do usuário (veja a tabela comparativa da 2.2 abaixo).

​

2.2 O que faz fallback e o que não faz

Observação: “Key inválida” aqui significa que sua própria Key da AIHubMix está inválida, o que não faz fallback. Se a key de algum canal upstream estiver com problema, o gateway troca de canal e, depois que os canais se esgotam, ele ainda pode fazer fallback. Não confunda os dois.

​

2.3 Base de cobrança

​

2.4 Regra de modelo gratuito

Uso típico: Defina um modelo gratuito como modelo principal e coloque modelos pagos na lista de reserva. Quando o modelo principal gratuito atinge uma cota / limite de taxa, ele faz fallback automaticamente para um modelo reserva pago. Normalmente você economiza usando a cota gratuita e, após o limite de taxa, troca perfeitamente para um modelo pago para garantir disponibilidade. Este é um dos usos mais comuns do fallback.

​

3. AIHubMix vs OpenRouter / LiteLLM

​

4. Configuração e verificação

​

4.1 Configuração

1. Configure o mapeamento de alias na Key: o alias à esquerda deve corresponder ao nome do modelo que o cliente realmente envia caractere a caractere.
2. Configure a lista de modelos reserva (uma lista ordenada por prioridade) na mesma Key.
3. A lista de reserva deve conter apenas modelos pagos / disponíveis, não modelos gratuitos (eles serão pulados).
4. Os modelos da lista de reserva devem estar dentro da faixa de modelos disponíveis da Key (modelos fora do escopo serão pulados).

​

4.2 Verificação (verifique primeiro os cabeçalhos da resposta, não os logs)

• X-Aihubmix-Fallback: true: ocorreu um fallback nesta requisição (adicionado quando o modelo final ≠ o modelo principal).
• X-Aihubmix-Model: o modelo que efetivamente respondeu nesta requisição e foi cobrado de acordo.

curl -i https://aihubmix.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"my-gpt","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i -E 'x-aihubmix-(model|fallback)'

​

5. Cenário Um Claude Desktop

​

5.1 Por que o mapeamento é necessário

O Claude Desktop usa a interface nativa /v1/messages do Claude, então, nos exemplos deste artigo, tanto o mapeamento quanto o Fallback entram em vigor.

​

5.2 Configuração de mapeamento e Fallback na AIHubMix

claude-g-p-t-5.5 -> gpt-5.5-pro
claude-gemi-3.1 -> gemini-3.1-pro-preview
claude-depsek-v4 -> deepseek-v4

fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview

​

5.3 Lista de modelos do Claude Desktop

• Use o prefixo claude- para o Model ID.
• Não escreva diretamente nomes reais de famílias de modelos como gpt, gemini ou deepseek; use aliases como g-p-t, gemi, depsek.
• O Model ID deve corresponder ao lado esquerdo do mapeamento da AIHubMix caractere a caractere, caso contrário a requisição não acionará o mapeamento esperado e poderá continuar descendo até o modelo de fallback de erro.

​

6. Cenário Dois Fallback de capacidade multimodal

claude-g-l-m-4.6 -> coding-glm-4.6-free
claude-g-p-t-5.5 -> gpt-5.5-pro
claude-gemi-3.1 -> gemini-3.1-pro-preview

fallback:
1. gpt-5.4
2. gemini-3.1-flash-image
3. veo-3

Tenha clareza sobre o motivo do acionamento: O fallback aqui acontece porque o upstream retornou um erro recuperável para esta entrada de imagem e os canais do modelo principal se esgotaram — é o mesmo mecanismo de fallback de “fazer fallback depois que o modelo principal atinge o limite de taxa”, apenas acionado por um tipo de erro diferente (o primeiro é entrada não suportada, o segundo é uma cota / limite de taxa). Distinga entendimento de geração: Isto se refere ao fallback de entendimento de imagem / vídeo, não de geração de imagem ou geração de vídeo. Uma requisição de chat não se transforma automaticamente em um endpoint de geração; para testar desenho ou geração de vídeo, você deve usar o endpoint e o modelo de geração correspondentes. As capacidades do modelo são determinadas pelas Input Modalities atualmente marcadas na página de modelos da AIHubMix.

​

7. Cenário Três Fallback de modelo gratuito

primary model (free): coding-glm-4.6-free

fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview

• Enquanto a cota gratuita ainda for suficiente, a requisição é respondida pelo modelo principal coding-glm-4.6-free e cobrada como gratuita.
• Depois que o modelo principal gratuito atinge o limite de taxa, ele faz fallback automaticamente para gpt-5.4; se gpt-5.4 também estiver indisponível, ele tenta então gemini-3.1-pro-preview.
• Qualquer modelo que responda no final é aquele pelo qual você é cobrado (veja a 2.3).

Observação: Um modelo gratuito só pode ser o modelo principal e não pode ser colocado na lista de fallback (se você o fizer, ele será pulado; veja a 2.4). Portanto, a forma correta de fazer “fallback de modelo gratuito” é: gratuito como principal, pago como reserva, e não o contrário.

​

8. Endpoints suportados

• O mapeamento de modelo e o fallback de erro suportam três categorias de interface: interfaces compatíveis com OpenAI, nativa do Claude /v1/messages e OpenAI Responses /v1/responses.
• Outras interfaces de passthrough nativo (Gemini nativo, Ideogram, vídeo, TTS, Stability, OCR, predictions etc.), passthrough de canal específico e interfaces de recuperação por ID de recurso / tipo de arquivo ainda não são suportadas.
• O Claude Desktop usa a interface nativa /v1/messages do Claude, então, nos exemplos deste artigo, tanto o mapeamento quanto o Fallback entram em vigor.

​

9. FAQ

​

Recursos relacionados

• Conectar a AIHubMix no Claude Desktop: passo a passo completo do modo desenvolvedor, configuração do Gateway, esquema de autenticação e mais.
• Página de modelos da AIHubMix: consulte nomes de modelo, preços e Input Modalities.
• Conectar a AIHubMix no LiteLLM: uma referência para quando você precisa de um gateway próprio + mapeamento / fallback de modelo.