在 LangSmith 中迭代构建在线评估器：从…

当你需要为 LangSmith 项目创建在线评估器（online evaluator）时，通过检查 trace、访谈用户、逐个构建并验证评估器的完整流程。

适用场景

解决思路

1. 先阅读 references/langsmith-api.md，再创建或修改评估器。
2. 向用户询问其 LangSmith 项目名称，拉取最近的根级 trace 并打印其结构，同时阅读 references/trace-inspection.md。
3. 从 trace 中找出：run 名称与类型、可用的输入输出字段名、数据的形状与内容（截断样本）、评估器所需数据位于哪些字段。
4. 在对话中总结 trace 结构：项目名、run 类型（chain/llm/tool 等）、输入字段及其内容、输出字段及其内容、一对代表性输入输出样本（截断）。
5. 保持用户参与：解释 trace 结构及其含义，只询问 trace 无法确定的信息，例如“这个应用是做什么的？”“最关心哪种质量问题？”“哪种失败绝不能发生？”。
6. 询问用户是否要为本次会话的评估器设置命名前缀（如 myapp-、v2-、dogfood-）；若有则应用到所有评估器名称、prompt hub handle 和 run rule 显示名；若拒绝则使用普通描述性名称。
7. 在理解 trace 结构且用户描述其关注点之前，不要提出评估器方案。
8. 阅读 references/evaluator-design.md，基于 trace 数据提出两到三个评估标准，并应用第 1 步的命名前缀。
9. 为每个候选评估器给出：名称、类型（LLM-as-judge 或 code）、衡量的质量维度、评分方式（bool、float 0-1 或 int，以及通过/失败含义）、所需字段及用法、选择该类型与方法的理由。
10. 推荐其中一个并询问用户选择构建哪个；在用户选择之前不要实现。
11. 阅读 references/langsmith-api.md，构建所选评估器；在执行任何 API 调用前，向用户展示完整配置并获得批准。
12. LLM-as-judge 路径：定义 ResponseSchema，先放 reasoning 再放 score 字段；编写带清晰 rubric 的 prompt 消息，评估结果本身而非是否匹配参考答案；使用第 1 步发现的字段名设置 variable_mapping；展示 schema、prompt、variable mapping 和评估器名称以供批准；批准后推送 prompt 并创建评估器，报告评估器 ID。
13. 代码评估器路径：编写 perform_eval(run, example=None) 函数；必须自包含（仅用内置模块和标准库）；以 dict 方式访问 run（run.get("outputs")）；返回 {"key": ..., "score": ..., "comment": ...}；展示函数代码和评估器名称以供批准；批准后创建评估器并报告评估器 ID。
14. 挂载前询问用户想要的采样率（1.0 = 每条 trace，0.5 = 一半，0.1 = 10%，或自定义）；不要静默使用默认值；若用户不确定，建议初始测试用 1.0。
15. 询问用户是否要在挂载前用少量已有 trace 测试评估器；run rule 只对新 trace 生效，因此历史测试是验证的唯一方式。
16. 对代码评估器，直接对拉取的根级 trace 执行 perform_eval，传入包含 inputs、outputs 和 attachments 键的 dict，以在生产前捕获运行时错误（字段名错误、dict 与对象访问、数据缺失）。
17. 对 LLM 评估器，验证配置：确认 variable_mapping 的键与 prompt 占位符匹配，确认映射的 trace 字段存在，并检查映射的数据是否有意义。
18. 若测试发现错误，在挂载前修复并重建；若用户拒绝测试，则直接挂载。
19. 创建 run rule 将评估器连接到 tracing 项目；将用户命名前缀应用到 display_name；确认评估器出现在评估器列表中且项目挂载正确。
20. 检查：评估器挂载与 run rule 状态；最近的 trace feedback 与分数（来自历史测试或新 trace）；分数是否符合所检查 trace 的预期；边界情况处理（空输出、出错 run、意外结构）。
21. 当评估器崩溃、评分错误或边界情况失败时，修复并重新挂载；在批准前确认评估器评分的是目标质量维度，而非基础设施或数据形状故障。
22. 与用户一起审查：解释评估器名称与 ID、质量维度与评分方式、使用的 trace 字段、采样率及任何限制；询问用户批准、修改、放弃还是选择下一个方向；若继续，复用 trace 发现，再提出一个不同的质量维度。
23. 不变量：每个评估器只负责一个质量维度；不要猜测字段名，实现前必须检查 trace；进行 API 调用前展示配置并获得用户批准；代码评估器必须自包含（仅内置模块和标准库）；代码评估器接收的 run 是普通 dict，使用 run.get("inputs") 和 run.get("outputs")，不要用属性访问；example 参数必须默认为 None；将 API 失败、认证错误和 run rule 失败视为基础设施错误，而非评估器 bug。

适用边界 · 注意事项

• 需要创建 Harbor 风格的在线评估时，应使用 "eval-engineering" 技能，而非本技能。
• 在尚未理解 trace 结构且用户未描述其关注点之前，不要提出评估器方案。
• 在用户选择评估方向之前，不要实现评估器。