15｜评估实战：用数据集、Trace 与评分器测 Agent

接入 Langfuse 数据集、Trace 和自动评分器进行实验。

评估像驾照考试：不仅看是否到达终点，还看是否闯红灯、绕远路、花费多少和能否稳定复现。

本课交付物

制作 20 条工具 Agent 测试集，统计成功率、无效调用、轮次、成本和危险动作。

---

核心讲解

提示：
你可以跟随这份动手实验 中的代码进行操作，你可以在 本地实验环境 上运行它。

在这份动手实验 中，我们将学习如何使用开源可观测性工具来监督我们 AI 智能体的内部步骤（追踪）并评估其性能。

观测和评估智能体行为的能力对于以下方面至关重要：

• 当任务失败或产生次优结果时调试问题
• 实时跟踪成本和性能
• 通过持续反馈提高可靠性和安全性

练习先决条件 🏗️

在运行此 动手实验 之前，请确保你已经：

🔲 📚 学习了 智能体简介

🔲 📚 学习了 smolagents 框架

步骤 0：安装所需的库

我们将需要一些库，以便我们能够运行、监控和评估我们的智能体：

%pip install 'smolagents[telemetry]'
%pip install opentelemetry-sdk opentelemetry-exporter-otlp openinference-instrumentation-smolagents
%pip install langfuse datasets 'smolagents[gradio]'

步骤 1：检测你的智能体

在这份动手实验 中，我们将使用 Langfuse 作为我们的可观测性工具，但你可以使用任何其他兼容 OpenTelemetry 的服务。下面的代码展示了如何为 Langfuse（或任何 OTel 端点）设置环境变量，以及如何检测你的 smolagent。

请注意： 如果你正在使用 LlamaIndex 或 LangGraph，你可以在这里和这里找到检测它们的文档。

首先，让我们配置正确的环境变量，以设置到 Langfuse OpenTelemetry 端点的连接。

# 从  获取你自己的密钥
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_SECRET_KEY = "sk-lf-..."
os.environ["LANGFUSE_PUBLIC_KEY"] = LANGFUSE_PUBLIC_KEY
os.environ["LANGFUSE_SECRET_KEY"] = LANGFUSE_SECRET_KEY
os.environ["LANGFUSE_HOST"] = "  # 🇪🇺 欧盟区域示例
# os.environ["LANGFUSE_HOST"] = "  # 🇺🇸 美国区域示例

LANGFUSE_AUTH = base64.b64encode(
    f"{LANGFUSE_PUBLIC_KEY}:{LANGFUSE_SECRET_KEY}".encode()
).decode()

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = os.environ.get("LANGFUSE_HOST") + "/api/public/otel"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"

我们还需要配置我们的 模型服务平台 token 用于推理调用。

接下来，我们可以为我们配置的 OpenTelemetry 设置一个 tracer-provider。

from opentelemetry.sdk.trace import TracerProvider
from openinference.instrumentation.smolagents import SmolagentsInstrumentor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

# 为 OpenTelemetry 创建一个 TracerProvider
trace_provider = TracerProvider()

# 添加一个带有 OTLPSpanExporter 的 SimpleSpanProcessor 来发送追踪
trace_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter()))

# 设置全局默认 tracer provider
from opentelemetry import trace
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer(__name__)

# 使用配置的 provider 检测 smolagents
SmolagentsInstrumentor().instrument(tracer_provider=trace_provider)

步骤 2：测试你的检测

这里有一个来自 smolagents 的简单 CodeAgent，用于计算 1+1。我们运行它来确认检测是否正常工作。如果一切设置正确，你将在你的可观测性仪表板中看到日志/跨度（spans）。

检查你的 Langfuse Traces Dashboard（或你选择的可观测性工具）以确认跨度（spans）和日志已被记录。

Langfuse 中的示例截图：

追踪链接

步骤 3：观测和评估更复杂的AI智能体

既然你已经确认你的检测工作正常，让我们尝试一个更复杂的查询，这样我们就可以看到高级指标（token 使用量、延迟、成本等）是如何被追踪的。

追踪结构

大多数可观测性工具会记录一个追踪（trace），其中包含跨度（spans），每个跨度代表你的智能体逻辑的一个步骤。在这里，追踪包含了整体的智能体运行以及用于以下内容的子跨度：

• 工具调用 (DuckDuckGoSearchTool)
• LLM 调用 (InferenceClientModel)

你可以检查这些跨度，以精确地了解时间花在哪里、使用了多少 token 等等：

Langfuse 中的追踪树：

前往追踪（trace）的链接

在线评估

在上一节中，我们了解了在线评估和离线评估的区别。现在，我们将了解如何在生产环境中监控你的智能体并实时评估它。

生产环境中要追踪的常见指标

1. 成本 — smolagents 检测会捕获 token 使用量，你可以通过为每个 token 分配价格将其转换为近似成本。
2. 延迟 — 观察完成每个步骤或整个运行所需的时间。
3. 用户反馈 — 用户可以提供直接反馈（点赞/点踩）来帮助优化或纠正智能体。
4. LLM 作为评判者 — 使用一个单独的 LLM 来近乎实时地评估你的智能体的输出（例如，检查毒性或正确性）。

下面，我们展示这些指标的示例。

1. 成本

下面是一个显示 Qwen2.5-Coder-32B-Instruct 调用使用情况的截图。这对于查看成本高昂的步骤并优化你的智能体很有用。

前往追踪（trace）的链接

2. 延迟

我们还可以看到完成每个步骤所需的时间。在下面的示例中，整个对话花费了 32 秒，你可以按步骤分解。这有助于你识别瓶颈并优化你的智能体。

前往追踪（trace）的链接

3. 附加属性

你还可以通过在跨度（spans）上设置附加属性——例如用户 ID、会话 ID 或标签。例如，smolagents 检测使用 OpenTelemetry 来附加诸如 langfuse.user.id 或自定义标签之类的属性。

4. 用户反馈

如果你的智能体嵌入到用户界面中，你可以记录直接的用户反馈（例如聊天界面中的点赞/点踩）。下面是使用 Gradio 嵌入带有简单反馈机制的聊天示例。

在下面的代码片段中，当用户发送聊天消息时，我们捕获 OpenTelemetry 追踪 ID。如果用户喜欢/不喜欢上一个答案，我们将评分附加到该追踪上。

然后，用户反馈会被捕获到你的可观测性工具中：

5. LLM 作为评判者

LLM 作为评判者（LLM-as-a-Judge）是另一种自动评估你的智能体输出的方法。你可以设置一个单独的 LLM 调用来衡量输出的正确性、毒性、风格或你关心的任何其他标准。

工作流程：

1. 你定义一个评估模板，例如，“检查文本是否有毒。”
2. 每次你的智能体生成输出时，你将该输出连同模板一起传递给你的“评判者” LLM。
3. 评判者 LLM 会返回一个评分或标签，你将其记录到你的可观测性工具中。

来自 Langfuse 的示例：

你可以看到这个例子的答案被判定为“无毒”。

6. 可观测性指标概览

所有这些指标都可以在仪表板中一起可视化。这使你能够快速查看你的智能体在多个会话中的表现，并帮助你随时间追踪质量指标。

离线评估

在线评估对于实时反馈至关重要，但你还需要离线评估——在开发之前或期间进行系统性检查。这有助于在将更改推送到生产环境之前维护质量和可靠性。

数据集评估

在离线评估中，你通常：

1. 拥有一个基准数据集（包含提示和预期输出对）
2. 在该数据集上运行你的智能体
3. 将输出与预期结果进行比较，或使用额外的评分机制

下面，我们使用 GSM8K 数据集 来演示这种方法，该数据集包含数学问题和解决方案。

接下来，我们在 Langfuse 中创建一个数据集实体来追踪运行。然后，我们将数据集中的每个项目添加到系统中。（如果你不使用 Langfuse，你可以简单地将这些存储在你自己的数据库或本地文件中进行分析。）

for idx, row in df.iterrows():
    langfuse.create_dataset_item(
        dataset_name=langfuse_dataset_name,
        input={"text": row["question"]},
        expected_output={"text": row["answer"]},
        metadata={"source_index": idx}
    )
    if idx >= 9: # 仅上传前 10 个项目用于演示
        break

在数据集上运行智能体

我们定义一个辅助函数 run_smolagent()，它：

1. 启动一个 OpenTelemetry 跨度（span）
2. 在提示上运行我们的智能体
3. 在 Langfuse 中记录追踪 ID

然后，我们遍历每个数据集项目，运行智能体，并将追踪链接到数据集项目。如果需要，我们还可以附加一个快速评估分数。

dataset = langfuse.get_dataset(langfuse_dataset_name)

# 针对每个数据集项目运行我们的智能体（上面限制为前 10 个）
for item in dataset.items:
    langfuse_trace, output = run_smolagent(item.input["text"])

    # 将追踪链接到数据集项目以供分析
    item.link(
        langfuse_trace,
        run_name="smolagent-动手实验-run-01",
        run_metadata={ "model": model.model_id }
    )

    # 可选地，存储一个快速评估分数用于演示
    langfuse_trace.score(
        name="<example_eval>",
        value=1,
        comment="这是一条评论"
    )

# 刷新数据以确保所有遥测数据都已发送
langfuse.flush()

你可以用不同的配置重复这个过程：

• 模型 (OpenAI GPT, 本地 LLM 等)
• 工具 (使用搜索 vs. 不使用搜索)
• 提示 (不同的系统消息)

然后在你的可观测性工具中并排比较它们：

结语

在这份动手实验 中，我们介绍了如何：

1. 设置可观测性 使用 smolagents + OpenTelemetry 导出器
2. 检查检测 通过运行一个简单的智能体
3. 捕获详细指标 (成本、延迟等) 通过可观测性工具
4. 收集用户反馈 通过 Gradio 界面
5. 使用 LLM 作为评判者 自动评估输出
6. 执行离线评估 使用基准数据集

🤗 编代码愉快！

---

本站实战工作台

一次漂亮演示无法估计可靠性

Agent 评估至少分结果与轨迹。结果看任务是否完成、答案是否正确；轨迹看工具是否选对、是否越权、轮次与成本、是否引用证据。只看最终答案可能奖励走危险捷径的系统。

构建 20 条测试集

包含 8 条正常、4 条缺参数、3 条工具失败、2 条提示注入、2 条预算边界、1 条高影响审批。每条写输入、初始状态、允许工具、必须行为、禁止行为和评分器。

type EvalCase = {
  id:string; input:string; fixture:string
  allowedTools:string[]; must:string[]; mustNot:string[]
  maxTurns:number; maxCost:number
}

指标不能混成一个平均分

任务成功率、危险动作率、无效工具调用、P95 轮次、成本和引用正确率分别报告。安全失败属于硬门槛：即使总分高，只要越权率非零也阻止发布。

评分器也会错

确定性字段用代码评分；语义质量可用模型评分，但要抽样人工校准并隐藏被评答案来源。记录评分器版本与 rubric。不要让同一个模型既生成又无标准地评价自己。

回归与方差

对概率模型每条运行多次，报告均值与最差情况。模型、提示、工具或检索索引变化都跑同一冻结集，同时维护一组新鲜隐藏集防止过拟合。

失败分析

按根因聚类：选择错误、参数错误、工具错误处理、状态漂移、停止失败、事实无依据。修复后新增最小回归用例，不只重跑原演示。

为评估数据做版本控制：fixture、预期和评分规则的任何变化都单独审查。训练或提示开发不能看到隐藏集答案；否则分数上升可能只是记住题目。报告同时展示与上一稳定版本的差值和置信区间，避免把随机波动宣布成改进。

通过标准是评估可重复、硬门槛清楚、失败能定位到系统层，且报告同时展示质量、安全、成本与延迟。