LangGraph 的架构由四个清晰的层次构成，从顶层的图构建器到底层的持久化系统，每一层都承担着明确的职责。整个系统的执行流遵循编译-执行-持久化的闭环模式。本文深入源码逐层分析 StateGraph.compile() 的内部原理。
LangGraph 是 LangChain 生态中用于构建有状态、多参与者的 AI Agent 应用的框架。与 AutoGen 的消息传递模型不同，LangGraph 采用有向图（DAG）编排模型——节点是 Agent 或工具函数，边是控制流逻辑。这种模型更适合确定性工作流，但灵活性也更高。LangGraph 的核心优势在于其强大的状态管理和检查点系统，这使它成为生产级 Agent 应用的首选框架之一。
理解 LangGraph 的内部架构对高效使用它至关重要。很多开发者只知道调用 graph.invoke() 却不知道背后发生了什么——StateGraph 如何编译为 Pregel 图？Pregel 引擎如何执行超步循环？通道系统如何管理状态版本？检查点如何实现时间旅行？本文将逐层解答这些问题。
LangGraph 的 BSP（Bulk Synchronous Parallel）模型源自 Google 的 Pregel 论文，最初用于大规模图处理。LangGraph 将其适配到 Agent 工作流编排场景中，保留了\"计算-通信-同步\"三轮循环的核心模式。与纯异步模型（如 AutoGen 的基于 asyncio 的消息队列）相比，BSP 提供了更强的确定性保证——每个超步结束时，所有节点的状态变更对下一个超步是全部可见的，不存在部分写入的模糊状态。
从架构演进的角度看，LangGraph 代表了 LangChain 从\"链式管道\"向\"图式编排\"的范式转变。LangChain 的 Chain 是线性序列——A→B→C，每个步骤只有一个输入和一个输出。LangGraph 的 StateGraph 则是任意拓扑的有向图——一个节点可以有多个输入通道和多个输出通道，边可以携带条件路由逻辑。这种从线性到拓扑的跃迁，使得 Agent 系统可以从简单的\"提示链\"进化为复杂的\"协作网络\"。
四层体系结构：LangGraph 的核心是 StateGraph 构建器、Pregel BSP 执行引擎、版本驱动的通道系统、以及 WAL 风格的检查点持久化。用户通过 add_node、add_edge 定义图，编译后生成 CompiledStateGraph（Pregel 子类）。运行时由 PregelLoop 执行 tick() 循环：任务准备 → 并行执行 → 写入应用 → 检查点持久化。
编译（compile）和执行（invoke/stream）是 LangGraph 的两个核心阶段。编译阶段将 StateGraph 的节点和边定义转换为 Pregel 引擎可以理解的低级表示——包括通道映射、节点定义、边条件。执行阶段由 PregelLoop 驱动，通过超步（Superstep）模型逐步推进图执行。每个超步包含任务调度、并行执行、结果归约和检查点持久化四个子步骤。
追踪一次完整的 graph.invoke() 数据流可以清晰地看到四层协作：用户输入进入 StateGraph 层，被编译为 Pregel 可执行的通道初始值；PregelLoop 启动后，从 Channels 层读取各通道的当前值，调度节点执行；节点输出通过通道系统写入，触发版本号递增；每轮超步结束时，Checkpoint 层将通道状态和版本号持久化。这四层的协作模式类似于数据库系统中的\"查询计划器→执行引擎→缓冲区管理器→WAL 日志\"的层次关系。
编译后的图（CompiledStateGraph）是一个完全可序列化的对象描述——它包含了所有节点的函数引用、通道的配置映射、边的拓扑关系和检查点的配置参数。这种设计使得编译后的图可以被缓存、跨进程传输、甚至序列化到磁盘。实际上，LangGraph Cloud 平台就是利用这一特性，在 Worker 进程之间共享编译好的图定义，仅需根据 thread_id 从数据库加载检查点即可恢复执行。
| 层次 | 模块 | 职责 |
|---|---|---|
| Layer 1 | StateGraph | 图构建、schema 解析、compile() |
| Layer 2 | Pregel | BSP 执行引擎、Loop、tick() |
| Layer 3 | Channels | 版本驱动状态存储、6 种通道类型 |
| Layer 4 | Checkpoint | WAL 持久化、快照、时间旅行 |
StateGraph 采用经典的构建器模式。用户在 compile() 之前通过链式调用定义图结构。_get_channels() 解析状态 schema 字段注解，根据 Annotated[T, reducer] 自动选择通道类型（LastValue、Topic、BinaryOperatorAggregate 等）。compile() 执行四步：构建通道映射 → 创建 PregelNode → 处理边 → 创建 CompiledStateGraph。
通道映射（channel map）是 compile() 最核心的输出。每个状态字段（如 messages、agent_output）被映射到一个通道实例。通道的类型由字段注解中的 reducer 函数决定：LastValue 用于覆盖式更新（如 agent_output），Topic 用于追加式更新（如 messages: Annotated[list, add_messages]），BinaryOperatorAggregate 用于聚合操作（如 total: Annotated[int, operator.add]）。
边处理是 compile() 的另一关键步骤。条件边（add_conditional_edges）被编译为路由函数——输入当前状态，输出目标节点名称。普通边（add_edge）被编译为无条件的数据流路径。PregelNode 的创建将节点函数、输入通道、输出通道和触发条件打包为一个可执行单元。
_get_channels() 方法对嵌套 TypedDict 的处理体现了 LangGraph 的设计深度。当状态 schema 包含嵌套结构（如 class AgentState(TypedDict): messages: Annotated[list, add_messages]; metadata: dict）时，_get_channels() 递归解析每个字段的注解，为嵌套字段的子字段创建独立的通道实例。外层通道负责管理子通道的版本号聚合，内层通道负责具体值的存储和更新。这种嵌套通道模型使得复杂状态结构可以在保持版本驱动语义的同时，实现高效的内存管理。
compile() 的校验阶段同样值得关注。在创建 PregelNode 之前，系统会验证所有节点名称的唯一性、边的起点和终点节点是否存在、条件边的路由函数返回值是否在已注册节点范围内。这些校验在开发期提前暴露问题，避免运行时崩溃。此外，compile() 还会检测 checkpointer 的配置一致性——如果节点中存在 interrupt() 调用但是没有配置 checkpointer，编译过程会抛出明确的配置错误提示。
Pregel 是执行核心，实现块同步并行（BSP）模型。PregelLoop 是上下文管理器，管理 tick() 循环。每个 tick：prepare_next_tasks() 并行调度 PUSH 和 PULL 任务，然后 apply_writes() 将任务输出写入通道系统并更新版本号。任务 ID 基于 (checkpoint_id, namespace, step, name, triggers) 的 xxhash 确定性生成，保障重放安全。
PUSH 任务是由节点主动产生的输出触发的（如 Agent 调用工具后产生结果），PULL 任务是由通道版本变化触发的（如通道值更新后通知下游节点）。PregelLoop 每轮 tick 会先收集所有 PUSH 任务的输出，然后检查哪些通道的版本号发生了变化，最后调度所有受影响的 PULL 任务。这种 PUSH-PULL 混合模型平衡了数据流和控制流的执行需求。
任务 ID 的确定性生成是 LangGraph 可靠性的基石。同一输入在完全相同的状态下重放时，任务 ID 完全相同。这意味着即使出现故障，系统也可以精确恢复——不会遗漏、不会重复。这是 LangGraph 的"可重放性优先"设计哲学的直接体现。
Pregel 的并行执行模型基于 Python 的 asyncio 实现。在每轮 tick 中，submit() 将所有就绪任务包装为 asyncio.Task 并发提交。LangGraph 不依赖多线程（threading）或进程池（multiprocessing），而是使用异步 I/O 模型实现并发——这意味着 CPU 密集型的 Agent 函数仍然会阻塞事件循环。对于 CPU 密集场景，LangGraph 建议将计算密集型节点包装为独立子进程或利用 LangServe 的水平扩展。异步模型的好处是 I/O 密集型节点（如 LLM 调用、API 请求）可以高效并发，不需要锁机制，避免了死锁和竞态条件。
错误处理在 PregelLoop 中采用"快速失败"策略。如果任意节点在执行过程中抛出未捕获的异常，tick() 会立即终止当前超步，将异常信息包装为 TaskError 并向上传播。此时检查点不会保存——系统状态回滚到上一个完整的检查点。这种设计确保了错误的"原子性"：要么整个超步成功，要么全部回滚。开发者可以在节点函数内部使用 try/except 捕获预期内的异常（如 LLM 超时），返回错误状态而非抛出异常，从而让图继续执行错误处理分支。
每个通道是有类型容器，通过单调递增版本号驱动节点执行。节点跟踪"已见版本"，当 channel_versions[ch] > versions_seen[node][ch] 时触发调度。六种通道类型：LastValue（覆盖）、Topic（PubSub）、DeltaChannel（WAL 日志）、EphemeralValue（瞬态）、BinaryOperatorAggregate（聚合）、NamedBarrierValue（屏障）。
版本驱动模型是 LangGraph 区别于其他 Agent 框架的核心创新。每个通道维护一个单调递增的版本号，每次写入操作后版本号 +1。节点记录它最后一次读取时各个通道的版本号（称为"已见版本"）。当 PregelLoop 检查到某个通道的当前版本号大于节点的已见版本时，该节点被标记为"需要执行"。这种模型自然支持选择性执行和增量计算——只有受影响的节点才会被触发。
DeltaChannel 是最重要的通道类型之一。它不存储完整的通道值，而是存储自上次检查点以来的增量变更。这对于大型状态（如数千条消息的对话历史）特别有价值——每次检查点只需要序列化增量而非全量数据。NamedBarrierValue 则用于同步多个节点的执行——当且仅当所有上游节点都写入后，下游节点才会被触发。
并发写入的冲突解决是通道系统设计中的核心挑战。当两个节点在同一超步中写入同一个通道时（例如两个并行 Agent 都尝试更新 messages 字段），通道的 reducer 函数决定了合并策略。Topic 通道的 add_messages reducer 会将所有写入追加到列表中——写入顺序由 apply_writes() 中收到的顺序决定。BinaryOperatorAggregate 使用二元运算符逐个折叠所有写入值。而 LastValue 通道则只保留最后一个写入——这可能导致数据丢失，是 LangGraph 中常见的配置错误源头。
通道的内存管理策略同样值得关注。每个通道在检查点持久化后，可以选择清除内部缓冲区以释放内存。Topic 通道在检查点后清除已持久化的消息列表，只保留未消费的增量。DeltaChannel 在检查点后将增量合并到基线值中，然后清除增量缓存。EphemeralValue 通道完全不参与持久化——它在每次检查点后被完全清除，适合存储临时计算中间结果。这种分级内存策略确保长时间运行的 Agent 系统不会因为累积的通道状态而耗尽内存。
采用预写日志（WAL）模式。不是直接刷入数据库，而是先写入操作日志，再定期生成快照。Checkpoint 包含通道值快照、版本号、已见版本。BaseCheckpointSaver 是抽象接口，支持 Memory、SQLite、Postgres 后端。检查点保存通过 future 链序列化排序，确保全序关系和可靠的时间旅行调试。
检查点的保存时序对系统正确性至关重要。LangGraph 使用 Python 的 asyncio Future 链来排序检查点操作——每个检查点保存必须等前一个完成后才能进行。这确保了即使在并发执行环境中，检查点也是严格有序的。无序的检查点会导致"时间旅行调试"返回不一致的状态视图。
Postgres 检查点存储是最推荐的生产级方案。它提供了 ACID 事务保证，支持两阶段 DeltaChannel 历史重建（Stage 1 扫描元数据，Stage 2 批量获取 blob），端到端延迟比 SQLite 快 3.0 倍，网络传输量小 61%。对于需要跨进程共享状态的多实例部署，Postgres 是必选方案。
检查点的序列化格式需要处理复杂的 Python 对象。LangGraph 使用内部序列化器，支持 TypedDict、Pydantic 模型、dataclass 和自定义类型。对于标准类型（str、int、list、dict），使用 JSON 序列化，对复杂类型（如 LangChain 的 AIMessage 对象），使用 pickle 协议回退。用户可以通过 Serializer 接口注册自定义序列化器，用于加密敏感数据或优化特定类型的序列化性能。
不同检查点后端在性能特性上有显著差异：MemorySaver（内存，最快，但不持久）、SqliteSaver（本地磁盘，适合开发和单实例部署、延迟 ~2ms）、PostgresSaver（网络数据库，适合多实例、延迟 ~5ms 但有事务保证）、DynamoDBSaver（AWS 原生集成、延迟 ~10ms，适合大规模云部署）。选择标准：单实例开发用 SqliteSaver，多实例生产用 PostgresSaver，需要 AWS 原生集成时用 DynamoDBSaver。
LangGraph 优先确定性 > 灵活性，可重放性 > 最低延迟。关键决策：确定性任务 ID（xxhash/UUIDv5）、序列化检查点排序（future 链）、BSP 超步模型、TypedDict 而非 Dataclass、DeltaChannel 写前日志、自研 Pregel 而非 Apache Beam。每个选择都围绕人机交互循环的精确状态管理这一核心目标。
TypedDict 而非 Pydantic/Dataclass 的选择值得关注。TypedDict 是原生 Python dict 的子类，天然支持 JSON 序列化——这意味着状态可以直接存入数据库、通过 API 返回、或在进程间传输。相比之下，Pydantic 模型需要额外的序列化/反序列化步骤，Dataclass 需要自定义编码器。TypedDict 的简洁性降低了框架的耦合度。
自研 Pregel 而非采用 Apache Beam 等现有 BSP 框架的决策，体现了 LangGraph 对 Python 生态集成度的重视。自研引擎可以最大化与 LangChain 生态系统（LangSmith、LangServe）的兼容性，同时避免引入过重的依赖。代价是需要自行维护执行引擎的复杂性和正确性。
Python 性能瓶颈是 LangGraph 架构中一个现实但被合理管理的权衡。PregelLoop 的核心路径完全在 Python 中执行——包括任务调度、通道写入、版本检查。对于大多数 Agent 工作流（每个超步涉及 LLM 调用，延迟在数百毫秒到数秒之间），Python 的解释器开销（~微秒级）可以忽略不计。但对于纯计算密集型节点（如数据处理、向量搜索），LangGraph 提供了 BatchNode 抽象用于批量处理，或者用户可以将其包装为外部服务调用。
LangGraph 架构的未来方向包括几个值得关注的演进：对多租户场景的原生支持（目前依赖 thread_id 命名空间模式），更高效的增量检查点算法（减少快照频率），以及可插拔的调度策略（当前 BSP 固定，未来可能支持异步流水线并行）。LangGraph 团队已经在 v0.3+ 中开始引入 Command 对象作为节点输出的新协议，取代传统的 dict 返回格式，这为更灵活的节点间通信铺平了道路。