AI Engineering Academy · Aula

Observabilidade independente de modelo com Langfuse

Observabilidade independente de modelo com Langfuse é uma aula grátis de AI Engineering Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Engineering Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Engineering Academy inclui 4 aulas no total.

Langfuse: observabilidade de LLM de código aberto

O Langfuse é uma plataforma de observabilidade de código aberto para aplicações de LLM que funciona com qualquer provedor de modelos: OpenAI, Anthropic, Mistral, modelos locais por meio do Ollama ou seu próprio modelo ajustado. Diferentemente do LangSmith, que vincula você ao LangChain, o Langfuse integra-se a qualquer código Python por meio de um SDK simples. Você pode hospedar o Langfuse por conta própria gratuitamente ou usar a nuvem gerenciada em cloud.langfuse.com.

# pip install langfuse
from langfuse import Langfuse

langfuse = Langfuse(
    public_key='pk-lf-...',
    secret_key='sk-lf-...',
    host='https://cloud.langfuse.com'  # or your self-hosted URL
)

print('Langfuse connected:', langfuse.auth_check())

Rastreamentos, intervalos e gerações

O Langfuse usa um modelo de dados hierárquico com três níveis. Um rastreamento representa uma solicitação de usuário de ponta a ponta. Dentro de um rastreamento, os intervalos representam etapas individuais de processamento (recuperação, pré-processamento e chamadas de ferramentas). As gerações são um tipo especial de intervalo, específico para chamadas de LLM: elas registram o modelo, os tokens do comando, os tokens da conclusão e o custo de forma estruturada, permitindo criar painéis de custos e métricas de qualidade.

from langfuse import Langfuse

langfuse = Langfuse()

# Create a trace for one user request
trace = langfuse.trace(
    name='rag-query',
    user_id='user_123',
    session_id='session_abc',
    tags=['production', 'rag']
)

# Add a retrieval span
retrieval_span = trace.span(
    name='vector-retrieval',
    input={'query': 'What is RAG?'}
)
chunks = vector_db.search('What is RAG?')
retrieval_span.end(output={'chunks': [c['text'][:100] for c in chunks]})

# Add an LLM generation
generation = trace.generation(
    name='answer-generation',
    model='gpt-4o',
    model_parameters={'temperature': 0.0},
    input=[{'role': 'user', 'content': 'Context: ...\nQuestion: What is RAG?'}]
)
response = openai_client.chat.completions.create(model='gpt-4o', messages=[...])
generation.end(
    output=response.choices[0].message.content,
    usage={'input': response.usage.prompt_tokens, 'output': response.usage.completion_tokens}
)

Padrão de integração com decoradores

O Langfuse fornece decoradores de funções que envolvem automaticamente suas funções com intervalos de rastreamento. O decorador @observe() registra entradas e saídas, tempo de execução e quaisquer exceções. Essa é a maneira mais simples de instrumentar código existente sem reestruturá-lo.

from langfuse.decorators import observe, langfuse_context

# @observe wraps the function as a span automatically
@observe()
def retrieve_chunks(query: str) -> list[dict]:
    return vector_db.search(query, top_k=5)

@observe()
def generate_answer(query: str, context: str) -> str:
    response = openai_client.chat.completions.create(
        model='gpt-4o',
        messages=[
            {'role': 'system', 'content': 'Answer using the context.'},
            {'role': 'user', 'content': f'Context: {context}\nQuestion: {query}'}
        ]
    )
    # Attach LLM usage data to the current span
    langfuse_context.update_current_observation(
        usage={'input': response.usage.prompt_tokens, 'output': response.usage.completion_tokens},
        model='gpt-4o'
    )
    return response.choices[0].message.content

@observe(name='rag-pipeline')  # top-level trace
def rag_pipeline(query: str) -> str:
    chunks = retrieve_chunks(query)  # becomes a nested span
    context = '\n'.join([c['text'] for c in chunks])
    return generate_answer(query, context)  # becomes another nested span

Integração com qualquer provedor de LLM

Diferentemente da integração profunda do LangSmith com o LangChain, o Langfuse funciona com qualquer provedor de LLM usando a mesma abordagem baseada em decoradores. Quer você esteja chamando a API da Anthropic, um modelo local do Ollama, um ponto de acesso de inferência do Hugging Face ou um modelo personalizado que tenha ajustado, o Langfuse rastreia a chamada da mesma maneira. Essa neutralidade em relação ao provedor é essencial quando você executa vários modelos na mesma aplicação.

from langfuse.decorators import observe, langfuse_context
import anthropic
from openai import OpenAI

anthropic_client = anthropic.Anthropic()
openai_client = OpenAI()

@observe()
def call_claude(prompt: str) -> str:
    response = anthropic_client.messages.create(
        model='claude-3-5-sonnet-20241022',
        max_tokens=1024,
        messages=[{'role': 'user', 'content': prompt}]
    )
    langfuse_context.update_current_observation(
        model='claude-3-5-sonnet-20241022',
        usage={'input': response.usage.input_tokens, 'output': response.usage.output_tokens}
    )
    return response.content[0].text

@observe()
def call_gpt4(prompt: str) -> str:
    response = openai_client.chat.completions.create(
        model='gpt-4o',
        messages=[{'role': 'user', 'content': prompt}]
    )
    langfuse_context.update_current_observation(model='gpt-4o',
        usage={'input': response.usage.prompt_tokens, 'output': response.usage.completion_tokens})
    return response.choices[0].message.content

Painéis de acompanhamento de custos

O Langfuse calcula automaticamente o custo a partir do nome do modelo e da contagem de tokens, usando uma tabela de preços integrada que abrange OpenAI, Anthropic, Mistral e dezenas de outros provedores. O painel de custos mostra: gasto total por período, custo dividido por modelo, custo dividido por funcionalidade ou usuário (usando etiquetas e metadados) e tendências de gastos diários e semanais. Essa visibilidade evita surpresas na conta e ajuda a identificar solicitações atípicas dispendiosas.

# Cost data is automatically computed - no manual config
# Langfuse knows: gpt-4o input = $0.005/1K tokens, output = $0.015/1K tokens

# Add metadata to enable cost breakdown by feature
@observe(name='rag-query')
def handle_rag_query(query: str, feature: str, user_id: str) -> str:
    langfuse_context.update_current_trace(
        user_id=user_id,
        tags=[feature, 'rag'],
        metadata={'feature': feature, 'query_length': len(query)}
    )
    return rag_pipeline(query)

# In Langfuse dashboard you can now filter costs by:
# - feature: 'document_qa', 'chat', 'summarization'
# - user_id: to see which users are your most expensive
# - model: to compare gpt-4o vs gpt-4o-mini costs
# - date range: to see daily/weekly/monthly trends

Adição de pontuações de feedback dos usuários

O Langfuse permite anexar feedback dos usuários aos rastreamentos posteriormente. Quando um usuário clica no polegar para cima ou para baixo em uma resposta, você pode registrar isso como uma pontuação no rastreamento correspondente. Assim, os sinais reais de satisfação dos usuários ficam associados ao contexto completo do rastreamento, permitindo analisar o que diferencia as respostas muito bem avaliadas das respostas mal avaliadas.

from langfuse.decorators import observe, langfuse_context

@observe()
def generate_response(query: str) -> dict:
    answer = rag_pipeline(query)
    # Get the current trace ID to link feedback later
    trace_id = langfuse_context.get_current_trace_id()
    return {'answer': answer, 'trace_id': trace_id}

# Later, when user submits feedback:
def record_user_feedback(trace_id: str, score: int, comment: str):
    langfuse.score(
        trace_id=trace_id,
        name='user_satisfaction',  # score name
        value=score,               # 1 (thumbs up) or 0 (thumbs down)
        comment=comment,
        data_type='BOOLEAN'
    )

# Now in Langfuse: filter traces where user_satisfaction = 0
# to find the exact prompts and contexts that users rated negatively

Pontuações automatizadas com LLM como avaliador

Além do feedback dos usuários, o Langfuse oferece suporte à pontuação automatizada usando avaliadores de LLM como avaliador. Você pode definir avaliadores que sejam executados de forma assíncrona em rastreamentos amostrados e atribuam pontuações segundo critérios como relevância, fidelidade, toxicidade ou correção do formato. Essas pontuações automatizadas preenchem o mesmo painel de pontuações que o feedback humano, proporcionando monitoramento contínuo da qualidade sem exigir anotação humana em grande escala.

from langfuse import Langfuse

langfuse = Langfuse()

def auto_score_traces():
    # Get recent unscored traces
    traces = langfuse.fetch_traces(tags=['production'], limit=50)
    
    for trace in traces.data:
        question = trace.input.get('query', '')
        answer = trace.output.get('answer', '') if trace.output else ''
        
        if not question or not answer:
            continue
        
        # LLM-as-judge scoring
        score = evaluate_relevance(question, answer)  # returns 0.0-1.0
        
        langfuse.score(
            trace_id=trace.id,
            name='auto_relevance',
            value=score,
            data_type='NUMERIC',
            comment='Automated relevance score from LLM judge'
        )

# Run this as a scheduled job every hour

Gerenciamento de comandos no Langfuse

O Langfuse inclui um recurso de gerenciamento de comandos que armazena seus comandos na nuvem do Langfuse e permite buscá-los durante a execução. Isso desacopla as versões dos comandos das implantações do código: você pode atualizar um comando na interface do Langfuse, e a alteração entra em vigor imediatamente, sem uma nova implantação do código. O Langfuse também registra qual versão do comando cada rastreamento usou, para que você possa comparar o desempenho entre versões.

from langfuse import Langfuse

langfuse = Langfuse()

# Fetch the current production prompt by name
# The prompt lives in Langfuse UI, not in your code
prompt = langfuse.get_prompt('rag-system-prompt', version='production')

# Use it in your pipeline
messages = [
    {'role': 'system', 'content': prompt.compile(context_limit=4000)},
    {'role': 'user', 'content': query}
]

response = openai_client.chat.completions.create(model='gpt-4o', messages=messages)

# The trace is automatically linked to the prompt version
# In Langfuse you can filter: show me traces using prompt v3 vs v4
# and compare their quality scores

Hospedagem própria do Langfuse

O Langfuse pode ser hospedado por conta própria com um único comando do Docker Compose, usando o PostgreSQL para armazenamento. Hospedar por conta própria significa que seus dados de rastreamento nunca deixam sua infraestrutura — algo essencial para aplicações que lidam com PII, dados médicos ou conteúdo proprietário. A versão hospedada por conta própria tem os mesmos recursos da nuvem gerenciada, mas exige que você gerencie a infraestrutura (cópias de segurança, escalabilidade e atualizações).

# Self-host Langfuse with Docker Compose
# docker-compose.yml (simplified)
# version: '3'
# services:
#   langfuse:
#     image: langfuse/langfuse:2
#     ports:
#       - '3000:3000'
#     environment:
#       - DATABASE_URL=postgresql://langfuse:password@postgres/langfuse
#       - NEXTAUTH_SECRET=your-random-secret
#       - SALT=your-random-salt
#   postgres:
#     image: postgres:15
#     environment:
#       - POSTGRES_DB=langfuse
#       - POSTGRES_PASSWORD=password

# After docker-compose up, point your SDK to:
langfuse = Langfuse(
    public_key='pk-lf-your-key',
    secret_key='sk-lf-your-key',
    host='http://localhost:3000'  # your self-hosted instance
)

Langfuse vs LangSmith: quando escolher cada um

Escolha o LangSmith quando você usa muito o LangChain e quer rastreamento automático sem configuração, integração profunda com as avaliações do LangChain e está confortável com a dependência de um fornecedor. Escolha o Langfuse quando usa vários provedores de LLM, precisa hospedar a solução por conta própria para cumprir requisitos de privacidade de dados, quer transparência de código aberto ou desenvolve com estruturas diferentes do LangChain. Ambos estão prontos para produção e oferecem planos gratuitos generosos.

Integração do OpenTelemetry para LLMs

Para equipes que já usam o OpenTelemetry para rastreamento distribuído, o Langfuse oferece suporte à ingestão de OTLP (OpenTelemetry Protocol). Você pode enviar dados de rastreamento de LLM dos seus exportadores OTel existentes diretamente para o Langfuse, sem alterar sua instrumentação. Isso permite uma pilha de observabilidade unificada, na qual rastreamentos de LLM, intervalos de consultas ao banco de dados e rastreamentos de solicitações HTTP ficam no mesmo sistema, com identificadores de correlação consistentes.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Configure OTel to send to Langfuse OTLP endpoint
exporter = OTLPSpanExporter(
    endpoint='https://cloud.langfuse.com/api/public/otel/v1/traces',
    headers={
        'Authorization': 'Basic ' + base64.b64encode(b'pk-lf-xxx:sk-lf-xxx').decode()
    }
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

# Now create spans as usual - they appear in Langfuse automatically
tracer = trace.get_tracer('my-llm-app')
with tracer.start_as_current_span('rag-query') as span:
    span.set_attribute('llm.model', 'gpt-4o')
    span.set_attribute('llm.prompt_tokens', 500)
    result = rag_pipeline(query)

Verificação rápida

Teste sua compreensão sobre o Langfuse para observabilidade independente de modelo nesta lição.

Recapitulação da lição

Nesta lição, você aprendeu que o Langfuse oferece observabilidade de LLM de código aberto e independente de modelo, usando um modelo de dados hierárquico de rastreamentos, intervalos e gerações; o decorador @observe() instrumenta código existente com alterações mínimas; e o acompanhamento de custos, as pontuações de feedback dos usuários e a pontuação automatizada com LLM como avaliador tornam o Langfuse uma plataforma completa de monitoramento da qualidade. A seguir, configuraremos alertas para latência, custo e degradação da qualidade.

Perguntas Frequentes

A aula “Observabilidade independente de modelo com Langfuse” é grátis?

Sim — o texto completo de “Observabilidade independente de modelo com Langfuse” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Engineering Academy, atualize para CoddyKit PRO. O curso de AI Engineering Academy inclui 4 aulas no total.

O que vou aprender em “Observabilidade independente de modelo com Langfuse”?

Integre o Langfuse como uma alternativa de código aberto compatível com qualquer provedor de LLM, capture intervalos personalizados para recuperação e chamadas de ferramentas e configure painéis de a… Você pratica AI Engineering Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Engineering Academy?

Nenhuma experiência prévia é necessária. AI Engineering Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Observabilidade independente de modelo com Langfuse”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Engineering Academy?

Sim. Cada aula de AI Engineering Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Por que aplicações com LLM são difíceis de depurar
Rastreamento com LangSmith
Observabilidade independente de modelo com Langfuse
Alertas sobre latência, custo e degradação da qualidade

← Voltar para AI Engineering Academy