# MinerU 4 模型资产

`mineru/model/registry.py` 定义仓库、必需文件和档位映射；`download.py` 负责显式下载、目录锁和完整性检查。
两个资源包常量为 `MINERU_4_MODELS_TORCH` 和 `MINERU_4_MODELS_ONNX`；
`small_model_repo()` 按小模型后端选择资源包，`vlm_model_repo()` 独立选择 VLM 权重。

| 小模型后端 | basic | standard |
|---|---|---|
| torch | MinerU-4_models_torch | Torch 资源包 + 所选 VLM 引擎的权重 |
| onnx | MinerU-4_models_onnx | ONNX 资源包 + 所选 VLM 引擎的权重 |

llama.cpp 选择 Q8_0 GGUF 和 mmproj；vLLM/lmdeploy/显式 MLX 选择原始 VLM 权重。
ARM Mac 默认 Torch MPS + llama；Linux/Windows 基础包默认 ONNX + llama，安装 full 且有加速器时默认 Torch + 平台引擎。
远程 VLM 不要求本地 VLM 权重。`full` 仅为安装 extra，不再是运行时后端名称。

新资源包使用各自的新缓存目录，不复用 PDF-Extract-Kit-1.0 或原来分散的 ONNX 仓库缓存。
当前只配置 Hugging Face 来源，ModelScope 镜像发布并核对文件后再添加来源地址。

## 下载与离线运行

```bash
export MINERU_MODEL_SMALL_BACKEND=onnx
export MINERU_MODEL_VLM_ENGINE=llama-cpp
export MINERU_MODEL_SOURCE=huggingface
mineru-kit models download --tier standard --small-backend onnx --vlm-engine llama-cpp --source huggingface
mineru-kit models verify --tier standard --small-backend onnx --vlm-engine llama-cpp

export MINERU_MODEL_SOURCE=local
mineru-kit parse input.pdf --tier basic -o output.md
```

`MINERU_MODEL_BASE_DIR` 可指定独立模型根目录。`--small-backend`、`--vlm-engine` 只覆盖当前模型管理命令；解析和服务运行时读取环境变量或配置文件。
Layout、OCR-det/rec、公式主批次和 UNet 通过 `model.onnx_device=auto/cpu/gpu` 共享 Windows DirectML／Linux WebGPU 设备选择。
环境变量为 `MINERU_MODEL_ONNX_DEVICE`。自动模式复用六图 rec 校准与输出检查；Linux 还执行 Intel 架构策略。
其他 ONNX 会话及规定的公式尾批次保持 CPU 路线，具体以日志中的实际 provider 为准。
CPU 算子线程读取 `MINERU_INTRA_OP_NUM_THREADS` 和 `MINERU_INTER_OP_NUM_THREADS`，默认 4/1。
llama.cpp 自动模式优先使用原生 ggml 实际可见的独显；没有可用独显时，Windows 复用 DirectML、Linux 复用 WebGPU 的 ONNX 设备决策，
包括已保存的 CPU/GPU 选择、输出一致性检查失败及架构回退。ONNX 决策涉及的 GPU 必须与 llama.cpp 的设备身份匹配，不能用另一张卡的成绩替集显决策。
因此 Linux 上 Xe-LP 及以前的 Intel 默认随现有 WebGPU 架构策略走 CPU；显式 `MINERU_LLAMA_CPP_BACKEND=vulkan`、GPU 层数或 server `--device` 仍可强制使用 GPU。

解析与 `mineru-kit vlm-server` 的 llama 入口共用设备策略。仅当 Linux Vulkan 实际选中明确 PCI 映射中的 Intel Xe-LP/更早架构，
或 Xe-LPG（`7dxx`、`b6xx`，包含 `8086:7d51`）时，自动启用 `GGML_VK_SERIALIZE_SUBMISSIONS=1`，
规避已复现的 i915 请求取消、设备丢失及异常视觉结果。该规则对 standard、advanced 等档位统一生效。
Xe-HPG、Xe2/Xe3 LPG 和其他后续架构、AMD、NVIDIA 及 Windows 不自动开启该开关。Xe-LPG 的 ONNX WebGPU 自适应校准策略不变。
多卡机器先确认原生设备，再隔离所选 GPU 并复核身份；不能仅因机器里存在 Intel 集显就给独显开启串行提交。
自动选择也不会混用需要串行提交的设备和其他设备；显式要求此类混合设备组会报错，因为 ggml 的环境开关无法逐卡设置。

已有的显式 `GGML_VK_SERIALIZE_SUBMISSIONS` 环境值保持不变：该开关检查变量是否存在，设为 `0` 同样会开启，撤销须 `unset`。
进程内初始化结束后会恢复临时环境；ggml 已缓存设备状态时，变更可见显卡或提交策略须使用新进程。
server 的 `--offline` 同样约束新增的 ONNX 校准模型读取，缺少本地模型时回退 CPU，不发起下载。
Torch、其他 VLM 引擎和远程 VLM 不使用这套 llama.cpp 设备策略。

## 资源结构

两个资源包均使用 `Layout/`、`OCR/paddleocr/`、`MFR/pp_formulanet_plus_m/`、`Table/`。

- Layout：PP-DocLayoutV2。ONNX 版读取官方 `inference.yml`，按调用方 batch 合并固定尺寸输入，并用逐页框数量拆分结果，保持页序。
- OCR：PP-OCRv6 Tiny Det + Small Rec。OCR TXT 字符表位于 `mineru/model/ocr/data/ppocrv6_dict.txt`，Torch/ONNX 共用。
- Seal：PP-OCRv4 mobile detector，使用多边形后处理、弯曲文字裁剪和共享 Small Rec。没有普通 OCR 替代 seal 的隐式降级。
- MFR：PP-FormulaNet plus-M，共用预处理、tokenizer 和公式修复；ONNX 自回归循环包含在图中；CPU 按原图面积排序，以最多 8 张一次合批推理，并恢复原顺序。
- Table：SlanetPlus、Unet 和 PP-LCNet 表格分类文件在两仓库中逐字节一致。

OCR YAML 保留上游配置，`MinerU` 字段另外记录普通 OCR 的实际阈值、宽度边界和字典位置。调用方传入的表格专用检测参数仍显式覆盖默认值。

## 可重复准备与验证

转换依赖只安装在开发环境，不属于 MinerU 的运行依赖：

```bash
uv pip install --python .venv1/bin/python 'onnx>=1.17,<2'
.venv1/bin/python -m scripts.prepare_onnx_models prepare --output-dir output/model-migration/models
.venv1/bin/python -m scripts.prepare_onnx_models verify \
  --repo-dir output/model-migration/models/MinerU-4_models_onnx
```

脚本使用固定源 revision；下载可利用 HF 缓存恢复。Seal 使用公开 `torch.onnx.export` API 导出 FP32、opset 17、动态 batch/高/宽概率图。
`manifest.json` 记录来源、哈希、大小、ONNX 签名、工具版本和导出验证。权重和验证产物保存在忽略的 `output/` 目录中。

组件验证示例：

```bash
.venv1/bin/python -m scripts.validate_onnx_models seal seal.png \
  --output-dir output/model-migration/validation/seal
.venv1/bin/python -m scripts.validate_onnx_models layout page1.png page2.png \
  --output-dir output/model-migration/validation/layout
.venv1/bin/python -m scripts.validate_onnx_models mfr formula1.png formula2.png \
  --output-dir output/model-migration/validation/mfr
```

使用独立 core 环境验证 light，而不是通过隐藏已安装的重依赖模拟：

```bash
uv venv output/model-migration/core-venv
uv pip install --python output/model-migration/core-venv/bin/python -e .
MINERU_INTRA_OP_NUM_THREADS=2 output/model-migration/core-venv/bin/python \
  -m scripts.validate_onnx_models parse input.pdf --small-backend onnx --tier basic \
  --rounds 2 --output-dir output/model-migration/validation/light-basic
```

验证报告分别保存初始化、首次/重复推理时间、进程峰值 RSS、结果包和叠图。公式逐项比较文本；版面检查页序、标签、几何和阅读顺序。

Seal 首先以 `rtol=1e-4, atol=1e-5` 比较概率图。若超限，报告保留失败标记并追加 Torch FP64 参考误差，
同时严格要求检测阈值掩码、多边形、裁剪图和最终文本一致；不会静默扩大概率图容差。完整验收结论应同时说明数值结果与语义结果。

发布按“本地验证 → HF 上传 → 新目录真实下载 → 本地来源解析”执行。ModelScope 镜像必须复制相同文件并核对哈希，不能指向旧模型仓库。

## Plus-M PTH 到 ONNX 对照实验

`scripts.export_formula_onnx` 从当前 Torch 资源包的 PTH 导出 CPU FP32 模型：
先导出编码器和单 token KV 缓存解码步骤，再用 ONNX Loop 组成独立的 image → token IDs 模型。
导出保留动态 batch、动态序列长度、EOS/PAD 和当前 Torch 路径的强制 EOS 行为。
导出中间产物写到独立目录；正式资源包采用这份经过验证的 PTH 导出模型。

```bash
.venv1/bin/python -m scripts.export_formula_onnx \
  --weights-dir output/model-migration/models/MinerU-4_models_torch/MFR/pp_formulanet_plus_m \
  --output-dir output/formula-onnx-comparison

.venv1/bin/python -m scripts.compare_formula_onnx \
  --reference output/model-migration/models/MinerU-4_models_onnx/MFR/pp_formulanet_plus_m/PP-FormulaNet_plus-M.onnx \
  --candidate output/formula-onnx-comparison/PP-FormulaNet_plus-M.from_torch.onnx \
  --config output/model-migration/models/MinerU-4_models_onnx/MFR/pp_formulanet_plus_m/PP-FormulaNet_plus-M_inference.yml \
  --weights-dir output/model-migration/models/MinerU-4_models_torch/MFR/pp_formulanet_plus_m \
  --inputs-json output/model-migration/formula-inputs.json \
  --output-dir output/formula-onnx-comparison
```

`--inputs-json` 接收公式图像路径的 JSON 数组。报告分别记录完整 token、LaTeX、原始权重按值匹配、
图节点/算子统计、编码器特征与前 16 步 logits 的三方数值对照，以及 batch=2 与逐项推理的结果。
权重匹配递归访问控制流子图，并考虑 Paddle/Torch Linear 权重的转置；未匹配项不能直接解释为权重不同。

`scripts.check_formula_generation_limit` 使用同样的 `--reference`、`--candidate` 和 `--output-dir` 参数，
在诊断副本中固定 argmax 为非 EOS token，保留原图的序列更新和停止逻辑，验证超长序列边界。
当前 Torch 的 `ForcedEOSTokenLogitsProcessor(max_length=1537)` 会在第 1536 个生成 token 强制 EOS；
现用 Paddle 来源 ONNX 没有这一强制步骤，最多生成 2560 个 token。
因此短公式结果一致不足以证明两个导出版本在超长公式上等价。

`scripts.benchmark_formula_onnx` 用 `--images-dir` 指定含 `manifest.json` 的公式样本目录，
用 `--reference`、`--candidate`、`--config`、`--output-dir` 指定两个模型、字典配置及输出目录。
它将原始 36 张和 demo1/demo2 的 117 张分开，按原图像素面积升序排列，测试真实 batch=1/2/4/8/16。
每个配置在独立 CPU ORT 进程中预热后测两轮，固定 intra-op=2、inter-op=1；配置间交替模型先后次序。
计时只包含 `session.run`，原始数据同时保存逐批耗时、EOS 截断后的 token、LaTeX 和进程峰值 RSS。
生产公式 CPU 封装采用 batch=8 上限；调用方请求更小批次时仍遵守其上限。

## 其他 ONNX 模型的 batch 现状

- Layout 图和封装均支持真 batch；通过逐页框数量拆分合并输出，再独立执行过滤与阅读顺序处理。
- OCR det 按预处理后完全相同的尺寸分桶，桶满或处理尾批时一次调用 ORT；不补边，结果恢复原输入顺序。
- OCR rec 图和封装都支持真实批量，默认 batch=6，按宽高比排序并将同批文本行补齐到共同宽度。

模型文件更新不会自动替换已标记完成的本地缓存。已有缓存需要更新对应权重，或使用新的模型目录下载。

Layout 与 OCR det 保留现有批次参数，PDF 主流程当前上限分别为 2 和 16；OCR det 尺寸不匹配时自然形成不同的桶，实际批次可小于上限。
单图检测共用批处理路径；无效批次上限、Layout 数量数组异常或检测输出 batch 不匹配时明确报错。

真批处理验证：

```bash
MINERU_INTRA_OP_NUM_THREADS=2 MINERU_INTER_OP_NUM_THREADS=1 .venv1/bin/python \
  -m scripts.validate_detection_batching components --output-dir output/detection-batching/components
MINERU_INTRA_OP_NUM_THREADS=2 MINERU_INTER_OP_NUM_THREADS=1 .venv1/bin/python \
  -m scripts.validate_detection_batching parse demo/pdfs/demo1.pdf demo/pdfs/demo2.pdf \
  --output-dir output/detection-batching/parse
```

验证脚本记录实际 ORT 输入形状，比较逐图/合批结果，并输出检测叠图、真实解析结果、耗时及进程峰值 RSS。