图结构详解

📚 学习目标

学完这篇文章后，你将能够：

• 深刻理解 StateGraph 的核心作用
• 掌握图的编译过程及其重要性
• 学会使用 Mermaid 可视化你的图结构
• 了解不同类型图结构的适用场景

前置知识

在开始学习之前，建议先阅读：

• 02-core-concepts

你需要了解：

• JavaScript/TypeScript 基础
• 基本的数据结构（图、节点、边）

1️⃣ 图（Graph）的核心地位

在 LangGraph 应用中，图是核心容器，它将状态、节点和边组织在一起，形成一个可执行的单元。

类比理解

2️⃣ 主要图类

StateGraph（推荐）

StateGraph 是最通用的图类，允许你定义强类型的状态结构。

import { StateGraph, Annotation } from '@langchain/langgraph';

// 1. 定义状态
const StateAnnotation = Annotation.Root({
  count: Annotation<number>(),
  history: Annotation<string[]>(),
});

// 2. 创建图
const graph = new StateGraph(StateAnnotation);

特点：

• ✅ 类型安全
• ✅ 高度灵活
• ✅ 支持复杂状态逻辑

MessageGraph

MessageGraph 是 StateGraph 的特化版本，状态固定为消息数组。

import { MessageGraph } from '@langchain/langgraph';

const graph = new MessageGraph();

适用场景：

• 简单的聊天机器人
• 仅需传递消息的链式调用

3️⃣ 编译过程（Compile）

图必须经过编译才能变为可执行的 Runnable。

const app = graph.compile();

编译做了什么？

1. 结构验证：检查是否有孤立节点、死循环（非预期）等。
2. 状态绑定：将 StateAnnotation 绑定到每个节点。
3. 运行时配置：注入 CheckpointSaver（用于持久化）等。

编译选项

const app = graph.compile({
  checkpointer: new MemorySaver(), // 启用记忆功能
  interruptBefore: ['human_review'], // 在特定节点前暂停
});

4️⃣ 可视化与调试

LangGraph 提供了生成 Mermaid 图表的能力，帮助你直观地理解图结构。

代码生成图表

import { StateGraph } from '@langchain/langgraph';

// ... 构建图的代码 ...

const app = graph.compile();

// 获取 Mermaid 源码
const mermaidSource = app.getGraph().drawMermaid();
console.log(mermaidSource);

典型结构可视化

线性结构

分支结构

循环结构（Agent）

💡 练习题

1. 思考题：为什么 StateGraph 比 MessageGraph 更适合复杂的企业级应用？
2. 操作题：使用 getGraph().drawMermaid() 方法，尝试打印出上一章“环境搭建”中示例代码的图结构。

📚 参考资源

官方文档

• LangGraph JS

✅ 总结

本章要点：

• 图是将业务逻辑组织成可执行流的容器。
• compile() 是图从定义到运行的必经之路。
• 可视化是调试和沟通 LangGraph 架构的最佳工具。

下一步：了解了图的骨架，我们需要填充血肉——状态管理。