本文引用的文件
本模块为系统提供“知识库 + 文档管理 + pgvector 向量索引 + Agent/RAG 语义检索”的完整闭环。用户通过前端上传文档,后端使用 Tika 提取全文、按配置分块、调用嵌入模型生成向量,并写入 PostgreSQL 的 pgvector 列;Agent 在研判方案中绑定知识库后,可通过 search_knowledge 工具召回相关片段作为提示上下文。
该模块与以下能力解耦但协作:
RagSchemaSearchTool 和 RagSchemaService 维护 DuckDB 表结构的向量索引。EmbeddingProvider 路由,本地模式使用 ONNX bge-m3,在线模式回退到模型管理中的 embedding 模型。知识库模块集中在 ai-server/src/main/java/com/zsjz/ai/module/knowledge,包含控制器、服务、实体、事件、解析器、索引器和 Mapper;向量推理位于 embedding 与 agent.rag 子模块;前端知识库页面位于 Electron 前端的 ai 视图与 API 层。
graph TB
FE["前端<br/>aiKnowledge/index.vue<br/>KnowledgeDocModal.vue<br/>knowledgeApi.ts"] --> CTRL["KnowledgeBaseController"]
CTRL --> KB_SVC["KnowledgeBaseService"]
CTRL --> DOC_SVC["KnowledgeDocService"]
DOC_SVC --> EVENT["KnowledgeDocIndexEvent"]
EVENT --> INDEXER["KnowledgeDocIndexer"]
INDEXER --> PARSER["KnowledgeDocParser"]
INDEXER --> PROVIDER["EmbeddingProvider"]
PROVIDER --> LOCAL["EmbeddingService<br/>bge-m3 ONNX"]
PROVIDER --> ONLINE["在线 embedding 模型"]
INDEXER --> VMAP["KnowledgeVectorMapper"]
VMAP --> PG["PostgreSQL<br/>pgvector 表 kb_vec_{kbId}{tag}_d{dims}"]
CTRL --> DB["knowledge_base / knowledge_doc / download_log"]
图表来源
章节来源
| 组件 | 职责 | 关键行为 |
|---|---|---|
KnowledgeBaseController |
HTTP 入口 | 列出/创建/编辑/删除知识库;上传、下载、删除、重试文档;下载返回裸流。 |
KnowledgeBaseService |
知识库生命周期 | 内置库只读、自建库归属校验;删除时级联清理文件、向量、下载记录并解绑方案。 |
KnowledgeDocService |
文档业务逻辑 | 上传校验、Tika 提取、sidecar 落盘、PENDING→发布事件;下载审计;删除重索引。 |
KnowledgeDocParser |
文本抽取 | Tika AutoDetect 解析 PDF/Word/表格等,超限截断但不丢弃已解析内容。 |
KnowledgeDocIndexer |
异步向量化与检索 | 单线程队列消费事件;分块、并发嵌入、幂等插入 pgvector;top-k 相似检索。 |
EmbeddingProvider |
嵌入模型路由 | 本地 ONNX 与在线模型二选一;隔离表名 tag;维度校验与不可用降级。 |
EmbeddingService |
本地嵌入实现 | bge-m3 1024 维 L2 归一化向量;批量推理、余弦相似度、预热与维度校验。 |
KnowledgeVectorMapper |
pgvector SQL | 动态建表、按 doc_id 去重插入、按 kbId 过滤检索、按 kb/doc 删除。 |
KnowledgeDocDownloadLog |
下载审计 | 记录谁在何时下载了哪个文件名快照。 |
KnowledgeSearchTool |
Agent 工具 | 暴露 search_knowledge,封装知识库语义检索结果给 LLM。 |
| 前端知识库页面 | 可视化操作 | 展示内置/自建库、我的文档列表、状态标签、上传/下载/重试/删除。 |
章节来源
知识库流程分为两条线:数据面(上传、存储、审计)和索引面(解析、分块、嵌入、pgvector)。两者通过 Spring 事件解耦,避免上传请求被向量化耗时阻塞。
sequenceDiagram
participant User as "用户"
participant FE as "前端知识库页面"
participant API as "KnowledgeBaseController"
participant DocSvc as "KnowledgeDocService"
participant Store as "LocalFileStorageUtil"
participant Parser as "KnowledgeDocParser"
participant Event as "KnowledgeDocIndexEvent"
participant Indexer as "KnowledgeDocIndexer"
participant Embed as "EmbeddingProvider"
participant Pg as "pgvector 表"
User->>FE: 选择文件并点击上传
FE->>API: POST /knowledge-bases/{id}/docs
API->>DocSvc: upload(userId, id, file)
DocSvc->>Store: 保存原件 file_path
DocSvc->>Parser: extract(file, maxChars)
Parser-->>DocSvc: fullText
DocSvc->>Store: 写入 sidecar .txt
DocSvc->>DocSvc: 登记 knowledge_doc(PENDING)
DocSvc->>Event: publish(docId)
Event-->>Indexer: onDocIndexEvent(docId)
Indexer->>Indexer: 读取 sidecar 或兜底重抽
Indexer->>Embed: embed(chunk)
Embed-->>Indexer: vector
Indexer->>Pg: INSERT kb_vec_{kbId}{tag}_d{dims}
Indexer->>DocSvc: UPDATE index_status=READY
图表来源
知识库采用两层隔离:
文档层隔离:文档列表、下载、删除、重试仅对上传者开放;RAG 检索则基于绑定的知识库全量文档,不与文档清单隔离耦合。
classDiagram
class KnowledgeBase {
+Long id
+Long userId
+Integer isBuiltin
+String name
+String description
+isBuiltin() boolean
}
class KnowledgeDoc {
+Long id
+Long kbId
+Long userId
+String fileName
+String filePath
+String sidecarPath
+String mime
+Long sizeBytes
+Integer charCount
+Integer chunkCount
+String indexStatus
+String failReason
+Integer downloadCount
}
class KnowledgeDocDownloadLog {
+Long id
+Long kbId
+Long docId
+Long userId
+String fileName
+LocalDateTime downloadTime
}
KnowledgeBase "1" -- "many" KnowledgeDoc : "包含"
KnowledgeDoc "1" -- "many" KnowledgeDocDownloadLog : "被下载"
图表来源
章节来源
上传链路是同步的,但向量化是异步的:
data/files/knowledge/{kbId}/doc/{uuid}.ext。.txt sidecar。knowledge_doc,初始状态 PENDING;提取失败记 FAILED。KnowledgeDocIndexEvent,索引器从单线程队列消费。成功置 READY 并更新 chunk_count;失败保留 fail_reason。
flowchart TD
Start(["上传开始"]) --> Validate["校验知识库与权限<br/>后缀/大小/数量上限"]
Validate --> SaveOriginal["保存原件 file_path"]
SaveOriginal --> Extract["Tika 提取全文"]
Extract --> ExtractOk{"提取成功?"}
ExtractOk -->|否| MarkFailed["标记 FAILED 并记录原因"]
ExtractOk -->|是| WriteSidecar["写入 sidecar .txt"]
WriteSidecar --> Register["登记 knowledge_doc<br/>status=PENDING"]
Register --> Publish["发布索引事件"]
MarkFailed --> End(["返回上传结果"])
Publish --> Queue["单线程索引队列"]
Queue --> LoadFull["加载全文<br/>sidecar 优先,否则兜底重抽"]
LoadFull --> Chunk["分块<br/>size/overlap/maxChunks"]
Chunk --> EmbedLoop["并发嵌入每个 chunk"]
EmbedLoop --> InsertVec["INSERT pgvector<br/>ON CONFLICT DO NOTHING"]
InsertVec --> BudgetCheck{"预算用尽?"}
BudgetCheck -->|是| Truncated["记录 truncated 提示"]
BudgetCheck -->|否| Done{"全部完成?"}
Truncated --> Done
Done --> Ready["UPDATE READY + chunk_count"]
Ready --> End
图表来源
章节来源
向量存储在 PostgreSQL pgvector 表中,表名规则为:
kb_vec_{kbId}{tag}_d{dims}tag 用于区分本地/在线模型:本地模式为 _bge_m3,在线模式为空串。dims 为向量维度:默认 1024,兼容 1536 等。每条向量记录包含:
doc_id:主键,形如 docId:chunkNo。content:chunk 文本。payload:JSONB,强制包含 kbId、docId、docName、chunkNo。embedding:pgvector 向量列。检索时先按 cosine 距离排序,再按 payload->>'kbId' 过滤,最后应用阈值与 topK。
sequenceDiagram
participant Agent as "Agent"
participant Tool as "KnowledgeSearchTool"
participant Indexer as "KnowledgeDocIndexer"
participant Embed as "EmbeddingProvider"
participant Mapper as "KnowledgeVectorMapper"
participant Pg as "pgvector 表"
Agent->>Tool: search_knowledge(query, top_k)
Tool->>Indexer: search(query, kbId)
Indexer->>Embed: embed(query)
Embed-->>Indexer: query_vector
Indexer->>Mapper: searchInKb(table, vector, kbId, threshold, topK)
Mapper->>Pg: SELECT ... WHERE payload->>'kbId'=kbId ORDER BY score DESC LIMIT topK
Pg-->>Mapper: hits
Mapper-->>Indexer: rows
Indexer-->>Tool: SearchHit[]
Tool-->>Agent: content/source/score
图表来源
章节来源
kb_vec_,检索工具 search_knowledge。AiCleanTemplateVectorIndex 维护。RagSchemaService 和 RagSchemaSearchTool 提供 search_table_schema。三者共享 EmbeddingProvider 提供的嵌入能力,但数据源、表结构和检索工具互不干扰。
graph LR
KB["知识库文档<br/>kb_vec_*"] --> SEARCH_KB["search_knowledge"]
CLEAN["清洗模板<br/>ai_clean_template_vector_index"] --> SEARCH_CLEAN["AI 智能清洗内部检索"]
SCHEMA["DuckDB 表结构<br/>RagSchemaService"] --> SEARCH_SCHEMA["search_table_schema"]
EMB["EmbeddingProvider<br/>本地/在线模型"] --> KB
EMB --> CLEAN
EMB --> SCHEMA
图表来源
章节来源
知识库模块依赖以下外部能力:
TransactionSynchronizationManager 保证 afterCommit 发布事件。StpUtil.getLoginIdAsLong() 获取当前用户。<=>。AgentScope:Tool、ToolResultBlock、ToolResults 包装工具返回值。
graph TB
Controller["KnowledgeBaseController"] --> Service["KnowledgeBaseService / KnowledgeDocService"]
Service --> Parser["KnowledgeDocParser"]
Service --> Event["KnowledgeDocIndexEvent"]
Event --> Indexer["KnowledgeDocIndexer"]
Indexer --> Provider["EmbeddingProvider"]
Provider --> Local["EmbeddingService"]
Provider --> Online["在线 embedding 模型"]
Indexer --> VectorMapper["KnowledgeVectorMapper"]
VectorMapper --> PG["pgvector"]
Controller --> SaToken["Sa-Token"]
Service --> Storage["LocalFileStorageUtil"]
图表来源
章节来源
zsjz.embedding.dimensions 声明,实际推理时会校验一致性;不一致会报错,防止写坏 pgvector 表。PENDING,前端轮询状态。index-concurrency 闸门限制。ON CONFLICT (doc_id) DO NOTHING,其中 doc_id = docId:chunkNo,天然防止同 chunk 重复插入。DELETE FROM ... WHERE payload->>'docId' = docId,确保旧向量清空后再重建。knowledge_doc 记录。可调参数包括:
zsjz.knowledge.chunkSize:分块大小,太小碎片多,太大丢失局部语义。zsjz.knowledge.chunkOverlap:重叠字符,提高边界连续性。zsjz.knowledge.maxChunks:单文档最大块数,超出截断并标注。zsjz.knowledge.scoreThreshold:cosine 相似度阈值,默认 0.3。zsjz.knowledge.topK:默认返回 8 个片段。eager-load=true 或手动预热。index-concurrency 不宜设置过高,避免内存与 CPU 争抢。index-budget-seconds 超时,剩余 chunk 会被跳过。<=> 算子,建议为常用知识库向量表建立合适的索引策略(例如 HNSW/IVFFlat,取决于部署环境)。x-token 请求头,否则会被鉴权拦截。[本节为通用性能指导,未直接分析具体代码行]
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
文档一直停留在 PENDING |
事件未发布或索引队列异常 | 检查日志中“发布索引事件失败”;点击“重试索引”。 |
文档状态 FAILED 并带原因 |
Tika 提取失败或嵌入服务不可用 | 查看 fail_reason;确认 Tika 支持该文件类型;检查本地模型目录或在线 embedding 配置。 |
| 检索无结果 | 向量表不存在、维度不匹配、阈值过高 | 确认嵌入模型可用;检查 kb_vec_{kbId}{tag}_d{dims} 是否存在;降低 scoreThreshold。 |
| 本地模型报错维度不一致 | zsjz.embedding.dimensions 与实际模型不符 |
修正配置并重建向量索引。 |
| 下载返回未登录 | 前端直链不带 token | 前端必须使用 fetch 带 x-token,不要使用 <a href>。 |
| 删除知识库后仍有残留向量 | 模型开关切换导致表名不同 | 索引器删除逻辑已兼容本地/在线 tag 与双维度;若仍异常需人工清理对应表。 |
章节来源
调试接口 /embedding/debug 用于验证本地嵌入模型是否正常工作:
使用步骤:
zsjz.embedding.enabled=true 且模型目录存在。POST /embedding/debug,请求体为文本数组。章节来源
indexStatus=PENDING,前端每 3 秒轮询,直到 READY 或 FAILED。PENDING、INDEXING、READY、FAILED。FAILED 时悬停可查看失败原因。READY 时显示已向量化块数。/embedding/debug,传入若干测试句子。dimension、embedMillis、vectors、similarity。search_knowledge 工具。章节来源
知识库模块通过清晰的职责分层实现了文档管理、异步向量化和 Agent/RAG 检索的完整闭环。其核心优势在于:
search_knowledge 工具让 LLM 能按需召回领域知识,减少幻觉。在生产环境中,建议合理配置分块大小、重叠、阈值和并发度,并根据数据规模考虑 pgvector 索引策略;同时启用本地模型预热以降低首次检索延迟。
[本节为总结性内容,未直接分析具体代码行]
| 方法 | 路径 | 说明 | 权限 |
|---|---|---|---|
| GET | /knowledge-bases |
列出内置 + 我的知识库 | 已登录 |
| POST | /knowledge-bases |
新建自建知识库 | 已登录 |
| PUT | /knowledge-bases/{id} |
编辑知识库 | 自建库主人 |
| DELETE | /knowledge-bases/{id} |
删除知识库 | 自建库主人 |
| GET | /knowledge-bases/{id}/docs |
我的上传文档列表 | 知识库可见 + 上传者本人 |
| POST | /knowledge-bases/{id}/docs |
上传文档 | 自建库主人或内置库管理员 |
| DELETE | /knowledge-bases/{id}/docs/{docId} |
删除文档 | 上传者本人 |
| POST | /knowledge-bases/{id}/docs/{docId}/reindex |
重试索引 | 上传者本人 |
| GET | /knowledge-bases/{id}/docs/{docId}/download |
下载文档 | 上传者本人 |
章节来源
| 方法 | 路径 | 请求体 | 响应字段 |
|---|---|---|---|
| POST | /embedding/debug |
文本数组 | dimension、embedMillis、vectors、similarity |
章节来源
| 配置键 | 默认值 | 说明 |
|---|---|---|
zsjz.knowledge.enabled |
true |
是否启用知识库功能 |
zsjz.knowledge.maxFileMb |
50 |
单文件大小上限 |
zsjz.knowledge.maxDocsPerUser |
200 |
单用户单库文档上限 |
zsjz.knowledge.chunkSize |
1000 |
分块字符数 |
zsjz.knowledge.chunkOverlap |
100 |
分块重叠字符数 |
zsjz.knowledge.maxChunks |
2000 |
单文档最大块数 |
zsjz.knowledge.indexBudgetSeconds |
900 |
单文档索引预算秒数 |
zsjz.knowledge.indexConcurrency |
8 |
嵌入并发闸门 |
zsjz.knowledge.topK |
8 |
检索返回片段数 |
zsjz.knowledge.scoreThreshold |
0.3 |
相似度阈值 |
zsjz.embedding.enabled |
true |
本地嵌入开关 |
zsjz.embedding.modelPath |
bge-m3 |
本地模型目录 |
zsjz.embedding.dimensions |
1024 |
向量维度 |
zsjz.embedding.batchSize |
8 |
批量推理批次大小 |
zsjz.embedding.eagerLoad |
false |
启动时预热模型 |
章节来源