✅派聪明 RAG 项目文件上传解析模块设计方案

文件上传与解析模块实现了大文件的分片上传、断点续传、文件合并以及文档解析功能。

通过 Redis 和 MinIO 的结合，确保大文件上传的可靠性；并通过 Kafka 实现异步处理。模块支持多种文档格式（PDF、Word、Excel）的解析，并提取文本内容用于后续向量化处理。文本向量化通过调用豆包 API 实现，生成的向量数据目前存储在 Elasticsearch 中，未来将同时支持 FAISS 存储。

一、核心功能设计

二、数据流转与存储设计

文件从上传到向量化完成的完整流程：

客户端计算文件 MD5，发起上传请求→服务端验证文件是否已存在，返回分片策略
客户端根据策略分片上传文件
服务端接收分片，存入 MinIO 并更新 Redis 状态
所有分片上传完成后，触发合并操作
合并完成后发送解析任务到 Kafka→解析服务消费任务，根据文件类型选择相应解析器提取文本
文本分块后发送向量化任务到 Kafka→向量化服务消费任务，调用豆包 API 将文本转换为向量表示
向量数据写入 Elasticsearch 和预留 FAISS 接口→更新任务状态，通知用户处理完成

01、MySQL

文件主表(file_upload)：存储文件元信息，如 MD5、名称、大小、状态

分片表(chunk_info)：记录每个分片的信息，包括索引、MD5、存储路径

解析结果表(document_vectors)：存储文本分块和向量化结果的元数据

02、Redis

使用 BitSet 记录已上传分片的位图（SETBIT命令）；存储上传任务的临时状态和进度；...

热门评论

Nanako 2026年03月21日 18:07

@派聪明文件上传完并合并完之后，完整的文件会按一个目录结构存在数据库里吗（例如MySQL)?

回复5 取消回复

派聪明 2026年03月21日 18:07

文件合并后，**完整文件不会直接存储在数据库中**，而是保存在文件系统（如MinIO），数据库仅记录文件的元数据信息。具体说明如下： ### 1. **文件存储位置** - **文件系统**：合并后的文件存储在MinIO的`/documents/{userId}/{fileName}`路径下（参考资料[3]）。 - **数据库**：仅存储文件的元数据（如MD5、文件名、大小、状态等），不存储实际文件内容（参考资料[5][6][10]）。 ### 2. **目录结构处理** - **文件系统保留结构**：若上传的是文件夹，合并后的文件在MinIO中会保持原始目录层级（参考资料[4][8]）。 - **数据库记录路径**：数据库通过`file_name`字段记录文件名（可能包含路径信息），但**不存储目录结构本身**（参考资料[6][10]）。例如： ```sql -- MySQL表结构示例（参考资料[5]） CREATE TABLE file_upload ( file_md5 VARCHAR(32) PRIMARY KEY, -- 文件唯一标识 file_name VARCHAR(255) NOT NULL, -- 文件名（可能含路径） storage_path VARCHAR(255) -- 文件系统存储路径（如MinIO路径） ); ``` ### 3. **关键设计逻辑** - **分片合并**：文件分片上传后，服务端在MinIO合并为完整文件（参考资料[3]）。 - **元数据管理**：数据库通过`file_upload`表记录文件元数据，`chunk_info`表记录分片信息（参考资料[5][10]）。 - **虚拟路径存储**：数据库中存储的是文件在MinIO的虚拟路径（如`/documents/user1/report.pdf`），而非二进制内容（参考资料[6][10]）。 ### 总结 - **实际文件**：存储在文件系统（MinIO），保留目录结构。 - **数据库**：仅存储文件的元数据（如MD5、路径、大小等），不存储文件内容或目录结构本身。若需管理目录层级，需在文件系统层面维护，数据库通过路径字符串间接体现（如`file_name="folder/subfolder/report.pdf"`）。

回复取消回复

展开剩余 4 条回复

102 条评论

angrybird 2026年04月17日 22:51

引用原文：预留 FAISS 接口

@派聪明这是什么

心平气和 2026年04月12日 16:52

引用原文：分片表

应该是分块表

亚泽 2026年04月09日 09:02

引用原文：成功：

@派聪明请问这里progress的含义是什么？

引用原文：失败响应

@派聪明成功响应中各个参数的含义

落后的店员 2026年04月07日 23:00

@派聪明 MinIO 实现热冷数据分离是什么意思？

落后的店员 2026年04月07日 18:57

引用原文：实现热冷数据分离

@派聪明这里什么是冷热数据

素月 2026年04月07日 14:52

引用原文：热冷数据分离

@派聪明这个是什么

兴奋的微笑 2026年04月02日 15:55

引用原文：调用豆包 API 将文本转换为向量表示

@派聪明这里向量化的是chunk还是整个文档

Te Fuir 2026年03月31日 17:18

@派聪明分片上传过程中，若redis存储的分片上传信息过期或极端环境下redis挂了，除了通过数据库存储的分片信息，还有什么兜底策略？有设置过期时间或刷新TTL吗？

回复1 取消回复

派聪明 2026年03月31日 17:21

根据资料，系统在Redis故障或信息过期时，已设计多重兜底策略，具体如下： ### 1. **数据库持久化兜底** - **分片表（`chunk_info`）**：所有分片上传成功后，其路径、索引、MD5等关键信息会**同步写入MySQL**（见"数据库设计"章节）。 - **合并校验**：文件合并时，系统会**直接查询MySQL的`chunk_info`表**，验证分片完整性，无需依赖Redis（见"文件合并流程"）。 ### 2. **Redis故障的降级处理** - **绕过Redis直接校验**：若Redis不可用，合并流程通过MySQL获取分片列表，确保合并操作正常执行（依赖数据库的持久化数据）。 - **进度查询降级**：`/api/v1/upload/status`接口在Redis缺失时，可回退到查询MySQL的`chunk_info`表计算进度（见"查询上传状态接口"）。 ### 3. **TTL设置与刷新机制** - **TTL配置**：Redis中分片状态存储**设置了过期时间**（资料未明确具体时长，但设计为临时状态）。 - **自动刷新TTL**：每次分片上传成功时，系统会**重置对应分片TTL**（通过Redis命令），确保上传过程中状态不失效。 ### 4. **极端场景的兜底策略** - **MD5全局校验**：客户端上传前计算文件MD5，服务端通过该值校验文件是否已存在（见"数据流转设计"），避免重复上传。 - **分片完整性校验**：合并前校验所有分片MD5与`chunk_info`表记录一致，确保数据无丢失。 ### 总结系统通过 **MySQL持久化存储 + Redis缓存 + MD5校验** 三重保障，确保即使Redis故障或状态过期，分片上传仍能可靠完成。TTL机制通过分片上传成功时自动刷新，避免正常上传过程中状态失效。

酷炫的仙人掌 2026年03月28日 19:01

@派聪明为什么需要mysql和redis两层存储分片文件信息

回复3 取消回复

派聪明 2026年03月28日 19:03

系统采用 **MySQL + Redis 双层存储** 分片文件信息，主要基于以下核心考虑： --- ### 1. **功能定位不同** - **MySQL（持久化存储）** - **存储完整分片元数据**：在 `chunk_info` 表中永久记录分片的索引、MD5、存储路径等结构化信息（见参考资料“数据库设计”）。 - **支持复杂查询**：如按文件MD5查询所有分片、统计分片数量等，需事务保障数据一致性。 - **长期可靠性**：确保分片信息在系统重启后不丢失。 - **Redis（高性能缓存）** - **实时状态追踪**：使用 **BitSet** 记录已上传分片状态（`SETBIT` 命令），实现毫秒级进度计算（如 `progress = 已上传分片数 / 总分片数`）。 - **临时任务管理**：缓存上传任务的中间状态（如当前上传用户、分片策略），避免频繁访问数据库。 - **热点数据加速**：缓存高频访问的文件元数据（如大文件分片状态），减轻MySQL压力。 --- ### 2. **性能与效率优化** - **高频写入场景**：分片上传时需频繁更新上传状态（每片一次）。Redis的内存操作（O(1)复杂度）远快于磁盘IO，大幅降低延迟。 - **实时进度反馈**：客户端通过 `/api/v1/upload/status` 接口查询进度时，Redis直接返回位图状态，无需扫描MySQL全表。 --- ### 3. **容错与数据一致性** - **Redis作为状态缓存**：即使Redis重启，丢失的临时状态可通过MySQL恢复（如重新计算已上传分片）。 - **MySQL作为数据源**：分片元数据持久化存储，确保文件合并、解析等后续流程依赖的数据不丢失。 --- ### 4. **扩展性设计** - **分片状态与元数据分离**： Redis处理动态状态（进度、任务），MySQL处理静态元数据（路径、MD5），职责清晰，便于独立扩展。 - **未来适配**：若需支持断点续传，Redis的BitSet可直接提供断点位置，无需查询数据库。 --- ### 总结 | **存储层** | **核心作用** | **典型场景** | |------------|---------------------------------------|----------------------------------| | **MySQL** | 持久化分片元数据，支持复杂查询与事务 | 分片合并、文件解析、长期归档 | | **Redis** | 高性能缓存分片状态，实时进度计算 | 上传进度反馈、任务临时状态管理 | 这种设计在**性能、可靠性、一致性**之间取得平衡，尤其适合大文件分片上传的高并发场景。

展开剩余 2 条回复