---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - python
  - testing
  - observability
  - deployment
  - migration
topic: LangChain Python 生产化、测试、可观测性与迁移
sources:
  - https://docs.langchain.com/oss/python/langchain/changelog-py.md
  - https://docs.langchain.com/oss/python/langchain/deploy.md
  - https://docs.langchain.com/oss/python/langchain/get-help.md
  - https://docs.langchain.com/oss/python/langchain/observability.md
  - https://docs.langchain.com/oss/python/langchain/studio.md
  - https://docs.langchain.com/oss/python/langchain/test
  - https://docs.langchain.com/oss/python/langchain/test/evals.md
  - https://docs.langchain.com/oss/python/langchain/test/index.md
  - https://docs.langchain.com/oss/python/langchain/test/integration-testing.md
  - https://docs.langchain.com/oss/python/langchain/test/unit-testing.md
  - https://docs.langchain.com/oss/python/langchain/ui.md
  - https://docs.langchain.com/oss/python/langchain/voice-agent.md
last_verified: 2026-08-11
---
# 生产化、测试、可观测性与迁移

> `/test` 是 unit、integration、evals 三条测试路径的聚合入口；与 `/test/index` 内容同源但属于独立可点击路由。

## 生产闭环

一个“能回答问题”的 agent 还不是生产系统。完整闭环至少包括：

> 本地可视化调试 → 单元/集成/轨迹评估 → 部署与持久运行 → trace/指标/告警 → 线上样本回流评估 → 受控升级与回滚

模型不确定性不会降低传统工程要求，反而要求把结构断言、执行轨迹、权限、副作用和恢复能力分层验证。

## 本地开发与 Studio

LangSmith Studio 是连接本地 Agent Server 的可视化调试界面，可查看 prompt、tool args/results、state、异常、token 和 latency，并从历史步骤重跑。

当前 Python setup 边界：

- `langgraph-cli[inmem]` 的本地 Studio 流程要求 **Python 3.11+**；这比 `langchain` 核心包的 Python 3.10+ 更严格。
- `create_agent` 返回 compiled LangGraph graph，可直接在 `langgraph.json` 的 `graphs` 中指向 `module:agent`。
- `langgraph dev` 默认在 `127.0.0.1:2024` 启动；Safari 对 Studio 访问 localhost 有限制，文档建议 `--tunnel`。
- Studio 需要 LangSmith 凭证建立连接；若不希望本地数据被 trace，显式设 `LANGSMITH_TRACING=false`。`.env` 不能进版本控制。

热重载和从中间步骤重跑适合开发诊断，但不能替代持久数据库、真实网络、并发和部署环境验证。

## 可观测性

LangChain agent 原生支持 LangSmith tracing。开启后，一条 trace 覆盖用户输入、每次模型调用、工具、决策点和最终输出。可通过环境配置全局开启，也可用 `tracing_context` 只 trace 指定操作，并用 project、tags、metadata 划分版本和环境。

生产 trace 设计建议：

- 用稳定的 app/model/prompt/tool 版本标签支持回归对比；
- 记录延迟、token、重试、工具错误、interrupt 等可操作指标；
- user/session 标识应使用受控、可脱敏标识，不记录凭证、完整 PII、原始敏感工具结果；
- trace 采样、保留期和访问权限按数据等级设置；
- 观测数据用于定位失败模式，不能只看平均响应时间。

## 测试金字塔

### 1. 单元测试

用 `GenericFakeChatModel` 依次返回预设文本、tool call 或错误，验证确定性逻辑；用 `InMemorySaver` 验证 thread 内 state/checkpoint 行为。适合：

- tool schema、输入校验和错误转换；
- middleware hook、顺序、jump、retry/fallback；
- state reducer、结构化输出解析和权限分支；
- 固定 tool-call/result 关联。

它不验证 provider schema 兼容性、真实模型选择工具的能力、网络与延迟。

### 2. 集成测试

真实模型/API 测试应与 unit tests 分开，以 pytest marker 显式运行；凭证从环境/CI secrets 注入，缺少时 skip。由于输出非确定性，断言 message/tool 类型、tool name、参数结构、状态和约束，不断言完整自然语言字符串。

控制成本和波动：选小模型、限制 max tokens、每个测试只覆盖一个行为、只在 CI/预发布运行。用 VCR/pytest-recording 重放 HTTP 时必须过滤 Authorization、API key 和 query secret；prompt/tool/预期轨迹变化会使 cassette 过期，应重新录制并审查内容。

### 3. Agent eval

AgentEvals 评估的是完整 trajectory，而不只是最终文本：

| 匹配模式 | 含义 | 适用 |
|---|---|---|
| strict | 消息结构和工具顺序严格一致 | 必须先查政策再授权等顺序约束 |
| unordered | 所需工具相同但顺序不限 | 可并行、顺序无关的检索 |
| subset | 实际工具不能超出 reference | 限制 agent 行为范围 |
| superset | 至少执行 reference 要求工具 | 验证最低必需动作，允许额外步骤 |

LLM-as-judge 可按 rubric 判断定性轨迹，不一定需要 reference，但自身也有模型偏差、费用和漂移；高风险规则优先确定性 evaluator，开放质量再叠加 judge。异步 evaluator 有对应 async factory。LangSmith 可在 pytest 或 experiment 中记录数据集、输出、reference 和评分，长期比较 prompt/model/tool 版本。

## 部署

官方快速路径是把 LangGraph-compatible agent 放在 GitHub 仓库，部署到 LangSmith Cloud，再从 Studio 测试并通过 deployment API/SDK 访问。Cloud 提供 stateful、long-running agent 的托管基础设施；另有 hybrid、standalone server 和 self-hosted control plane，选择取决于数据驻留、网络、合规、团队运维能力和成本。

部署前最少确认：

- 生产 checkpointer/store、备份、迁移与恢复；
- 工具出网、文件系统、sandbox、数据库账号的最小权限；
- request/run/node/tool timeout，有限重试、幂等和 graceful shutdown；
- queue/concurrency、模型/工具 rate limit、费用上限与租户隔离；
- HITL 恢复、webhook/外部副作用幂等、审计；
- readiness、health、metrics、trace sampling、告警与回滚版本。

部署教程展示的是接入路径，不是完整生产验收清单；约 15 分钟等时间描述也只是页面当时的经验值。

## Agent Chat UI

开源 Agent Chat UI 是可快速连接本地或 deployed agent 的 Next.js 客户端，内建实时 chat、tool visualization、interrupt thread、time travel/state fork。Hosted UI 适合验证协议；自托管/定制时通过 graph ID、deployment URL 连接。它能减少基础 UI 开发，但鉴权、数据暴露、品牌、accessibility 与业务审批仍由应用负责。

## Voice agent 架构

两条生产路线：

| 架构 | 优点 | 代价 |
|---|---|---|
| STT → text agent → TTS（sandwich） | 组件可替换、最新文本模型能力、边界可观察可控制 | 多服务编排、音频转文字会损失语气信息 |
| Native speech-to-speech | 链路短、简单交互通常延迟低、保留语音细节 | provider/model 选择少、锁定强、可解释和定制较弱 |

官方教程选择 sandwich，以浏览器与 Python server 间 WebSocket、async generators 串起音频输入、STT transcript、LangChain token stream 与 TTS audio chunks。页面提到特定 provider 可做到 sub-700ms，这是特定实现的目标/示例，不是普遍 SLA。生产还需处理 VAD、打断/barge-in、背压、会话取消、音频隐私、重连、语言与无障碍文本回退。

## 版本与迁移观察

`changelog-py.md` 当前重定向到 canonical `/oss/python/releases/changelog.md`。当前页面覆盖 v1.0 以来的重要变化：

- **LangChain v1.0**：高层 chains/agents 收敛为 LangGraph 上的 agent；旧能力迁至 `langchain-classic`；迁移需查专用 guide。
- **v1.1**：model profiles、profile-aware summarization、ProviderStrategy 推断、SystemMessage prompt、ModelRetryMiddleware。
- **v1.2**：tool `extras` 承载 provider-specific tool 配置，structured output strict schema。
- **v1.3**：agent 支持 `stream_events`/`astream_events` 的 `version="v3"` typed projections。
- 同期 LangGraph 1.1 引入 opt-in v2 typed invoke/stream；1.2 加入 node timeout/error handler/graceful shutdown、DeltaChannel 和 v3 event stream。不要把 LangChain、LangGraph、Deep Agents 的版本号当成同一序列。

升级策略：锁定 direct dependencies → 阅读目标版本 release/migration guide → 先跑 unit/integration/evals → 对 streaming、state/checkpoint、tool schema、structured output 和 middleware 顺序做契约回归 → 灰度 → 保留回滚。订阅 changelog RSS 比偶尔浏览更适合持续维护。

## 求助与权威来源

排查顺序建议：当前版本 API Reference/官方 docs → changelog/migration guide → GitHub issue → Community Forum/Slack；企业关键问题使用 support portal，并通过 LangSmith status 区分平台故障。提问时提供最小复现、包版本、trace/错误类型和已脱敏配置，不公开凭证或业务数据。

## 逐页覆盖索引

| 页面 | 学习结论 |
|---|---|
| Deployment | LangSmith Cloud GitHub 部署、Studio 验证、deployment URL 与 SDK 访问；其他托管模式另选。 |
| Observability | 自动 tracing、selective context、project、tags 和 metadata。 |
| Studio | CLI、本地 Agent Server、`langgraph.json`、hot reload、state/tool/trace 调试。 |
| Test overview | unit、integration、trajectory eval 的职责与 agent 更依赖集成测试的原因。 |
| Unit testing | `GenericFakeChatModel` 与 `InMemorySaver` 的确定性测试。 |
| Integration testing | pytest marker、凭证管理、结构断言、成本控制、VCR 脱敏与 cassette 更新。 |
| Agent evals | strict/unordered/subset/superset trajectory match、LLM judge、async 与 LangSmith experiment。 |
| Agent Chat UI | hosted/local Next.js UI、graph/deployment 连接、tool/interrupt/time-travel 支持。 |
| Voice agent | sandwich 与 S2S 架构，WebSocket + async streaming 的 STT-agent-TTS 实现。 |
| Get help | Chat LangChain/API reference、Forum/Slack、support/status、贡献和更新渠道。 |
| Changelog | alias 重定向后的 v1.0–v1.3、LangGraph/Deep Agents 同期变化、RSS 与迁移边界。 |

## 上线前验收

- [ ] 单元、真实 provider 集成、关键 trajectory eval 均有基线。
- [ ] 数据库/工具/文件系统/网络权限最小化，所有副作用具备幂等与审批策略。
- [ ] checkpointer/store 在真实后端完成迁移、恢复、并发与容量验证。
- [ ] tracing/日志已脱敏，并具备费用、错误率、延迟、重试和异常轨迹告警。
- [ ] streaming/HITL/rejoin/checkpoint 在断网、重启、超时和取消下可恢复。
- [ ] 版本锁、迁移说明、灰度与回滚路径明确。

## 延伸

- [[01-Overview-and-Setup]]
- [[04-Middleware-Context-and-Runtime]]
- [[06-Frontend-and-Generative-UI]]