truera/trulens · 上手攻略

  • 仓库：truera/trulens
  • 链接：https://github.com/truera/trulens
  • 分类：agent / evaluation / llm-infra
  • 作者：spark
  • 更新：2026-07-17

这是什么

TruLens 是 TruEra 公司（已被 Snowflake 收购）维护的、面向 LLM 实验和 AI Agent 的评估与追踪框架。它做两件事：

  1. Instrumentation（埋点）：用 OpenTelemetry 拦截你的 LLM / RAG / Agent 调用，把每一次 LLM 生成、检索、工具调用都落成结构化 OTEL span。
  2. Evaluation（评估）：在这些 span 上跑一套「反馈函数（Feedback Function）」——既可以是 LLM-as-judge 的主观打分（groundedness、relevance、coherence），也可以是传统的 metrics（BLEU、BERTScore 等）。

最终产物是一份可视化的「应用评估仪表盘」，你可以对比同一应用不同版本（换 prompt、换 retriever、换模型）的指标变化——告别「感觉变好了/变差了」的 vibe check。

重要更新：从 2.x 起，TruLens 完全基于 OpenTelemetry，trace 可直接导出到 Jaeger / Grafana Tempo / Datadog / 任何 OTLP 后端，不再绑定自家的 TruEra Dashboard。

仓库 3.4k+ Stars，最近提交 2026-07-11，主语言 Python，许可证 MIT。社区入口在 Snowflake Discourse。

解决什么问题

LLM 应用进入「调 prompt / 换 retriever / 换模型」的迭代阶段后，会撞到三个典型痛点：

  1. 没有量化指标：每次改完 prompt，「看起来不错」靠肉眼，无法横向对比 A/B。
  2. 失败模式不可见：RAG 经常是「答案错」但不知道是检索召回错、rerank 错、还是生成幻觉——根因定位极慢。
  3. 多框架切换成本高：LangChain 写的应用，想加 observability/eval 就要再接一套；换 LlamaIndex 又要重来。

TruLens 的解法：

  • Stack-agnostic 埋点：只要用 @instrument() 装饰你的函数，框架/模型/检索器是什么都无所谓——TruLens 把 span 抽出来统一分析。
  • Feedback Function 即插即用：内置 RAG Triad（Context Relevance / Groundedness / Answer Relevance），以及 7 个面向 Agent 的专用 evaluator（见下文）。
  • 批跑 + 在线跑两种姿势：可以 inline 边跑边评，也可以离线批跑历史数据集。
  • MCP 原生支持：给 MCP tool call 一个 span type，捕获 tool name / arguments / output / latency。

快速安装

TruLens 拆成了多个 wheel，按「核心 + 你用的 provider + 你用的框架」按需装。先装核心，再选 provider 和 app 集成：

# 0) 准备 Python 环境（官方建议 conda）
conda create -n trulens python=3.11
conda activate trulens

# 1) 核心
pip install trulens-core

# 2) 选一个 feedback provider
pip install trulens-providers-openai        # OpenAI / Azure OpenAI
pip install trulens-providers-litellm       # LiteLLM（Anthropic / Cohere / Mistral 等）
pip install trulens-providers-google        # Google Gemini
pip install trulens-providers-bedrock       # AWS Bedrock
pip install trulens-providers-cortex        # Snowflake Cortex
pip install trulens-providers-huggingface   # HuggingFace
pip install trulens-providers-langchain     # LangChain 模型

# 3) 选一个 app 框架集成
pip install trulens-apps-langchain          # LangChain / LangGraph
pip install trulens-apps-llamaindex         # LlamaIndex

# 一行全装（也支持）
pip install trulens

也可以只装一个包：直接 pip install trulens，会自动拉核心 + 常用 provider；之后按需追加。

版本备注：当前是 2.x（OTEL-based），API 与 1.x（TruEra Dashboard 中心）不兼容；新项目一律装 2.x。

核心用法

1) 给自己的函数埋点

不用动框架，只要把函数用 @instrument 包起来：

from trulens.core.otel.instrument import instrument
from trulens.otel.semconv.trace import SpanAttributes

class MyRAG:
    @instrument(
        span_type=SpanAttributes.SpanType.RETRIEVAL,
        attributes={
            SpanAttributes.RETRIEVAL.QUERY_TEXT: "query",
            SpanAttributes.RETRIEVAL.RETRIEVED_CONTEXTS: "return",
        },
    )
    def retrieve(self, query: str) -> list:
        # 你的检索逻辑
        return docs

    @instrument(span_type=SpanAttributes.SpanType.GENERATION)
    def generate(self, query: str, contexts: list) -> str:
        # 你的生成逻辑
        return answer

SpanAttributes 里定义了 RETRIEVAL / GENERATION / MCP / AGENT 等标准 span type，让 evaluator 能自动取到「输入 query」「召回 context」「生成答案」三个关键字段。

2) 定义 Feedback Function

from trulens.core import Metric, Selector
from trulens.providers.openai import OpenAI

provider = OpenAI(model_engine="gpt-4o")

f_context_relevance = Metric(
    name="Context Relevance",
    implementation=provider.context_relevance,
    selectors={
        "input":     Selector.select_record_input(),
        "context":   Selector.select_context(),
    },
)

f_groundedness = Metric(
    name="Groundedness",
    implementation=provider.groundedness,
    selectors={
        "input":     Selector.select_record_input(),
        "output":    Selector.select_record_output(),
        "context":   Selector.select_context(),
    },
)

3) 在线跑（inline 评估）

from trulens.core.otel.instrument import TruSession

session = TruSession()
tru_app = session.App(
    app=my_rag,
    app_name="my-rag",
    app_version="v1",
    metrics=[f_context_relevance, f_groundedness],
)

with tru_app(recorder=tru_app):
    answer = my_rag.query("什么是 OpenTelemetry？")

每个调用都会被记录、跑 feedback function、写到 session 数据库，再在仪表盘里可视化。

4) 离线批跑（Run API，2.8+）

from trulens.core.run import RunConfig

run_config = RunConfig(
    run_name="batch_eval_v1",
    dataset_name="eval_questions",
    source_type="TABLE",
    dataset_spec={"input": "QUESTION"},
    invocation_max_workers=8,
    metric_max_workers=4,
)
run = tru_app.add_run(run_config=run_config)
run.start()
run.compute_metrics([f_context_relevance, f_groundedness])

适合「跑完一批评估问题，再统一对比 v1 / v2 / v3」的场景。

5) MCP 工具调用埋点

@instrument(span_type=SpanAttributes.SpanType.MCP)
def call_mcp_tool(self, tool_name: str, arguments: dict) -> str:
    # 调你的 MCP server
    ...

MCP span 会自动捕获 tool name、arguments、output、latency——配合 Agent 的 7 个专用 evaluator，能直接量化「Agent 选工具选得对不对」。

7 个面向 Agent 的专用 Evaluator

Evaluator 衡量什么
LogicalConsistency 推理连贯性，揪出幻觉和无依据断言
ExecutionEfficiency 是否有多余步骤、重复 retry、浪费算力
PlanAdherence 执行是否真的跟着 plan 走
PlanQuality plan 本身的质量（策略好不好，不看结果）
ToolSelection 每一步选的工具有没有选对
ToolCalling 参数是否合法、输出解读是否正确
ToolQuality 外部 tool/service 本身的可信度

跑法跟普通 Metric 一样，加到 tru_app(metrics=[...]) 里就行。

典型适用场景

  • RAG 上线前的「上线评估」：用 RAG Triad 三个 metric 把现有 100 个问答样本过一遍，定位是检索差还是生成差。
  • Prompt / 模型 A/B 测评：同一个 app 跑 v1 / v2 两个版本，仪表盘里直接对比 Groundedness / Context Relevance 的分布。
  • Agent 行为回归测试：CI 里跑 50 条任务，对比 ToolSelection / PlanAdherence 是否有回归。
  • 多团队共用 observability 后端：trace 走 OTLP 到公司已有的 Grafana Tempo / Datadog，TruLens 只负责「在那些 span 上跑 LLM-as-judge」。
  • MCP 工具调用质量监控：每个 MCP 工具的成功率、参数合法性、输出可读性实时统计。

坑与注意

  1. 2.x 与 1.x 不兼容：如果你看到博客是 TruChain / Feedback / App 那种老 API，那是 1.x，要去 pip install trulens==1.x。新项目一律 2.x + OTEL。
  2. OTEL 引入的额外依赖：opentelemetry-api / opentelemetry-sdk 在你已有 OTEL 栈时要注意版本冲突。
  3. Feedback Function 本身要花 token：LLM-as-judge 的 metric 每次评估都会调一次 LLM，评估本身也是计费的——千条样本 × 3 个 metric 是真金白银，先估算。
  4. Provider ≠ Application：装 trulens-providers-openai 只是给 feedback function 提供 LLM judge；你的应用本身用什么 provider 是另一回事，两者不要混。
  5. Dashboard 入口：纯本地用 TruSession 默认 SQLite + 控制台；想看 UI 可以跑 trulens-dashboard 或导出到 Snowflake Discourse 的官方社区实例。
  6. Span type 命名要正确：SpanAttributes.SpanType.RETRIEVAL / GENERATION / MCP 这些枚举值写错了，evaluator 取不到对应字段，metric 会返回 NaN，不会报错——只看分数会很难发现。

与同类对比

工具 形态 关键差异
TruLens OTEL-based 评估 + 追踪 Feedback Function 生态最全；7 个 Agent 专用 evaluator；与 OTLP 后端互通
LangSmith LangChain 官方 SaaS 深度绑定 LangChain；UI 漂亮；闭源 / 收费
Arize Phoenix 开源 observability 偏 trace 调试，eval 模型不如 TruLens 丰富
RAGAS RAG 专项评估库 指标科学严谨，但只服务 RAG、不覆盖 Agent
DeepEval pytest 风格 eval 写测试用例一样的姿势，本地 CI 友好；UI 弱
OpenLLMetry 纯 OTEL 埋点 不做评估，只做 trace；可以跟 TruLens 互补

一句话：TruLens 是当下「feedback function 数量 × Agent evaluator 覆盖度」最齐全的 OTEL-native 方案。

一句话推荐结论

如果你做的是 RAG 或 Agent、需要把「调 prompt/换 retriever」从玄学变成数据驱动，TruLens 是当前门槛最低、社区最稳的选择——pip install trulens-core trulens-providers-openai，给函数加 @instrument，三十分钟跑起来。

参考来源

  • GitHub README: https://github.com/truera/trulens
  • 官方快速上手: https://www.trulens.org/getting_started/
  • 核心概念: https://www.trulens.org/getting_started/core_concepts/feedback_functions/
  • 官方 blog（OTEL 重构公告）: https://www.trulens.org/blog/2025/06/02/telemetry-for-the-agentic-world-trulens--opentelemetry/
  • 社区: https://snowflake.discourse.group/c/ai-research-and-development-community/trulens/97
  • DeepWiki: https://deepwiki.com/truera/trulens

不确定处

  • 2.x 的具体最新 minor 版本号 README 未单独标出，按 pip install trulens-core 默认拉最新版即可；写代码前用 pip show trulens-core 确认版本。
  • SpanAttributes.SpanType.MCP 是较新加的枚举，老版本可能没有；遇到 AttributeError 时升 trulens-core 即可。
  • trulens-dashboard 入口在新版本是否仍是默认 CLI 命令，以安装后 trulens --help 为准——OTEL 化后很多人直接用 Grafana Tempo / Jaeger 看 trace。