MonkeyOCRv2

专为文档打造的视觉骨干，让 OCR 与版面理解更准

MonkeyOCRv2 是一个面向文档理解场景的原生视觉编码器（Vision Encoder），定位为文档专用视觉骨干网络。传统 OCR 或文档 AI 方案通常直接复用自然图像预训练模型（如 CLIP、ViT），但这类模型对密集文本、表格、公式、版面结构等文档特征并不敏感，导致下游识别与理解效果受限。MonkeyOCRv2 从骨干层面针对文档图像重新设计，让视觉编码器在预训练阶段就学习文档的版面、文字排布与结构信息，从而为 OCR、版面分析、文档问答等任务提供更契合的特征表示。项目以 Python 实现，提供可复用的视觉 Backbone，方便研究者接入现有文档 AI 流水线。作为成长中项目，它强调“Document-Native”理念，即视觉编码器应原生理解文档而非迁移自通用图像模型，适合需要高质量文档特征的研究与工程场景。

开源 free 计算机视觉

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1409

维护状态活跃

是否开源是

定价模式 free

项目数据

分类计算机视觉

开发团队Yuliang-Liu

所属国家

官网地址https://yuliang-liu.github.io/MonkeyOCRv2

GitHubhttps://github.com/Yuliang-Liu/MonkeyOCRv2

定价模式free

价格说明开源项目，免费使用

访问状态

是否开源是

开源协议NOASSERTION

主要语言Python

技术栈/模型

GitHub 星标★ 1409

30天Star增速

HF 下载量

上线时间2026-07-10 00:00:00

最近更新2026-09-18 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-09-19

浏览次数0

使用教程

难度：进阶约 30 分钟部署方式：本地安装 8 步

环境要求

Conda（用于创建 Python 3.11 环境）
Python 3.11
NVIDIA GPU 与匹配的 CUDA 环境（DFlash 加速需 CUDA 12.9 及以上）
需分别创建 Parsing / Understanding 等不同环境，按任务选择安装方式
flash-attn 需编译安装，耗时较长

安装与启动步骤

1创建 Python 环境

用 conda 新建 Python 3.11 环境，README 中视觉编码器环境名为 MonkeyOCRv2。
```
conda create -n MonkeyOCRv2 python=3.11
```
2激活环境

激活刚创建的环境，后续 pip 安装都需在该环境内执行。
```
conda activate MonkeyOCRv2
```

3安装 PyTorch

按官方索引安装指定版本 torch、torchvision、torchaudio（cu126 轮子）。

pip install torch==2.8.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu126

4安装基础依赖

安装 README 指定的 transformers、accelerate、qwen_vl_utils 三个库。
```
pip install transformers==4.57.1
pip install accelerate==1.11.0
pip install qwen_vl_utils==0.0.14
```
5安装 flash-attn

使用 --no-build-isolation 安装 flash-attn 2.8.3，编译过程较慢需耐心等待。
```
pip install flash-attn==2.8.3 --no-build-isolation
```

6安装 vLLM（Parsing）

MonkeyOCRv2-Parsing 用 vLLM 加速推理，需新建环境并执行 requirements。

conda create -n MonkeyOCRv2Parsing python=3.11
conda activate MonkeyOCRv2Parsing
pip install uv
uv pip install vllm --extra-index-url https://wheels.vllm.ai/0.25.1/cu129 --extra-index-url https://download.pytorch.org/whl/cu129 -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install -r parsing/requirements.txt

7无CUDA12.9的替代装法

系统不支持 CUDA 12.9 时改装 vLLM 0.11.2，可正常推理但没有 DFlash 加速。
```
uv pip install vllm==0.11.2 --torch-backend=auto -i https://pypi.tuna.tsinghua.edu.cn/simple
```

8安装Understanding环境

Understanding 场景可新建独立环境，用 vLLM 0.11.2 快速推理。

conda create -n MonkeyOCRv2Und python=3.11
conda activate MonkeyOCRv2Und
pip install uv
uv pip install vllm==0.11.2 --torch-backend=auto -i https://pypi.tuna.tsinghua.edu.cn/simple

关键配置

配置项	必填	说明	示例
`trust_remote_code`	是	加载远程自定义代码所需开关，加载内容见 docs/trust_remote_code.md	`True`

如何确认成功

README 未给出启动验证命令；安装过程无报错、pip show transformers 显示 4.57.1 即视为环境就绪。

常见问题

Q：DFlash 加速对环境和 vLLM 版本有什么要求？

A：需使用 vLLM 0.25.1，并依赖 CUDA 12.9 或更高版本，可获得最高约 2 倍推理加速。

Q：系统不支持 CUDA 12.9 怎么办？

A：可改装 vLLM 0.11.2（不带 DFlash 支持），推理仍可正常运行，只是没有 DFlash 加速。

Q：能在 CPU 上跑 MonkeyOCRv2-Parsing 吗？

A：可以，项目已支持 CPU 运行 Parsing，具体步骤见仓库 docs/cpu_support.md。

Q：只想用 transformers 而不是 vLLM 怎么装？

A：按 MonkeyOCRv2 视觉编码器的安装部分（torch + transformers + accelerate + qwen_vl_utils + flash-attn）安装，可与论文性能对齐。

注意事项

README 中有多个 Install 小节，分别对应 Parsing 与 Understanding 等不同任务，请按需选择，不要混装到同一环境。
README 未提供推理、训练或评测的具体运行命令，实际调用方式需查看仓库中各任务章节与文档。
识别、检测、重叠文本分割、公式识别等任务的训练与评测说明见 README 对应章节，本教程未涉及。
命令中使用的是 README 给定的固定版本号与官方索引地址，替换版本可能导致依赖冲突。

核心亮点

针对文档版面、密集文本与结构重新设计视觉骨干，而非直接套用自然图像预训练模型
以 Python 实现，可作为可复用 Backbone 接入现有 OCR/文档理解流水线
提出 Document-Native 理念，为文档视觉编码提供区别于通用 ViT 的技术路线

不足之处

项目处于成长阶段，生态与下游适配案例相对有限
文档与社区规模待观察，长期维护与版本迭代情况尚不明确

适用场景

文档 OCR 与文字识别系统的视觉特征提取
版面分析、表格与公式等结构化文档理解任务
文档问答、检索增强等需要文档视觉表示的 AI 应用

替代项目

PaddleOCR、Donut、LayoutLMv3

项目介绍

MonkeyOCRv2 是一个计算机视觉领域的开源项目，官方简介：MonkeyOCRv2 Vision Encoder — A Document-Native Visual Backbone。项目使用 Python 开发，在 GitHub 上获得 1409 星标。

上一篇：tessdoc

下一篇：OCR4all