PaddleOCR HPD-Parsing 高吞吐文档解析模型部署与推理实战指南

PaddleOCR HPD-Parsing 高吞吐文档解析模型部署与推理实战指南【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCRHPD-Parsing 是 PaddleOCR 生态中一款面向高吞吐文档解析的轻量级视觉语言模型VLM其核心价值在于通过层级并行解码与渐进式多 token 预测P-MTP技术在保持有竞争力解析精度的同时将公开基准上的峰值吞吐提升至 4,752 tokens/s。本指南基于仓库 HPD-Parsing 使用教程 完整讲解模型原理、运行环境准备Docker 镜像 / 预编译包两种方式、OpenAI 兼容服务化部署、vLLM Python API 本地推理以及性能调优要点读者按文操作即可将 HPD-Parsing 落地到生产级文档解析场景。HPD-Parsing 是什么HPD-Parsing 是一款面向高吞吐文档解析的轻量级视觉语言模型。与 PaddleOCR-VL 系列如 PaddleOCR-VL强调解析精度 紧凑参数量的路线不同HPD-Parsing 将设计重心放在解码效率上适用于对推理效率和部署吞吐要求较高的文档解析场景。传统统一式文档解析模型沿单一轨迹逐 token 串行生成解码步数长、吞吐受限。HPD-Parsing 采用层级并行解码范式主布局分支负责全局结构协调先确定文档的整体版面骨架主分支动态生成多个局部内容分支进行并发解码各分支并行产出文本、标题、图片说明等局部内容结合**渐进式多 token 预测P-MTP**进一步减少各分支内部的解码步数。在保持具有竞争力解析精度的同时HPD-Parsing 在公开基准上达到4,752 tokens/s的峰值吞吐分别达到当前最快文档解析模型的1.62 倍和该模型自回归基线的3.06 倍。该数据与仓库 README.md 在 2026.07.22 发布的更新说明一致其中同样介绍了 HPD-Parsing 的层级并行解码范式与 P-MTP 技术并确认其同时支持 OpenAI 兼容服务化推理与本地推理两种方式。HPD-Parsing需要定制版 vLLM 运行环境该版本基于 vLLM v0.17.1增加了层级并行解码所需的动态请求分叉机制并支持 P-MTP 投机解码因此无法用社区原版 vLLM 直接驱动。使用 HPD-Parsing 分为两步先选择一种方式准备运行环境官方 Docker 镜像或安装预编译包并下载模型权重再选择一种推理方式服务化部署启动 OpenAI 兼容推理服务客户端通过 API 调用。一次部署可供多个客户端并发调用适用于生产部署场景。本地推理通过 vLLM Python API 在当前 Python 进程中直接加载模型无需启动服务适用于单机批量处理。两种推理方式使用同一套推理引擎并且都支持 Docker 镜像和预编译包环境。环境要求维度要求硬件NVIDIA GPU已在 H100、H800、H20、A100、A800、A30、L20、RTX Pro 6000 上完成验证NVIDIA 驱动需支持 CUDA 12.8 或以上版本操作系统Linux x86-64。其他操作系统仅支持通过能够运行 Linux NVIDIA GPU 容器的 Docker 环境使用Docker 镜像方式Docker 版本 19.03并已安装 NVIDIA Container Toolkit预编译包方式Python 3.10–3.13INFOHPD-Parsing 不依赖paddleocrPython 库本教程中的服务启动、客户端调用与本地推理均不需要安装 PaddleOCR。它通过独立的定制版 vLLM 运行时工作这也是它能够独立于 PaddleOCR 主包部署的原因。1. 准备运行环境无论采用服务化部署还是本地推理都需要先准备定制版 vLLM 运行环境。以下两种方式任选其一方式一使用官方 Docker 镜像。方式二安装定制版 vLLM 预编译包并下载模型权重。官方推荐采用 Docker 镜像的方式以最大程度减少可能出现的环境问题。1.1 方式一使用 Docker 镜像官方 Docker 镜像内置定制版 vLLM 及其全部依赖ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu该镜像默认启动推理服务见 2.1 节也可以覆盖默认入口将其用作本地推理环境见第 3 节。无需提前执行docker pull首次执行docker run时Docker 会自动拉取镜像。如需在无法连接互联网的环境中运行 HPD-Parsing请使用离线镜像ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu-offline离线镜像约为24.5 GB内置模型权重启动时无需联网在线镜像约为20.2 GB。请先在联网机器上拉取并导出离线镜像再将其传输到离线机器并导入# 在能够联网的机器上执行 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu-offline # 将镜像保存到文件中 docker save ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu-offline -o hpd-parsing-vllm-latest-nvidia-gpu-offline.tar # 将镜像文件传输到离线机器 # 在离线机器上执行 docker load -i hpd-parsing-vllm-latest-nvidia-gpu-offline.tarTIP标签后缀为latest-xxx的镜像对应最新版本。如果本地已经存在对应的latest镜像但希望使用最新功能或修复建议在继续使用前重新执行一次docker pull更新镜像。1.2 方式二安装预编译包并准备模型权重如果无法使用 Docker可以安装定制版 vLLM 的预编译包。该预编译包支持 Python 3.10–3.13并要求 NVIDIA 驱动支持 CUDA 12.8 或以上版本。建议在虚拟环境中安装以避免依赖冲突。例如可以使用 Python 标准库中的venv创建虚拟环境# 创建虚拟环境 python -m venv .venv_hpd_parsing # 激活环境 source .venv_hpd_parsing/bin/activate执行如下命令完成安装python -m pip install https://paddle-model-ecology.bj.bcebos.com/paddlex/PaddleX3.0/deploy/hpd_parsing/vllm-0.17.1hpdparsing-cp38-abi3-manylinux_2_31_x86_64.whl安装完成后下载完整模型仓库。该仓库同时包含主模型和P-MTP投机解码模型hf download PaddlePaddle/HPD-Parsing --local-dir ./HPD-Parsing下载完成后请确认./HPD-Parsing/config.json和./HPD-Parsing/P-MTP/config.json均存在并保留完整目录结构。第 2 节的服务化部署和第 3 节的本地推理都会使用该目录。如需在离线机器上使用预编译包请在具有相同 Python 版本和操作系统架构的联网机器上通过pip download下载预编译包及其全部依赖同时下载完整模型目录再将这些文件传输到离线机器安装。INFO如果所在网络访问 Hugging Face 较慢可以在下载模型或启动在线 Docker 镜像前设置环境变量HF_ENDPOINThttps://hf-mirror.com使用镜像站。2. 服务化部署服务化部署分为两步先启动推理服务再通过客户端调用。2.1 启动服务使用在线 Docker 镜像时直接启动容器即可。容器会自动下载模型并启动推理服务默认监听8118端口docker run \ -it \ --rm \ --gpus all \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu模型默认缓存在容器内容器删除后缓存也会丢失。如需在后续容器中复用模型缓存可在docker run命令中添加可选参数-v hpd_parsing_hf_cache:/home/hpd/.cache/huggingface。如需使用 Hugging Face 镜像站可添加-e HF_ENDPOINThttps://hf-mirror.com。使用离线 Docker 镜像时直接运行已导入的离线镜像。模型权重已内置无需联网或挂载缓存卷docker run \ -it \ --rm \ --gpus all \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu-offline使用预编译包时请先激活第 1.2 节创建的虚拟环境再进入HPD-Parsing模型目录所在的目录并执行以下命令MODEL_PATH$(realpath ./HPD-Parsing) MAX_PATCHES_WITH_RESIZEtrue vllm serve ${MODEL_PATH} \ --trust-remote-code \ --port 8118 \ --served-model-name HPD-Parsing \ --max-model-len 16384 \ --limit-mm-per-prompt {image: 1} \ --gpu-memory-utilization 0.9 \ --attention-backend FLASHINFER \ --attention-config {use_prefill_query_quantization:true} \ --enable-chunked-prefill \ --enable-prefix-caching \ --speculative-config {\method\:\medusa\,\model\:\${MODEL_PATH}/P-MTP\,\num_speculative_tokens\:6}其中的关键参数说明如下参数说明MAX_PATCHES_WITH_RESIZEtrue环境变量控制图像预处理行为必须设置。--attention-backend FLASHINFER使用 FlashInfer 注意力后端为推荐配置。--speculative-config配置 P-MTPmodel指向 P-MTP 权重目录num_speculative_tokens指定每步生成的投机 token 数量。--max-model-len最大上下文长度可根据显存情况调整。--gpu-memory-utilization显存占用比例可根据实际情况调整。从该命令可以看出 HPD-Parsing 定制版 vLLM 的几个关键机制--enable-chunked-prefill与--enable-prefix-caching用于优化长上下文文档场景下的显存与重复前缀计算--attention-config {use_prefill_query_quantization:true}开启 prefill 阶段 query 量化以降低显存占用而--speculative-config中method: medusa表明 P-MTP 投机解码复用了 Medusa 式的多头投机框架配合num_speculative_tokens: 6每步最多预测 6 个 token。2.2 客户端调用服务启动后可通过OpenAI 兼容 API调用。解析文档图像时提示词固定为document parsing with fork.服务端将自动完成层级并行解码一次请求即可返回完整解析结果。以下是使用openaiPython 客户端库调用服务的示例。请先安装客户端库python -m pip install openaiimport base64 from openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8118/v1, api_keyEMPTY) def encode_image(image_path: str) - str: with open(image_path, rb) as f: return base64.b64encode(f.read()).decode(utf-8) image_base64 encode_image(demo.png) response client.chat.completions.create( modelHPD-Parsing, messages[ { role: user, content: [ { type: image_url, image_url: {url: fdata:image/png;base64,{image_base64}}, }, {type: text, text: document parsing with fork.}, ], } ], max_tokens8000, temperature0, ) print(response.choices[0].message.content)解析结果的结构化格式模型返回结构化的文档解析结果。每个版面块以BLOCK开头后面依次是块类别如text、title、image、image_caption、header、page_number等、边界框坐标以及CHILD后的文本内容。image等无文本内容的块不包含CHILD。这种输出约定使得一次请求即可同时获得版面结构、元素类型与坐标信息便于下游直接构造 JSON 或对接 RAG 管线。以下代码可从输出中提取所有版面块import re def parse_blocks(input_text: str) - list[dict]: 解析输出中的所有版面块 pattern re.compile( rBLOCK(\w)\s*\[([^\]]*)\](?:CHILD)?(.*?)(?BLOCK|\Z), re.DOTALL ) blocks [] for block_type, coords_str, content in pattern.findall(input_text): blocks.append( { type: block_type, bbox: [int(x.strip()) for x in coords_str.split(,)], text: content.strip(), } ) return blocks并发批量请求HPD-Parsing 的吞吐优势在多请求并发场景下更为明显。批量处理文档时建议使用多线程或异步方式并发提交请求。以下示例使用线程池处理多张图像import base64 from concurrent.futures import ThreadPoolExecutor from openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8118/v1, api_keyEMPTY) def parse_one(image_path: str) - str: with open(image_path, rb) as f: image_base64 base64.b64encode(f.read()).decode(utf-8) response client.chat.completions.create( modelHPD-Parsing, messages[ { role: user, content: [ { type: image_url, image_url: {url: fdata:image/png;base64,{image_base64}}, }, {type: text, text: document parsing with fork.}, ], } ], max_tokens8000, temperature0, ) return response.choices[0].message.content image_paths [page_1.png, page_2.png, page_3.png] with ThreadPoolExecutor(max_workers16) as executor: results list(executor.map(parse_one, image_paths)) for path, result in zip(image_paths, results): print(path, len(result))3. 本地推理Python API除了启动推理服务还可以通过 vLLM Python API 在当前进程中直接加载模型。这种方式无需启动服务适用于单机批量处理。首先将以下代码保存为hpd_infer.py并将待解析图像保存为同一目录下的demo.pngimport base64 import os from pathlib import Path from vllm import LLM, SamplingParams model_path Path(os.environ[MODEL_PATH]) if not (model_path / config.json).is_file(): raise FileNotFoundError(f主模型目录无效{model_path}) if not (model_path / P-MTP / config.json).is_file(): raise FileNotFoundError(fP-MTP 模型目录无效{model_path / P-MTP}) llm LLM( modelstr(model_path), trust_remote_codeTrue, max_model_len16384, limit_mm_per_prompt{image: 1}, gpu_memory_utilization0.9, attention_backendFLASHINFER, enable_prefix_cachingTrue, speculative_config{ method: medusa, model: str(model_path / P-MTP), num_speculative_tokens: 6, }, ) sampling_params SamplingParams(temperature0, max_tokens8000) with open(demo.png, rb) as f: image_base64 base64.b64encode(f.read()).decode(utf-8) messages [ { role: user, content: [ { type: image_url, image_url: {url: fdata:image/png;base64,{image_base64}}, }, {type: text, text: document parsing with fork.}, ], } ] outputs llm.chat(messagesmessages, sampling_paramssampling_params) print(outputs[0].outputs[0].text)使用在线 Docker 镜像时在包含hpd_infer.py和demo.png的目录中执行docker run --rm --gpus all \ --entrypoint /bin/bash \ -v $(pwd):/workspace \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu \ -lc export MODEL_PATH$(hf download PaddlePaddle/HPD-Parsing --quiet); cd /workspace; python hpd_infer.py在线镜像首次运行时需要下载模型。如需在后续容器中复用下载结果可在docker run命令中添加可选参数-v hpd_parsing_hf_cache:/home/hpd/.cache/huggingface。如需使用 Hugging Face 镜像站可添加-e HF_ENDPOINThttps://hf-mirror.com。使用离线 Docker 镜像时模型权重已内置无需联网或挂载模型缓存docker run --rm --gpus all \ --entrypoint /bin/bash \ -e MODEL_PATH/home/hpd/models/HPD-Parsing \ -v $(pwd):/workspace \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu-offline \ -lc cd /workspace; python hpd_infer.py使用预编译包时请确认当前目录同时包含hpd_infer.py、demo.png和第 1.2 节下载的HPD-Parsing目录然后执行MAX_PATCHES_WITH_RESIZEtrue \ MODEL_PATH$(realpath ./HPD-Parsing) \ python hpd_infer.py以上三种运行方式共用同一套推理引擎层级并行解码与 P-MTP 均会生效。批量处理时可将多组对话以列表形式传给llm.chat引擎将自动完成批量调度。注意hpd_infer.py中通过os.environ[MODEL_PATH]读取模型路径且启动前校验主模型与 P-MTP 子目录的config.json是否存在这保证了投机解码配置不会因目录缺失而静默失效。4. 性能调优并发请求HPD-Parsing 的层级并行解码会为每个请求动态创建多个并发解码分支吞吐优势在多并发场景下更为显著。建议客户端使用多线程/异步方式批量提交请求参考 2.2 节的线程池示例。减少重复输出解析版面极其复杂的文档时如果模型输出重复内容可以在客户端请求中设置extra_body{repetition_penalty: 1.05}。调整显存占用如果与其他程序共用 GPU服务化部署时可调低--gpu-memory-utilization本地推理时可调低LLM的gpu_memory_utilization。调整输出长度如果解析结果因达到输出上限而被截断可在客户端请求或SamplingParams中调大max_tokens。如果输入与期望输出的总长度超过上下文限制服务化部署时还需调大--max-model-len本地推理时则需调大LLM的max_model_len。增大这些值会占用更多显存。小结HPD-Parsing 通过主布局分支 动态局部内容分支并发解码 P-MTP 投机预测的层级并行解码范式为高吞吐文档解析提供了一条与精度导向型模型互补的路径。在 PaddleOCR 仓库中它作为独立于paddleocr主包的部署单元以定制版 vLLM基于 v0.17.1为运行底座通过 Docker 镜像或预编译包两种方式交付并统一支持 OpenAI 兼容服务与 vLLM Python API 本地推理。实践中的要点可以概括为服务启动务必设置MAX_PATCHES_WITH_RESIZEtrue并配置 FlashInfer 后端与 P-MTP 投机配置客户端固定使用document parsing with fork.提示词并以BLOCK格式解析结构化结果批量场景优先并发提交请求以充分发挥吞吐优势。相关英文版本可参阅 HPD-Parsing.en.md该文档在仓库 mkdocs.yml 中挂载于产线使用导航下随文档站持续维护。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考