[Bug]: When uploading and parsing files in batch, the number of content blocks in the file list remains the same, but the content blocks of

[Bug]: When uploading and parsing files in batch, the number of content blocks in the file list remains the same, but the content blocks of the files that were uploaded first will be lost.

快速结论：该问题通常出现在通过 REST API 批量上传并解析大量文档（如 9000+ 文件）时，首批解析完成文件的 content blocks 丢失，chunk_num 变为 0。优先排查 Elasticsearch 资源是否饱和，并尝试降低并发任务数或分小批次处理。

问题场景

用户在 RAGFlow 中通过 API 接口批量上传并解析文档。具体工作流为：调用 POST /api/v1/datasets/{dataset_id}/documents 上传文件，随后立即调用 POST /api/v1/datasets/{dataset_id}/chunks 进行解析。在处理超过 9000 个文件时，每上传一个文件等待 1 秒，调用解析接口，再等待 10 秒再进行下一个文件的处理。最终结果是最先上传并解析完成的文件失去了所有内容块。

报错原文

chunk_num = 0
Existing chunks deleted from Elasticsearch before async parsing task runs
Elasticsearch bulk inserts use refresh=False
Elasticsearch 503 errors / shard failures due to resource saturation

注：此处为根据 Issue 上下文总结的核心错误现象和代码行为，非单一报错字符串。

原因分析

根据 Issue 分析和相关代码审查，根本原因是批量解析管道中的多个并发问题重叠导致：

主要触发路径： 当调用 POST /api/v1/datasets/{dataset_id}/chunks 时，API 会同步将 chunk_num 重置为 0 并从 Elasticsearch 中删除原有 chunks。之后才会运行异步解析任务。若异步解析任务因 Elasticsearch 过载（如处理数千文档时出现 shard 故障）失败，chunk_num 就会永久停留在 0，且 chunks 数据丢失。
二次加重因素： Elasticsearch 批量写入时使用了 refresh=False，这意味着新插入的 chunks 在解析完成后不会立即对查询可见，进一步增加了状态不一致的风险。
资源瓶颈： 对于 9000+ 文件的操作，Elasticsearch 极有可能达到资源饱和，导致 shard 故障和 503 错误，令解析任务无声失败。

环境排查

RAGFlow 版本：v0.24.0
RAGFlow 代码提交 ID：630f05b
Elasticsearch 集群健康状态（GET /_cluster/health）
系统资源（内存/CPU/磁盘 I/O）是否在批量操作期间被耗尽
MAX_CONCURRENT_TASKS 配置（默认为 5）
Elasticsearch bulk insert 的 refresh 参数状态

解决步骤

分小批次处理： 每次只提交 10–50 个文档进行解析，待所有文档状态变为 DONE 后，再提交下一批次。
降低并发任务数： 在部署配置中将 MAX_CONCURRENT_TASKS 设置为 2 或更低（默认 5）。可优先尝试。
增加查询前等待时间： 在文档状态变为 DONE 后，至少等待 1–2 秒再查询 chunks API，以应对 ES 索引刷新延迟。
验证并重新解析失败文档： 每个批次完成后，检查 chunk_num=0 的文档，并为其重新提交解析请求。
监控 Elasticsearch 健康状态： 在批量操作期间运行 GET /_cluster/health，确保集群未处于降级状态。必要时增加 ES 的内存/CPU 资源。

验证方法

完成上述操作后，重新执行批量上传与解析流程。确认首批解析完成的文件在状态变为 DONE 且等待 ES 索引刷新后，chunk_num 大于 0，且通过 chunks API 能正确返回文档内容块。

参考来源

infiniflow/ragflow #13864

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Bug]: When uploading and parsing files in batch, the number of content blocks in the file list remains the same, but the content blocks of