Gerenciar canais no AI Gateway

Um «Canal (Channel)» é a configuração de um ponto de acesso de provedor no AI Gateway — ele armazena o endereço de um provedor, a chave de API real, os modelos disponíveis e informações como precificação e cota. É com base nesses canais que o gateway roteia as requisições enviadas pelo aplicativo para o provedor correspondente. Este artigo explica como adicionar, configurar, testar e gerenciar canais.

Pré-requisitos

• ServBay instalado e em execução, com login feito na conta ServBay (é necessário estar logado antes de adicionar canais).
• A chave de API real do provedor desejado já preparada (provedores locais como Ollama / LM Studio podem ficar sem preencher).
• Caso ainda não conheça a arquitetura geral do AI Gateway, recomenda-se ler primeiro Introdução ao AI Gateway.

Adicionar um canal

Acesse a página AI Gateway → Canais (Channels) e clique em Adicionar (Add) para abrir o assistente. O assistente é dividido em três etapas.

Etapa 1: Selecionar o provedor

Os provedores são exibidos agrupados por categoria. Basta clicar no cartão para selecionar:

• Principais (Mainstream): OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• China (China): DeepSeek, Qwen, Zhipu GLM, Kimi, Doubao·Volcano, ERNIE, Hunyuan, MiniMax, 01.AI, StepFun.
• Locais (Local): Ollama, LM Studio.
• Personalizados (Custom): OpenAI Compatible, Custom.

Após selecionar o provedor, o gateway preenche automaticamente o Base URL padrão desse provedor.

Alternância entre duas regiões

Provedores chineses como Qwen, Zhipu GLM, Kimi, Doubao·Volcano, Hunyuan, MiniMax e StepFun oferecem dois conjuntos de endpoints: doméstico e global. Ao selecionar esse tipo de provedor, o assistente exibe um seletor de «Região» (🇨🇳 Doméstico / 🌐 Global). Ao alternar, o Base URL é atualizado automaticamente para o endereço da região correspondente.

Etapa 2: Preencher a configuração

• Nome do canal (obrigatório) — usado para identificar o canal na lista; pode ser personalizado.
• Base URL (obrigatório) — endereço da API do provedor. Para a maioria dos provedores já é preenchido automaticamente; Azure OpenAI e Custom exigem preenchimento manual.
• API Key (opcional) — a chave real do provedor. Se deixada em branco, só será possível testar se o endpoint é acessível, sem validar a chave; provedores locais (Ollama / LM Studio) geralmente não precisam dela.
• Modelos — há duas formas; escolha uma:
  • Descoberta automática: ao clicar em descobrir, o gateway chama a interface de listagem de modelos do provedor para obter os modelos disponíveis, e você seleciona vários no formato de etiquetas (chips).
  • Preenchimento manual: digite o nome do modelo diretamente. Canais do Azure exigem o nome da implantação (Deployment name) em vez do nome do modelo.
• Prioridade / Peso — quando vários canais podem atender o mesmo modelo, o gateway usa isso para decidir o roteamento e a distribuição de carga.

Atenção com Azure OpenAI

No campo «Modelos» do canal Azure, preencha o nome da implantação (Deployment name) criado no portal do Azure, e não o nome do modelo subjacente. O Base URL também deve conter o endpoint do seu recurso do Azure.

Etapa 3: Confirmar e enviar

Revise o resumo da configuração e envie. Após o envio bem-sucedido, o novo canal aparecerá na lista de canais, exibindo seu status de saúde em tempo real.

Sondagem de capacidade e estratégia de roteamento

Após adicionar um canal, o gateway realiza uma sondagem de capacidade (capability probing) nesse canal — este é o mecanismo de roteamento inteligente mais central do AI Gateway. O resultado da sondagem determina se ferramentas como o Claude Code podem ser usadas diretamente ou se é necessário criar mapeamentos de modelos, além de definir como escolher o modelo de destino.

Duas métricas-chave da sondagem

O gateway sonda dois fatos centrais em cada canal (ambos trinários: true / false / não determinado):

Item sondado	Significado	true	false	Não determinado
Reconhece nomes de modelos Claude (accepts_claude_names)	Se o canal reconhece nativamente nomes de modelos como claude-opus-* / claude-sonnet-* / claude-haiku-*	Conexão direta, sem necessidade de mapeamento	Não reconhece; é obrigatório criar mapeamento traduzindo os nomes claude-* para os nomes reais dos modelos no upstream	A sondagem não foi executada ou falhou; não é possível concluir
Diferencia por nível (tier_aware)	Se o upstream retorna modelos diferentes por nível (opus / sonnet / haiku)	O upstream já diferencia os níveis; basta deixar que ele trate disso	Não diferencia (retorna o mesmo modelo para todos os níveis); é necessário que o gateway crie mapeamentos	Não é possível sondar ou nunca foi sondado

Por que sondar em vez de adivinhar

O comportamento varia muito entre provedores. O OpenAI não reconhece nativamente nomes de modelos claude-*; alguns provedores intermediários reconhecem por encaminhamento; e provedores de pacotes de codificação (como as assinaturas Claude Pro/Max) podem reconhecer apenas nomes específicos de modelos vinculados à assinatura. O gateway não adivinha com base no tipo de canal: ele sonda na prática e só então decide a estratégia de roteamento.

Decisão de roteamento: cinco estados

Quando você faz a «tomada de controle com um clique» do Claude Code em AI Gateway → Gerenciamento de acesso → página de clientes, o gateway agrega os resultados de sondagem de todos os canais candidatos e produz uma decisão de roteamento:

Estado dos canais candidatos	Decisão	Significado
Nenhum canal candidato disponível (sem canais / todos indisponíveis / sem canais no escopo da chave virtual)	Sem canais candidatos	É preciso adicionar ou corrigir canais primeiro
O valor de sondagem de qualquer canal candidato está não determinado	Não detectado	É preciso executar uma sondagem primeiro; não se pode criar mapeamentos sem verificação prévia
Todos os canais candidatos reconhecem nomes de modelos claude	Conexão direta	Não criar mapeamento; a requisição é encaminhada como está
Todos os canais candidatos não reconhecem nomes de modelos claude	Mapeamento obrigatório	O gateway cria mapeamentos para os três níveis, traduzindo claude-* para os nomes reais dos modelos no upstream
Há canais que reconhecem e canais que não reconhecem entre os candidatos	Misto	Requer decisão manual (os que reconhecem vão direto; os que não reconhecem usam mapeamento)

Mapeamento de modelos: traduzir claude-* para os nomes reais dos modelos no upstream

Quando a decisão é «mapeamento obrigatório», o gateway cria três regras de mapeamento de modelos para o Claude Code, cobrindo os três níveis:

Nome do modelo enviado pelo Claude Code	Regra de mapeamento (curinga)	Mapeia para
claude-opus-*	Corresponde a todas as requisições do nível opus	O modelo principal entre os canais candidatos
claude-sonnet-*	Corresponde a todas as requisições do nível sonnet	O modelo principal ou o modelo padrão entre os canais candidatos
claude-haiku-*	Corresponde a todas as requisições do nível haiku	O modelo leve entre os canais candidatos

Regras de seleção do modelo de destino (com fallback por prioridade):

1. Predefinição por família: se aparecer nos modelos candidatos uma palavra-chave de família conhecida (como glm), use diretamente o modelo principal dessa família (como glm-5.2) como destino dos níveis opus/sonnet, e o modelo leve dessa família (como glm-4.7-flash) como destino do nível haiku.
2. Correspondência por palavra-chave: na ausência de predefinição por família, opus/sonnet usam o primeiro modelo da lista de candidatos; haiku usa o primeiro modelo da lista que corresponda a uma palavra-chave leve (flash / mini / lite / air / small / turbo / haiku).
3. Fallback final: se ainda não houver correspondência, os três níveis usam o primeiro modelo da lista de candidatos.

Errar a configuração do nível haiku é o mais custoso

O nível haiku do Claude Code tem o maior volume de chamadas (todas as chamadas leves de cada conversa o utilizam). Se um modelo principal for colocado por engano no nível haiku, a fatura pode multiplicar várias vezes. A tabela de correspondência de palavras-chave do gateway cobre 7 sufixos leves (flash / mini / lite / air / small / turbo / haiku), garantindo que modelos pesados não sejam colocados no nível haiku.

Mecanismo de gravação dos mapeamentos

Após a confirmação da tomada de controle, o gateway grava os registros de mapeamento pela API /admin/model-mappings. Cada registro de mapeamento contém:

• Protocolo de origem (source_protocol): anthropic (as requisições enviadas pelo Claude Code estão no formato Anthropic)
• Correspondência do modelo de origem (source_model_pattern): curinga, como claude-opus-*
• Protocolo de destino (target_protocol): openai (convertido uniformemente para o formato OpenAI antes de enviar ao upstream)
• Modelo de destino (target_model): o nome específico do modelo selecionado pela sondagem

A gravação é idempotente — repetir a tomada de controle não gera mapeamentos duplicados; antes de gravar, a lista atual de mapeamentos é obtida para comparação.

Regras de roteamento em tempo de execução: failover e degradação

Além dos mapeamentos estáticos gravados na fase de tomada de controle, o gateway também oferece suporte a regras de roteamento em tempo de execução (routing rules), que decidem dinamicamente enquanto as requisições passam pelo gateway:

Campo da regra	Função
Condição de disparo (condition_type)	Quando acionar a degradação, por exemplo, esgotamento da cota do canal (quota_exhausted)
Limite de custo (cost_threshold_usd)	Opcional: acionado quando o custo acumulado do canal ultrapassa o limite
Ação (action_type)	O que fazer após o disparo, por exemplo, alternar para um canal de reserva especificado (switch_to)
Canal de destino (target_channel_id)	O canal de reserva para o qual degradar
Modelo de destino (target_model)	Opcional: alternar também o modelo ao degradar para o canal de reserva

Combinando várias regras de roteamento, você pode implementar cenários como: alternar automaticamente para o endpoint de pagamento por uso do canal B quando a cota da assinatura do canal A se esgotar; ou degradar para um modelo mais barato quando o custo de 24 horas de um canal ultrapassar o limite.

Balanceamento de carga e prioridade

Quando vários canais saudáveis podem atender o mesmo modelo, o gateway escolhe segundo as estratégias a seguir:

• Modo por prioridade (padrão): usa apenas o canal de maior prioridade; entre canais de mesma prioridade, o gateway distribui conforme pesos internos.
• Modo rodízio (round_robin): alterna as requisições entre todos os canais candidatos saudáveis.

A prioridade é definida na configuração do canal (quanto maior o número, maior a prioridade), e o allowed_channels da chave virtual delimita o escopo dos canais disponíveis.

Teste de conectividade

Na lista de canais, é possível testar a conectividade de um canal individual. O teste tem duas dimensões:

• Acessibilidade do endpoint (reachable) — verifica se o Base URL é acessível (se a rede e o endereço estão corretos).
• Validade da chave (authenticated) — chama de fato a interface do provedor para verificar se a API Key é válida. Só é verificado se uma API Key tiver sido preenchida.

O resultado do teste exibe: latência de ida e volta (milissegundos), selo de status e mensagem de erro.

TIP

No assistente de adição, se o endpoint não estiver acessível, você será impedido de avançar para a próxima etapa; se o endpoint estiver acessível mas a chave for inválida, será exibido apenas um aviso e você ainda poderá continuar (por exemplo, se pretende adicionar a chave depois).

Configuração avançada

Ao adicionar ou editar um canal, é possível expandir a configuração avançada, usada para cálculo de custos e controle de cotas:

• Multiplicador de preço (Rate Multiplier) — multiplica o preço oficial do provedor por um fator, facilitando o cálculo com base no seu custo real ou preço de revenda; padrão 1.0.
• Estrutura de cobrança — descreve a forma de cobrança do canal, como pagamento por uso (pay as you go), assinatura (subscription) ou pacote (package).
• Saldo — a origem do saldo pode ser um valor fixo, fatura OSS ou manutenção manual; ao escolher fatura OSS, também é possível especificar o tipo de fatura. O saldo e o horário de atualização são exibidos somente para leitura nos detalhes do canal.
• Data de vencimento da assinatura — canais do tipo assinatura / pacote podem registrar a data de vencimento.
• Limite de cota — é possível definir um teto por número de tokens, número de requisições ou valor, escolhendo o período (diário / semanal / mensal / personalizado). Quando a cota se esgota, o canal é automaticamente excluído da seleção de rotas, funcionando como uma válvula de segurança contra gastos inesperados.

Editar e excluir canais

• Editar — abra um canal na lista de canais para modificar o nome, o Base URL, a API Key, os modelos e a configuração avançada.
• Excluir — após excluir um canal, as chaves virtuais que dependem dele não poderão mais rotear para ele; proceda com cautela.

Status de saúde

A lista de canais e a página de visão geral exibem em tempo real o status de saúde de cada canal (normal / degradado / indisponível), ajudando você a identificar rapidamente configurações de provedor com falha.

Perguntas frequentes (FAQ)

• P: Ao adicionar um canal, aparece uma mensagem pedindo login?
  • R: O AI Gateway é um recurso de valor agregado do ServBay. Antes de adicionar canais / chaves, é necessário fazer login na conta ServBay; basta seguir as instruções na interface.
• P: Aparece uma mensagem dizendo que o número de canais atingiu o limite?
  • R: O número de canais que podem ser criados depende do plano da conta. Ao atingir o limite, você pode excluir canais não utilizados ou fazer upgrade do plano.
• P: A descoberta automática de modelos não retorna a lista?
  • R: Primeiro, confirme que o Base URL está correto e a API Key é válida (pode usar «Validade da chave» do teste de conectividade para verificar). Alguns provedores exigem uma chave válida para retornar a lista de modelos; alternativamente, você pode preencher o nome do modelo manualmente.
• P: É necessário preencher uma Key para integrar o Ollama / LM Studio local?
  • R: Normalmente não. Basta garantir que o serviço local correspondente esteja em execução e ouvindo a porta padrão (Ollama 11434, LM Studio 1234).

Resumo

Os canais são a base do roteamento de requisições do AI Gateway. Com o assistente de três etapas, você pode integrar rapidamente quase 20 provedores, contando com a alternância entre duas regiões, a descoberta automática de modelos e o teste de conectividade em duas dimensões para garantir que a configuração esteja correta, além de gerenciar custos com precisão usando configurações avançadas como precificação e cota. Depois de configurar os canais, você já pode criar Chaves virtuais para uso por aplicativos e ferramentas.