设置多轮在线评估器

多轮在线评估器让你能够评估人类与 agent 之间的整个对话，而不仅是单次交换。它们衡量线程中所有轮次上的端到端交互质量。

TIP

要使用一个由 LangChain 托管、线程级的评判者，而无需配置模型、API 密钥或提示，参阅 LangChain Tuned Evaluators。

你可以用多轮评估来衡量：

1. 语义意图：用户想要做什么。
2. 语义结果：实际发生了什么，任务是否成功。
3. 轨迹：对话如何展开，包括工具调用的轨迹。

NOTE

多轮在线评估器默认会延长追踪保留。你可以在配置评估器时选择退出，让追踪保持项目配置的保留层级。如果另一个动作显式延长保留，或项目已经使用延长保留，追踪仍会被升级。有关分步退出说明，参阅管理评估器追踪保留。有关详情，参阅数据保留自动升级。

工作原理

多轮在线评估器遵循以下评估生命周期：

1. 追踪摄取：对话中的每一轮都被追踪为一次单独的运行，并通过共享线程 ID 与一个线程关联。
2. 空闲时间检测：在线程中最后一条追踪被摄取后，LangSmith 会等待配置的空闲时间过去。这段空闲期表明对话已完成、可进行评估。
3. 消息组装：LangSmith 收集线程中每条追踪的 messages，并将它们组装成一段单一的对话历史。如果每条追踪只含最新消息，LangSmith 会跨轮次把消息拼接起来。如果每条追踪含完整历史，LangSmith 会直接用它。由于线程中连续的追踪常重发先前历史，LangSmith 会对重叠的消息去重，使每条只出现一次。结果是一个 OpenAI 聊天格式的消息列表（{"role": ..., "content": ...}），这正是你提示中的 all_messages 变量所解析到的内容。
4. LLM-as-a-judge 评估：组装好的对话被传给你配置的 LLM-as-a-judge 提示。评估器基于你的标准对完整线程打分：语义意图、结果或轨迹。
5. 反馈记录：评估器使用你配置的、与线程关联的反馈键，将反馈写入 LangSmith。

这一生命周期意味着多轮评估器在每个完成的线程上运行一次，而非每条追踪一次。如果你想按追踪评估，使用运行级在线评估器。

前置条件

• 你的追踪项目必须使用线程。
• 线程中每条追踪的顶层输入和输出必须有一个 messages 键，其中含一个消息列表。我们支持 LangChain、OpenAI Chat Completions 和 Anthropic Messages 格式的消息。
  • 如果每条追踪的顶层输入和输出只含对话中的最新消息，LangSmith 会自动跨轮次把消息合并到一个线程中。
  • 如果每条追踪的顶层输入和输出含完整对话历史，LangSmith 会直接使用它。

NOTE

如果你的追踪不符合上述格式，线程级评估器将无法工作。你需要更新你向 LangSmith 追踪的方式，以确保每条追踪的顶层输入和输出含一个 messages 列表。

更多信息请参考故障排除一节。

配置

1. 导航到 Tracing 页面并选择一个追踪项目。

2. 点击 Evaluators 标签，然后点击 + Evaluator。在 Create from scratch 下选择 LLM-as-a-Judge Evaluator。在 Source 下选择 Threads。

3. 为你的评估器命名。

4. 应用 Filters 或一个 Sampling Rate。

   使用过滤器或采样来控制评估器成本。例如，只评估少于 N 轮的线程，或采样所有线程的 10%。

5. 配置一个空闲时间。

   你首次配置一个线程级评估器时，可以定义空闲时间，即线程中最后一条追踪之后、被视为完成并可评估的那段时间。这个值应当反映你应用中用户交互的预期长度。空闲时间默认为 10 分钟，且不能设到 2 分钟以下。

NOTE

空闲时间是一个项目级设置。它适用于项目中每个线程级评估器，以及每个 item type 为 Threads 的 automation rule。

TIP

首次测试你的评估器时，用一个短的空闲时间，以便你快速看到结果，但要受 2 分钟最小值约束。一旦验证通过，把它增大以匹配用户交互的预期长度。

6. 配置你的模型。

   选择你想为你的评估器使用的提供商和模型。线程往往很长，因此你应当使用一个上下文窗口更大的模型，以避免触达限制。例如，OpenAI 的 GPT-5.4 mini 或 Gemini 2.5 Flash 都是不错的选择，因为它们都有 1M+ token 的上下文窗口。

7. 配置你的 LLM-as-a-judge 提示。

   定义你想评估什么。这个提示将被用来评估该线程。你也可以通过 all_messages 变量配置组装好的对话的哪些部分被传给评估器，以控制它接收到的内容：

   • 全部消息：把完整对话作为一个 OpenAI 聊天格式的 JSON 消息对象列表（{"role": ..., "content": ...}）发送，每条消息渲染为缩进的 JSON 并以空行分隔。
   • 人类与 AI 配对：只发送 user 和 assistant 消息，格式化为 <user>...</user> 和 <assistant>...</assistant>，排除 system 消息、工具调用和其他角色。
   • 首个用户与末个 AI：只发送第一条 user 消息和最后一条 assistant 回复。

8. 设置你的反馈配置。

   为反馈键配置一个名称、你想收集的反馈的格式，并可选地在反馈上启用推理。

WARNING

对线程级评估器和运行级评估器使用同一个反馈键不推荐，因为难以区分两者。

9. 保存你的评估器。

   保存后，你的评估器会出现在 Evaluators 标签中。一旦保存后创建的新线程过了空闲时间，你就可以测试它。

评估轨迹

trajectory 是线程评估器可使用的变量之一，与 all_messages、human_ai_pairs 和 first_human_last_ai 并列。它解析到对话的轨迹：从始至终扁平、有序的消息列表，包括工具调用及其结果。用它来为 agent 所采取的路径打分，例如它是否选对了工具、遵循了它的计划，并在抵达结果时没有做多余的步骤。

NOTE

trajectory 变量仅在 LangSmith Cloud 的 GCP US 区域（smith.langchain.com）可用。它在 GCP EU、GCP APAC 或 AWS US 区域，以及自托管和 BYOC 部署上不可用。自托管支持不包含在 LangSmith v0.16.0 稳定版发布中。对自托管和 BYOC 部署的支持将在未来的版本中提供。

这些变量在评判者收到的内容上有所不同：

• all_messages、human_ai_pairs 和 first_human_last_ai 解析到从线程中每次根运行的输入和输出组装出的对话。发生在子运行中的工作，例如中间模型调用、工具调用和工具结果，除非某次根运行自身的输入或输出包含它们，否则不被纳入。human_ai_pairs 和 first_human_last_ai 会进一步收窄到仅 user 和 assistant 消息。
• trajectory 解析到从每条追踪内部的模型和工具调用构建的轨迹。其他视图省略的工具调用和工具结果会被保留。

有关每个变量解析到的消息形状，参阅线程消息变量。

WARNING

一条轨迹通常比其他任何视图都大，因为它同时涵盖根运行和子运行。如配置第 6 步所述，选择一个上下文窗口高的模型，并预期每次评估有更高的 token 用量。

使用 trajectory 变量

遵循上面的配置步骤。有两处不同：

1. 在 Source 下，选择 Threads。该变量仅在对追踪项目（而非数据集）运行的评估器上可用。
2. 在你的提示中引用 {trajectory}，并把该变量映射到 trajectory 来源。该变量必须命名为 trajectory：一个指向该来源但名称不同的变量会被拒绝。种子的默认提示和映射已经这样做了，因此新评估器此处无需更改。

在 Runs 和 Threads 之间切换 Source，只在你尚未编辑默认提示时才会重新种子默认提示。一旦你编辑了提示，你的版本就会被保留，由你自己映射变量。

{trajectory} 不能与 {all_messages}、{human_ai_pairs} 或 {first_human_last_ai} 并存。一旦你映射了轨迹来源，其他来源会在变量来源下拉菜单中被禁用，而一旦你映射了其中其他一个，轨迹来源就被禁用。无论如何，下拉菜单会解释轨迹变量与非轨迹变量不能一起使用。保存一个混合它们的评估器会以同样的方式失败。

当评估器完成时，LangSmith 会在你配置的反馈键下，把反馈写入线程中最近的根运行，并将该反馈与线程关联。要日后找到它，参阅查看反馈。

有关你可以改编的完整提示，参阅带轨迹上下文的示例。

WARNING

这个选择在你创建评估器时就已固定。要在 trajectory 与其他线程变量之间移动一个现有评估器，需删除它并新建一个。

设置与约束

一个使用 trajectory 的评估器支持以下设置：

• 过滤器：限制评估器在哪些线程上运行。
• 采样率：评估匹配你过滤器的线程的一个百分比。
• 空闲时间：项目级线程空闲时间，它适用于项目中每个线程级评估器。

以下选项不可用，包含其中之一的配置会被拒绝：

• 作为来源的数据集和实验。
• 对现有线程的回填。
• 追踪过滤器和树过滤器。
• few-shot 示例、扩展统计和数据集修正。
• 同一条自动化规则上的代码评估器，以及非评估器动作，例如把线程添加到标注队列。

轨迹不是一次运行，因此任何读取运行级字段的选项都不可用。

限制

这些是线程级处理的当前限制（可能变化）。它们适用于多轮在线评估器，以及 item type 为 Threads 的自动化规则。如果你遇到其中任何限制，请联系我们。

• 运行必须少于一周龄：当一个线程变为空闲时，只有过去 7 天内的运行符合评估条件。
• 一次最多处理 500 个线程：单次执行最多处理 500 个匹配的线程，按最近活动排序。
• 每个工作区最多 10 个多轮在线评估器

故障排查

检查你的评估器状态

你可以通过导航到追踪项目内的 Evaluators 标签、为你创建的评估器点击 Logs 按钮查看其运行历史，来检查你的评估器上次运行的时间。

检查发送给评估器的数据

通过导航到追踪项目内的 Evaluators 标签、点击你创建的评估器，并点击 Evaluator traces 标签，来检查发送给评估器的数据。

在此标签中，你可以看到传入 LLM-as-a-judge 评估器的输入。如果你的消息没有被正确传入，你会在输入中看到空白值。如果你的消息未按预期格式之一格式化，就可能发生这种情况。

---