大PDF处理挂起怎么办?用opendataloader-pdf --hybrid-chunk-size 分块送检避坑指南
大PDF处理挂起怎么办?用opendataloader-pdf --hybrid-chunk-size 分块送检避坑指南
opendataloader-pdf 是一个面向 AI 数据准备的开源 PDF 解析工具,可将 PDF 转换为 Markdown、JSON、HTML。当你启用 --hybrid 模式处理几百页的大型文档时,后端请求很容易长时间无响应甚至挂起。而 --hybrid-chunk-size 参数正是官方为此提供的"分块送检"开关——它能把大文档拆成多个批次分批交给 AI/OCR 后端处理,从根源上避免单次请求过大导致的挂起。
为什么大 PDF 会挂起?
在 hybrid 模式下,PDF 需要发送到独立的后端服务(如 docling-fast)进行 OCR、表格结构分析或公式提取。早期版本会把所有待处理页面打包成一次请求发给后端,文档越大,后端处理时间越长,最终表现为:
- 命令行长时间无输出,像"卡死"了一样;
- 请求超时或被后端直接拒绝;
- 复杂文档(扫描件、密集表格)处理到一半整个任务失败。
针对这个问题(issue #352),opendataloader-pdf 在核心处理流程中加入了分页机制,将待送检页面按固定批次拆分:
// Split backend pages into chunks to prevent hang on large documents (#352).
int chunkSize = effectiveChunkSize(sortedPages.size(), config.getHybridConfig().getChunkSize());
对应源码见 HybridDocumentProcessor.java。这个批次大小,就是你可以通过命令行控制的 --hybrid-chunk-size。
--hybrid-chunk-size 参数详解
根据官方参数定义(见 options.json),该参数的规则如下:
| 项目 | 说明 |
|---|---|
| 参数名 | --hybrid-chunk-size |
| 默认值 | 50(即每次最多送 50 页给后端) |
| 取值要求 | 正整数,空值或非法值会直接报错 |
| 作用 | 大文档按此页数拆分为多个批次,逐批请求后端 |
几个新手最容易踩的坑:
- 值太小 ≠ 越快。每个批次请求时都会重新上传整份 PDF,只是其中一部分页面被处理。批次越小,重复上传次数越多,总耗时反而可能变长。
- 值太大 = 退回挂起老路。超过默认 50 页的设定,相当于重新引入大文档挂起风险,官方文档中明确这一点属于"有意为之的自选行为"(见 docs/residual-review-findings/feat-configurable-hybrid-chunk-size.md)。
- 非法输入会被拒绝。传入空字符串或负数时,CLI 会直接抛出错误提示"requires a positive integer",不会静默使用默认值(解析逻辑见 CLIOptions.java)。
一条命令启用分块送检
假设你已安装 hybrid 依赖并启动了后端服务(完整流程见 hybrid-guide.md),处理一份 300 页的扫描报告,只需加一个参数:
opendataloader-pdf --hybrid docling-fast --hybrid-chunk-size 20 report.pdf -o output/
执行时的实际行为是:
- 300 页会被拆成 15 个批次(每批 20 页)依次送检;
- 每批处理完成后立即合并结果,中途某一批失败时,日志会标记"Backend chunk failed (pages X-Y)",其余批次继续处理,不会整单作废;
- 处理进度在日志中按批次打印,你可以清晰看到"卡在哪一批",而不是面对一整份文档干等。
如果你使用的是 Python API,对应参数名为 hybrid_chunk_size,同样会自动透传为 --hybrid-chunk-size,参见 convert_generated.py。
如何选择合适的 chunk size?
选值的口诀是:"宁小而稳,逐步放大"。
- 扫描件、复杂表格、公式密集文档:建议从 20 页甚至 10 页起步。这类页面单页处理慢,小批次能显著降低挂起概率,也能让失败定位更精确。
- 纯文本、排版简单的文档:保持默认 50 页即可,无需额外调参。
- 后端资源充足(有 GPU 或高配 CPU):可以适度上调,减少批次数量和重复上传开销,但建议不要大幅超过 50 页。
配合 --hybrid-timeout 设置合理的请求超时(毫秒),是第二道保险——超时后任务可以快速失败重试,而不是无限等待。
排查挂起时的检查清单
遇到"不动了",按顺序检查这 3 步:
- 确认后端真的在运行。backend 选项能被接受 ≠ 服务在响应,可以先跑项目自带的健康检查脚本 hybrid-health.sh,它会输出 reachable / stopped / error 状态。
- 观察日志的批次进度。开启分块后,日志会显示每批页码范围(如 pages 1-20、21-40),卡在哪个批次就说明该批次页面处理耗时异常。
- 检查文档语言是否设置。OCR 质量取决于你告诉引擎文档是什么语言,语言码写错或漏写不会报错,但文本会为空或乱码——排查方法详见 hybrid-guide.md 的 Troubleshooting 章节。
常见问题速答
Q:--hybrid-chunk-size 对本地模式有效吗?
无效。它只作用于 --hybrid 模式下的后端请求拆分,纯本地提取不涉及后端服务。
Q:批次之间会互相影响结果吗? 不会。每个批次的页面独立送检、独立合并,单批失败只影响该批页面(会被标记并走 Java 本地路径重试),其余批次正常输出。
Q:为什么我的 200 页文档没拆批? 因为 200 页在 auto 分诊模式下,只有被判定为"复杂页面"的页才会送后端,送检页不足 50 页时本身就只有一个批次,属正常现象。
总结
--hybrid-chunk-size是处理大型 PDF 时防止 hybrid 后端挂起的关键参数,默认每批 50 页;- 复杂文档建议调小(10~20 页),简单文档保持默认即可;
- 调参前先用健康检查脚本确认后端存活,再观察批次日志定位慢批次;
- 批次过小会因重复上传变慢,批次过大会退回挂起风险——"小而稳"是最安全的起点。
掌握这一个参数,你的大型 PDF 处理任务就能从"干等挂起"变成"分块可见、失败可定位"。
