PaddleOCR-VL：版本、安装、服务化部署与基准测试

PaddleOCR-VL 是什么#

PaddleOCR-VL 是一条两阶段产线，而不是单个模型。¹第一阶段是版面分析模型：检测页面上的每个元素（段落、标题、表格、公式、图表、印章），排好阅读顺序并裁剪出来。第二阶段是一个小型视觉语言模型：逐个读取裁剪出的区块，输出 Markdown、HTML 表格、LaTeX 或图表数据表。最后产线按阅读顺序把各部分重新拼接起来。

VLM 组件由 NaViT 风格的动态分辨率视觉编码器和 ERNIE-4.5-0.3B 语言模型组成。¹Hugging Face API 给出的参数量为 958,588,736（BF16 safetensors），三个版本都一样——v1、1.5 和 1.6 共用同一套架构。⁴PaddleOCR-VL-1.6-0.9B 这类名称中的“0.9B”仅指这个 VLM 组件，并不是另一种模型规模。¹

选 PaddleOCR-VL 还是 PP-StructureV3？#

两者都能把文档转换为 Markdown 和 JSON，也都包含在 paddleocr[doc-parser] 中。README 的定位是：需要更细粒度坐标（例如表格单元格框和文本行框）时选 PP-StructureV3，VL 系列不返回这些坐标。⁵PaddleOCR-VL 则是精度之选：在 OmniDocBench v1.5 榜单上，PaddleOCR-VL-1.5 得分 94.50，PP-StructureV3 为 86.73。⁷PP-StructureV3 在 CPU 上就能流畅运行；PaddleOCR-VL 则是为 GPU 设计的。

版本：v1、1.5 与 1.6#

1. 2025 年 10 月 16 日PaddleOCR-VL（v1）随 PaddleOCR 3.3.0 发布。支持 109 种语言；文本、表格、公式和图表；arXiv 2510.14528。⁵⁴
2. 2025 年 10 月 29 日支持 Hugging Face Transformers。⁴
3. 2025 年 11 月 4 日官方支持 vLLM。⁴
4. 2026 年 1 月 29 日PaddleOCR-VL-1.5随 PaddleOCR 3.4.0 发布。新的 PP-DocLayoutV3 版面模型支持多边形框，新增印章识别、文字定位识别（spotting）、跨页表格合并和标题层级；新增藏文和孟加拉文；arXiv 2601.21957。¹⁵
5. 2026 年 3 月 6 日1.5 支持 llama.cpp（GGUF）。⁴
6. 2026 年 5 月 28 日PaddleOCR-VL-1.6随 PaddleOCR 3.6.0 发布。架构与 1.5 相同；据百度称，古籍、生僻字、印章、文字定位和图表的效果更好。技术报告 arXiv 2606.03264 于 6 月 3 日发布。¹⁹
7. 2026 年 7 月 22 日发布独立的高吞吐文档解析方案 HPD-Parsing（见下文）。⁵

版面模型和组件名来自 PaddleX 3.7.2 的产线配置。³VLM 通过任务提示词工作：v1 支持 OCR:、Table Recognition:、Formula Recognition: 和 Chart Recognition:；1.5 和 1.6 新增 Spotting: 和 Seal Recognition:。⁴PP-DocLayoutV2 和 V3 使用同样的 25 个标签，包括 display_formula、inline_formula、vertical_text、seal 和 chart。¹⁵V3 在一次前向中同时预测多边形框和阅读顺序；它自己的模型卡称 GLM-OCR 也在使用它。¹⁵

基准测试：PaddleOCR-VL 处于什么水平#

文档解析领域引用最多的基准是 OmniDocBench，由 OpenDataLab 发布——这个团队也在开发 MinerU，而 MinerU 就出现在同一张榜单上。下面的榜单来自 OmniDocBench 自己的 README，而不是百度。各行数据按原样照录。⁶其中“综合得分”（Overall）为 ((1 − TextEdit) × 100 + TableTEDS + FormulaCDM) / 3，基于 1,651 页计算。⁶

在这十个系统中，PaddleOCR-VL-1.6 的公式得分最高（CDM 97.53），TeleOCR 的表格得分领先，OvisOCR2 的文本编辑距离最好。⁶作为参照，同一张表中 Gemini 3 Pro 为 92.91，dots.ocr 为 90.77，GPT-5.2 为 86.59，MinerU 产线为 86.47。GPT-4o 和 PP-StructureV3 不在这张表中。⁶请记住，在一个 1,651 页的基准上相差 1–2 分，对你自己的文档说明不了太多——请用自己的样本测试。

每个版本提升了多少？#

在 Real5-OmniDocBench 上，从 v1 到 1.5 的跃升主要来自困难样本：倾斜页面从 77.47 提升到 91.66，屏幕翻拍从 82.54 提升到 91.76，这与 PP-DocLayoutV3 改用多边形版面框相吻合。⁸请把这些当作厂商数据看待。在独立榜单上提升幅度更小：v1 到 1.5 为 +0.75，1.5 到 1.6 为 +1.41。⁶

硬件要求#

在 NVIDIA GPU 上，要求取决于运行 VLM 的推理引擎：¹

• T4 和 V100（CC 7.x）可以启动 vLLM，但文档说“prone to timeouts or OOM”（容易超时或显存不足），不推荐使用。这些显卡请使用 PaddlePaddle 推理引擎。¹
• RTX 30/40/50 和 A10/A100 的 CC 均在 8 以上，所有后端都可用，只是 RTX 50（Blackwell，CC 12）不在 SGLang 和 FastDeploy 的支持范围内。Blackwell 有单独的指南：需要支持 CUDA 12.9+ 的驱动和 -sm120 镜像。¹¹
• 显存：仓库中没有任何地方给出最低要求。唯一与显存相关的说明是针对 NVIDIA RTX 3060 的调优建议：为 vLLM 或 FastDeploy 设置 gpu-memory-utilization: 0.7。¹
• x64 CPU：支持矩阵把 x64 CPU 上的本地 PaddlePaddle 推理标为支持，但 MCP 服务器文档说 VL 系列“CPU inference is not recommended”（不推荐 CPU 推理）。¹¹⁶我们没有测过耗时。

各推理方式支持哪些设备#

“+ 服务”各行表示版面分析在客户端用 PaddlePaddle 运行，VLM 在对应的推理服务上运行。“待定”表示文档标注为进行中或尚未验证。官方矩阵还涵盖昆仑芯、海光、沐曦、天数智芯和 Intel Arc（见下文）。vLLM、SGLang 和 FastDeploy 不能在 Windows 上原生运行，因此在 Windows 上请使用 Docker。¹

安装#

VL 指南要求 PaddlePaddle 3.2.1 或更高版本、Python 3.9–3.13，并建议使用虚拟环境。不要同时安装 CPU 版和 GPU 版 PaddlePaddle。¹

python -m venv .venv_paddleocr && source .venv_paddleocr/bin/activate
python -m pip install paddlepaddle-gpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
python -m pip install -U "paddleocr[doc-parser]"

python -m venv .venv_paddleocr && source .venv_paddleocr/bin/activate
python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install -U "paddleocr[doc-parser]"

# 约 8 GB 的镜像，已预装 PaddlePaddle；需要支持 CUDA 12.6+ 的驱动
docker run -it --gpus all --network host --user root \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-nvidia-gpu \
  /bin/bash
# 然后在容器内运行 paddleocr 命令行或 Python
# 离线版（约 10 GB）：...:latest-nvidia-gpu-offline

两点来自我们自己测试的版本说明。使用 PyPI 上默认的 paddlepaddle（撰写本文时为 3.3.1）时，我们在 CPU 上运行 PP-OCRv6 推理会因 ConvertPirAttribute2RuntimeAttribute 错误而崩溃——所以我们锁定了指南中给出的确切版本。另外，如果看到 A dependency error occurred during pipeline creation，说明安装 paddleocr 时没有带 [doc-parser] extra。两者都收录在我们的报错排查中；各操作系统和 CUDA 选项的完整组合见安装教程。

Python 与命令行用法#

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL()          # 默认加载 v1.6
# pipeline = PaddleOCRVL(pipeline_version="v1.5")
# pipeline = PaddleOCRVL(engine="transformers")
# pipeline = PaddleOCRVL(device="cpu")   # Apple Silicon

for res in pipeline.predict("paper.png"):
    res.print()
    res.save_to_json(save_path="output")
    res.save_to_markdown(save_path="output")
    res.save_to_word(save_path="output")   # .docx

paddleocr doc_parser -i paper.png --save_path ./output

# 指定版本，或切换推理引擎
paddleocr doc_parser -i paper.png --pipeline_version v1.5 --save_path ./output
paddleocr doc_parser -i paper.png --engine transformers --save_path ./output

# 先校正旋转或弯曲的页面
paddleocr doc_parser -i photo.jpg --use_doc_orientation_classify True --use_doc_unwarping True

pipeline_version 只接受 "v1"、"v1.5" 和 "v1.6"，分别对应 PaddleX 产线 PaddleOCR-VL、PaddleOCR-VL-1.5 和 PaddleOCR-VL-1.6。²每个结果的 parsing_res_list 结构与 PP-StructureV3 相同——block_label、block_content、block_bbox、block_order——保存方法有 save_to_json、save_to_markdown、save_to_html、save_to_xlsx、save_to_word 和 save_to_img。¹

多页 PDF：restructure_pages()#

PDF 会按页各返回一个结果。要合并跨页延续的表格、在整篇文档范围内重建标题层级，或把所有内容合并成一个结果，请把页面列表传给 restructure_pages()：¹

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL()
pages = list(pipeline.predict("report.pdf"))

# 代码中 merge_tables 和 relevel_titles 默认已经是 True
merged = pipeline.restructure_pages(pages, concatenate_pages=True)

for res in merged:        # concatenate_pages=True 时只有一个结果
    res.save_to_markdown(save_path="output")

PaddleOCR 3.7.0 中的签名是 restructure_pages(res_list, merge_tables=True, relevel_titles=True, concatenate_pages=False)，返回一个列表。²官方示例显式传入了 merge_tables=True, relevel_titles=True，看起来像是默认关闭；实际上并非如此。只有 concatenate_pages 需要手动打开。另外还有一个更简单的 concatenate_markdown_pages(markdown_list) 辅助方法，与 PP-StructureV3 中的那个相同。

常用参数#

vl_rec_* 类参数只能在构造函数中设置；其余参数既可在构造函数中设置，也可在每次调用 predict() 时设置，但 prompt_label、layout_shape_mode 和采样参数只能在 predict() 中设置。默认值来自使用文档和 3.7.0 源码；prompt_label 的取值来自 PaddleX 3.7.2 代码，它接受六个标签，尽管报错信息里只列出四个。¹²³有一处矛盾：文档给出 layout_threshold 的默认值为 0.5，而 PaddleX 配置中 1.5 和 1.6 使用 0.3，v1 则按类别使用 0.4–0.5。³要查看你的产线实际使用的配置，可调用 pipeline.export_paddlex_config_to_yaml("vl.yaml")；修改后再用 PaddleOCRVL(paddlex_config="vl.yaml") 传回。²

服务化部署：vLLM、SGLang、FastDeploy、llama.cpp#

上面的快速开始方式在一个 Python 进程内运行全部内容。文档称其适合“rapid validation”（快速验证），生产环境则推荐使用独立的 VLM 推理服务。¹分工如下：VLM 服务端只运行 0.9B 模型；你的客户端——仍然是 PaddleOCRVL 产线——在本地做版面分析，再把裁剪出的区块发送给服务端。由于客户端仍要运行版面模型，文档建议客户端也使用 GPU。¹

启动 VLM 推理服务#

docker run -it --rm --gpus all --network host \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-nvidia-gpu \
  paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm

docker run -it --rm --gpus all --network host \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-fastdeploy-server:latest-nvidia-gpu \
  paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend fastdeploy

python -m venv .venv_vlm && source .venv_vlm/bin/activate
python -m pip install "paddleocr[doc-parser]"
paddleocr install_genai_server_deps vllm      # 或：sglang、fastdeploy
paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --backend vllm --port 8118

# GGUF 文件：huggingface.co/PaddlePaddle/PaddleOCR-VL-1.6-GGUF
./build/bin/llama-server \
  -m /path/to/PaddleOCR-VL-1.6-GGUF.gguf \
  --mmproj /path/to/PaddleOCR-VL-1.6-GGUF-mmproj.gguf \
  --port 8111 --host 0.0.0.0 --temp 0

以上命令原样摘自使用教程。¹install_genai_server_deps 安装的 vLLM 和 SGLang 构建面向 CUDA 12.6，且 vLLM/SGLang 需要 FlashAttention 2.8.2。Transformers 推理引擎不能与 vLLM 或 SGLang 共用一个环境，因为它们需要不同版本的 transformers。¹服务端调优参数写在一个 YAML 文件里，通过 --backend_config 传入（例如 vLLM 的 gpu-memory-utilization 和 max-num-seqs）。

让产线调用推理服务#

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL(
    vl_rec_backend="vllm-server",      # 或 sglang-server、fastdeploy-server
    vl_rec_server_url="http://localhost:8118/v1",
    vl_rec_max_concurrency=16,         # 根据你的 GPU 调整
)
for res in pipeline.predict("report.pdf"):
    res.save_to_markdown(save_path="output")

paddleocr doc_parser --input report.pdf \
  --vl_rec_backend vllm-server \
  --vl_rec_server_url http://localhost:8118/v1

# 用普通 `vllm serve` 启动的服务（端口 8000）：传入 HF 仓库 ID
paddleocr doc_parser --input report.pdf \
  --vl_rec_backend vllm-server \
  --vl_rec_server_url http://localhost:8000/v1 \
  --vl_rec_api_model_name 'PaddlePaddle/PaddleOCR-VL-1.6'

托管的 VLM 端点用法相同，另加 --vl_rec_api_key。根据文档，SiliconFlow（硅基流动）只提供 v1 和 1.5（请使用 pipeline_version="v1.5"），Novita AI 只提供 v1。¹

完整的 HTTP API#

如果需要一个运行整条产线的 HTTP 接口，文档提供了 Docker Compose 方案（监听 8080 端口）或 paddlex --serve --pipeline PaddleOCR-VL。两者都一次只处理一个请求；需要并发时，文档指向另一套高性能服务化部署（HPS）方案。¹请求格式和客户端见我们的服务化部署与 API 指南（英文）。

官方公布的吞吐量（百度数据）#

百度公布了 PaddleOCR-VL-1.5 在 OmniDocBench v1.5 上的端到端吞吐量（单张 A100，批大小 512）：FastDeploy 2.3 为 1.4335 页/秒，vLLM 0.10.2 为 1.1433，SGLang 0.5.2 为 1.0091。同一张表中，MinerU2.5 在 vLLM 上为 0.9984 页/秒。¹⁰这些表格在仓库中只以图片形式存在，数值由我们转录。1.6 的文档称其推理速度与 1.5 相同。⁹我们没有自己的 GPU 数据。

Apple Silicon、AMD、昇腾及其他硬件#

每种加速硬件都有自己的官方指南，各自注明了一款经过验证的设备：¹¹

Hugging Face 与 Transformers#

模型权重发布在 Hugging Face 上：PaddlePaddle/PaddleOCR-VL、-1.5 和 -1.6，另有一个 GGUF 版本和独立的 PP-DocLayoutV3 版面模型。模型卡中附有一个直接调用 Transformers 的示例，发送一张图片和一个任务提示词，例如 OCR: 或 Table Recognition:；1.5 和 1.6 需要 transformers>=5.0.0。⁴这是元素级识别——适合处理裁剪好的表格或公式，但不是整页解析器。如果要通过 Transformers 处理整篇文档，请保留产线并切换其推理引擎：PaddleOCRVL(engine="transformers")。¹

托管 API（无需 GPU）#

PaddleOCR 3.7.0 自带官方托管服务的客户端，文档解析默认使用 PaddleOCR-VL-1.6。¹³你需要从 AI Studio（飞桨星河社区）获取访问令牌。我们对照 3.7.0 源码核实了代码，但没有实际调用过该服务。

# export PADDLEOCR_ACCESS_TOKEN="..."
from paddleocr import PaddleOCRClient, Model

client = PaddleOCRClient()
result = client.parse_document(
    file_path="report.pdf",
    model=Model.PADDLE_OCR_VL_16,   # 默认值
)
for page in result.pages:
    print(page.markdown_text)
client.close()

export PADDLEOCR_ACCESS_TOKEN="..."
paddleocr api --model_type doc_parsing --file_path report.pdf

AI Studio 的配额页面称，每个用户每个模型每天最多解析 3,000 页，且每个文件只解析前 100 页；异步 API 指南则说单个请求最多支持 1,000 页 PDF。两份官方页面说法不一致，请用自己的文件测试。¹⁴我们能查阅到的页面上都没有公布价格。详细说明、TypeScript 和 Go 的 SDK 以及错误码见我们的 API 页面（英文）。

HPD-Parsing：主打吞吐量的姊妹方案#

HPD-Parsing 于 2026 年 7 月 22 日发布，是一个独立的约 1B 文档 VLM，基于 InternVL3.5-1B 构建，面向大批量解析。它不是把一页解码成一条长 token 序列，而是由一个主版面分支派生出多个内容分支并行解码，并通过渐进式多 token 预测（Progressive Multi-Token Prediction，P-MTP）进一步减少解码步数。¹²

• 精度（官方自报）：在 OmniDocBench v1.6 上综合得分 94.91。HPD-Parsing 不在 OmniDocBench README 的表格中，因此没有独立数据；作为对比，PaddleOCR-VL-1.6 在该表中为 96.34。¹²⁶
• 速度（官方自报）：在 A800 80GB 上使用 vLLM、批大小 512 时为 2.68 页/秒、4,752.1 tokens/秒，自回归基线为 1.02 页/秒。¹²
• 环境要求：NVIDIA GPU（已在 H100、H800、H20、A100、A800、A30、L20、RTX Pro 6000 上验证）、支持 CUDA 12.8+ 的驱动、Linux x86-64、Python 3.10–3.13，以及基于 v0.17.1 的定制 vLLM 构建。它完全不使用 paddleocr 包。¹²

docker run -it --rm --gpus all --network host \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu

服务监听 8118 端口，兼容 OpenAI API；客户端每页都发送固定提示词 document parsing with fork.。¹²如果每 GPU 小时处理的页数比最后一点精度更重要，且你使用的是受支持的数据中心 GPU，选 HPD-Parsing；如果看重精度、更广泛的硬件支持以及 paddleocr 工具链，选 PaddleOCR-VL。

微调#

VLM 可以通过 ERNIEKit 进行监督微调（SFT）；版面模型和阅读顺序模型则不能。¹有一处不一致：v1 算法文档的 FAQ 在一个回答中说微调“not supported”（不支持），在另一个回答中又推荐用 ERNIEKit SFT。以使用教程中的 ERNIEKit 章节为准。

常见问题#