> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# 知识库 RAG 管线
> 连接器采集 → 分块嵌入 → 混合检索：知识库如何从直搜升级为 RAG
知识库连接器让专家能访问飞书、语雀、IMA 等外部平台的文档。但「直搜」依赖平台自身的搜索 API——各平台搜索质量参差不齐，钉钉甚至无法返回全文。
RAG 管线将连接器从「搜索通道」升级为「采集层」：定期同步文档到本地，分块建立向量索引，用混合检索替代平台原生搜索。结果精准度显著提升，且回复中每句话都可以溯源到原始文档段落。
## 两种模式并存
每个知识库连接可以独立选择模式：
不索引，不存储。每次提问实时调用平台 API 搜索。适合文档少、更新频繁、对搜索质量要求不高的场景。
开启后，系统定期同步文档、分块、建立向量索引。提问时走本地混合检索（向量 + 关键词），质量远高于平台原生搜索。
两种模式可以在同一用户的不同连接上共存。例如：飞书连接开启 RAG（文档多、搜索质量重要），钉钉连接保持直搜（文档少、仅做补充）。
## 启用 RAG 索引
在 **设置 → 连接器** 中绑定平台凭证（详见[知识库连接](/zh/documentation/capabilities/knowledge-connectors)）。
在连接卡片上打开「启用 RAG 索引」开关。
点击「立即同步」按钮触发首次全量同步。卡片上会显示同步进度和状态。
同步完成后，启用 Knowledge 插件开始对话。搜索自动走 RAG 管线，回复中带有来源标记。
首次同步后，系统每 24 小时自动增量同步一次（仅处理新增和变更的文档）。你也可以随时手动触发同步。
## RAG 管线架构
```mermaid theme={null}
flowchart LR
subgraph 采集层
A[平台 API
飞书/语雀/IMA] -->|拉取文档| B[同步引擎]
end
subgraph 处理层
B -->|Markdown| C[文本分块
按标题层级切割]
C -->|chunk × N| D[向量嵌入
DashScope 1024维]
end
subgraph 存储层
D -->|写入| E[(PostgreSQL
pgvector)]
end
subgraph 检索层
F[用户提问] -->|嵌入 query| G[向量检索
余弦相似度]
F -->|原文| H[关键词检索
tsvector]
G --> I[RRF 融合排序]
H --> I
I -->|Top-K chunks| J[专家回答
带来源标记]
end
E --> G
E --> H
```
整条管线运行在 Core 服务内部，零新增容器、零新增部署配置。
## 同步机制
### 增量同步
同步引擎不是每次全量重新处理。每篇文档在首次同步时计算内容的 SHA-256 哈希值，后续同步时对比哈希——内容未变的文档直接跳过，只处理新增和变更的部分。
### 文档处理流程
通过平台 API 获取全量文档元数据（标题、ID、所属知识库）。
对比本地已索引文档的 content\_hash，筛出新增和变更的文档。
对变更文档调用平台 API 获取 Markdown 全文。
使用 MarkdownTextSplitter 按标题层级（`#/##/###`）作为首选分割点，超长段落在句号/换行处二次切割，保留 100 字符的上下文重叠。每个 chunk 约 1500 字符。
每个 chunk 通过 DashScope text-embedding-v3 生成 1024 维向量（与记忆系统复用同一嵌入模型）。
在数据库事务内完成：UPSERT 文档记录 → 删除旧 chunks → 插入新 chunks。保证数据一致性。
### 并发与容错
* **Worker 单实例**：同步 worker 使用 PostgreSQL Advisory Lock 保证跨副本单实例运行，不会出现多个 pod 同时同步同一连接
* **单文档容错**：某篇文档处理失败不阻塞其他文档，错误记录在连接的 sync\_error 字段
* **嵌入并发控制**：批量嵌入有并发上限（5 并行），避免打满 DashScope API 配额
## 混合检索
RAG 检索不是单纯的向量搜索——而是**向量 + 关键词双通道**检索，通过 RRF（Reciprocal Rank Fusion）融合排序。
将用户问题嵌入为向量，在 pgvector 中按余弦相似度检索 Top-30 语义最相关的 chunks。擅长理解同义词和语义关联。
使用 PostgreSQL 全文搜索（tsvector + tsquery）检索 Top-30 关键词匹配的 chunks。擅长精确术语和专有名词匹配。
两组结果通过 RRF 公式融合：
$\text{score}(d) = \sum_{r \in \text{lists}} \frac{1}{k + \text{rank}_r(d)}$
其中 $k=60$ 是平滑常数。这种融合方式的优势：
* 向量检索擅长的语义匹配和关键词检索擅长的精确匹配**互补**
* 某条结果在两个列表中都排名靠前时，融合后得分更高（**共识增强**）
* 单通道噪声被另一通道稀释（**噪声抑制**）
融合后去重，取 Top-K（默认 10）返回给专家。
## 来源溯源
RAG 检索结果与[来源引用管线](/zh/documentation/capabilities/knowledge-connectors)集成。专家回复中的 `[1]` `[2]` 标记链接到对话底部的来源卡片，每张卡片显示：
* 原始文档标题和平台来源
* 匹配的段落预览
* 文档所属知识库名称
* 文档原始链接（如有）
## 同步状态
连接卡片右侧实时显示同步状态：
| 状态 | 含义 |
| -------- | ------------- |
| **就绪** | 上次同步成功，等待下次调度 |
| **同步中** | 正在拉取、分块、嵌入 |
| **同步失败** | 上次同步出错，显示错误原因 |
同步失败不影响已有索引——之前成功索引的文档仍可被正常检索。下次同步会自动重试。
## 平台支持
| 平台 | 采集方式 | 内容格式 | 备注 |
| --- | ---------------------------------- | -------- | -------------------------- |
| 飞书 | Wiki Spaces → Nodes → Raw Content | Markdown | 自动刷新 tenant\_access\_token |
| 语雀 | Repos → Docs → Raw Body | Markdown | 企业版可配置自定义 host |
| IMA | KBs → Knowledge List → Doc Content | 结构化文本 | 仅处理笔记类型（media\_type=11） |
| 钉钉 | — | — | 暂不支持 RAG（无全文读取 API），保持直搜 |
## 计费说明
* **同步过程**：文档嵌入消耗 DashScope embedding API 配额（平台内部成本，不扣用户积分）
* **检索过程**：query 嵌入同上，不额外扣用户积分
* **对话消耗**：检索到的 chunk 内容注入对话上下文，按模型 token 计费——与直搜模式一致，具体消耗以产品内实时显示为准
RAG 模式的主要成本在首次全量同步的嵌入调用。增量同步只处理变更文档，后续成本极低。