Dolphin：通过异构锚点提示进行文档图像解析

Dolphin-v2 是一个增强的通用文档解析模型，在原始 Dolphin 的基础上有了显著提升。它通过一种文档类型感知（document-type-aware）的两阶段架构（two-stage architecture）和可扩展的锚点提示（anchor prompting），无缝处理任何类型的文档——无论是数字原生还是拍摄的。

📑 概述

文档图像解析具有挑战性，因为文档类型多样，且文本段落、图片、公式、表格和代码块等元素复杂交织。Dolphin-v2 通过一种文档类型感知的两阶段方法来解决这些挑战：

1. 🔍 阶段 1：文档类型分类（数字版 vs. 拍摄版）+ 带有阅读顺序预测的布局分析
2. 🧩 阶段 2：混合解析策略 - 拍摄文档的整体解析，数字文档的并行元素级解析

Dolphin 在各种**页面级（page-level）和元素级（element-level）解析任务中取得了令人瞩目的性能，同时通过其轻量级架构（lightweight architecture）和并行解析机制（parallel parsing mechanism）**确保了卓越的效率。

📅 更新日志

• 🔥 2025.12.12 发布 Dolphin-v2 模型。升级至 3B 参数，支持 21 种元素检测、属性字段提取、专用公式/代码解析以及鲁棒的拍摄文档解析。（Dolphin-1.5 已移至 v1.5 分支）
• 🔥 2025.10.16 发布 Dolphin-1.5 模型。在保持轻量级 0.3B 架构的同时，此版本实现了显著的解析改进。（Dolphin 1.0 已移至 v1.0 分支）
• 🔥 2025.07.10 发布 Fox-Page Benchmark，这是原始 Fox 数据集 的手动优化子集。下载地址：百度网盘 | Google Drive。
• 🔥 2025.06.30 添加 TensorRT-LLM 支持 以加速推理！
• 🔥 2025.06.27 添加 vLLM 支持 以加速推理！
• 🔥 2025.06.13 添加多页 PDF 文档解析功能。
• 🔥 2025.05.21 我们的演示已在 链接 发布。快去体验吧！
• 🔥 2025.05.20 发布 Dolphin 的预训练模型和推理代码。
• 🔥 2025.05.16 我们的论文已被 ACL 2025 接收。论文链接：arXiv。

📈 性能

OmniDocBench (v1.5) 上的文档解析综合评估

模型	大小	总体↑	文本Edit↓	公式CDM↑	表格TEDS↑	表格TEDS-S↑	阅读顺序Edit↓
Dolphin	0.3B	74.67	0.125	67.85	68.70	77.77	0.124
Dolphin-1.5	0.3B	85.06	0.085	79.44	84.25	88.06	0.071
Dolphin-v2	3B	89.78	0.054	87.63	87.02	90.48	0.054

🛠️ 安装

1. 克隆仓库：

   git clone https://github.com/ByteDance/Dolphin.git
   cd Dolphin
   

2. 安装依赖：

   pip install -r requirements.txt
   

3. 下载 Dolphin-v2 的预训练模型（pre-trained models）：

   访问我们的 Huggingface 模型卡，或通过以下方式下载模型：

   # 从 Hugging Face Hub 下载模型
   git lfs install
   git clone https://huggingface.co/ByteDance/Dolphin-v2 ./hf_model
   # 或使用 Hugging Face CLI
   pip install huggingface_hub
   huggingface-cli download ByteDance/Dolphin-v2 --local-dir ./hf_model
   

⚡ 推理

Dolphin 提供两个推理框架（inference frameworks），支持两种解析粒度（parsing granularities）：

• 📄 页面级解析（Page-level Parsing）：将整个文档页面解析为结构化的 JSON 和 Markdown 格式
• 🧩 元素级解析（Element-level Parsing）：解析单个文档元素（文本、表格、公式）

📄 页面级解析

# 处理单张文档图像
python demo_page.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs/page_1.png 

# 处理单个文档 pdf
python demo_page.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs/page_6.pdf 

# 处理目录中的所有文档
python demo_page.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs 

# 使用自定义批量大小进行并行元素解码
python demo_page.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs \
    --max_batch_size 8

🧩 元素级解析

# 处理元素图像（指定 element_type: table、formula、text 或 code）

Process element images (specify element_type: table, formula, text, or code)

python demo_element.py --model_path ./hf_model --save_dir ./results
--input_path
--element_type [table|formula|text|code]

### 🎨 布局解析
```bash
# Process a single document image
python demo_layout.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs/page_1.png 
    
# Process a single PDF document
python demo_layout.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs/page_6.pdf 

# Process all documents in a directory
python demo_layout.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs 

🌟 主要特性

• 🔄 基于单个 VLM（视觉语言模型）的两阶段分析后解析方法
• 📊 在文档解析任务上表现优异
• 🔍 自然阅读顺序的元素序列生成
• 🧩 针对不同文档元素的异构锚点提示
• ⏱️ 高效的并行解析机制
• 🤗 支持 Hugging Face Transformers 库以便更轻松地集成

📮 注意事项

征集错误案例： 如果您遇到任何模型表现不佳的案例，我们非常希望您能在 Issue 中分享。我们正在持续努力优化和改进模型。

💖 致谢

我们要感谢以下为我们工作提供灵感和参考的开源项目：

• OmniDocBench
• Donut
• Nougat
• GOT
• MinerU
• Swin
• Hugging Face Transformers

📝 引用

如果您的研究使用了此代码，请使用以下 BibTeX 条目。

@article{feng2025dolphin,
  title={Dolphin: Document Image Parsing via Heterogeneous Anchor Prompting},
  author={Feng, Hao and Wei, Shu and Fei, Xiang and Shi, Wei and Han, Yingdong and Liao, Lei and Lu, Jinghui and Wu, Binghong and Liu, Qi and Lin, Chunhui and others},
  journal={arXiv preprint arXiv:2505.14059},
  year={2025}
}

Star 历史

Dolphin 文档解析模型快速上手指南

Dolphin-v2 是一款增强的通用文档解析模型，采用文档类型感知的两阶段架构，能够无缝处理数字版或拍摄版的各类文档。它支持页面级和元素级的结构化解析（JSON/Markdown），在保持轻量化的同时实现了高效的并行解析。

1. 环境准备

建议配置如下：

• 操作系统: Linux / macOS / Windows
• Python: 3.8 及以上版本
• 硬件: 推荐使用 NVIDIA GPU (CUDA 环境)，以发挥最佳推理性能
• 依赖: 需安装 git-lfs 用于大文件下载

2. 安装步骤

克隆代码仓库

git clone https://github.com/ByteDance/Dolphin.git
cd Dolphin

安装依赖

pip install -r requirements.txt

下载预训练模型

访问 HuggingFace 下载 Dolphin-v2 模型权重（约 3B 参数）：

# 确保已安装 git-lfs
git lfs install

# 方式一：使用 git clone 下载
git clone https://huggingface.co/ByteDance/Dolphin-v2 ./hf_model

# 方式二：或使用 huggingface-cli 下载
pip install huggingface_hub
huggingface-cli download ByteDance/Dolphin-v2 --local-dir ./hf_model

3. 基本使用

模型支持多种解析粒度，以下是最常用的页面级解析命令。请根据实际路径替换 --input_path 和 --save_dir。

页面级解析 (Page-level Parsing)

将整页文档解析为结构化的 JSON 和 Markdown 格式。

单张图片：

python demo_page.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs/page_1.png 

单个 PDF 文档：

python demo_page.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs/page_6.pdf 

批量处理目录：

python demo_page.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs 

自定义批处理大小（并行解码）：

python demo_page.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs \
    --max_batch_size 8

布局解析 (Layout Parsing)

仅提取文档的布局信息（如文本框、表格位置等）。

python demo_layout.py --model_path ./hf_model --save_dir ./results \
    --input_path ./demo/page_imgs/page_1.png 

元素级解析 (Element-level Parsing)

针对特定元素类型（表格、公式、文本、代码）进行精细解析。

python demo_element.py --model_path ./hf_model --save_dir ./results \
    --input_path [element_image_path] \
    --element_type [table|formula|text|code]

---

更多部署优化方案（如 TensorRT-LLM, vLLM）请参考项目根目录下的 deployment 文件夹说明。