Langfuse: como ver o que seu chatbot faz em produção

Índice

• As três falhas silenciosas de um bot com IA
• O que é a observabilidade de LLMs
• O que o Langfuse resolve

  • Quanto custa
• Seu primeiro trace em dez minutos

  • Se você quiser os dados no seu servidor
• Quando vale a pena
• Construir é metade do trabalho

Numa segunda-feira chega a mensagem do cliente: "O bot disse a uma usuária que o frete era grátis. Não é". Você abre o painel e vê a conversa. O que você não vê é por que ele respondeu isso.

Qual prompt estava ativo? Quais documentos a busca passou? Foi o modelo, o contexto ou uma mudança de sexta? Sem esses dados, corrigir é chutar.

No trabalho de implementar chatbots e fluxos de WhatsApp para empresas, essa cena se repete. Quase todo conteúdo sobre IA ensina a construir o bot. Muito pouco ensina a saber o que ele está fazendo depois que fala com clientes reais. Se você ainda está montando esse fluxo, a peça anterior está em como levar um processo a um chatbot. Isso é o que vem depois do lançamento.

As três falhas silenciosas de um bot com IA

Um bot tradicional falha com barulho: cai, devolve um erro e alguém fica sabendo. Um bot com IA falha em silêncio, porque sempre responde alguma coisa. Estas são as três falhas que mais aparecem em produção:

1. Respostas que soam bem e estão erradas. O modelo inventa um preço, uma política ou um horário com total segurança. Ninguém nota até um cliente reclamar.
2. Custos que disparam sem uma causa visível. Um histórico que cresce sem limite, ou um loop num agente, dobra a fatura da API. A fatura chega no fim do mês, quando já não há o que cortar.
3. Prompts que pioram sem que ninguém saiba. Você muda o prompt para corrigir um caso e quebra outros três. Sem versões comparáveis, você descobre pelos usuários.

As três têm a mesma causa: o problema não é só o modelo. É que você não consegue ver o que aconteceu por dentro.

O que é a observabilidade de LLMs

Pense na caixa-preta de um avião. Ela não evita o acidente. Permite reconstruir, passo a passo, o que aconteceu. A observabilidade de LLMs faz isso com o seu bot: guarda cada passo de cada conversa para revisar depois.

Cada interação fica registrada como um trace. A pergunta "O frete é grátis?" apareceria assim:

• Trace: mensagem da usuária no WhatsApp (1,8 s · USD 0,004)
  • Busca na base de conhecimento: os documentos que encontrou
  • Chamada ao modelo: o prompt exato e a versão, a resposta e os tokens
  • Resposta enviada ao usuário

Com isso, o caso do frete grátis se resolve em minutos. Você vê que a busca trouxe uma promoção vencida e que o modelo a tratou como vigente. Você não chuta mais: sabe o que corrigir.

Se você vem do marketing, é o equivalente a ter analytics das conversas: quem perguntou o quê, quanto custou e se a conversa saiu bem.

O que o Langfuse resolve

Langfuse é uma plataforma open source, com licença MIT, para rastrear, avaliar e melhorar aplicações com modelos de linguagem. Cada função responde a uma das falhas acima.

Função	O que faz	Qual falha resolve
Traces	Registra cada passo de cada conversa, com custo e latência	"Não sei por que respondeu isso"
Gestão de prompts	Versiona os prompts e permite voltar a uma versão anterior	"O prompt piorou e não sei quando"
Avaliações	Avalia respostas com outro modelo, com regras ou com revisão humana	"Soa bem, mas está errado"
Experimentos	Testa um prompt ou um modelo novo contra casos reais antes de publicar	"Consertei um e quebrei três"
Painéis	Custo, latência e qualidade ao longo do tempo, com alertas	"A fatura dobrou"

Conecta com OpenAI, Anthropic, Google, LangChain, o Vercel AI SDK, CrewAI, n8n e qualquer stack que fale OpenTelemetry. Na página de preços aparecem equipes como Canva, Khan Academy e Hugging Face.

Em 16 de janeiro de 2026, a ClickHouse comprou o Langfuse. O projeto continua open source e auto-hospedável, com a mesma licença MIT. No anúncio, a ClickHouse colocou o projeto acima das 20.000 estrelas no GitHub no fechamento de 2025. A compra não muda o uso deste guia: a nuvem segue nos mesmos endpoints e o código de instrumentação é o mesmo na nuvem ou num servidor próprio.

Quanto custa

Plano	Preço	Uso incluído	Retenção
Hobby	Grátis	50.000 unidades/mês, 2 usuários	30 dias
Core	USD 29/mês	100.000 unidades/mês, usuários ilimitados	90 dias
Pro	USD 199/mês	100.000 unidades/mês, usuários ilimitados	3 anos
Auto-hospedado	Grátis (você paga o seu servidor)	Sem teto da plataforma	A que você definir

Preços da página oficial, revisados em outubro de 2026. No Hobby não há unidades extras: ao atingir a cota, o plano não cobre mais. No Core e no Pro, as primeiras 100.000 unidades estão incluídas e o consumo adicional é cobrado por faixas, a partir de USD 8 a cada 100.000. Uma unidade é um ponto de rastreamento: o trace, cada passo e cada avaliação.

Para testar, o Hobby basta. Escolha a região ao criar o projeto. A nuvem guarda os dados nos Estados Unidos, na União Europeia ou no Japão, e a URL base muda conforme essa escolha.

Seu primeiro trace em dez minutos

O caminho mais curto é um bot em Python que já usa a OpenAI. Se você usa n8n, LangChain ou outra ferramenta, a ideia é a mesma e o detalhe está no guia de integrações.

1. Crie a conta em cloud.langfuse.com, crie um projeto e copie as duas chaves, a pública e a secreta.
2. Instale o pacote:

pip install langfuse openai

3. Configure as variáveis de ambiente. A URL da União Europeia é a de baixo. Se você escolheu outra região, use https://us.cloud.langfuse.com ou https://jp.cloud.langfuse.com.

LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_BASE_URL="https://cloud.langfuse.com"
OPENAI_API_KEY="sk-..."

4. Mude o import e agrupe a conversa. O Langfuse traz um substituto do cliente da OpenAI que registra a chamada. propagate_attributes marca o usuário e a sessão para o painel juntar os turnos de um mesmo chat. Em um script que termina logo, flush() envia os dados antes de o processo encerrar.

from langfuse import observe, propagate_attributes, get_client
from langfuse.openai import openai  # antes: import openai

@observe()
def responder(mensaje: str, usuario_id: str, conversacion_id: str):
    with propagate_attributes(user_id=usuario_id, session_id=conversacion_id):
        respuesta = openai.chat.completions.create(
            name="respuesta-bot",
            model="gpt-4o-mini",
            messages=[
                {"role": "system", "content": "Eres el asistente de una tienda online."},
                {"role": "user", "content": mensaje},
            ],
        )
        return respuesta.choices[0].message.content

print(responder("¿El envío es gratis?", "cliente-123", "chat-456"))
get_client().flush()

5. Abra o painel. Em Tracing você vê o trace com o prompt, a resposta, os tokens, o custo e o tempo. Com o session_id dá para seguir a conversa inteira daquele usuário.

Se você quiser os dados no seu servidor

Dá para auto-hospedar com Docker. No ambiente local, clone o repositório, revise os segredos marcados como CHANGEME no docker-compose.yml e suba os contêineres:

git clone https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up

A documentação diz que em uns 2 ou 3 minutos o contêiner web fica pronto em http://localhost:3000. Não há usuário administrador padrão: o primeiro acesso é um cadastro. Para uma máquina de produção, o mesmo guia recomenda pelo menos 4 núcleos e 16 GB de RAM, e lembra que o Compose não oferece alta disponibilidade. Para uma PME que está começando, o plano gratuito na nuvem costuma sair mais barato do que esse servidor.

Quando vale a pena

O Langfuse vale a pena a partir do momento em que o bot fala com clientes reais. Antes disso, quase sempre é demais.

Use se:

• O bot atende clientes ou lida com preços, pedidos ou suporte.
• Você implementa bots para terceiros e precisa explicar o que aconteceu quando algo falha.
• Você gasta mais do que alguns dólares por mês em APIs de IA e quer saber em quê.
• Você muda prompts com frequência ou mais de uma pessoa os edita.

Você ainda não precisa se:

• Está num protótipo só seu ou num teste de fim de semana.
• A plataforma do bot é fechada e não deixa conectar ferramentas externas. Nesse caso, veja quais registros a própria plataforma oferece.

Alternativas. LangSmith e Braintrust cobrem um terreno parecido. A diferença prática do Langfuse é que ele é open source e você pode levar os dados para um servidor próprio.

Construir é metade do trabalho

Lançar um bot com IA leva uma tarde. Saber se ele está funcionando bem é o que separa um experimento de um produto em que um cliente pode confiar.

O Langfuse não deixa o modelo mais inteligente. Faz algo mais útil: deixa ver o que está acontecendo, para corrigir com o prompt, os documentos e o custo visíveis. O plano de entrada é grátis. Seguir no escuro, depois da primeira reclamação de um cliente, já não tem desculpa.