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-LLMDolphin 的解析分两步先按阅读顺序输出一页里所有元素的位置和类型再对文本、表格、公式、代码四类元素批量并行解码两阶段架构。0.3B 的体量决定了部署选型不是能不能跑而是哪条路匹配你的硬件。我们的判断很简单原生 PyTorchdemo_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 装torch2.6.0、transformers4.51.0、triton3.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支持单张图或单份 PDFpython 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装成了新版按锁定版本重装即可。目录批量与多页PDFmax_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 建议 44GB 卡直接降到 2再往上每加一张元素图就多一份视觉编码占用峰值显存是线性涨的。PDF 走 convert_pdf_to_images 逐页渲染长边 896px再按页解析、合并成整份 JSON Markdownpage_6.pdf可直接复现。显存不够先调这三个参数批量、精度、输入尺寸顺序固定先降--max_batch_size4→2多数 OOM 到这步就解了再确认没有其他进程占卡nvidia-smi先看一眼最后才考虑动精度——脚本里 CUDA 分支默认bfloat16()demo_page.py不建议自己改成 FP32那是显存翻倍的死路。输入侧也有一道隐式保护超过 1600px 的图会被压回 1600 长边超大扫描件不需要自己预处理。vLLM加INT4备选单卡吞吐翻身的启动命令原生路线跑通但吞吐不够比如排队几百页等不起备选是 vLLM 后端加 INT4 量化适合离线批处理、不追求单页极限延迟的场景pip install vllm0.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对比部署方案单页耗时显存峰值精度保持率原生 PyTorch (BF16)~28s/页8.7GB100%基线vLLM INT4~1.8s/页2.1GB~96.5%TensorRT-LLM~1.4s/页1.9GB~95.8%耗时和显存来自官方部署文档的参考值加社区 T4 机器实测不同显卡会有出入精度口径是文本编辑距离和表格 TEDS 相对 BF16 基线的保持率——基线本身在 OmniDocBench v1.5 上是总体 85.06、文本 Edit 0.085、表格 TEDS 84.25Dolphin-1.5README_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考