为什么MinerU-4_models_onnx要求onnxruntime≥1.20.1:ONNX IR 10兼容性问题深度解析
为什么MinerU-4_models_onnx要求onnxruntime≥1.20.1:ONNX IR 10兼容性问题深度解析
MinerU-4_models_onnx 是 MinerU 文档解析轻量栈的 CPU 版 ONNX 推理模型库,官方明确要求 onnxruntime ≥ 1.20.1——根本原因在于仓库中有 2 个模型使用了 ONNX IR 10 格式,旧版运行时无法加载。本文带你从零基础看懂这个"版本墙",并给出最快的解决方法。
一、先认识 MinerU-4_models_onnx:8 个 CPU ONNX 模型全家桶 📦
这个仓库为 MinerU 4.0 轻量解析栈提供了一整套 CPU ONNX Runtime(CPUExecutionProvider)推理模型,无需 GPU,覆盖文档智能解析的每个关键环节:
| 功能 | 模型文件 | 大小 |
|---|---|---|
| 版面分析 | Layout/PP-DocLayoutV2/inference.onnx | ~204 MB |
| 公式识别(LaTeX) | MFR/pp_formulanet_plus_m/PP-FormulaNet_plus-M.onnx | ~564 MB |
| 文字识别 | OCR/paddleocr/ch_PP-OCRv6_small_rec_infer.onnx | ~20 MB |
| 文字行检测 | OCR/paddleocr/ch_PP-OCRv6_tiny_det_infer.onnx | ~1.7 MB |
| 印章检测 | OCR/paddleocr/seal_PP-OCRv4_det_infer.onnx | ~4.5 MB |
| 表格方向分类 | Table/PP-LCNet_x1_0_table_cls.onnx | ~6.5 MB |
| 表格结构识别 | Table/slanet-plus.onnx | ~7.4 MB |
| 表格单元格分割 | Table/unet.onnx | ~8 MB |
每个模型都附带推理配置(如 ch_PP-OCRv6_tiny_det_inference.yml),其中已内嵌 MinerU 的运行时参数(如检测阈值、边长限制),下载即可直接使用。
二、ONNX IR 版本是什么?.onnx 文件里藏着的"版本号" 🔍
要理解版本要求,先分清 ONNX 里的两个"版本号":
- IR 版本(ir_version):模型文件"容器格式"的版本。
.onnx本质是一个 protobuf 文件,导出时会在文件头写入当时 ONNX 规范定义的 IR 版本号; - opset(算子集版本):如
ai.onnx: 14、ai.onnx: 17,决定模型使用了哪一代算子定义。
opset 管"词汇表",IR 版本管"文件格式",两者互不替代。manifest.json 中为每个模型都记录了这两项,一眼就能看出差异:
| 模型 | IR 版本 | opset |
|---|---|---|
| ch_PP-OCRv6_tiny_det_infer.onnx | 10 ⚠️ | 14 |
| PP-LCNet_x1_0_table_cls.onnx | 10 ⚠️ | 9 |
| PP-DocLayoutV2 / PP-FormulaNet / seal_PP-OCRv4_det | 8 | 17 |
| slanet-plus.onnx | 7 | 14 |
| ch_PP-OCRv6_small_rec / unet.onnx | 6 | 11 |
可以看到:仓库里最高 IR 版本是 10,其余模型都更低。
三、为什么 onnxruntime 低于 1.20.1 会直接"拒载" ⚠️
onnxruntime 加载模型时有一道"快速失败"检查:
- 读取模型文件的
ir_version; - 与自身内置 ONNX 库支持的最大 IR 版本比较;
- 若模型更新,直接拒绝加载并报错——这是刻意的设计,宁可报错也不拿旧解析器硬读新格式。
而 onnxruntime 支持的最大 IR 版本,取决于其编译时捆绑的 ONNX 库。仓库 README.md 给出了明确结论:
CPU ONNX Runtime models for MinerU's light stack. Requires onnxruntime >= 1.20.1 (ONNX IR 10 support).
也就是说,onnxruntime 1.20.1 正是首个支持 ONNX IR 10 的最低版本。用 1.20.1 之前的运行时打开两个 IR 10 模型,典型报错形如(不同版本措辞略有差异):
[ONNXRuntimeError] : 1 : FAIL : Load model from
ch_PP-OCRv6_tiny_det_infer.onnx failed: This model uses ONNX IR
version 10, but the current onnxruntime only supports up to
IR version 9.
抓住关键信息即可:模型要求 IR 10,运行时最高只支持 9——版本差一代,文件被拒。
四、问题定位:只有两个"IR 10"模型在拖后腿
结合 manifest.json 中的 "minimum_onnxruntime": "1.20.1" 与各模型的 IR 版本记录(如 manifest.json、manifest.json),责任链非常清晰:
- ch_PP-OCRv6_tiny_det_infer.onnx(OCR 文字行检测,记录位置):来自 PaddlePaddle 官方 ONNX 发布(PP-OCRv6_tiny_det_onnx),由较新版本 ONNX 工具导出,天然带 IR 10;
- PP-LCNet_x1_0_table_cls.onnx(表格方向分类,记录位置):同为新版工具导出,IR 10。
其余 6 个模型是 IR 6/7/8,旧版 onnxruntime 也能加载。整个仓库的最低运行时版本,由这 2 个"最高 IR"的模型决定——这就是 1.20.1 这个下限的由来。
💡 补充:公式模型 PP-FormulaNet plus-M 虽为 IR 8,但内部包含自回归 Loop、动态 batch(CPU 端批处理上限 8),属于较复杂的图,对新运行时的稳定性也有隐性要求(详见 README.md 的 2026-09-11 更新说明)。
五、最快解决步骤:一键升级 onnxruntime ⚡
升级是官方推荐的唯一解法,两条命令搞定:
pip install "onnxruntime>=1.20.1"
python -c "import onnxruntime as ort; print(ort.__version__)"
确认版本号 ≥ 1.20.1 即可。若使用 MinerU 完整流程,可按 README.md 的指引准备全部模型资产:
python -m scripts.prepare_onnx_models prepare
manifest.json 还为每个模型记录了 SHA-256 校验和,怀疑文件损坏时可直接比对。
六、3 步自检:确认 IR 版本与运行时匹配 ✅
遇到"加载模型失败"类报错时,按此顺序排查:
-
查模型 IR 版本(需
onnx包):python -c "import onnx; print(onnx.load('OCR/paddleocr/ch_PP-OCRv6_tiny_det_infer.onnx').ir_version)" -
查运行时版本:
python -c "import onnxruntime as ort; print(ort.__version__)"; -
对照升级:IR 10 → 至少 onnxruntime 1.20.1(本仓库其余模型 IR ≤ 8,无更高要求)。
七、常见误区避坑指南 ❌
- "把模型重新导出成低 IR 版本"不可取:官方发布文件按原样使用,重新导出会改变字节与 SHA-256,与 manifest.json 中的校验记录不符;
- opset 低 ≠ IR 低:
PP-LCNet_x1_0_table_cls.onnx的 opset 只有 9,但 IR 仍是 10,照样需要新版运行时; - 只报一个模型的错,却以为只它坏了:推理管线是整体加载的,任一模型被拒,整条管线都无法启动;
- 升级后仍失败? 优先核对文件 SHA-256 是否与 manifest 一致,并确认安装的是 CPU 版
onnxruntime(本仓库面向 CPU 推理)。
八、总结
MinerU-4_models_onnx 要求 onnxruntime ≥ 1.20.1,本质是"格式版本"问题:仓库中的 OCR 文字检测器与表格分类器两个模型使用了 ONNX IR 10,而 1.20.1 之前的运行时最高只支持 IR 9,加载时被快速失败机制直接拒绝。记住一句话即可:看 IR 版本定运行时下限,升级 pip install "onnxruntime>=1.20.1" 一步到位。