Langfuse sur Spaces

Ce guide vous montre comment déployer Langfuse sur Hugging Face Spaces et commencer à instrumenter votre application LLM pour l’observabilité. Cette intégration vous aide à expérimenter avec les API LLM sur le Hugging Face Hub, à gérer vos prompts en un seul endroit et à évaluer les sorties des modèles.

Qu'est-ce que Langfuse ?

Langfuse est une plateforme open source d’ingénierie LLM qui aide les équipes à déboguer, évaluer et itérer sur leurs applications LLM de manière collaborative.

Les principales fonctionnalités de Langfuse incluent le traçage des LLM pour capturer le contexte complet du flux d’exécution de votre application, la gestion des prompts pour une itération centralisée et collaborative, des métriques d’évaluation pour mesurer la qualité des sorties, la création de jeux de données pour les tests et les benchmarks, ainsi qu’un espace de jeu pour expérimenter avec les prompts et les configurations de modèles.

Cette vidéo est un tour d’horizon de 10 minutes des fonctionnalités de Langfuse :

Pourquoi l'observabilité des LLM ?

• À mesure que les modèles de langage se généralisent, il est essentiel de comprendre leur comportement et leurs performances.
• L'observabilité des LLM consiste à surveiller et à comprendre les états internes d'une application LLM à travers ses sorties.
• Il est essentiel pour relever des défis tels que :
  • Flux de contrôle complexes avec des appels répétés ou enchaînés, ce qui rend le débogage difficile.
  • Sorties non déterministes, ajoutant de la complexité à l'évaluation cohérente de la qualité.
  • Intentions variées des utilisateurs, nécessitant une compréhension approfondie pour améliorer l'expérience utilisateur.
• La création d'applications LLM implique des flux de travail complexes, et l'observabilité aide à gérer ces complexités.

Étape 1 : Configurer Langfuse sur Spaces

L'Espace Hugging Face de Langfuse vous permet de démarrer rapidement avec une version déployée de Langfuse en quelques clics.

Pour commencer, cliquez sur le bouton ci-dessus ou suivez ces étapes :

1. Créer un nouveau Hugging Face Space
2. Sélectionnez Docker comme SDK de Space
3. Sélectionnez Langfuse comme modèle d’espace
4. Attachez un Storage Bucket pour vous assurer que vos données Langfuse sont persistées après les redémarrages
5. Assurez-vous que l’espace est configuré avec une visibilité public afin que les API/SDK de Langfuse puissent accéder à l’application (voir la note ci-dessous pour plus de détails)
6. [Optionnel mais recommandé] Pour un déploiement sécurisé, remplacez les valeurs par défaut des variables d'environnement:
   • NEXTAUTH_SECRET : Utilisé pour valider les cookies de session de connexion, générez un secret avec au moins 256 d'entropie à l'aide de openssl rand -base64 32.
   • SALT : Utilisé pour saler les clés API hachées, générez un secret avec au moins 256 d'entropie à l'aide de openssl rand -base64 32.
   • ENCRYPTION_KEY : utilisé pour chiffrer les données sensibles. Doit être de 256 bits, soit 64 caractères en format hexadécimal, à générer via : openssl rand -hex 32.
7. Cliquez sur Créer un Space !

Accès utilisateur

Votre espace Langfuse est préconfiguré avec l’authentification OAuth de Hugging Face pour une authentification sécurisée. Lors de la première connexion, vous devrez donc autoriser l’accès en read à votre compte Hugging Face en suivant les instructions affichées dans la fenêtre contextuelle.

Une fois dans l’application, vous pouvez utiliser les fonctionnalités natives de Langfuse pour gérer les Organisations, les Projets et les Utilisateurs.

L'espace Langfuse doit être configuré avec une visibilité publique afin que les API/SDK de Langfuse puissent accéder à l'application. Cela signifie que, par défaut, n'importe quel utilisateur connecté à Hugging Face pourra accéder à l'espace Langfuse.

Vous pouvez empêcher les nouveaux utilisateurs de s'inscrire et d'accéder à l'espace via deux méthodes différentes :

1. (Recommandé) Restrictions OAuth natives au niveau de l'organisation Hugging Face

Si vous souhaitez restreindre l’accès aux membres uniquement d’une ou plusieurs organisations spécifiées, il vous suffit de définir le champ de métadonnées hf_oauth_authorized_org dans le fichier README.md de l’espace, comme indiqué ici.

Une fois configuré, seuls les membres de l'organisation ou des organisations spécifiées pourront accéder à l'espace.

2. Contrôle d'accès manuel

Vous pouvez également restreindre l’accès sur une base utilisateur par utilisateur en définissant la variable d’environnement AUTH_DISABLE_SIGNUP sur true. Assurez-vous d’avoir d’abord effectué votre connexion et votre authentification à l’espace avant de définir cette variable, sinon votre propre profil utilisateur ne pourra pas s’authentifier.

Remarque : Si vous avez défini la variable d’environnement AUTH_DISABLE_SIGNUP sur true pour restreindre l’accès et souhaitez accorder l’accès à l’espace à un nouvel utilisateur, vous devez d’abord la remettre à false (attendre la fin de la reconstruction), ajouter l’utilisateur et lui faire s’authentifier via OAuth, puis la remettre à true.

Étape 2 : Utiliser Langfuse

Maintenant que vous avez Langfuse en cours d’exécution, vous pouvez commencer à instrumenter votre application LLM afin de capturer les traces et de gérer vos prompts. Voyons comment !

Surveiller toute application

Langfuse est indépendant du modèle et peut être utilisé pour tracer n'importe quelle application. Suivez le guide de démarrage dans la documentation Langfuse pour voir comment instrumenter votre code.

Langfuse maintient des intégrations natives avec de nombreux frameworks LLM populaires, notamment Langchain, LlamaIndex et OpenAI, et propose des SDK Python et JS/TS pour instrumenter votre code. Langfuse propose également divers points d’entrée API pour ingérer des données et a été intégré par d’autres projets open source tels que Langflow, Dify et Haystack.

Exemple 1 : Suivi des appels aux fournisseurs d’inférence

En guise d’exemple simple, voici comment tracer les appels LLM vers Inference Providers à l’aide du SDK Python Langfuse.

Assurez-vous d'abord de configurer vos variables d'environnement LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY et LANGFUSE_SECRET_KEY, et de vous être authentifié avec votre compte 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,
)

Exemple 2 : Surveiller une application Gradio

Nous avons créé un espace de modèle Gradio qui montre comment créer une application de chat simple à l'aide d'un modèle Hugging Face et tracer les appels au modèle et les retours des utilisateurs dans Langfuse - sans quitter Hugging Face.

Pour commencer, dupliquez cet espace de modèle Gradio et suivez les instructions du README.

Étape 3 : Afficher les traces dans Langfuse

Une fois votre application instrumentée et les traces ou retours utilisateurs ingérés dans Langfuse, vous pouvez consulter vos traces dans Langfuse.

Exemple de trace dans l’interface Langfuse

Ressources et assistance supplémentaires

• Documentation Langfuse
• Dépôt GitHub de Langfuse
• Discord Langfuse
• Espace de modèle Langfuse

Pour obtenir plus d'aide, ouvrez un fil de support sur GitHub discussions ou ouvrez un problème.