为什么MinerU-4_models_onnx要求onnxruntime≥1.20.1:ONNX IR 10兼容性问题深度解析

原创2026-10-19 23:25:191,702 阅读

为什么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 加载模型时有一道"快速失败"检查:

  1. 读取模型文件的 ir_version;
  2. 与自身内置 ONNX 库支持的最大 IR 版本比较;
  3. 若模型更新,直接拒绝加载并报错——这是刻意的设计,宁可报错也不拿旧解析器硬读新格式。

而 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 版本与运行时匹配 ✅

遇到"加载模型失败"类报错时,按此顺序排查:

  1. 查模型 IR 版本(需 onnx 包):

    python -c "import onnx; print(onnx.load('OCR/paddleocr/ch_PP-OCRv6_tiny_det_infer.onnx').ir_version)"
    
  2. 查运行时版本:python -c "import onnxruntime as ort; print(ort.__version__)";

  3. 对照升级: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" 一步到位。

登录后查看全文
MinerU-4_models_onnx