Antes de tocar código: decisões que condicionam tudo
Integrar um modelo de linguagem em um site não começa instalando um SDK. Começa respondendo três perguntas que determinam o restante da checklist: qual tarefa concreta o LLM resolve, onde a inferência é executada e quem assume o custo por token. Se você não tem resposta fechada para as três, qualquer integração acabará sendo um protótipo caro que ninguém mantém.
Esta lista de verificação está ordenada por fases reais de projeto. Não é um guia teórico: cada ponto inclui o motivo pelo qual existe e a falha típica que evita. Alguns pontos não se aplicam a todos os casos e indico isso explicitamente.
Fase 1. Definição do caso de uso (não pule esta parte)
1.1. Escreva a tarefa em uma frase verificável
«Melhorar a experiência do usuário» não é uma tarefa. «Classificar tickets de suporte recebidos em cinco categorias com uma etiqueta de confiança» sim, é. Se você não pode medir se a resposta do modelo está correta, não pode integrá-lo com garantias.
1.2. Verifique se um LLM é realmente necessário
Muitas tarefas atribuídas a LLMs são resolvidas com regras, expressões regulares ou um classificador clássico mais barato e determinístico. Um LLM se destaca em linguagem livre, ambiguidade e geração; falha em cálculos exatos, lógica estrita e dados que mudam a cada minuto. Se o seu caso é «extrair um valor de uma fatura com formato fixo», provavelmente você não precisa de um modelo generativo.
1.3. Defina o custo máximo aceitável por interação
Os preços por milhão de tokens variam muito entre fornecedores e entre modelos da mesma família. Antes de integrar, calcule: comprimento médio do prompt + comprimento médio da resposta × volume diário estimado. Um chatbot que recebe 3.000 consultas por dia com prompts de 2.000 tokens pode custar mais que a hospedagem anual do site. Tenha esse número antes de escrever a primeira linha.
Fase 2. Arquitetura e segurança
2.1. A chave de API nunca vai para o navegador
Este é o erro mais comum e o mais caro. Qualquer chamada a partir do JavaScript do cliente expõe a chave nas ferramentas de desenvolvimento. A chamada ao fornecedor deve sair do seu servidor ou de uma função edge. Se você precisa de streaming para o navegador, use um proxy no seu backend que reenvie os chunks.
2.2. Decida entre API externa e modelo auto-hospedado
API externa: rápida de implementar, sem infraestrutura, mas você depende da disponibilidade e dos preços do fornecedor, e os dados saem do seu ambiente. Modelo auto-hospedado (por exemplo, pesos abertos servidos com ferramentas de inferência locais): controle total e custo fixo, mas exige GPU, manutenção e know-how. Para sites pequenos ou médios, a API costuma ser a decisão sensata; para dados sensíveis com requisitos estritos de residência, a auto-hospedagem pode ser obrigatória.
2.3. Filtre e minimize os dados que você envia
Antes de enviar um prompt, elimine identificadores pessoais, e-mails e dados de pagamento que o modelo não precisa. Não é apenas conformidade normativa: reduz tokens e melhora a qualidade da resposta ao eliminar ruído.
2.4. Proteção contra prompt injection
Se o LLM processa conteúdo que o usuário controla (comentários, descrições de produto, textos colados), assuma que esse conteúdo pode conter instruções maliciosas. Mitigações práticas: separe instruções do sistema e conteúdo do usuário com delimitadores claros, valide a saída contra um esquema, e nunca deixe que a saída do modelo dispare ações destrutivas sem confirmação humana.
Fase 3. Design do prompt e da saída
3.1. Instrução do sistema estável e versionada
Guarde o prompt do sistema em um arquivo com controle de versão. Quando você mudar uma palavra, poderá comparar resultados. Os prompts que vivem dentro do código misturados com a lógica de negócio são impossíveis de auditar.
3.2. Saída estruturada sempre que possível
Se o resultado alimenta um banco de dados ou uma interface, peça JSON com um esquema definido e valide a resposta com um parser estrito. Se o modelo devolve texto livre e você faz split por vírgulas, você quebrará assim que o modelo mudar de formato. A maioria dos fornecedores atuais oferece modos de saída estruturada; use-os.
3.3. Inclua exemplos no prompt (few-shot)
Dois ou três exemplos de entrada-saída correta costumam melhorar mais o resultado que parágrafos de instruções. Custam tokens, então reserve-os para tarefas onde o formato importa.
3.4. Defina o comportamento diante da dúvida
Indique explicitamente o que o modelo deve fazer quando não sabe: devolver um campo confiança: baixa, uma frase concreta de encaminhamento para humano, ou uma resposta vazia que sua interface interprete. Sem esta instrução, o modelo inventará com total segurança.
Fase 4. Integração no frontend
4.1. Estados de carregamento e cancelamento
As respostas generativas demoram segundos. A interface precisa de um estado de espera visível e um botão de cancelar que aborte a requisição. Se você usa streaming, mostre o texto à medida que chega: reduz a percepção de lentidão de forma notável.
4.2. Acessibilidade do componente
O contêiner de respostas deve ter aria-live=»polite» para que os leitores de tela anunciem o texto novo. O streaming sem gestão de acessibilidade gera experiências quebradas para usuários com leitores de tela.
4.3. Limites no cliente e no servidor
Limite o comprimento de entrada em ambos os lados. Um campo de texto sem limite é uma via direta para prompts gigantes que inflam sua fatura. Adicione também um limite de requisições por sessão ou por IP.
Fase 5. Qualidade, avaliação e monitoramento
5.1. Conjunto de testes com respostas esperadas
Antes de publicar, reúna entre 30 e 100 casos representativos com a resposta correta anotada à mão. Execute o prompt contra eles cada vez que o modificar. Sem este banco de testes, cada mudança é uma aposta.
5.2. Registro de requisições e respostas (com cuidado)
Guarde o prompt, a resposta e a latência para poder depurar. Anonimize antes de armazenar e defina um período de retenção. Um log sem política de retenção se torna um passivo.
5.3. Alertas de custo e de latência
Configure um limite de gasto diário que avise antes que a fatura saia do controle. Um loop infinito no cliente ou um bot que repete requisições podem multiplicar o consumo em horas.
Fase 6. SEO e visibilidade
6.1. O conteúdo gerado não é indexado por mágica
Se o LLM gera páginas ou fragmentos que você quer posicionar, eles precisam de URL própria, título, meta descrição e renderização no servidor. Um widget que gera texto dentro de uma div após uma interação do usuário não contribui em nada para o rastreamento.
6.2. Não gere conteúdo massivo sem revisão
As políticas de qualidade dos buscadores desincentivam o conteúdo produzido em escala sem valor agregado. Se você usa o LLM para redigir, use-o como rascunho com revisão editorial. Segundo a documentação oficial dos principais buscadores, o critério continua sendo a utilidade para o usuário, não o método de produção.
6.3. Bloqueie ou marque as rotas internas do assistente
Os endpoints da sua API e as rotas de geração não devem ser rastreáveis nem indexáveis. Adicione noindex e restrições no robots.txt onde corresponder.
Fase 7. Lançamento e manutenção
7.1. Implantação progressiva
Ative a função para uma porcentagem de usuários primeiro. Meça taxa de erro, latência e satisfação antes de abri-la para todo o tráfego.
7.2. Plano de degradação
O que acontece se o fornecedor devolver erros 429 ou 500? Defina uma resposta de reserva: mensagem de indisponibilidade, formulário de contato ou resposta em cache. Um assistente que quebra a página quando a API falha é pior que não ter assistente.
7.3. Revisão periódica do modelo
Os fornecedores retiram versões de modelos com avisos prévios. Anote a data de descontinuação da versão que você usa e teste a migração antes que ela seja forçada. Os prompts ajustados para uma versão podem se comportar de forma diferente na seguinte.
Um caso concreto e sua lição
Em um projeto de assistente para uma loja de componentes, a equipe testou o prompt com perguntas de catálogo e funcionava bem. Ao publicá-lo, os usuários começaram a perguntar sobre compatibilidades entre peças. O modelo respondia com segurança sobre combinações que não existiam no catálogo. A causa: o prompt incluía uma amostra de produtos, não o catálogo completo, e o modelo preenchia as lacunas com plausibilidade. A solução não foi um prompt melhor, mas recuperar os produtos relevantes do banco de dados e passá-los como contexto em cada consulta. Lição: se a resposta depende de dados que mudam, o modelo precisa de acesso a esses dados no momento da consulta, não de uma amostra estática no prompt.
O que esta checklist não resolve
Não há garantia de que o modelo responda corretamente a tudo. Os LLMs alucinam, e nenhuma configuração elimina esse comportamento por completo. Também não existe um prompt perfeito: o que funciona hoje pode se degradar com a próxima atualização do fornecedor. E há tarefas onde um LLM não é a ferramenta adequada: buscas exatas, cálculos financeiros, filtros determinísticos. Reconhecer isso a tempo economiza orçamento e frustração.
Se você revisar estas fases em ordem e deixar por escrito as decisões de cada uma, terá algo mais valioso que uma integração funcionando: terá uma integração que você pode manter quando mudar o modelo, o fornecedor ou a equipe.