文档上传、解析与索引生命周期.md 33 KB

文档上传、解析与索引生命周期

**本文引用的文件 **

  • KnowledgeBaseController.java
  • KnowledgeDocService.java
  • KnowledgeDocParser.java
  • KnowledgeDocIndexer.java
  • KnowledgeDocIndexEvent.java
  • KnowledgeDocVO.java
  • KnowledgeDocDownloadLog.java
  • KnowledgeDocDownloadLogMapper.java
  • KnowledgeProperties.java

目录

  1. 引言
  2. 项目结构定位
  3. 核心组件职责
  4. 系统架构总览
  5. 详细流程分析
  6. REST API 接口定义
  7. 配置项与容量限制
  8. 依赖关系分析
  9. 性能特征与优化建议
  10. 错误处理与故障排查
  11. 结论

引言

本文件面向知识库文档的完整生命周期:从前端通过 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"]
    

图表来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocService.java:1-247
  • KnowledgeDocParser.java:1-55
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeDocIndexEvent.java:1-59

章节来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocService.java:1-247

核心组件职责

  • KnowledgeBaseController:接收登录用户身份,转发知识库与文档请求;下载返回裸文件流。
  • KnowledgeDocService:实现文档上传、列表、下载、删除、重试;维护上传者隔离;发布索引事件。
  • KnowledgeDocParser:基于 Tika 自动解析多种文档类型,提取可检索正文。
  • KnowledgeDocIndexer:单线程守护队列顺序索引文档;内部按配置并发执行 chunk 嵌入;写 pgvector。
  • KnowledgeDocIndexEvent:事务提交后安全发布索引事件,避免阻塞主流程。
  • KnowledgeDocDownloadLog:持久化下载审计信息,文件名快照保留历史语义。
  • KnowledgeDocVO:对外暴露文档元信息与索引状态。
  • KnowledgeProperties:集中管理知识库启用开关、大小上限、分块策略、并发度、后缀白名单等。

章节来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocService.java:1-247
  • KnowledgeDocParser.java:1-55
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeDocIndexEvent.java:1-59
  • KnowledgeDocDownloadLog.java:1-45
  • KnowledgeDocVO.java:1-38
  • KnowledgeProperties.java:1-65

系统架构总览

知识文档生命周期分为两条主线:

  1. 同步上传主线:控制器校验身份 → 服务层校验可见性、上传权限、类型与大小 → 原件落盘 → Tika 提取全文 → 保存 sidecar → 登记文档行(PENDING 或 FAILED)→ 发布索引事件。
  2. 异步索引主线:事件监听器消费事件 → 单线程队列依次处理 → 加载全文 → 分块 → 调用嵌入模型 → 幂等删除旧向量 → 批量写入 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
    

图表来源

  • KnowledgeBaseController.java:60-122
  • KnowledgeDocService.java:60-180
  • KnowledgeDocParser.java:18-55
  • KnowledgeDocIndexEvent.java:20-59
  • KnowledgeDocIndexer.java:70-200

详细流程分析

上传流程

上传入口为 POST /knowledge-bases/{id}/docs。控制器通过会话工具获取当前用户 ID,并委托服务层处理。服务层执行以下关键步骤:

  • 校验文件非空。
  • 校验知识库可见性与上传权限:自建库允许库主人上传,内置库仅管理员上传。
  • 校验文件后缀是否在生效白名单中。
  • 校验文件大小是否超过 maxFileMb。
  • 校验用户在单个知识库下的文档数量是否超过 maxDocsPerUser。
  • 使用 LocalFileStorageUtil.generatePath 生成路径,并将原件保存到 knowledge/{kbId}/doc/{uuid}.ext。
  • 调用 KnowledgeDocParser.extract 提取全文,上限为 maxChunks * chunkSize。
  • 将全文以 sidecar .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(["结束"])
    

图表来源

  • KnowledgeDocService.java:60-180
  • KnowledgeDocParser.java:18-55

章节来源

  • KnowledgeBaseController.java:70-86
  • KnowledgeDocService.java:60-180
  • KnowledgeDocParser.java:18-55

解析与侧车存储

KnowledgeDocParser 使用 Tika 的 AutoDetectParser 自动检测文档格式,并通过 BodyContentHandler 捕获正文。其设计要点包括:

  • 根据 maxChars 设置提取上限,防止超大文档撑爆内存。
  • 当 Tika 因长度限制中断时,只要已提取内容非空,就视为截断成功。
  • 如果最终内容为空白,抛出异常,提示可能是扫描件或图片型 PDF。
  • sidecar 路径规则为:与原文件同名但扩展名替换为 .txt,便于索引阶段优先读取稳定侧车文本。

章节来源

  • KnowledgeDocParser.java:18-55

异步索引与 pgvector 写入

索引器在收到 KnowledgeDocIndexEvent 后,将其提交到单线程守护队列,保证文档逐个索引,避免多个大文档同时打满嵌入模型。每个文档内部按配置开启并发嵌入,并使用信号量控制全局嵌入并发。

索引流程关键点:

  • 将文档状态置为 INDEXING。
  • 优先从 sidecar 读取全文;缺失时从原件兜底重抽并补写 sidecar。
  • 校验嵌入模型可用性和维度。
  • 按知识库、标签、维度选择向量表名。
  • 对全文进行分块,最多保留 maxChunks 个块。
  • 重放幂等:先删除该文档旧向量行,再插入新向量。
  • 按预算时间跳过剩余 chunk,防止队列被慢查询长期占用。
  • 成功后将状态改为 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"]
    

图表来源

  • KnowledgeDocIndexer.java:70-200
  • KnowledgeDocIndexEvent.java:20-59

章节来源

  • KnowledgeDocIndexer.java:70-200

重试机制

重试入口为 POST /knowledge-bases/{id}/docs/{docId}/reindex。服务层会:

  • 校验文档归属:只有上传者本人可重试。
  • 将文档索引状态重置为 PENDING。
  • 显式清空 fail_reason。
  • 再次发布索引事件,让索引器重新执行。

索引器本身具备幂等性:重复事件不会造成向量重复写入,因为会先删除旧向量行。重试适用于两类场景:

  • 上次文本提取失败,sidecar 缺失,索引器会从原件兜底重抽。
  • 嵌入服务临时不可用,等待恢复后重试。

    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: 幂等重建向量
    

图表来源

  • KnowledgeBaseController.java:92-98
  • KnowledgeDocService.java:140-180
  • KnowledgeDocIndexEvent.java:20-59
  • KnowledgeDocIndexer.java:100-140

章节来源

  • KnowledgeDocService.java:140-180

下载与审计

下载入口为 GET /knowledge-bases/{id}/docs/{docId}/download。控制器返回裸 InputStreamResource,不包裹通用结果对象,以便浏览器或前端直接保存二进制文件。

服务层在下载时:

  • 校验文档存在且属于当前用户。
  • 从存储服务读取原件流。
  • 写入 KnowledgeDocDownloadLog,记录知识库 ID、文档 ID、用户 ID、下载时文件名快照和时间。
  • 通过 SQL 自增更新 download_count,避免读改写带来的并发问题。

下载审计字段包括:

  • kb_id:所属知识库。
  • doc_id:被下载文档。
  • user_id:下载人。
  • file_name:下载时的文件名快照。
  • download_time:下载时间。

章节来源

  • KnowledgeBaseController.java:100-122
  • KnowledgeDocService.java:100-140
  • KnowledgeDocDownloadLog.java:1-45
  • KnowledgeDocDownloadLogMapper.java:1-19

删除与清理

删除入口为 DELETE /knowledge-bases/{id}/docs/{docId}。服务层执行:

  • 校验文档归属。
  • 删除原件文件。
  • 删除 sidecar 文本。
  • 删除该文档的向量行。
  • 删除该文档的全部下载记录。
  • 删除文档记录。

删除操作确保物理文件、向量数据和审计日志保持一致。

章节来源

  • KnowledgeBaseController.java:88-92
  • KnowledgeDocService.java:120-140

权限与隔离

文档层隔离比知识库可见性更严格:

  • 列表、下载、删除、重试只对上传者本人开放。
  • 上传权限区分自建库与内置库:自建库允许库主人,内置库仅管理员。
  • 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 : "异步消费"
    

图表来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocService.java:1-247
  • KnowledgeDocParser.java:1-55
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeDocIndexEvent.java:1-59

章节来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocService.java:1-247

REST API 接口定义

列出知识库

  • 方法:GET
  • 路径:/knowledge-bases
  • 鉴权:需要登录身份;后端按当前用户过滤知识库列表。
  • 请求参数:无。
  • 响应结构:Result<List<KnowledgeBaseVO>>。
  • 说明:包含内置知识库与当前用户自建知识库。

新建知识库

  • 方法:POST
  • 路径:/knowledge-bases
  • 鉴权:需要登录身份。
  • 请求体:SaveKnowledgeBaseDTO。
  • 响应结构:Result<KnowledgeBaseVO>。

编辑知识库

  • 方法:PUT
  • 路径:/knowledge-bases/{id}
  • 鉴权:需要登录身份;内置知识库拒绝编辑。
  • 路径参数:id。
  • 请求体:SaveKnowledgeBaseDTO。
  • 响应结构:Result<KnowledgeBaseVO>。

删除知识库

  • 方法:DELETE
  • 路径:/knowledge-bases/{id}
  • 鉴权:需要登录身份;内置知识库拒绝删除。
  • 路径参数:id。
  • 响应结构:Result<Void>。
  • 副作用:级联清理文档与向量,并解绑引用它的方案。

列出我的上传文档

  • 方法:GET
  • 路径:/knowledge-bases/{id}/docs
  • 鉴权:需要登录身份;只返回当前用户上传的文档。
  • 路径参数:id。
  • 响应结构:Result<List<KnowledgeDocVO>>。

章节来源

  • KnowledgeBaseController.java:40-86

上传文档

  • 方法:POST
  • 路径:/knowledge-bases/{id}/docs
  • 鉴权:需要登录身份;上传权限为自建库库主人或内置库管理员。
  • 路径参数:id。
  • 请求参数:
    • file:multipart 文件。
  • 响应结构:Result<KnowledgeDocVO>。
  • 主要错误码:
    • 400:文件为空。
    • 400:不支持的文件类型。
    • 400:文件超过大小上限。
    • 400:我的文档数已达上限。
    • 500:文档保存失败。

章节来源

  • KnowledgeBaseController.java:70-86
  • KnowledgeDocService.java:60-180

删除文档

  • 方法:DELETE
  • 路径:/knowledge-bases/{id}/docs/{docId}
  • 鉴权:需要登录身份;仅上传者可删除。
  • 路径参数:id、docId。
  • 响应结构:Result<Void>。
  • 副作用:删除原件、sidecar、向量行、下载记录,并删除文档记录。

章节来源

  • KnowledgeBaseController.java:88-92
  • KnowledgeDocService.java:120-140

重试索引

  • 方法:POST
  • 路径:/knowledge-bases/{id}/docs/{docId}/reindex
  • 鉴权:需要登录身份;仅上传者可重试。
  • 路径参数:id、docId。
  • 响应结构:Result<Void>。
  • 行为:重置索引状态为 PENDING,清空失败原因,重新发布索引事件。

章节来源

  • KnowledgeBaseController.java:92-98
  • KnowledgeDocService.java:140-180

下载文档

  • 方法:GET
  • 路径:/knowledge-bases/{id}/docs/{docId}/download
  • 鉴权:需要登录身份;仅上传者可下载;前端必须携带 x-token。
  • 路径参数:id、docId。
  • 响应结构:裸文件流,HTTP 头中包含 Content-Disposition: attachment; filename*=UTF-8''{encodedFileName}。
  • 副作用:写入 KnowledgeDocDownloadLog,并原子增加 download_count。
  • 常见错误码:
    • 404:文档不存在或已删除。
    • 400:只能操作自己上传的文档。

章节来源

  • KnowledgeBaseController.java:100-122
  • KnowledgeDocService.java:100-140

配置项与容量限制

配置前缀

知识库相关配置位于 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 限制,超时后剩余块跳过。

章节来源

  • KnowledgeProperties.java:1-65
  • KnowledgeDocParser.java:18-55
  • KnowledgeDocIndexer.java:140-200
  • KnowledgeDocVO.java:1-38

依赖关系分析

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"]

图表来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocService.java:1-247
  • KnowledgeDocParser.java:1-55
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeDocIndexEvent.java:1-59

章节来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocService.java:1-247
  • KnowledgeDocIndexer.java:1-359

性能特征与优化建议

现有优化点

  • 异步解耦:上传不等待索引完成,提升接口响应速度。
  • 事务安全发布:事件在事务提交后发布,避免事务未提交导致异步线程读不到新文档。
  • 单线程队列:文档索引串行执行,避免多文档同时抢占嵌入模型资源。
  • 并发闸门:单文档内 chunk 嵌入并发受 indexConcurrency 控制。
  • 预算保护:indexBudgetSeconds 防止单次索引长时间占用队列。
  • 幂等重建:索引前删除旧向量行,避免重试产生重复数据。
  • sidecar 缓存:优先读取稳定文本,避免重复解析原件。
  • 原子计数:下载计数通过 SQL 自增,避免并发读改写竞争。

建议优化方向

  • 监控与指标:为索引成功率、平均索引时长、嵌入调用延迟、pgvector 写入耗时添加埋点。
  • 背压与队列监控:统计待处理事件数,避免事件积压。
  • 分页下载审计:当下载记录增长较快时,考虑归档或分页查询。
  • 向量表分区:对超大数据集可按知识库或时间对向量表做进一步治理。
  • 嵌入模型连接池:若使用在线嵌入服务,应评估连接池与重试退避策略。
  • 文件存储扩容:关注 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。

去重与幂等

  • 重试索引会先删除旧向量行,再插入新向量,因此重复事件不会产生重复向量。
  • 侧车文本与原件分离,重试时优先读取侧车;缺失则从原件兜底并重写侧车。
  • 下载计数使用 SQL 自增,避免并发写入竞争。

排查步骤

  1. 查看文档列表中的 indexStatus 与 failReason。
  2. 若为 FAILED,确认嵌入模型是否可用。
  3. 检查 sidecar 是否存在;若缺失,确认原件是否仍可读取。
  4. 检查 pgvector 向量表是否存在,以及数据库连接是否正常。
  5. 检查日志中是否有事件发布失败、索引任务提交失败或嵌入调用异常。
  6. 对于下载问题,确认前端是否携带 x-token,以及后端会话是否能解析出当前用户。

章节来源

  • KnowledgeDocService.java:60-180
  • KnowledgeDocIndexer.java:100-200
  • KnowledgeDocIndexEvent.java:20-59
  • KnowledgeDocVO.java:1-38

结论

知识文档功能通过控制器、服务层、解析器、索引器和事件机制形成清晰的分层架构。上传链路保持轻量快速,索引链路通过事件与单线程队列异步执行,既避免阻塞主流程,又保障资源可控。权限上实现了知识库级隔离与文档上传者级双重隔离;数据上通过 sidecar、pgvector 表和下载审计表实现可观测与可恢复。通过合理配置分块大小、并发度与预算时间,可以在不同规模的知识库场景中平衡吞吐、延迟与成本。