基于ChromaDB与嵌入技术的多智能体平台语义检索

企业多智能体AI平台项目又迎来了一个新的里程碑：其检索流程现在能够实现真正的语义搜索，借助存储在ChromaDB中的嵌入向量。该架构已从单纯的文档准备阶段发展到完整的检索流程，依次包括SourceDocument、DocumentChunker、EmbeddingService、OpenAI Embeddings、ChromaDB、语义搜索，最终生成RetrievedDocument。

这无疑是一个重要的阶段转变。该平台不再仅负责文档准备和嵌入向量生成，还能存储向量化企业知识，通过语义进行搜索，对相关内容块进行排序，并返回结构化结果。在构建过程中还发现了一些检索质量方面的问题，必须在将这些组件整合到RetrievalAgent之前解决。

检索流程逐渐成型

检索架构的结构如下：

Enterprise Documents
        │
        ▼
   SourceDocument
        │
        ▼
 DocumentChunker
        │
        ▼
  DocumentChunk[]
        │
        ▼
 EmbeddingService
        │
        ▼
 OpenAI Embeddings
        │
        ▼
     ChromaDB
        │
        ▼
 Semantic Search
        │
        ▼
RetrievedDocument[]
        │
        ▼
  RetrievalAgent

每一层都只承担一项职责，这是经过刻意设计的。我们的目标从来不是创建一个能同时完成加载文件、分割文本、生成嵌入向量、管理向量数据库、执行检索并输出答案的庞大RAG函数。相反，该系统是由具有明确边界的分层架构构成的。

第一阶段：源文档

一切始于企业知识。这些内容可能来自PDF、DOCX和TXT文件、财务报告、内部政策、技术文档、研究资料以及企业知识库。在进入处理流程之前，SourceDocument模型会为这些材料赋予统一的结构。从概念上来看，其结构如下：

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

这里重要的原则是可追溯性。无论之后检索到什么内容，都必须能够追溯到其来源。

第二阶段：分块

大型文档通常不应作为一个整体被嵌入。DocumentChunker会将每个SourceDocument拆分成更小的部分，以便后续检索：

SourceDocument
      │
      ▼
DocumentChunker
      │
      ├── Chunk 0
      ├── Chunk 1
      ├── Chunk 2
      └── Chunk N

每个分块都保留着其 chunk_id、document_id、content、source、chunk_index 以及元数据。因此，语义搜索可以在较小的信息单元上运行，同时仍能与原始文档保持关联。

提升分块质量

在实际的检索流程中发现了一个问题：基于字符的分块方式可能在不当的位置切断普通文本，有时甚至会直接切过一个单词。这样的分界线可能会导致某个分块以如下形式结束：

...important financial risks for

接着是一段类似这样的内容：

the upcoming quarter...

或者在更糟糕的情况下，单词中间会出现分割。这类片段在技术上虽属有效，但检索质量并不仅仅取决于数据结构是否有效。边界决定了被嵌入内容的语义质量。

因此，分块策略调整为：对于普通散文优先使用单词边界，而对于没有有效空白字符的文本则退而使用字符边界。现在的分块器具有两种处理方式：

Normal prose
    ↓
Prefer word-aware boundaries

Text without whitespace
    ↓
Fallback to character boundaries

这虽只是一个小小的实现细节，却蕴含着重要的架构启示：通过测试并不意味着检索质量良好，真实数据能够揭示出孤立单元测试往往无法显示的问题。

第三阶段：嵌入向量

当数据块准备就绪后，EmbeddingService会将其中的文本转换为数值向量。

DocumentChunk
      │
      ▼
EmbeddingService
      │
      ▼
Embedding Model
      │
      ▼
Vector Representation

该服务支持对查询使用单文本嵌入，而对文档片段则使用批量嵌入。早前的本地集成测试已确认向量维度为1,536。这一数值本身并非关键，重要的是嵌入实现被限制在服务边界之内，因此检索代理无需知晓向量是如何生成的。

第4阶段：ChromaDB向量存储

下一层是持久化向量存储。现在每个文档片段都可以与其对应的向量和元数据一起被存储。从概念上来说：

DocumentChunk
      +
Embedding
      +
Metadata
      │
      ▼
   ChromaDB
      │
      ▼
Persistent Vector Collection

向量记录可以存储以下信息：

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

单纯的向量对应用程序的其他部分毫无用处。平台需要获取实际的内容，并且需要知道这些内容来自何处。

第5阶段：语义搜索

由于嵌入的片段存储在ChromaDB中，系统便能够进行语义检索。查询路径如下：

User Query
     │
     ▼
EmbeddingService
     │
     ▼
Query Embedding
     │
     ▼
   ChromaDB
     │
     ▼
Similarity Search
     │
     ▼
Top-K Relevant Chunks
     │
     ▼
RetrievedDocument[]

检索方式已从寻找包含完全相同单词的文档，转变为查找含义最符合查询需求的文本片段。这正是RAG背后的核心功能之一。

相似度度量的修正

实际测试还暴露了第二个问题。向量数据库支持不同的距离或相似度度量方式，如果集合使用某种度量标准，而应用程序却将返回的距离值按另一种标准解读，那么相关性评分就会产生误导。对于该流程，ChromaDB集合被明确配置为使用余弦距离，这样检索层就能始终将结果视为基于余弦值的相似度。

Query Embedding
      │
      ▼
ChromaDB
      │
      ▼
Cosine Distance
      │
      ▼
Similarity Score
      │
      ▼
Ranked Results

语义检索并不仅仅是返回文档，还涉及理解这些文档的相关性。

真实的检索结果

在完成分块处理和相似度修正后，该流程使用一个真实的金融风险查询进行了测试。排序后的结果对应的相似度分数分别为0.6181、0.5520和0.4198，检索到的内容包含了关于流动性风险和市场波动性的相关信息。因此，该流程成功完成了整个处理流程：

Question
   ↓
Query Embedding
   ↓
ChromaDB
   ↓
Semantic Similarity
   ↓
Relevant Chunks
   ↓
Financial Risk Context

在那一刻，检索基础设施不再仅仅是设置工作，而是开始展现出真正的语义知识检索能力。

为何真正的检索测试如此重要

模拟单元测试依然具有极高的价值。它们能够提升效率、确保确定性、保障持续集成流程的安全性、无需任何外部API成本、提供可控的故障场景以及实现应用逻辑的隔离。不过，它们无法回答所有问题。模拟测试可以确认某个功能在结构上是否正常运行：

EmbeddingService
      ↓
Expected Vector

但它无法完全证明以下链条能够带来良好的检索效果：

Real Document
      ↓
Real Chunking
      ↓
Real Embedding
      ↓
Real Vector Database
      ↓
Real Semantic Query
      ↓
Useful Context

因此，测试策略将多种验证层级分开处理。

测试策略

该平台正朝着三种互补的测试层级发展。

单元测试速度快且结果可预测，应纳入常规的持续集成流程中：

Application Logic
      ↓
Mock External Dependencies
      ↓
Controlled Results
      ↓
Assertions

集成测试用于验证实际基础设施，可独立于快速的CI流程运行：

Application
      ↓
Real Embedding Provider
      ↓
Real ChromaDB
      ↓
End-to-End Retrieval

随着平台的成熟，性能与弹性测试变得必不可少：

Realistic Workload
      ↓
Concurrent Requests
      ↓
Latency
Throughput
Rate Limits
Failures
Cost
Scalability

一个可投入生产的 AI 系统需要这三者。在单元测试中模拟外部服务并不能替代集成测试，而集成测试也无法取代性能测试。每一层都旨在解决不同的工程问题。

CI 持续正常运行

经过检索性能优化后，快速测试套件状态良好，17 项测试通过，2 项集成测试被跳过。这一点很重要，因为 RAG 流水线在日益复杂化的同时仍能保持确定的 CI 验证机制。开发流程将继续如下进行：

Code Change
     ↓
Fast Unit Tests
     ↓
Commit
     ↓
Push
     ↓
GitHub Actions
     ↓
CI Validation
     ↓
Keep Green

针对真实服务的测试会作为独立进程持续运行。

将RAG连接到多智能体平台

检索基础设施并非独立存在，它的目标是成为更大规模多智能体系统的知识层，整体架构正朝着这个方向发展：

User
                          │
                          ▼
                    Supervisor Agent
                          │
                          ▼
                     Planning Agent
                          │
                          ▼
                    Execution Plan
                          │
                          ▼
                     Agent Registry
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
      RetrievalAgent ResearchAgent AnalysisAgent
             │
             ▼
      RetrievalService
             │
             ▼
      EmbeddingService
             │
             ▼
          ChromaDB
             │
             ▼
      Semantic Search
             │
             ▼
      Relevant Context
             │
             ▼
       Downstream Agents

这就是 RAG 与多智能体协调开始融合的节点。

保持检索智能体的简洁性

一个关键目标就是让 RetrievalAgent 专注于自身的任务。它无需了解分块算法、嵌入实现方式、向量维度、ChromaDB 的内部结构、相似度计算方法或存储配置。相反：

RetrievalAgent
      ↓
RetrievalService
      ↓
VectorStoreService
      ↓
EmbeddingService + ChromaDB

代理会请求相关知识，而检索基础设施则决定如何找到这些知识。这种分离使得底层实现可以不断演进，而无需重写代理代码。

下一个里程碑：替换临时检索机制

下一步很明确。检索代理仍需直接连接到真正的检索基础设施。目前的状况如下：

BEFORE

RetrievalAgent
      ↓
Temporary Local Documents

目标就是这个：

NEXT

RetrievalAgent
      ↓
RetrievalService
      ↓
VectorStoreService
      ↓
EmbeddingService
      ↓
ChromaDB
      ↓
Semantic Search
      ↓
Enterprise Knowledge

完成该集成后，代理将不再返回临时的硬编码结果，而是从真实的索引文档集合中获取知识。

从基础设施到多代理执行

这一集成标志着又一次转变。迄今为止的大部分工作都集中在构建检索基础设施上。一旦RetrievalAgent开始使用真实的语义处理流程，该架构就能支持如下工作流：

User Request
      ↓
Supervisor
      ↓
Planning Agent
      ↓
Execution Plan
      ↓
Retrieval Agent
      ↓
Enterprise Knowledge
      ↓
Analysis Agent
      ↓
Report Agent
      ↓
Quality Review
      ↓
Final Response

RAG由此成为更广泛的多智能体执行系统中的一项功能，而不再是一个独立的检索功能。

未来展望

检索技术的发展路径正从基础组件逐步迈向面向实际应用的功能：

Document Contracts               ✅
        ↓
Chunking                         ✅
        ↓
Embeddings                       ✅
        ↓
ChromaDB Vector Storage          ✅
        ↓
Semantic Search                  ✅
        ↓
RetrievalAgent Integration       ← NEXT
        ↓
Reranking
        ↓
Caching & Cost Controls
        ↓
Observability & Metrics
        ↓
Multi-Tenant Isolation
        ↓
Production Hardening

随着平台从功能架构转向企业级运营，后期阶段的重要性日益凸显。

生产环境中的RAG需要超越简单的检索功能

从ChromaDB中获取相关内容仅是重要里程碑，并非架构的终点。一个真正的生产级检索平台最终必须能够处理：

• 重新排序，因为初始的向量相似度并不总能给出最佳顺序。
• 缓存机制，因为重复的嵌入和搜索会增加延迟与成本。
• 可观测性，以便能够监测检索延迟、嵌入延迟、文档数量、得分、故障情况以及成本等指标。
• 模型与向量空间的演化，因为更换嵌入模型可能需要使用版本化的索引并实施受控的重新嵌入操作。
• 速率限制处理，因为外部AI服务提供商会施加一些非确定性的运营约束。

多租户隔离，因为企业数据不能拥有无限制的检索边界。

模式契约，即确保数据摄入、嵌入、存储、检索及代理层之间的接口稳定性。

在真实的并发场景和数据量条件下进行性能测试。

这些内容应当被纳入发展路线图，但需在稳定的框架下逐步添加，而非从一开始就混为一谈进行大规模实现。

工程原则

此阶段最重要的经验是：先设计抽象层，用真实数据验证其行为，再随着架构的完善逐步强化其生产环境适用性。这一发展过程是经过深思熟虑的：

Data Contract
     ↓
Chunking
     ↓
Unit Testing
     ↓
Embeddings
     ↓
Mocked Provider Testing
     ↓
Real Integration Validation
     ↓
Vector Storage
     ↓
Semantic Retrieval
     ↓
Retrieval Quality Improvements
     ↓
Agent Integration

每个阶段都会面临不同类型的问题，这正是渐进式架构能够发挥优势的原因。

从文档到多智能体执行

更宏大的愿景正逐渐清晰：

Enterprise Knowledge
        ↓
Document Processing
        ↓
Chunking
        ↓
Embeddings
        ↓
Vector Storage
        ↓
Semantic Retrieval
        ↓
Retrieval Agent
        ↓
Multi-Agent Orchestration
        ↓
Analysis + Research + Reporting
        ↓
Quality Review
        ↓
Grounded Enterprise Response

RAG并非整个平台，它只是让专用智能体在基于企业实际背景的环境中工作的知识基础设施。

当前里程碑

目前已实现的功能包括：统一的文档模型、普通分块与基于词边界的分块功能、带有模拟单元测试及实际验证的嵌入服务、明确设置了余弦相似度的持久化ChromaDB存储、能够返回排序结果的语义搜索功能，以及17个通过测试的快速测试套件。下一个里程碑是将RetrievalAgent接入实际的语义检索流程，届时系统将不再仅仅包含RAG子系统，而是开始实现基于RAG的多智能体协同执行功能。

企业级人工智能并不意味着只需将大型语言模型接入向量数据库即可宣告成功。各层之间需要契约约束，契约需要测试验证，集成方案需要实际检验，而系统本身也需要发展空间。技术流程已从单纯的文档、片段、嵌入向量发展到涵盖文档、片段、嵌入向量、ChromaDB、语义搜索以及相关企业上下文的内容。接下来的发展是让这些上下文流入检索代理，进而实现多智能体协同执行。工作循环始终如一：构建、测试、评估、改进、集成与扩展。