Dolphin 0.3B 文档解析模型单卡部署实战：从环境配置到批量 Markdown 输出-二趣网

Dolphin 0.3B 文档解析模型单卡部署实战：从环境配置到批量 Markdown 输出

【免费下载链接】DolphinThe official repo for “Dolphin: Document Image Parsing via Heterogeneous Anchor Prompting”, ACL, 2025.项目地址: https://gitcode.com/GitHub_Trending/dolphin33/Dolphin

在本地单卡 GPU 上部署 Dolphin 文档解析模型，可将数字版与拍照版页面（含多页 PDF）批量转换为带阅读顺序的 JSON 与 Markdown，0.3B 参数规模即可运行，整页、元素、布局三种粒度开箱可用。

项目能力与适用边界

Dolphin（Document Image Parsing via Heterogeneous Anchor Prompting）是字节跳动开源的轻量级文档解析模型，核心参数规模 0.3B（ACL 2025）。

它能做什么：

整页解析：数字版（digital-born）与拍照版（photographed）页面均可处理；多页 PDF 自动逐页拆分解析。
元素级解析：对 table、formula、code、text 四类元素单独解析。
布局分析：仅输出元素定位框（bbox）与自然阅读顺序，不生成内容。

输入与边界：

支持输入：jpg/jpeg/png 图片、pdf（脚本按扩展名分发，见 demo_page.py）。
页面被判定为扭曲/拍照文档（bbox 大面积重叠）时，会整体回退为整页解析模式，元素级精度下降。
不适合：手写文档、重度倾斜或低光照扫描件的精确还原。

方案选型：三条部署路线对比

路线	显存占用	单页吞吐	搭建难度	精度保持
Transformers 基线（本仓库脚本）	低（0.3B，bf16）	基准速度	低，装依赖即可跑	100%（基线）
vLLM	略高	高，批量服务化	中，需部署插件	以部署配置为准
TensorRT-LLM	与精度配置相关	最高，需构建引擎	高，依赖版本要求严格	以引擎配置为准

一句话建议：快速验证与离线批处理选 Transformers 基线；面向多租户的解析服务选 vLLM；追求极限吞吐且愿意维护引擎构建流程再考虑 TensorRT-LLM。后两条路线的完整配置在官方仓库deployment/目录下维护，搭建前请先核对版本要求。

环境与依赖准备

环境清单（依据 requirements.txt 固定版本）：

系统：Linux
Python：3.8–3.10（torch 2.6.0 对应版本）
显卡：NVIDIA GPU，CUDA 可用；无 GPU 会自动降级 CPU + float32，速度大幅下降
依赖：transformers 4.51.0、torch 2.6.0、qwen_vl_utils、pymupdf（PDF 转页）

最小安装命令：

git clone https://gitcode.com/GitHub_Trending/dolphin33/Dolphin && cd Dolphin pip install -r requirements.txt

主路线实施：基线推理

步骤 1：下载模型权重

操作目标：拿到完整模型目录。
命令（按版本选择其一，Dolphin-1.5 或 Dolphin-v2）：

git lfs install && git clone https://huggingface.co/ByteDance/Dolphin-1.5 ./hf_model

验证方法：./hf_model下应同时存在配置文件（config）与权重文件；AutoProcessor.from_pretrained加载不报错即完整。

步骤 2：页面级解析（主流程）

操作目标：把整页/整 PDF 转成结构化 JSON + Markdown。
命令：

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

关键参数：--model_path指向本地模型目录；--input_path可传单文件（图片或 PDF）或整个目录；--max_batch_size控制单次批量解码的元素数（默认 4），是显存与速度的直接调节旋钮。
验证方法：终端打印Processing completed. Results saved to ./results；检查./results/output_json/*.json（每个元素含 label、bbox、text、reading_order）、./results/markdown/*.md（图片以相对路径引用figures/）、./results/layout_visualization/*.png（框线可视化，用于核对阅读顺序）。

步骤 3：元素级解析

操作目标：对已裁出的表格、公式、代码块单独出结果。
命令：

python demo_element.py --model_path ./hf_model \ --input_path ./demo/element_imgs/table.jpg \ --element_type table

说明：--element_type取值为table | formula | code | text，对应不同的任务提示词。
验证方法：开启--print_results可把识别文本直接打到终端，与输入图肉眼比对；./results/output_json中 label 应为tab。

步骤 4：仅做布局分析

操作目标：只要元素定位与阅读顺序，不要内容。
命令：

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

验证方法：查看layout_visualization下的框线图，元素编号顺序是否符合版面阅读习惯。

效果验证

官方在 OmniDocBench (v1.5) 上的基准数据（来源 README.md）：

模型	参数	Overall↑	Text^Edit↓	Formula^CDM↑	Table^TEDS↑	Table^TEDS-S↑	ReadOrder^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.5 相对 1.0 的提升明显，低配机器优先部署 1.5。仓库内置样例可用来做回归：

自建数据的验收清单：JSON 中元素 label 无缺失、reading_order 单调递增；Markdown 中表格保留结构、公式为 LaTeX、图片引用路径可解析；对照layout_visualization抽查 2–3 页定位框。

常见问题排查

现象：CUDA out of memory。原因：--max_batch_size过大，或同卡还有其它进程。处理：降到--max_batch_size 4或更低；用nvidia-smi释放其它占用。
现象：推理极慢，日志提示运行在 CPU。原因：torch.cuda.is_available()为 False，驱动/CUDA 不匹配（demo_page.py 会自动降级 CPU + float32）。处理：核对驱动版本，python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"应输出 CUDA 版本与 True。
现象：JSON 里出现distorted_page，整页只有一个元素。原因：拍照/倾斜文档的 bbox 重叠率超过阈值，脚本整体回退为整页解析。处理：查看终端High overlap detected提示与layout_visualization框图；重新拍摄摆正后复跑。
现象：PDF 报错Failed to convert PDF。原因：pymupdf 不可用或文件损坏。处理：确认requirements.txt已装齐（pymupdf==1.26），先用 demo/page_imgs/page_6.pdf 做最小回归。
现象：JSON 正常但 markdown 目录为空。原因：MarkdownConverter 初始化异常被静默跳过。处理：加--post_process复跑；仍异常时在 issue 中附上输入样本。

结语

0.3B 的 Dolphin 用一套基线脚本即可在单卡上跑通整页、元素、布局三种解析，后续吞吐升级路径（vLLM / TensorRT-LLM）由官方deployment/目录承接。遇到问题欢迎到仓库 issue 区反馈 bad case。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析