OpenBMB/MiniCPM-OCR · 上手攻略

  • 仓库：OpenBMB/MiniCPM-OCR
  • 链接：https://github.com/OpenBMB/MiniCPM-OCR
  • 分类：engineering（主分类：engineering，副分类：trending）
  • 作者：Jay
  • 更新：2026-10-30

资料来源：GitHub README、docs/minicpm_ocr_tutorial_en.md、docs/SKILL_en.md、docs/minicpm_ocr_jev_tutorial_en.md（均于 2026-10-30 抓取）。版本号取自 SKILL 文件里的 pin 值，README 未标注统一 release 版本号。

是什么

MiniCPM-OCR 是 OpenBMB（面壁智能）开源的 OCR 专用模型族，包含两个互补的模型：

  • MiniCPM-OCR 1.0（1.3B）：MiniCPM-V/o 家族里第一个专门做 OCR 的模型，偏"文本中心的文档理解"，覆盖正文、表格、公式、图表、印章与结构化信息抽取（KIE）。输入中英文文档与 PDF，输出 Markdown。
  • MiniCPM-OCR Jev（2B）：不是再做一遍 OCR，而是 "这份 OCR 结果对不对"的判决模型。给它原图 + 候选文本，返回 0~1 的一致性分数，用来筛出可靠结果、标记需要人工复核的区域。

技术上最值得注意的一点是 DSpark 解码加速：主模型配一个同 release 的 draft 模型做投机解码，官方称端到端处理效率提升 55%，吞吐约为 PaddleOCR-VL-1.6 的 1.49×、MinerU2.5 Pro 的 3.62×。开源 OCR 模型对比中，MiniCPM-OCR 1.0 为 1.2 页/秒。

另有两个容易被忽略的工程设计：

  1. SDK 与推理服务分离。SDK（PyPI 包 minicpm-ocr，命令 minicpmvocr）负责版面检测（PP-DocLayoutV3，PaddlePaddle）、裁切与结果组装；推理服务单独跑识别模型，通过 HTTP 通信。两套 Python 环境、两个终端。
  2. Jev 把"渲染"放进评分链路。它不是让模型纯读文本，而是先把候选文本渲染成图，再把「原图 + 渲染图 + 文本」一起送进模型，所以模型能"看见"版式。链路是 precheck（LaTeX 语法校验）→ render → forward。

许可：代码、文档、模型权重全部 Apache 2.0。

解决什么问题

  1. 真实世界文档的解析质量：扫描件、翻拍照片、弯曲书页、倾斜页面、重拍文档——这些是 OCR 最容易崩的场景。官方在 Real5-OmniDocBench 上报 93.68 的 SOTA 分，OCRBench v2 上 54.7。
  2. 多引擎可替换：vLLM、SGLang、llama.cpp、Ollama 开箱支持，Apple Silicon / CPU 也能跑（llama.cpp Metal 路线不需要 CUDA）。
  3. 大规模解析的成本：DSpark 加速 + 量化版本（AWQ / GPTQ / GGUF / DSpark-GGUF）让吞吐和显存都可控。
  4. OCR 结果的"复核成本"：Jev 专门解决"模型不知道自己错了"的问题——给出 AUROC（×100）93.6（2B），超过 JEV-35B-A3B 的 90.1，逼近 Qwen3.5-397B-A17B 的 93.8。
  5. 跨 OCR 模型的排序：同一张图跑多个 OCR 模型，用 Jev 打分排序挑最好的那份。

快速安装

推荐路线是 Linux x86_64 + NVIDIA GPU（官方在 RTX 5090 32GB 上验证）。硬件门槛：驱动 ≥580（CUDA 13），Python 3.12（uv 自动下载），磁盘至少留 40GB（GPU SDK 环境约 9GB，vLLM 环境 8GB，vLLM 源码与构建产物 6GB，模型 3GB，其余为下载与构建缓存）。

git clone https://github.com/OpenBMB/MiniCPM-OCR.git
cd MiniCPM-OCR

# 1) SDK 环境（独立 venv）
pip install uv
uv venv .minicpm-ocr --python 3.12 --seed
source .minicpm-ocr/bin/activate
python -m pip install --upgrade "minicpm-ocr[all]"
python -m pip install "paddlepaddle-gpu==3.3.0" \
  -i https://www.paddlepaddle.org.cn/packages/stable/cu129/

# 2) 推理环境（vLLM）
apt-get update && apt-get install -y software-properties-common
add-apt-repository -y ppa:ubuntu-toolchain-r/test
apt-get install -y gcc-13 g++-13 libdw-dev libelf-dev
bash scripts/install.sh vllm     # 默认 MAX_JOBS=8；96 核机器全量安装约 40 分钟

想省事就用 Ollama 路线（不需要 CUDA toolkit、不需要 Python 推理环境、不编译源码），llama.cpp 路线适合 Apple Silicon 与纯 CPU。

核心用法

启动 vLLM 推理服务（新终端，仓库根目录）：

source .venv-vllm/bin/activate
export CC=gcc-13 CXX=g++-13
export CUDA_HOME="$(python -c 'import sysconfig; print(sysconfig.get_path("purelib") + "/nvidia/cu13")')"
export PATH="$CUDA_HOME/bin:$PATH"

vllm serve openbmb/MiniCPM-OCR-1.0 \
  --served-model-name minicpm-ocr --host 127.0.0.1 --port 18499 \
  --max-model-len 40960 --max-num-batched-tokens 40960 --max-num-seqs 32 \
  --limit-mm-per-prompt '{"image":36,"video":0}' \
  --attention-backend FLASH_ATTN --mm-encoder-attn-backend FLASH_ATTN \
  --mm-processor-kwargs '{"downsample_mode":"4x"}' \
  --gpu-memory-utilization 0.85 --trust-request-mm-kwargs \
  --speculative-config '{
    "method": "dspark",
    "model": "openbmb/MiniCPM-OCR-1.0-DSpark",
    "num_speculative_tokens": 15,
    "enable_adaptive_verification": false
  }' \
  --default-chat-template-kwargs '{"enable_thinking":false}'

删掉整个 --speculative-config 就是普通解码（不需要 draft 模型）。

解析文档（SDK 终端）：

source .minicpm-ocr/bin/activate
minicpmvocr parse \
  --device cuda:0 \
  --server-url http://127.0.0.1:18499 \
  --model minicpm-ocr \
  --input doc.pdf \
  --output doc.md

SDK 会检查 models/PP-DocLayoutV3_infer/，文件不全时从 Paddle 官方地址自动下载版面模型。输出 Markdown：正文为文本、表格为 HTML、公式为 LaTeX，并保留阅读顺序。

Jev 部署与打分。Docker 路线最省事，镜像里钉死了 Chromium 与 CJK 字体，渲染结果与云 API 一致，分数可与公开数字直接对比：

cd scripts/minicpm-ocr-jev
docker build -f serve/Dockerfile -t minicpm-ocr-jev-1-0:latest .
docker run -d --name minicpm-ocr-jev --gpus '"device=0"' \
    -p 127.0.0.1:8030:8030 \
    -v /path/to/checkpoint:/weights:ro \
    minicpm-ocr-jev-1-0:latest 8030 /weights

curl -f http://127.0.0.1:8030/healthz

打一次分：

curl -s http://127.0.0.1:8030/v1/rm/score -H 'Content-Type: application/json' -d '{
  "input_form": "ternary",
  "items": [
    {"case_id": "blk-001", "image": "<base64>",
     "ocr_text": "the OCR text to be scored", "category": "text"}
  ]
}'

返回里有 prob_yes / prob_no / verdict / summary（含 total、scored、pass_rate、throughput_rate）。另有 /v1/rm/score_best 与 /v1/rm/score_best_batch 用于块内 best-of-N。硬件要求：NVIDIA ≥12GB 显存、驱动 ≥535；磁盘约 5–9GB（推理环境）+ 1.5GB（渲染环境）+ 2.5GB（权重）。

最省事的入口：官方提供 SKILL 文件，让编码 Agent 自己去装环境、下模型、跑通第一篇文档：

Read and execute https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/SKILL_en.md

Jev 有对应的 SKILL_jev_en.md。已 clone 仓库的话直接用 ./docs/SKILL_en.md。

典型适用场景

  • 批量合同/发票/研报转 Markdown：中文为主、扫描件与照片混杂，用 Real5-OmniDocBench 上的解析质量兜底。
  • "解析 + 质检"两段式流水线：1.0 跑全量出 Markdown，Jev 打分，只把低分区域送人工复核——Jev 的"review-free rate"曲线就是为这个设计的。
  • 多模型择优：同一个 PDF 分别交给 MiniCPM-OCR、GLM-OCR、PaddleOCR-VL-1.6、Xiaomi-OCR-0，用 Jev 打分排序。官方称跨这些解析结果时 Jev 的 AUROC（×100）落在 91.9~93.4 区间。
  • 端侧 / 私有化：llama.cpp Metal 路线在 Mac 上跑；Ollama 路线不需编译；按教程本地部署时原始文档与解析结果都留在本机，不需要上传云端。

坑与注意

  1. 现象：Jev 返回 0.0 或 -1.0。影响：你会以为"置信度极低"，其实它是评分失败的固定占位值。修复：永远先读同一 item 的 verdict 字段拿失败原因；0.0/-1.0 不是概率。
  2. 现象：category 传错（把公式块当 text）。影响：公式会被按字面 LaTeX 渲染，分数被扭曲，而且不会报任何错。修复：category 必须匹配块的真实类型（text / formula / table）。
  3. 现象：自建渲染器和官方 Docker 镜像分数对不上。影响：绝对值漂移。修复：同一段文本在不同 Chromium 版本与字体依赖下渲染结果本就不同；Docker 镜像钉死了版本所以与云 API 可直接对比，SDK 部署下渲染器取决于你自己的环境——排序稳定，绝对值会漂，官方也不承诺第三位小数。
  4. 现象：阈值设完发现大量漏检。影响：复核率失控。修复：官方明确要求"先在真实应用的一小批样本上验证阈值"，参考 review-free 曲线，而不是直接套用论文数字。
  5. 现象：vLLM 启动后 SDK 请求一直挂着。影响：以为服务挂了。修复：先 curl --noproxy 127.0.0.1 -fsS http://127.0.0.1:18499/v1/models 确认服务在，再检查 --server-url，并保留 vLLM 启动命令里的 --trust-request-mm-kwargs。
  6. 现象：编译 vLLM 时进程被 OOM kill。影响：安装中断。修复：调低 MAX_JOBS（默认 8，内存充足可 MAX_JOBS=32）并确认内存足够。
  7. 现象：驱动低于 580 起不来。影响：CUDA 13 不兼容。修复：按 FAQ 配置 CUDA 兼容库，并在每一个终端（安装、server、GPU SDK）都设好环境变量；驱动版本不够不意味着所有后端都不行（llama.cpp / Ollama / SGLang 路线各有要求，别一刀切放弃）。
  8. 现象：显存不够（OOM）。影响：服务起不来。修复：降低 --max-model-len（示例 40960），必要时再降 --gpu-memory-utilization；llama.cpp 侧把 --n-gpu-layers 与 --gpu-layers-draft 设为 0（CPU 推理）并加 --no-mmproj-offload。
  9. 现象：SGLang / llama.cpp 装的版本对不上。影响：报 minicpm_ocr architecture 不支持，或 prompt mismatch。修复：仓库用的是打过适配补丁的固定 commit，不是 pip install sglang 或上游主线——SKILL 文件里 pin 了 vLLM fa3b9d1…、Transformers 144ecf0…、SGLang aaab6bf…、llama.cpp a08ab75…（含 draft-dspark 的合并 PR #30979）；版本不匹配时按脚本提示重装，不要 reset 本地工作区。
  10. 现象：DSpark 加速配了但没生效或报错。影响：吞吐回到普通解码。修复：主模型和 draft 模型必须来自同一 release；vLLM 用 --speculative-config JSON，SGLang 用 --speculative-algorithm DSPARK + --speculative-draft-model-path，llama.cpp 用 --model-draft + --spec-type draft-dspark + --spec-draft-n-max 15——三套参数不能混抄。llama.cpp 侧还要保持 --reasoning off，官方 PR 说明默认 auto 可能出问题。
  11. 现象：源码准备阶段失败。影响：安装中断。修复：按脚本提示检查 GitHub 访问或 sources/ 下已有 revision，然后重跑 bash scripts/install.sh vllm；版本不符时保留本地改动再解决冲突。
  12. 现象：以为装完 SDK 就能解析。影响：命令跑不通。修复：SDK 只做版面检测与结果组装，必须有配套的识别推理服务（vLLM / SGLang / llama.cpp / Ollama 任一）才能出结果；Meta 路线下 llama.cpp Metal 服务能跑不代表整个 SDK 链路通（还要能跑 PP-DocLayoutV3 的 PaddlePaddle 轮子）。

与同类对比

  • PaddleOCR-VL：生态成熟、部署面广，官方给出的吞吐对比是 MiniCPM-OCR 约为其 1.49×；MiniCPM-OCR 在解析质量基准上更强并自带 Jev 质检这一层。
  • MinerU2.5 Pro：以文档抽取流水线见长，官方对比称 MiniCPM-OCR 吞吐约 3.62×；但 MinerU 是完整工具链，MiniCPM-OCR 更像"模型 + SDK"的组合。
  • GLM-OCR / Xiaomi-OCR-0：Jev 的评测里它们被当作被评对象（跨模型解析结果上 AUROC 91.9~93.4），说明 Jev 本身就是为"多模型混用"设计的裁判。
  • 云 OCR API（Google / Azure / 百度等）：省事但文档要出境、单价随量涨；MiniCPM-OCR 的价值在于本地化、可量化、可微调（提供 LLaMA-Factory 与 Swift 微调教程）。
  • 传统 OCR（Tesseract / PaddleOCR）：纯字符识别管线，没有版式理解与结构化输出；MiniCPM-OCR 输出的是带阅读顺序的 Markdown，定位是"文档理解"而非"字符识别"。

一句话推荐结论

如果你的主力场景是中文为主的扫描件/照片/PDF 结构化转 Markdown，且在意数据不出本地、又要兼顾吞吐，MiniCPM-OCR 1.0 值得优先试——尤其是再叠一个 Jev 做低置信度区域兜底，是目前开源 OCR 里少见的"质量 + 效率 + 可自检"三件齐的组合；但它对部署环境不友好（Linux + NVIDIA + 40GB 磁盘 + 源码编译 vLLM），只想点个 API 的话官方托管的 modelbest API 更划算。

⚠️ 待核项：本文未复现任何基准分数，93.68 / 54.7 / 93.6 / 1.2 页每秒 等数字均为 README 自述（对应 Real5-OmniDocBench、OCRBench v2、JevOCRBench），未做第三方交叉验证；仓库未标注统一 release 版本号，SKILL 文件中 pin 的 commit 随仓库变动可能过期；"1.49×/3.62×/55%"的对比基准机配置未在 README 中完整披露。