**本文引用的文件 **
本文件面向知识库文档的完整生命周期:从前端通过 multipart 上传,到后端校验、落盘、文本提取、事件驱动异步向量化、写入 pgvector,再到下载审计、删除清理和失败重试。该能力由控制器暴露 REST 接口,服务层负责权限与数据流,解析器基于 Tika 提取正文,索引器负责分块、嵌入和向量存储,事件用于解耦主流程与耗时索引过程。
知识文档功能集中在 ai-server 模块的 com.zsjz.ai.module.knowledge 包中:
KnowledgeBaseController 暴露知识库与文档的 HTTP 端点。KnowledgeDocService 封装上传、列表、下载、删除、重试等业务逻辑。KnowledgeDocParser 使用 Apache Tika 自动识别并提取文本。KnowledgeDocIndexer 消费事件,完成分块、嵌入和 pgvector 写入。KnowledgeDocIndexEvent 将文档索引任务异步化。KnowledgeDocDownloadLog 记录下载审计;KnowledgeDocDownloadLogMapper 提供级联删除。KnowledgeDocVO 是“我的上传文档”列表与上传接口的响应结构。配置:KnowledgeProperties 管理文件大小、分块策略、并发度和后缀白名单。
graph TB
Client["客户端"] --> Controller["KnowledgeBaseController"]
Controller --> Service["KnowledgeDocService"]
Service --> Parser["KnowledgeDocParser"]
Service --> Event["KnowledgeDocIndexEvent"]
Event --> Indexer["KnowledgeDocIndexer"]
Indexer --> Embedding["EmbeddingProvider<br/>嵌入模型"]
Indexer --> VectorDB["pgvector<br/>知识库向量表"]
Service --> Storage["LocalFileStorageUtil<br/>原件与 sidecar"]
Service --> DownloadLog["KnowledgeDocDownloadLogMapper"]
图表来源
章节来源
章节来源
知识文档生命周期分为两条主线:
异步索引主线:事件监听器消费事件 → 单线程队列依次处理 → 加载全文 → 分块 → 调用嵌入模型 → 幂等删除旧向量 → 批量写入 pgvector → 更新索引状态。
sequenceDiagram
participant C as "客户端"
participant Ctrl as "KnowledgeBaseController"
participant Svc as "KnowledgeDocService"
participant Par as "KnowledgeDocParser"
participant Sto as "LocalFileStorageUtil"
participant Ev as "KnowledgeDocIndexEvent"
participant Idx as "KnowledgeDocIndexer"
participant Emb as "EmbeddingProvider"
participant V as "pgvector"
C->>Ctrl: POST /knowledge-bases/{id}/docs
Ctrl->>Svc: upload(userId, kbId, file)
Svc->>Sto: 生成路径并上传原件
Svc->>Par: extract(输入流, 最大字符数)
Par-->>Svc: 提取全文
Svc->>Sto: 保存 sidecar .txt
Svc->>Svc: 登记 KnowledgeDoc(PENDING/FAILED)
Svc->>Ev: publish(docId)
Ev-->>Idx: onDocIndexEvent(docId)
Idx->>Idx: loadFullText()
Idx->>Idx: chunk(fullText)
Idx->>Emb: embed(chunk)
Emb-->>Idx: vector[]
Idx->>V: deleteByDoc(table, docId)
Idx->>V: insert vectors
Idx->>Svc: update indexStatus READY/FAILED
图表来源
上传入口为 POST /knowledge-bases/{id}/docs。控制器通过会话工具获取当前用户 ID,并委托服务层处理。服务层执行以下关键步骤:
maxFileMb。maxDocsPerUser。LocalFileStorageUtil.generatePath 生成路径,并将原件保存到 knowledge/{kbId}/doc/{uuid}.ext。KnowledgeDocParser.extract 提取全文,上限为 maxChunks * chunkSize。.txt 形式与原件同目录保存。KnowledgeDoc 记录,初始索引状态为 PENDING;若提取失败则记 FAILED 并截断失败原因。保存文档后,发布 KnowledgeDocIndexEvent 触发异步索引。
flowchart TD
Start(["开始"]) --> CheckEmpty["检查文件是否为空"]
CheckEmpty -->|为空| ErrorEmpty["抛出 400 文件为空"]
CheckEmpty -->|非空| CheckKB["校验知识库可见性与上传权限"]
CheckKB -->|不可见或无权限| ErrorAuth["抛出 400 上传权限不足"]
CheckKB --> CheckSuffix["校验文件后缀白名单"]
CheckSuffix -->|不支持| ErrorSuffix["抛出 400 不支持的文件类型"]
CheckSuffix --> CheckSize["校验文件大小"]
CheckSize -->|超限| ErrorSize["抛出 400 文件超过大小上限"]
CheckSize --> CheckCount["校验单库下我的文档数"]
CheckCount -->|超限| ErrorCount["抛出 400 我的文档数已达上限"]
CheckCount --> SaveFile["生成路径并上传原件"]
SaveFile --> Extract["Tika 提取全文"]
Extract -->|成功| SaveSidecar["保存 sidecar .txt"]
Extract -->|失败| MarkFailed["标记 FAILED 并记录失败原因"]
SaveSidecar --> SaveDoc["保存 KnowledgeDoc"]
MarkFailed --> SaveDoc
SaveDoc --> Publish["发布索引事件"]
Publish --> End(["结束"])
图表来源
章节来源
KnowledgeDocParser 使用 Tika 的 AutoDetectParser 自动检测文档格式,并通过 BodyContentHandler 捕获正文。其设计要点包括:
maxChars 设置提取上限,防止超大文档撑爆内存。.txt,便于索引阶段优先读取稳定侧车文本。章节来源
索引器在收到 KnowledgeDocIndexEvent 后,将其提交到单线程守护队列,保证文档逐个索引,避免多个大文档同时打满嵌入模型。每个文档内部按配置开启并发嵌入,并使用信号量控制全局嵌入并发。
索引流程关键点:
INDEXING。maxChunks 个块。成功后将状态改为 READY;任何异常就地捕获并改为 FAILED。
flowchart TD
OnEvent["收到 KnowledgeDocIndexEvent"] --> Queue["提交单线程队列"]
Queue --> Load["loadFullText: sidecar 优先,缺失则兜底重抽"]
Load --> Available{"嵌入模型可用?"}
Available -->|否| FailUnavailable["抛出不可用异常 → FAILED"]
Available -->|是| Chunk["分块: chunkSize 与 chunkOverlap"]
Chunk --> Truncate{"chunk 数 > maxChunks?"}
Truncate -->|是| Cut["截取前 maxChunks 个块"]
Truncate -->|否| Proceed["继续"]
Cut --> Proceed
Proceed --> DeleteOld["deleteByDoc(table, docId) 幂等清理旧向量"]
DeleteOld --> EmbedLoop["按 budget 与并发门限嵌入"]
EmbedLoop --> Write["写入 pgvector 向量表"]
Write --> Ready["更新状态为 READY"]
EmbedLoop --> Timeout["超出预算跳过剩余块"]
Timeout --> Ready
EmbedLoop --> Exception["异常捕获 → FAILED"]
图表来源
章节来源
重试入口为 POST /knowledge-bases/{id}/docs/{docId}/reindex。服务层会:
PENDING。fail_reason。索引器本身具备幂等性:重复事件不会造成向量重复写入,因为会先删除旧向量行。重试适用于两类场景:
嵌入服务临时不可用,等待恢复后重试。
sequenceDiagram
participant C as "客户端"
participant Ctrl as "KnowledgeBaseController"
participant Svc as "KnowledgeDocService"
participant Ev as "KnowledgeDocIndexEvent"
participant Idx as "KnowledgeDocIndexer"
C->>Ctrl: POST /knowledge-bases/{id}/docs/{docId}/reindex
Ctrl->>Svc: reindex(userId, docId)
Svc->>Svc: 校验文档归属
Svc->>Svc: 重置 PENDING 并清空失败原因
Svc->>Ev: publish(docId)
Ev-->>Idx: onDocIndexEvent(docId)
Idx->>Idx: 幂等重建向量
图表来源
章节来源
下载入口为 GET /knowledge-bases/{id}/docs/{docId}/download。控制器返回裸 InputStreamResource,不包裹通用结果对象,以便浏览器或前端直接保存二进制文件。
服务层在下载时:
KnowledgeDocDownloadLog,记录知识库 ID、文档 ID、用户 ID、下载时文件名快照和时间。download_count,避免读改写带来的并发问题。下载审计字段包括:
kb_id:所属知识库。doc_id:被下载文档。user_id:下载人。file_name:下载时的文件名快照。download_time:下载时间。章节来源
删除入口为 DELETE /knowledge-bases/{id}/docs/{docId}。服务层执行:
删除操作确保物理文件、向量数据和审计日志保持一致。
章节来源
文档层隔离比知识库可见性更严格:
RAG 检索不受文档层隔离限制,检索绑定知识库的全量文档。
classDiagram
class KnowledgeBaseController {
+list()
+create()
+update()
+delete()
+listDocs()
+uploadDoc()
+deleteDoc()
+reindexDoc()
+downloadDoc()
}
class KnowledgeDocService {
+listMine()
+upload()
+download()
+delete()
+reindex()
-requireOwnedDoc()
}
class KnowledgeDocParser {
+extract()
+sidecarPathOf()
}
class KnowledgeDocIndexer {
+onDocIndexEvent()
+indexDoc()
-loadFullText()
-doIndex()
}
class KnowledgeDocIndexEvent {
+publish()
}
KnowledgeBaseController --> KnowledgeDocService : "委托业务"
KnowledgeDocService --> KnowledgeDocParser : "提取文本"
KnowledgeDocService --> KnowledgeDocIndexEvent : "发布事件"
KnowledgeDocIndexEvent --> KnowledgeDocIndexer : "异步消费"
图表来源
章节来源
GET/knowledge-basesResult<List<KnowledgeBaseVO>>。POST/knowledge-basesSaveKnowledgeBaseDTO。Result<KnowledgeBaseVO>。PUT/knowledge-bases/{id}id。SaveKnowledgeBaseDTO。Result<KnowledgeBaseVO>。DELETE/knowledge-bases/{id}id。Result<Void>。GET/knowledge-bases/{id}/docsid。Result<List<KnowledgeDocVO>>。章节来源
POST/knowledge-bases/{id}/docsid。file:multipart 文件。Result<KnowledgeDocVO>。400:文件为空。400:不支持的文件类型。400:文件超过大小上限。400:我的文档数已达上限。500:文档保存失败。章节来源
DELETE/knowledge-bases/{id}/docs/{docId}id、docId。Result<Void>。章节来源
POST/knowledge-bases/{id}/docs/{docId}/reindexid、docId。Result<Void>。PENDING,清空失败原因,重新发布索引事件。章节来源
GET/knowledge-bases/{id}/docs/{docId}/downloadx-token。id、docId。Content-Disposition: attachment; filename*=UTF-8''{encodedFileName}。KnowledgeDocDownloadLog,并原子增加 download_count。404:文档不存在或已删除。400:只能操作自己上传的文档。章节来源
知识库相关配置位于 zsjz.knowledge 命名空间。
| 配置键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
enabled |
boolean | true |
是否启用知识库功能 |
maxFileMb |
long | 50 |
单文件大小上限,单位 MB |
maxDocsPerUser |
int | 200 |
单用户在单个知识库下的文档数上限 |
chunkSize |
int | 1000 |
RAG 分块大小,单位字符 |
chunkOverlap |
int | 100 |
RAG 分块重叠,单位字符 |
maxChunks |
int | 2000 |
RAG 分块数量上限,超出截断索引 |
indexBudgetSeconds |
int | 900 |
单文档索引总预算秒数,超时后跳过剩余 chunk |
indexConcurrency |
int | 8 |
嵌入并发度,所有文档共享的信号量许可数 |
topK |
int | 8 |
search_knowledge 检索片段数 |
scoreThreshold |
double | 0.3 |
检索相似度阈值 |
acceptSuffixes |
List<String> | 空时使用默认清单 | 接受的后缀白名单 |
默认支持的文本类文档与常见表格格式包括:
txt、md、log、json、xml、yaml、yml、ini、sql、tsv。pdf、doc、docx、rtf、odt、wps、html、htm、eml。csv、xls、xlsx、ppt、pptx。可通过 acceptSuffixes 覆盖默认白名单。
maxChunks * chunkSize 限制 Tika 提取字符上限。chunkSize 与 chunkOverlap 进行分块。maxChunks 个块,多余部分截断并在 KnowledgeDocVO 中标注索引状态。indexBudgetSeconds 限制,超时后剩余块跳过。章节来源
graph LR
Controller["KnowledgeBaseController"] --> DocService["KnowledgeDocService"]
DocService --> Parser["KnowledgeDocParser"]
DocService --> Event["KnowledgeDocIndexEvent"]
Event --> Indexer["KnowledgeDocIndexer"]
Indexer --> Embedding["EmbeddingProvider"]
Indexer --> VectorMapper["KnowledgeVectorMapper"]
DocService --> DownloadLog["KnowledgeDocDownloadLogMapper"]
DocService --> Storage["LocalFileStorageUtil"]
图表来源
章节来源
indexConcurrency 控制。indexBudgetSeconds 防止单次索引长时间占用队列。data/files 所在磁盘空间,避免原件与 sidecar 占满。[本节为通用性能建议,不直接分析具体文件]
| 场景 | 表现 | 可能原因 | 处理建议 |
|---|---|---|---|
| 文件为空 | 上传返回 400 | 前端未正确传递 multipart | 检查表单字段名与文件选择逻辑 |
| 不支持的文件类型 | 上传返回 400 | 后缀不在白名单 | 调整 acceptSuffixes 或使用默认白名单 |
| 文件过大 | 上传返回 400 | 超过 maxFileMb |
压缩文件或增大配置 |
| 我的文档数已达上限 | 上传返回 400 | 超过 maxDocsPerUser |
清理旧文档或提高上限 |
| 文档保存失败 | 上传返回 500 | 文件系统不可写、路径异常 | 检查存储服务与磁盘权限 |
| 提取失败 | 文档状态 FAILED |
扫描件、图片型 PDF、解析异常 | 重试;必要时更换源文件 |
| 嵌入服务不可用 | 文档状态 FAILED |
嵌入模型初始化失败或网络异常 | 检查嵌入服务可用性后重试 |
| 索引超时 | 部分 chunk 跳过 | 超过 indexBudgetSeconds |
降低并发、提升嵌入性能或增加预算 |
| 下载失败 | 404 或 400 | 文档不存在或非上传者 | 确认文档归属与权限 |
| 删除后仍可访问 | 预期不一致 | 缓存或前端未刷新 | 清理缓存并刷新页面 |
KnowledgeDocVO 中的 indexStatus 可能取值:
PENDING:已登记,等待索引。INDEXING:正在索引。READY:索引成功。FAILED:索引失败,可查看 failReason。indexStatus 与 failReason。FAILED,确认嵌入模型是否可用。x-token,以及后端会话是否能解析出当前用户。章节来源
知识文档功能通过控制器、服务层、解析器、索引器和事件机制形成清晰的分层架构。上传链路保持轻量快速,索引链路通过事件与单线程队列异步执行,既避免阻塞主流程,又保障资源可控。权限上实现了知识库级隔离与文档上传者级双重隔离;数据上通过 sidecar、pgvector 表和下载审计表实现可观测与可恢复。通过合理配置分块大小、并发度与预算时间,可以在不同规模的知识库场景中平衡吞吐、延迟与成本。