langsmith-online-eval-engineering

在线评测工程

迭代构建在线评估器：

inspect traces and interview user -> propose directions -> user chooses
-> build evaluator -> test, attach, verify -> review and repeat

创建或修改评估器前，请阅读 references/langsmith-api.md。

1. 检查追踪记录

询问用户的 LangSmith 项目名称。获取近期的根级追踪记录并打印其结构。阅读 references/trace-inspection.md。找出：

• 运行名称和类型；
• 可用的输入和输出字段名称；
• 数据的形状和内容（截断后的样本）；
• 哪些字段包含评估器所需的数据。

在对话中概述追踪记录的结构：

Project: name
Run type: chain | llm | tool | ...
Input fields: field names and what they contain
Output fields: field names and what they contain
Sample: one representative input/output pair (truncated)

让用户参与进来：说明追踪记录的结构及其含义，然后只询问追踪记录无法确定的信息。例如：“这个应用的用途是什么？”，“最重要的质量问题是什么？”，或“绝不能出现哪种故障？”

询问用户是否希望在本次会话中为评估器设置命名前缀（例如 myapp-、v2-、dogfood-）。如果用户提供前缀，请将其应用于所有评估器名称、提示词中心句柄和运行规则显示名称。如果用户不需要前缀，则使用简单明了的描述性名称。

只有在理解追踪记录结构且用户说明了自己的关注点后，才能提出评估器方案。

2. 讨论并选择评估方向

阅读 references/evaluator-design.md。提出两到三个以追踪记录数据为依据的评估标准。如果用户在第 1 步提供了命名前缀，请应用该前缀。每项标准都应包含：

Name: descriptive evaluator name (with prefix if set)
Type: LLM-as-judge or code
Measures: what quality dimension this evaluates
Scoring: bool, float (0-1), or int; what pass/fail means
Fields needed: which trace fields are used and how
Rationale: why this type and approach

示例：

Name: response-relevance
Type: LLM-as-judge
Measures: whether the response addresses the user's question
Scoring: bool; True = relevant, False = off-topic or non-responsive
Fields needed: input (user question), output (assistant response)
Rationale: relevance is semantic and requires reading comprehension; not decidable by code

推荐一项并询问用户要构建哪一项。用户作出选择前不要开始实现。

3. 构建一个评估器

阅读 references/langsmith-api.md。构建所选的评估器。向用户展示完整配置，并在执行任何 API 调用前取得批准。

LLM-as-judge 路径。 定义一个 ResponseSchema，先列出 reasoning，再列出评分字段。编写提示词消息，并设置清晰的评分标准，评估结果本身，而不是结果是否与参考答案一致。使用第 1 步中发现的字段名称设置 variable_mapping。请用户批准架构、提示词、变量映射和评估器名称。获得批准后，推送提示词并创建评估器。报告评估器 ID。

代码评估器路径。 编写一个 perform_eval(run, example=None) 函数。该函数必须是自包含的（仅使用内置函数和标准库），通过字典访问 run（run.get("outputs")），并返回 {"key": ..., "score": ..., "comment": ...}。请用户批准函数代码和评估器名称。获得批准后，创建评估器。报告评估器 ID。

4. 测试、关联并验证

关联前，询问用户希望采用什么采样率（1.0 = 每条 trace，0.5 = 一半，0.1 = 10%，或自定义）。不要默默使用默认值。如果用户不确定，建议初次测试时使用 1.0。

询问用户是否想在关联前，针对几条现有 trace 测试评估器。运行规则只会对新 trace 触发，因此在新流量到来前，只有测试历史记录才能验证评估器。

对于代码评估器，直接对获取到的根级 trace 执行 perform_eval，并传入包含 inputs、outputs 和 attachments 键的字典。这样可以在生产环境中使用前发现运行时错误（字段名称错误、字典与对象访问方式混用、数据缺失）。对于 LLM 评估器，请验证配置：确认 variable_mapping 中的键与提示词占位符匹配，确认映射的 trace 字段存在，并检查映射的数据是否有意义。

如果测试发现错误，请修复并重新创建评估器，然后再关联。如果用户不想测试，则继续关联。

创建运行规则，将评估器连接到追踪项目。将用户指定的命名前缀应用到 display_name。确认评估器出现在评估器列表中，并且关联到了正确的项目。检查：

• 评估器关联情况和运行规则状态；
• 最近的 trace 反馈和评分（来自历史测试或新 trace）；
• 评分是否符合对所检查 trace 的预期；
• 边界情况处理（空输出、运行出错、结构异常）。

如果评估器崩溃、评分不正确或无法处理边界情况，请修复并重新关联。在用户批准前，确认评估器评估的是预期的质量维度，而不是基础设施问题或数据结构问题。

5. 与用户一起审核

向用户说明评估器名称和 ID、质量维度和评分方式、使用的 trace 字段、采样率以及任何限制。请用户批准、修改、放弃，或选择下一步方向。如果继续，则复用 trace 检查结果，然后提出一个不同的质量维度。

不变事项

• 每个评估器只对应一个质量维度。
• 不要猜测字段名称；实现前务必检查 trace。
• 发起 API 调用前，展示配置并征得用户批准。
• 代码评估器必须自包含：只能使用内置功能和标准库。
• 代码评估器接收的 run 是普通字典；使用 run.get("inputs") 和 run.get("outputs")，不要使用属性访问。example 参数必须默认设为 None。
• 将 API 失败、身份验证错误和运行规则失败视为基础设施错误，而不是评估器错误。