Langfuse em Spaces

Este guia mostra como implantar o Langfuse nos Hugging Face Spaces e começar a instrumentar seu aplicativo de LLM para observabilidade. Essa integração ajuda você a experimentar APIs de LLM no Hugging Face Hub, gerenciar seus prompts em um único local e avaliar as saídas dos modelos.

O que é Langfuse?

Langfuse é uma plataforma de engenharia de LLM de código aberto que ajuda equipes a depurar, avaliar e iterar colaborativamente em seus aplicativos de LLM.

Entre os principais recursos do Langfuse, destacam-se o rastreamento de LLM para capturar o contexto completo do fluxo de execução do seu aplicativo, o gerenciamento de prompts para iteração centralizada e colaborativa, métricas de avaliação para medir a qualidade da saída, a criação de conjuntos de dados para testes e benchmarking, e um playground para experimentar prompts e configurações de modelos.

Este vídeo é um tour de 10 minutos pelos recursos do Langfuse:

Por que Observabilidade de LLMs?

• À medida que os modelos de linguagem se tornam mais prevalentes, compreender seu comportamento e desempenho é importante.
• Observabilidade de LLMs envolve monitorar e compreender os estados internos de um aplicativo de LLM por meio de suas saídas.
• É essencial para lidar com desafios como:
  • Fluxos de controle complexos com chamadas repetidas ou encadeadas, o que torna o depurador desafiador.
  • Saídas não determinísticas, adicionando complexidade à avaliação consistente da qualidade.
  • Intenções de usuário variadas, que exigem uma compreensão profunda para melhorar a experiência do usuário.
• Construir aplicações de LLM envolve fluxos de trabalho complexos, e a observabilidade ajuda a gerenciar essas complexidades.

Etapa 1: Configure o Langfuse nos Spaces

O Espaço do Hugging Face do Langfuse permite que você comece a usar uma versão implantada do Langfuse com apenas alguns cliques.

Para começar, clique no botão acima ou siga estas etapas:

1. Crie um novo Hugging Face Space
2. Selecione Docker como o SDK do Space
3. Selecione Langfuse como o modelo de Space
4. Anexe um Storage Bucket para garantir que os dados do Langfuse sejam persistidos entre reinicializações
5. Certifique-se de que o espaço esteja configurado com visibilidade pública para que as APIs/SDKs do Langfuse possam acessar o aplicativo (veja a observação abaixo para mais detalhes)
6. [Opcional, mas recomendado] Para uma implantação segura, substitua os valores padrão das variáveis de ambiente:
   • NEXTAUTH_SECRET: Usado para validar cookies de sessão de login, gere um segredo com pelo menos 256 de entropia usando openssl rand -base64 32.
   • SALT: Usado para salgar as chaves de API hasheadas, gere um segredo com pelo menos 256 de entropia usando openssl rand -base64 32.
   • ENCRYPTION_KEY: Usado para criptografar dados sensíveis. Deve ter 256 bits, 64 caracteres em formato hexadecimal, gerado via: openssl rand -hex 32.
7. Clique em Criar Space!

Acesso do usuário

Seu espaço Langfuse vem pré-configurado com OAuth do Hugging Face para autenticação segura, portanto, será necessário autorizar o acesso de read à sua conta do Hugging Face no primeiro login, seguindo as instruções exibidas na janela pop-up.

Uma vez dentro do aplicativo, você pode usar os recursos nativos do Langfuse para gerenciar Organizações, Projetos e Usuários.

O espaço Langfuse deve ter visibilidade pública para que as APIs/SDKs do Langfuse possam acessar o aplicativo. Isso significa que, por padrão, qualquer usuário conectado do Hugging Face poderá acessar o espaço Langfuse.

Você pode impedir que novos usuários se inscrevam e acessem o espaço por meio de dois métodos diferentes:

1. (Recomendado) Restrições de OAuth nativas do Hugging Face em nível de organização

Se você deseja restringir o acesso apenas a membros de uma ou mais organizações específicas, basta definir o campo de metadados hf_oauth_authorized_org no arquivo README.md do espaço, conforme mostrado aqui.

Uma vez configurado, apenas usuários que são membros da(s) organização(ões) especificada(s) poderão acessar o espaço.

2. Controle de acesso manual

Você também pode restringir o acesso por usuário definindo a variável de ambiente AUTH_DISABLE_SIGNUP como true. Certifique-se de que você já fez login e autenticou-se no espaço antes de definir essa variável, caso contrário, seu próprio perfil de usuário não será capaz de se autenticar.

Observação: Se você configurou a variável de ambiente AUTH_DISABLE_SIGNUP como true para restringir o acesso e deseja conceder acesso a um novo usuário no espaço, primeiro você precisa reconfigurá-la como false (aguarde a conclusão da reconstrução), adicionar o usuário e solicitá-lo para autenticar com OAuth, e então reconfigurá-la como true.

Etapa 2: Use o Langfuse

Agora que você tem o Langfuse em execução, pode começar a instrumentar seu aplicativo de LLM para capturar rastros e gerenciar seus prompts. Vamos ver como!

Monitore qualquer aplicativo

Langfuse é agnóstico em relação ao modelo e pode ser usado para rastrear qualquer aplicativo. Siga o guia de introdução na documentação do Langfuse para ver como você pode instrumentar seu código.

Langfuse mantém integrações nativas com muitos frameworks de LLM populares, incluindo Langchain, LlamaIndex e OpenAI, e oferece SDKs em Python e JS/TS para instrumentar seu código. O Langfuse também oferece vários endpoints de API para ingerir dados e foi integrado por outros projetos de código aberto, como Langflow, Dify e Haystack.

Exemplo 1: Rastrear chamadas a provedores de inferência

Como um exemplo simples, veja como rastrear chamadas de LLM para Inference Providers usando o SDK Python do Langfuse.

Certifique-se de configurar primeiro as variáveis de ambiente LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY e LANGFUSE_SECRET_KEY, e verifique se você autenticou-se com sua conta do Hugging Face.

from langfuse.openai import openai
from huggingface_hub import get_token

client = openai.OpenAI(
    base_url="https://huggingface.co/proxy/router.huggingface.co/hf-inference/models/meta-llama/Llama-3.3-70B-Instruct/v1",
    api_key=get_token(),
)

messages = [{"role": "user", "content": "What is observability for LLMs?"}]

response = client.chat.completions.create(
    model="meta-llama/Llama-3.3-70B-Instruct",
    messages=messages,
    max_tokens=100,
)

Exemplo 2: Monitorar uma aplicação Gradio

Criamos um espaço de modelo Gradio que mostra como criar um aplicativo de chat simples usando um modelo do Hugging Face e rastrear chamadas de modelo e feedback do usuário no Langfuse - sem sair do Hugging Face.

Para começar, duplicar este espaço de modelo do Gradio e siga as instruções no README.

Etapa 3: Visualizar Traces no Langfuse

Depois de instrumentar seu aplicativo e ingerir traces ou feedback de usuários no Langfuse, você pode visualizar seus traces no Langfuse.

Exemplo de trilha na interface do Langfuse

Recursos e Suporte Adicionais

• Documentação do Langfuse
• Repositório do Langfuse no GitHub
• Discord do Langfuse
• Espaço do modelo Langfuse

Para mais ajuda, abra um tópico de suporte em GitHub discussions ou abra uma issue.