夜雨聆风学习资料网

ARTICLE · 1376640

数智人事系统(二十一):知识库文档的入库与清理

数智人事系统(二十一):知识库文档的入库与清理

数智人事系统(二十一):知识库文档的入库与清理

在企业日常办公中,员工手册、考勤制度、请假规定和业务操作说明等文档,通常分散在不同的文件或系统中。员工想了解某项制度,或查询某个业务流程时,往往需要人工查找,效率不高。

如果希望 AI 助手能够依据企业内部的制度和文档回答问题,就需要先建立统一的知识库,将这些资料集中管理,并为后续的知识检索和问答提供数据基础。

本期目标

本期主要完成知识库文档的入库与清理,包括创建文档记录、异步完成解析与切片、生成并保存向量、维护处理状态,以及在删除文档时清理相关数据。

切片算法、向量生成的具体细节,以及检索和问答功能的完整实现,将放在后续第 22~24 期介绍。

需求分析

知识库模块主要负责管理企业内部文档,并为后续的知识检索和问答提供数据基础。结合这一目标,需要实现以下几项基本功能。

文档列表与状态展示:用户进入知识库页面后,可以查看已上传的文档,包括文档名称、文件类型、文件大小、上传时间和处理状态等信息。文档解析需要一定时间,因此页面还需要展示当前处理状态,让用户了解文档是否已经处理完成,或是否处理失败。

查看文档切片:文档处理完成后,用户可以查看系统生成的文本切片,了解原始文档被拆分成了哪些内容。每个切片需要展示对应的文本,方便检查解析和切片结果是否符合预期。

文档重新处理:用户可以对处理失败或已经处理完成的文档重新发起处理。处理失败的文档可以通过重试恢复处理;对于已经处理完成的文档,也可以根据需要重新解析,生成新的切片和向量数据。

删除文档:用户可以删除不再需要的知识库文档。删除后,不仅需要移除文档列表中的记录,还要清理对应的切片、向量数据和原始文件,避免留下无效数据。

方案设计

技术选型

知识库模块涉及文档存储、文本处理、向量化和检索等环节,主要技术选型如下:

环节
技术选型
主要用途
文档元数据
MySQL + MyBatis-Plus
存储文档信息和处理状态
原始文件
MinIO
存储上传的原始文档
切片与向量
PostgreSQL + pgvector
存储切片文本和向量
向量读写
JdbcTemplate
通过原生 SQL 操作切片数据
对话模型
Spring AI OpenAI Starter
通过 DashScope 兼容模式调用
文本向量化
Spring AI EmbeddingModel
通过兼容模式批量生成文本向量

文档元数据需要关联员工信息,并参与现有业务事务,因此继续使用 MySQL 主库。向量检索使用 PostgreSQL 的 pgvector 扩展,同时利用 PostgreSQL 的文本查询能力实现关键词检索,无需额外引入独立的向量数据库。相应地,项目需要额外维护一套 PostgreSQL 实例,并处理 MySQL 与 PostgreSQL 之间的数据清理问题。

配置说明

模型地址、凭据和模型名称统一放在 llm.* 配置项中:

# application.yml:114llm:  base-url: ${LLM_BASE_URL:https://dashscope.aliyuncs.com/compatible-mode}  api-key: ${LLM_API_KEY:}  chat-model: ${LLM_CHAT_MODEL:qwen3.7-flash}  embedding-model: ${LLM_EMBEDDING_MODEL:qwen3.7-text-embedding-flash}  rerank-model: ${LLM_RERANK_MODEL:qwen3.7-text-rerank}

切片参数单独放在 kb.chunk.* 配置项中:

# application.yml:130kb:  enabled: true  chunk:    max-size: 1000    overlap: 100

模型名称和密钥通常会随部署环境变化,也不适合直接提交到代码仓库,因此通过 spring.config.import 从 .env 文件中读取:

# application.yml:10spring:  config:    import: optional:file:.env[.properties],optional:file:hrm-server/.env[.properties]

这里配置了两个查找路径,分别对应从项目根目录和 hrm-server/ 目录启动应用的情况。optional: 前缀表示即使对应的 .env 文件不存在,应用也可以继续启动。配置示例放在随代码入库的 hrm-server/.env.example 中,用占位值列出需要在部署环境中提供的变量:

# .env.example:10LLM_API_KEY=<API密钥>LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-modeLLM_CHAT_MODEL=qwen3.7-flashLLM_EMBEDDING_MODEL=qwen3.7-text-embedding-flashLLM_RERANK_MODEL=qwen3.7-text-rerankJWT_SECRET=REPLACE_WITH_BASE64_JWT_SECRET

其中,五个 LLM_* 变量对应 llm.* 配置项,JWT_SECRET 则由认证模块单独使用。这样,切换模型或修改密钥时,只需要调整 .env 文件,不必修改源码或提交敏感配置。

切片参数由 IngestionPipeline 读取。max-size: 1000 用于限制单个切片的最大字符数,overlap: 100 表示相邻切片之间保留 100 个字符的重叠,以减少切片边界处的上下文丢失。切分逻辑本身是纯函数,参数由调用方传入;具体切分过程将在后续介绍摄入流水线时展开。

实现方案

知识库模块主要分为文档管理、文档摄入和检索数据管理三个部分。各部分职责相对独立,并通过文档 ID 关联数据。

文档管理

负责文档信息入库、状态维护、查询、重试和删除。文档上传完成后,系统先创建文档记录,并将其状态初始化为待处理。后续处理过程中的状态变化和处理结果,都通过该记录统一维护。

文档摄入

负责将原始文档转换为可检索的数据,这一过程可以概括为 ETL(提取、转换、加载)。主要步骤包括文件读取、解压、内容解析、文本清洗、切片、向量化和结果存储。上传回调会根据文件类型决定是否使用 zstd 压缩后再存入 MinIO;摄入时则先根据文件魔数判断是否需要解压,再进行解析和文本清洗,最终得到纯文本。

文档处理涉及文件解析和模型调用,执行时间相对较长。如果在上传请求中同步完成,容易延长请求响应时间。因此,这部分采用异步方式执行,避免阻塞用户的上传请求。

此外,为避免同一份文档被重复处理,系统采用基于文档状态的 CAS(Compare-And-Swap,比较并交换)机制认领处理任务。首次处理和重试共用同一个认领入口,只有成功认领文档的请求才能派发后续处理任务。

处理成功后,文档状态更新为 READY;发生异常时则更新为 FAILED,并记录失败原因,方便用户查看和重新处理。

检索数据管理

负责保存文档切片、来源信息和向量数据,为后续的关键词检索与向量检索提供数据基础。切片中会保留文档名称,检索命中后可以直接获取来源信息,无需再跨库查询文档记录。

整体处理流程如下:

分片上传完成  → 创建文档记录(UPLOADED)  → CAS 认领(PROCESSING)  → 事务提交后派发线程池任务  → 文件解析与文本清洗  → 文本切片  → 批量向量化  → 保存切片与向量  → 更新文档状态(READY / FAILED)

文档删除与异常清理

文档删除涉及 MySQL、PostgreSQL 和 MinIO 三处存储,无法通过一个本地事务保证数据一致性。因此,删除时分别清理各处数据;如果清理失败,则记录日志,并由定时任务进行补偿。

定时清理主要处理以下两类数据:

  • • MinIO 中没有文档记录引用的文件。每天 04:30 扫描 kb/ 前缀下的对象,清理超过 24 小时且仍没有文档记录引用的残留文件。设置宽限期,是为了避免误删刚上传、但尚未创建文档记录的文件。
  • • PostgreSQL 中找不到对应 MySQL 文档记录的切片。每天 04:45 扫描并清理已经失去文档记录的切片。

通过这两项定时任务,可以处理文档删除过程中可能残留的数据。

数据库设计

本模块涉及两张核心数据表,分别存储在 MySQL 和 PostgreSQL 中。

kb_document:文档元数据表

该表存储在 MySQL 中,主要记录文件信息、处理状态、处理结果和上传者信息(db/mysql/hrm.sql):

-- mysql/hrm.sql:1440CREATE TABLE `kb_document` (  `id`              bigint        NOT NULL AUTO_INCREMENT COMMENT '主键',  `name`            varchar(200)  NOT NULL COMMENT 'MinIO 对象键(物理文件引用键)',  `type`            varchar(10)   DEFAULT NULL COMMENT '文件类型',  `old_name`        varchar(200)  DEFAULT NULL COMMENT '文件原名称',  `file_hash`       varchar(64)   DEFAULT NULL COMMENT '文件SHA256哈希',  `size`            bigint        DEFAULT NULL COMMENT '文件原始大小KB',  `stored_size`     bigint        DEFAULT NULL COMMENT '磁盘实际占用(字节)',  `compressed`      tinyint(1)    NOT NULL DEFAULT 0 COMMENT '是否zstd压缩: 0=否 1=是',  `staff_id`        int           DEFAULT NULL COMMENT '上传者id',  `status`          varchar(20)   NOT NULL DEFAULT 'UPLOADED' COMMENT 'UPLOADED/PROCESSING/READY/FAILED',  `failure_reason`  varchar(512)  DEFAULT NULL COMMENT '处理失败原因',  `preview_text`    text          COMMENT '文档预览文本',  `chunk_count`     int           DEFAULT 0 COMMENT '切片数量',  `upload_time`     datetime      DEFAULT NULL COMMENT '上传完成时间',  `process_time`    datetime      DEFAULT NULL COMMENT '处理完成时间',  `create_time`     datetime      NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',  `update_time`     datetime      DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',  PRIMARY KEY (`id`),  UNIQUE KEY `uk_document_name` (`name`),  KEY `idx_document_status` (`status`),  KEY `idx_document_staff_hash` (`staff_id`, `file_hash`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='知识库文档';

其中,name 保存 MinIO 对象键,也就是文件在对象存储中的唯一定位信息;old_name 保存用户上传时的原始文件名,用于页面展示。compressed 字段用于标记存储对象是否经过 zstd 压缩。DocumentUploadCompletionHandler.onComplete 会在提交文档记录前,根据文件类型尝试压缩;摄入线程读取文件时,则通过魔数判断是否需要解压。对后续解析逻辑而言,这一过程是透明的。

索引方面,唯一索引用于保证对象键不重复;状态索引用于按处理状态查询文档;上传者与文件哈希组成联合索引,用于满足相关查询需求。

kb_chunk:切片向量表

该表存储在 PostgreSQL 中(db/postgresql/hrm_kb.sql),主要字段如下:

  • • document_name:文档名称,取自 kb_document.old_name,即用户上传时使用的文件名。
  • • chunk_text、chunk_index:分别表示切片内容和切片序号。
  • • token_count、chunk_summary:分别表示切片统计信息和摘要。其中,token_count 是切分工具根据字符数估算的词元数量,并非精确的分词结果。
  • • char_start、char_end:切片在原文中的起止位置。
  • • embedding:1024 维向量。
-- postgresql/hrm_kb.sql:7CREATE EXTENSION IF NOT EXISTS vector;CREATE TABLE IF NOT EXISTS kb_chunk (    id              BIGSERIAL PRIMARY KEY,    document_id     BIGINT       NOT NULL,    document_name   VARCHAR(255) NOT NULL DEFAULT '',    chunk_index     INT          NOT NULL,    chunk_text      TEXT         NOT NULL,    token_count     INT          DEFAULT 0,    chunk_summary   TEXT,    char_start      INT          DEFAULT 0,    char_end        INT          DEFAULT 0,    embedding       vector(1024),    create_time     TIMESTAMP    NOT NULL DEFAULT NOW(),    UNIQUE (document_id, chunk_index));CREATE INDEX IF NOT EXISTS idx_chunk_document ON kb_chunk(document_id);CREATE INDEX IF NOT EXISTS idx_chunk_embedding    ON kb_chunk USING hnsw (embedding vector_cosine_ops)    WHERE embedding IS NOT NULL;

切片文本、文档名称和向量保存在同一张表中。检索命中后,可以直接获取来源信息,无需跨库查询。这样设计也有一个代价:表中包含体积较大的向量列,因此查询切片列表时不能使用 SELECT *,而应像 DocumentChunkMapper.selectByDocumentIdOrderByChunkIndex 一样,显式列出需要的字段。向量列只在检索流程中读取。

索引方面,(document_id, chunk_index) 唯一约束用于避免同一文档出现重复序号的切片;文档 ID 索引用于支持按文档查询和删除;HNSW(Hierarchical Navigable Small World,分层可导航小世界图)索引则用于加速向量近邻检索。

核心功能实现

文档提交与任务派发

DocumentService 是文档模块对外提供服务的统一入口。上传完成回调是文档提交流程的起点:DocumentController 将 DocumentUploadCompletionHandler 交给 FileUploadService.completeUpload,后者在同一个事务中合并分片,再回调 handler.onComplete。回调负责读取合并后的文件、按需压缩,并构造 Document 对象,最后调用 submit 方法。

submit 首先插入一条状态为 UPLOADED 的文档记录,然后在同一事务中调用 claimForProcessing,将文档认领为 PROCESSING,以避免重复处理。真正的解析和摄入任务则要等事务提交后才会派发:

// DocumentService.java:98@Transactional(rollbackFor = Exception.class)public void submit(Document document) {    document.setStatus(DocumentStatusEnum.UPLOADED.name())            .setUploadTime(LocalDateTime.now());    documentMapper.insert(document);    // 新行必是 UPLOADED,认领不会落空;保留是为了让两条命令路径都经由同一状态入口    Long documentId = document.getId();    documentMapper.claimForProcessing(documentId);    // 必须等提交:worker 读不到未提交的行,抢跑会卡死在 PROCESSING    TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {        @Override        public void afterCommit() {            ingestExecutor.execute(() -> pipeline.run(documentId));        }    });}

事务外直接调用 submit 时,该方法会开启自己的事务;如果它由上传回调在外层事务中调用,则会加入外层事务。无论哪种情况,工作线程都只能在事务提交后读取到文档记录。

这里的 UPLOADED 和 PROCESSING 会在同一次事务提交前依次写入,因此外部通常看不到 UPLOADED 状态。保留这一状态,主要是为了让首次提交和重试共用同一套认领入口,避免新建文档时直接设置为 PROCESSING,形成一条特殊处理路径。

任务通过 afterCommit 派发,而不是在事务尚未提交时直接提交到线程池。这是因为处理线程使用另一个数据库连接,事务未提交时无法读取刚插入的文档记录。重试也不需要重新上传文件:原始文件仍保存在 MinIO 中,只需重新认领文档并派发任务即可。重试时的认领操作是一条自动提交的 UPDATE。

submit 和 retry 这两个修改状态并触发任务派发的命令方法,不应在同一个类中通过 this 相互调用。因为这种自调用会绕过 Spring 事务代理,导致事务同步回调无法按预期注册或生效。

文档处理与状态流转

文档状态定义在 DocumentStatusEnum 中:

状态
含义
UPLOADED
已上传,等待处理
PROCESSING
正在处理
READY
处理完成,可以参与检索
FAILED
处理失败,可以重新尝试

正常情况下,状态流转为 UPLOADED → PROCESSING → READY;处理过程中抛出异常时,管道会调用 markFailed,将状态更新为 FAILED。处于 READY 或 FAILED 状态的文档,也可以重新进入 PROCESSING。

目前的实现还有一个边界:认领 SQL 不接受 PROCESSING 状态。因此,如果工作进程在处理过程中崩溃,文档可能一直停留在 PROCESSING,无法通过现有重试入口重新认领,需要人工介入处理。

状态变更统一通过带前置条件的 UPDATE 完成,相关 SQL 集中在 DocumentMapper 中:

// DocumentMapper.java:42@Update("UPDATE kb_document SET status = 'PROCESSING', failure_reason = NULL, "        + "chunk_count = NULL, preview_text = NULL, update_time = NOW() "        + "WHERE id = #{id} AND status IN ('UPLOADED', 'READY', 'FAILED')")int claimForProcessing(Long id);@Update("UPDATE kb_document SET status = 'READY', preview_text = #{previewText}, "        + "chunk_count = #{chunkCount}, failure_reason = NULL, process_time = NOW(), update_time = NOW() "        + "WHERE id = #{id} AND status = 'PROCESSING'")int completeProcessing(@Param("id") Long id, @Param("previewText") String previewText,                       @Param("chunkCount") Integer chunkCount);@Update("UPDATE kb_document SET status = 'FAILED', failure_reason = #{reason}, update_time = NOW() "        + "WHERE id = #{id} AND status = 'PROCESSING'")int markFailed(@Param("id") Long id, @Param("reason") String reason);

这三条 SQL 分别负责认领任务、标记处理成功和标记处理失败。后两步通过 WHERE 中的状态条件与 UPDATE 的原子性控制并发:如果多人同时尝试处理同一份文档,只有第一条符合条件的 UPDATE 会影响 1 行,其余请求影响 0 行,并据此退出。

认领文档时,还会清空上一轮处理留下的失败原因、chunk_count 和 preview_text,避免旧结果影响本轮处理。

completeProcessing 要求文档当前状态为 PROCESSING。如果文档在处理期间被删除,这条 UPDATE 就会影响 0 行,管道据此删除本次 ETL 刚写入的切片,避免留下无主数据。markFailed 同样限定当前状态为 PROCESSING,因此不会覆盖其他操作已经完成的状态变更。

文档删除与资源清理

删除文档时,需要同时清理三处数据:MySQL 中的文档记录、PostgreSQL 中的切片,以及 MinIO 中的原始文件。由于后续清理还需要文档 ID 和对象键,因此删除前要先查询文档信息,再删除文档记录。具体清理逻辑集中在 purge 方法中:

// DocumentService.java:169private void purge(List<Document> documents) {    List<Long> documentIds = documents.stream().map(Document::getId).toList();    List<String> storageKeys = documents.stream()            .map(Document::getName).filter(Objects::nonNull).toList();    // PG 切片必须先删:残留切片会继续参与检索,失败要留痕(DocumentCleanupJob 次日兜底)    try {        chunkMapper.deleteByDocumentIds(documentIds);    } catch (Exception e) {        log.error("删除检索产物失败,切片将残留在 kb_chunk 中,需人工清理: documentIds={}",                documentIds, e);    }    // MinIO 远端调用失败有 DocumentCleanupJob 兜底,放在最后且只记日志    try {        Set<String> failed = storageService.deleteAll(storageKeys);        if (!failed.isEmpty()) {            log.warn("删除物理文件失败(对象将由孤儿清理兜底): {}", failed);        }    } catch (Exception e) {        log.warn("删除物理文件失败(对象将由孤儿清理兜底): {}", storageKeys, e);    }}

清理顺序是先删除 PostgreSQL 中的切片,再删除 MinIO 中的原始文件。切片会直接参与检索,因此需要优先清理,避免已经删除的文档仍被检索召回。

两处清理失败都只记录日志,不影响文档删除操作的返回结果。其中,PostgreSQL 清理失败时记录 error 日志,MinIO 批量删除返回失败对象键或抛出异常时记录 warn 日志。需要注意的是,代码中的日志提示“需人工清理”并不完全准确:文档记录删除后,残留切片会由次日 04:45 执行的定时清理任务自动兜底删除;MinIO 中未被文档记录引用的对象,也会由对应的孤儿文件清理任务处理。

删除方法没有添加事务注解。原因在于,PostgreSQL 和 MinIO 的清理操作无法随 MySQL 本地事务一起回滚。如果将这些操作放在一个 MySQL 事务中,一旦事务回滚,就可能出现文档记录仍然存在,但对应切片或原始文件已经被删除的情况。

异常恢复与残留清理

正常删除流程之外可能留下的残余数据,由 DocumentCleanupJob 中的两个定时任务负责兜底:

  • • 每天 04:30 扫描 MinIO 的 kb/ 前缀,删除对象键不在 kb_document 表中、且最后修改时间超过 24 小时的对象。设置 24 小时宽限期,是为了避免误删“文件已经上传,但文档记录尚未提交”的文件。
  • • 每天 04:45 扫描 PostgreSQL,根据切片中的 document_id 删除已经找不到对应 MySQL 文档记录的切片。

第二个任务对查询顺序有要求:必须先读取切片中的文档 ID,再查询当前仍然存在的文档 ID。如果顺序相反,在两次查询之间恰好有新文档提交并生成切片,那么新文档的 ID 就不在此前读取的存活文档 ID 集合中,可能被误判为残留数据并删除。

前端交互与功能入口

前端页面位于 hrm-admin/src/views/kb/document/index.vue,提供文档上传、列表查询、状态展示、切片预览、重试和删除等功能。

上传功能复用 ChunkedImportBtn 组件,并通过 scope="DOCUMENT" 区分上传类型。分片合并完成后,前端调用 /document/upload-task 接口。当前支持 .pdf、.docx、.md 和 .txt 格式,按钮会显示“上传 2/5”一类的上传进度。

文档列表支持按 old_name 模糊查询和按状态筛选,状态通过 el-tag 展示,中文状态名称在页面内维护。对于处于 UPLOADED 或 PROCESSING 状态的文档,页面每 3 秒轮询一次列表,用户无需手动刷新即可查看处理进度。

点击“分块”可以只读查看文档切片,包括 chunk_index、token_count 和切片原文;点击“重试”需要二次确认,确认后调用 /document/{id}/retry 接口;点击“删除”则通过气泡确认后调用 DELETE /document/{id} 接口。

至此,文档从上传、创建记录、异步处理和状态维护,到删除及残留数据清理的主要流程已经打通。文档转换为切片和向量后,如何进行检索召回、如何将检索结果组织到提示词中,以及如何流式返回问答结果,属于后续知识库问答环节的内容,本期暂不展开。

效果验证

知识库文档管理主界面:

知识库主界面

文档分块预览界面:

文档分块界面

小结

本期完成了知识库文档的入库与清理流程。上传文档后,系统会创建文档记录,并异步完成解析、切片和向量保存;用户可以在列表中查看处理状态,也可以预览切片。删除文档时,系统会清理 MySQL 中的文档记录、PostgreSQL 中的切片和 MinIO 中的原始文件;如果跨存储清理失败,则由定时任务处理残留数据。

实现上,切片文本与向量保存在同一张表中,减少了检索和清理时的跨表操作,但列表查询必须显式指定字段,避免读取体积较大的向量列。任务认领采用 CAS 状态更新,没有额外引入任务表,使文档状态成为处理过程的统一依据;相应的限制是,工作进程如果在处理中途崩溃,文档可能停留在 PROCESSING,现阶段需要人工介入恢复。

至此,知识库文档管理的基础流程已经完成。下一期将继续介绍文档切片与向量化的具体实现。

在线访问:https://hrm.qiujie.net.cn

GitHub:https://github.com/quuuuj/hrm

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料