关注公众号
原创

✅派聪明 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命令）； 存储上传任务的临时状态和进度； 缓存热点文件的元数据，减轻数据库压力

03、MinIO

临时分片：存储上传的文件分片，路径结构为/temp/{fileMd5}/{chunkIndex}

完整文件：合并后的文件存储在/documents/{userId}/{fileName}

存储策略：实现热冷数据分离

04、 Elasticsearch

存储文本向量数据和原始文本内容，索引基于文件 MD5 和分块 ID 组织

三、关键流程

01. 分片上传流程

02. 文件合并流程

03.文档处理流程（合并解析和向量化）

04.文档删除流程

四、接口设计

01、分片上传接口

基本信息

  • URL: /api/v1/upload/chunk

  • Method: POST

  • Headers

Authorization: Bearer {token}
  • Body (multipart/form-data)
fileMd5: d41d8cd98f00b204e980099...
以下内容需要加入二哥编程星球解锁，即刻绑定星球编号解锁🔐
已加入星球，可直接知识星球授权登录
二哥编程星球目前包含：
企业级Agent工作流编排项目PaiFlow
Vibe Coding版本的PaiAgent
派聪明RAG AI知识库Java版本+Go版本
微服务 PmHub、技术派、MYDB
求职派JobClaw（OpenClaw/Hermes架构
PaiCLI（类似Claude Code的Agent
派简历（代码已完成）
等实战项目。

1. 微信扫右侧的优惠券加入知识星球

2. 解锁星球的实战项目教程和源码： 项目源码+教程获取

二哥的星球

47人已点赞

杠精派
派聪明
0/512

热门评论

玄英 2026年06月24日 17:21
@派聪明 文件解析的时候会在mysql中也存一次文本数据吗？
点赞
回复9 取消回复
派聪明 2026年06月24日 17:21
根据提供的参考资料，**是的，文件解析时MySQL中也会存储文本数据**。 在数据库设计的**解析结果表（`document_vectors`）**中，有一个 `text_content` 字段（`TEXT` 类型），专门用于存储解析后提取的**文本分块内容**。表的定义如下： ```sql CREATE TABLE document_vectors ( vector_id BIGINT AUTO_INCREMENT PRIMARY KEY, file_md5 VARCHAR(32) NOT NULL, chunk_id INT NOT NULL, text_content TEXT COMMENT '文本内容', -- 这里存储文本数据 model_version VARCHAR(32), user_id VARCHAR(64) NOT NULL, org_tag VARCHAR(50), is_public BOOLEAN NOT NULL DEFAULT FALSE ); ``` 此外，参考资料中提到，**Elasticsearch** 也会存储原始文本内容和向量数据。也就是说，文本数据实际上是**双存储**的： - **MySQL**：存储文本分块内容，用于元数据管理和快速查询 - **Elasticsearch**：同时存储原始文本和向量数据，用于后续的向量检索 两者的定位不同：MySQL 偏向**记录与状态管理**，ES 偏向**搜索与向量匹配**。
点赞
回复 取消回复
展开剩余 8 条回复

130 条评论

A.Mars（水准） 2026年07月02日 00:02
引用原文：实现热冷数据分离
实现冷热数据分离是什么意思@派聪明
点赞
回复1 取消回复
派聪明 2026年07月02日 00:02
## 冷热数据分离是什么意思？ **冷热数据分离**是一种数据存储优化策略，核心思想是：**根据数据的访问频率，将不同"热度"的数据存储在不同的存储介质或路径上，以平衡性能与成本。** ### 🌡️ 数据热度分类 | 类型 | 特征 | 存储方式 | |------|------|----------| | **热数据** | 频繁访问、实时性高 | 高性能存储（如 SSD、本地磁盘） | | **温数据** | 偶尔访问 | 中等性能存储 | | **冷数据** | 很少访问、归档性质 | 低成本存储（如对象存储、磁带） | ### 📎 结合参考资料中的理解 在您引用的文档中，MinIO 存储策略实现热冷数据分离，具体体现为： - **临时分片**（上传中的分片数据） → 存储在 `/temp/{fileMd5}/{chunkIndex}`，属于短期热数据，上传完成后即可清理 - **完整文件**（合并后的正式文件） → 存储在 `/documents/{userId}/{fileName}`，属于长期存储的冷/温数据 这样做的**好处**： 1. **降低存储成本**——冷数据不需要放在昂贵的存储上 2. **提升访问效率**——热数据放在更快的位置，减少 I/O 延迟 3. **便于生命周期管理**——可以针对不同温度的数据设定不同的备份、清理策略 简单来说，就是**让合适的数据待在合适的地方**。
点赞
回复 取消回复
A.Mars（水准） 2026年07月01日 23:49
引用原文：状态
文件状态在这里指的是什么@派聪明
点赞
回复1 取消回复
派聪明 2026年07月01日 23:49
根据参考资料，文件状态指的是**文件上传状态**，记录在 `file_upload` 表的 `status` 字段中，具体含义如下： - **0**：上传中（文件正在分片上传或合并中） - **1**：已完成（文件已成功上传并合并完成）
点赞
回复 取消回复
haohao 2026年06月30日 10:12
CREATE TABLE file_upload ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键', file_md5 VARCHAR(32) NOT NULL COMMENT '文件的MD5值，用于识别文件内容', file_name VARCHAR(255) COMMENT '文件的原始名称', total_size BIGINT NOT NULL COMMENT '文件总大小(字节)', status INT NOT NULL DEFAULT 0 COMMENT '文件上传状态：0-上传中，1-已完成，2-合并中', user_id VARCHAR(64) NOT NULL COMMENT '上传用户的标识符', org_tag VARCHAR(255) COMMENT '文件所属组织标签', is_public BOOLEAN NOT NULL DEFAULT FALSE COMMENT '文件是否公开', estimated_embedding_tokens BIGINT C
点赞
回复 取消回复
聪明的小土豆 2026年06月26日 09:15
引用原文：FAISS
@派聪明 这是什么呀？
点赞
回复1 取消回复
派聪明 2026年06月26日 09:15
根据提供的参考资料，**FAISS** 是一个用于**存储文本向量数据**的系统（或接口）。 在文档解析与处理的流程中，文件被解析提取出文本后，会通过调用豆包 API 将文本转换为向量表示。这些生成的向量数据目前主要是存储在 **Elasticsearch** 中，但系统未来计划**同时支持使用 FAISS 来进行存储**（资料中提及已预留了 FAISS接口）。
点赞
回复 取消回复
玄英 2026年06月24日 17:22
@派聪明 文件解析的时候会在mysql中也存一次文本数据吗
点赞
回复1 取消回复
派聪明 2026年06月24日 17:22
是的，MySQL中会存储文本数据。具体体现在 **`document_vectors`（解析结果表）** 中，该表包含一个 `text_content TEXT` 字段，用于存储解析后提取的文本内容。 ```sql CREATE TABLE document_vectors ( vector_id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '向量记录唯一标识', file_md5 VARCHAR(32) NOT NULL COMMENT '关联的文件MD5值', chunk_id INT NOT NULL COMMENT '文本分块序号', text_content TEXT COMMENT '文本内容', -- 这里存储文本数据 model_version VARCHAR(32) COMMENT '向量模型版本', user_id VARCHAR(64) NOT NULL COMMENT '上传用户ID', org_tag VARCHAR(50) COMMENT '文件所属组织标签', is_public BOOLEAN NOT NULL DEFAULT FALSE COMMENT '文件是否公开' ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文档向量存储表'; ``` **数据流转流程是**：文件合并完成后发送解析任务到 Kafka → 解析服务消费任务，根据不同文件类型（PDF、Word、Excel）提取文本 → 文本分块后，一方面将文本内容（`text_content`）存入 MySQL 的 `document_vectors` 表，另一方面发送向量化任务到 Kafka → 向量化服务调用豆包 API 生成向量数据，最终存入 Elasticsearch。 所以 MySQL 中存储的是原始文本分块内容（作为元数据持久化），而向量数据则存储在 Elasticsearch 中（未来也会支持 FAISS）。
点赞
回复 取消回复
玄英 2026年06月24日 17:21
@派聪明 文件解析的时候会在mysql中也存一次文本数据吗？
点赞
回复9 取消回复
派聪明 2026年06月24日 17:21
根据提供的参考资料，**是的，文件解析时MySQL中也会存储文本数据**。 在数据库设计的**解析结果表（`document_vectors`）**中，有一个 `text_content` 字段（`TEXT` 类型），专门用于存储解析后提取的**文本分块内容**。表的定义如下： ```sql CREATE TABLE document_vectors ( vector_id BIGINT AUTO_INCREMENT PRIMARY KEY, file_md5 VARCHAR(32) NOT NULL, chunk_id INT NOT NULL, text_content TEXT COMMENT '文本内容', -- 这里存储文本数据 model_version VARCHAR(32), user_id VARCHAR(64) NOT NULL, org_tag VARCHAR(50), is_public BOOLEAN NOT NULL DEFAULT FALSE ); ``` 此外，参考资料中提到，**Elasticsearch** 也会存储原始文本内容和向量数据。也就是说，文本数据实际上是**双存储**的： - **MySQL**：存储文本分块内容，用于元数据管理和快速查询 - **Elasticsearch**：同时存储原始文本和向量数据，用于后续的向量检索 两者的定位不同：MySQL 偏向**记录与状态管理**，ES 偏向**搜索与向量匹配**。
点赞
回复 取消回复
展开剩余 8 条回复
nyl 2026年06月15日 18:56
引用原文：存储上传的文件分片，路径结构为/temp/{fileMd5}/{chunkIndex}
临时数据删除了吗
点赞
回复 取消回复
boom 2026年06月09日 21:28
@派聪明 文档分片操作是在前端代码中完成吗？分片后一个一个上传到后端的/api/v1/upload/chunk接口吗？
点赞
回复1 取消回复
派聪明 2026年06月09日 21:28
是的。根据提供的系统设计，文档的分片上传机制如下： 1. **前端负责分片计算**：上传流程的第一步是“客户端根据策略分片上传文件”，这意味着前端代码需要将大文件分割成多个分片，并为每个分片标记索引。 2. **逐个上传至后端**：分片后，前端会调用 `/api/v1/upload/chunk`接口，将分片数据逐个发送给后端。从接口参数设计可以看出，每次请求都会携带一个具体的 `chunkIndex`（分片索引）和对应的分片文件数据。 3. **后端记录与合并**：后端接收到这些分片后，会存入 MinIO 的临时目录中，并通过 Redis 的 BitSet技术记录已上传的分片位图。当所有分片全部上传完成后，前端再调用 `/api/v1/upload/merge`接口，触发后端进行文件合并。
点赞
回复 取消回复
walter 2026年05月28日 15:49
引用原文：四、接口设计
为什么没有说文档解析与向量化的接口设计
点赞
回复1 取消回复
walter 2026年05月28日 15:53
@派聪明，为什么这里没有说文档解析与向量化的接口设计
点赞
回复 取消回复
junnichi910 2026年05月26日 20:46
引用原文：PDF、Word、Excel
@派聪明 如果文档有表格怎么处理，表格跨页怎么处理
点赞
回复 取消回复

目录