Para testar regressões em prompts corporativos com DeepEval, transforme regras de atendimento em casos versionados, gere respostas com a versão candidata e avalie cada saída contra referências revisadas. O resultado precisa mostrar quais comportamentos pioraram, quais melhoraram e quais continuam sem evidência suficiente para liberar a mudança.
O trabalho começa antes da métrica: definir o que uma resposta correta deve preservar. Uma alteração que deixa o texto mais simpático pode eliminar uma condição comercial essencial. A proposta abaixo é uma suíte específica para prompts de resposta, complementar aos testes de regressão de agentes e ferramentas, com artefatos que uma equipe pequena consegue revisar.
Resumo rápido
- Separe o texto de referência da resposta realmente produzida.
- Versione prompt, conjunto de casos, modelo gerador e avaliador.
- Use regras determinísticas para formato e julgamento semântico para conteúdo.
- Compare versão atual e candidata com as mesmas perguntas.
- Trate falhas de infraestrutura separadamente de reprovações de qualidade.
O contrato de qualidade vem antes da pontuação
Escolha uma tarefa delimitada: responder dúvidas sobre um procedimento interno, explicar uma política comercial ou orientar abertura de chamado. Escreva os comportamentos obrigatórios em linguagem que um responsável pelo processo consiga validar. “Responder bem” não é um contrato. “Informar os documentos necessários e não prometer aprovação” permite avaliação.
Monte uma ficha por caso contendo identificador, pergunta, contexto autorizado, resposta de referência e motivo da inclusão. Acrescente a categoria de risco e o nome de quem revisou a expectativa. A referência pode aceitar diferentes redações; o objetivo é preservar decisões e informações, sem exigir cópia literal de uma frase.
Uma boa seleção inclui perguntas frequentes, pedidos ambíguos, informações ausentes e situações em que o assistente deve encaminhar para alguém. Acrescente variações de português realmente usadas pela equipe, como abreviações e mensagens incompletas. Não transforme todas as perguntas em versões gramaticalmente perfeitas que nunca aparecem no atendimento.
Comece com uma coleção pequena, mas explique a razão de cada entrada. Quando aparecer um incidente, registre um novo caso antes de corrigir o prompt. Isso evita que a mesma falha retorne depois. Mantenha também uma parcela reservada para revisão final, que não seja usada continuamente para ajustar a redação das instruções.
Como representar os casos no DeepEval
A documentação de LLMTestCase apresenta campos como input, actual_output e expected_output. Para esta suíte, o primeiro recebe a pergunta, o segundo recebe a saída capturada da aplicação e o terceiro registra a referência aprovada. Os campos exigidos dependem também da métrica escolhida.
Guarde as saídas em arquivos separados por execução. Um registro útil contém o identificador do caso, texto gerado, versão do prompt e metadados da chamada. Esse desenho permite reavaliar uma saída com outra rubrica sem consultar novamente o gerador. Também permite verificar se a diferença veio da geração ou do julgamento.
| Artefato | Responsabilidade | Erro que ajuda a investigar |
|---|---|---|
| Casos aprovados | Equipe do processo | Expectativa desatualizada |
| Prompt versionado | Responsável pela aplicação | Regra removida ou ambígua |
| Saídas capturadas | Executor da avaliação | Resposta efetivamente entregue |
| Rubrica e avaliador | Responsável por qualidade | Critério inconsistente |
| Relatório comparativo | Revisor da mudança | Regressão escondida pela média |
Não coloque respostas desejadas no arquivo reservado às saídas da aplicação. Essa separação parece burocrática, mas evita uma suíte que aprova textos escritos pelo próprio autor do teste. Se o sistema usa busca documental, preserve também a versão dos documentos usados na rodada. Alterar documentos junto com o prompt dificulta atribuir a causa da melhora ou piora.
Uma avaliação mínima com GEval
O GEval permite fornecer etapas explícitas de avaliação, parâmetros relevantes e um limite de aprovação. O exemplo abaixo lê uma saída previamente capturada; ele não executa sua aplicação. Configure o provedor do avaliador e as credenciais antes de rodar. O valor do limite é ilustrativo e precisa de calibração.
import json
from pathlib import Path
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams
def test_politica_comercial() -> None:
registro = json.loads(
Path("saidas/caso-condicao.json").read_text(encoding="utf-8")
)
caso = LLMTestCase(
input=registro["pergunta"],
actual_output=registro["resposta"],
expected_output=(
"Solicitar o identificador do pedido. "
"Explicar que a análise depende da conferência. "
"Não prometer aprovação antecipada."
),
)
criterio = GEval(
name="Aderencia ao procedimento",
evaluation_steps=[
"Compare actual_output com expected_output.",
"Verifique se todas as condições foram preservadas.",
"Penalize promessas incompatíveis com a referência.",
"Aceite redações diferentes com o mesmo significado.",
],
evaluation_params=[
SingleTurnParams.ACTUAL_OUTPUT,
SingleTurnParams.EXPECTED_OUTPUT,
],
threshold=0.8,
)
assert_test(test_case=caso, metrics=[criterio])O arquivo de entrada deve conter pergunta e resposta da execução candidata. Instale a biblioteca em ambiente isolado e rode deepeval test run test_prompts.py, conforme o guia inicial oficial. Fixe a versão instalada no projeto para tornar as próximas execuções comparáveis.
O código usa a nomenclatura da documentação consultada. Se um projeto antigo usa outra versão, confirme os imports antes da migração. Defina explicitamente o avaliador na configuração da equipe; deixar a escolha implícita dificulta interpretar mudanças futuras. Quando a avaliação utilizar serviços da OpenAI, consulte também o catálogo de integrações da OpenAI.
Este exemplo demonstra a estrutura, não comprova desempenho. A aprovação de uma resposta depende da saída real, do avaliador configurado e da rubrica. Não há resultado de teste presumido ou porcentagem de precisão prometida.
Como decidir se a candidata pode substituir a atual
Execute a versão atual e a candidata sobre a mesma coleção congelada. Compare por caso e por categoria. Uma média melhor pode esconder uma regressão grave no encaminhamento de pedidos fora da política. Para situações críticas, adote condições obrigatórias independentes da nota global, com revisão humana quando a regra não puder ser verificada por código.
Formato deve ser validado fora do julgamento subjetivo sempre que possível. Se a aplicação entrega JSON, use um validador de esquema. Se um campo só aceita categorias conhecidas, confronte o valor com essa lista. O guia de avaliação de aderência a JSON Schema ajuda a separar essa exigência da qualidade textual.
Calibre a rubrica com exemplos que pessoas já classificaram como aceitáveis e inaceitáveis. Inclua casos difíceis, nos quais o texto parece correto, mas omite uma ressalva decisiva. Se o avaliador discordar repetidamente dos revisores, investigue a referência e a instrução de avaliação antes de mexer no limite para obter aprovação.
Repita um subconjunto de casos para observar instabilidade. Uma execução isolada não permite distinguir mudança persistente de oscilação. Registre o orçamento e o número de repetições adotados como decisões do projeto, sem apresentá-los como padrão universal. Para cada regressão, examine pergunta, resposta antiga, resposta nova e justificativa lado a lado.
A integração com testes automatizados está descrita na documentação de CI/CD do DeepEval. No fluxo proposto, o trabalho da integração contínua é produzir evidências e impedir a promoção quando uma regra acordada falhar. Erro de autenticação, indisponibilidade e arquivo ausente devem aparecer como execução incompleta, sem nota artificial de qualidade.
Exemplo: distribuidora em Campinas revisa o atendimento
Considere uma distribuidora fictícia de materiais de escritório em Campinas. O assistente explica como solicitar troca de itens entregues incorretamente. A equipe quer deixar o prompt mais curto, porque respostas longas confundem clientes. Este é um exemplo ilustrativo de desenho de teste, sem resultados comerciais atribuídos a uma empresa real.
A responsável pelo atendimento separa três famílias de casos: pedido identificado, pedido sem identificação e cliente solicitando exceção. Em cada referência, registra o próximo passo permitido. A equipe não usa regras jurídicas inventadas para o exemplo; o foco é uma política interna fictícia previamente definida.
Na comparação, a revisão deve procurar se a versão curta continua pedindo os dados necessários e evita confirmar a troca antes da conferência. Uma resposta elegante que omite essa dependência recebe reprovação da regra correspondente. Uma resposta com redação diferente, mas com orientação completa, pode ser aceita.
Antes de liberar, a supervisora lê todos os casos críticos e uma amostra dos demais. O registro da decisão informa qual mudança foi autorizada e quais limitações permanecem. Se o procedimento comercial mudar depois, a referência é atualizada com justificativa, e ambas as versões são avaliadas novamente quando a comparação ainda fizer sentido.
Erros comuns
Usar uma rubrica para tudo. Clareza, correção e respeito ao procedimento são dimensões distintas. Uma avaliação abrangente demais produz justificativas difíceis de transformar em ação. Separe as dimensões necessárias e mantenha cada uma compreensível para quem aprova o atendimento.
Confundir limite com garantia. A nota não representa automaticamente probabilidade de acerto. Um limite escolhido sem revisão de exemplos só cria aparência de rigor. Documente quais erros a equipe aceita e quais impedem a liberação independentemente da média.
Mudar referência para acomodar uma falha. Corrija expectativas quando o processo realmente mudou, com aprovação de seu responsável. Não altere a resposta esperada apenas porque a candidata ficou abaixo do limite.
Guardar conteúdo sensível indiscriminadamente. Use exemplos sintéticos ou minimizados e controle acesso aos artefatos. Avaliação também pode transmitir dados a um serviço externo. Confirme o destino dos textos e a configuração de armazenamento antes de usar conversas reais.
Perguntas frequentes
Preciso comparar o texto palavra por palavra?
Não para respostas livres. Prefira critérios de significado, condições preservadas e ações permitidas. Igualdade literal é útil para campos fechados e protocolos que exigem uma representação exata, mas costuma penalizar variações legítimas de redação.
DeepEval substitui a revisão humana?
Não. A equipe define a referência e calibra a avaliação. Use automação para localizar divergências e repetir verificações, reservando julgamento humano para ambiguidades, casos críticos e mudanças de procedimento.
É necessário testar um agente completo?
Não para este recorte. Você pode avaliar respostas capturadas de um componente de geração. Se a alteração também afeta ferramentas e permissões, acrescente testes específicos dessas operações; a suíte textual não observa sozinha esses efeitos.
Posso reutilizar respostas antigas?
Sim, para comparar avaliadores ou revisar uma rubrica, desde que a origem esteja registrada. Para validar um prompt novo, gere novas saídas com ele. Reavaliar respostas antigas não testa uma modificação que nunca as produziu.
Quando devo ampliar a coleção?
Quando surgir uma intenção relevante, incidente recorrente ou mudança no processo. Evite acumular variações quase idênticas enquanto categorias importantes permanecem ausentes. A cobertura deve refletir decisões de negócio, não apenas quantidade de linhas.
