本文引用的文件
本文聚焦知识库(module/knowledge)的知识文档向量层,说明其在 pgvector 中的表结构设计、主键与外键语义、向量维度来源、索引类型与查询语句,并解释 KnowledgeVectorMapper 提供的建表、插入、删除和相似检索接口如何被 Agent 的 KnowledgeSearchTool 以及 RAG Schema 检索链路间接使用。同时补充向量归一化、余弦距离计算、批量写入、索引刷新策略、维度不匹配处理、召回率调优、pgvector 扩展安装和性能监控建议。
知识库向量能力属于 AI Server 的“知识文档 RAG”子模块,与“附件大文档 RAG”“模板元数据向量索引”共享同一套嵌入模型路由(EmbeddingProvider),但物理表隔离、调用方不同:
| 层次 | 职责 | 关键文件 |
|---|---|---|
| 数据定义 | 知识库元数据、文档元数据、下载记录;向量表动态命名约定 | sql/knowledge_base.sql |
| 持久化映射 | 原生 SQL 的向量表 Mapper | KnowledgeVectorMapper.java |
| 异步索引 | 事件驱动分块、向量化、落库、状态机 | KnowledgeDocIndexer.java |
| 事件发布 | 事务后提交发布,fail-open | KnowledgeDocIndexEvent.java |
| 配置 | 知识库开关、分块、TopK、阈值、并发与预算 | KnowledgeProperties.java |
| Agent 工具 | search_knowledge 语义检索 |
KnowledgeSearchTool.java |
| 统一 RAG 门面 | 表结构向量检索入口,供 Agent 工具使用 | RagSchemaService.java |
| 嵌入模型路由 | 本地 ONNX / 在线模型二选一、维度与表标签 | EmbeddingProvider.java |
| 通用向量化逻辑 | 文本分块、向量字面量构造、虚拟线程执行 | AttachmentDocIndexer.java |
| 全局配置 | 向量模型开关、bge-m3 参数、RAG 默认 TopK 与阈值 | application.yaml |
graph TB
subgraph "知识库"
KB_SQL["知识库 DDL<br/>knowledge_base / knowledge_doc"]
KB_VEC["向量表 kb_vec_{kbId}{tag}_d{dims}"]
end
subgraph "Java 服务层"
Event["KnowledgeDocIndexEvent"]
Indexer["KnowledgeDocIndexer"]
Mapper["KnowledgeVectorMapper"]
Tool["KnowledgeSearchTool"]
Embed["EmbeddingProvider"]
AppCfg["application.yaml"]
end
KB_SQL --> Indexer
Embed --> Indexer
Indexer --> Mapper
Mapper --> KB_VEC
Tool --> Indexer
AppCfg --> Embed
图表来源
章节来源
knowledge_base 表示一个知识库,支持内置库和用户自建库;knowledge_doc 表示上传到某个知识库的文档,维护解析状态、字符数、块数和失败原因。kb_vec_{kbId}{tag}_d{dims}。search_knowledge,按自然语言检索绑定知识库的片段。KnowledgeVectorMapper,但与知识库向量层共享同一套向量模型与 pgvector 部署方式。章节来源
知识库向量层是“文档 → 文本 → 分块 → 向量 → pgvector → 相似度检索”的闭环:
sequenceDiagram
participant User as "用户或 Agent"
participant Tool as "KnowledgeSearchTool"
participant Indexer as "KnowledgeDocIndexer"
participant Provider as "EmbeddingProvider"
participant Mapper as "KnowledgeVectorMapper"
participant PG as "pgvector 表 kb_vec_{kbId}{tag}_d{dims}"
User->>Tool: 调用 search_knowledge(query, top_k)
Tool->>Indexer: search(query, kbId)
Indexer->>Provider: embed(query)
Provider-->>Indexer: double[] queryVector
Indexer->>Mapper: searchInKb(table, vector, kbId, threshold, limit)
Mapper->>PG: 相似度检索 + kbId 过滤
PG-->>Mapper: content/payload/score
Mapper-->>Indexer: 结果列表
Indexer-->>Tool: SearchHit 列表
Tool-->>User: JSON 片段、来源、分数
图表来源
knowledge_base 和 knowledge_doc 是固定结构,用于知识库与文档元数据:
| 字段 | 含义 | 约束 |
|---|---|---|
knowledge_base.id |
知识库主键,内置库固定为 1 | 主键 |
knowledge_base.user_id |
创建者,内置库为平台管理员 | 非空 |
knowledge_base.is_builtin |
1=内置,0=自建 | 非空,默认 0 |
knowledge_doc.id |
文档主键 | 主键 |
knowledge_doc.kb_id |
所属知识库 | 非空,业务上关联 knowledge_base.id |
knowledge_doc.user_id |
上传者,列表与下载隔离依据 | 非空 |
knowledge_doc.sidecar_path |
Tika 提取的全文路径,向量化优先读取 | 可选 |
knowledge_doc.chunk_count |
已向量化块数 | 整数,默认 0 |
knowledge_doc.index_status |
索引状态:PENDING / INDEXING / READY / FAILED | 字符串,默认 PENDING |
向量表不是固定 DDL,而是由 KnowledgeVectorMapper.createVectorTable 在运行时创建,表名规则为:
| 组成部分 | 说明 |
|---|---|
kb_vec_ |
前缀 |
{kbId} |
知识库 ID,实现知识库级物理隔离 |
{tag} |
嵌入模型标签,本地模式为 _bge_m3,在线模式为空串 |
_d{dims} |
向量维度,来自当前 EmbeddingProvider.dimensions() |
向量表结构如下:
| 列 | 类型 | 用途 | 约束 |
|---|---|---|---|
doc_id |
VARCHAR(128) |
分块主键,值为 docId:chunkNo |
主键 |
content |
TEXT |
分块原文内容 | 无 |
payload |
JSONB |
来源元数据,包含 kbId、docId、docName、chunkNo |
无 |
embedding |
vector(${dims}) |
pgvector 稠密向量 | 无显式索引 |
主键是 doc_id,没有传统意义上的外键约束。隔离通过两层保证:
kbId。payload->>'kbId' = #{kbId}。因此,它不是严格的关系型外键,而是“命名空间 + payload 过滤”的业务隔离。
章节来源
向量维度来源于 EmbeddingProvider.dimensions():
zsjz.embedding.enabled=true,使用进程内 bge-m3,维度由 zsjz.embedding.dimensions 决定,默认 1024。zsjz.embedding.enabled=false,从 agent_model 表解析 type=embedding 的活跃模型,取配置的 dimensions。本地模式下的 bge-m3 输出向量会进行 L2 归一化;在线模型返回什么向量取决于远程服务,但代码要求长度必须等于配置维度。
flowchart TD
Start["开始"] --> CheckMode{"本地模型可用?"}
CheckMode -->|是| LocalDims["取 zsjz.embedding.dimensions<br/>默认 1024"]
CheckMode -->|否| OnlineSpec["解析 agent_model 中 type='embedding'"]
OnlineSpec --> ValidSpec{"规格有效?"}
ValidSpec -->|否| Invalid["dimensions=0,索引/检索降级"]
ValidSpec -->|是| OnlineDims["取模型 dimensions"]
LocalDims --> Output["返回向量维度"]
OnlineDims --> Output
Invalid --> Output
图表来源
章节来源
| 方法 | 行为 | 关键参数 |
|---|---|---|
createVectorTable(tableName, dims) |
动态创建向量表,不存在则跳过 | 表名、向量维度 |
tableExists(tableName) |
检查信息_schema 中是否存在该表 | 表名 |
insertVectorDoc(tableName, docId, content, payloadJson, embedding) |
插入分块向量,冲突时忽略 | doc_id、content、payload、embedding |
searchInKb(tableName, embedding, kbId, threshold, limit) |
cosine 相似度检索,限制 kbId、阈值和 TopK | 查询向量、知识库 ID、阈值、上限 |
deleteByDoc(tableName, docId) |
删除某文档全部向量行 | 文档 ID |
deleteByKb(tableName, kbId) |
删除某知识库全部向量行 | 知识库 ID |
插入语句使用 ON CONFLICT (doc_id) DO NOTHING,实现幂等写入;删除语句按 payload->>'docId' 或 payload->>'kbId' 过滤,确保跨维度/跨模型兼容删除。
章节来源
知识库文档索引不是同步阻塞在上传请求中,而是通过 Spring 事件解耦:
sequenceDiagram
participant Service as "上传服务"
participant Publisher as "KnowledgeDocIndexEvent.publish"
participant Queue as "单线程 indexExecutor"
participant Indexer as "KnowledgeDocIndexer.indexDoc"
participant Parser as "文档解析"
participant Provider as "EmbeddingProvider"
participant Mapper as "KnowledgeVectorMapper"
Service->>Publisher: publish(docId)
Publisher-->>Queue: afterCommit 提交事件
Queue->>Indexer: indexDoc(docId)
Indexer->>Parser: loadFullText()
Parser-->>Indexer: 全文
Indexer->>Provider: dimensions() + embed(chunk)
Indexer->>Mapper: deleteByDoc() + insertVectorDoc()
Indexer->>Service: 更新 chunk_count/index_status
关键点:
FAILED 并记录失败原因。图表来源
章节来源
KnowledgeSearchTool.searchKnowledge 是 Agent 可调用的工具:
top_k。KnowledgeDocIndexer.search(query, kbId)。EmbeddingProvider.embed()。KnowledgeVectorMapper.searchInKb(),按 kbId 过滤、cosine 相似度排序、限制 TopK。将 content、source、score 包装为工具结果返回。
flowchart TD
A["收到 search_knowledge(query, top_k)"] --> B["校验 kbId 与模型可用"]
B --> C["embed(query) 得到查询向量"]
C --> D["确定向量表名"]
D --> E{"向量表存在?"}
E -->|否| F["返回空结果"]
E -->|是| G["searchInKb: cosine + kbId 过滤 + threshold + limit"]
G --> H["解析 payload 获取 docName"]
H --> I["返回片段列表"]
图表来源
章节来源
RagSchemaService 主要面向“表结构向量索引”,不直接操作 KnowledgeVectorMapper,但它与知识库向量层共享:
EmbeddingProvider,因此使用相同模型、相同维度和相同 pgvector 部署。因此,知识库向量层可视为 RAG 体系中的一个“文档片段检索分支”,而 RAG Schema 是另一个“表结构检索分支”。
章节来源
classDiagram
class KnowledgeVectorMapper {
+createVectorTable(tableName, dims)
+tableExists(tableName)
+insertVectorDoc(tableName, docId, content, payloadJson, embedding)
+searchInKb(tableName, embedding, kbId, threshold, limit)
+deleteByDoc(tableName, docId)
+deleteByKb(tableName, kbId)
}
class KnowledgeDocIndexer {
+onDocIndexEvent(event)
+indexDoc(docId)
+search(question, kbId)
+deleteDocVectors(kbId, docId)
+deleteKbVectors(kbId)
-vectorTableName(kbId, tag, dims)
}
class KnowledgeSearchTool {
+searchKnowledge(query, top_k)
}
class EmbeddingProvider {
+isAvailable()
+dimensions()
+tableTag()
+embed(text)
}
class KnowledgeDocIndexEvent {
+publish(publisher, docId)
}
KnowledgeDocIndexer --> KnowledgeVectorMapper : "读写向量表"
KnowledgeDocIndexer --> EmbeddingProvider : "获取维度与向量"
KnowledgeSearchTool --> KnowledgeDocIndexer : "语义检索"
KnowledgeDocIndexer --> KnowledgeDocIndexEvent : "消费事件"
图表来源
章节来源
<=> 运算符,即余弦距离。1 - (embedding <=> #{embedding}::vector) 作为相似度分数,分数越高越相关。scoreThreshold 是“最低相似度分数”,例如 0.3 表示至少 0.3 的相关度才返回。insertVectorDoc 是单条插入,没有 MyBatis batchInsert 或 COPY 批量语法。KnowledgeDocIndexEvent。PENDING → INDEXING → READY / FAILED。EmbeddingProvider.dimensions()。relation does not exist。| 参数 | 默认值 | 影响 | 调优建议 |
|---|---|---|---|
zsjz.knowledge.chunkSize |
1000 | 分块大小 | 太小丢失上下文,太大 token 浪费;中文技术文档可从 500~1000 调整 |
zsjz.knowledge.chunkOverlap |
100 | 分块重叠 | 提升边界召回,但增加冗余 |
zsjz.knowledge.maxChunks |
2000 | 最大块数 | 超长文档只索引前部,截断会标注 |
zsjz.knowledge.topK |
8 | 返回片段数 | 给 LLM 的候选越多,提示词压力越大 |
zsjz.knowledge.scoreThreshold |
0.3 | 最低相似度 | 太低引入噪声,太高召回不足 |
zsjz.knowledge.indexConcurrency |
8 | 嵌入并发 | CPU 密集场景不宜过大 |
zsjz.knowledge.indexBudgetSeconds |
900 | 单文档索引预算 | 过长可能卡住队列,过短导致大量跳过 |
embedding 列创建 IVFFlat 或 HNSW 索引。CREATE TABLE IF NOT EXISTS 与索引创建拆分为运维脚本。payload->>'kbId' 建立函数索引或展开字段以加速隔离过滤。knowledge_doc.chunk_count、index_status、fail_reason。kbId 统计 kb_vec_* 表数量。KnowledgeDocIndexer 日志中的预算耗尽、分块失败、索引完成信息。章节来源
| 现象 | 可能原因 | 排查步骤 |
|---|---|---|
| 知识库检索始终为空 | 向量表不存在、模型不可用、阈值过高 | 检查 EmbeddingProvider.isAvailable()、向量表是否存在、scoreThreshold |
| 上传成功但索引失败 | 嵌入模型返回错误、维度无效、分块失败 | 查看 knowledge_doc.fail_reason 和 index_status=FAILED |
| 切换本地/在线模型后召回异常 | 向量空间不一致,旧表与新表隔离 | 确认表名是否含模型标签,必要时重建索引 |
| 向量维度报错 | 在线模型配置维度与实际返回不一致 | 检查 agent_model 中 embedding 模型的 dimensions |
| 索引很慢 | 嵌入模型 CPU 压力大、并发过高、预算过长 | 调整 indexConcurrency、indexBudgetSeconds |
| 检索太慢 | 无 pgvector 索引,全表余弦排序 | 评估安装 pgvector 并创建 IVFFlat/HNSW 索引 |
| 知识库隔离失效 | payload 缺失 kbId 或 SQL 拼接错误 | 检查 payload->>'kbId' 过滤逻辑 |
章节来源
知识库向量层采用“动态表名 + 主键幂等 + payload 隔离 + cosine 相似度”的设计,实现了按知识库隔离的知识文档片段检索。它通过事件驱动、单文档顺序 + 分块并发、预算控制和模型路由,兼顾了稳定性与可扩展性。当前版本未使用 pgvector 专属索引,适合中小规模知识库;大规模场景需要评估 pgvector 扩展、IVFFlat/HNSW 索引、批量写入和查询计划监控。
以下示例描述实际 SQL 与 Java 调用方式,不直接粘贴源代码。
kb_vec_{kbId}{tag}_d{dims} 插入一行,主键为 doc_id = '{docId}:{chunkNo}',payload 为 JSONB,embedding 为 vector。doc_id 时忽略。KnowledgeVectorMapper.insertVectorDoc。KnowledgeDocIndexer.doIndex → vectorMapper.deleteByDoc → vectorMapper.insertVectorDoc。参考位置:
1 - (embedding <=> #{embedding}::vector) 作为 score,按 score 降序取前 limit 条,并强制 payload->>'kbId' = #{kbId} 且 score ≥ threshold。KnowledgeVectorMapper.searchInKb。KnowledgeSearchTool.searchKnowledge → KnowledgeDocIndexer.search。参考位置:
payload->>'docId' = #{docId} 的全部行。KnowledgeVectorMapper.deleteByDoc。KnowledgeDocIndexer.deleteDocVectors 会遍历多种标签和维度组合,提高兼容删除概率。参考位置:
payload->>'kbId' = #{kbId} 的全部行。KnowledgeVectorMapper.deleteByKb。参考位置: