Langfuse: observar seus LLM locais (rastreamentos, prompts, avaliações)

#Por que observar um LLM local

O Langfuse é uma plataforma de observabilidade para aplicações LLM, cujo repositório principal está sob licença MIT, que você pode hospedar por conta própria para manter os registros das suas conversas no seu ambiente. Ele registra, para cada requisição, o prompt realmente enviado ao modelo, a resposta, a duração de cada etapa e, se um preço estiver definido, o custo. Ele serve para entender por que uma resposta é ruim: trecho recuperado fora do assunto, prompt diferente do que você imaginava ou falha do modelo. Ele se torna útil assim que uma segunda pessoa depende do resultado ou quando a cadeia tem várias etapas; para uso exploratório individual, um arquivo de log basta. Preveja uma pilha de vários contêineres (servidor web, worker, PostgreSQL, ClickHouse, Redis, armazenamento de objetos) e, para produção, Kubernetes em vez de Docker Compose.

Quando uma resposta decepciona, três causas são possíveis e apenas uma é visível sem instrumentação: o prompt final enviado ao modelo não era o que você imaginava, os trechos recuperados pela busca documental estavam fora de contexto, ou o próprio modelo falhou. Sem registro, altera-se o prompt ao acaso até que o resultado melhore, sem nunca saber por quê.

O argumento é o mesmo tanto localmente quanto online, com uma diferença: a fatura deixa de ser o indicador que alerta você. Ninguém recebe um extrato quando uma cadeia de agentes entra em loop na sua própria placa gráfica; a latência e o calor é que indicam isso. A observabilidade substitui esse sinal de preço por métricas: número de tokens, duração, taxa de falha, qualidade.

#O que o Langfuse registra

O projeto apresenta-se como uma plataforma open source de avaliação de agentes e observabilidade: rastrear, avaliar e melhorar aplicações LLM em uma única plataforma aberta. Seus SDKs em Python (versão 4) e JS/TS (versão 5) são baseados em OpenTelemetry, e outras linguagens podem enviar seus rastros por esse protocolo. O repositório principal ultrapassa 35.000 estrelas no GitHub. Seu README indica que o Langfuse faz parte do ClickHouse desde janeiro de 2026, e o ClickHouse também é o banco de dados que armazena os rastros.

Traces

O fluxo completo de uma solicitação do usuário: cada etapa, na ordem, com sua duração. Esta é a unidade básica.

Observações

Dentro de um rastreamento: as chamadas ao modelo com seu prompt exato e sua resposta, as etapas de recuperação de documentos, as chamadas às ferramentas.

Sessões e usuários

O agrupamento dos rastros por conversa e por pessoa, para acompanhar um percurso em vez de uma chamada isolada.

Pontuações

Uma pontuação associada a um trace: uma avaliação positiva de um usuário, o resultado de uma avaliação automática ou uma anotação manual.

Prompts

Templates de prompt, versionados, recuperados pela aplicação durante a execução, em vez de codificados diretamente no código.

Custos

O Langfuse calcula um custo a partir de uma definição de modelo que associa um preço a cada tipo de uso. Ele fornece essas definições para modelos da OpenAI, Anthropic e Google. Para um modelo local, não há preço definido até que você adicione um: sem uma definição, não procure custos na interface, ou defina um preço fictício para refletir a eletricidade e a amortização.

#Instalá-lo em casa

O Langfuse pode ser auto-hospedado com Docker Compose. O README anuncia uma inicialização em cinco minutos; a documentação de implantação indica dois a três minutos até que o contêiner web exiba “Ready”. A pilha não se limita a um contêiner: são dois contêineres de aplicação (o servidor web, que fornece a interface e a API, e um worker que processa os eventos de forma assíncrona) e quatro componentes de armazenamento: PostgreSQL para os dados transacionais, ClickHouse para os rastreamentos, as observações e as pontuações, Redis ou Valkey para a fila e o cache, e um armazenamento de objetos compatível com S3 que mantém todos os eventos recebidos. É mais pesado que um simples painel, como consequência do que se exige dele: ingerir muitos eventos sem perder nenhum rastreamento, mesmo que o banco de dados fique temporariamente indisponível.

Duas limitações a conhecer antes de instalá-lo junto com um modelo. Primeiro, a documentação diz que o Docker Compose serve para testes: essa configuração não oferece alta disponibilidade, escalabilidade nem backup, e a documentação recomenda Kubernetes com Helm para produção. Segundo, para uma máquina virtual, ela recomenda pelo menos 4 núcleos, 16 GiB de memória e 100 GiB de armazenamento. Em um computador que já está servindo um modelo, essas ordens de grandeza importam: uma pilha de observabilidade que consome parte da memória do modelo faz isso no pior momento. Por fim, altere os segredos do arquivo docker-compose.yml marcados como CHANGEME: não existe uma conta padrão; o primeiro usuário é criado pelo botão Sign up em http://localhost:3000.

git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
# Éditer docker-compose.yml : remplacer chaque secret marqué CHANGEME
docker compose up
# Après 2 à 3 minutes, le conteneur web affiche « Ready » : ouvrir http://localhost:3000

#Conectá-lo ao Ollama ou ao vLLM

O Langfuse não é um servidor de inferência e não se coloca no caminho do tráfego: é a sua aplicação que envia os rastros de execução para ele. O projeto documenta três caminhos concretos de acordo com a forma como você chama seu modelo, além de uma página dedicada ao Ollama, cujo exemplo utiliza o SDK OpenAI: o Ollama expõe uma API compatível com OpenAI no endereço http://localhost:11434/v1, e o Langfuse fornece um substituto direto desse SDK, que exige apenas mudar a importação. Também existe uma página para vLLM.

1. 01
   Pelo SDK, no seu código

   Você aplica decoradores às funções que chamam o modelo. Essa é a abordagem mais explícita e fiel, pois você escolhe o que é rastreado.
2. 02
   Por meio de uma integração com um framework

   Existe instrumentação automatizada para uma substituição direta do SDK OpenAI, para um gerenciador de callbacks integrado a uma aplicação LangChain e para o sistema de callbacks do LlamaIndex: os traces são enviados sem alterar a lógica de negócio.
3. 03
   Por meio de um gateway de API

   Se suas chamadas já passam por um roteador compatível com OpenAI, a instrumentação ocorre nesse nível e cobre todas as aplicações de uma vez.

Nos três casos, o ponto a verificar é se o prompt realmente transmitido está sendo registrado, e não apenas a pergunta do usuário: é precisamente a diferença entre os dois que explica a maioria das respostas incorretas de um sistema de busca documental. Com Ollama, a configuração abaixo aponta LANGFUSE_BASE_URL para sua instância auto-hospedada (http://localhost:3000) e declara suas chaves pública e secreta em variáveis de ambiente.

# pip install langfuse openai
# Variables d'environnement : LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY,
# LANGFUSE_BASE_URL=http://localhost:3000
from langfuse.openai import OpenAI  # remplace : from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1',
    api_key='ollama',  # requis mais inutilisé
)
reponse = client.chat.completions.create(
    model='llama3.1',
    messages=[{'role': 'user', 'content': 'Bonjour !'}],
)

• Centralizar suas chamadas com um gateway compatível com OpenAI
• Implantar o vLLM para atender a vários usuários
• Chamar Ollama pelo Python
• Ragas: avaliar um RAG local com números
• Fonte: detalhes das integrações com SDKs, frameworks e gateways

#Gerenciar e versionar os prompts

Tirar os prompts do código é o benefício que as equipes percebem primeiro. De acordo com o README, um cache robusto no servidor e no cliente permite iterar sobre os prompts sem aumentar a latência da aplicação. O template fica no Langfuse, a aplicação o recupera em tempo de execução e cada alteração cria uma versão. Corrigir uma formulação não exige mais uma nova implantação e, sobretudo, o registro de rastreamento indica qual versão produziu qual resposta: quando a qualidade cai após uma mudança, fica claro qual mudança é a responsável, sem precisar cruzar logs de implantação separados.

#Conjuntos de teste e avaliação

Os rastros reais de execução alimentam conjuntos de teste: você marca os casos interessantes — sobretudo as falhas — e eles se tornam uma coleção com a qual testar novamente uma nova versão do prompt ou outro modelo. É isso que permite responder com seriedade à pergunta «o modelo de 14 bilhões de parâmetros é suficiente?», em vez de apenas discutir o assunto.

As pontuações vêm de várias fontes: os usuários, uma anotação humana na interface, avaliadores baseados em código ou um modelo que julga a resposta de outro segundo uma grade de critérios — o método chamado LLM-as-a-judge, que o Langfuse oferece nativamente. Neste último caso, é necessário criar uma conexão com um LLM. A documentação indica que qualquer modelo que siga o esquema da API da OpenAI serve, substituindo a URL base: um modelo local servido pelo Ollama pode, portanto, atuar como juiz, desde que seu endereço seja acessível a partir do contêiner do Langfuse. O método é útil e apresenta vieses: os autores do artigo de referência sobre o tema (arXiv 2306.05685) descrevem vieses de posição, de verbosidade e de preferência por si próprio, ao mesmo tempo que medem mais de 80% de concordância entre um juiz do tipo GPT-4 e preferências humanas. Ele serve para comparar duas versões, não para atribuir uma nota absoluta.

Uma ferramenta dedicada à avaliação do RAG, como o Ragas, complementa o Langfuse em vez de substituí-lo: o Langfuse captura o rastreamento e armazena a pontuação, enquanto o Ragas calcula métricas específicas — fidelidade ao contexto, relevância da resposta — que o Langfuse pode então exibir como qualquer outra pontuação associada a um rastreamento.

#Casos de uso concretos

Assistente de suporte com RAG

Uma resposta fora do assunto pode ser investigada no registro de execução: o trecho recuperado era relevante ou o modelo ignorou um trecho correto? Esse registro permite decidir entre as duas hipóteses.

Agente que chama ferramentas

Em uma cadeia com várias etapas — pesquisa, cálculo, redação —, o rastreamento mostra qual delas falhou, em vez de deixar você tentando adivinhar diante de uma falha geral sem detalhes.

Comparação de dois modelos antes de decidir

Repetir o mesmo conjunto de testes com um modelo de 8 bilhões e depois com um de 27 bilhões de parâmetros fornece uma medida de qualidade e uma duração, em vez de uma impressão.

Acompanhamento de uma regressão após uma atualização

Uma mudança de versão do prompt ou do modelo que degrada a qualidade aparece nas pontuações agregadas antes que um usuário se queixe.

O ponto em comum nesses casos: nenhum deles se resolve relendo o código. A causa de uma resposta ruim está nos dados que passaram pelo sistema — o prompt exato, os trechos recuperados, a resposta gerada — e esses dados não existem em nenhum outro lugar se não tiverem sido registrados no momento da chamada. Esse é o argumento central a favor de implementar a observabilidade antes de colocar o sistema em operação, em vez de esperar pelo primeiro incidente.

#Quanto custa e o que não faz

Isso não torna um modelo melhor

A observabilidade mede, mas não corrige nada. Ela diz onde procurar.

Isso armazena suas conversas

Mesmo em uma instalação auto-hospedada, o conteúdo dos prompts é gravado no disco e, sem uma política de retenção (recurso da edição empresarial), os dados são mantidos indefinidamente. Os SDKs, por outro lado, oferecem funções de mascaramento (masking) para remover dados sensíveis antes do envio dos traces.

É uma pilha para manter

Backups, atualizações, migrações: a própria documentação diz que o Docker Compose não oferece backup. Para uma experimentação pessoal, isso é desproporcional.

Muitas vezes, isso acontece tarde

O momento certo para instalá-lo é antes da entrada em operação, não após a primeira falha silenciosa.

• Fonte: repositório oficial do Langfuse no GitHub
• Fonte: repositório oficial do Ragas, para avaliação de RAG

#FAQ