---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langsmith
  - evaluation
  - regression-testing
  - rag
  - agents
topic: LangSmith 实验分析、回归比较、外部实验导入与场景化测试
sources:
  - https://docs.langchain.com/langsmith/analyze-an-experiment
  - https://docs.langchain.com/langsmith/chat-evaluation
  - https://docs.langchain.com/langsmith/compare-experiment-results
  - https://docs.langchain.com/langsmith/filter-experiments-ui
  - https://docs.langchain.com/langsmith/fetch-perf-metrics-experiment
  - https://docs.langchain.com/langsmith/upload-existing-experiments
  - https://docs.langchain.com/langsmith/evaluate-chatbot-tutorial
  - https://docs.langchain.com/langsmith/evaluate-rag-tutorial
  - https://docs.langchain.com/langsmith/test-react-agent-pytest
  - https://docs.langchain.com/langsmith/evaluate-complex-agent
  - https://docs.langchain.com/langsmith/run-backtests-new-agent
last_verified: 2026-08-11
---
# 实验分析、回归与场景化测试

## 从分数到可解释结论

Experiment view 不只是平均分表。应依次检查：

1. **完成度**：进度同时包含 target run 与 evaluator run。SDK 实时进度要求 Python LangSmith 0.8.16 以上、TypeScript 0.7.8 以上。
2. **单行证据**：展开 trace、输入、输出、reference、evaluator trace 与 judge prompt；有 repetitions 时回看每次运行，而非只看均值。
3. **切片表现**：按 example metadata 分组，比较分数、延迟、token 和成本。2025-02-20 之前的实验只有 trace 本身带 metadata 时才能这样分组。
4. **基线差异**：固定 baseline/source experiment，确认每个指标是“越高越好”还是“越低越好”，再解释红色回退与绿色提升。
5. **总体约束**：同时审查错误率、尾延迟、成本和关键业务分组，不能用全局平均掩盖高风险长尾。

Compact 适合扫描分数，Full 适合读完整内容，Diff 适合对 reference 或两个版本做文本差异。两个实验时 JSON/YAML 可用 side-by-side diff；比较多于两个实验时，详情面板仍一次只展示两个。

模型、prompt、tool 信息可通过 experiment metadata 的 models、prompts、tools 保留并用于列、过滤和分组。普通 metadata 也可叠加过滤，例如 provider、model、prompt ID 与 feedback 阈值。metadata 是归因依据，应记录真实版本，不应只写“new”或“test”。

## 比较与导出的边界

- 比较视图默认以首先选中的实验为 source，可显式更换；位置随机化属于 pairwise judge 的偏差控制，不等同于这里的 UI source。
- experiment 名称在 workspace 内必须唯一。Playground 的自动名称可以修改，但生产流水线最好生成可追踪且幂等的命名。
- CSV 导出固定包含全部列，不受当前隐藏、排序或过滤影响，且最多 5,000 行。导出前要做数据出域与敏感字段审查。
- read_project / readProject 的 include stats 可取得 p50/p99、首 token 延迟、token、成本、反馈统计和错误率。后端把 tracing project、experiment、session 视为同一底层结构，API 术语可能混用。
- SDK 自动记录的 Git metadata 可能包含远程地址、作者姓名和邮箱；对外分享或导出实验时需要脱敏。

## LangSmith Chat 不是权威评估器

旧的 chat-evaluation 路由已跳转到 LangSmith Chat 的 Evaluation 区域。Chat 可在 experiment、dataset、annotation queue 和 evaluator 页面用自然语言分析数据，也能辅助生成 evaluator 代码；它还可直接修改 Playground 的 messages、tools、schema 与 examples。

这是一种交互式分析助手，不应替代可版本化 evaluator 或发布门：

- 结论必须回到具体 run、trace、feedback 与统计证据验证。
- 模型凭据应配置为 workspace secret；OAuth2 client credentials 则配置在 model configuration。
- Chat 调用从 LangSmith egress IP 发出，受限 provider/proxy 需要显式 allowlist。
- 自定义模型由 workspace admin 决定是否开放给 Chat；生产 workspace 应遵循最小权限。

## 外部实验导入

REST 端点 /datasets/upload-experiment 可把外部系统运行的 experiment 上传到 LangSmith UI。每行包含稳定 UUID、inputs、可选 expected/actual outputs、反馈、时间和 metadata。

关键约束：

- dataset_id 与 dataset_name 至少提供一个，它们表示**外部系统标识**；相同标识用于把多次 experiment 归到同一 dataset。
- 该入口只能继续写入由它创建的 externally managed dataset，不能向普通 LangSmith dataset 注入外部实验。
- 每行 start/end 必须落在 experiment start/end 内；调用方需自行校验时区和顺序。
- 写入是最终一致的，刚返回时 latency 与 feedback stats 可能为空；token/cost 若请求没有提供，也不会凭空补齐。
- API key 必须服务端注入；row_id、experiment name 和重试要做幂等控制，避免重复实验或重复行。

## Chatbot：从小型黄金集开始

手工标注约 10–20 个代表样本即可启动，10–50 个覆盖常见边界往往已能产生价值；之后持续把真实失败补入 living dataset。不要等待“大而全”才开始，也不要用大量同质合成样本制造虚假信心。

教程组合了：

- reference-aware 的语义 correctness judge；
- 确定性的长度/简洁性检查；
- 多模型、多 prompt experiment；
- UI 对比；
- CI 中的最低通过率断言；
- 长期趋势和 Git 版本关联。

发布门应对关键确定性规则直接 assert，对主观质量设置统计阈值和容差。教程中的“80% 长度检查”只是示例，不是通用 SLA。

## RAG：四个正交指标

| 指标 | 比较对象 | 是否需要 reference | 能回答的问题 |
|---|---|---|---|
| Correctness | response 对 reference answer | 是 | 最终事实是否正确 |
| Relevance | response 对 user input | 否 | 是否回答了问题 |
| Groundedness | response 对 retrieved docs | 否 | 输出是否被上下文支持 |
| Retrieval relevance | retrieved docs 对 user input | 否 | 检索是否找对资料 |

四者不能互相替代：检索相关不代表回答正确，回答相关不代表有依据，grounded 也可能忠实于错误资料。target 必须返回 answer 和 documents，evaluator 的字段契约应固定。

教程的 TypeScript RAG prompt 明确要求把检索文档当数据并忽略其中指令，Python 片段没有同等约束。生产实现无论语言都必须防 prompt injection，并限制抓取来源、响应大小、超时、MIME 和网络出口。网页抓取 + 内存向量库仅是教学实现，不代表生产索引、许可或新鲜度方案。

## Agent：按失败定位能力分层测试

ReAct 教程把测试拆成四层：

1. off-topic 输入不应调用工具；
2. 简单任务检查工具名和关键参数；
3. 多步骤任务运行完整 agent，检查必需工具、结构化最终值、数值容差与步骤数；
4. 让 judge 检查答案是否被搜索结果支持，并把 evaluator trace 与主 agent trace 分离。

Python pytest 示例要求 LangSmith 0.3.1 以上；当前总览页对 pytest 集成要求更高的 0.3.4，应按更高版本执行。教程使用的 langchain-community 与 @langchain/community 已标注停止维护，不能照搬到新项目。

复杂 agent 教程进一步展示三种粒度：

- **最终响应**：最接近用户结果，但定位能力弱；
- **轨迹**：按期望节点/工具的子序列给部分分，适合复杂路径；
- **单节点**：直接调用 router 等节点，快速定位局部逻辑。

示例 refund 通过删除 SQLite 记录模拟退款，明确跳过认证，并依赖 config 中 env=test 避免真实删除。它只能说明测试结构：生产评估必须使用隔离数据库、最小权限凭据、事务回滚或不可变 fixture；不能把一个可伪造的运行参数当作唯一副作用保护。

## Backtest：历史流量不是天然真值

Backtest 的流程是：从生产 project 过滤代表性 runs → 把 inputs 变成 dataset → 把历史 outputs 变成 baseline experiment → 用新系统跑同一 dataset → 使用 reference-free 或人工标注指标比较。相关转换教程要求 LangSmith 0.2.4 以上。

历史输出只是“当前线上行为”，不是 ground truth。回流前应：

- 按时间、用户场景、失败类型分层采样，避免只取容易样本；
- 脱敏输入、输出、tool result 和 metadata；
- 保存生产版本、采样查询和 dataset version；
- 有用户反馈时优先转成 label，无 label 时保留人工抽审；
- 检查数据漂移和时间泄漏。

教程的模型升级案例说明：更强模型提高格式遵循，却降低了对搜索结果的 groundedness。升级模型、prompt 或架构都必须按多指标和关键切片比较，不能根据单一榜单能力直接发布。

## 生产发布门

一套可复现的发布判断至少固定：

- dataset version/split、target commit、prompt/model/tool 版本；
- evaluator prompt/code 版本与 metric 方向；
- repetitions、concurrency、cache、随机化和失败策略；
- baseline、关键 metadata 切片及样本量；
- correctness/安全硬门、质量统计门、p99/成本预算；
- 回退样本的 trace 证据与人工复核结论。

只有在“总体不退化 + 高风险切片通过 + 成本延迟可接受 + 失败样本可解释”同时成立时，experiment 才能支撑发布决策。