预构建组件 API 参考文档 #

本文档中引用的文件

目录 #

  1. 简介
  2. CreateAgent 组件
  3. RAGPipeline 组件
  4. CreateSupervisor 组件
  5. 工具组件
  6. 架构概览
  7. 使用示例
  8. 最佳实践

简介 #

langgraphgo 提供了一套高级预构建组件，简化了复杂 AI 应用程序的开发。这些组件包括：

这些组件基于 langgraphgo 的核心图执行引擎，提供了开箱即用的功能和灵活的配置选项。

CreateAgent 组件 #

CreateAgent 是一个高级代理创建函数，能够快速构建具备工具调用能力的智能代理。

核心功能 #

flowchart TD
A[CreateAgent] --> B[配置选项]
B --> C[系统消息]
B --> D[状态修改器]
B --> E[检查点存储]
A --> F[代理节点]
A --> G[工具节点]
F --> H[模型推理]
F --> I[工具调用解析]
G --> J[工具执行]
G --> K[结果处理]
H --> L[条件边]
I --> L
J --> M[消息合并]
K --> M
L --> N{是否有工具调用?}
N --> |是| G
N --> |否| O[结束]

图表来源

函数签名 #

func CreateAgent(model llms.Model, inputTools []tools.Tool, opts ...CreateAgentOption) (*graph.StateRunnable, error)

参数说明 #

参数 类型 描述
model llms.Model 语言模型实例，用于推理和工具调用
inputTools []tools.Tool 工具列表，代理可以调用的外部功能
opts …CreateAgentOption 可选配置选项

配置选项 #

WithSystemMessage #

设置代理的系统提示词。

func WithSystemMessage(message string) CreateAgentOption

参数：

使用示例：

agent, err := CreateAgent(model, tools,
    WithSystemMessage("你是一个有用的天气助手。始终保持礼貌。"),
    WithStateModifier(customModifier),
)

WithStateModifier #

设置状态修改器函数，在发送给模型之前修改消息列表。

func WithStateModifier(modifier func(messages []llms.MessageContent) []llms.MessageContent) CreateAgentOption

参数：

使用示例：

modifier := func(messages []llms.MessageContent) []llms.MessageContent {
    log.Printf("当前消息数量: %d", len(messages))
    return messages
}

agent, err := CreateAgent(model, tools, WithStateModifier(modifier))

WithCheckpointer #

设置检查点存储，用于保存和恢复代理状态。

func WithCheckpointer(checkpointer graph.CheckpointStore) CreateAgentOption

注意： 当前是占位实现，可能尚未完全集成到图执行中。

返回值 #

返回一个 *graph.StateRunnable 实例，表示编译后的代理图。

内部架构 #

classDiagram
class CreateAgentOptions {
+string SystemMessage
+func StateModifier
+CheckpointStore Checkpointer
}
class StateRunnable {
+Invoke(ctx, state) interface
+InvokeWithConfig(ctx, state, config) interface
}
class ToolExecutor {
+Execute(ctx, invocation) string
+ExecuteMany(ctx, invocations) []string
}
CreateAgent --> CreateAgentOptions
CreateAgent --> StateRunnable
StateRunnable --> ToolExecutor

图表来源

章节来源

RAGPipeline 组件 #

RAGPipeline 提供了构建检索增强生成系统的完整框架，支持多种 RAG 模式和配置选项。

核心组件 #

graph TB
subgraph "RAG 管道"
A[查询输入] --> B[检索节点]
B --> C[重排序节点]
C --> D[生成节点]
D --> E[格式化节点]
F[向量存储] -.-> B
G[嵌入模型] -.-> F
H[重排序器] -.-> C
I[LLM] -.-> D
J[文档加载器] -.-> G
K[文本分割器] -.-> G
end

图表来源

RAGConfig 配置 #

RAGConfig 定义了 RAG 系统的所有配置选项：

配置项 类型 默认值 描述
TopK int 4 检索的文档数量
ScoreThreshold float64 0.7 相关性阈值
UseReranking bool false 是否使用重排序
UseFallback bool false 是否使用回退搜索
SystemPrompt string 帮助提示 系统提示词
IncludeCitations bool true 是否包含引用
MaxTokens int 1000 最大令牌数
Temperature float64 0.0 温度参数

构建方法 #

BuildBasicRAG #

构建基础 RAG 管道：检索 → 生成

func (p *RAGPipeline) BuildBasicRAG() error

特点：

BuildAdvancedRAG #

构建高级 RAG 管道：检索 → 重排序 → 生成 → 引用格式化

func (p *RAGPipeline) BuildAdvancedRAG() error

特点：

BuildConditionalRAG #

构建条件 RAG 管道：根据相关性阈值决定是否使用回退搜索

func (p *RAGPipeline) BuildConditionalRAG() error

特点：

节点内部逻辑 #

retrieve 节点 #

负责从向量存储中检索相关文档。

flowchart TD
A[查询] --> B[GetRelevantDocuments]
B --> C[返回文档列表]
C --> D[更新状态]
E[Retriever接口] -.-> B
F[VectorStore] -.-> E

图表来源

generate 节点 #

使用检索到的文档生成答案。

flowchart TD
A[构建上下文] --> B[构建提示词]
B --> C[调用LLM]
C --> D[提取回答]
D --> E[更新状态]
F[文档列表] --> A
G[系统提示词] --> B
H[温度参数] --> C

图表来源

rerank 节点 #

对检索到的文档进行重新排序以提高质量。

flowchart TD
A[查询 + 文档列表] --> B{是否有重排序器?}
B --> |是| C[Rerank方法]
B --> |否| D[简单评分]
C --> E[返回重排序结果]
D --> F[基于位置的评分]
F --> E
E --> G[更新文档顺序]

图表来源

RAGState 状态结构 #

type RAGState struct {
    Query              string
    Documents          []Document
    RetrievedDocuments []Document
    RankedDocuments    []DocumentWithScore
    Context            string
    Answer             string
    Citations          []string
    Metadata           map[string]interface{}
}

组件接口 #

DocumentLoader #

文档加载接口，支持从各种源加载文档。

type DocumentLoader interface {
    Load(ctx context.Context) ([]Document, error)
}

TextSplitter #

文本分割接口，将长文档分割成较小的块。

type TextSplitter interface {
    SplitDocuments(documents []Document) ([]Document, error)
}

Embedder #

嵌入生成接口，将文本转换为向量表示。

type Embedder interface {
    EmbedDocuments(ctx context.Context, texts []string) ([][]float64, error)
    EmbedQuery(ctx context.Context, text string) ([]float64, error)
}

VectorStore #

向量存储接口，支持相似性搜索。

type VectorStore interface {
    AddDocuments(ctx context.Context, documents []Document, embeddings [][]float64) error
    SimilaritySearch(ctx context.Context, query string, k int) ([]Document, error)
    SimilaritySearchWithScore(ctx context.Context, query string, k int) ([]DocumentWithScore, error)
}

章节来源

CreateSupervisor 组件 #

CreateSupervisor 创建一个监督者代理，能够协调多个子代理的工作流程。

协调机制 #

sequenceDiagram
participant U as 用户
participant S as 监督者
participant A1 as 代理1
participant A2 as 代理2
participant FIN as FINISH
U->>S : 初始请求
S->>S : 分析请求并选择下一个代理
S->>A1 : 路由到代理1
A1->>A1 : 执行任务
A1->>S : 返回结果
S->>S : 决定下一步
alt 有更多任务
S->>A2 : 路由到代理2
A2->>A2 : 执行任务
A2->>S : 返回结果
S->>S : 决定是否完成
end
alt 完成所有任务
S->>FIN : 发送FINISH信号
FIN->>U : 返回最终结果
end

图表来源

函数签名 #

func CreateSupervisor(model llms.Model, members map[string]*graph.StateRunnable) (*graph.StateRunnable, error)

参数说明 #

参数 类型 描述
model llms.Model 用于决策的语言模型
members map[string]*graph.StateRunnable 代理成员映射表

成员代理管理 #

监督者通过以下方式管理成员代理：

  1. 动态路由: 根据当前状态和用户请求动态选择下一个代理
  2. 状态共享: 所有成员代理共享相同的状态模式
  3. 循环协调: 支持多个代理的循环执行直到完成

路由机制 #

flowchart TD
A[接收状态] --> B[准备系统提示词]
B --> C[定义路由工具]
C --> D[调用模型]
D --> E{模型选择}
E --> |代理名称| F[路由到指定代理]
E --> |FINISH| G[完成流程]
F --> H[执行代理]
H --> I[返回结果]
G --> J[结束]

图表来源

使用示例 #

// 创建数学专家代理
mathAgent, err := prebuilt.CreateReactAgent(model, []tools.Tool{CalculatorTool{}})

// 创建通用助理代理  
generalAgent, err := prebuilt.CreateReactAgent(model, []tools.Tool{})

// 创建监督者
members := map[string]*graph.StateRunnable{
    "MathExpert":       mathAgent,
    "GeneralAssistant": generalAgent,
}

supervisor, err := prebuilt.CreateSupervisor(model, members)

章节来源

工具组件 #

ToolExecutor #

ToolExecutor 提供工具执行功能，支持单个和批量工具调用。

classDiagram
class ToolExecutor {
+map[string]tools.Tool tools
+Execute(ctx, invocation) string
+ExecuteMany(ctx, invocations) []string
+ToolNode(ctx, state) interface
}
class ToolInvocation {
+string Tool
+string ToolInput
}
ToolExecutor --> ToolInvocation
ToolExecutor --> tools.Tool

图表来源

工具节点 #

ToolNode 是一个图节点函数，专门用于执行工具调用。

支持的状态格式：

章节来源

架构概览 #

graph TB
subgraph "预构建组件层"
A[CreateAgent]
B[RAGPipeline]
C[CreateSupervisor]
end
subgraph "核心图执行引擎"
D[StateGraph]
E[StateRunnable]
F[MessageGraph]
end
subgraph "工具组件"
G[ToolExecutor]
H[工具节点]
end
subgraph "数据组件"
I[Document]
J[VectorStore]
K[Embedder]
end
A --> D
B --> F
C --> D
D --> E
F --> E
A --> G
G --> H
B --> I
B --> J
B --> K

图表来源

使用示例 #

CreateAgent 示例 #

// 定义工具
type WeatherTool struct{}
func (t *WeatherTool) Name() string { return "get_weather" }
func (t *WeatherTool) Description() string { return "获取城市天气" }
func (t *WeatherTool) Call(ctx context.Context, input string) (string, error) {
    return fmt.Sprintf(" %s 天气晴朗，气温 25°C", input), nil
}

// 创建代理
agent, err := prebuilt.CreateAgent(model, []tools.Tool{&WeatherTool{}},
    prebuilt.WithSystemMessage("你是一个有用的天气助手。始终保持礼貌。"),
    prebuilt.WithStateModifier(func(msgs []llms.MessageContent) []llms.MessageContent {
        log.Printf("当前消息数量: %d", len(msgs))
        return msgs
    }),
)

// 运行代理
result, err := agent.Invoke(context.Background(), map[string]interface{}{
    "messages": []llms.MessageContent{
        llms.TextParts(llms.ChatMessageTypeHuman, "旧金山的天气怎么样？"),
    },
})

章节来源

RAGPipeline 基础示例 #

// 创建文档
documents := []prebuilt.Document{
    {
        PageContent: "LangGraph 是一个用于构建带有 LLM 的有状态多参与者应用程序的库。",
        Metadata: map[string]interface{}{
            "source": "langgraph_intro.txt",
            "topic":  "LangGraph",
        },
    },
}

// 创建向量存储和检索器
embedder := prebuilt.NewMockEmbedder(128)
vectorStore := prebuilt.NewInMemoryVectorStore(embedder)
retriever := prebuilt.NewVectorStoreRetriever(vectorStore, 3)

// 配置 RAG 管道
config := prebuilt.DefaultRAGConfig()
config.Retriever = retriever
config.LLM = llm
config.TopK = 3

// 构建管道
pipeline := prebuilt.NewRAGPipeline(config)
err = pipeline.BuildBasicRAG()

// 编译和运行
runnable, err := pipeline.Compile()
result, err := runnable.Invoke(context.Background(), prebuilt.RAGState{
    Query: "什么是 LangGraph？",
})

章节来源

RAGPipeline 高级示例 #

// 创建高级 RAG 配置
config := prebuilt.DefaultRAGConfig()
config.Retriever = retriever
config.Reranker = reranker
config.LLM = llm
config.TopK = 5
config.UseReranking = true
config.IncludeCitations = true

// 构建高级管道
pipeline := prebuilt.NewRAGPipeline(config)
err = pipeline.BuildAdvancedRAG()

// 运行查询
result, err := runnable.Invoke(context.Background(), prebuilt.RAGState{
    Query: "LangGraph 在多代理系统中的应用是什么？",
})

finalState := result.(prebuilt.RAGState)
fmt.Printf("答案: %s\n", finalState.Answer)
fmt.Printf("引用: %v\n", finalState.Citations)

章节来源

CreateSupervisor 示例 #

// 创建数学专家代理
mathAgent, err := prebuilt.CreateReactAgent(model, []tools.Tool{CalculatorTool{}})

// 创建通用助理代理
generalAgent, err := prebuilt.CreateReactAgent(model, []tools.Tool{})

// 创建监督者
members := map[string]*graph.StateRunnable{
    "MathExpert":       mathAgent,
    "GeneralAssistant": generalAgent,
}

supervisor, err := prebuilt.CreateSupervisor(model, members)

// 执行多步骤任务
result, err := supervisor.Invoke(context.Background(), map[string]interface{}{
    "messages": []llms.MessageContent{
        llms.TextParts(llms.ChatMessageTypeHuman, "计算 10 * 5 然后告诉我关于结果的笑话。"),
    },
})

章节来源

条件 RAG 示例 #

// 配置条件 RAG
config := prebuilt.DefaultRAGConfig()
config.Retriever = retriever
config.Reranker = reranker
config.LLM = llm
config.TopK = 2
config.ScoreThreshold = 0.5
config.UseReranking = true
config.UseFallback = true

// 构建条件管道
pipeline := prebuilt.NewRAGPipeline(config)
err = pipeline.BuildConditionalRAG()

// 测试低相关性查询
result, err := runnable.Invoke(context.Background(), prebuilt.RAGState{
    Query: "今天的天气怎么样？",
})

// 检查是否触发了回退搜索
if finalState.Metadata != nil {
    if fallbackUsed, ok := finalState.Metadata["fallback_used"]; ok && fallbackUsed.(bool) {
        fmt.Println("触发了回退搜索")
    }
}

章节来源

最佳实践 #

CreateAgent 最佳实践 #

  1. 系统消息设计

    • 明确代理的角色和职责
    • 设定适当的语气和风格
    • 包含必要的约束和限制

  2. 工具选择

    • 只添加真正需要的工具
    • 确保工具描述清晰准确
    • 考虑工具的安全性和可靠性

  3. 状态管理

    • 使用状态修改器处理特殊需求
    • 注意消息历史的长度限制
    • 实现适当的错误处理

RAGPipeline 最佳实践 #

  1. 文档组织

    • 合理的文档分割策略
    • 丰富的元数据信息
    • 保持文档质量一致性

  2. 检索优化

    • 选择合适的 TopK 值
    • 调整相关性阈值
    • 使用重排序提升质量

  3. 生成控制

    • 设置合理的最大令牌数
    • 调整温度参数
    • 使用适当的系统提示词

CreateSupervisor 最佳实践 #

  1. 代理设计

    • 明确每个代理的专长领域
    • 避免功能重叠
    • 设计清晰的边界

  2. 工作流设计

    • 合理安排代理执行顺序
    • 处理代理间的依赖关系
    • 实现优雅的错误恢复

  3. 监控和调试

    • 记录代理执行过程
    • 监控性能指标
    • 提供详细的日志信息

性能优化 #

  1. 并发处理

    • 利用并行节点处理独立任务
    • 实现异步工具调用
    • 优化内存使用

  2. 缓存策略

    • 缓存嵌入结果
    • 缓存检索结果
    • 实现智能的检查点机制

  3. 资源管理

    • 控制并发连接数
    • 实现超时机制
    • 监控资源使用情况