Primeiros passos com Langfuse (Guia 2026)

A criação e implantação de aplicativos que utilizam Giant Language Fashions (LLMs) apresentam seu próprio conjunto de problemas. Os LLMs têm natureza não determinística, podem gerar informações plausíveis, mas falsas, e rastrear suas ações em sequências complicadas pode ser muito problemático. Neste guia, veremos como o Langfuse surge como um instrumento essencial para resolver esses problemas, oferecendo uma base sólida para toda a observabilidade, avaliação e manuseio imediato de aplicações LLM.

O que é Langfuse?

Langfuse é uma plataforma inovadora de observabilidade e avaliação de código aberto e criada especificamente para aplicações LLM. É a base para rastrear, visualizar e depurar todos os estágios de uma interação LLM, começando com o immediate inicial e terminando com a resposta closing, seja uma simples chamada ou uma conversa complicada entre agentes.

Langfuse não é apenas uma ferramenta de registro, mas também um meio de avaliar sistematicamente o desempenho do LLM, testes A/B de prompts e coleta de suggestions do usuário, o que, por sua vez, ajuda a fechar o ciclo de suggestions essencial para a melhoria iterativa. O principal ponto de seu valor é a transparência que traz ao mundo dos LLMs, permitindo assim aos desenvolvedores:

• Entenda o comportamento do LLM: Descubra os prompts exatos que foram enviados, as respostas recebidas e as etapas intermediárias em um aplicativo de vários estágios.
• Encontre problemas: Localize rapidamente a origem dos erros, do baixo desempenho ou dos resultados inesperados.
• Avaliação de qualidade: A eficácia das respostas LLM pode ser medida em relação às métricas predefinidas com medidas manuais e automatizadas.
• Refinar e melhorar: Insights baseados em dados podem ser usados ​​para aperfeiçoar prompts, modelos e lógica de aplicação.
• Lidar com solicitações: controle a versão dos prompts e teste-os para obter o melhor LLM.

Principais recursos e conceitos

Existem vários recursos principais que Langfuse oferece, como:

1. Rastreamento e monitoramento

Langfuse nos ajuda a capturar os traços detalhados de cada interação que o LLM possui. O ‘rastreamento’ é basicamente a representação de uma solicitação de usuário ou fluxo de aplicativo ponta a ponta. Dentro de um rastreamento, as unidades lógicas de trabalho são indicadas por “períodos” e as chamadas para um LLM referem-se a “gerações”.

2. Avaliação

Langfuse permite avaliação tanto handbook quanto programaticamente. Métricas personalizadas podem ser definidas pelos desenvolvedores, que podem então ser usadas para executar avaliações para diferentes conjuntos de dados e, em seguida, ser integradas como avaliadores baseados em LLM.

3. Gerenciamento de immediate

Langfuse fornece controle direto sobre o gerenciamento imediato, juntamente com recursos de armazenamento e controle de versão. É possível testar vários prompts por meio de testes A/B e, ao mesmo tempo, manter a precisão em diversos locais, o que também abre caminho para a otimização de prompts baseada em dados.

4. Coleta de comentários

Langfuse absorve as sugestões do usuário e as incorpora diretamente em seus rastros. Você será capaz de vincular comentários específicos ou avaliações de usuários à interação precisa do LLM que resultou em um resultado, fornecendo-nos assim suggestions em tempo actual para solução de problemas e melhorias.

Por que Langfuse? O problema que ele resolve

As ferramentas tradicionais de observabilidade de software program têm características muito diferentes e não atendem aos critérios de aplicativos baseados em LLM nos seguintes aspectos:

• Não determinismo: Os LLMs nem sempre produzirão o mesmo resultado, mesmo para uma entrada idêntica, o que torna a depuração bastante desafiadora. O Langfuse, por sua vez, registra a entrada e a saída de cada interação, dando uma imagem clara da operação naquele momento.
• Sensibilidade imediata: Qualquer pequena alteração em um immediate pode alterar completamente a resposta do LLM. Langfuse está lá para ajudar a acompanhar as versões do immediate junto com suas métricas de desempenho.
• Cadeias Complexas: A maioria das aplicações LLM são caracterizadas por uma combinação de múltiplas chamadas LLM, diferentes ferramentas e recuperação de dados (por exemplo, pano arquiteturas). A única forma de conhecer o fluxo e identificar o native onde está o gargalo ou o erro é traçando. Langfuse apresenta uma linha do tempo visible para essas interações.
• Qualidade Subjetiva: O termo “bondade” para a resposta de um LLM é muitas vezes sinônimo de opinião pessoal. Langfuse permite avaliações de qualidade objetivas (por exemplo, latência, contagem de tokens) e subjetivas (suggestions humano, avaliação baseada em LLM).
• Gestão de Custos: Chamar APIs LLM tem um preço. Compreender e otimizar seus custos será mais fácil se você tiver o Langfuse monitorando o uso de tokens e o quantity de chamadas.
• Falta de visibilidade: O desenvolvedor não consegue ver o desempenho de seus aplicativos LLM no mercado e, portanto, é difícil para eles torná-los gradualmente melhores devido à falta de observabilidade.

Langfuse não oferece apenas um método sistemático para LLM interação, mas também transforma o processo de desenvolvimento em uma disciplina de engenharia interativa e baseada em dados, em vez de tentativa e erro.

Primeiros passos com Langfuse

Antes de começar a usar o Langfuse, você deve primeiro instalar a biblioteca cliente e configurá-la para transmitir dados para uma instância do Langfuse, que pode ser hospedada na nuvem ou auto-hospedada.

Instalação

Langfuse possui bibliotecas clientes disponíveis para Python e JavaScript/TypeScript.

Cliente Python

pip set up langfuse 

Cliente JavaScript/TypeScript

npm set up langfuse 

Ou

yarn add langfuse 

Configuração

Após a instalação, lembre-se de configurar o cliente com as chaves e o host do projeto. Você pode encontrá-los nas configurações do projeto Langfuse.

• chave_pública: Isto é para aplicativos frontend ou para casos em que apenas dados limitados e não confidenciais estão sendo enviados.
• chave_secreta: isso é para aplicativos de back-end e cenários onde a observabilidade complete, incluindo entradas/saídas confidenciais, é um requisito.
• hospedar: refere-se ao URL da sua instância Langfuse (por exemplo, https://cloud.langfuse.com).
• ambiente: Esta é uma string opcional que pode ser usada para distinguir entre diferentes ambientes (por exemplo, produção, teste, desenvolvimento).

Por razões de segurança e flexibilidade, considera-se uma boa prática defini-las como variáveis ​​de ambiente.

export LANGFUSE_PUBLIC_KEY="pk-lf-..." 
export LANGFUSE_SECRET_KEY="sk-lf-..." 
export LANGFUSE_HOST="https://cloud.langfuse.com" 
export LANGFUSE_ENVIRONMENT="improvement"

Em seguida, inicialize o cliente Langfuse em sua aplicação:

Exemplo de Python

from langfuse import Langfuse
import os

langfuse = Langfuse(public_key=os.environ.get("LANGFUSE_PUBLIC_KEY"),    secret_key=os.environ.get("LANGFUSE_SECRET_KEY"),    host=os.environ.get("LANGFUSE_HOST"))

Exemplo de JavaScript/TypeScript

import { Langfuse } from "langfuse";

const langfuse = new Langfuse({  publicKey: course of.env.LANGFUSE_PUBLIC_KEY,  secretKey: course of.env.LANGFUSE_SECRET_KEY,  host: course of.env.LANGFUSE_HOST});

Configurando seu primeiro rastreamento

A unidade basic de observabilidade em Langfuse é o traço. Um rastreamento normalmente representa uma única interação do usuário ou um ciclo de vida completo da solicitação. Dentro de um rastreamento, você registra chamadas LLM individuais (geração) e etapas computacionais arbitrárias (intervalo).

Vamos ilustrar com uma chamada LLM simples usando API da OpenAI.

Exemplo de Python

import os
from openai import OpenAI
from langfuse import Langfuse
from langfuse.mannequin import InitialGeneration

# Initialize Langfuse
langfuse = Langfuse(
    public_key=os.environ.get("LANGFUSE_PUBLIC_KEY"),
    secret_key=os.environ.get("LANGFUSE_SECRET_KEY"),
    host=os.environ.get("LANGFUSE_HOST"),
)

# Initialize OpenAI consumer
consumer = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

def simple_llm_call_with_trace(user_input: str):
    # Begin a brand new hint
    hint = langfuse.hint(
        identify="simple-query",
        enter=user_input,
        metadata={"user_id": "user-123", "session_id": "sess-abc"},
    )

    attempt:
        # Create a technology throughout the hint
        technology = hint.technology(
            identify="openai-generation",
            enter=user_input,
            mannequin="gpt-4o-mini",
            model_parameters={"temperature": 0.7, "max_tokens": 100},
            metadata={"prompt_type": "customary"},
        )

        # Make the precise LLM name
        chat_completion = consumer.chat.completions.create(
            mannequin="gpt-4o-mini",
            messages=({"position": "person", "content material": user_input}),
            temperature=0.7,
            max_tokens=100,
        )

        response_content = chat_completion.decisions(0).message.content material

        # Replace technology with the output and utilization
        technology.replace(
            output=response_content,
            completion_start_time=chat_completion.created,
            utilization={
                "prompt_tokens": chat_completion.utilization.prompt_tokens,
                "completion_tokens": chat_completion.utilization.completion_tokens,
                "total_tokens": chat_completion.utilization.total_tokens,
            },
        )

        print(f"LLM Response: {response_content}")
        return response_content

    besides Exception as e:
        # Report errors within the hint
        hint.replace(
            stage="ERROR",
            status_message=str(e)
        )
        print(f"An error occurred: {e}")
        increase

    lastly:
        # Guarantee all knowledge is distributed to Langfuse earlier than exit
        langfuse.flush()


# Instance name
simple_llm_call_with_trace("What's the capital of France?")

Eventualmente, sua próxima etapa após executar este código seria ir para a interface Langfuse. Haverá um novo rastreamento “consulta simples” que consiste em uma geração “geração openai”. É possível clicar nele para visualizar a entrada, saída, modelo usado e outros metadados.

Funcionalidade principal em detalhes

Aprender a trabalhar com objetos de rastreamento, extensão e geração é o principal requisito para aproveitar as vantagens do Langfuse.

Rastreamento de chamadas LLM

• langfuse.hint(): Este comando inicia um novo rastreamento. O contêiner de nível superior para toda uma operação.
  • nome: o nome muito descritivo do rastreamento.
  • entrada: A primeira entrada de todo o procedimento.
  • metadados: um dicionário de quaisquer pares de valores-chave para filtragem e análise (por exemplo, user_id, session_id, AB_test_variant).
  • ID_da_sessão: (Opcional) um identificador compartilhado por todos os rastreamentos provenientes da mesma sessão de usuário.
  • ID do usuário: (Opcional) um identificador compartilhado por todas as interações de um usuário específico.

• hint.span(): esta é uma etapa lógica ou operação secundária dentro de um rastreamento que não é uma interação direta de entrada-saída com o LLM. Chamadas de ferramentas, pesquisas em bancos de dados ou cálculos complexos podem ser rastreados dessa maneira.
  • nome: Nome do span (por exemplo, “retrieve-docs”, “parse-json”).
  • entrada: a entrada relevante para este intervalo.
  • saída: a saída criada por este intervalo.
  • metadados: os metadados de span são formatados como adicionais.
  • nível: O nível de gravidade (INFO, WARNING, ERROR, DEBUG).
  • mensagem_status: uma mensagem vinculada ao standing (por exemplo, detalhes do erro).
  • parent_observation_id: conecta esse intervalo a um intervalo pai ou rastreamento para estruturas aninhadas.

• hint.technology(): significa uma invocação específica do LLM.
  • nome: O nome da geração (por exemplo, “resposta inicial”, “etapa de refinamento”).
  • entrada: o immediate ou as mensagens que foram comunicadas ao LLM.
  • saída: A resposta recebida do LLM.
  • modelo: O modelo LLM preciso que foi empregado (por exemplo, “gpt-4o-mini“,“claude-3-opus“).
  • parâmetros_modelo: Um dicionário de parâmetros específicos do modelo (como temperature, max_tokens, top_p).
  • uso: Um dicionário exibindo o número de tokens utilizados (prompt_tokens, completion_tokens, total_tokens).
  • metadados: metadados adicionais para a invocação do LLM.
  • parent_observation_id: vincula esta geração a um intervalo ou rastreamento pai.
  • incitar: (Opcional) Pode identificar um modelo de immediate específico que está sob gerenciamento no Langfuse.

Conclusão

Langfuse torna o desenvolvimento e a manutenção de aplicativos baseados em LLM uma tarefa menos árdua, transformando-os em um processo estruturado e orientado por dados. Ele faz isso dando aos desenvolvedores acesso às interações com o LLM como nunca antes, por meio de rastreamento extensivo, avaliação sistemática e gerenciamento imediato e poderoso.

Além disso, incentiva os desenvolvedores a depurar seu trabalho com certeza, acelerar o processo de iteração e continuar melhorando seus produtos de IA em termos de qualidade e desempenho. Conseqüentemente, Langfuse fornece os instrumentos necessários para garantir que os aplicativos LLM sejam confiáveis, econômicos e realmente poderosos, não importa se você está desenvolvendo um chatbot básico ou um agente autônomo sofisticado.

Perguntas frequentes

Estagiário de Ciência de Dados na Analytics Vidhya
Atualmente estou trabalhando como Trainee de Ciência de Dados na Analytics Vidhya, onde me concentro na construção de soluções baseadas em dados e na aplicação de técnicas de IA/ML para resolver problemas de negócios do mundo actual. Meu trabalho me permite explorar análises avançadas, aprendizado de máquina e aplicações de IA que capacitam as organizações a tomar decisões mais inteligentes e baseadas em evidências.
Com uma base sólida em ciência da computação, desenvolvimento de software program e análise de dados, sou apaixonado por aproveitar a IA para criar soluções impactantes e escaláveis ​​que preencham a lacuna entre tecnologia e negócios.
📩 Você também pode entrar em contato comigo em (e-mail protegido)