No mês passado, acompanhei um colega recém-transferido na construção de um protótipo de atendimento inteligente. O requisito era simples: o usuário pergunta, o modelo responde, com um pouco de memória de contexto e capacidade de digitação em streaming. Parecia algo que se resolveria em dois dias, mas ele tropeçou na chave de API hardcoded, na lógica de retry e na integração de streaming, cada um deles uma vez. Organizei todo o processo neste artigo, para ser lido como anotações de onboarding de novos membros.
Primeiro passo: decompor os requisitos antes de escolher o modelo
Não comece escrevendo código. As necessidades de capacidade de um atendimento inteligente se dividem basicamente em três partes: reconhecimento de intenção, perguntas e respostas sobre conhecimento e conversa informal em múltiplos turnos. O reconhecimento de intenção precisa ser rápido e barato; usar a API do DeepSeek-V3 ou do Qwen já é suficiente. As perguntas e respostas sobre conhecimento envolvem seus documentos privados, exigindo RAG, e o modelo precisa entender contextos longos. A conversa informal em múltiplos turnos tem alta exigência de tom; Claude 4 Sonnet ou GPT-4o são mais estáveis.
Minha abordagem foi primeiro fazer o fluxo funcionar com um modelo genérico e depois substituir item por item. O roteamento multi-modelo da SiCore TokenWorks economiza trabalho nesse momento: o mesmo código troca o nome do modelo e você compara os resultados, sem alterar a autenticação. A escolha da API de grandes modelos não é escolher a mais forte, mas a que melhor se adapta à tarefa.
Segundo passo: gerenciamento de chaves, não coloque no código
Colocar a chave hardcoded no código-fonte é o erro mais comum entre os novatos. Uma vez commitado no git, é como torná-la pública. A prática correta é usar variáveis de ambiente com configuração em camadas: localmente use .env, e em teste e produção use um centro de configuração ou serviço de gerenciamento de segredos.
Para o isolamento entre múltiplos ambientes, lembre-se de três pontos: use chaves diferentes para desenvolvimento, teste e produção; defina um limite de cota independente para cada chave; a chave de produção só vai para o servidor, o frontend nunca a recebe. No nosso projeto usamos a SiCore TokenWorks: uma única chave dá acesso a GPT-4o, Claude, DeepSeek, Qwen, ERNIE, Doubao e outros modelos mainstream, economizando o trabalho de manter vários conjuntos de autenticação, e trocar de chave entre ambientes é só mudar uma variável.
Terceiro passo: encapsulamento de chamadas e retry de erros
Código que chama o SDK cru não é sustentável. Encapsule uma camada para tratar uniformemente timeout, rate limiting e retry. A ideia é esta: envolver a chamada do modelo em uma função cujos parâmetros são messages e o nome do modelo, capturando internamente três tipos de erro — timeout de rede, rate limit 429 e erro de servidor 5xx.
A estratégia de retry usa backoff exponencial: espera 1 segundo na primeira vez, 2 segundos na segunda, 4 segundos na terceira, no máximo três vezes. O 429 precisa de tratamento especial; observe o header retry-after retornado. Não faça retry de todos os erros; retentar um erro de parâmetro cem vezes não adianta nada. O valor do gateway de modelos está justamente nessa camada, concentrando retry, degradação e logs em um só lugar, enquanto o código de negócio só se preocupa em obter o resultado.
Alerta de armadilha: o retry precisa ser idempotente. Se a chamada tem efeitos colaterais (como gravar no banco de dados), confirme antes se a última tentativa realmente falhou.
Quarto passo: saída em streaming e integração com o frontend
O núcleo da experiência de atendimento é o "efeito máquina de escrever". O servidor usa SSE para enviar os tokens bloco a bloco ao frontend, e o frontend recebe com EventSource ou o ReadableStream do fetch.
Pontos-chave no backend: definir stream=True, analisar bloco a bloco o delta retornado e encerrar ao encontrar [DONE]. Pontos-chave no frontend: não faça setState a cada caractere recebido; acumule de 20 a 50 milissegundos e renderize em lote, caso contrário a página trava como um slide.
Há ainda outra armadilha: durante o streaming, o usuário pode fechar a página. O servidor precisa escutar o evento de desconexão e cancelar a tempo a requisição upstream, senão é token queimado à toa. Com cobrança por uso, esse desperdício se acumula.
Quinto passo: monitoramento de custos e alertas
Antes de ir para produção, é obrigatório instrumentar. Registre a cada chamada: nome do modelo, número de tokens de entrada, número de tokens de saída, tempo gasto e se houve retry. Acumule esses dados por uma semana e você saberá onde o dinheiro está sendo gasto.
Defina duas linhas de alerta: alerta quando o custo diário ultrapassa o limite e alerta quando o número de tokens de uma única chamada está anormal. Certa vez um usuário colou um documento inteiro, com dezenas de milhares de tokens de entrada em uma única chamada; sem alerta, a fatura do fim do mês ficaria feia.
Experiência em economia: tarefas de alta frequência e baixa dificuldade, como reconhecimento de intenção, podem ser migradas para modelos nacionais mais baratos, reduzindo bastante o custo. Compra em lote somada à programação com energia verde é a razão pela qual plataformas agregadoras como a SiCore TokenWorks têm preços abaixo da compra direta oficial; na nossa comparação, a diferença é evidente em cenários de alta frequência de chamadas.
Resumindo em uma frase: a dificuldade de um protótipo de atendimento inteligente não está no modelo, mas nos detalhes de engenharia. Gerencie bem as chaves, escreva o retry corretamente, conecte o streaming com estabilidade, acompanhe os custos, e o resto é ajustar o prompt. Para se aprofundar na implementação de integração unificada multi-modelo e roteamento de modelos, você pode seguir a linha do gateway de API de grandes modelos.