---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langsmith
  - evaluation
  - langgraph
  - agents
topic: LangSmith target function、Graph、中间步骤与 Agent 轨迹评估
sources:
  - https://docs.langchain.com/langsmith/evaluate-llm-application
  - https://docs.langchain.com/langsmith/evaluate-with-opentelemetry
  - https://docs.langchain.com/langsmith/playground-link
  - https://docs.langchain.com/langsmith/run-evals-api-only
  - https://docs.langchain.com/langsmith/define-target-function
  - https://docs.langchain.com/langsmith/evaluate-on-intermediate-steps
  - https://docs.langchain.com/langsmith/langchain-runnable
  - https://docs.langchain.com/langsmith/evaluate-graph
  - https://docs.langchain.com/langsmith/multi-turn-simulation
  - https://docs.langchain.com/langsmith/trajectory-evals
last_verified: 2026-08-11
---
# Target、Graph 与 Agent 轨迹评估

## Target function 契约

`evaluate()` 的 target 接收一个 Example 的 `inputs`，返回应用输出字典；evaluator 必须与该输出结构一致。target 内的 traceable 调用会成为根 target trace 的 child runs，因此既能评最终输出，也能访问内部步骤。单个模型调用、非 LLM 组件、完整应用、LangChain Runnable 和已编译 LangGraph graph 都可以成为 target。

Python 大任务优先 `aevaluate()`；JavaScript/TypeScript 的 `evaluate()` 本身已经是 async。Graph 只要包含 async node，Python 必须使用 `aevaluate()`。元数据中的保留键 `models`、`prompts`、`tools` 会填充 experiment 专用列，便于分组与过滤，但应写真实版本/标识，不能把它们当自由文本备注。

## 三种运行入口

| 入口 | 适合 | 代价 |
|---|---|---|
| SDK | 常规自动化、CI、大批量实验 | 功能最完整，需引入 SDK |
| Playground | 无代码比较 prompt/model | dataset input key 必须匹配 prompt variables；最多 15 个输入变量 |
| REST API | 非 Python/TS 或受限环境 | 需自行创建 dataset、project/run、关联 example、上传 feedback 和处理重试 |

SDK 是官方推荐入口，包含更多性能与可靠性处理。Playground 跑实验前建议先提交 prompt 版本，否则之后难以复现实验。REST 只是不便使用 SDK 时的协议级替代，不应遗漏幂等、分页、轮询、部分失败与限流控制。

## OpenTelemetry 应用接入

已经使用 OTel 的应用可以绕开 `evaluate()`：创建关联 dataset 的 experiment session，把 traces 发往 LangSmith，并给根 span 设置：

- `langsmith.trace.session_id`：路由到 experiment；
- `langsmith.reference_example_id`：关联具体 Example；
- `langsmith.span.kind`：标识 chain/model/tool 等类型；
- `inputs` / `outputs`：记录 target 输入输出。

自托管 OTLP endpoint 使用实例地址并追加 `/api/v1/otel`。experiment/session 与 example ID 若漏传或错传，trace 即使可见也不能成为正确的评估行。2026-02 文档示例中 Strands TypeScript SDK 尚不支持该 OTel observability 路径，这是示例集成限制，不是 OTel 协议本身的能力判断。

## 中间步骤与 Graph

RAG 等流水线应分别评 retrieval 和 generation。自定义 evaluator 可遍历 `run`/`rootRun` 读取 child runs；相关示例要求 `langsmith>=0.3.13`。如果 Graph state 已保存 messages、工具结果或决策，优先直接从最终 state 评估；只有 state 不含所需证据时才下钻 trace，减少对内部 span 命名的脆弱耦合。

Graph 有三种测试粒度：

1. 端到端调用整个 graph，判断最终 state；
2. 从 state 或 Run 检查中间节点/工具调用；
3. 直接调用单个 node，降低运行时间和模型费用。

端到端不能替代节点测试，节点测试也不能证明 routing、checkpoint、并发与恢复路径正确。

## Multi-turn simulation

OpenEvals simulator 在 simulated user 与 app 间轮流传递单条 chat message。app 接收 message 与 `thread_id`，并按 thread 维护历史；运行到 `max_turns` 或自定义 stopping condition，返回完整 trajectory。模拟的优势是低成本覆盖上下文丢失、重复行为和长对话失败，缺点是表面面积更大、可重复性比固定单轮 dataset 低。

使用 pytest/Vitest/Jest 时通过 trajectory evaluators 在对话结束后评分；使用 `evaluate()` 时把 simulation 放入 target，target 输出完整 trajectory。persona 可以作为 dataset 字段逐例变化；固定初始 response 和随机种子/模型参数有助于重现。

## Trajectory match

AgentEvals 支持四种匹配：

| 模式 | 语义 | 适合 |
|---|---|---|
| strict | 消息和工具调用顺序完全一致 | 授权前必须查策略等强顺序流程 |
| unordered | 同一组工具，顺序不限 | 可并行或顺序无关的检索 |
| subset | 实际工具只能来自 reference | 防止越权与无关工具调用 |
| superset | 至少包含 reference 工具，可有额外调用 | 验证最低必需动作 |

默认工具相等还要求参数相同，可用 match mode/override 调整。路径存在多种正确解时，用 LLM-as-judge 按效率、合理性和 rubric 判断，可选 reference trajectory；代价是更慢、更贵且非确定。高风险动作仍应保留确定性 policy/argument 检查，不能只靠 judge。