知识库、插件与 RAG — 检索增强生成全链路解析

本文是「Coze Studio 源码解析系列」的第 9 篇，深入解析 Coze Studio 的知识库 RAG 全链路、插件系统设计，以及数据库与变量系统。

一、知识库 RAG 全链路

RAG（Retrieval-Augmented Generation）是 AI Agent 解决幻觉问题的核心技术。Coze Studio 实现了完整的 RAG 管线：

二、文档处理管线

2.1 文档解析器

Coze Studio 支持多种文档格式的解析：

// infra/document/parser/parser.gotype Parser interface {    Parse(ctx context.Context, doc *Document) (*ParseResult, error)}// 支持的格式// PDF、Word (.docx)、Excel (.xlsx)、Markdown、纯文本、HTML

解析器管理器根据文件类型选择合适的解析器：

// infra/document/parser/manager.gotype ParseManager struct {    parsers map[string]Parser}func(m *ParseManager) Parse(ctx context.Context, doc *Document) (*ParseResult, error) {    parser, ok := m.parsers[doc.Format]    if !ok {        return nil, fmt.Errorf(”unsupported format: %s”, doc.Format)    }    return parser.Parse(ctx, doc)}

2.2 文本切片策略

文档解析后需要进行切片（Slicing），将长文档分割成适合 Embedding 的片段：

// domain/knowledge/entity/strategy.gotype SliceStrategy struct {    MaxLength    int    // 最大切片长度    Overlap      int    // 重叠字符数    Separator    string // 分隔符}

2.3 OCR 支持

对于图片和扫描件，Coze Studio 集成了 OCR 能力：

// infra/document/ocr/ocr.gotype OCRService interface {    Recognize(ctx context.Context, image []byte) (string, error)}

三、Embedding 向量化

3.1 Embedding 接口

// infra/embedding/embedding.gotype EmbeddingService interface {    Embed(ctx context.Context, texts []string) ([][]float64, error)}

3.2 多种实现

Coze Studio 支持多种 Embedding 服务：

// infra/embedding/impl/├── ark/# 火山引擎 Ark Embedding├── http/# 通用 HTTP Embedding API└── wrap/# 包装器（缓存、批处理等）

从 go.mod 可以看到还支持 OpenAI、Gemini、Ollama 等 Embedding 模型：

// go.modgithub.com/cloudwego/eino-ext/components/embedding/arkgithub.com/cloudwego/eino-ext/components/embedding/geminigithub.com/cloudwego/eino-ext/components/embedding/ollamagithub.com/cloudwego/eino-ext/components/embedding/openai

四、混合检索架构

Coze Studio 采用Milvus 向量检索 + Elasticsearch 全文检索的混合检索架构。

4.1 向量检索（Milvus）

向量检索基于语义相似度找到最相关的文档片段：

// infra/document/searchstore/searchstore.gotype SearchStoreManager interface {    Search(ctx context.Context, opts *SearchOptions) ([]*SearchResult, error)    Upsert(ctx context.Context, docs []*VectorDoc) error    Delete(ctx context.Context, ids []string) error}

4.2 全文检索（Elasticsearch）

全文检索基于关键词匹配找到精确相关的文档：

// infra/es/es.gotype ESClient interface {    Search(ctx context.Context, index string, query *SearchQuery) (*SearchResult, error)}

4.3 结果合并与 Rerank

两种检索结果合并后，通过 Rerank 模型重新排序：

// infra/document/rerank/rerank.gotype Reranker interface {    Rerank(ctx context.Context, query string,        docs []*Document) ([]*RankedDocument, error)}

4.4 检索流程

// domain/knowledge/service/retrieve.gofunc(s *KnowledgeService) Retrieve(ctx context.Context,    knowledgeID int64, query string) ([]*entity.Slice, error) {    // 1. 查询向量化    queryVec, err := s.embedding.Embed(ctx, []string{query})    // 2. 并行执行向量检索和全文检索    var vectorResults, fulltextResults []*SearchResult    go func() {        vectorResults, _ = s.searchStore.Search(ctx, &SearchOptions{            Vector: queryVec[0],            TopK:   20,        })    }()    fulltextResults, _ = s.es.Search(ctx, index, &SearchQuery{        Query: query,        Size:  20,    })    // 3. 合并结果    merged := mergeResults(vectorResults, fulltextResults)    // 4. Rerank 重排序    ranked, err := s.reranker.Rerank(ctx, query, merged)    // 5. 返回 Top-K 结果    return ranked[:topK], nil}

五、知识库管理

5.1 知识库实体

// domain/knowledge/entity/knowledge.gotype Knowledge struct {    ID          int64    Name        string    Description string    Type        KnowledgeType   // 文本/表格/图片    Config      *KnowledgeConfig    // 处理策略    SliceStrategy  *SliceStrategy    EmbeddingModel string}// domain/knowledge/entity/document.gotype Document struct {    ID          int64    KnowledgeID int64    Name        string    Format      string          // pdf/docx/xlsx/md    Status      DocumentStatus  // 解析中/已完成/失败    Size        int64}

5.2 文档处理流程

// domain/knowledge/service/knowledge.gofunc(s *KnowledgeService) CreateDocument(ctx context.Context,    knowledgeID int64, file *UploadFile) error {    // 1. 保存文档元数据    doc := &entity.Document{        KnowledgeID: knowledgeID,        Name:        file.Name,        Format:      file.Format,        Status:      StatusProcessing,    }    s.repo.CreateDocument(ctx, doc)    // 2. 发送处理事件（异步）    s.producer.Send(ctx, &DocumentProcessEvent{        DocumentID: doc.ID,        FilePath:   file.Path,    })    return nil}// 异步处理器func(s *KnowledgeService) ProcessDocument(ctx context.Context,    event *DocumentProcessEvent) error {    // 1. 解析文档    content, err := s.parser.Parse(ctx, event.FilePath)    // 2. 切片    slices := s.sliceStrategy.Slice(content)    // 3. 向量化    vectors, err := s.embedding.Embed(ctx, slices)    // 4. 存入向量数据库    s.searchStore.Upsert(ctx, buildVectorDocs(slices, vectors))    // 5. 存入全文索引    s.es.BulkIndex(ctx, index, buildESDocs(slices))    // 6. 更新状态    s.repo.UpdateDocumentStatus(ctx, event.DocumentID, StatusCompleted)    return nil}

六、插件系统

6.1 插件架构

Coze Studio 的插件系统支持三种类型：

类型	说明
官方插件	预置的第三方服务集成（搜索、天气等）
自定义插件	用户自己开发的 API 插件
工具插件	内置工具（代码执行、数据库等）

6.2 插件数据模型

// domain/plugin/entity/type Plugin struct {    ID          int64    Name        string    Description string    IconURI     string    AuthType    AuthType     // None / APIKey / OAuth    // API 定义（OpenAPI Schema）    Manifest    *PluginManifest    Tools       []*PluginTool}type PluginTool struct {    Name        string    Description string    Parameters  *JSONSchema   // 参数定义    Endpoint    string        // API 地址    Method      string        // HTTP 方法}

6.3 插件配置与鉴权

插件配置位于 backend/conf/plugin/：

conf/plugin/├── common/│   └── oauth_schema.json# OAuth 鉴权 Schema└── pluginproduct/# 插件产品配置    ├── google_search.json    ├── weather.json    └── ...

6.4 插件执行

当 Agent 决定调用插件时：

// domain/agent/singleagent/internal/agentflow/node_tool_plugin.gofunc(n *PluginToolNode) Execute(ctx context.Context,    toolName string, params map[string]any) (any, error) {    // 1. 获取插件信息    plugin := n.pluginSVC.GetPlugin(ctx, n.pluginID)    // 2. 构建 HTTP 请求    req := buildHTTPRequest(plugin, toolName, params)    // 3. 添加鉴权信息    if plugin.AuthType == AuthTypeOAuth {        addOAuthHeader(req, plugin.AuthConfig)    }    // 4. 发送请求    resp, err := httpClient.Do(req)    // 5. 解析响应    return parseResponse(resp)}

6.5 Mock 数据支持

开发阶段可以为插件配置 Mock 数据，避免频繁调用真实 API：

// 前端 @coze-agent-ide/bot-plugin-mock-set// 后端通过 Mock 配置表管理

七、数据库与变量系统

7.1 数据库（Memory/Database）

Coze Studio 支持 Agent 关联数据库，通过自然语言查询数据：

// infra/rdb/rdb.go — 关系型数据库type RDBService interface {    Execute(ctx context.Context, sql string) (*QueryResult, error)}// infra/document/nl2sql/ — 自然语言转 SQLtype NL2SQLService interface {    Convert(ctx context.Context, question string, schema string) (string, error)}

7.2 变量系统

变量可以在智能体、工作流、应用之间共享数据：

// domain/workflow/variable/variable.gotype VariableService interface {    GetVariable(ctx context.Context, key string) (any, error)    SetVariable(ctx context.Context, key string, value any) error    ListVariables(ctx context.Context) ([]*Variable, error)}

八、Prompt 管理

// domain/prompt/├── entity/# 提示词实体├── service/# 提示词服务└── repository/# 持久化

提示词是 Agent 的灵魂，Coze Studio 支持：

Persona 提示词：定义 Agent 的人设和回复风格
系统提示词：运行时自动注入知识库、工具等上下文
提示词变量：使用 {{variable}} 语法引用动态数据
提示词模板：预定义的提示词模板库

九、总结

Coze Studio 的知识库和插件系统展示了几个关键设计：

混合检索：Milvus 向量检索 + ES 全文检索，兼顾语义和关键词
Rerank 优化：检索结果通过 Rerank 模型二次排序提升精度
异步处理：文档处理通过事件驱动异步执行，不阻塞用户操作
插件标准化：OpenAPI Schema 定义插件接口，统一调用方式
NL2SQL：自然语言转 SQL 实现智能数据库查询

下一篇预告：《二次开发指南与最佳实践》，系列最后一篇将教你如何快速上手 Coze Studio 的二次开发。