· LangGraph / LangChain / StateGraph / Checkpoint / Agent / Pregel
Day4:Langgraph的一次小回顾
前言
感觉每天学同类型的内容终究有点审美疲劳(可能也和我三天打鱼两天晒网的性格有关),总之今天就从繁杂的理论学习中脱离出来(我希望不会烂尾吧!),稍微轻松一点,总结一下前段时间另一个技术——Langgraph的学习进展。听的课是尚硅谷的Langgraph课程哦。
0. 目前的学习进展
可以将目前的学习进度分为三个部分(当然部分三还在进行中):
【CP1 状态底座】
TypedDict / dataclass / BaseModel 三形态
→ Reducer 归约合并(add / 自定义)
→ 消息专用归约 add_messages 与 MessagesState
→ 节点增量补丁(Partial State Update)与 Overwrite 强制覆盖
→ 多 Schema 视图隔离(Input / OverAll / Output / Private)
→ MessagesState 与 DeepSeek LLM 对话联动
│
▼
【CP2 控制流与运行时治理】
扇出并行(Fan-Out)
→ 条件路由(Conditional Edges)与 path_map 解耦
→ 多路分支 Sequence 扇出与 defer 延迟审计节点
→ 动态分支(Send API):输入决定并行度的 Map-Reduce
→ 指令式控制流:Command(goto, update) 原生状态跳转
→ 汇合语义:AND 扇入(全部到达)vs OR 扇入(任一触发)
→ ReAct 工具调用循环与随机失败模拟
→ 递归上限限制与 RemainingSteps 优雅退避
→ RetryPolicy 异常重试策略与 CachePolicy(TTL) 内存缓存
│
▼
【CP3 记忆、持久化与时间旅行】
InMemorySaver 内存检查点与 thread_id 会话隔离
→ PostgresSaver 数据库落盘持久化与 setup() 初始化
→ StateSnapshot 数据结构剖析(values, next, step, parent_config)
→ get_state_history 与 get_state(checkpoint_id) 任意时刻状态回放(时间旅行)
1. 状态底座(CP1):State 的三形态与 Reducer 归约机制
在 LangGraph 中,State 是整个图计算流转的“单一事实源(Single Source of Truth)”。图中的每一个节点都接受当前 State 的快照作为输入,并返回对其的部分增量修改。
1.1 State 的三种声明形态与选型对比
在 CP1/02_state.ipynb 中,演示了三种声明 State 的方式:
| 特性 | TypedDict(官方推荐) | dataclass | Pydantic BaseModel |
|---|---|---|---|
| 定义语法 | class S(TypedDict): ... |
@dataclass class S: ... |
class S(BaseModel): ... |
| 字段访问 | 字典语法:state["logs"] |
属性语法:state.logs |
属性语法:state.logs |
| 节点返回 | 返回字典增量补丁 | 需构造并返回新的 dataclass 对象 | 可返回字典或 BaseModel 实例 |
| 校验开销 | 编译期静态类型检查,运行期零开销 | 基础对象封装,无内置数据校验 | 运行期严格字段类型校验与转换 |
| 双重累加风险 | 无(返回字典增量) | 极高(若在构造函数中自行拼接会与 Reducer 发生双重累加) | 低 |
⚠️ dataclass 中的“双重累加陷阱”代码深度解析
在 CP1/02_state.ipynb 的第一个 Cell 中,暴露出一个非常典型的概念陷阱:
@dataclass
class OverAllState:
logs: Annotated[list[str], add] # 声明了 add 归约器
cur_id: str
def node_1(state: OverAllState) -> OverAllState:
pre_id = state.cur_id
# 错误写法:开发者在内部做了 state.logs + ["..."],又返回了 OverAllState 对象
return OverAllState(state.logs + ["node_1 运行完毕"], pre_id + ", node_1")
陷阱剖析:logs 字段已经通过 Annotated[..., add] 注册了框架级的列表累加 Reducer。当 node_1 内部手动执行 state.logs + [...] 并返回时,框架接收到该全量列表,又在原有 state.logs 基础之上执行了一次 operator.add,导致 node_1 运行完毕 在最终日志中被重复累加了两次!
正解:在 LangGraph 节点中,永远只返回需要更新的增量字段(Partial Update),交给 Reducer 统一执行合并,这也是为什么 TypedDict 是最不容易踩坑的推荐形态。
1.2 Reducer 的本质与归约规则
如果多个节点在执行过程中都需要修改同一个字段,或者同一个字段在图的流转中需要保留历史轨迹,就必须通过 typing.Annotated 显式挂载 Reducer。
Reducer 的数学定义是一个二元归约函数:
\[\text{State}_{\text{new}}[k] = \text{Reducer}\left(\text{State}_{\text{old}}[k],\; \Delta\text{State}_{\text{node}}[k]\right)\]- 默认覆盖语义(无 Annotated):若未指定 Reducer,框架执行等价于
lambda old, new: new,即后执行的节点直接覆盖前序值。 - 列表追加归约(
operator.add):lambda old, new: old + new,适合收集各节点执行日志或分布式子任务结果。 - 消息专用归约(
add_messages):针对对话消息设计的智能 Reducer,具备按message.id覆盖更新、无 ID 追加以及特殊删除标记识别功能。
# 自定义 Reducer 示例(CP1/03_reducer.ipynb)
def my_reducer(left: list[str], right: list[str]) -> list[str]:
return left + right # 严格保持时序合并
class OverAllState(TypedDict):
logs: Annotated[list[str], my_reducer]
1.3 强制覆盖:Overwrite 语义
在某些业务场景下(如重置对话上下文、清空错误重试计数器),即使字段声明了追加 Reducer,某个特定节点也需要强行将其重置。LangGraph 提供了 Overwrite 包装类(CP1/05_overwrite.ipynb):
from langgraph.types import Overwrite
def node_2(state: OverAllState) -> OverAllState:
# 强制覆盖:忽略 logs 上的 add reducer,直接将 logs 替换为单元素列表
return {
"cur_id": "node_2",
"logs": Overwrite(["node_2 运行完毕"])
}
1.4 多 Schema 架构(Multi-Schema)与视图隔离
多 Schema 可以分别声明输入、内部状态和输出,让调用方只接触所需字段。下面的例子将三者分开:
# 1. 外部调用输入接口:仅暴露必要入参
class InputState(TypedDict):
username: str
# 2. 外部调用最终输出:仅暴露脱敏/精简后的结果
class OutputState(TypedDict):
graph_output: str
# 3. 图内部全局流转状态:包含全量上下文与内部私有字段
class OverAllState(TypedDict):
username: str
graph_output: str
nickname: str # 内部中间字段
# 4. 节点私有局部状态:高内聚
class PrivateState(TypedDict):
greeting: str
builder = StateGraph(
state_schema=OverAllState,
input_schema=InputState,
output_schema=OutputState
)
多 Schema 核心收益:
- 接口安全与清晰契约:调用方清晰知晓必传字段,无法窥探或篡改内部中间态;
- 状态解耦:内部各子节点可按需使用私有状态进行细粒度封装,防止全局命名污染。
2. 控制流拓扑演进(CP2):从静态边到动态分发与指令式跳转
如果说 CP1 解决了“数据如何存与合”,那么 CP2 则全面解决了“任务如何调度与流转”。
2.1 静态边与条件路由解耦(path_map)
在 CP2/02_route.ipynb 和 CP2/03_path_map.ipynb 中,对比了两种条件分支写法:
# 写法A:路由函数直接返回实际节点名(高耦合,重构节点名时易碎)
def my_route(state: OverAllState) -> Literal["node_1", "node_2"]:
return "node_1" if "诗" in state["content_type"] else "node_2"
builder.add_conditional_edges(START, my_route)
# 写法B(推荐):路由函数返回抽象业务标签,通过 path_map 映射到物理节点(解耦)
def my_route(state: OverAllState) -> Literal["poem", "joke"]:
return "poem" if "诗" in state["content_type"] else "joke"
builder.add_conditional_edges(
START,
my_route,
path_map={
"poem": "node_1",
"joke": "node_2"
}
)
2.2 延迟节点(defer=True)
在 CP2/05_defer.ipynb 中引入了 defer=True 属性。声明为延迟执行的节点,无论在图拓扑中处于何种前驱位置,Pregel 调度器都会保证该超步内的所有常规并行节点均执行完毕后,才最后调度该延迟节点。该机制天然适用于全链路审计日志记录、资源清理以及指标打点上报。
builder.add_node("audit_node", audit_node, defer=True)
builder.add_edge(START, "audit_node") # 虽然连自 START,但会在常规任务完成后触发
2.3 动态分支(Send API)与 MapReduce 范式
传统的 add_edge 或 add_conditional_edges 必须在编译期静态确定拓扑分支数量。而现实业务中,往往需要根据用户输入的数组长度动态并行触发 N 个 Worker 节点。
CP2/06_dynamic_branch.ipynb 与 CP2/09_mapreduce.ipynb 展示了 Send API 的能力:
# 分发路由:动态产生 N 个 Send 任务(CP2/09_mapreduce.ipynb)
def router_node(state: OverAllState) -> Sequence[Send]:
input_values = state["input_values"] # 如 ['hello world', 'hello redmoon', 'hello llm']
tasks = []
for item in input_values:
# Send(目标节点名, 该节点的独立输入入参)
tasks.append(Send("mapper_node", {"input_value": item}))
return tasks
# 构建图
builder.add_conditional_edges(START, router_node, path_map=["mapper_node"])
builder.add_edge("mapper_node", "reducer_node") # 所有 Mapper 节点并行完成后自动汇入 Reducer
MapReduce 三阶段协同机理:
- Map 分发:
router_node使用Send将句子列表拆分为 N 个并发的mapper_node; - Shuffle 汇聚:
entries: Annotated[list[tuple[str, int]], add]自动将所有并发 Mapper 返回的单词元组汇总入全局 State; - Reduce 聚合:
reducer_node从entries中读取所有键值对并完成合并计数。
2.4 指令式控制流:Command 原生跳转
Command 可以在节点的一次返回中同时更新状态和指定下一跳。CP2/07_command.ipynb 和 CP2/11_loop.ipynb 用的是 Command(goto=..., update=...):
from langgraph.types import Command
def llm_node(state: OverAllState) -> Command[Literal["tool_node", "output_node"]]:
ai_msg = model_with_tools.invoke(state["messages"])
if ai_msg.tool_calls:
goto = "tool_node" # 动态指示下一跳为工具节点
else:
goto = "output_node" # 动态指示下一跳为输出节点
return Command(
goto=goto,
update={"messages": [ai_msg]} # 同时携带状态更新补丁
)
Command 的核心优势:
- 节点兼具“计算”与“动态流转决策”能力,大幅精简图中复杂的条件边声明;
- 工具调用后,可以根据结果决定继续执行还是结束。
2.5 扇入汇合语义:AND 汇合 vs OR 汇合
在多分支汇合时,CP2/08_fan_in_and.ipynb 揭示了两种完全不同的扇入语义:
# 1. AND 汇合(列表边):node_e 必须等待 node_c 和 node_d 全部执行完毕才触发一次
builder.add_edge(["node_c", "node_d"], "node_e")
# 2. OR 汇合(多条独立边):node_c 完成触发一次 node_e,node_d 完成又触发一次 node_e
# builder.add_edge("node_c", "node_e")
# builder.add_edge("node_d", "node_e")
| 汇合模式 | 语法形式 | 触发条件 | 执行次数 | 适用场景 |
|---|---|---|---|---|
| AND 扇入 | builder.add_edge([A, B], C) |
前驱 A 与 B 全部完成 | 仅触发 1 次 | 数据合并、协同完成、栅栏同步 |
| OR 扇入 | 连续两条 add_edge(A, C), add_edge(B, C) |
前驱 A 或 B 任一完成 | 共触发 2 次 | 竞速模式、事件通知(需下游节点幂等) |
3. 循环、容错与运行时防护(CP2 后半)
真实生产环境中的 Agent 绝非一帆风顺,网络抖动、模型幻觉、死循环和超时是必须治理的常态。
3.1 经典 ReAct 工具调用循环与死循环防护
在 CP2/10_static_loop.ipynb 中,构建了 input_node -> llm_node <-> tool_node -> output_node 的完整循环链路,并在工具节点中以 60% 概率模拟网络波动抛出错误信息。模型根据错误反馈重新发起工具调用,直到获取成功响应后退出循环。
递归深度限制:recursion_limit
为了防止无限循环耗尽 Token 与算力,LangGraph 在调用时支持指定 recursion_limit(默认 25)。当超步数达到上限时,框架会主动抛出 GraphRecursionError(CP2/13_end_loop.ipynb):
from langgraph.errors import GraphRecursionError
try:
graph.invoke({}, config={"recursion_limit": 10})
except GraphRecursionError as e:
logger.error(f"达到最大递归限制,安全中断: {e}")
优雅降级退出:RemainingSteps
相比直接被动抛出异常中断整个程序,更好的做法是在步数耗尽前主动降级并产出当前最优答卷。CP2/12_remaining_setps.ipynb 演示了托管变量 RemainingSteps 的使用:
from langgraph.managed import RemainingSteps
class OverAllState(TypedDict):
remaining_steps: RemainingSteps # 由框架自动注入与扣减
def router(state: OverAllState) -> Literal["loop_node", END]:
remaining = state["remaining_steps"]
if remaining < 3:
# 当剩余步数不足 3 步时,主动中断循环流向收尾节点
logger.warning(f"可用超步仅剩 {remaining} 步,执行优雅退出策略")
return END
return "loop_node"
3.2 节点故障重试策略:RetryPolicy
在 CP2/14_retry_ipynb.ipynb 中,通过在 add_node 时挂载 RetryPolicy,可实现对指定瞬时异常(如 HTTPError 502/504)的自动退避重试:
from langgraph.types import RetryPolicy
from urllib.error import HTTPError
builder.add_node(
"node_a",
node_a,
retry=RetryPolicy(
max_attempts=3, # 最大重试 3 次(含首次共 3 次)
retry_on=(HTTPError,), # 仅捕获 HTTPError 触发重试,其余异常直接向上抛出
jitter=False # 关闭随机抖动(开启后可在指数退避上增加微小随机扰动以削峰)
)
)
3.3 节点级结果缓存:CachePolicy
在 CP2/15_ache.ipynb 中,针对耗时较长、入参幂等的节点(如高耗时联网检索或 Embedding 计算),通过 CachePolicy 挂载 TTL 缓存机制:
from langgraph.types import CachePolicy
from langgraph.cache.memory import InMemoryCache
# 节点设置 10 秒 TTL 缓存
builder.add_node("node_a", node_a, cache_policy=CachePolicy(ttl=10))
# 编译时挂载缓存后端
graph = builder.compile(cache=InMemoryCache())
缓存命中规则:缓存 Key 由 node_name + 节点输入状态的哈希指纹 组合生成。在 10 秒内使用相同输入再次触发该节点时,将跳过 3 秒的模拟执行耗时,以 0ms 瞬间返回历史缓存;超过 10 秒后缓存失效,重新执行节点函数。
4. 记忆与状态持久化(CP3):Checkpointer 与时间旅行
智能体若只能在单次执行期间驻留内存,便无法支撑长周期任务、多轮用户对话以及人工介入审核(Human-in-the-Loop)。Checkpointer(检查点保存器)是 LangGraph 实现记忆、状态恢复与分支探索的底层中枢。
4.1 检查点存储器选型:InMemorySaver vs PostgresSaver
在 CP3/01_in_memory.ipynb 与 CP3/02_in_SQL.ipynb 中分别演示了两种典型的检查点持久化实现:
# 1. 内存存储(仅用于本地单测 / 开发原型)
from langgraph.checkpoint.memory import InMemorySaver
checkpointer = InMemorySaver()
graph = builder.compile(checkpointer=checkpointer)
# 2. PostgreSQL 数据库持久化(生产推荐)
from langgraph.checkpoint.postgres import PostgresSaver
DB_URL = "postgresql://user:pwd@localhost:5432/db?sslmode=disable"
with PostgresSaver.from_conn_string(DB_URL) as checkpointer:
checkpointer.setup() # 首次使用自动初始化 checkpoints 表结构
graph = builder.compile(checkpointer=checkpointer)
会话级隔离:thread_id
挂载 Checkpointer 的图在执行时,必须在 config["configurable"] 中传入 thread_id。所有使用相同 thread_id 的调用都会自动沿用上一轮保存的 State;换用新的 thread_id 则立即开启一条全新的独立上下文链。
4.2 核心数据结构深度拆解:StateSnapshot
在 CP3/03_history_state.ipynb 中调用 graph.get_state_history(config),可取得由 StateSnapshot 构成的历史时间链。
下面结合真实执行输出,详细解析 StateSnapshot 的核心字段构成:
| 字段名称 | 类型 | 核心含义与作用 | 典型输出取值样例 |
|---|---|---|---|
values |
dict |
当前超步结束时,全局 State 字典的完整数据快照 | {'topic': '莲花', 'poem': '《咏莲》...', 'joke': '...'} |
next |
tuple[str] |
下一个等待被调度的节点名称元组(若为空元组 () 则表示图已结束) |
('node_output',) 或 () |
config |
dict |
定位当前检查点的配置字典,包含 thread_id 与本快照专属的 checkpoint_id |
{'configurable': {'thread_id': '123', 'checkpoint_id': '1f1a2296-d5ad-6eb5-8001-2afa8c444f2f'}} |
metadata |
dict |
框架运行元信息,记录触发来源 source(如 input/loop)以及当前逻辑步骤 step |
{'source': 'loop', 'step': 1, 'parents': {}} |
created_at |
str |
该检查点生成的 UTC 时间戳(ISO 8601 格式) | '2026-08-27T15:10:23.722667+00:00' |
parent_config |
dict | None |
指向上一个父级检查点的定位字典,串联成单向链表 | {'configurable': {'checkpoint_id': '1f1a2296-b730-6552-8000-2b88cd283dec'}} |
tasks |
tuple[PregelTask] |
在当前超步中被执行的底层任务列表,包含任务 ID、执行节点及该节点的增量返回 result |
(PregelTask(name='node_output', result={'final_output': ...}),) |
interrupts |
tuple |
人工介入中断信号元组(若遇到 interrupt() 断点则携带中断上下文) |
() |
4.3 时间旅行(Time-Travel)与任意时刻回放
完整的检查点链既支持向后追加对话,也支持从已保存的历史步骤恢复执行(Time-Travel),或从历史分叉点尝试不同的执行路径:
# 1. 获取某个历史检查点的 checkpoint_id
history = list(graph.get_state_history(config=config))
target_checkpoint_id = history[3].config["configurable"]["checkpoint_id"]
# 2. 精准加载历史某时刻的快照
target_config = {
"configurable": {
"thread_id": "123",
"checkpoint_id": target_checkpoint_id
}
}
snapshot = graph.get_state(config=target_config)
print("历史快照状态:", snapshot.values)
# 3. 从该历史快照分叉继续执行(Time-Travel Branching)
# 可以通过 graph.update_state 修改历史状态,或以此 config 继续 invoke 新输入
5. LangGraph 核心 API 官方定义与概念溯源速查
为了避免概念模糊,本节对照 LangGraph 官方底层设计规范,将全系列涉及的关键组件整理为速查矩阵:
| 核心组件 | 官方概念定义 / 角色 | 底层机理与注意事项 |
|---|---|---|
StateGraph |
图结构定义构建器 | 必须绑定 state_schema。通过 add_node、add_edge 构建静态拓扑,经 compile() 编译为可执行的 CompiledStateGraph。 |
Node |
图中的计算处理单元 | 普通 Python 函数(同步/异步),接收当前 State 快照,返回 Partial Update 增量字典或 Command。 |
Edge |
节点之间的确定性有向连接 | 静态声明控制权转移,支持一对一、扇出(一对多)以及 AND 汇合(多对一列表形式)。 |
ConditionalEdge |
基于状态判断的动态路由边 | 接收路由函数,根据返回值动态决定下游走向;推荐配合 path_map 实现业务标签与节点名解耦。 |
Send |
动态并行子任务投递原语 | 允许在路由函数中返回 Sequence[Send],根据运行时数据动态分发 N 个子任务,是 MapReduce 的核心支撑。 |
Command |
节点内部的指令式流转原语 | 允许节点在一次返回中同时完成状态修改(update)与下一跳指定(goto),消除对外部显式条件边的依赖。 |
MessagesState |
预置对话消息状态基类 | 预置 messages: Annotated[list[AnyMessage], add_messages],封装了消息去重、更新与时序合并的标准 Reducer。 |
InMemorySaver / PostgresSaver |
状态检查点持久化后端 | 在每个超步(Superstep)执行边界自动将全局 State 与任务元信息写入持久化存储,赋予图“记忆”与“回滚”能力。 |
RemainingSteps |
框架托管的剩余步数变量 | 受 recursion_limit 约束逐步递减,节点或路由函数可感知剩余可用步数以实现优雅降级退出。 |
RetryPolicy |
节点级故障重试规则配置 | 声明 max_attempts、retry_on 及指数退避抖动 jitter,增强面对不稳定外设/API 时的系统鲁棒性。 |
CachePolicy |
节点级计算结果缓存规则配置 | 结合编译时挂载的 Cache 后端(如 InMemoryCache),按入参指纹与 ttl 自动复用计算结果。 |
6. Day 4 收工小结
“节点返回了什么”和“图接下来执行什么”属于两个层面。State 的字段及其覆盖、追加、按消息 ID 更新等合并规则决定状态如何变化;条件边、Send 分发和 Command 跳转决定执行路径。
循环跑起来以后,还要分别处理步数、异常和重复计算:RemainingSteps 用来感知剩余步数,RetryPolicy 处理适合重试的异常,CachePolicy 复用结果。它们解决的问题不同。
最后是跨次执行的状态。PostgresSaver 保存检查点,StateSnapshot 展示现场,checkpoint_id 定位历史位置。
附 · 项目仓库
本篇对应的完整实战代码(CP1 / CP2 / CP3 共 26 个 Notebooks)与 8 张架构图已整理至 GitHub,开箱可复现博客全部案例:
- Redmoon-2333/Langgraph — GuiGU 课程实战(CP1-CP3) — 含精析长文 Day4.md、CP1/ CP2/ CP3/ 全量 notebooks 与 assets/img/ 原图,依 CP1 → CP2 → CP3 顺序执行即可复现。