Neste artigo
Você subiu um agente que parecia funcionar no desenvolvimento, botou em produção e agora recebe reclamação de resposta estranha. O problema: você não tem log nenhum das chamadas ao LLM. O Langfuse self-hosted resolve exatamente esse buraco, e você consegue subir em menos de dez minutos com Docker Compose.
O que é o Langfuse
Langfuse é uma plataforma open source de observabilidade para LLMs. Ele rastreia cada chamada ao modelo com o prompt completo, a resposta, o tempo de execução, o custo estimado, e permite anotar e avaliar esses resultados depois.
Não é um substituto para Prometheus ou Grafana. Se você já configurou monitoramento de infraestrutura com Prometheus e Grafana, sabe que essas ferramentas cuidam de métricas de sistema. O Langfuse cuida do que acontece dentro da chamada ao LLM.
Por que o Langfuse self-hosted faz sentido
A versão cloud do Langfuse existe e funciona. Mas para a maioria dos projetos com volume moderado, self-hosted é a escolha certa por três razões:
- Seus prompts e respostas ficam no seu servidor, não em infraestrutura de terceiro
- O custo operacional é basicamente zero além do que você já tem rodando
- Você controla retenção de dados e acesso sem depender de política de terceiro
Se você já tem uma VPS com Docker, não tem motivo para pagar cloud quando o Langfuse self-hosted cobre tudo que você precisa.
Quando o rastreamento de LLM faz diferença
Tem projeto que vai bem sem isso por meses. O problema aparece quando:
- Um usuário reclama de uma resposta específica e você não tem como reproduzir
- O custo de API sobe e você não sabe qual chamada está custando mais
- Você muda o prompt e não tem base para comparar se melhorou ou piorou
- Você opera com múltiplos modelos e quer comparar qualidade de resposta lado a lado
Qualquer um desses cenários é sinal de falta de visibilidade. E monitorar custo e latência de LLMs fica impossível sem saber exatamente o que está sendo chamado.
O que o Langfuse rastreia na prática
Traces e spans
Cada chamada ao modelo vira um "trace" com um ou mais "spans". Se você tem um agente que faz três chamadas em sequência, o Langfuse mostra as três em ordem, com o tempo de cada uma e o custo associado. Dá para enxergar onde a latência está concentrada sem precisar cruzar logs na mão.
Prompts versionados
O Langfuse tem um gerenciador de prompts integrado. Você versiona seus prompts lá dentro e faz referência no código. Quando muda, a versão anterior fica registrada com todas as chamadas que a usaram. Facilita comparar comportamento antes e depois de qualquer alteração.
Avaliação de respostas
Você pode anotar respostas diretamente na interface ou configurar avaliadores automáticos que pontuam as respostas sem intervenção manual. Se quiser entender como esse processo de avaliação funciona no nível conceitual, o post sobre avaliação de respostas de LLM em produção cobre esse terreno bem.
Como subir o Langfuse com Docker Compose
Se você já tem Docker instalado, a sequência é rápida. A documentação oficial do Langfuse disponibiliza um docker-compose.yml pronto para uso:
- git clone https://github.com/langfuse/langfuse.git && cd langfuse
- cp .env.example .env (edite NEXTAUTH_SECRET, SALT e as credenciais do banco antes de continuar)
- docker compose up -d
- Acesse http://localhost:3000 e crie sua conta
Se você nunca montou um ambiente com Docker Compose, o post Docker Compose do zero cobre o que você precisa saber antes de chegar nessa etapa.
Uma coisa que engana: o .env.example tem variáveis que parecem opcionais mas não são em produção. Deixar NEXTAUTH_SECRET ou SALT com valor padrão levanta a instância, mas de forma insegura. Troca esses valores antes de expor a qualquer rede.
Integrando com sua aplicação
O Langfuse tem SDK para Python e JavaScript. Para quem usa LangChain ou LlamaIndex, existem callbacks oficiais que fazem rastreamento automático sem mudar o código de chamada ao modelo. Para integração com Claude via API direta, você cria a trace manualmente antes da chamada e fecha ao final. Trabalho de alguns minutos.
O Langfuse é agnóstico a modelo. Funciona com OpenAI, Anthropic, Mistral e modelos locais via Ollama sem diferença de configuração.
Langfuse vs alternativas
Existem outras opções: LangSmith (cloud-first da Langchain), Helicone, Arize Phoenix, Braintrust.
Na minha visão, o Langfuse ganha pelo self-hosted funcional sem custo fixo. O LangSmith é uma boa escolha se você já está no ecossistema LangChain e aceita depender de SaaS. O Arize Phoenix é interessante para avaliações mais sofisticadas com datasets maiores. Para a maioria dos projetos, Langfuse resolve com sobra.
O que você perde sem rastreamento de LLM
Um agente sem rastreamento vai funcionar. O problema aparece quando você precisa debugar um comportamento que acontece em 5% das requisições, quando quer medir o impacto de uma mudança de prompt, ou quando o custo de API cresce e você não sabe onde.
Sem rastreamento, você opera no escuro. Para projetos pequenos isso pode ser aceitável por um tempo. Para qualquer coisa que vai para usuários reais, o risco cresce com o volume.
Perguntas frequentes
O Langfuse funciona com qualquer LLM?
Sim. O Langfuse é agnóstico a modelo. Funciona com OpenAI, Anthropic, Mistral, modelos locais via Ollama e qualquer API compatível. A integração é via SDK oficial ou chamada HTTP direta.
Precisa de banco de dados separado?
O docker-compose que o Langfuse disponibiliza já inclui PostgreSQL. Para ambiente de produção com volume alto, vale usar um banco externo gerenciado. Para projetos menores, o banco embutido no Compose resolve bem.
O Langfuse self-hosted escala bem?
Para volumes de até algumas dezenas de milhares de traces por dia, uma VPS com 2 vCPUs e 4 GB de RAM dá conta tranquilo. Acima disso, começa a valer ajustar configurações de banco e worker separadamente.
Tem limitação comparado ao cloud?
A versão self-hosted tem paridade quase total com o cloud. O que fica de fora são algumas features de Enterprise, como SSO e permissões granulares. Para a maioria dos casos de uso, self-hosted entrega tudo que você precisa.
Vale a pena para projetos pequenos?
Se é uso pessoal e pontual, provavelmente não vale o overhead de subir a infraestrutura. Se o projeto vai para usuários reais, mesmo que poucos, vale. O custo de não ter rastreamento aparece antes do que você espera.
Conclusão
Langfuse self-hosted é uma das ferramentas mais diretas para ganhar visibilidade sobre o que seu LLM está fazendo em produção. Não tem custo fixo além do servidor que você já tem, não é complexo de operar, e resolve uma lacuna real que aparece cedo em qualquer projeto com IA.
Se você ainda não tem rastreamento nenhum, começa por aqui. O setup é pequeno, e você vai querer ter feito isso antes do primeiro bug que chega de produção sem contexto nenhum para investigar.
Ação primária: suba o Langfuse no seu ambiente de testes essa semana. Leva menos de 15 minutos e o retorno aparece na primeira vez que você precisar debugar algo sem ter onde olhar.
Ação secundária: se você ainda não tem uma estratégia de avaliação de LLM, esse é o momento de montar as duas coisas juntas. Rastreamento sem avaliação é log. Rastreamento com avaliação é visibilidade de verdade.
