LangGraph（Agent 编排）学习路线图：步骤 · 方式 · 检查点

定制日期：2026-11-10 ｜ 针对环境：Windows 10 + Git Bash + i7-8550U/16GB/无独显 姊妹篇（概念详解与代码示例）：LangGraph（Agent 编排）.md 总时长：6 周，每天 1.5-2 小时（每天都能看到可运行成果，无枯坐读文档环节）

〇、学习前 10 分钟决策（开始前必须定好的三件事）

决策 1：模型供给 ✅ 已定：硅基流动（SiliconFlow），key 已验证可用（2026-11-10）

已完成的配置（2026-11-10）： - 环境变量已写入：SILICONFLOW_API_KEY（新开终端生效） - ⚠️ 该 key 曾在对话中明文出现，尽快到硅基流动后台「API 密钥」重置一个新 key，然后只改环境变量一处 - 推荐模型（先看官网价格页选便宜的）：学习用 Qwen/Qwen3.5-4B；质量验收用 deepseek-ai/DeepSeek-V3.2 或 zai-org/GLM-5.3

接入代码模板（学习文档中所有示例统一改用这个写法）：

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="Qwen/Qwen3.5-4B",                     # 学习用；验收时换 deepseek-ai/DeepSeek-V3.2
    api_key=os.environ["SILICONFLOW_API_KEY"],
    base_url="https://api.siliconflow.cn/v1",
    temperature=0,
)
# 用法：create_agent(model=llm, tools=..., ...)；自定义图里直接 llm.invoke(...)

注意：硅基流动是 OpenAI 兼容协议，所以不需要 init_chat_model("deepseek-chat") 这种写法，直接传 llm 实例即可。

决策 2：开发工具

• 编辑器：VS Code + Python 扩展 + LangGraph Studio 插件（langgraph-cli[inmem] 自带，看图执行是学习加速器）
• Python：3.11+（python --version 确认；没有就用 winget install Python.Python.3.12）
• 笔记：每学完一节，在 doc/学习笔记/LangGraph/ 下写一篇"我学到了什么+踩了什么坑"（费曼式输出，第 6 周回看会发现自己进步惊人）

决策 3：成功标准（6 周后你应该能）

1. 白板手写一个带条件边和检查点的状态图
2. 给 Agent 加"危险操作人工审批"并演示断点续跑
3. 搭出 Supervisor 双智能体协作
4. 交付一个真实可用的知识库问答 Agent（第 5-6 周实战）

一、阶段 0：环境搭建（第 1 天，约 1 小时）

# 1. 项目目录（在 E 盘，空间充足）
mkdir -p /e/zcode/DeepTraining/langgraph-learn && cd /e/zcode/DeepTraining/langgraph-learn

# 2. 虚拟环境（隔离依赖）
python -m venv .venv
source .venv/Scripts/activate          # Git Bash 写法；cmd 用 .venv\Scripts\activate.bat

# 3. 安装全家桶（清华镜像加速）
pip install -U langgraph langchain langchain-openai langchain-ollama \
  "langgraph-cli[inmem]" -i https://pypi.tuna.tsinghua.edu.cn/simple

# 4. 本地模型（备用，约 1.2GB，下载后断网也能跑；不急可跳过）
ollama pull qwen3:1.7b

# 5. 环境变量（key 不进代码！）——已于 2026-11-10 配置硅基流动 key
setx SILICONFLOW_API_KEY "你的key"     # 新开终端生效

# 6. 验证安装 + 验证 key（新开终端后执行）
python -c "import langgraph; print(langgraph.__version__)"
curl -s https://api.siliconflow.cn/v1/models -H "Authorization: Bearer $SILICONFLOW_API_KEY" | head -c 200

✅ 过关检查点 0：langgraph dev 能启动并在浏览器打开 Studio 空白页；ollama run qwen3:1.7b 能对话。

坑速查：Git Bash 激活 venv 用 source .venv/Scripts/activate；langgraph dev 默认端口 2024，防火墙拦截就放行。

二、阶段 1（第 1 周）：建立"图"的心智模型

本周目标：彻底理解 State → Node → Edge → Reducer 四件套。所有练习用 Ollama（不耗赠金）。

Day 1：跑通第一个工具 Agent（高层 API）

• 读：官方文档 create_agent 一节（15 分钟）
• 做：跑 姊妹篇第九节示例 A，模型按「决策 1」的硅基流动模板接入（ChatOpenAI + base_url），然后改 3 次：①换 model="Qwen/Qwen3.5-4B" ↔ "deepseek-ai/DeepSeek-V3.2" 观察工具调用差异 ②加第二个工具 ③改 system_prompt 观察行为变化
• 改示例比看示例重要 10 倍——每改一次都要预测输出再对照

Day 2：手写最小 StateGraph（低层 API）

# 练习：不查资料，写出"写诗 → 审诗 → 通过/重写"的图
# 状态：messages + draft(当前诗) + revisions(重写次数)
# 节点：poet(写) / critic(审) ；条件边：revisions >= 3 或 critic 通过 → END

卡住就看文档 Low Level: StateGraph 一节，但先尝试 20 分钟再看。

Day 3：Reducer 深挖

• 实验：把 Annotated[list, add_messages] 改成普通 list，让两个节点都返回 messages，观察覆盖 vs 追加的差异（这是最多人栽的坑）
• 做一个自定义 reducer：def merge_dicts(a, b): return {**a, **b}

Day 4：条件边 + 循环

• 练习：ReAct 风格循环（agent ⇄ tools）自己手写一遍（不要用 create_agent！）——这是理解 Agent 本质的必经之路
• 工具随便造两个：@tool def get_weather(city)、@tool def calculator(expr)

Day 5：Streaming 四种模式

• 对同一个图分别用 values / updates / messages / custom 四种 stream_mode 打印，用纸笔记下每种输出的形状差异

Day 6-7：小测 + 笔记

• 综合练习：写一个"数学解题 Agent"：解析题目 → 判断是否需要计算器 → 循环调用 → 最终给答案。要求：手写 StateGraph、至少 1 个自定义 Reducer、2 个工具、条件边循环
• 写第 1 篇学习笔记

✅ 过关检查点 1（自测）： - [ ] 能说清"为什么 Agent 是图不是链"（用 30 秒讲给假想的新手听） - [ ] 不查资料写出带条件边的循环图 - [ ] 能解释 Reducer 为什么必须存在

三、阶段 2（第 2 周）：生产级能力三件套

本周目标：Checkpointer（持久化）+ interrupt（人工审批）+ Send（并行）。从这周开始，你写的东西已经有企业级雏形。

Day 8：Checkpointer 与 thread_id

# 练习：给 Day7 的解题 Agent 加 SqliteSaver
from langgraph.checkpoint.sqlite import SqliteSaver
saver = SqliteSaver.from_conn_string("checkpoints.db")
graph = builder.compile(checkpointer=saver)
# 实验：① 同一 thread_id 连续对话→有记忆；② 换 thread_id→失忆；③ 中途 Ctrl+C 重跑→从存档恢复

Day 9-10：interrupt 人工审批（本框架的灵魂）

• 跑姊妹篇示例 B（转账审批），然后升级：审批人可以选择 批准 / 拒绝 / 修改金额 三种 resume
• 练习：给解题 Agent 加规则——"计算结果 > 1000 时必须人工确认"

Day 11：Send 并行（Map-Reduce）

# 练习：给 10 篇短文并行做摘要再汇总
from langgraph.types import Send
def fan_out(state):
    return [Send("summarize", {"article": a}) for a in state["articles"]]
# summarize 是一个节点，Reducer 合并 10 份摘要，最后一个节点汇总成报告

Day 12：Subgraph 子图

• 把 Day 7 的解题图改造成子图，外面套一个"路由图"：数学题走解题子图，闲聊走直接回复节点

Day 13：时间旅行调试

• 用 graph.get_state_history(cfg) 列出历史检查点，挑一个旧状态 invoke(None, config) 重跑——体验"回到过去改决策"

Day 14：小测 + 笔记

• 综合练习："报销审批流水线"：读发票（模拟 OCR 数据）→ 金额校验 → 超过 500 元 interrupt 人工审批 → 通过则记账（更新状态字典）。要求 SqliteSaver 持久化 + 三种审批结果
• 写第 2 篇笔记

✅ 过关检查点 2： - [ ] 能演示"杀掉进程后从检查点恢复" - [ ] 能解释 interrupt 为什么要配 checkpointer - [ ] 能写出并行 fan-out/fan-in 图

四、阶段 3（第 3 周）：多智能体与生态打通

本周目标：Supervisor/Swarm 模式 + MCP 工具接入 + deepagents 模板。本周起用 DeepSeek API（质量要求上来了）。

Day 15-16：Supervisor（主管分派模式）

• 官方教程 multi-agent supervisor 跟写一遍：主管 + 研究员 + 写手
• 改造：把研究员换成"知识库检索员"（接一个假知识库字典）

Day 17：Swarm（移交模式）

• 跑官方 swarm 教程：模拟"售前客服 → 售后客服 → 人工"的转接链
• 对比两种模式的适用场景，写进笔记（一句话：能明确分工用 Supervisor，要"转接"用 Swarm）

Day 18：MCP 接入

• 用 langchain-mcp-adapters 把一个现成 MCP server（如 filesystem）接进你的 Agent
• 这一步让你同时踩中两个市场最高频关键词（LangGraph + MCP）

Day 19-20：deepagents 模板

• 跑通 https://github.com/langchain-ai/deep-agents 的最小示例，读它的结构：规划节点 + 子代理 + 虚拟文件系统——这就是第 5 周投研项目的骨架

Day 21：Middleware + 小测

• 给 Agent 加自定义 middleware：所有输出先过敏感词替换再返回
• 写第 3 篇笔记

✅ 过关检查点 3： - [ ] 能搭 Supervisor 双专家协作并说清何时用 Swarm - [ ] 能把任一 MCP server 接进 Agent - [ ] 能解释 deepagents 的规划-执行结构

五、阶段 4（第 4-6 周）：实战项目（三选一，必选其一）

学而不产 = 白学。项目直接对应你的变现路线（长远价值项目低配计算机.md）。

项目 A：企业知识库问答 Agent（★推荐，对应 S1 项目骨架）

• Week 4：LlamaIndex + Chroma + bge-small 建中文索引；Agent 加"检索→不够好自动改写重查→给答案"循环
• Week 5：加权限（interrupt：涉及敏感文档时人工放行）+ SqliteSaver 多租户 + Streamlit 前端
• Week 6：自建 30 题评测集（promptfoo 跑分），给出准确率数字——这是与 90% 撸库存学习者的差距所在
• 交付物：langgraph dev 可演示 + 一页 README（架构图+评测数字）

项目 B：票据处理流水线（对应 S2 的 Agent 化）

• Week 4：RapidOCR 识别 → 字段校验 Agent（结构化输出）
• Week 5：异常单据 interrupt 人工复核 + Send 批量并行 + 断点续跑演示
• Week 6：Web 界面 + 实测 100 张真实票据的准确率

项目 C：企微客服 Agent（对应 S3）

• Week 4：Swarm 三角色（欢迎/问答/转人工）+ 知识库检索节点
• Week 5：企微 webhook 对接（测试号即可）
• Week 6：全流程演示视频 + 部署脚本

每周节奏：工作日每天 1.5h 推进 → 周末各 3h 攻关 → 每周日写周记（做了什么/卡在哪/怎么解决）。

✅ 过关检查点 4（毕业标准）：你的项目能当着别人的面完整演示：提问 → 图执行（Studio 可见）→ 人工审批环节 → 断网重启后续跑 → 给出带溯源的答案。

六、学习方式总纲（比路线更重要）

1. 改 > 跑 > 看：改别人的示例 10 分钟 > 跑通示例 30 分钟 > 看教程 1 小时。每接触新概念，必做"改动实验"并预测结果
2. 先猜后看：卡住时强制自己先写 20 分钟再查文档——检索记忆比阅读记忆牢 3 倍
3. Studio 当 debugger：langgraph dev 打开图视图，单步看状态流转；看不懂别人代码时先画成图
4. LangSmith 看真相（免费额度）：每次执行的完整 trace——模型实际收到什么 prompt、工具返回了什么。调试幻觉和工具调用失败全靠它
5. 费曼笔记：每周一篇，格式固定：这周学会了 X / 卡过 Y / 坑是 Z / 给一个月前的我一句忠告
6. 绝不背 API：API 会变（1.0 就刚大改过），背的是思想：状态机、检查点、审批、并行模式——这些 5 年内不会过时
7. 时间预算纪律：单日卡壳超过 40 分钟 → 记录问题 → 跳过 → 周末集中解决（避免"一行代码卡一晚"的经典时间黑洞）

七、资源清单（按使用顺序）

八、自测清单（第 6 周末，全部能答 = 出师）

1. 为什么要 Reducer？没有它并发节点会发生什么？
2. interrupt() 和普通异常中断的区别？为什么必须配 checkpointer？
3. Supervisor 和 Swarm 各适合什么场景？
4. Send 解决什么问题？和"循环里逐个处理"差在哪？
5. 你的知识库 Agent 里，哪三处用了 LangGraph 独有能力（链式框架做不到）？
6. 如果模型 API 突然不可用，你的图会怎样？怎么设计降级？（加分题）

九、常见坑速查表（遇到就回来翻）

十、6 周后的去向（衔接你的价值主线）

学完 LangGraph ≠ 结束，是三岔口（对应 长期价值评估 Top50 排名）： - 向 RAG 深挖：LlamaIndex + 评测（promptfoo）→ 补齐"企业 RAG 工程师"技能（Top3 技能） - 向底层深挖：读 llama.cpp 量化/GGUF → 补齐"私有化部署"技能（Top3 技能） - 直接接单：把第 4-6 周项目包装成案例，去代账公司/中小企业找第一单（MVP 2万-15万）

三岔口都通，先走哪个取决于你第 5 周实战项目选了 A/B/C。