LangChain 测试、评测与升级清单
本节目标
为 LCEL、工具 Agent、RAG 和 LangGraph 建立分层验证；用数据而不是演示决定模型或框架改动；按可回退流程升级快速变化的包和提供商集成。
“能 invoke”只是第一层
框架项目至少有七类证据：
- 纯函数与 schema：解析、切分、路由、参数、状态 reducer。
- 工具执行：授权、超时、错误分类、幂等、结果大小和脱敏。
- 节点与图：状态更新、边、循环上限、interrupt 和终态。
- 模型行为：结构化输出、工具选择、拒答和引用，允许合理表达变化。
- RAG 分层：解析、chunk、召回、排序、生成支持度和权限过滤。
- 恢复与兼容：旧 checkpoint、重复事件、提交后崩溃、模型/Prompt/工具版本变化。
- 系统指标：端到端成功率、p95/p99、token/费用、人工接管和安全违规。
单元测试适合确定性合同；模型行为需要固定数据集、多次 trial 和统计。不要用一次聊天截图证明回归通过。
测试替身怎么选
- 纯节点测试使用普通函数或确定性 fake，定位状态逻辑。
- Agent 循环使用会固定产生工具调用/错误的模型桩，验证执行器和预算。
- 提供商集成保留少量真实 API smoke test，明确需要凭据且控制费用。
- 质量评测使用代表真实分布的数据集，不把训练 Prompt 的样本全部当最终验证集。
- 高风险工具使用 mock 服务验证授权、幂等和故障，不向真实用户发送内容。
Mock 全绿只证明本地合同；真实模型 smoke 全绿只证明当时能调用。两类证据不能互相替代。
LangGraph 的测试层次
官方测试指南建议节点尽量成为可独立调用的纯函数；也可编译单节点图测试运行时行为。需要从图中间开始时，可用测试 checkpointer、update_state(..., as_node=...) 和相同 thread ID 构造暂停状态。
每条关键路径至少测试：
- 正常完成与无答案/业务拒绝；
- 条件边所有枚举及未知值安全默认；
- 循环达到完成、失败、预算和 deadline；
- interrupt 暂停、批准、编辑、拒绝、过期和错误 thread ID；
- 节点恢复时 interrupt 前代码重跑；
- 同一副作用提交后崩溃不会重复；
- 旧 state schema 和图版本能迁移或明确拒绝。
InMemorySaver 适合测试，不证明数据库 checkpointer 的并发、备份或访问控制。
相邻 Layer B 项目用 scripted model 在真实 create_agent 中验证消息、工具分派和 schema-error 合同；它不证明 provider schema 转换或真实模型质量。Layer C 再用 SQLite saver 验证跨进程恢复，并在应用层拒绝未知、owner 错配、已完成、未暂停、版本不兼容或状态不一致的 thread。它们都不证明生产数据库的多 worker 并发、灾备或外部副作用 exactly-once。
Agent 评测记录什么
一个 eval case 至少有任务、输入文件、环境夹具、允许工具、期望 outcome 和机械断言。一次 trial 记录：
- 是否完成真实任务，而非模型自称完成；
- 工具名、参数、顺序、次数、错误恢复和越权尝试；
- 最终环境状态与引用证据；
- 模型、Prompt、工具、数据和依赖版本；
- token、费用、时延和人工介入。
对非确定模型重复运行，报告均值、分布与失败类型。把调参集和锁定验证集分开，避免把描述或 Prompt 调成只记住测试题。
当前版本快照如何使用
2026-07-22 从 PyPI 核对到：
| 包 | 当前发布 | 发布日期 | 课程用途 |
|---|---|---|---|
langchain | 1.3.14 | 2026-07-16 | 高层 Agent API |
langgraph | 1.2.9 | 2026-07-10 | 有状态图运行时 |
langchain-core | 1.5.0 | 2026-07-21 | Runnable、消息、工具等基础抽象 |
这些是资料快照，不是让学习者在生产项目的 requirements 中手工组合三个精确版本。安装 langchain 与所需集成包，让解析器选择兼容依赖，随后保存完整锁文件和运行证据。第 10 节为教学级隔离 harness 有意固定旧但已验证的 langchain-core==1.4.9，并在运行前失败关闭地核验版本；它是可重复的最小 runtime 合同，不是可替代解析器和 lockfile 的项目安装方式。升级时重新核对，而不是把此表永久当“最新”。
安全升级流程
- 保存当前锁文件、Python 版本、关键配置和通过的 eval 报告。
- 在新 venv 复制生产依赖，不原地覆盖唯一可工作环境。
- 阅读官方 release notes、版本策略和迁移指南；检查 yanked 版本与 provider 包。
- 一次升级一个依赖族，记录解析后的完整版本，而非只写顶层包。
- 运行导入、静态检查、无密钥 LCEL、离线工具和全部单元测试。
- 运行图恢复/旧 checkpoint、工具 schema 快照和 RAG 索引兼容测试。
- 使用受控凭据运行少量提供商集成与锁定质量集；记录费用和区域。
- 灰度发布新实例；运行中的旧实例固定兼容 worker 或使用已验证迁移。
- 以任务成功、安全、p95、费用和人工接管门槛决定继续或回退。
代码回滚不能撤销已经发送的邮件、执行的 SQL 或写入的外部系统；高风险发布还要准备对账和补偿。
常见升级陷阱
- 只看
pip install成功，不看解析出的 transitive versions。 - 把旧
LLMChain示例改到能导入，就声称已完成 v1 迁移。 - tool schema 或消息 content blocks 改变，却没有快照/合同测试。
- 新模型结构化输出更稳定，但事实质量或费用退化未被发现。
- 新 worker 恢复旧 checkpoint 时改变路由或重复副作用。
- provider 包支持的参数与统一接口说明不一致，却没有真实集成测试。
综合练习
为一个“检索政策并在批准后创建工单”的项目写升级验收矩阵，至少 20 条：
- 5 条确定性工具和 schema；
- 5 条检索与引用；
- 4 条审批和恢复；
- 3 条安全/权限；
- 3 条真实模型质量与成本。
然后设计从旧版本到新版本的灰度、回退、旧实例处理和外部副作用对账步骤。
掌握标准
- 能区分单元、合同、图、模型、RAG、恢复和系统测试。
- 能让 eval 判断环境 outcome，而非只看最终自然语言。
- 能解释 fake 与真实提供商 smoke test 各自能证明什么。
- 能在新 venv 按锁文件升级并保留可回退环境。
- 能为旧 checkpoint、tool schema 和 RAG 索引写兼容验收。
回到目录
返回 LangChain 学习路线，再按项目需要查阅官方参考层。
资料基线
官方事实与包版本核对日期：2026-07-22。