Dolphin文档解析低显存部署实录：8GB显卡从跑不动到批量出Markdown

Dolphin文档解析低显存部署实录：8GB显卡从跑不动到批量出Markdown

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

上周给组里那台只剩 8GB 显存的 T4 找活干，活是每天上千页合同扫描件转结构化 Markdown，原生 PyTorch 一开就爆显存。最后我们选了字节开源的 0.3B 文档解析模型 Dolphin 做文档图像解析，在低显存机器上把整条链路跑通了：BF16 权重本身只占约 1.2GB，剩下空间全留给元素解码的 KV cache。这篇是完整实录——一条从 clone 到出结果的部署路径，加一份显存、批大小、量化档位的参数速查，照着抄就行。

三条部署路线怎么选：原生PyTorch、vLLM量化、TensorRT-LLM

Dolphin 的解析分两步：先按阅读顺序输出一页里所有元素的位置和类型，再对文本、表格、公式、代码四类元素批量并行解码（两阶段架构）。0.3B 的体量决定了部署选型不是"能不能跑"，而是"哪条路匹配你的硬件"。

我们的判断很简单：

• 原生 PyTorch（demo_page.py）：显存 8GB 起步，精度无损，先拿它验证功能和输出格式；
• vLLM + INT4：吞吐导向，适合离线跑几百页的队列，显存能压到 2.1GB 一线，精度约掉 3 个点；
• TensorRT-LLM：延迟导向，单页延迟最低，但要单独构建视觉编码器和 LLM 两套引擎，多卡或高配机器才值得上。

只有一张消费级卡、显存 6-8GB 的，直接按第一条路线走，本文后续全部基于它展开。

环境与最小安装：锁定版本、权重单独下

硬门槛：Linux、Python 3.10、NVIDIA 显卡配 CUDA 12.1 的驱动、显存最低 4GB、推荐 8GB。依赖版本锁得很死，照 requirements.txt 装，torch==2.6.0、transformers==4.51.0、triton==3.2.0这些是硬绑定：

git clone https://gitcode.com/GitHub_Trending/dolphin33/Dolphin cd Dolphin && pip install -r requirements.txt huggingface-cli download <ByteDance-Dolphin权重> --local-dir ./hf_model # 0.3B BF16，约0.6GB

仓库里只有推理代码和演示样例，权重需要单独拉取，具体模型名以当前分支（1.5 / v2）在项目发布页的标注为准。

单页验证：先跑通demo_page.py再谈批量

第一步别碰批量，先拿仓库自带样例验流水线。--model_path指向权重目录，--input_path支持单张图或单份 PDF：

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

验证点：results/下自动建出output_json/、markdown/、layout_visualization/三个目录，同名文件各一份；可视化图里的框应该贴着实际元素、序号按阅读顺序递增。常见卡点在加载阶段就炸——Qwen2_5_VLForConditionalGeneration报架构不识别，基本是transformers装成了新版，按锁定版本重装即可。

目录批量与多页PDF：max_batch_size怎么定

单页通了之后，把--input_path换成目录或 PDF 就是批量模式：

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

--max_batch_size控制同类型元素一次解码几张，脚本默认 4。8GB 卡跑混合版面 PDF 建议 4，4GB 卡直接降到 2，再往上每加一张元素图就多一份视觉编码占用，峰值显存是线性涨的。PDF 走 convert_pdf_to_images 逐页渲染（长边 896px），再按页解析、合并成整份 JSON + Markdown，page_6.pdf可直接复现。

显存不够先调这三个参数：批量、精度、输入尺寸

顺序固定：先降--max_batch_size（4→2，多数 OOM 到这步就解了），再确认没有其他进程占卡（nvidia-smi先看一眼），最后才考虑动精度——脚本里 CUDA 分支默认bfloat16()（demo_page.py），不建议自己改成 FP32，那是显存翻倍的死路。输入侧也有一道隐式保护：超过 1600px 的图会被压回 1600 长边，超大扫描件不需要自己预处理。

vLLM加INT4备选：单卡吞吐翻身的启动命令

原生路线跑通但吞吐不够（比如排队几百页等不起），备选是 vLLM 后端加 INT4 量化，适合离线批处理、不追求单页极限延迟的场景：

pip install "vllm>=0.9.0" python -m vllm.entrypoints.openai.api_server \ --model ./hf_model --hf-overrides '{"architectures": ["Qwen2_5_VLForConditionalGeneration"]}' \ --quantization awq --max-num-batched-tokens 4096

与主路径的差异一句话：解码从transformers的model.generate()换成 vLLM 的 PagedAttention 调度，精度代价约 3 个点，换来 2.1GB 级别的显存占用。注意架构名必须改成Qwen2_5_VLForConditionalGeneration（见 demo_page.py 的实际加载类），仓库更新日志里提到的DolphinForConditionalGeneration在当前快照里并不存在，照抄会加载失败。

实测数据与精度取舍：原生、vLLM INT4、TensorRT-LLM对比

耗时和显存来自官方部署文档的参考值加社区 T4 机器实测，不同显卡会有出入；精度口径是文本编辑距离和表格 TEDS 相对 BF16 基线的保持率——基线本身在 OmniDocBench v1.5 上是总体 85.06、文本 Edit 0.085、表格 TEDS 84.25（Dolphin-1.5，README_CN.md 性能表）。

最该盯的是编辑距离而不是表格分：0.3 个点的文本 Edit 差异，对内部知识库、文档归档这类场景无感；如果你的业务是合同、论文这种逐字核对的，别量化，BF16 原样跑，8GB 显存完全装得下。

上面两张是仓库演示样例（demo/element_imgs/）：表格块要还原成结构可解析的 HTML，代码块要保住缩进和语法结构，这两类输出的质量直接决定下游要不要人工兜底。

三个高频使用入口：目录批跑、元素单测、布局定位

• 整目录/多页 PDF 批跑：--input_path直接给目录，*.jpg/*.jpeg/*.png/*.pdf自动收集排序，PDF 逐页拆再合并，适合接 cron 做夜间批处理；注意队列并发开 2 个进程以上时显存峰值会叠加，4GB 卡只开 1 个。
• 元素级单测：已有版面检测结果、只想重跑某类元素时用 demo_element.py，--element_type取table|formula|text|code，输出字段格式和页面级解析对齐，方便直接替换流水线里的单类结果。
• 只要框和阅读顺序：demo_layout.py 只跑第一阶段，出布局框 + 序号，下游接自己的识别模型时用。

踩坑记录：版本锁、批大小、拍照文档

transformers 版本漂移：加载即报架构不识别，排查了很久最后对比 requirements.txt 发现是transformers装成了 4.5x 之后的新版，连带qwen_vl_utils的预处理接口也对不上。解法只有一条：按锁定版本整组重装，别只升单个包。

8GB 卡上--max_batch_size 8必 OOM：报错发生在元素解码阶段而不是布局阶段，说明布局那一下没问题，死在同类型元素并行时。我们把批大小降到 4 后峰值回落到安全线内，再降到 2 只用于 4GB 卡。这个值不改也能跑通单页（默认 4），但批量时它第一个该动。

拍照/倾斜文档出"空结果"：日志里会打Falling back to distorted_page mode，这是 check_bbox_overlap 检测到 60% 以上框重叠后的兜底降级——整页当一个扭曲页处理，不再做元素级解析。想拿全内容，先把图做矫正再重跑，比调参数有效。

从 8GB 卡上的原生 BF16 起步，吞吐不够切 vLLM INT4，单页延迟卡得死再上 TensorRT-LLM，三个参数的入口都在 demo_page.py 和 demo_element.py 里。部署中遇到的 badcase 和显存异常，带nvidia-smi快照和参数直接去仓库 issue 区提。

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