没有GPU也能跑:MonkeyOCRv2-Parsing纯CPU推理部署完整指南
没有GPU也能跑:MonkeyOCRv2-Parsing纯CPU推理部署完整指南
还在为文档解析离不开显卡而发愁吗?MonkeyOCRv2 是面向文档智能(Document AI)的开源视觉-文本基础模型,其文档解析模块 MonkeyOCRv2-Parsing 现已官方支持纯 CPU 推理:无需 GPU、无需 CUDA、无需 vLLM 服务,在 Windows 或 Linux 普通电脑上即可完成多语言文档解析,输出 Markdown、JSON 与版面可视化结果。本文将带你从环境配置到命令运行,一步步完成 MonkeyOCRv2 的 CPU 部署。
为什么选择 MonkeyOCRv2 纯CPU部署?
MonkeyOCRv2-Parsing 将扫描件、拍照件、PDF 中的文字、表格、公式、版面结构解析为结构化 Markdown,支持 17 种语言,并在 MDPBench 官方榜单上位列开源模型第一(B 版综合得分 83.3)。对于以下场景,纯 CPU 方案几乎是零门槛的选择:
- 💻 只有办公本、树莓派级服务器,或公司内网不允许装显卡驱动;
- 🔧 需要长期低成本挂机跑文档批处理(电费远小于 GPU 服务器);
- 📦 快速验证模型效果,再决定是否迁移到 GPU 加速。
💡 性能预期:CPU 推理速度明显慢于 GPU(逐页解析,适合批量夜间任务),但对单页文档通常也只需几秒到几十秒。内存建议 8GB 以上;资源紧张时可选更小的
MonkeyOCRv2-S-Parsing。
快速上手:纯CPU推理四步走
整体流程只有四步:克隆仓库 → 安装 CPU 版 PyTorch 与依赖 → 下载模型权重 → 运行解析命令。官方完整说明见 docs/cpu_support.md。
1️⃣ 克隆仓库并创建虚拟环境
git clone https://gitcode.com/gh_mirrors/mo/MonkeyOCRv2
cd MonkeyOCRv2
conda create -n MonkeyOCRv2Parsing_CPU python=3.11 -y
conda activate MonkeyOCRv2Parsing_CPU
Windows 用户可用内置 venv 替代 conda:
py -3.11 -m venv .venv
2️⃣ 安装 CPU 版 PyTorch 与解析依赖
关键点:安装 +cpu 版本的 PyTorch,而不是默认带 CUDA 的版本;依赖清单位于 parsing/requirements.txt(包含 gradio、timm、pypdfium2 等)。
pip install torch==2.5.1+cpu torchvision==0.20.1+cpu torchaudio==2.5.1+cpu --index-url https://download.pytorch.org/whl/cpu
pip install -r parsing/requirements.txt
pip install transformers==4.57.1 accelerate==1.11.0 huggingface_hub qwen_vl_utils opencv-python einops
3️⃣ 下载模型权重
仓库自带的 download_model.py 支持从 HuggingFace 或 ModelScope(国内更快)下载,权重会保存在 model_weight/ 目录:
# 国内推荐走 ModelScope
pip install modelscope
python download_model.py -t modelscope -n MonkeyOCRv2-B-Parsing
# 或直接从 HuggingFace 下载
python download_model.py -n MonkeyOCRv2-B-Parsing
⚠️ CPU 场景只需下载
MonkeyOCRv2-B-Parsing(或-S-Parsing)。不要下载MonkeyOCRv2-B-Parsing-DFlash——那是 GPU vLLM 推测解码专用的草稿模型。
4️⃣ 一行命令开始解析
CPU 推理入口脚本为 parsing/cpu/parse_cpu.py。解析单张图片或整个目录(支持 PDF 和图片混合):
cd parsing
# 解析单张文档图片
python cpu/parse_cpu.py -i ../images_test/vqa.png -m ../model_weight/MonkeyOCRv2-B-Parsing -o output/test_cpu
# 解析整个目录(PDF/图片)
python cpu/parse_cpu.py -i ../images_test -m ../model_weight/MonkeyOCRv2-B-Parsing -o output/test_cpu
输出目录中会生成:
markdowns/:每页文档对应的 Markdown 文本(含 HTML 表格);jsons/:版面块级的结构化 JSON;- 配合
--draw-layout还会输出版面可视化 PDF。
常用参数速查:CPU推理调优技巧
python cpu/parse_cpu.py -h 可查看全部参数,以下是 CPU 场景下最值得了解的几项:
| 参数 | 作用 | 建议 |
|---|---|---|
-i / -m / -o |
输入路径、模型路径、输出目录 | 输入可为文件或目录 |
--dtype |
数值精度,默认 float32 |
支持 bfloat16,在支持 AVX512-BF16 的 CPU 上可提速 |
--attn-implementation |
注意力实现,默认 eager |
CPU 上保持默认最稳妥 |
--max-pixels |
输入图最大像素,默认 1003520 | 大图会按比例缩放,降低此值可提速 |
--page-max-inflight |
并发处理页数,默认 1 | CPU 单路即可,勿盲目调大 |
--end2end |
端到端解析,直接输出整图 bbox/label/content | 简单任务可用 |
--skip-processed |
跳过已有 Markdown 的文档 | 批量任务中断续跑必加 |
--retry-repeat |
检测重复 token 输出并自动重试(默认最多 3 次) | 长文档推荐开启 |
-t |
单任务识别:text / formula / table |
只要某类结果时更快 |
启动 Web 演示:可视化体验文档解析
除了命令行,MonkeyOCRv2 还内置了 CPU 版 Gradio Web 演示,入口脚本为 parsing/cpu/gradio_demo_cpu.py:
cd parsing
python cpu/gradio_demo_cpu.py \
--model-path ../model_weight/MonkeyOCRv2-B-Parsing \
--output-dir output/demo_cpu_outputs \
--demo-server-name 127.0.0.1 \
--demo-server-port 8891 \
--demo-concurrency 1 \
--page-max-inflight 1
浏览器打开 http://127.0.0.1:8891,即可上传 PDF 或图片,在页面中实时预览解析出的 Markdown 结果,并支持一键下载。CPU 版内置了并发保护参数(--demo-concurrency、--page-max-inflight),避免多请求抢占单核资源。
常见问题排查
- 速度慢:属正常现象。可降低
--max-pixels、优先选MonkeyOCRv2-S-Parsing小模型,或改用bfloat16精度。 - 依赖报错:确认 PyTorch 装的是
+cpu版本(python -c "import torch; print(torch.__version__)"应显示2.5.1+cpu)。 - 解析结果含重复乱码:加上
--retry-repeat让管线自动重试。 - 想上 GPU 加速?:GPU 版走 vLLM 服务(parsing/serve.py + parsing/parse.py),流程与 CPU 版不同,参见 README.md 中 Document Parsing 章节。
- 相关资源:CPU 完整文档 docs/cpu_support.md、WSL 说明 docs/wsl_support.md、信任远程代码说明 docs/trust_remote_code.md、示例图片集 images_test/。
总结
MonkeyOCRv2-Parsing 的纯 CPU 部署把文档解析的硬件门槛降到了零:只需一条 pip install torch==2.5.1+cpu 和一行 parse_cpu.py 命令,普通电脑就能获得 17 语言、支持表格公式的开源文档解析能力。建议先用 images_test/ 里的示例图跑通全流程,再批量处理你的 PDF 语料——没有 GPU,也能让文档智能落地。


