Provedores e modelos de IA: o que configurar primeiro
O passo a passo do cadastro de provedor e modelo, os erros de ambiente que mais aparecem e por que o teste de conexão vem antes de qualquer outra coisa.
Perdi uma manhã inteira achando que a configuração de provedores e modelos de IA estava errada. Refiz o cadastro três vezes, troquei a chave, apaguei e criei de novo. O problema era SSL local ausente na chamada de catálogo do meu ambiente de desenvolvimento. Nada a ver com o que eu estava mexendo.
Se tivesse rodado o teste de conexão logo no começo, a manhã teria sido outra. Hoje é a primeira coisa que faço, antes de cadastrar qualquer modelo.
Vou percorrer o cadastro na ordem, com os pontos de tropeço que eu conheço de perto. Para entender onde essas peças se encaixam, veja a visão geral da Central de IA.
Cadastrando provedores e modelos de IA na ordem
- Cadastre o provedorInforme a credencial e a configuração extra que aquele fornecedor exige. Nada de modelo ainda.
- Rode o teste de conexãoAntes de tudo. Se falhar aqui, o problema é credencial ou ambiente, e não adianta seguir em frente.
- Liste os modelos disponíveisA tela busca o catálogo do provedor. É onde você confirma que a credencial tem alcance de verdade.
- Cadastre o modeloVincule ao provedor, defina a categoria e ajuste temperatura, top-p e limites quando o caso permitir.
- Só então crie o agenteCom provedor testado e modelo cadastrado, a tela de agente para de parecer um formulário sem sentido.
Parece óbvio escrito assim. Não foi óbvio para mim na primeira vez, quando comecei pelo agente e fui voltando de tela em tela tentando entender o que faltava.
Quem o gateway atende
O gateway trabalha com Gemini, OpenAI, Anthropic e provedores compatíveis com a API da OpenAI, categoria que inclui Groq, OpenRouter, Ollama e LM Studio. Os dois últimos abrem a porta para rodar modelo local, o que muda bastante a conversa sobre dado sensível.
- Gemini, com tratamento próprio para os nomes de modelo
- OpenAI, com API Key como configuração estável
- Anthropic, pelo cadastro de provedor
- Compatíveis com API OpenAI: Groq, OpenRouter, Ollama e LM Studio
O tratamento de nomes de modelo do Gemini existe porque a nomenclatura dele tem particularidades. Se você digitar o nome de cabeça e ele não aparecer, use a listagem da tela em vez de brigar com o campo.
A API Key que não some
Ao editar um provedor sem trocar o valor da chave, a API Key é preservada. Demorei para confiar nisso e ficava com a credencial aberta num arquivo ao lado, com medo de perder acesso ao ajustar qualquer campo.
Isso muda a rotina de manutenção: dá para ajustar configuração extra, revisar limites e corrigir nome sem envolver quem guarda a credencial. Menos gente circulando com chave na mão é um ganho de segurança que nem sempre aparece na conversa.
Erros de ambiente que confundem
Boa parte dos problemas de IA que me chegaram não estava na IA. Estava no ambiente entre o servidor e o provedor. Reconhecer o padrão economiza tempo e evita aquela sensação de estar caçando fantasma.
| Sintoma | Causa provável | Por onde começar |
|---|---|---|
| Catálogo de modelos vazio | SSL local ausente no ambiente | Teste de conexão e configuração do servidor |
| Credencial recusada | Chave inválida, expirada ou sem permissão | Regenerar no provedor e recadastrar |
| Modelo do Gemini não encontrado | Nome digitado fora do formato esperado | Usar a listagem de modelos da tela |
| Funciona em um ambiente e no outro não | Configuração extra diferente entre eles | Comparar provedor a provedor, campo a campo |
O OAuth do ChatGPT é experimental
Existe autenticação assistida com ChatGPT por OAuth e PKCE como alternativa à API Key. Leia essa frase com atenção: é experimental, não representa integração oficial garantida para aplicativos de terceiros e pode deixar de funcionar.
Uso isso para experimentar rápido e nunca para sustentar atendimento em produção. A configuração estável da OpenAI continua sendo a API Key, e essa é uma daquelas decisões em que economizar cinco minutos hoje custa um dia depois.
Ajustando temperatura e limites
O modelo aceita temperatura, top-p e limites quando o caso permite, e o agente também tem os próprios ajustes, incluindo max turns. Mexer nos dois lugares ao mesmo tempo é o caminho mais rápido para não entender mais nada.
Meu jeito: fixo o modelo, mexo só no agente e comparo respostas do meu próprio negócio. Nada de exemplo genérico. O critério de configuração do agente está em templates de skill e prompt de agente, e os limites de uso responsável em governança de IA.
Antes de soltar no atendimento
Provedor testado, modelo cadastrado, agente com escopo pequeno e fallback humano configurado. Só depois disso o bloco Agente entra num fluxo que fala com cliente, e mesmo assim com alguém acompanhando. Se a jornada toca pedido ou pagamento, combine antes com quem cuida do controle financeiro, porque resposta errada nessa área custa dinheiro de verdade.