Xiaomi-OCR-0 评测流水线实战：两阶段推理与 OmniDocBench 复现全指南

Xiaomi-OCR-0 评测流水线帮助你将文档图片批量转成 Markdown，并用 OmniDocBench v1.6 标准指标打分。本文带你从零走通两条推理路线——端到端（e2e）与两阶段（two-stage）推理，完整复现论文级别的评测结果。

两条推理路线：怎么选？

Xiaomi-OCR-0 是一个 0.8B 参数的视觉语言模型，专攻文档解析。它支持两种把图片变成 Markdown 的方式：

核心代码位于 evaluation_pipeline/ 目录，两条路线的详细文档见 evaluation_pipeline/README_zh.md。

新手建议：先用 e2e 跑通全流程（简单），再用两阶段冲高分。

前置准备：环境安装与输入数据格式

需要准备两个环境（可分开装）：

1. vLLM 推理环境：GPU 环境 + requirements.txt，用于跑模型推理；
2. PaddlePaddle + PaddleX：仅两阶段需要，安装 requirements-paddlex.txt；
3. 评测环境：官方提供的 Docker 镜像（无需本地安装 TeX Live、ImageMagick 等依赖）。

完整安装步骤见 INSTALL.md。克隆仓库：

git clone https://gitcode.com/gh_mirrors/xi/Xiaomi-OCR-0 cd Xiaomi-OCR-0

输入数据格式

推理输入是 JSONL 文件，每行一张页面图片的绝对路径：

{"images": ["/absolute/path/to/page.png"]}

两个关键细节：

• 输出按<图片文件名>.md命名，文件名必须唯一，且与评测标注中的页面名称一致；
• 两阶段推理时，layout JSONL 与输入 JSONL 里的图片路径字符串必须完全一致，脚本靠它关联检测结果。

端到端推理：一条命令输出整页 Markdown

使用 evaluation_pipeline/e2e_img2md.py，脚本会自动启动/停止 vLLM 服务：

python -m evaluation_pipeline.e2e_img2md \ --input-jsonl "$INPUT_JSONL" \ --output_dir "$OUTPUT_DIR/e2e" \ --model_path SeerRay-Lab/Xiaomi-OCR-0 \ --task document --gpu_devices 0,1,2,3 \ --start_server --stop_server

推理超参数建议保持论文设置：temperature=0.0、top_p=0.8、max_tokens=16384、presence_penalty=0.0，并开启--retry-repetitive（对重复输出自动重试）。

后处理会把模型输出的OTSL 表格转成 HTML 表格，公式保留 LaTeX 格式，最终产出逐页.md文件。公共后处理逻辑见 postprocess/README.md。

两阶段推理教程：版面检测 + 区域识别

两阶段把"看整页"拆成"先找区域、再认内容"，官方复现结果比 e2e 高出约 1~2 分。

第一步：用 PaddleX 生成版面检测结果

运行 evaluation_pipeline/layout_detect_paddlex.py，使用PaddleX 版 PP-DocLayoutV3，阈值 0.25：

python -m evaluation_pipeline.layout_detect_paddlex \ --input_jsonl "$INPUT_JSONL" \ --output_jsonl "$OUTPUT_DIR/layout_paddlex-th0.25.jsonl" \ --gpu_ids 0 --batch_size 8 --threshold 0.25

首次运行 PaddleX 会自动下载 PP-DocLayoutV3 权重；也可用--model_dir指定本地 PaddleX 格式权重。

版面检测结果包含 25 类区域标签（text、table、display_formula 等），脚本按标签分发任务：文本走"提取文字"、表格走 OTSL 提示、公式走 LaTeX 提示，图像类区域则跳过。

第二步：区域识别并组装页面

在 vLLM 环境运行 evaluation_pipeline/twostage_img2md.py，把上一步的 layout 文件传入：

python -m evaluation_pipeline.twostage_img2md \ --input-jsonl "$INPUT_JSONL" \ --layout-jsonl "$LAYOUT_JSONL" \ --output_dir "$OUTPUT_DIR/stage2" \ --model_path SeerRay-Lab/Xiaomi-OCR-0 \ --vlm_gpus 0,1,2,3 --start_server --stop_server

页面组装时按阅读顺序排序、过滤页眉页脚、合并公式编号、拼接文本块，表格同样由 OTSL 转 HTML。

用 OmniDocBench 评测：指标说明与 Docker 运行

评测复用 OmniDocBench v1.6 的pdf_validation.py，配置直接使用仓库公开的 evaluation_pipeline/configs/end2end.yaml：

关键配置：匹配方式quick_match，matching/CDM/TEDS 的 worker 数均为 16，超时时间 1200 秒。复现时请保留这些设置。

评测在 Docker 镜像中完成，一条命令即可（GT为标注 JSON，PRED_DIR为 Markdown 输出目录）：

docker run --rm --entrypoint bash \ -v "$PWD/evaluation_pipeline/configs/end2end.yaml:/repro/end2end.yaml:ro" \ -v "$GT:/repro/gt.json:ro" \ -v "$PRED_DIR:/repro/predictions:ro" \ -v "$RESULT_DIR:/workspace/result" \ ghcr.io/zeng-weijun/omnidocbench-eval:repro-ubuntu2204 \ -c 'python pdf_validation.py --config /tmp/xiaomi-ocr-eval.yaml'

复现结果参考：三大数据集成绩

以下是官方公布的两条路线复现成绩（两阶段使用 PaddleX 版 PP-DocLayoutV3，阈值 0.25）：

OmniDocBench v1.6

Real5-OmniDocBench（真实拍摄场景）

可以看到：两阶段在公式（CDM）和表格（TEDS）上优势最明显，这正来自区域识别时"表格用表格提示、公式用公式提示"的任务分发策略。

复现避坑：4 个高频问题

• 阈值必须独立重跑：PaddleX 原生后处理使高阈值结果不一定是低阈值结果的子集，不能离线过滤替代重新生成，比较不同阈值请用各自独立的 layout 文件。
• 别混用 layout 来源：若改用--layout_model_dir（HF Transformers 加载），默认阈值变为 0.3，与 0.25 的 PaddleX 结果不可直接对比；复现请始终传 PaddleX 生成的--layout-jsonl。
• 路径字符串必须逐字一致：输入 JSONL 与 layout JSONL 的图片路径有任何差异（相对/绝对、空格），检测结果就对不上。
• worker 数别拉满：配置注释明确建议每阶段保持约 1/3~1/2 空闲 CPU，设满可能死锁。

总结

跑通 Xiaomi-OCR-0 评测流水线的完整路径是：准备 JSONL 输入 → e2e 或两阶段推理生成逐页 Markdown → Docker 内 OmniDocBench 打分。全程脚本化、可复现，配置文件已随仓库公开。

核心资料索引：

• 评测总文档：evaluation_pipeline/README_zh.md
• 推理脚本：e2e_img2md.py · twostage_img2md.py · layout_detect_paddlex.py
• 评测配置：configs/end2end.yaml
• 公共后处理：postprocess/