Langfuse : observer ses LLM locaux (traces, prompts, évals)

#Pourquoi observer un LLM local

Langfuse est une plateforme d'observabilité pour applications LLM, sous licence MIT pour son dépôt principal, que l'on peut auto-héberger pour que les traces de vos conversations restent chez vous. Elle enregistre, pour chaque requête, le prompt réellement envoyé au modèle, la réponse, la durée de chaque étape et, si un prix est défini, le coût. Elle sert à savoir pourquoi une réponse est mauvaise : passage récupéré hors sujet, prompt différent de celui que vous croyiez, ou échec du modèle. Elle devient utile dès qu'une deuxième personne dépend du résultat ou que la chaîne compte plusieurs étapes ; pour un usage exploratoire seul, un fichier de journal suffit. Comptez une pile de plusieurs conteneurs (serveur web, worker, PostgreSQL, ClickHouse, Redis, stockage objet) et, pour la production, Kubernetes plutôt que Docker Compose.

Quand une réponse déçoit, trois causes sont possibles et une seule est visible sans instrumentation : le prompt final envoyé au modèle n'était pas celui que vous croyiez, les passages récupérés par la recherche documentaire étaient hors sujet, ou le modèle lui-même a échoué. Sans enregistrement, on change le prompt au hasard jusqu'à ce que ça aille mieux, sans jamais savoir pourquoi.

L'argument est le même en local qu'en ligne, à une différence près : la facture n'est plus l'indicateur qui vous alerte. Personne ne reçoit de relevé quand une chaîne d'agents part en boucle sur votre propre carte graphique ; c'est la latence et la chaleur qui le disent. L'observabilité remplace ce signal de prix par des mesures : nombre de tokens, durée, taux d'échec, qualité.

#Ce que Langfuse enregistre

Le projet se présente lui-même comme une plateforme d'évaluation d'agents et d'observabilité open source : tracer, évaluer et améliorer des applications LLM sur une seule plateforme ouverte. Ses SDK Python (version 4) et JS/TS (version 5) reposent sur OpenTelemetry, et d'autres langages peuvent envoyer leurs traces par ce protocole. Le dépôt principal dépasse les 35 000 étoiles sur GitHub. Son README indique que Langfuse fait partie de ClickHouse depuis janvier 2026, et ClickHouse est aussi la base qui stocke les traces.

Traces

Le déroulé complet d'une requête utilisateur : chaque étape, dans l'ordre, avec sa durée. C'est l'unité de base.

Observations

À l'intérieur d'une trace : les appels au modèle avec leur prompt exact et leur réponse, les étapes de récupération documentaire, les appels d'outils.

Sessions et utilisateurs

Le regroupement des traces par conversation et par personne, pour suivre un parcours plutôt qu'un appel isolé.

Scores

Une note attachée à une trace : pouce levé d'un utilisateur, résultat d'une évaluation automatique, annotation manuelle.

Prompts

Les gabarits de prompt, versionnés, récupérés par l'application à l'exécution plutôt qu'écrits en dur dans le code.

Coûts

Langfuse calcule un coût à partir d'une définition de modèle qui associe un prix à chaque type d'usage. Il en fournit pour des modèles OpenAI, Anthropic et Google. Pour un modèle local, aucun prix n'existe tant que vous n'en ajoutez pas : sans définition, ne cherchez pas de coût dans l'interface, ou définissez un prix fictif pour refléter l'électricité et l'amortissement.

#L'installer chez soi

Langfuse s'auto-héberge avec Docker Compose. Le README annonce un démarrage en cinq minutes ; la documentation de déploiement compte deux à trois minutes avant que le conteneur web affiche « Ready ». La pile ne se limite pas à un conteneur : deux conteneurs applicatifs (le serveur web, qui sert l'interface et l'API, et un worker qui traite les événements en asynchrone) et quatre composants de stockage, PostgreSQL pour les données transactionnelles, ClickHouse pour les traces, observations et scores, Redis ou Valkey pour la file et le cache, et un stockage objet compatible S3 qui conserve tous les événements entrants. C'est plus lourd qu'un simple tableau de bord, et c'est la conséquence de ce qu'on lui demande : ingérer beaucoup d'événements sans perdre une trace, même si la base est momentanément indisponible.

Deux limites à connaître avant de l'installer à côté d'un modèle. D'abord, la documentation dit que Docker Compose sert à essayer : cette configuration n'offre ni haute disponibilité, ni montée en charge, ni sauvegarde, et pour la production elle recommande Kubernetes avec Helm. Ensuite, pour une machine virtuelle, elle conseille au moins 4 cœurs, 16 Gio de mémoire et 100 Gio de stockage. Sur un poste qui sert déjà un modèle, ces ordres de grandeur comptent : une pile d'observabilité qui prend une part de la mémoire du modèle le fait au pire moment. Changez enfin les secrets du fichier docker-compose.yml, marqués CHANGEME : il n'existe pas de compte par défaut, le premier utilisateur se crée par le bouton Sign up sur http://localhost:3000.

git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
# Éditer docker-compose.yml : remplacer chaque secret marqué CHANGEME
docker compose up
# Après 2 à 3 minutes, le conteneur web affiche « Ready » : ouvrir http://localhost:3000

#Le brancher à Ollama ou vLLM

Langfuse n'est pas un serveur d'inférence et ne s'intercale pas dans le trafic : c'est votre application qui lui envoie les traces. Le projet documente trois chemins concrets selon la façon dont vous appelez votre modèle, et une page dédiée à Ollama, dont l'exemple utilise le SDK OpenAI : Ollama expose une API compatible OpenAI à l'adresse http://localhost:11434/v1, et Langfuse fournit un remplacement direct de ce SDK, qui ne demande que de changer l'import. Une page existe aussi pour vLLM.

1. 01
   Par le SDK, dans votre code

   Vous décorez les fonctions qui appellent le modèle. C'est le plus explicite et le plus fidèle, puisque vous choisissez ce qui est tracé.
2. 02
   Par une intégration de framework

   Une instrumentation automatisée existe pour un remplacement direct du SDK OpenAI, pour un gestionnaire de rappel branché sur une application LangChain, et pour le système de rappel de LlamaIndex : les traces remontent sans modifier la logique métier.
3. 03
   Par une passerelle d'API

   Si vos appels passent déjà par un routeur compatible OpenAI, l'instrumentation se fait à ce niveau et couvre toutes les applications d'un coup.

Dans les trois cas, le point à vérifier est que le prompt réellement transmis soit enregistré, et pas seulement la question de l'utilisateur : c'est précisément l'écart entre les deux qui explique la plupart des mauvaises réponses d'un système de recherche documentaire. Avec Ollama, le montage ci-dessous pointe LANGFUSE_BASE_URL vers votre instance auto-hébergée (http://localhost:3000) et déclare vos clés publique et secrète en variables d'environnement.

# pip install langfuse openai
# Variables d'environnement : LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY,
# LANGFUSE_BASE_URL=http://localhost:3000
from langfuse.openai import OpenAI  # remplace : from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1',
    api_key='ollama',  # requis mais inutilisé
)
reponse = client.chat.completions.create(
    model='llama3.1',
    messages=[{'role': 'user', 'content': 'Bonjour !'}],
)

• Centraliser ses appels avec une passerelle compatible OpenAI
• Déployer vLLM pour servir plusieurs utilisateurs
• Appeler Ollama depuis Python
• Ragas : évaluer un RAG local avec des chiffres
• Source : détail des intégrations SDK, framework et passerelle

#Gérer et versionner les prompts

Sortir les prompts du code est le bénéfice que les équipes constatent en premier. Selon le README, un solide cache côté serveur et côté client permet d'itérer sur les prompts sans ajouter de latence à l'application. Le gabarit vit dans Langfuse, l'application le récupère à l'exécution, et chaque modification crée une version. Corriger une formulation ne demande plus de redéployer, et surtout la trace indique quelle version a produit quelle réponse : quand la qualité chute après un changement, on sait lequel accuser sans avoir à recouper des journaux de déploiement séparés.

#Jeux de test et évaluation

Les traces réelles alimentent des jeux de test : vous marquez les cas intéressants — les échecs surtout — et ils deviennent une collection contre laquelle rejouer une nouvelle version de prompt ou un autre modèle. C'est ce qui permet de répondre sérieusement à « est-ce que le modèle de 14 milliards de paramètres suffit ? » au lieu d'en discuter.

Les scores viennent de plusieurs sources : les utilisateurs, une annotation humaine dans l'interface, des évaluateurs par code, ou un modèle qui juge la réponse d'un autre selon une grille — la méthode dite LLM-as-a-judge, que Langfuse propose nativement. Pour ce dernier cas, il faut créer une connexion LLM. La documentation indique que tout modèle qui suit le schéma de l'API OpenAI convient, en remplaçant l'URL de base : un modèle local servi par Ollama peut donc jouer le juge, à condition que son adresse soit joignable depuis le conteneur Langfuse. La méthode est utile et biaisée : les auteurs de l'article de référence sur le sujet (arXiv 2306.05685) décrivent des biais de position, de verbosité et d'auto-préférence, tout en mesurant plus de 80 % d'accord entre un juge de type GPT-4 et des préférences humaines. Elle sert à comparer deux versions, pas à décerner une note absolue.

Un outil dédié à l'évaluation du RAG, comme Ragas, complète Langfuse plutôt qu'il ne le remplace : Langfuse capture la trace et stocke le score, Ragas calcule des métriques spécifiques — fidélité au contexte, pertinence de la réponse — que Langfuse peut ensuite afficher comme n'importe quel autre score attaché à une trace.

#Cas d'usage concrets

Assistant de support avec RAG

Une réponse hors sujet se retrace dans la trace : le passage récupéré était-il pertinent, ou le modèle a-t-il ignoré un passage correct ? Elle tranche entre les deux hypothèses.

Agent qui appelle des outils

Sur une chaîne à plusieurs étapes — recherche, calcul, rédaction —, la trace montre laquelle a échoué au lieu de faire deviner un échec global sans détail.

Comparaison de deux modèles avant de trancher

Rejouer le même jeu de test avec un modèle de 8 milliards puis de 27 milliards de paramètres donne un chiffre de qualité et une durée, plutôt qu'une impression.

Suivi d'une régression après mise à jour

Un changement de version de prompt ou de modèle qui dégrade la qualité se voit dans les scores agrégés avant qu'un utilisateur ne s'en plaigne.

Le point commun à ces cas : aucun ne se résout en relisant du code. La cause d'une mauvaise réponse se trouve dans les données qui ont transité — le prompt exact, les passages récupérés, la réponse produite — et ces données n'existent nulle part ailleurs si elles n'ont pas été enregistrées au moment de l'appel. C'est tout l'argument en faveur d'installer l'observabilité avant la mise en service plutôt qu'après le premier incident.

#Ce que ça coûte et ce que ça ne fait pas

Ça ne rend pas un modèle meilleur

L'observabilité mesure, elle ne corrige rien. Elle vous dit où chercher.

Ça stocke vos conversations

Même auto-hébergé, le contenu des prompts est écrit sur disque, et sans politique de rétention (fonction de l'édition entreprise), les données sont conservées indéfiniment. Les SDK offrent en revanche des fonctions de masquage (masking) pour retirer les données sensibles avant l'envoi des traces.

C'est une pile à maintenir

Sauvegardes, mises à jour, migrations : la documentation dit elle-même que Docker Compose n'offre pas de sauvegarde. Pour une expérimentation personnelle, c'est disproportionné.

Ça arrive tard, souvent

Le bon moment pour l'installer est avant la mise en service, pas après la première panne silencieuse.

• Source : dépôt officiel Langfuse sur GitHub
• Source : dépôt officiel Ragas, pour l'évaluation de RAG

#FAQ