07 Avaliar uma mudança

O material do workshop é mantido no repositório público langfuse/langfuse-workshop. Use o repositório para executar a aplicação, acessar os branches de checkpoint e fazer a configuração local.

Ver este arquivo Markdown

Ponto de partida

git checkout checkpoint/07-evaluation

Sua aplicação tem tracing, monitoramento, um dataset hospedado e ao menos uma execução de experimento com pontuações keyword_overlap e correctness. Agora você altera a aplicação e executa o experimento novamente para saber se o resultado melhorou ou piorou.

Examine a primeira execução antes de mudar qualquer coisa. Abra dataset → Runs e confira as médias:

• média de correctness — que fração dos itens o juiz considerou realmente correta?
• média de keyword_overlap — que fração cobriu as etapas esperadas?

Abra os itens em que uma das pontuações está baixa e leia a resposta do agente. É comum descobrir que ele pulou uma etapa, recusou algo que deveria atender ou deu uma orientação genérica em vez de instruções específicas para iPhone. O que você encontrar é o problema que tentará corrigir.

Por que avaliar mudanças com experimentos

Se você mudar qualquer parte da aplicação de IA — prompt, modelo, contexto ou arquitetura do agente — precisa saber se o sistema realmente melhorou. Examinar uma ou duas saídas parece convincente, mas não generaliza. Executar o mesmo dataset na nova versão e comparar as pontuações à execução anterior é o mais próximo de uma medição.

Isso também permite fechar o ciclo e publicar com confiança: quando as médias da nova execução sobem — e você lê itens suficientes para confirmar que a pontuação representa a realidade — há evidências para publicar a mudança.

O que você pode mudar

Este capítulo usa uma iteração de prompt porque é a alavanca de menor atrito. O mesmo fluxo funciona se você mudar:

• O modelo — experimente um modelo mais forte ou mais barato e execute novamente.
• O contexto — adicione ou remova campos do prompt de sistema ou dos resultados das ferramentas.
• A arquitetura do agente — adicione uma ferramenta, mude a ordem ou as tentativas.
• O prompt — o que faremos aqui.

O formato é sempre igual: mude uma coisa — ou uma configuração de variáveis —, execute o dataset novamente e compare lado a lado.

Objetivo

Mudar algo no prompt e melhorar os resultados, medidos pela alta de correctness e keyword_overlap no dataset.

Três passos:

1. Mudar uma coisa — trocar a variante do prompt ou editá-lo no Langfuse.
2. Executar o dataset novamente com o novo prompt.
3. Comparar as execuções lado a lado e decidir se deve publicar.

Etapa 1 — Mudar o prompt

A mudança deve responder ao que você observou na execução 1 — por exemplo, itens com correctness baixa porque o agente contornou uma solicitação fora do escopo em vez de recusá-la claramente. Uma edição concreta seria:

Acrescente uma regra: "Se uma solicitação estiver fora da ajuda com iPhone — impostos, reserva de viagem ou algo que exija acesso em tempo real a uma conta — diga isso diretamente em uma frase curta: com o que você não pode ajudar e com o que pode. Depois, pare. Não tente responder à solicitação."

Isso torna o comportamento fora do escopo explícito, em vez de deixar o modelo improvisar.

Duas formas de fazer a mudança:

Opção A — No Langfuse (criar uma nova versão pela interface, recomendado):

Prompts → dad-it-support-agent → crie uma nova versão ou draft → adicione a regra à seção Rules → salve a versão → promova-a ao label production. O resolver busca pelo label; a próxima requisição recebe a nova versão automaticamente. Esse é o fluxo que sua equipe usará para iterações contínuas em produção.

Opção B — No código (editar src/server/support-agent.ts e publicar novamente):

Abra src/server/support-agent.ts, adicione a mesma regra ao bloco Rules da constante SYSTEM_PROMPT e publique:

npm run prompt:publish

O repositório também inclui uma variante gentler pronta (WORKSHOP_PROMPT_VARIANT=gentler npm run prompt:publish) — útil se você quiser apenas observar qualquer mudança de prompt, em vez de criar uma.

Nos dois casos, você termina com uma nova versão, usada pela próxima chamada a runSupportConversation(...).

Etapa 2 — Executar o dataset novamente

npm run dataset:run

Agora há duas execuções no mesmo dataset, cada uma vinculada a uma versão diferente do prompt. O avaliador keyword_overlap do script e o avaliador correctness da etapa 06 pontuam a nova execução automaticamente.

Etapa 3 — Comparar

No Langfuse:

• Dataset → aba Runs → duas linhas com médias de keyword_overlap e correctness.
• Chart view → médias de cada execução lado a lado.
• Adicione a nova execução como 'Compare with' na barra lateral.

Observe:

• Quais itens melhoraram intencionalmente.
• Quais regrediram — a parte que torna a avaliação útil.
• Se a mudança alterou o escopo: mais recusas, respostas mais confiantes, mais etapas por resposta?

Como verificar a conclusão

• Duas execuções aparecem no dataset, vinculadas a versões diferentes do prompt.
• As duas pontuações (keyword_overlap, correctness) têm médias comparáveis.
• Se uma pontuação ainda estiver pendente, atualize depois que a fila do avaliador terminar.

Encerramento

Fechar o ciclo — mudar → executar novamente → comparar → decidir — transforma mudanças de prompt ou modelo de decisões intuitivas em decisões de engenharia. Toda mudança futura passa a ter uma linha de base gratuita.

A skill do Langfuse (/langfuse) atualiza versões de prompt, liga execuções às versões e gera automaticamente um gráfico de comparação. Este passo a passo existe para mostrar o que ela faz por baixo dos panos.

Estado final

Este é o ponto de partida para 08-wrap-up.