Tutorial LangFuse: plataforma de engenharia de LLM para monitoramento e avaliações

Construir aplicações com LLM vira uma bagunça rápido. Você começa a chutar os custos. Depurar falhas fica mais difícil quando não dá para ver o que aconteceu. Prompts se espalham pelo seu código. O LangFuse resolve isso com uma plataforma que rastreia tudo, gerencia prompts e mede qualidade.

Neste tutorial, você vai construir uma ferramenta de perguntas e respostas sobre documentos e ver como o LangFuse organiza seu desenvolvimento. Você vai aprender a traçar chamadas de LLM para depuração, gerenciar prompts com controle de versão e explorar abordagens de avaliação.

O que é o LangFuse?

LangFuse é uma plataforma open source que ajuda times a construir melhores aplicações com LLM. Enquanto você foca nas funcionalidades, o LangFuse cuida do monitoramento, testes e depuração.

A plataforma cobre três áreas principais:

1. Observabilidade: veja o que acontece quando seu LLM roda. Acompanhe custos, identifique erros e entenda como os usuários interagem com seu app. Chega de adivinhar por que algo quebrou ou quanto a OpenAI cobrou no mês passado.
2. Gestão de prompts: armazene e versione seus prompts em um só lugar em vez de espalhá-los pelo código. Seu time pode testar versões diferentes sem mexer no código de produção.
3. Avaliação: meça o desempenho do seu LLM. Configure testes automatizados para verificar se as respostas fazem sentido, permanecem no tema e atendem aos padrões de qualidade.

Quando usar o LangFuse?

Você vai querer o LangFuse quando sua aplicação com LLM sair dos experimentos simples. Eis as situações em que ele agrega valor:

• Várias pessoas no time trabalhando em prompts, e você precisa de controle de versão
• Aplicações em produção em que você precisa acompanhar custos e monitorar desempenho
• Fluxos de trabalho complexos como sistemas RAG, setups multiagente ou cadeias de conversação
• Preocupações com qualidade em que você precisa de testes sistemáticos, não apenas checagens pontuais manuais

Se você está criando um protótipo rápido ou projeto pessoal, provavelmente ainda não precisa. Mas quando seu app atende usuários reais ou seu time cresce além de uma pessoa, o LangFuse passa a ser útil.

Adoção e integração

O LangFuse funciona com seu stack de IA atual. Ele integra com frameworks como LangChain, LlamaIndex, AutoGen e CrewAI. Você pode usar com qualquer provedor de modelo — OpenAI, Anthropic, Google Gemini, Mistral ou modelos do Hugging Face funcionam de primeira.

A plataforma oferece SDKs nativos para Python e JavaScript, além de suporte a OpenTelemetry para setups personalizados. Esteja você usando construtores de agentes no-code ou frameworks multiagente complexos, o LangFuse se conecta sem alterar sua arquitetura principal.

Empresas como Samsara, Twilio e Khan Academy usam em produção, e a solução atende aos padrões de segurança enterprise. O projeto tem mais de 16.500 estrelas no GitHub e é apoiado pela Y Combinator. Você pode usar a versão hospedada ou rodar na sua própria infraestrutura.

Agora que você já entendeu o que o LangFuse faz e quando ele ajuda, vamos construir algo com ele. Como prometido, vamos criar uma ferramenta simples de perguntas e respostas sobre documentos que mostra as três funcionalidades em ação.

Pré-requisitos

Você precisa de alguma experiência com Python e LLM antes de mergulhar no LangFuse.

Indispensável:

• Python 3.8+ e conhecimento básico de APIs
• Experiência com a API da OpenAI (vamos usar o GPT-4)
• Noções de LangChain — prompts, chains e conceitos básicos

Bom ter:

• Entendimento de embeddings e padrões de busca/recuperação
• Experiência com engenharia de prompts

Configuração:

• Chave de API da OpenAI
• Gerenciador de pacotes Python (uv ou pip)
• Vamos criar juntos uma conta gratuita no LangFuse

Novo em desenvolvimento de IA? Comece pelo nosso guia completo de aprendizado em IA.

Para entender onde o LangFuse se encaixa no ecossistema, confira nossa visão geral de ferramentas de LLMOps.

Agora vamos construir algo. Vamos começar com uma função simples de perguntas e respostas sobre documentos e ver como o LangFuse rastreia o que acontece quando você a executa. Este exemplo básico mostra as três funcionalidades — observabilidade, gestão de prompts e avaliação — de um jeito que escala para projetos mais complexos.

Construindo uma ferramenta de perguntas e respostas com o LangFuse

Você vai criar um sistema simples de Q&A que responde perguntas a partir de um PDF. Assim, teremos algo real para rastrear, gerenciar e avaliar. Embora o exemplo seja simples, os mesmos padrões funcionam para sistemas RAG complexos e fluxos multiagente.

Configurando o ambiente

Primeiro, crie um diretório para o projeto e instale os pacotes necessários:

mkdir langfuse-qa-demo
cd langfuse-qa-demo
uv add langfuse langchain langchain-openai langchain-community pypdf python-dotenv

Cadastre-se para uma conta gratuita no LangFuse Cloud em langfuse.com. Após entrar, crie uma nova organização e projeto. Você verá uma tela com suas chaves de API:

Copie sua Public Key e Secret Key. Você também vai precisar da sua chave de API da OpenAI em platform.openai.com.

Agora crie um arquivo .env no diretório do projeto:

OPENAI_API_KEY=your_openai_key_here
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com

Se preferir rodar o LangFuse na sua própria infraestrutura, você pode usar Docker Compose para testes locais. O guia de self-hosting explica como configurar PostgreSQL, ClickHouse e os serviços do LangFuse. Para produção, use Kubernetes ou templates Terraform específicos de nuvem.

Construindo uma chain de Q&A de documentos no LangChain

Você vai construir uma retrieval chain que carrega um PDF, o divide em partes, armazena em um banco vetorial e responde perguntas com base no contexto recuperado.

Crie um arquivo chamado qa_chain.py:

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_core.vectorstores import InMemoryVectorStore
from langchain.chains import create_retrieval_chain
from langchain.chains.combine_documents import create_stuff_documents_chain
from langchain_core.prompts import ChatPromptTemplate
from dotenv import load_dotenv

load_dotenv()

Isso importa tudo que você precisa. A chamada load_dotenv() carrega suas chaves de API do arquivo .env.

# Load and split PDF
loader = PyPDFLoader("ai-security-landscape.pdf")
docs = loader.load()

text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
splits = text_splitter.split_documents(docs)

Aqui estamos carregando o documento ai-security-landscape.pdf, um dos whitepapers da Amazon Web Services. Para rodar este exemplo, você vai precisar baixar o arquivo por conta própria e adicioná-lo ao seu diretório de trabalho com o nome correto.

O PyPDFLoader lê o PDF e o RecursiveCharacterTextSplitter divide em blocos de 1.000 caracteres com sobreposição de 200. A sobreposição ajuda a manter o contexto entre os blocos.

Em seguida, crie o repositório vetorial:

# Create vector store
embeddings = OpenAIEmbeddings()
vectorstore = InMemoryVectorStore.from_documents(documents=splits, embedding=embeddings)

InMemoryVectorStore armazena embeddings de documentos em memória. Em produção, você usaria Pinecone, Weaviate ou outro banco vetorial.

Agora crie a chain de Q&A:

# Build QA chain
llm = ChatOpenAI(model="gpt-4")
prompt = ChatPromptTemplate.from_messages([
   ("system", "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\n{context}"),
   ("human", "{input}"),
])

question_answer_chain = create_stuff_documents_chain(llm, prompt)
qa_chain = create_retrieval_chain(vectorstore.as_retriever(), question_answer_chain)

create_stuff_documents_chain pega os documentos recuperados e os insere no contexto do prompt. create_retrieval_chain combina recuperação e resposta em uma única chain.

Com a chain pronta, vamos conectá-la ao LangFuse para tracing.

Rastreando sua primeira chamada com o LangFuse

Adicione um callback handler do LangFuse ao script:

from langfuse.langchain import CallbackHandler

langfuse_handler = CallbackHandler()

response = qa_chain.invoke(
   {"input": "What are the main security risks discussed?"},
   config={"callbacks": [langfuse_handler]}
)

print(response["answer"])

The main security risks discussed in relation to generative artificial intelligence (AI) are context window overflow, agent mismanagement, indirect prompt injections and data leaks from overprivileged agents, logging, and caching.

Trace sent to LangFuse! Check your dashboard at https://cloud.langfuse.com

Ao rodar, o LangFuse captura todo o trace de execução. Vá ao seu painel do LangFuse e você verá os detalhes atualizados:

Note que, embora usemos um exemplo simples aqui, o LangFuse funciona com pipelines RAG complexos que lidam com múltiplos tipos de documentos, utilizam reranking ou executam estratégias de recuperação em paralelo.

Com seu sistema de Q&A rodando e o tracing do LangFuse ativo, você está pronto para entender o que o LangFuse captura e como usar essas informações para melhorar sua aplicação.

Observabilidade no LangFuse

Você acabou de enviar um trace para o LangFuse. Agora, vamos entender o que isso traz para você — e por que importa.

Por que a observabilidade de LLM importa

Logs tradicionais não funcionam bem para apps com LLM. Você consegue logar que uma função rodou, mas não enxerga o que o modelo realmente fez com o input do usuário. Ele recuperou os documentos certos? O prompt foi formatado corretamente? Qual etapa levou cinco segundos?

Observabilidade de LLM rastreia todo o caminho de execução. Você vê cada input, output e etapa intermediária. Quando um usuário relata uma resposta errada, você abre o trace dele e vê exatamente o que aconteceu. Sem achismo. Você sabe.

Isso fica ainda mais importante conforme o app fica complexo. Uma chain simples de Q&A tem 4–5 etapas. Sistemas RAG em produção têm carregadores de documentos, estratégias de chunking, múltiplos retrievers, re-rankers e etapas de geração. Sem observabilidade, depurar vira missão impossível. Com ela, você encontra o ponto do problema.

Entendendo traces e sessões

Abra o painel do LangFuse e clique em “Tracing” na barra lateral esquerda. Você verá seu primeiro trace listado em uma tabela.

A tabela mostra quando o trace rodou, como foi chamado (retrieval_chain) e o que entrou e saiu. Cada linha representa uma execução completa da sua chain de Q&A.

Clique no trace para ver o que ocorreu dentro. Você terá um detalhamento completo.

O painel esquerdo mostra sua árvore de execução. O LangFuse rastreou cada etapa na chain. A raiz retrieval_chain levou 4,75 segundos no total. Abaixo, você vê cada operação executada: recuperação de documentos (retrieve_documents), busca vetorial (VectorStoreRetriever) e geração da resposta (stuff_documents_chain). Cada etapa mostra seu tempo de execução.

Essa hierarquia revela onde sua chain gastou tempo. Se o app está lento, você saberá se é a busca de embeddings, a pesquisa vetorial ou a chamada ao LLM.

O painel direito mostra os dados do trace. No topo, estão as métricas que importam: latência (4,75s), custo (~US$ 0,016) e tokens usados (426 de entrada, 55 de saída). Abaixo, você vê o input real e o output. A seção context exibe os quatro blocos de documento que o seu retriever puxou do repositório vetorial.

No fim, um diagrama de fluxo mapeia como sua chain conecta as operações. Isso ajuda bastante ao depurar chains complexas com múltiplos ramos.

Agora vamos falar de sessões. Um trace captura um ciclo pergunta–resposta. Mas apps reais têm conversas. Um usuário pode fazer três perguntas relacionadas sobre riscos de segurança. Você quer agrupar esses traces.

É isso que sessões fazem. Elas agrupam múltiplos traces em um único fio de conversa. Quando um usuário relata um bug, você puxa toda a sessão dele e vê cada pergunta e cada resposta.

Vamos ver isso na prática. Primeiro, crie um arquivo utilitário chamado build_chain.py que encapsula a lógica de construção da chain:

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_core.vectorstores import InMemoryVectorStore
from langchain.chains import create_retrieval_chain
from langchain.chains.combine_documents import create_stuff_documents_chain
from langchain_core.prompts import ChatPromptTemplate
from dotenv import load_dotenv

load_dotenv()

def build_qa_chain():
   # Load and split PDF
   loader = PyPDFLoader("ai-security-landscape.pdf")
   docs = loader.load()

   text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
   splits = text_splitter.split_documents(docs)

   # Create vector store
   embeddings = OpenAIEmbeddings()
   vectorstore = InMemoryVectorStore.from_documents(documents=splits, embedding=embeddings)

   # Build QA chain
   llm = ChatOpenAI(model="gpt-4")
   prompt = ChatPromptTemplate.from_messages([
       ("system", "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\n{context}"),
       ("human", "{input}"),
   ])

   question_answer_chain = create_stuff_documents_chain(llm, prompt)
   qa_chain = create_retrieval_chain(vectorstore.as_retriever(), question_answer_chain)

   return qa_chain

Isso encapsula tudo em uma função que você pode importar. Agora crie sessions_demo.py:

from build_chain import build_qa_chain
from langfuse.langchain import CallbackHandler

# Build the Q&A chain
qa_chain = build_qa_chain()

# Set up LangFuse handler
langfuse_handler = CallbackHandler()
This imports your chain and sets up the LangFuse handler. Now add session tracking for the first conversation:
# Session 1: User asking about security risks
response1 = qa_chain.invoke(
   {"input": "What are the main security risks discussed?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {"langfuse_session_id": "conversation-001"}
   }
)
print(f"Q1: {response1['answer']}\n")

O campo metadata com langfuse_session_id marca esse trace com um ID de sessão. Rode e você verá:

Q1: The main security risks discussed are context window overflow, agent mismanagement, and indirect prompt injections.

Agora adicione uma pergunta de acompanhamento com o mesmo ID de sessão:

response2 = qa_chain.invoke(
   {"input": "How can these risks be mitigated?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {"langfuse_session_id": "conversation-001"}
   }
)
print(f"Q2: {response2['answer']}\n")

Essa segunda pergunta pertence à mesma conversa, então usa conversation-001 de novo. Você verá uma resposta mais longa:

Q2: Risks can be mitigated through several strategies including:
1. Input Management: Limit and sanitize inputs going into the model.
2. Real-time Monitoring: Use systems that alert when the context window is nearing capacity.
3. Principle of Least Privilege: Implement this for all agents and external integrations.
....

Agora simule um segundo usuário com perguntas diferentes. Adicione isto ao seu script:

# Session 2: Different user asking about AI applications
response3 = qa_chain.invoke(
   {"input": "What AI applications are mentioned in the document?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {"langfuse_session_id": "conversation-002"}
   }
)
print(f"Q3: {response3['answer']}\n")

response4 = qa_chain.invoke(
   {"input": "What are the benefits of these applications?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {"langfuse_session_id": "conversation-002"}
   }
)
print(f"Q4: {response4['answer']}\n")

Essas duas perguntas usam conversation-002. Rode o script completo:

uv run python sessions_demo.py

As duas últimas saídas serão:

Q3: The document does not specifically mention any AI applications. However, it discusses the concept of generative AI and its security considerations.

Q4: The context does not provide specific benefits of these applications.

Agora vá ao painel do LangFuse e clique em “Sessions” na barra lateral esquerda. Você verá as duas conversas listadas:

Aparecem duas sessões: conversation-002 (~4 segundos de duração) e conversation-001 (~14 segundos). O LangFuse agrupou seus traces pelo ID de sessão.

Clique em conversation-001 para ver a conversa completa:

Você vê os dois traces em ordem: Pergunta 1 sobre riscos de segurança, e Pergunta 2 sobre mitigação. A sessão mostra o custo total (US$ 0,05121 para ambos os traces) e a duração (14 segundos no total). Cada trace aparece com seu input, output e contexto recuperado.

Essa visão de sessão mostra exatamente o que o usuário experimentou na interação. Se ele reportar um problema, você não precisa caçar traces isolados: abre a sessão e vê todo o fluxo da conversa.

Rastreando usuários

Até agora você rastreou sessões, mas e usuários individuais? Apps reais com LLM precisam saber qual usuário fez qual requisição. Quando alguém se cadastra, você gera um ID único e anexa esse ID a cada chamada de LLM que ele faz.

O LangFuse permite agrupar traces por ID de usuário além do agrupamento por sessão. Isso oferece outra forma de organizar seus dados de observabilidade.

Veja como adicionar rastreamento de usuário. Crie user_tracking.py:

from build_chain import build_qa_chain
from langfuse.langchain import CallbackHandler

# Build the Q&A chain
qa_chain = build_qa_chain()

# Set up LangFuse handler
langfuse_handler = CallbackHandler()

# Simulate a new user asking a question
user_response = qa_chain.invoke(
   {"input": "What security controls are recommended for AI systems?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {
           "langfuse_session_id": "conversation-003",
           "langfuse_user_id": "user-12345"
       }
   }
)
print(f"Response: {user_response['answer']}")

O campo langfuse_user_id marca o trace com o ID do usuário. Rode o script:

uv run python user_tracking.py

Você verá:

Response: The recommended security controls for AI systems include:

1. Adaptive defenses: Incorporate machine learning-powered filters that continuously learn and adapt to new adversarial techniques.
2. Defense-in-depth: Introduce layered security mechanisms, such as refusal classifiers and real-time input monitoring, to fortify AI system integrity.
3. Data classification: Properly classify your data according to sensitivity.
......

Agora vá ao painel do LangFuse. Clique em “Users” na barra lateral e você verá user-12345 listado. Clique no usuário para ver todos os traces dele em diferentes sessões.

Essa visão por usuário ajuda a responder perguntas como “Quanto o usuário X nos custou este mês?” ou “Que tipo de pergunta o usuário Y faz com frequência?”. Você pode acompanhar o comportamento individual e depurar problemas específicos.

Gestão de prompts no LangFuse

Seu sistema de Q&A tem um problema: o prompt está enterrado no código. Para mudar como o sistema responde, você precisa editar o qa_chain.py, testar localmente e fazer deploy. Se alguém do time quiser tentar uma abordagem diferente, precisa entender a estrutura do código e criar um branch novo. Você não consegue comparar versões de prompt lado a lado nem reverter para a versão da semana passada sem fuçar o histórico do Git.

A gestão de prompts resolve isso ao armazená-los fora do código. Você edita na interface, tem versionamento automático e busca em tempo de execução. Seu código permanece o mesmo enquanto seus prompts evoluem.

O problema do prompt colaborativo

Veja o prompt na sua chain de Q&A:

prompt = ChatPromptTemplate.from_messages([
   ("system", "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\n{context}"),
   ("human", "{input}"),
])

Isso funciona para projetos solo. Mas quando você trabalha em equipe ou roda em produção, prompts hardcoded causam problemas:

• Atrito no deploy: toda mudança no prompt exige um deploy de código. Você não consegue fazer testes A/B sem alterar a aplicação. Se quiser trocar “Be brief and factual” por “Keep the answer concise”, precisa commitar, fazer push e redeploy.
• Sem controle de versão: o Git rastreia mudanças no código, mas não mostra qual versão de prompt performou melhor em produção. Você não vê métricas de “prompt v1” vs “prompt v2” nem reverte rápido sem um deploy.
• Gargalos no time: pessoas não técnicas não conseguem iterar nos prompts. Seu PM tem ideias de melhorias, mas precisa pedir para um engenheiro mudar. Isso desacelera a experimentação.
• Dificuldade de testes: comparar variações de prompt exige rodar múltiplas versões do código. Você não testa respostas concisas versus detalhadas lado a lado sem trabalho manual.

A gestão de prompts do LangFuse resolve isso tratando prompts como dados, não como código.

Criando e versionando prompts

O LangFuse armazena seus prompts em um local central com versionamento automático. Você pode criá-los pela UI ou via SDK.

Criando prompts na UI

Vá ao painel do LangFuse e clique em “Prompts” na barra lateral. Clique em “New Prompt” para criar um.

Você verá um formulário onde pode:

• Dar um nome ao prompt (use document-qa-prompt)
• Escolher o tipo (text ou chat)
• Escrever o template do prompt com variáveis usando a sintaxe {{variable}}
• Definir configurações como modelo e temperatura
• Adicionar labels para marcar versões (como production ou staging)

Para nosso sistema de Q&A, crie um prompt de chat com duas mensagens:

Mensagem de sistema:

Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.

{{context}}

Mensagem do usuário:

{{input}}

O LangFuse detectará automaticamente as variáveis {{context}} e {{input}}.

Em seguida, defina a config para:

{
 "model": "gpt-4",
 "temperature": 0.0
}

Adicione o label production para marcar esta como sua versão de produção.

Ao salvar, o LangFuse cria a versão 1 do seu prompt. Toda edição salva cria uma nova versão. As versões antigas permanecem disponíveis.

Criando prompts via SDK

Você também pode criar prompts usando o SDK em Python:

from langfuse import Langfuse

langfuse = Langfuse()

langfuse.create_prompt(
   name="document-qa-prompt",
   type="chat",
   prompt=[
       {"role": "system", "content": "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\n{{context}}"},
       {"role": "user", "content": "{{input}}"}
   ],
   labels=["production"]
)

Isso cria o mesmo prompt de forma programática. Se você chamar create_prompt() novamente com o mesmo nome, o LangFuse adiciona uma nova versão em vez de sobrescrever.

Controle de versão com labels

O LangFuse rastreia cada mudança no prompt com números de versão (v1, v2, v3). Você também pode atribuir labels às versões. Labels ajudam a gerenciar deploys:

• production - a versão que seu app em produção usa
• staging - a versão no ambiente de homologação
• latest - aponta automaticamente para a versão mais recente

Quando você melhora seu prompt, cria uma nova versão. Teste em staging primeiro dando a ela o label staging. Quando estiver ok, mova o label production para a nova versão. Seu app de produção pega a mudança automaticamente na próxima busca do prompt.

Testando variações no playground

A UI do LangFuse inclui um playground para testar prompts antes de usá-los no código. Você pode:

• Experimentar diferentes valores de variáveis
• Comparar múltiplas versões lado a lado
• Ver como mudanças afetam o output
• Compartilhar resultados de teste com seu time

Assim, pessoas não técnicas podem experimentar redações sem tocar no código.

Integrando prompts gerenciados no código

Veja como usar prompts gerenciados pelo LangFuse na sua aplicação. Esse fluxo mantém seu código estável enquanto os prompts evoluem.

Passo 1: buscar o prompt

No seu código, busque o prompt do LangFuse em vez de hardcodá-lo:

from langfuse import Langfuse

langfuse = Langfuse()

# Get the production version
prompt = langfuse.get_prompt("document-qa-prompt", type="chat")

Isso busca a versão com o label production. O LangFuse faz cache dos prompts no cliente, então não há impacto de latência nas chamadas ao LLM.

Você também pode buscar versões ou labels específicos:

# Get version 2 specifically
prompt = langfuse.get_prompt("document-qa-prompt", version=2, type="chat")

# Get staging version
prompt = langfuse.get_prompt("document-qa-prompt", label="staging", type="chat")

# Get latest version (automatically maintained by LangFuse)
prompt = langfuse.get_prompt("document-qa-prompt", label="latest", type="chat")

Passo 2: compilar o prompt com variáveis

O prompt buscado é um template com {{variables}}. Compile substituindo variáveis pelos valores reais:

compiled_messages = prompt.compile(
   context="Retrieved document context goes here",
   input="What are the main security risks?"
)

Isso retorna uma lista de mensagens de chat prontas para enviar ao seu LLM:

[
   {
       "role": "system",
       "content": "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\nRetrieved document context goes here"
   },
   {
       "role": "user",
       "content": "What are the main security risks?"
   }
]

Passo 3: usar o prompt compilado com seu LLM

Passe as mensagens compiladas para a chamada do seu LLM. O código exato depende se você usa LangChain, o SDK da OpenAI diretamente ou outro framework.

Passo 4: vincular o prompt aos traces

Ao fazer uma chamada de LLM com um prompt gerenciado pelo LangFuse, vincule-a ao trace. Assim você vê qual versão de prompt foi usada em cada chamada e acompanha métricas por versão:

from langfuse.langchain import CallbackHandler

langfuse_handler = CallbackHandler()

response = qa_chain.invoke(
   {"input": "What are the main security risks?"},
   config={"callbacks": [langfuse_handler]}
)

No painel do LangFuse, você verá traces agrupados por nome e versão do prompt. Isso mostra quais versões custam mais, rodam mais devagar ou geram melhores resultados.

Passo 5: iterar sem mudar código

É aqui que a gestão de prompts brilha. Para melhorar seu prompt:

1. Abra a UI do LangFuse
2. Edite seu prompt (cria nova versão automaticamente)
3. Teste no playground
4. Atribua o label staging para testar no ambiente de homologação
5. Mova o label production para fazer o deploy

Seu código não muda. Na próxima chamada a get_prompt(), ele busca a nova versão.

Passo 6: rollback se precisar

Se o novo prompt performar pior, faça rollback movendo o label production de volta para a versão anterior. Sem deploy de código.

Esse fluxo separa engenharia de prompts da engenharia de software. Seu time itera rápido nos prompts enquanto o código da aplicação permanece estável.

Para saber mais: o LangFuse também oferece testes A/B para dividir tráfego entre versões de prompt, webhooks para notificar seus sistemas quando prompts mudam e recursos de colaboração, como comentários e fluxos de aprovação. Esses recursos avançados ajudam times maiores a gerenciar prompts em escala. Confira a documentação de gestão de prompts para detalhes.

Avaliação no LangFuse

Você construiu um sistema de Q&A, adicionou observabilidade e configurou gestão de prompts. Mas como saber se as respostas são boas? Por enquanto, você deve estar testando manualmente: faz uma pergunta, lê a resposta e julga. Isso funciona para poucos exemplos, mas não escala.

O que acontece quando você muda o prompt? Precisa testar tudo de novo. E os casos extremos? Você não lembra de todas as perguntas que já testou. E quando for para produção, não tem como medir se a versão 2 do prompt é melhor que a versão 1.

A avaliação resolve isso medindo sistematicamente o desempenho do seu LLM. O LangFuse oferece ferramentas para pontuar respostas automaticamente, comparar versões de prompt com métricas reais e detectar problemas de qualidade antes de chegarem aos usuários.

Abordagens sistemáticas de avaliação de LLM

Testes manuais dizem se uma resposta específica está boa. Avaliação sistemática diz se o sistema inteiro funciona bem em centenas ou milhares de exemplos.

Veja como funciona a avaliação sistemática no LangFuse:

1. Crie um dataset de teste: colete de 20 a 50 perguntas que representem uso real, incluindo edge cases em que a resposta não está nos documentos.
2. Escolha métodos de pontuação: decida quais dimensões de qualidade importam para seu sistema de Q&A (vamos falar disso na próxima seção).
3. Rode seu sistema no dataset: processe cada pergunta e registre os resultados como traces no LangFuse.
4. Pontue as respostas: aplique seus métodos de pontuação automaticamente em cada resposta.
5. Analise os resultados: o LangFuse agrega as pontuações no conjunto de teste e mostra quais exemplos falharam.
6. Itere e compare: mude seu prompt, rode o conjunto novamente e compare métricas para ver se melhorou.

Esse processo troca o “acho que esse prompt é melhor” por “este prompt teve 0,85 de relevância vs. 0,72 da versão antiga”.

Para um guia completo de abordagens de avaliação e como implementá-las no LangFuse, confira a documentação de overview de avaliação.

Entendendo LLM-as-a-Judge

Você precisa pontuar centenas de respostas. Fazer isso manualmente leva horas. LLM-as-a-judge automatiza usando outro LLM para avaliar as saídas do seu LLM principal.

Como funciona

Você entrega a um LLM juiz três coisas: a pergunta original, a resposta do seu sistema de Q&A e os critérios de pontuação. O juiz lê a resposta e atribui uma nota.

Para um sistema de Q&A, há diferentes dimensões de qualidade. Eis três juízes que você pode criar:

Juiz de correção: “Avalie se a resposta reflete corretamente as informações no contexto fornecido. Marque 1 se totalmente correta, 0,5 se parcialmente correta, 0 se incorreta ou alucinação.”

Isso pega respostas que contradizem seus documentos ou inventam coisas.

Juiz de relevância: “Avalie se a resposta aborda diretamente a pergunta. Marque 1 se altamente relevante, 0,5 se parcialmente, 0 se fora do tema.”

Isso garante que o sistema se mantenha no tema em vez de dar informação correta porém irrelevante.

Juiz de fundamentação: “Avalie se a resposta se baseia apenas no contexto fornecido. Marque 1 se totalmente fundamentada no contexto, 0,5 se parcialmente, 0 se incluir informação fora do contexto.”

Isso evita alucinações em que o LLM adiciona fatos que não estão nos seus documentos.

Cada juiz olha uma dimensão específica. Você roda os três em cada resposta e obtém um perfil de qualidade completo. Pode adicionar juízes para estilo (é conciso?), tom (é profissional?) ou tratamento de recusa (diz “não sei” quando apropriado?).

Configurando juízes no LangFuse

O LangFuse permite configurar juízes de LLM pela UI ou API. O processo:

1. Defina o prompt do juiz: escreva instruções claras de pontuação com critérios específicos para cada nível.
2. Escolha o modelo juiz: use GPT-4, Claude ou outro LLM. Modelos mais fortes pontuam melhor, mas custam mais.
3. Configure o juiz no LangFuse: crie um template de pontuação que o LangFuse aplicará automaticamente aos traces.
4. Teste seu juiz: rode em alguns exemplos com nota conhecida. Ajuste o prompt se o juiz estiver muito rígido ou permissivo.
5. Aplique ao seu dataset: o LangFuse pontua todos os seus traces automaticamente quando o juiz estiver calibrado.

Os juízes rodam de forma assíncrona, então não atrasam sua aplicação principal. Você confere as notas no painel do LangFuse após o término dos testes.

Quando juízes funcionam bem

Juízes LLM funcionam melhor para critérios subjetivos difíceis de medir com código: tom, relevância, estilo. São menos confiáveis para fatos objetivos. Se você precisa verificar “2+2=4”, escreva uma checagem determinística, não use um juiz.

No nosso sistema de Q&A, juízes funcionam bem para relevância e fundamentação, mas você pode combiná-los com checagens determinísticas para critérios como “resposta com menos de 100 palavras”.

Limitações a considerar

Juízes LLM não são perfeitos. Eles podem discordar entre si, ter viés por certos estilos de resposta e errar ao dar notas altas para respostas confiantes porém incorretas.

Para lidar com isso, teste seus juízes em exemplos com gabarito conhecido, use múltiplos juízes e faça média das notas, e faça amostragens manuais para flagrar erros do juiz.

Nota de implementação: fluxos completos de avaliação envolvem montar datasets, configurar juízes, rodar avaliações em lote e analisar resultados. Isso exige mais setup do que cabe neste tutorial mantendo a praticidade. A documentação de LLM-as-a-judge traz todos os detalhes, incluindo exemplos de código e boas práticas. Para abordagens personalizadas além de juízes LLM, veja o guia de pontuações customizadas.

O fluxo que descrevemos aqui mostra a mentalidade de avaliação. Depois que você tem traces e prompts gerenciados no LangFuse, adicionar avaliação sistemática é um passo natural. Construa conjuntos de teste aos poucos, comece com juízes simples e refine à medida que entende quais métricas importam para sua aplicação.

Para saber mais: o LangFuse também oferece gestão de datasets para organizar casos de teste, funções de pontuação customizadas para checagens determinísticas e avaliação contínua que roda automaticamente no tráfego de produção. Esses recursos ajudam você a manter qualidade conforme o sistema escala. Veja a visão geral de avaliação para o panorama completo.

Conclusão

Você construiu um sistema de Q&A de documentos e aprendeu como os três pilares do LangFuse funcionam juntos. Observabilidade mostra o que acontece quando seu LLM roda: cada trace, cada custo, cada token. A gestão de prompts tirou seus prompts do código e os levou para um sistema com versionamento onde você pode iterar sem deploys. A avaliação trouxe formas de medir qualidade de forma sistemática, em vez de suposições. Tudo se conecta: traces alimentam datasets de avaliação, versões de prompt se ligam a métricas de performance, e o sistema inteiro ajuda você a entender se mudanças melhoram ou pioram os resultados.

Comece pequeno nos seus projetos. Escolha um recurso. Talvez adicionar tracing para ver onde seu app gasta dinheiro, ou mover um prompt hardcoded para a gestão do LangFuse. Os padrões que você aprendeu com nosso exemplo simples de Q&A escalam para pipelines RAG complexos, sistemas multiagente e aplicações em produção atendendo milhares de usuários. Confira a documentação do LangFuse para se aprofundar em recursos específicos, ou teste os notebooks de exemplo que mostram implementações reais. Da próxima vez que você construir com LLMs, terá ferramentas para ver o que está acontecendo, controlar o que muda e medir o que importa.