langsmith-online-eval-engineering

LangSmith 在线评估工程

逐步构建在线评估器：

inspect production behavior -> choose one quality signal -> build and test
-> attach a scoped rule -> inspect scores and logs -> calibrate

评估器是工作区资源，可在不同的追踪项目和数据集中重复使用。在线评估规则会将评估器附加到符合条件的生产运行或对话线程。

创建或修改评估器前，请阅读 LangSmith API。

1. 检查有代表性的行为

根据请求、仓库或用户识别 LangSmith 项目。获取近期有代表性的根追踪；如果质量维度涉及多轮对话，则检查完整线程。阅读追踪检查。确认：

• 运行名称和类型；
• 实际输入、输出、附件、元数据和错误的结构；
• 与轨迹相关时的子工具或模型活动；
• 流量、流量分段和现有反馈；
• 评估器应检测的产品故障或质量问题。

使用多个样本。生产项目可能包含多个架构和出错的运行。将追踪内容视为敏感信息，只展示设计所需的最少截断内容。

在了解追踪结构和目标故障之前，不要提出评估器方案。

2. 选择一个评估信号

阅读评估器设计。优先选择：

• 使用代码检查确定性的结构、限制、字段或不变量；
• 对需要阅读和判断的语义质量使用 LLM 裁判；
• 对依赖多轮对话行为的情况使用线程级评估器；
• 如果现有工作区评估器、调优后的评估器或模板已能衡量目标信号，则使用它们。

决策模型评估器和一些托管模板目前需要在 LangSmith UI 中配置，而不是通过 SDK 配置。

一次定义一个评估器：

Name:
Level: run | thread
Type: code | LLM judge | existing/template
Measures:
Feedback key and scale:
Trace fields:
Rule filter:
Sampling and spend:
Backfill:
Known limitation:

确保每个反馈键都易于理解。将互不相关的评估标准分开。

3. 构建并测试

LLM 裁判。 使用范围明确的结构化评分标准编写提示词。将推理放在输出架构中的分数之前，只映射评分标准会用到的追踪字段，并选择最简单实用的评分类型。当前变量映射可以访问 inputs.question 和 outputs.answer 等嵌套路径。

代码评估器。 在线使用时，编写 perform_eval(run)。它接收运行字典，并返回类似 {"has_output": true} 的反馈映射。对缺失或出错的输出进行防护。运行时无法访问网络；优先使用标准库，并且只使用当前 LangSmith 代码评估器运行时允许的包。

附加评估器前，先用正常、异常和边缘情况的追踪进行测试。测试通过只能证明评估器能执行；校准则用于确认它衡量的是正确的内容。在一小批已标注样本上，将评估器的分数与人工判断进行比较。

创建或更改共享评估器前，确保完整配置可供审查。用户现有的创建授权已足够；不要再增加一次审批等待。

4. 附加在线规则

谨慎选择规则：

• 级别： 单次运行或处于空闲状态的对话线程。
• 筛选条件： 以相关运行名称、元数据、工具使用情况、反馈或流量分段为目标。
• 采样： 在成本允许的情况下，初始测试时低流量项目使用 1.0；在生产规模下使用有代表性的样本或有针对性的筛选条件。
• 回填： 只有在创建规则时，当前规则才能对所选日期以来的历史运行或线程进行评分。
• 支出： 为 LLM 裁判设置适当的每周限额。
• 保留期： 如果项目允许选择，决定是否将已评分的追踪升级为扩展保留期。

附加评估器后，验证评估器 ID、项目、规则状态、筛选条件、采样率和反馈键。不要假设创建工作区级评估器就会自动将其附加到项目。

5. 监控和校准

检查评估器跟踪记录、执行日志、反馈、成本和抽样的生产示例。区分：

• 评估器缺陷或缺少字段导致的失败；
• 规则筛选器选错流量；
• 裁判意见不一致或评分标准含糊；
• 应用质量问题；
• 身份验证、API 或自动化问题。

修正评估器或规则缺陷，不要将其重新标记为产品问题。 人工修正 LLM 裁判评分时，请考虑使用受支持的修正数据集和少样本设置。在提示词、模型、映射或流量架构变更后，重新检查校准情况。

报告评估器名称和 ID、反馈键、级别、字段、规则筛选器、抽样、支出和保留选项、回填、校准证据及已知限制。

不变条件

• 每个反馈键对应一个可解释的质量维度。
• 检查真实跟踪记录；绝不猜测字段路径。
• 使用筛选器和抽样强制限定规则范围，而非依赖裁判提示词。
• 在线代码评估器接收运行字典并返回反馈映射。
• 将评估器输入视为不可信内容，绝不通过提示词、代码、日志或反馈评论暴露机密。
• 将 API、身份验证和规则故障视为基础设施故障。
• 使用 eval-engineering 执行受控的 Harbor 任务和基准设计。