> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 概览

> Zeus 知识库系统概览 — Agentic RAG 架构与技术选型

Zeus 的知识库系统实现了 **Agentic RAG**（检索增强生成），让 Agent 能够主动从用户上传的文档中检索相关信息。与传统 RAG 不同，Zeus 的知识库是 Agent 的一个 **专业工具** — Agent 自主决定何时调用检索、支持多轮查询和结果验证，并与其他工具（代码执行、网络搜索等）协同工作。

***

## 核心架构

```mermaid theme={null}
graph TD
    subgraph Agent["Zeus Agent"]
        tool["search_knowledge_base<br/>Agentic RAG 工具"]
        parse["parse_resource_file<br/>文档解析工具"]
    end

    subgraph Services["Service Layer"]
        rag["RAGService<br/>检索 + 格式化"]
        doc["DocumentService<br/>上传 + 解析 + 分块"]
        chunker["SmartChunker<br/>智能分块"]
    end

    subgraph Storage["存储层"]
        pgvector["PostgreSQL pgvector<br/>向量存储 + 元数据过滤"]
        bm25["BM25Store<br/>关键词索引（三层缓存）"]
        nextjs["Next.js API<br/>知识库/文档元数据 (CRUD)"]
        local["本地文件系统<br/>文档原文件"]
    end

    tool --> rag
    parse --> doc
    rag --> pgvector
    rag --> bm25
    doc --> chunker
    doc --> pgvector
    doc --> nextjs
    doc --> local
```

系统采用 **向量语义搜索 + BM25 关键词匹配** 的双路召回策略，通过 **RRF（Reciprocal Rank Fusion）** 融合排序返回最优结果。

***

## 技术选型

| 组件        | 技术                                                 | 说明                                |
| --------- | -------------------------------------------------- | --------------------------------- |
| 向量存储      | PostgreSQL pgvector（`langchain-postgres` PGVector） | 向量 + 元数据过滤，支持余弦相似度                |
| Embedding | OpenAI `text-embedding-3-small`（默认）                | 支持用户自定义 Embedding 模型              |
| 关键词检索     | BM25（`rank-bm25` + `jieba` 中文分词）                   | 三层缓存（内存 → Redis → PostgreSQL），懒加载 |
| 文档解析      | LangChain Document Loaders + SmartChunker          | 多格式支持 + 语义感知分块                    |
| 元数据存储     | Next.js API（Drizzle ORM + PostgreSQL）              | 知识库/文档 CRUD                       |
| Agent 框架  | DeepAgents（LangGraph）                              | Agentic RAG 工具集成                  |

***

## 数据流总览

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Web as Web App
    participant NextJS as Next.js API
    participant Backend as AI Backend
    participant PGVector as pgvector
    participant BM25 as BM25Store

    User->>Web: 上传文档到知识库
    Web->>Backend: POST /documents (file)
    Backend->>Backend: 保存文件到本地
    Backend->>NextJS: 创建文档记录

    User->>Web: 触发处理
    Web->>Backend: POST /documents/{id}/process
    Backend->>Backend: 加载 → SmartChunker → Embedding
    Backend->>PGVector: 存储向量 + 元数据
    Backend->>BM25: invalidate(kb_id)
    Backend->>NextJS: 更新状态 → completed

    User->>Web: 对话中 @知识库
    Web->>Backend: POST /agent/invoke (knowledge_base_ids)
    Backend->>Backend: Agent 调用 search_knowledge_base
    Backend->>PGVector: 向量检索
    Backend->>BM25: BM25 检索（首次自动构建索引）
    Backend->>Backend: RRF 融合排序
    Backend->>User: SSE 流式返回（含知识库引用）
```

<CardGroup cols={2}>
  <Card title="文档处理" icon="file-lines" href="/zh/knowledge-base/document-processing">
    多格式上传、SmartChunker 智能分块、处理管线
  </Card>

  <Card title="向量存储" icon="database" href="/zh/knowledge-base/vector-store">
    pgvector 存储、用户级 Embedding 配置
  </Card>

  <Card title="检索策略" icon="magnifying-glass" href="/zh/knowledge-base/retrieval">
    双路召回、RRF 融合、BM25 三层缓存
  </Card>

  <Card title="API 参考" icon="code" href="/zh/knowledge-base/api">
    知识库 / 文档管理 API、Agent 工具
  </Card>
</CardGroup>