MonkeyOCRv2

环境要求

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

安装与启动步骤

1. 1创建 Python 环境

   用 conda 新建 Python 3.11 环境，README 中视觉编码器环境名为 MonkeyOCRv2。

   conda create -n MonkeyOCRv2 python=3.11

   复制

2. 2激活环境

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

   conda activate MonkeyOCRv2

   复制

3. 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. 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. 5安装 flash-attn

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

   pip install flash-attn==2.8.3 --no-build-isolation

   复制

6. 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. 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. 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

   复制

关键配置

如何确认成功

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

常见问题

注意事项

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