基于 LangGraph 官方最佳实践，使用 DeepSeek 作为大语言模型的完整教学课程。从 StateGraph 核心概念开始，逐步掌握 Agent 构建、多智能体协作和生产环境部署。
| 模块 | 目录 | 学习目标 |
|---|---|---|
| 00 | Hello Graph | StateGraph 三要素、compile/invoke、Chain vs Graph |
| 01 | State & Reducers | TypedDict 定义、add_messages、operator.add、自定义 reducer、MessagesState |
| 02 | 条件路由 | add_conditional_edges、关键词路由、LLM 路由、Refine 循环 |
| 03 | Checkpointing | InMemorySaver、thread_id 隔离、状态回放、update_state |
| 04 | 人工介入 | interrupt()、Command 恢复、interrupt_before/after、审批工作流 |
| 05 | 并行执行 | Send API、fan-out/fan-in、map-reduce 摘要 |
| 06 | 子图组合 | 编译图作为节点、父子状态共享、模块化组件 |
| 07 | 流式输出 | stream_mode（messages/updates/custom/debug）、StreamWriter |
| 08 | Agent 模式 | create_agent、ReAct 循环、system_prompt、response_format 结构化输出 |
| 09 | 多 Agent 系统 | Supervisor-Worker 模式、Agent Handoff 交接、共享状态 |
| 10 | 生产环境 | RetryPolicy、error_handler、RemoveMessage 裁剪、CachePolicy、检查清单 |
- Python 3.12+
- Windows / macOS / Linux
git clone https://github.com/cccsama/langgraph-deepseek-tutorial.git
cd langgraph-deepseek-tutorial如果你已有本项目的姊妹教程 LangChain + DeepSeek，可直接复用其虚拟环境和依赖。
python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate
pip install -r requirements.txtcp .env.example .env编辑 .env 文件，填入你的 DeepSeek API Key：
LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=sk-your-api-key-here
LLM_BASE_URL=https://api.deepseek.com前往 platform.deepseek.com/api_keys 注册并获取 API Key。
python 00_hello_graph/hello_graph.py如果看到 LLM 回复和计数器结果，说明环境配置成功！
.
├── .env.example # 环境变量模板
├── .gitignore
├── config.py # 共享配置（模型初始化、API 加载）
├── requirements.txt # Python 依赖列表
├── LICENSE # MIT License
├── README.md # 项目说明
│
├── 00_hello_graph/ # StateGraph 核心概念
│ ├── hello_graph.py # 三要素、三步管道、纯逻辑图、Chain vs Graph
│ └── README.md
│
├── 01_state_reducers/ # 状态与 Reducer
│ ├── state_reducers.py # 覆盖、累加、add_messages、自定义 reducer
│ └── README.md
│
├── 02_conditional_routing/ # 条件路由
│ ├── conditional_routing.py # 关键词路由、LLM 路由、Refine 循环
│ └── README.md
│
├── 03_checkpointing/ # 持久化与回放
│ ├── checkpointing.py # InMemorySaver、线程隔离、状态回放、update_state
│ └── README.md
│
├── 04_human_in_loop/ # 人工介入
│ ├── human_in_loop.py # interrupt()、Command、审批流程、interrupt_before
│ └── README.md
│
├── 05_parallel_execution/ # 并行执行
│ ├── parallel_execution.py # Send fan-out、fan-in、map-reduce
│ └── README.md
│
├── 06_subgraphs/ # 子图组合
│ ├── subgraphs.py # 编译图作为节点、父子状态共享、私有键隔离
│ └── README.md
│
├── 07_streaming/ # 流式输出
│ ├── streaming.py # messages/updates/custom/debug 四种模式
│ └── README.md
│
├── 08_agent_patterns/ # Agent 构建
│ ├── agent_patterns.py # create_agent、system_prompt、结构化输出
│ └── README.md
│
├── 09_multi_agent/ # 多 Agent 协作
│ ├── multi_agent.py # Supervisor、Handoff、Agent 间通信
│ └── README.md
│
└── 10_production/ # 生产最佳实践
├── production.py # RetryPolicy、error_handler、缓存、状态裁剪
└── README.md
- Python 基础（函数、类、类型注解、装饰器）
- 基本的命令行操作
- 了解 LLM / ChatGPT 的基本概念
- 建议先学习 LangChain 基础教程（本项目的姊妹教程）
每个模块都是独立可运行的 Python 文件，按编号顺序学习效果最佳：
- 00 Hello Graph — 理解 StateGraph 三要素和基本用法
- 01 State & Reducers — 掌握状态设计和合并策略
- 02 条件路由 — 让图根据状态动态选择路径
- 03 Checkpointing — 持久化对话状态，实现多轮交互
- 04 人工介入 — 在工作流中插入人工审批节点
- 05 并行执行 — 用 Send API 实现动态并行任务
- 06 子图组合 — 构建可复用的图组件
- 07 流式输出 — 实时反馈和调试模式
- 08 Agent 模式 — 用 create_agent 构建智能体
- 09 多 Agent 系统 — 多智能体协作与交接
- 10 生产环境 — 重试、降级、缓存等最佳实践
每个模块的 README.md 包含核心概念解释，建议先阅读再动手。
| LangChain (LCEL) | LangGraph | |
|---|---|---|
| 抽象 | 链式处理（Chain） | 有向图（Graph） |
| 控制流 | 线性 A→B→C | 分支、循环、并行 |
| 状态管理 | 数据流经管道 | 显式 State + Reducer |
| 循环 | 不支持 | 原生支持（Agent tool loop） |
| 持久化 | 手动管理 | 内置 Checkpointer |
| 人工介入 | 无 | interrupt() / Command |
| 适用 | 简单流水线、RAG | Agent、复杂工作流、多步规划 |
一句话：Chain 适合"一次性处理"，Graph 适合"有状态的、多步骤的、需要判断和循环"的场景。
本教程的姊妹项目 LangChain + DeepSeek 教程 涵盖了 LCEL 链式编程的完整内容。
和 LangChain 教程的关系？
两个项目是姊妹教程，均使用 DeepSeek 模型：langchain-deepseek-tutorial 侧重链式编程（LCEL），本教程侧重图式编程（Graph）。建议先学 LangChain 再学 LangGraph。
为什么使用 DeepSeek？
DeepSeek 是国内最优秀的 LLM 服务商之一，API 兼容 OpenAI 格式，性价比极高。本教程的代码只需修改 .env 配置即可切换到 OpenAI、Moonshot 等服务商。
可以复用 LangChain 教程的 venv 吗？
可以。本项目的 requirements.txt 引用了 LangChain 教程的依赖，两个项目可以使用同一个虚拟环境。只需将 requirements.txt 中的路径改为你的实际路径。
create_react_agent 还能用吗？
已弃用。请统一使用 from langchain.agents import create_agent，本教程所有 Agent 代码均使用新 API。
如何换成其他模型？
编辑 .env 中的 LLM_MODEL_ID 和 LLM_BASE_URL：
LLM_MODEL_ID=gpt-4o
LLM_API_KEY=sk-your-openai-key
LLM_BASE_URL=https://api.openai.com/v1MIT License — 详见 LICENSE 文件。开源、免费、随意用于学习和商业项目。