用途
LangSmith Evaluators 用于为 LangSmith 构建评估流水线（evaluation pipelines）。技能覆盖三个核心组成部分：（1）创建评估器，包括 LLM-as-Judge 与自定义代码；（2）运行函数与轨迹捕获；（3）评估器的上传与运行。
核心准则：先检查再实现
技能明确要求：在编写任何评估器或抽取逻辑之前，必须先运行智能体并捕获实际输出，检查输出（打印、查询 LangSmith trace、理解确切结构），之后才编写处理该输出的代码。输出的结构会因框架、智能体类型和配置而有显著差异，绝不能假设其形状，务必先验证。当输出不含所需数据时，查询 LangSmith trace 来理解如何从执行中抽取。
评估器类型与格式
评估器分为两种：
- 离线评估器（绑定数据集）：函数签名为 (run, example)，同时接收运行输出和数据集中样例，用于将智能体输出与数据集中的期望值对比，通过
--dataset "Dataset Name"上传。 - 在线评估器（绑定项目）：函数签名为 (run)，只接收运行输出，没有 example 参数，用于生产运行的实时质量检查（无参照数据），通过
--project "Project Name"上传。
返回格式为 {"score": value, "comment": "..."}，指标键名由函数名自动派生。每个评估器只返回一个指标，需要多个指标就创建多个评估器函数。不得返回 {"metric_name": value} 或指标列表。
Python 中需注意本地与上传的差异：本地 evaluate() 的 run 是 RunTree 对象，用 run.outputs；上传到 LangSmith 后 run 是 dict，用 run["outputs"]。二者兼容写法为 run.outputs if hasattr(run, "outputs") else run.get("outputs", {})。TypeScript 始终使用属性访问：run.outputs?.field。
评估器种类
LLM as Judge：用 LLM 给输出打分，适合主观质量评估（准确性、有用性、相关性）。
自定义代码评估器：确定性逻辑，适合客观检查（精确匹配、轨迹校验、格式合规）。
脚本目前仅支持代码评估器，LLM-as-Judge 上传暂不支持。针对数据集的评估，技能强烈建议先定义本地评估器并与 evaluate(evaluators=[...]) 配合使用。
运行函数与轨迹捕获
运行函数负责执行智能体并返回供评估的输出。技能要求在编写评估器前必须先测试运行函数并检查实际输出结构，调试流程为：在样例输入上运行智能体一次；查询 trace 查看执行结构；打印原始输出并与 trace 核对；按需调整运行函数；验证输出与数据集 schema 匹配。应尽量让运行函数输出匹配数据集 schema，便于写出简单、可复用的评估器。
轨迹评估要求运行函数在执行过程中捕获工具调用。LangGraph 智能体（LangChain OSS）使用 stream_mode="debug" 与 subgraphs=True 来捕获嵌套子智能体的工具调用。对于自定义/非 LangChain 智能体，先检查输出是否已包含轨迹数据（如 result.tool_calls、result.steps），若框架支持执行回调则注册钩子记录工具名，最后才考虑从结构化日志或 trace 数据中解析。关键是在执行时而非定义时捕获工具名。
使用方式
上传到数据集的评估器在运行实验时会自动执行，无需传给 evaluate()。上传的评估器出于安全原因只有非常有限的包访问权限，仅依赖标准 Python/JavaScript 功能（如内置包）时方可上传；数据集（离线）评估器优先本地用 evaluate(evaluators=[...]) 运行，以获得完整包访问权限。
命令行示例（Python）：list 列出全部评估器；upload 上传离线或在线评估器，需指定 --dataset 或 --project 之一，全局评估器不支持；delete 删除。JavaScript 使用 npx tsx upload_evaluators.ts 执行相同操作。
脚本在破坏性操作前会提示确认，除非用户明确要求，绝不使用 --yes 标志。
运行评估
上传的评估器在运行实验时自动运行；本地评估器直接传入以用于开发测试。示例：from langsmith import evaluate; results = evaluate(run_agent, data="My Dataset", experiment_prefix="eval-v1")。
最佳实践与常见问题
- LLM 评判使用结构化输出，比解析自由文本更可靠。
- 按数据集类型匹配评估器：最终响应 → LLM as Judge 评质量；轨迹 → 自定义代码评序列。
- LLM 评判使用 async 以支持并行评估。
- 独立测试评估器，先用已知好/坏样例验证。
- 语言选择：Python 用于 Python 智能体与 langchain 集成；JavaScript 用于 TypeScript/Node.js 智能体。
常见问题：输出不符合预期时查询 LangSmith trace 查看每步确切的输入/输出；每个评估器只返回一个指标；字段名不匹配时确保运行函数输出与数据集 schema 完全一致，先用 client.read_example(example_id) 检查数据集；Python 中本地与上传的 run 类型不同，需兼容处理。
依赖与配置
环境变量：LANGSMITH_API_KEY（必需）、LANGSMITH_WORKSPACE_ID（可选，用于组织级密钥）、OPENAI_API_KEY（LLM as Judge 所需）。Python 依赖：pip install langsmith langchain-openai python-dotenv。JavaScript 依赖：npm install langsmith commander chalk cli-table3 dotenv openai。
限制
脚本目前不支持 LLM-as-Judge 评估器的上传，仅支持代码评估器；上传评估器包访问权限受限；必须指定 --dataset 或 --project，不支持全局评估器。