TruLens est une bibliothèque Python pour tracer et évaluer des applications construites sur des modèles de langage, avec un accent particulier sur les systèmes qui répondent à des questions à partir de documents. Sa contribution la plus connue est la triade RAG : trois mesures qui couvrent ensemble pratiquement toutes les façons dont une telle application peut échouer.
La version de fin juillet 2026 porte le numéro 2.10, la licence est MIT, et le Python requis commence à 3.10. Cette distinction mérite d'être notée, car plusieurs outils concurrents de cette catégorie sont publiés sous des licences qui restreignent la redistribution commerciale, et ici ce problème n'existe pas.
Qui est derrière
La bibliothèque est issue de Truera, une entreprise que Snowflake a rachetée en mai 2024. Le développement continue, et l'intégration avec l'écosystème de ce fournisseur se voit dans la documentation et les exemples.
Pour un utilisateur, cela a une conséquence pratique : beaucoup de contenus montrent TruLens avec des services Snowflake, ce qui peut égarer. La bibliothèque elle-même est indépendante, s'installe avec un gestionnaire de paquets ordinaire, tourne en local et n'exige de compte chez personne. Le modèle juge peut être n'importe quel fournisseur ou un modèle exécuté sur ton propre matériel.
La triade RAG, l'idée centrale de cet outil
C'est l'idée pour laquelle il vaut la peine d'apprendre la bibliothèque, même si tu finis par en utiliser une autre.
Une application qui répond à des questions à partir de documents comporte trois liens : la question vers les morceaux récupérés, les morceaux récupérés vers la réponse, et la question vers la réponse. Chacun peut casser séparément, et chacun casse différemment.
La pertinence du contexte (context relevance) mesure le premier : si les morceaux récupérés concernent seulement la question. Un score bas signifie que le problème se trouve dans la recherche, et aucun changement de prompt ne le réparera.
L'ancrage (groundedness) mesure le deuxième : si chaque affirmation de la réponse peut être rattachée aux morceaux récupérés. Un score bas avec un bon contexte signifie que le modèle ajoute des choses que les documents ne contenaient jamais.
La pertinence de la réponse (answer relevance) mesure le troisième : si la réponse traite la question posée. Un score bas avec les deux autres bons signifie que le modèle a répondu à autre chose, généralement à un fragment de la question ou à un sujet voisin.
La force de ce dispositif est qu'une combinaison de trois scores pointe une cause plutôt qu'un symptôme. Un rapport qui dit « le système a donné de fausses informations » mène à des devinettes sans ces mesures. Avec elles, tu sais s'il faut chercher dans l'index, dans le prompt ou dans le modèle.
Installation et première exécution
pip install trulens trulens-providers-openaifrom trulens.core import TruSession, Feedback
from trulens.providers.openai import OpenAI
import numpy as np
session = TruSession()
provider = OpenAI(model_engine="gpt-4o-mini")
context_relevance = (
Feedback(provider.context_relevance_with_cot_reasons, name="context relevance")
.on_input()
.on(context)
.aggregate(np.mean)
)
groundedness = (
Feedback(provider.groundedness_measure_with_cot_reasons, name="groundedness")
.on(context.collect())
.on_output()
)La façon de déclarer les choses ici diffère de la plupart des outils et demande un instant d'adaptation. Au lieu d'écrire une fonction de scoring, tu en composes une : tu choisis une mesure toute prête, tu indiques sur quoi elle s'exécute et tu définis comment agréger les résultats quand il y a plusieurs morceaux.
Cette dernière partie égare les gens. La pertinence du contexte est calculée séparément pour chaque morceau récupéré, donc cinq morceaux donnent cinq scores. La moyenne dit si la recherche fonctionne en général ; le maximum dit si au moins un morceau pertinent est apparu. Ce sont deux questions différentes et il est utile de savoir à laquelle tu réponds.
Les variantes avec raisonnement et leur utilité
Les mesures existent sous deux formes : l'une renvoie seulement un nombre, l'autre renvoie un nombre avec une explication.
La variante avec raisonnement coûte plus de tokens et s'exécute plus lentement, et elle vaut généralement quand même la peine d'être utilisée pendant le développement. La raison est simple : un score de 0,4 sans explication ne dit rien. Un score de 0,4 avec une justification qui indique que deux morceaux sur cinq concernaient un autre produit pointe directement ce qu'il faut corriger.
Sans justifications, tu tombes dans le piège classique du travail avec des évaluateurs : une courbe qui chute et tu ne peux pas dire si l'application s'est dégradée ou si quelque chose a changé dans le fonctionnement du scoring. Une justification règle cela en une minute.
Pour des exécutions sur un grand échantillon, inverse : la variante sans raisonnement sur tout l'ensemble pour établir une tendance, la variante avec raisonnement sur quelques dizaines de pires cas pour comprendre la cause.
Le modèle juge et sa fiabilité
Toutes ces mesures fonctionnent de la même façon : un prompt à un modèle qui émet un score. Donc il faut poser la question qui convient à tout outil de ce genre.
La réponse est : vérifie sur tes propres données. Prends une centaine de cas, étiquette-les à la main, compare avec la mesure et calcule la concordance. Sans ce chiffre, une courbe de qualité montre quelque chose que tu ne connais pas, et les décisions prises à partir d'elle sont arbitraires.
Le choix du modèle juge compte plus ici qu'on ne le suppose. Un modèle moins cher et plus rapide suffit pour l'ancrage, car cette tâche se ramène à comparer des affirmations avec un texte. La pertinence de la réponse est plus difficile, et un modèle plus faible se trompe plus souvent là, en particulier sur des questions en plusieurs parties.
La troisième chose est la langue. Les mesures sont décrites par des prompts en anglais et peuvent donner de moins bons résultats sur du texte dans d'autres langues, surtout pour l'ancrage, où la correspondance exacte entre une affirmation et une phrase source compte. Les prompts peuvent être changés, et sur des documents non anglophones cela vaut généralement la peine.
Au-delà de la triade, le reste de l'ensemble de mesures
Les trois mesures principales couvrent les échecs les plus courants, tandis que la bibliothèque en contient bien d'autres, et certaines traitent des problèmes dont les équipes se souviennent trop tard.
La détection de contenu nuisible et le scoring du sentiment aident là où les réponses vont directement à un client. Ce n'est pas une protection au sens d'un filtre en temps réel, seulement une mesure qui te dit à quelle fréquence une telle sortie apparaît.
Le respect d'un style ou d'un périmètre de sujets indiqué est souvent la mesure la plus sous-estimée dans les assistants d'entreprise. Une réponse factuellement correcte et écrite sur le mauvais ton est un vrai problème, et la triade ne l'attrapera pas, car sur les faits tout est en ordre.
Les mesures sans rapport avec le modèle méritent d'être calculées séparément. Le temps de réponse, le nombre de morceaux récupérés, la longueur de la réponse et le coût en tokens n'ont besoin d'aucun juge, et expliquent souvent plus que les scores de qualité. Une application dont les réponses ont doublé de longueur après un changement de prompt s'est généralement dégradée en réception, même quand les mesures de qualité n'ont rien montré.
Ajouter ta propre mesure est simple ici, car une fonction de feedback est une fonction Python ordinaire qui renvoie un nombre. Dans un domaine avec des règles strictes, l'obligation de citer un numéro de base légale par exemple, une vérification par expression régulière est moins chère et plus fiable que n'importe quel modèle juge.
Le coût du scoring et comment le limiter
L'évaluation peut coûter plus cher que l'application elle-même, et cela surprend les équipes qui n'ont chiffré que le coût des réponses aux utilisateurs.
La facture découle de l'arithmétique. Les trois mesures de la triade sont trois appels de modèle supplémentaires par réponse, et la pertinence du contexte calculée par morceau sur cinq morceaux donne sept appels au lieu de trois. Les variantes avec raisonnement consomment en plus des tokens de sortie, et il y en a beaucoup, puisque le modèle écrit une explication.
Trois choses réduisent ce coût sans perdre de valeur. La première est l'échantillonnage : scorer une conversation de production sur vingt donne la même tendance que scorer toutes, pour un vingtième de la facture. Exécute l'ensemble de test complet sur les changements ; échantillonne le trafic de production.
La deuxième est d'adapter le modèle juge à la mesure. L'ancrage peut se mesurer avec un modèle moins cher, car la tâche est comparative. La pertinence de la réponse sur des questions complexes mérite un modèle plus fort.
La troisième est de renoncer aux justifications en dehors du travail de diagnostic. Une tendance se calcule à partir des seuls nombres, et les explications ne sont nécessaires que lorsqu'on descend dans des cas individuels.
À grand volume, une quatrième voie a du sens, une qui change l'unité de facturation : exécuter toi-même le modèle juge. Un serveur comme vLLM expose une interface compatible OpenAI, donc tu diriges le fournisseur de scoring vers ta propre adresse et la facture cesse de dépendre du nombre de conversations scorées pour dépendre des heures de GPU. Le point d'équilibre se situe là où le scoring tourne en continu plutôt qu'une fois par version. La réserve est celle indiquée plus haut : la concordance entre un modèle plus petit et un scoring manuel doit être mesurée séparément, car le résultat d'un juge ne se transpose pas à un autre.
Le cache mérite aussi réflexion. Le même ensemble de test exécuté plusieurs fois par jour sur une application inchangée n'a pas besoin d'être recalculé quand l'entrée et la sortie n'ont pas changé.
TruLens face aux alternatives
| Option | Accent | Licence | À choisir quand |
|---|---|---|---|
| TruLens | Mesures de qualité, la triade RAG | MIT | Une application construite sur la recherche dans des documents |
| Arize Phoenix | Traçage et scoring | Elastic License 2.0 | Tu veux une console solide et du traçage |
| Langfuse | Traçage, choix de l'hébergement | Ouvert avec des modules complémentaires | Tu as besoin des deux options de déploiement |
| Weave | Évaluations et expériences | Apache 2.0, service payant | L'équipe utilise le reste de cette plateforme |
La différence entre la première ligne et les autres est une question de proportion. TruLens met l'accent sur les mesures et leur justesse, tandis que la couche de visualisation des résultats est plus mince. Les autres outils ont des consoles plus riches et un ensemble de mesures toutes prêtes moins raffiné pour la recherche dans des documents.
Remarque que ce ne sont pas des choix exclusifs. TruLens peut tourner comme une bibliothèque qui calcule des scores dans un pipeline de tests, les résultats étant envoyés là où l'équipe regarde déjà. Sous licence MIT, rien ne s'y oppose.
L'intégrer dans un processus
L'outil rapporte le plus quand il s'exécute automatiquement plutôt qu'à la main quand quelqu'un s'en souvient.
Commence par un ensemble de test. Trente questions avec des réponses attendues suffisent pour démarrer et valent mieux que trois cents collectées en un an, car il existe maintenant. La meilleure source est constituée des questions que les utilisateurs ont réellement posées et auxquelles le système a mal répondu.
Branche ensuite le calcul de la triade dans un pipeline qui s'exécute à chaque changement du prompt, des paramètres de recherche ou du modèle. Des résultats avant et après visibles dans la revue de code changent la façon de travailler d'une équipe plus que n'importe quelle console.
Fixe des seuils par mesure. L'ancrage devrait être élevé et mérite de la rigueur, car c'est la mesure qui attrape l'invention. La pertinence du contexte est plus basse et c'est normal, car la recherche renvoie aussi des morceaux qui ne correspondent que partiellement.
Le dernier point est la surveillance du trafic de production. Des mesures calculées une fois par semaine sur un échantillon de vraies conversations montrent si l'ensemble de test reflète encore ce que les gens demandent. Généralement non, et c'est précisément le signal pour l'étendre.
Erreurs fréquentes
La première est de calculer une mesure au lieu de trois. Un seul score de réponse ne dit pas si le problème se trouve dans la recherche ou dans le modèle, donc la correction avance à l'aveugle.
La deuxième est de faire confiance aux scores sans vérifier la concordance avec des personnes. Une mesure fondée sur un modèle peut se tromper de façon systématique, et sans comparaison sur des cas étiquetés à la main, tu ne sais pas à quelle fréquence.
La troisième est d'utiliser le même modèle pour générer et pour juger. Un modèle évalue sa propre sortie plus indulgemment, donc les résultats sortent plus hauts qu'ils ne devraient.
La quatrième est une mauvaise agrégation pour la pertinence du contexte. Une moyenne sur cinq morceaux répond à une autre question que le maximum, et les mélanger mène à de mauvaises conclusions.
La cinquième est de laisser les prompts du juge en anglais en travaillant sur des documents dans une autre langue. L'ancrage exige une correspondance précise des affirmations, et c'est là que l'écart est le plus grand.
La sixième est d'exécuter les évaluations une fois par trimestre. Une mesure qui n'est pas calculée à chaque changement ne protège pas contre la régression, elle la documente après coup.
La septième est de scorer chaque conversation de production au lieu d'un échantillon. La tendance se voit sur une sur vingt, et la facture du scoring peut dépasser le coût des réponses aux utilisateurs.
FAQ
Qu'est-ce que la triade RAG ?
Trois mesures qui couvrent les trois liens d'une application qui répond à partir de documents : la pertinence des morceaux récupérés par rapport à la question, l'ancrage de la réponse dans ces morceaux et la pertinence de la réponse par rapport à la question. Leur combinaison indique s'il faut corriger la recherche, le prompt ou le modèle.
TruLens est-il gratuit ?
Oui, la bibliothèque est publiée sous licence MIT, sans frais ni restriction commerciale. Le coût est celui des appels au modèle juge, car chaque mesure est un prompt à payer à un fournisseur ou à calculer sur ton propre matériel.
Ai-je besoin d'un compte Snowflake ?
Non. La bibliothèque vient d'une entreprise que ce fournisseur a rachetée et s'intègre à ses services, tout en s'installant avec un gestionnaire de paquets ordinaire, en tournant en local et en acceptant n'importe quel fournisseur de modèle juge.
En quoi diffère-t-il de Phoenix et de Langfuse ?
Par l'accent et la licence. TruLens se concentre sur les mesures de qualité, en particulier pour la recherche dans des documents, et est publié sous MIT. Arize Phoenix offre un traçage plus solide sous licence Elastic, et Langfuse s'appuie sur le choix entre l'auto-hébergement et un cloud.
Puis-je scorer des applications en dehors de LangChain ?
Oui. Des intégrations toutes prêtes couvrent des bibliothèques populaires, dont LangChain, mais les mesures se calculent sur n'importe quelle entrée et sortie, donc ton propre code qui appelle un modèle fonctionne aussi.
La documentation se trouve sur le site du projet, et le code et les versions dans le dépôt GitHub.