Gerenciamento de Canais no AI Gateway

Um canal (Channel) é a configuração de um ponto de acesso de fornecedor no AI Gateway — ele armazena o endereço do fornecedor, autenticação real (API Key), modelos disponíveis, informações de preços, limites e outros dados importantes. O gateway usa esses canais para rotear as solicitações do aplicativo para o fornecedor correspondente. Este artigo ensina como adicionar, configurar, testar e gerenciar canais.

Pré-requisitos

• ServBay já está instalado e em execução, com uma conta ServBay conectada (é necessário login antes de adicionar canais).
• Você tem em mãos uma API Key válida do fornecedor desejado (para fornecedores locais como Ollama / LM Studio não é obrigatório).
• Caso ainda não conheça a arquitetura do AI Gateway, recomenda-se ler primeiro a Introdução ao AI Gateway.

Adicionando um Canal

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

Passo 1: Escolha do Fornecedor

Os fornecedores aparecem organizados por categoria; selecione clicando na respectiva opção:

• Principais (Mainstream): OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• China: DeepSeek, Qwen, Zhipu GLM, Kimi, Doubao·Volcano, Wenxin Yiyan, Hunyuan, MiniMax, Zero One, StepStar.
• Local: Ollama, LM Studio.
• Personalizado (Custom): OpenAI Compatible, Custom.

Após selecionar o fornecedor, o gateway preenche automaticamente o Base URL padrão do fornecedor.

Alternância de Dupla Região

Fornecedores chineses como Qwen, Zhipu GLM, Kimi, Doubao·Volcano, Hunyuan, MiniMax e StepStar oferecem endpoints separados para China e Global. Ao escolher estes fornecedores, um seletor de região aparecerá (🇨🇳 China / 🌐 Global), atualizando automaticamente o Base URL de acordo com a região selecionada.

Passo 2: Preencha a Configuração

• Nome do Canal (obrigatório) — Identifica o canal na lista, pode ser personalizado.
• Base URL (obrigatório) — Endereço da API do fornecedor. Já vem preenchido para a maioria dos fornecedores; para Azure OpenAI e Custom é necessário inserir manualmente.
• API Key (opcional) — Chave de autenticação do fornecedor. Se deixado em branco, só será possível testar a conexão do endpoint, não a validade da chave; para fornecedores locais (Ollama / LM Studio) normalmente não é exigida.
• Modelos — Duas opções disponíveis (escolher uma):
  • Descoberta automática: Clique para que o gateway recupere, via API, a lista de modelos disponíveis do fornecedor; selecione múltiplos por etiqueta (chip).
  • Preenchimento manual: Digite o nome do modelo desejado. Para canais Azure, é necessário informar o nome da instância (Deployment name) ao invés do nome do modelo.
• Prioridade / Peso — Quando vários canais são compatíveis com o mesmo modelo, o gateway usa esses parâmetros para definir o roteamento e a divisão de carga.

Atenção para Azure OpenAI

No canal Azure, o campo "Modelos" deve ser o nome da instância (Deployment name) criado no portal Azure, e não o nome do modelo. O Base URL também deve ser o endpoint do seu recurso Azure.

Passo 3: Confirme e Envie

Cheque o resumo da configuração e envie. Ao finalizar, o novo canal aparece na lista, exibindo seu status de saúde em tempo real.

Teste de Conectividade

Na lista de canais é possível testar individualmente a conectividade de cada canal, avaliando dois aspectos:

• Acessibilidade do endpoint (reachable) — Verifica se o Base URL está acessível (rede e endereço certos).
• Validação da chave (authenticated) — Faz uma chamada real à API do fornecedor para checar se o API Key é válido. Só será feito se a API Key for informada.

Os resultados do teste exibem: latência (ms), ícone de status e mensagens de erro.

TIP

No assistente de configuração, se o endpoint não for acessível, não será possível avançar. Se o endpoint estiver ok, mas a chave for inválida, um alerta será exibido permitindo prosseguir (caso deseje inserir a chave depois, por exemplo).

Configurações Avançadas

Durante a criação ou edição do canal, é possível expandir as configurações avançadas para controle de custos e limites:

• Multiplicador de preço (Rate Multiplier) — Multiplica automaticamente o preço oficial do fornecedor, ajustando para custo real ou preço de revenda. O valor padrão é 1.0.
• Estrutura de cobrança — Define o método de cobrança do canal, como pós-pago (pay as you go), assinatura (subscription) ou pacote (package).
• Saldo — Origem do saldo: valor fixo, conta OSS ou manutenção manual. Se for OSS, é possível definir o tipo de conta. Informações de saldo são exibidas apenas leitura no detalhe do canal.
• Validade da assinatura — Para canais por assinatura/pacote, registre aqui a data de expiração.
• Limite de cota (VIP) — Defina limites por tokens, quantidade de requisições ou valor em dinheiro, especificando o ciclo (diário, semanal, mensal, personalizado). Há opção de permitir uso acima do limite dentro de uma certa tolerância. O controle de cota é um recurso pago.

Editar e Excluir Canal

• Editar — Abra o canal na lista para alterar nome, Base URL, API Key, modelos ou configurações avançadas.
• Excluir — Após excluir um canal, as chaves virtuais que dependiam dele não poderão mais rotear solicitações para esse fornecedor. Tenha cuidado ao excluir.

Status de Saúde

A lista de canais e a página de visão geral mostram em tempo real o status de cada canal (Normal / Degradado / Indisponível), ajudando você a identificar rapidamente configurações de fornecedor que falhem.

Perguntas Frequentes (FAQ)

• Q: Preciso fazer login para adicionar canal?
  • A: O AI Gateway é uma funcionalidade premium do ServBay. É necessário estar logado para adicionar canais/chaves. Siga as instruções na tela para login.
• Q: Aparece aviso de que o número máximo de canais foi alcançado?
  • A: O número de canais permitidos depende do seu plano ServBay. Para adicionar mais, exclua canais não utilizados ou faça um upgrade no plano.
• Q: A descoberta automática de modelos não retorna lista?
  • A: Verifique se o Base URL está correto e se a API Key informada é válida (use o teste de conectividade — "validação de chave"). Alguns fornecedores exigem chave válida para retornar a lista de modelos. Se necessário, insira os nomes dos modelos manualmente.
• Q: Preciso informar API Key para conectar Ollama / LM Studio local?
  • A: Normalmente não é necessário. Apenas garanta que os serviços locais estejam em execução e escutando as portas padrão (Ollama 11434, LM Studio 1234).

Resumo

Canais são a base para roteamento no AI Gateway. Usando o assistente de três etapas, você pode rapidamente conectar quase 20 fornecedores, alternar entre regiões, utilizar descoberta automática de modelos e validar conexões. Além disso, possibilita controles sofisticados de custo, limite e saldo. Quando tudo estiver configurado, é só criar chaves virtuais para uso em seus aplicativos e ferramentas.