zenosai/MonkeyOCRv2-B

MonkeyOCRv2: A Visual-Text Foundation Model for Document AI

News

• 2026.09.07 🚀 MonkeyOCRv2-Parsing is now supported by RAGFlow as a PDF parser. Thanks to the RAGFlow team and community for the support!
• 2026.08.22 🖥️ We now support running MonkeyOCRv2-Parsing on CPU. See the CPU support instructions.
• 2026.08.17 ⚡ Releasing training and evaluation instructions for Recognition, Detection, Overlapping Text Segmentation and Formula.
• 2026.07.24 ⚡ We released MonkeyOCRv2-B-Parsing-DFlash, enabling vLLM serving with DFlash for up to 2× faster inference.
• 2026.07.22 🏆 MonkeyOCRv2-B-Parsing ranks #1 among evaluated open-source models on the official MDPBench Leaderboard, achieving 83.3 overall across 17 languages, including digital-born and photographed documents.
• 2026.07.21 📦 We release MonkeyDoc v2, an open multilingual corpus for document-oriented pretraining. We hope it can serve as a shared data foundation for more transparent, reproducible, and fair comparisons in Document AI.
• 2026.07.14 🚀 We release MonkeyOCRv2, including MonkeyOCRv2 vision encoder, MonkeyOCRv2-Parsing for multilingual document parsing, MonkeyOCRv2-Und for efficient document understanding.

Use MonkeyOCRv2 as a Vision Backbone

MonkeyOCRv2 is released as a standalone, document-native vision encoder. It can be integrated into different OCR and document AI systems as a visual backbone.

The current release has been evaluated on document parsing, document understanding, text recognition, formula recognition, text detection, document tampering detection, and overlapping-text segmentation.

Beyond these evaluated tasks, the encoder may also be useful for text-rich scenarios such as scientific papers, historical documents, medical reports, charts and tables, and remote-sensing maps or reports. We welcome community exploration of these directions.

from transformers import AutoModel

encoder = AutoModel.from_pretrained(
    "zenosai/MonkeyOCRv2-B",
    trust_remote_code=True,
    dtype="auto",
    device_map="auto",
)

See the Vision Encoder Quick Start for installation and feature-extraction examples. If you adapt MonkeyOCRv2 to a new task or domain, feel free to open an issue or pull request and share the results.

MonkeyDoc v2

MonkeyDoc v2 is currently the largest document image pre-training image-text pair dataset, comprising 113 million document images across 17 languages. The open-sourcing of MonkeyDoc v2 is still underway. So far, we have released 52 million synthetic samples and 52 million real-world samples. You can download the full dataset as follows:

pip install modelscope
modelscope download --dataset zenosai/MonkeyDocv2 --local_dir ./MonkeyDocv2

After processing and compression, downloading the dataset currently requires approximately 10 TB of disk space. We recommend having at least 11 TB of available storage before starting the download to ensure sufficient space throughout the process.

Model Zoo

1. Vision Encoder

2. Document Parsing Model

3. Document Understanding Model

Quick Start

What trust_remote_code=True loads is listed in docs/trust_remote_code.md.

Vision Encoder

1. Install

Install transformers and flash attention:

conda create -n MonkeyOCRv2 python=3.11
conda activate MonkeyOCRv2
pip install torch==2.8.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu126
pip install transformers==4.57.1
pip install accelerate==1.11.0
pip install qwen_vl_utils==0.0.14
pip install flash-attn==2.8.3 --no-build-isolation

2. Download Model Weights

Download our model from Huggingface.

python download_model.py -n MonkeyOCRv2-B # or MonkeyOCRv2-S / MonkeyOCRv2-AS

You can also download our model from ModelScope.

pip install modelscope
python download_model.py -t modelscope -n MonkeyOCRv2-B # or MonkeyOCRv2-S / MonkeyOCRv2-AS

3. Extract Image Feature

cd vision
# For MonkeyOCRv2-B and MonkeyOCRv2-S
python extract_feature.py -m ../model_weight/MonkeyOCRv2-B -i ../images_test/ar.JPEG
# For MonkeyOCRv2-AS
python extract_feature_vitae.py -m ../model_weight/MonkeyOCRv2-AS -i ../images_test/ar.JPEG

Document Parsing

1. Install

Install vLLM following its official guide:

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

To use DFlash for faster inference, vLLM 0.25.1 is required, which depends on CUDA 12.9 or later.

If your system does not support CUDA 12.9, you can instead install vLLM 0.11.2 (without DFlash support) by running:

uv pip install vllm==0.11.2 --torch-backend=auto -i https://pypi.tuna.tsinghua.edu.cn/simple

Inference will still work normally, but DFlash acceleration will not be available.

2. Download Model Weights

Download our model from Huggingface.

python download_model.py -n MonkeyOCRv2-B-Parsing # or MonkeyOCRv2-S-Parsing
# use DFlash for faster inference, support MonkeyOCRv2-B-Parsing only for now
python download_model.py -n MonkeyOCRv2-B-Parsing-DFlash

You can also download our model from ModelScope.

pip install modelscope
python download_model.py -t modelscope -n MonkeyOCRv2-B-Parsing # or MonkeyOCRv2-S-Parsing
# use DFlash for faster inference, support MonkeyOCRv2-B-Parsing only for now
python download_model.py -t modelscope -n MonkeyOCRv2-B-Parsing-DFlash

3. vLLM Serving

You should start a vLLM service before parsing documents:

cd parsing
# Serve with DFlash for faster inference
python serve.py -m ../model_weight/MonkeyOCRv2-B-Parsing -d ../model_weight/MonkeyOCRv2-B-Parsing-DFlash -p 8888
# Serve without DFlash
python serve.py -m ../model_weight/MonkeyOCRv2-B-Parsing  -p 8888
# 2 GPUs
python serve.py -m ../model_weight/MonkeyOCRv2-B-Parsing --tp 2 -p 8888
# Show help messages
python serve.py -h

4. Inference

You can parse documents using CLI or serve with demo and FastAPI.

4.1 Parse using CLI

Parse a single document or a directory containing PDFs or images:

cd parsing
python parse.py \
    -i ../images_test \
    -o output/test \
    -s http://127.0.0.1:8888 \
    --draw-layout \
    --skip-processed
# Show help messages
python parse.py -h

4.2 Serve with Web Demo

cd parsing
python demo/gradio_demo.py -s http://127.0.0.1:8888 -p 8891
# Show help messages
python demo/gradio_demo.py -h

You can access the web demo at http://localhost:8891.

4.3 Serve with FastAPI

cd parsing
python fastapi/main.py -s http://127.0.0.1:8888 -p 8000
# Show help messages
python fastapi/main.py -h

You can access the API documentation at http://localhost:8000/docs to explore available endpoints.

POST /parse accepts a single multipart field file or a repeatable files field and returns application/zip (monkeyocrv2_results.zip), with one directory per document containing Markdown. See /docs for the remaining endpoints and request fields.

5. Fine-tune

You can fine-tune MonkeyOCRv2-Parsing on your own data. Please refer to the training instructions.

Document Understanding

1. Install

You can use vLLM for faster inference. Install vLLM following its official guide:

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

or follow the install part of MonkeyOCRv2 vision encoder if you use transformers for aligned performance with the paper.

2. Download Model Weights

Download our model from Huggingface.

python download_model.py -n MonkeyOCRv2-B-Und # or MonkeyOCRv2-S-Und

You can also download our model from ModelScope.

pip install modelscope
python download_model.py -t modelscope -n MonkeyOCRv2-B-Und # or MonkeyOCRv2-S-Und

3. Inference

3.1 Infer with vLLM

Start vLLM service first:

cd understanding
python serve.py -m ../model_weight/MonkeyOCRv2-B-Und  -p 8889

Run inference scripts:

python infer.py \
    -s http://127.0.0.1:8889 \
    -i ../images_test/vqa.png \
    -q 'What is the serving size?'
# Show help messages
python infer.py -h

3.2 Infer with transformers

You can infer with transformers for aligned performance with the paper:

python infer.py \
    -m ../model_weight/MonkeyOCRv2-B-Und \
    --attn-implementation flash_attention_2 \
    -i ../images_test/vqa.png \
    -q 'What is the serving size?'

4. Fine-tune

You can fine-tune MonkeyOCRv2-Und on your own data. Please refer to the training instructions.

Scene Text Recognition

Please refer to ./recognition for training and evaluation instructions.

Scene Text Detection

Please refer to ./detection for training and evaluation instructions. Detection is split into two trees: DPText-DETR/ and mmocr/ (DBNet and PSENet).

Overlapping Text Segmentation

Please refer to MOT for training and evaluation instructions.

Formula Recognition

Please refer to ./formula for training and evaluation instructions.

Document Tampering Detection

Please refer to ./forensics/readme.md for installation, checkpoints, and evaluation.

Visualization

Our model supports robust document parsing in real-world scenarios across 17 languages, including Simplified Chinese (ZH), Traditional Chinese (ZH-T), English (EN), Arabic (AR), German (DE), Spanish (ES), French (FR), Hindi (HI), Indonesian (ID), Italian (IT), Japanese (JP), Korean (KO), Dutch (NL), Portuguese (PT), Russian (RU), Thai (TH), and Vietnamese (VI).

Evaluation Results

1. Text recognition results on Common Benchmarks, Union14M-Benchmark, OST, and Chinese Benchmarks. We follow the training and evaluation protocols of OpenOCR.

2. Formula recognition results on OmniDocBench 1.6, MathWriting, and UniMER-Test.

3. Text detection results on Total-Text, CTW1500, ICDAR2015 and ArT. We follow the training and evaluation protocols of MMOCR and DPText-DETR.

4. Document tampering detection results on DocTamper benchmark.

* denotes models trained with the ViTAEv2 pretrained by DeepSolo

5. Overlapping text segmentation results on MOT dataset.

6. Document parsing results on MDPBench, a comprehensive multilingual benchmark for real-world document parsing.

7. Document understanding performance comparison across different vision foundation models. The evaluation benchmarks are selected following TextMonkey and DT-VQA.

MonkeyDoc v2

MonkeyDoc v2 is currently the largest document image pre-training image-text pair dataset, comprising 113 million document images across 17 languages. The open-sourcing of MonkeyDoc v2 is still underway. So far, we have released all 52 million synthetic samples and 41 million real-world samples derived from FinePDF. Additional real-world data from other sources is currently being organized and will be released progressively.

Expert Model Labeling Toolchain

We adopt a multi-expert labeling pipeline to obtain reliable annotations for documents. The pipeline includes the following steps:

1. Structure Detection
   We use dots.mocr for document structure detection and reading-order prediction. The detected regions, including text blocks, tables, formulas, and other layout elements, are cropped from the original page image for subsequent recognition.
2. Content Recognition
   Each cropped block is independently recognized by three expert models: dots.mocr, PaddleOCR-VL, and Qwen3-VL. These complementary models provide multiple annotations for the same block, reducing reliance on any single OCR system.
3. Block-Level Agreement Filtering
   We compare the recognition results from the three expert models and filter out blocks with low agreement. For retained blocks, we select the prediction that has the highest average agreement with the other two predictions as the final block-level annotation.
4. Page-Level Quality Control
   Pages containing any filtered block are discarded. In addition, we use Qwen3 to verify whether the predicted reading order is reasonable, and Qwen3-VL to check whether document regions are missed during structure detection. This multi-expert agreement strategy reduces model-specific annotation errors and improves the reliability of the generated annotations.

References

• dots.mocr: https://github.com/rednote-hilab/dots.mocr
• PaddleOCR-VL: https://github.com/PaddlePaddle/PaddleOCR
• Qwen3-VL: https://github.com/QwenLM/Qwen3-VL
• Qwen3: https://github.com/QwenLM/Qwen3
• MonkeyOCR: https://github.com/Yuliang-Liu/MonkeyOCR
• MDPBench: https://github.com/Yuliang-Liu/MultimodalOCR
• MonkeyDoc: https://modelscope.cn/datasets/zenosai/MonkeyDoc
• MonkeyDoc v2: https://modelscope.cn/datasets/zenosai/MonkeyDocv2

Citation

If you use any part of this release — the MonkeyOCRv2 encoders, MonkeyOCRv2-Parsing, MonkeyOCRv2-Und, the MDPBench benchmark, or the MonkeyDoc v2 dataset — please cite:

@article{liu2026monkeyocrv2,
  title   = {MonkeyOCRv2: A Visual-Text Foundation Model for Document AI},
  author  = {Liu, Yuliang and Li, Zhang and Zhang, Ziyang and Zhang, Shuo and
             Liu, Qiang and Song, Jiajun and Guo, Zidun and Wang, Xinhan and
             Zheng, Handong and Liu, Yang and Luo, Dongliang and Ma, Zhiyin and
             Zhang, Jiarui and Bai, Xiang},
  journal = {arXiv preprint arXiv:2607.11562},
  year    = {2026}
}

Copyright

Share reproductions, integrations, and failure cases in GitHub Discussions. We warmly welcome your feedback, suggestions, and contributions, which are essential to the continued development and improvement of our framework. The models are are released under the Apache License 2.0 and are free for both research and commercial use. For any questions, please contact us at xbai@hust.edu.cn or ylliu@hust.edu.cn.