Melhores Práticas de LLMs
Regras para construir aplicações LLM confiáveis, seguras e econômicas. Revise esta lista durante a revisão do design e antes do lançamento em produção.
Como Usar Esta Lista
- Regras A-B cobrem segurança e higiene de API.
- Regras C-D governam a qualidade do prompt e o tratamento da saída.
- Regras E-F cobrem custo, avaliação e operações.
- Revise ao adicionar um novo modelo, provedor ou recurso.
A - Segurança e Chaves
- Carregue chaves de API de variáveis de ambiente. Nunca comite chaves no git; use gerenciadores de segredos em produção.
- Rotacione chaves se expostas. Trate commits acidentais como incidentes - revogue e reemita imediatamente.
- Sanitize a entrada do usuário antes de incluí-la nos prompts. Use delimitadores; nunca concatene a entrada do usuário em prompts do sistema.
- Valide as saídas do modelo antes da execução. Nunca use
eval()ouexec()código gerado por LLM sem sandboxing. - Registre hashes de prompt, não prompts completos. Proteja os dados do usuário nos logs; registre o suficiente para depuração.
B - Uso da API
- Defina
max_tokensem cada solicitação. Evite geração descontrolada e surpresas de custo. - Lide com limites de taxa com backoff exponencial. Capture erros 429; use semáforos para concorrência.
- Use o nível de modelo correto. Mini/haiku para tarefas simples; full/sonnet apenas quando necessário.
- Defina timeouts em chamadas de API. Evite que solicitações pendentes bloqueiem sua aplicação.
- Use clientes assíncronos em servidores web.
AsyncOpenAIno FastAPI; nunca bloqueie o loop de eventos.
C - Qualidade do Prompt
- Escreva prompts de sistema específicos. Papel, restrições, formato de saída e comportamento em caso de falha.
- Use
temperature=0para extração e classificação. Reserve temperaturas mais altas para tarefas criativas. - Fundamente as respostas com contexto recuperado (RAG). Instrua "diga que não sei" quando o contexto for insuficiente.
- Versionamento de prompts no git. Rastreie alterações de prompt como código; teste A/B de variantes.
- Itere prompts antes do fine-tuning. Engenharia de prompt é mais barata e rápida de iterar.
D - Tratamento de Saída
- Valide saída estruturada com Pydantic. Nunca confie em JSON bruto do modelo.
- Tente novamente em caso de falha de validação (máximo 3). Inclua o erro de validação no prompt de nova tentativa.
- Lide com conteúdo nulo e
tool_calls. Ramifique com base emfinish_reasone tipo de resposta. - Adicione pontuações de confiança ou revisão humana para campos de alto risco. A saída do modelo é probabilística, não garantida.
- Transmita para usuários em respostas longas. Melhore a latência percebida com streaming de tokens.
E - Custo e Desempenho
- Registre o uso de tokens em cada chamada. Rastreie
response.usagepor recurso para atribuição de custo. - Apare a história da conversa. Resuma ou descarte turnos antigos para permanecer dentro dos limites de contexto.
- Cache consultas repetidas. Hash do prompt + modelo; retorne a resposta em cache quando idêntica.
- Agrupe trabalho offline. Use a API Batch para incorporação e avaliação em massa.
- Considere modelos locais para tarefas simples de alto volume. Ollama/vLLM quando o custo da API exceder o custo da GPU.
F - Avaliação e Segurança
- Construa um conjunto de avaliação antes de implantar. Mínimo de 20-50 pares de entrada/saída esperada rotulados.
- Meça a precisão, não as "vibrações". Métricas automatizadas no conjunto de avaliação para cada alteração de prompt.
- Teste casos extremos. Entrada vazia, entrada muito longa, prompts adversários, texto não inglês.
- Implemente filtragem de conteúdo. Lide com recusas, violações de política e saídas prejudiciais graciosamente.
- Monitore a qualidade da produção. Rastreie feedback do usuário, taxas de erro e falhas de validação de saída.
FAQs
Qual é o principal erro de segurança em LLMs?
- Codificar chaves de API no código-fonte.
- As chaves são commitadas no git e raspadas por bots.
- Use variáveis de ambiente e gerenciadores de segredos.
Como prevenir injeção de prompt?
- Separe claramente o conteúdo do sistema e do usuário.
- Use delimitadores XML para entrada do usuário.
- Nunca siga instruções embutidas em dados do usuário.
Quando devo usar RAG vs fine-tuning?
- RAG: respostas precisam de dados atuais ou privados.
- Fine-tuning: formato/estilo consistente em alto volume.
- Comece com RAG + engenharia de prompt.
Como testar recursos de LLM?
- Conjunto de avaliação com saídas esperadas.
- Mock da API em testes unitários; testes de integração com fixtures gravados.
- Teste de regressão em alterações de prompt.
O que devo registrar?
- Modelo, contagens de tokens, latência, versão do prompt, resultado da validação.
- Não prompts completos se contiverem PII do usuário.
Como lidar com recusas de modelo?
- Verifique
finish_reasone conteúdo vazio. - Mostre uma mensagem de fallback amigável ao usuário.
- Registre para revisão, mas não tente novamente indefinidamente.
Devo usar um provedor ou vários?
- Comece com um provedor por simplicidade.
- Adicione a abstração LiteLLM quando precisar de fallback ou otimização de custo.
Como configurar um ambiente de desenvolvimento sem custos de API?
- Ollama para desenvolvimento local.
- Mock de respostas em testes unitários.
- Chaves de API de desenvolvimento separadas com limites de gastos.
O que é um eval mínimo viável?
- 20 exemplos cobrindo o caminho feliz e casos extremos.
- Pontuação automatizada (correspondência exata, F1 ou LLM-como-juiz).
- Execute em cada alteração de prompt ou modelo.
Como revisar um PR de recurso de LLM?
- Verifique o manuseio de chaves, validação de saída, tratamento de erros e registro.
- Verifique se o conjunto de avaliação existe e passa.
- Teste com entradas adversárias.
Quando é OK executar código gerado por LLM?
- Nunca diretamente em produção sem sandboxing.
- Use contêineres isolados com limites de recursos.
- Revisão humana para qualquer coisa que toque na infraestrutura.
Como documentar um recurso de LLM?
- Modelo, versão do prompt, comportamento esperado, limitações conhecidas.
- Precisão da avaliação, custo por solicitação e latência p50/p99.
Relacionados
- Engenharia de Prompt - padrões de prompt
- Saída Estruturada - validação de saída
- Tokens, Custo e Limites de Taxa - orçamento
- Avaliação e Guardrails - medição de qualidade
- Melhores Práticas de Agentes de IA - regras específicas de agentes
Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.