Um único model=auto entrega ao gateway a decisão de “qual modelo usar”.
O roteamento inteligente (LLM Router) seleciona em tempo real, dentre as centenas de modelos da plataforma, o mais adequado de acordo com o conteúdo da requisição. Basta definir model como auto — sem escolher modelo, sem comparar preços, sem acompanhar as iterações de modelos.
A cobrança é feita pelo modelo realmente usado, sem taxa adicional e com zero alteração no código do cliente. Qual modelo foi usado fica registrado no cabeçalho e no corpo da resposta (veja Como confirmar o modelo realmente usado), totalmente rastreável.
Casos de uso
- Distribuição automática por contexto: atribui automaticamente o modelo mais adequado conforme o contexto atual do usuário — especialmente útil para agents / apps que chamam modelos muitas vezes e não conseguem fixar de antemão a escolha do modelo em cada etapa.
- Otimização de custo: deixe que tarefas simples caiam automaticamente em modelos mais baratos e mais rápidos (
autoé, por padrão, custo prioritário). - Otimização de qualidade: garanta que requisições complexas sejam roteadas para modelos mais capazes (
auto:quality_first). - Cenários de baixa latência: loops de agent multironda, chat interativo em tempo real e outros cenários sensíveis à latência preferem o modelo de resposta mais rápida (
auto:latency_critical). - Entrada unificada, sem seleção manual: requisições de tipos diferentes são distribuídas automaticamente para o modelo ideal de cada uma — sem precisar manter uma tabela de mapeamento “tarefa → modelo”, nem acompanhar continuamente as iterações de modelos ou comparar preços e trocar nomes manualmente.
Início rápido
Definamodel como auto; o restante do corpo da requisição é exatamente igual a uma chamada normal. Use https://aihubmix.com/v1 como base_url.
Como confirmar o modelo realmente usado
Esta é a âncora de confiança do roteamento inteligente: você sempre sabe qual modelo foi finalmente usado nesta requisição. Método 1 · Console da AIHubMix “Logs”: em console.aihubmix.com/logs, cada requisição mostra diretamente o nome real do modelo efetivamente acertado e cobrado — sem código, verificável a olho nu. Método 2 · Campos da resposta (prático para leitura programática):- O campo
modeldo corpo da resposta é preenchido com o modelo realmente usado (por exemplo,mimo-v2.5-pro), e nãoauto. - Os cabeçalhos da resposta trazem as informações completas da decisão:
Cabeçalhos HTTP são insensíveis a maiúsculas/minúsculas: a tabela acima usa inicial maiúscula por convenção, mas a resposta HTTP/2 real vem em minúsculas como x-aihubmix-router-*; ambos são equivalentes.
Ler a decisão de roteamento (curl mostra os cabeçalhos da resposta; com o SDK use o objeto de resposta bruta para obter o header):
reason: survivors=20/33 indica que, dos 33 candidatos, 20 passaram pelo filtro rígido e entraram na pontuação; top=0.182 é a pontuação composta normalizada do modelo vencedor dentro do pool de candidatos (capacidade / custo / latência ponderados pela política).
O
Resolved-Model do exemplo depende dos candidatos e preços atuais do catalog online e muda conforme os modelos da plataforma entram e saem — e é exatamente esse o valor do roteamento inteligente: você não precisa acompanhar essas mudanças. Para que a decisão seja auditável, baseie-se sempre no nome real do modelo no cabeçalho / corpo da resposta, e não na suposição de que ele é fixo.Políticas de roteamento
Oauto sem sufixo usa a política padrão cost_optimized. Você pode usar auto:<política> para indicar explicitamente a ênfase:
Uma política não é uma “lista fixa de modelos”, mas uma ponderação diferente de capacidade / custo / latência. O
auto primeiro delimita a dimensão da tarefa pelo conteúdo da sua requisição e então escolhe em tempo real o melhor modelo do conjunto de candidatos de centenas de modelos na plataforma conforme a política escolhida — então a mesma política acerta modelos diferentes conforme o conteúdo. A tabela “mesma requisição, políticas diferentes → resultados diferentes” abaixo ilustra exatamente isso; qual modelo vence a cada vez é determinado pelo nome real do modelo nos cabeçalhos de resposta / nos logs do console. Os modelos atualmente no pool e as pontuações por dimensão podem ser consultados pelo endpoint Escopo de Modelos da Estratégia LLM Router.
Para especificar a política, basta adicionar o sufixo ao model:
What is the meaning of life?, todas caindo na dimensão text.overall):
Olatency_criticalescolheu a versão sem-think— variantes de thinking têm latência de raciocínio maior, e a política de baixa latência as evita ativamente. Vê-se que os pesos da política atuam de fato no trade-off entre “capacidade / custo / latência”, e não apenas na capacidade.
O conteúdo também muda o resultado: aplicar o mesmoauto:quality_firstem uma tarefa de código (a requisição do exemplo acima) faz a dimensão mudar detext.overallparatext.coding, com modelo usado medidoclaude-opus-4-6-think— política e conteúdo da requisição determinam juntos o modelo final.
Sufixos de política desconhecidos (como
auto:fast) voltam à política padrão cost_optimized, sem gerar erro.Como funciona
Ao recebermodel=auto, o gateway transforma a “intenção” em “modelo concreto” em três passos:
1
Extrair características da requisição
Analisa as modalidades de entrada / saída desta requisição (texto, imagem, arquivo), a intenção do conteúdo (código, matemática, OCR, gráfico, idioma, se há busca na internet etc.) e a escala da requisição (tokens de entrada / saída estimados), normalizando tudo em uma dimensão de tarefa. Por exemplo: uma pergunta com código →
text.coding; com imagem e pedido de OCR → vision.ocr; texto comum → text.overall.2
Filtro rígido de candidatos
Exclui diretamente os modelos que não atendem às restrições rígidas: não suportam as modalidades de entrada / saída exigidas, a janela de contexto não comporta, foram removidos pelo circuit breaker (veja Confiabilidade e tolerância a falhas) ou não estão no conjunto de modelos disponíveis para a sua Key.
3
Pontuação ponderada pela política
Para os candidatos que passam pelo filtro, com base na pontuação de capacidade dos modelos segundo benchmarks reconhecidos do setor, somando preço em tempo real e dados de desempenho, faz uma pontuação ponderada tridimensional de “capacidade / custo / latência” conforme a política escolhida e seleciona o de maior pontuação. O nome do modelo final é gravado de volta na requisição e nos cabeçalhos da resposta.
quality_first, top 3 do mesmo conjunto de candidatos; dados de exemplo baseados em logs históricos de decisão de produção):
Note que o claude-fable-5 tem a maior pontuação de capacidade (1510), mas, por ter custo mais alto e latência maior, foi rebaixado para terceiro na pontuação composta. É exatamente esse o sentido da pontuação ponderada: não é “só capacidade”, e sim ponderar capacidade / custo / latência conforme a política.
O
claude-fable-5 foi um modelo-base de prévia em fases (staged preview baseline) e agora está descontinuado (deprecated) e não é mais oferecido; sua pontuação histórica é mantida aqui apenas para ilustrar o mecanismo de pontuação ponderada — requisições reais não o acertarão mais.auto, conteúdos diferentes são roteados para dimensões diferentes:
Esses nomes de dimensão vêm de leaderboards autorizados do setor que detalham as capacidades específicas dos modelos; o
auto envia cada tipo de requisição ao modelo mais forte naquela capacidade. Domínios comuns, por exemplo:
- Texto:
text.coding= escrever / depurar código,text.math= resolução matemática,text.longer_query= texto longo,text.language.chinese= chinês,text.occupational.legal/text.occupational.medicine= cenários profissionais jurídicos / médicos. - Visão:
vision.ocr= reconhecer texto em imagens,vision.diagram= entender gráficos / fluxogramas,vision.overall= compreensão geral de imagens.
A entrada de imagem também passa pelo roteamento inteligente: ao enviar imagem em
/v1/chat/completions, a requisição é roteada para modelos com forte capacidade visual conforme a tarefa de imagem. Medição real em produção — «OCR this image» → vision.ocr, modelo usado qwen3.5-397b-a17b; visão genérica «What is in this image?» → vision.overall, modelo usado gpt-5.4-mini. (Aqui refere-se a compreensão de imagem; a geração de imagem /v1/images/* também suporta auto, veja FAQ.)Ranking de Pontuações e Pool de Modelos
O ranking de pontuações de modelos por dimensão e o pool de modelos atual podem ser consultados interativamente na página do LLM Router, ou obtidos diretamente pelos endpoints abertos sem login: Escopo de Modelos da Estratégia LLM Router e Ícones de Fornecedores de Modelos. O ranking exibe o mesmo conjunto que os candidatos de roteamento: apenas modelos atualmente roteáveis aparecem, as pontuações são normalizadas de 0 a 100 dentro de cada dimensão e o ranking é atualizado continuamente com o pool de modelos.Confiabilidade e tolerância a falhas
O roteamento inteligente traz embutidas múltiplas camadas de tolerância a falhas, garantindo que o caminhoauto nunca falhe sem motivo:
Circuit breaker: remoção automática de modelos com falha
Circuit breaker: remoção automática de modelos com falha
O gateway mantém, para cada modelo, uma estatística de taxa de falha em janela deslizante. Quando um modelo acumula falhas suficientes na janela e a taxa de falha ultrapassa o limiar, ele é temporariamente removido do pool de candidatos e, após um período de resfriamento, é restaurado automaticamente — evitando continuar enviando requisições para um modelo que está instável. O sinal de falha vem do erro que o upstream retorna para aquela requisição; o “nenhum canal disponível” do próprio gateway não conta (isso não é problema do modelo em si).
Fallback por ausência de candidatos: nunca retorna 400 no auto
Fallback por ausência de candidatos: nunca retorna 400 no auto
Caso o filtro rígido exclua todos os candidatos (por exemplo, alguma combinação de modalidades sem modelo disponível no momento), o gateway não retorna erro: ele atribui um modelo de fallback conforme o tipo de saída para garantir uma resposta e adiciona o cabeçalho
X-Aihubmix-Router-Fallback: true para você saber.Linha de defesa contra excesso de permissão: Key restrita não é contornada pelo fallback
Linha de defesa contra excesso de permissão: Key restrita não é contornada pelo fallback
Se a sua Key limita o conjunto de modelos disponíveis, o modelo escolhido pelo roteamento inteligente (incluindo o fallback) está sempre dentro desse conjunto. Se realmente não houver nenhum modelo no conjunto capaz de atender a esta requisição, será retornado explicitamente 403, em vez de usar silenciosamente um modelo fora do conjunto (possivelmente mais caro).
Sobre a cobrança
A cobrança é feita pelo preço original do modelo realmente usado; o roteamento inteligente em si não cobra nenhuma taxa adicional. Qual modelo finalmente responder é o que vale para calcular preço, capacidade e limite de contexto — esse modelo é o valor presente no cabeçalhoX-Aihubmix-Router-Resolved-Model e no campo model do corpo da resposta. Em outras palavras, o roteamento inteligente não vai “usar um modelo caro às escondidas”: cada modelo usado fica registrado na resposta e pode ser conciliado item a item.
Limitações
-
O roteamento inteligente é atualmente voltado para a interface de chat completion
/v1/chat/completionse para as interfaces de geração / edição de imagem/v1/images/*(veja FAQ: quais interfaces são suportadas). -
?router=offou o cabeçalhoX-Router-Offfaz omodel=autoretornar diretamente 400 — é uma recusa explícita ao uso ambíguo de “querer auto e ao mesmo tempo desligar o roteamento”, e não uma ignorância silenciosa: -
O conjunto de candidatos muda dinamicamente conforme o catalog da plataforma: o mesmo
autopode usar modelos diferentes em momentos diferentes (isso é por design e pode ser auditado pelos cabeçalhos da resposta). O escopo atual de candidatos pode ser consultado pelo endpoint Escopo de Modelos da Estratégia LLM Router.
Diferenças em relação ao OpenRouter / LiteLLM
“Seleção automática de modelo” não é exclusividade da AIHubMix; OpenRouter e LiteLLM oferecem capacidades semelhantes. As diferenças estão principalmente no custo de integração e no modo de hospedagem:Perguntas frequentes FAQ
P: Quais interfaces o roteamento inteligente suporta? R: Atualmentemodel=auto suporta a interface de chat completion compatível com OpenAI /v1/chat/completions, bem como as interfaces de geração / edição de imagem (/v1/images/generations, /v1/images/edits). Áudio, /v1/embeddings, /v1/rerank e outras interfaces ainda não suportam auto; indique o modelo específico diretamente.
P: O roteamento inteligente suporta entrada de imagem?
R: Suporta. Perguntar com imagem (image_url) em /v1/chat/completions é compreensão de imagem e é roteado para modelos com forte capacidade visual conforme a tarefa de imagem (vision.ocr = reconhecer texto em imagens, vision.diagram = entender gráficos / fluxogramas, vision.overall = compreensão geral de imagens, etc.). A geração de imagem também suporta auto: defina model como auto nas interfaces /v1/images/* e a requisição é roteada pelas dimensões de geração de imagem (por exemplo, text_to_image.overall).
P: Como sei qual modelo foi de fato usado nesta requisição?
R: Veja o cabeçalho X-Aihubmix-Router-Resolved-Model ou o campo model do corpo da resposta — ambos são preenchidos com o nome real do modelo. Veja Como confirmar o modelo realmente usado.
P: O roteamento inteligente usa modelos caros às escondidas?
R: Não. A política padrão cost_optimized é custo prioritário; além disso, cada modelo usado fica registrado na resposta e é cobrado pelo seu preço original, podendo ser conciliado item a item. Veja Sobre a cobrança.
P: Como controlar / estimar o custo?
R: Três recursos combinados — ① o auto padrão (cost_optimized) já é custo prioritário; ② use o conjunto de modelos disponíveis da Key para travar os candidatos na faixa de preço que você aceita, o que equivale a definir um teto de custo; ③ cada modelo usado é cobrado pelo preço original do modelo do cabeçalho Resolved-Model, podendo ser conciliado item a item. Quando precisar de mais capacidade, use explicitamente auto:quality_first.
P: Qual a diferença entre auto e “mapeamento de modelos / fallback”?
R: O mapeamento de modelos / fallback é alias fixo em nível de Key + fallback ordenado em caso de falha (sempre o mesmo destino); o roteamento inteligente é seleção dinâmica de modelo conforme o conteúdo de cada requisição. O primeiro resolve “o cliente só reconhece um certo nome / o modelo principal caiu e troca pelo backup”, o segundo resolve “não me importa qual seja, me dê o mais adequado”.
P: É possível limitar o roteamento inteligente a escolher apenas entre alguns modelos?
R: Sim — por meio do conjunto de modelos disponíveis da Key: o roteamento inteligente só escolhe entre os modelos permitidos para aquela Key, e modelos fora do conjunto não serão usados.
P: Requisições em streaming são suportadas?
R: Suportadas. O roteamento é concluído antes de a requisição chegar ao upstream e trata streaming / não-streaming da mesma forma.
P: Por que duas chamadas com a mesma frase usaram modelos diferentes?
R: O conjunto de candidatos e os preços mudam dinamicamente conforme o catalog da plataforma; isso é por design. Use o Decision-Id e o Resolved-Model dos cabeçalhos para auditar cada decisão. O escopo atual de candidatos pode ser consultado pelo endpoint Escopo de Modelos da Estratégia LLM Router.
P: Como fazer a requisição usar de forma estável sempre o mesmo modelo (por exemplo, para reaproveitar o cache de prompt)?
R: O auto seleciona o modelo dinamicamente conforme o catalog atual e não garante determinismo. Se você precisa usar de forma estável o mesmo modelo (por exemplo, dependendo do cache de prompt do upstream ou para reprodução estrita), indique diretamente o nome do modelo específico ou use a Key para limitar o conjunto disponível a um único modelo — nessas duas formas o modelo usado é determinístico.
Recursos relacionados
- Mapeamento de modelos e fallback: alias fixo em nível de Key + fallback em caso de falha, complementar ao roteamento inteligente.
- Parâmetros de inferência unificados: parâmetros de requisição consistentes entre modelos.
- Página de modelos da AIHubMix: consulte nome do modelo, preço e
Input Modalities. - Escopo de Modelos da Estratégia LLM Router: acesso sem login ao subconjunto público de 23 subdimensões (das 30+ dimensões de roteamento) e ao pool de modelos roteáveis.