Roteamento e seleção de modelos: a relação entre canais, modelos e clientes
Ao usar o AI Gateway, é fácil confundir três conceitos: canais, modelos e clientes. Entender a relação entre eles ajuda você a configurar o roteamento corretamente e evita dúvidas do tipo "por que minha requisição não passou pelo canal que eu esperava".
Os três conceitos básicos
- Canal é uma conexão upstream: uma instância do Ollama ou uma conta de provedor de nuvem.
- Modelo é uma capacidade disponível em um canal: por exemplo, um nome de modelo específico como
qwen3:8b. - Cliente é a ferramenta de IA que você usa no dia a dia: Claude Code, Codex, opencode, entre outras.
A relação entre eles forma uma cadeia unidirecional:
Cliente → (chave virtual) → Gateway (política de roteamento) → Canal → Modelo
Em cada requisição, o cliente especifica o nome do modelo, e o gateway, com base nesse nome, encontra o canal capaz de atendê-la e encaminha a requisição para lá.
O que significa "modelo (nome do canal)" na lista de modelos
No seletor de modelos de clientes como Claude Code e opencode, você verá entradas como qwen3:8b (Ollama Qwen3). O nome entre parênteses indica o canal de origem desse modelo, e não "outra conexão":
- Entre o seu cliente e o gateway há sempre apenas uma conexão (um endereço + uma chave virtual).
- O mesmo modelo também pode estar configurado em vários canais. Nesse caso, o seletor continua exibindo apenas uma linha (os parênteses mostram um dos canais de origem); qual canal de fato atende a cada requisição é determinado pela política de roteamento (veja abaixo).
Os três modos de roteamento: Fixed, Failover e Balanced
A pergunta que a política de roteamento responde é: quando vários canais podem atender o mesmo modelo, qual usar?
| Modo | Comportamento | Cenários adequados |
|---|---|---|
| Fixed (fixo) | Usa sempre o mesmo canal | Qualidade de canal estável, quando se deseja fixar a origem |
| Failover (principal/backup) | Quando o canal principal falha ou fica sem cota, alterna em ordem para os canais de backup | Configurações com canal principal e reserva |
| Balanced (equilibrado) | Distribui as requisições de forma alternada entre os canais disponíveis | Vários canais equivalentes para dividir a carga |
Dois limites importantes:
- O roteamento alterna apenas entre canais, não entre modelos. Qual modelo solicitar é sempre decidido pelo seu cliente; o gateway não troca o modelo por você.
- Modelos diferentes já usam naturalmente seus próprios canais. O Balanced não faz "desta vez o modelo do canal A, da próxima o do canal B" — ele alterna apenas entre os canais de um mesmo modelo.
O modelo é decidido pelo cliente: como trocar de modelo
O gateway apenas encaminha: sua ferramenta inclui o nome do modelo em cada requisição, e o gateway faz o roteamento de acordo. A troca de modelo acontece no cliente:
- opencode: digite
/modelsna TUI para selecionar; ou configuremodel(modelo principal) esmall_model(tarefas leves, como geração de títulos) noopencode.json. - Claude Code: use o comando
/modelpara alternar. - Codex: especifique com o parâmetro
-m <model>ou no arquivo de configuração.
Conectando suas ferramentas do dia a dia ao gateway com segurança
Preocupado em afetar seu uso cotidiano? Siga este processo:
- Teste primeiro em um projeto secundário: faça a conexão com um clique em um diretório de projeto pouco importante e confirme se o fluxo de trabalho funciona normalmente.
- Valide com uma requisição: envie uma requisição de teste e vá até a página "Histórico de uso" para verificar em qual modelo e em qual canal ela caiu e qual foi o custo.
- Volte atrás quando quiser: interrompa o takeover na página "Gerenciamento de conexões". Após a interrupção: as configurações gravadas pelo ServBay serão removidas e as chaves virtuais criadas pelo takeover serão revogadas; suas configurações personalizadas anteriores não serão restauradas automaticamente — ajuste manualmente, se necessário; a mudança entra em vigor após reiniciar o cliente.
Resumo
- Canal = conexão upstream; modelo = capacidade em um canal; o nome do modelo é especificado pelo cliente em cada requisição.
- A política de roteamento escolhe apenas entre "os canais de um mesmo modelo": Fixed fixa, Failover alterna principal/backup, Balanced reveza.
- Troque de modelo no seletor de modelos do cliente; confira o destino e o custo de cada requisição na página "Histórico de uso".
