层层递进：为AI智能体设计真正的RAG检索流程

用真正的 RAG 流水线取代玩具版的检索代理是个适合放慢节奏、分步推进工作的时机。在多代理企业平台中，RetrievalAgent 最初是在一个刻意简化的本地实现上运行的。这足以验证架构的可行性，但实际生产环境需要真实的文档、嵌入向量、向量存储以及语义搜索功能。目标流程是从文档开始，经过数据摄取、分块处理和生成嵌入向量，再将其存储到 ChromaDB 中，随后进行语义检索，最终由 RetrievalAgent 以及整个平台来完成后续操作。

与其一次性构建所有功能，不如逐步添加每一层，在每个阶段都进行测试，并确保持续集成流水线始终处于正常状态。稳步推进、稳定的持续集成以及合理的架构才是最终目标。

RAG 流水线的组成部分

一个完整的流程链整合了多个独立的工程要素，下图从源文档开始展示了这些要素的构成。

Source Documents
       ↓
Document Ingestion
       ↓
    Chunking
       ↓
   Embeddings
       ↓
 Vector Storage
       ↓
Semantic Search
       ↓
Retrieved Context
       ↓
Retrieval Agent

可以同时构建所有组件，但这会使得故障定位变得困难。当检索质量不佳时，问题出在哪里？可能是文档解析、分块处理、嵌入生成、向量存储、查询逻辑、元数据或代理集成方面的问题。为每一层明确职责、定义接口规范并设定测试边界，就能让这些问题有据可查。在持续集成流程中，应遵循“构建、测试、推送、验证”的节奏，确保系统始终正常运行，然后再继续下一步。

从数据接口规范开始

在涉及任何嵌入生成或ChromaDB功能之前，首要任务是制定数据接口规范。该流程需要区分两个概念：SourceDocument和DocumentChunk。

SourceDocument指的是在被拆分之前的原始知识来源。它可以是PDF、DOCX或TXT文件，也可以是内部文档、财务报告、企业政策、技术手册或知识库内容。其概念结构如下所示：

SourceDocument
 ├── document_id
 ├── content
 ├── source
 └── metadata

因此，每份原始文档在检索架构中都会拥有一个稳定的标识。

大型企业文档通常不应被作为一个巨大的文本块嵌入其中。需要将其拆分成更小且具有意义的单元，而这正是DocumentChunk的功能：

DocumentChunk
 ├── chunk_id
 ├── document_id
 ├── content
 ├── source
 ├── chunk_index
 └── metadata

两者之间的关系是一对多：

SourceDocument
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       Chunk 0       Chunk 1      Chunk 2
          │            │            │
          └────────────┼────────────┘
                       ↓
                 Same document_id
                  + source metadata

一个来源文件可能会生成数十个数据块，甚至数百个，但每个数据块都会保留指向其原始document_id及来源的链接。一旦语义检索开始返回更大文档中的各个片段，这一链接就变得至关重要。

为何从一开始就注重可追溯性

想象一份50页的财务报告。系统可能会将其拆分为数十个数据块，而语义搜索可能只返回其中三个。系统仍需能够指出这些信息源自哪份原始文档。在检索后再重建这种关联十分脆弱，因此应在处理流程的每一步都保留这种关联。

Original Document
       ↓
SourceDocument
       ↓
DocumentChunk
       ↓
Embedding
       ↓
Vector Record
       ↓
Semantic Search
       ↓
RetrievedDocument
       ↓
Original Source

可追溯性从一开始就是数据架构的组成部分，而非事后添加的功能。

合约测试

在模型定义完成后，自动化测试会覆盖SourceDocument和DocumentChunk。这些测试会检查模型是否构建正确，以及关键字段（包括文档ID、来源信息、内容及分块索引）是否按预期运行。

这看似只是一个小里程碑，但实际上这些模型将贯穿整个检索流程：

Document Models
      ↓
   Chunking
      ↓
  Embeddings
      ↓
   ChromaDB
      ↓
  Retrieval
      ↓
    Agents

该链条起始处的合同出现故障可能会影响后续的所有环节，因此在构建更多上层基础设施之前，数据基础必须得到保护。

另一个刻意做出的选择是让这一阶段不依赖任何外部组件。这里不会发起对OpenAI的调用，也不会使用ChromaDB，测试仅用于验证文档合同。因此，快速的CI流程能够保持确定性。

Code Change
     ↓
Local Fast Tests
     ↓
Commit
     ↓
Push to GitHub
     ↓
GitHub Actions
     ↓
Clean CI Environment
     ↓
Fast Unit Tests
     ↓
CI PASSED ✅

快速开发套件不断扩展，而外部集成测试则保持独立的分类。其背后的原则是：每一层新功能加入平台时都会配备自动保护机制。

完整路线图

文档处理功能仅是第一层。以下为整个目标架构：

Enterprise Documents
        │
        ▼
     Ingestion
        │
        ▼
      Chunking
        │
        ▼
     Embeddings
        │
        ▼
     ChromaDB
   Vector Storage
        │
        ▼
 Semantic Retrieval
        │
        ▼
 Retrieved Context
        │
        ▼
  RetrievalAgent
        │
        ▼
Multi-Agent Platform

每个阶段都有特定的职责，且应能够独立被理解与测试。

接下来是分块处理

下一个组件是分块服务，它可将SourceDocument转换为多个DocumentChunk对象。

SourceDocument
      │
      ▼
ChunkingService
      │
      ├── DocumentChunk 0
      ├── DocumentChunk 1
      ├── DocumentChunk 2
      └── DocumentChunk N

随着时间推移，该服务需要处理数据块的大小与重叠问题，传递元数据及源文件详情，为每个数据块分配索引并生成稳定的标识符。其中有一个架构设计要点十分重要：数据分块功能不应由检索代理承担，因为该代理仅负责检索功能，不应同时处理文档准备工作。

嵌入向量与存储

在完成数据分块功能的实现与测试后，下一层便会生成向量嵌入结果。

DocumentChunk
      ↓
Embedding Service
      ↓
Embedding Model
      ↓
Vector Representation

每个数据块都会转化为一个向量，用以编码其含义。随后，这些向量会与嵌入的用户查询进行比对，从而找到相关内容。

DocumentChunk
      ↓
EmbeddingService
      ↓
Embedding Provider
      ↓
Vector

日后更换嵌入模型几乎不会影响RAG设计的其他部分。

嵌入模型之后是持久向量存储。在本地开发时，ChromaDB的持久化客户端能够确保索引过的知识在应用程序重启后依然存在。

DocumentChunk
      +
Embedding
      +
Metadata
      ↓
   ChromaDB
      ↓
Persistent Vector Collection

存储的记录不仅仅需要一个向量，还需包含足够的信息以维持上下文关联与可追溯性：

Vector Record
 ├── chunk_id
 ├── embedding
 ├── content
 ├── document_id
 ├── source
 ├── chunk_index
 └── metadata

这样检索就能返回有意义的文档上下文，而不仅仅是相似的向量。

查询

当数据存储完成后，系统即可进行语义搜索。查询路径为：

User Query
    ↓
Query Embedding
    ↓
ChromaDB Similarity Search
    ↓
Top-K Relevant Chunks
    ↓
Scores + Metadata
    ↓
Retrieved Context

语义检索并非完全依赖精确的关键词匹配，而是寻找在概念上与用户请求相关的内容片段。随后这些结果会被转换为平台已使用的标准化检索格式。

重新连接智能体

只有当检索基础设施正常运行时，整个流程才会重新接入 RetrievalAgent。从智能体的角度来看，情况依然很简单：

AgentRequest
     ↓
RetrievalAgent
     ↓
RetrievalService
     ↓
Relevant Documents
     ↓
Structured RetrievalResult

RetrievalService背后，其实现方式要复杂得多：

RetrievalService
      ↓
Query Embedding
      ↓
ChromaDB
      ↓
Semantic Search
      ↓
Ranking
      ↓
Retrieved Context

分离这一点很重要。检索代理应将检索视为一项功能，无需了解向量数据库、嵌入生成、分块存储或文档导入等相关内容。

最初的代理在本地数据上运行，其架构大致如下：

RetrievalAgent
      ↓
RetrievalService
      ↓
Local Documents

该实现现在可以朝着更丰富的方向发展：

RetrievalAgent
      ↓
RetrievalService
      ↓
Semantic Retrieval
      ↓
ChromaDB
      ↓
Embedded Enterprise Documents

注意那些保持不变的部分：从 RetrievalAgent 到 RetrievalService 的链接。只有该契约背后的基础设施会发生变化，这也正是为什么在向量数据库出现之前就先创建了检索抽象层。基础设施应当能够自由发展，而不必强制重新设计代理架构。

融入平台

RAG 流水线并非独立存在，它的作用是为更大的多代理系统提供基于实际数据的企业知识。

User
                          │
                          ▼
                    Supervisor Agent
                          │
                          ▼
                     Planning Agent
                          │
                          ▼
                    Execution Plan
                          │
                          ▼
                     Agent Registry
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
       RetrievalAgent  ResearchAgent AnalysisAgent
             │
             ▼
      RetrievalService
             │
             ▼
         RAG Pipeline
             │
             ▼
      Relevant Context
             │
             ▼
       Downstream Agents

在那张图中，检索代理将多个代理执行所在的层与存储企业知识的那层连接起来。

有一点需要特别强调：RAG并非简单的“添加一个向量数据库”那么简单。一个完善的检索架构涉及诸多决策：

• 文档的格式化与导入
• 分块处理及嵌入向量生成
• 向量存储与元数据管理
• 语义检索与排序
• 来源可追溯性
• 代理集成
• 测试与监控

向量数据库只是整个庞大检索系统中的一个组成部分。

刻意设计的重复模式

实现这一目标的工程流程是刻意设计成重复性的：

Build One Layer
      ↓
Add Unit Tests
      ↓
Run Fast Suite
      ↓
Push to GitHub
      ↓
CI Validates
      ↓
Keep Green
      ↓
Build Next Layer

它允许在保持对现有系统信心的同时逐步增加复杂性。无需一次性添加五个组件并同时进行调试，而是会在每新增一个功能之前对其进行验证。

实际开发流程的第一个里程碑已经完成：包括SourceDocument合约、DocumentChunk合约、针对这两种模型的测试，以及一次成功的快速持续集成测试。接下来的路线图为：

1. Document Contract             ✅ COMPLETE
          ↓
2. Chunking Service              ← NEXT
          ↓
3. Embedding Service
          ↓
4. ChromaDB Integration
          ↓
5. Semantic Retrieval
          ↓
6. RetrievalAgent Integration
          ↓
7. End-to-End RAG Pipeline

在进入下一阶段之前，每个层次都会被独立实现并测试。

为何这很重要

第一个检索代理证明了代理架构是可行的。现在的目标是用真正的基础设施取代其临时的检索方式，从本地检索逐步过渡到文档处理流程、分块技术、嵌入模型、向量存储、语义搜索，最终实现基于RAG的代理。由于该代理依赖于服务抽象层而非直接依赖ChromaDB，因此无需重新设计多代理平台即可实现这些改进。

还有一个更普遍的原则：为那些可能发生变化的组件构建稳定的接口规范。模型会更新，向量数据库可能会更换，分块策略也会演变，检索算法也会不断改进，但围绕这些组件的平台无需每次都重新编写。

正在构建的其实是一种属于企业多智能体平台内部的检索能力，而非一次性的RAG演示。在该体系中，监督器负责协调调度，注册表用于解析各种能力，专用智能体执行任务，RAG提供基于事实的知识支持，测试机制保障行为规范，持续集成工具监控每一次变更，而可观测性功能则用于评估生产环境的表现。其实现方法始终如一：构建一个层，进行测试，将其部署，保持持续集成状态正常，然后再构建下一个层。