基础示例教程 #

本文档中引用的文件

目录 #

  1. 简介
  2. 项目结构概览
  3. 核心组件分析
  4. 基础示例详解
  5. LLM集成示例
  6. 架构概览
  7. 详细组件分析
  8. 依赖关系分析
  9. 性能考虑
  10. 故障排除指南
  11. 结论

简介 #

LangGraphGo 是一个强大的工作流编排框架，专为构建复杂的异步处理流程而设计。本教程将通过两个核心示例：basic_example 和 basic_llm，帮助初学者快速掌握 langgraphgo 的核心概念和使用方法。

这两个示例分别展示了：

项目结构概览 #

langgraphgo 项目采用模块化架构，主要包含以下核心目录：

graph TB
subgraph "示例目录"
A[basic_example] --> A1[主程序]
A --> A2[README文档]
B[basic_llm] --> B1[LLM集成示例]
B --> B2[LangChain集成]
end
subgraph "核心库"
C[graph] --> C1[消息图]
C --> C2[状态图]
C --> C3[监听器]
C --> C4[检查点]
end
subgraph "扩展功能"
D[prebuilt] --> D1[预构建组件]
E[checkpoints] --> E1[存储后端]
F[tool] --> F1[工具集成]
end
A1 --> C
B1 --> C
D1 --> C
E1 --> C
F1 --> C

图表来源

章节来源

核心组件分析 #

图形系统架构 #

langgraphgo 的核心是基于图的工作流系统，支持多种类型的图结构：

classDiagram
class MessageGraph {
+nodes map[string]Node
+edges []Edge
+conditionalEdges map[string]func
+entryPoint string
+AddNode(name, fn)
+AddEdge(from, to)
+SetEntryPoint(name)
+Compile() Runnable
}
class StateGraph {
+nodes map[string]Node
+Schema StateSchema
+retryPolicy RetryPolicy
+AddNode(name, fn)
+SetSchema(schema)
+Compile() StateRunnable
}
class ListenableMessageGraph {
+listenableNodes map[string]ListenableNode
+AddNode(name, fn)
+AddListener(listener)
}
class CheckpointableMessageGraph {
+checkpointConfig CheckpointConfig
+SetCheckpointConfig(config)
+ListCheckpoints() []Checkpoint
}
MessageGraph <|-- ListenableMessageGraph
MessageGraph <|-- CheckpointableMessageGraph
StateGraph --> StateSchema

图表来源

节点和边系统 #

工作流的基本构建块是节点（Node）和边（Edge），它们定义了数据在系统中的流动路径：

flowchart TD
A[入口节点] --> B[处理节点1]
B --> C[条件判断]
C --> |条件1| D[分支节点1]
C --> |条件2| E[分支节点2]
D --> F[合并节点]
E --> F
F --> G[结束节点]
style A fill:#e1f5fe
style G fill:#f3e5f5
style C fill:#fff3e0

图表来源

章节来源

基础示例详解 #

基本工作流执行 #

第一个示例展示了最基础的工作流执行模式，演示了如何创建简单的线性处理流程。

图的初始化和配置 #

sequenceDiagram
participant Main as 主程序
participant Graph as MessageGraph
participant Node as 处理节点
participant Runner as 可运行实例
Main->>Graph : NewMessageGraph()
Main->>Graph : AddNode("process", processingFunction)
Main->>Graph : AddEdge("process", END)
Main->>Graph : SetEntryPoint("process")
Main->>Graph : Compile()
Graph-->>Runner : 返回可运行实例
Main->>Runner : Invoke(context, "input")
Runner->>Node : 执行处理函数
Node-->>Runner : 返回处理结果
Runner-->>Main : 返回最终状态

图表来源

关键步骤解析 #

  1. 创建图实例：使用 NewMessageGraph() 创建新的消息图
  2. 添加节点：通过 AddNode() 方法注册处理函数
  3. 设置连接：使用 AddEdge() 定义节点间的流向
  4. 配置入口点：通过 SetEntryPoint() 指定起始节点
  5. 编译执行：调用 Compile() 获取可运行实例
  6. 触发执行：通过 Invoke() 启动工作流

流式监听器示例 #

第二个示例展示了如何使用监听器实现实时进度跟踪：

sequenceDiagram
participant Main as 主程序
participant Graph as ListenableMessageGraph
participant Listener as ProgressListener
participant Node as 流式节点
Main->>Graph : NewListenableMessageGraph()
Main->>Graph : AddNode("stream_process", processingFunction)
Main->>Listener : NewProgressListener()
Main->>Node : AddListener(listener)
Main->>Graph : CompileListenable()
Main->>Graph : Invoke(context, "stream_input")
par 并行执行
Graph->>Node : 开始处理
Node->>Listener : 通知开始事件
Node->>Node : 模拟处理工作
Node->>Listener : 通知进度事件
Node->>Listener : 通知完成事件
end
Node-->>Graph : 返回处理结果
Graph-->>Main : 返回最终状态

图表来源

检查点持久化示例 #

第三个示例演示了状态持久化和恢复机制：

flowchart TD
A[创建工作流] --> B[配置检查点]
B --> C[添加多个处理节点]
C --> D[启用自动保存]
D --> E[执行工作流]
E --> F[自动生成检查点]
F --> G[查询检查点列表]
G --> H[状态恢复]
style A fill:#e3f2fd
style F fill:#f1f8e9
style H fill:#fff8e1

图表来源

章节来源

LLM集成示例 #

LangChain集成架构 #

LLM示例展示了如何将 langgraphgo 与 LangChain Go 集成，实现智能对话处理：

sequenceDiagram
participant Main as 主程序
participant Graph as MessageGraph
participant LLM as OpenAI客户端
participant Node as LLM节点
Main->>LLM : openai.New()
Main->>Graph : NewMessageGraph()
Main->>Graph : AddNode("generate", llmProcessingFunction)
Main->>Graph : AddEdge("generate", END)
Main->>Graph : Compile()
Main->>Graph : Invoke(context, initialMessages)
Graph->>Node : 执行LLM处理
Node->>LLM : GenerateContent(messages, temperature)
LLM-->>Node : 返回AI响应
Node->>Node : 构建更新的消息数组
Node-->>Graph : 返回完整对话历史
Graph-->>Main : 返回最终对话

图表来源

消息处理流程 #

LLM示例中的消息处理遵循以下模式：

  1. 初始化对话：创建包含初始消息的数组
  2. LLM调用：使用 LangChain 客户端生成响应
  3. 状态更新：将AI响应追加到对话历史
  4. 状态传播：将更新后的对话历史传递给下一个节点

章节来源

架构概览 #

整体系统架构 #

langgraphgo 采用分层架构设计，支持多种工作流模式：

graph TB
subgraph "应用层"
A[用户应用] --> B[工作流定义]
end
subgraph "执行层"
B --> C[MessageGraph]
B --> D[StateGraph]
B --> E[ListenableMessageGraph]
B --> F[CheckpointableMessageGraph]
end
subgraph "核心引擎"
C --> G[节点执行器]
D --> G
E --> G
F --> G
G --> H[状态管理]
G --> I[事件调度]
end
subgraph "存储层"
F --> J[检查点存储]
J --> K[内存存储]
J --> L[文件存储]
J --> M[数据库存储]
end
subgraph "监控层"
E --> N[监听器系统]
N --> O[进度跟踪]
N --> P[事件通知]
end

图表来源

详细组件分析 #

节点执行机制 #

节点是工作流的基本执行单元，每个节点都包含一个处理函数：

classDiagram
class Node {
+string Name
+func Function
+Execute(ctx, state) (result, error)
}
class ListenableNode {
+[]NodeListener listeners
+sync.RWMutex mutex
+AddListener(listener)
+NotifyListeners(event, state, error)
+Execute(ctx, state) (result, error)
}
class StateRunnable {
+*StateGraph graph
+Invoke(ctx, initialState) (state, error)
+InvokeWithConfig(ctx, initialState, config) (state, error)
}
class Runnable {
+*MessageGraph graph
+Invoke(ctx, initialState) (state, error)
+InvokeWithConfig(ctx, initialState, config) (state, error)
}
Node <|-- ListenableNode
StateRunnable --> StateGraph
Runnable --> MessageGraph

图表来源

状态传递机制 #

工作流中的状态传递遵循以下原则：

  1. 状态不变性：默认情况下，状态在节点间保持不变
  2. 显式更新：只有当节点返回新状态时才会更新
  3. 命令模式：支持通过 Command 对象控制执行流程
  4. Schema驱动：可选的状态模式定义更新逻辑

监听器系统 #

监听器系统提供了强大的事件通知机制：

flowchart LR
A[节点执行] --> B{有监听器?}
B --> |是| C[通知开始事件]
B --> |否| D[直接执行]
C --> E[执行节点函数]
E --> F{执行成功?}
F --> |是| G[通知完成事件]
F --> |否| H[通知错误事件]
G --> I[通知所有监听器]
H --> I
I --> J[事件处理完成]
D --> E

图表来源

章节来源

依赖关系分析 #

核心依赖图 #

langgraphgo 的依赖关系相对简洁，主要依赖于标准库和少量外部包：

graph TD
A[langgraphgo] --> B[context]
A --> C[fmt]
A --> D[sync]
A --> E[time]
F[basic_example] --> A
G[basic_llm] --> A
G --> H[langchaingo/llms]
G --> I[openai]
J[checkpoints] --> A
K[sqlite] --> A
L[redis] --> A
M[postgres] --> A
N[prebuilt] --> A
O[tool] --> A

图表来源

模块间耦合度 #

langgraphgo 设计为低耦合的模块化系统：

章节来源

性能考虑 #

并发执行优化 #

langgraphgo 支持并行节点执行，提高整体性能：

内存管理 #

扩展性设计 #

故障排除指南 #

常见问题及解决方案 #

1. 入口点未设置 #

问题：尝试编译图但未设置入口点 解决：确保调用 SetEntryPoint() 设置起始节点

2. 节点未找到 #

问题：执行时提示节点不存在 解决：检查节点名称拼写和添加顺序

3. 状态类型不匹配 #

问题：节点函数返回的状态类型不符合预期 解决：确保节点函数返回正确的状态类型

4. 监听器阻塞 #

问题：监听器处理耗时过长影响主流程 解决：在监听器中使用异步处理或快速返回

调试技巧 #

  1. 启用追踪：使用内置的追踪功能查看执行路径
  2. 检查点调试：利用检查点功能暂停和检查状态
  3. 监听器日志：添加日志监听器跟踪执行过程
  4. 可视化工具：使用图形化工具检查工作流结构

章节来源

结论 #

langgraphgo 提供了一个强大而灵活的工作流编排平台，通过本教程的介绍，您应该能够：

  1. 理解核心概念：掌握图、节点、边等基本概念
  2. 构建简单工作流：学会创建和执行基本的线性工作流
  3. 使用高级功能：了解监听器、检查点和可视化等高级特性
  4. 集成LLM功能：掌握与大型语言模型的集成方法
  5. 扩展系统功能：了解如何根据需求扩展系统能力

建议初学者从基础示例开始，逐步探索更复杂的功能，并参考项目的完整文档和示例代码。随着对核心概念的理解加深，您可以开始构建自己的工作流应用，利用 langgraphgo 强大的并发处理能力和灵活的架构设计。

通过实践这些示例，您将能够快速上手 langgraphgo 的核心工作流概念，并为构建生产级别的应用程序打下坚实基础。