PaddleOCR-VL

1 简介

PaddleOCR-VL 是一个专为文档解析设计的 SOTA 且资源高效的模型。其核心组件是 PaddleOCR-VL-0.9B，一个紧凑而强大的视觉语言模型（VLM），它集成了 NaViT 风格的动态分辨率视觉编码器与 ERNIE-4.5-0.3B 语言模型，以实现精确的元素识别。

本文档提供了模型完整部署和验证的详细工作流程，包括支持的特性、环境准备、单节点部署和功能验证。旨在帮助用户快速完成模型部署和验证。

本文档基于 vLLM-Ascend v0.21.0rc1 进行验证和编写。当前模型（PaddleOCR-VL）在此版本中得到支持。建议使用此版本或其他更新的官方版本进行部署。

2 支持的特性

请参考支持的特性获取模型支持的特性矩阵。

请参考特性指南获取特性的配置。

3 前提条件

3.1 模型权重

• PaddleOCR-VL-0.9B：PaddleOCR-VL-0.9B

建议将模型权重下载到缓存目录，并设置 VLLM_USE_MODELSCOPE=True 以自动加载模型。如果您已将权重下载到本地目录，请相应更新部署脚本中的 MODEL_PATH 变量。

4 安装

4.1 Docker 镜像安装

您可以直接使用我们的官方 Docker 镜像来运行 PaddleOCR-VL。

根据您的机器类型选择镜像，并在节点上启动 Docker 镜像，请参考使用 Docker。

A2 系列Atlas 300 推理产品

export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1
docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --net=host \
    --device /dev/davinci0 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-310p
docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --net=host \
    --device /dev/davinci0 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

Docker 运行成功后，您可以通过执行 docker ps 命令来验证正在运行的容器服务。

4.2 源码安装

如果您不想像上面那样使用 Docker 镜像，也可以从源码构建所有内容：

• 从源码安装 vllm-ascend，请参考安装。

Note

如果您使用的是 Atlas 300 推理产品，可能需要卸载 triton-ascend 以避免依赖冲突。

5 在线服务部署

5.1 单节点在线部署

PaddleOCR-VL 支持在 A2 系列和 Atlas 300 推理产品平台上进行单节点单卡部署。单节点部署在同一节点内完成 Prefill 和 Decode。

按照以下步骤启动推理服务：

1. 准备模型权重：确保模型权重可访问。设置 VLLM_USE_MODELSCOPE=True 后，模型将从 ModelScope 自动加载。
2. 设置 MODEL_PATH 环境变量指向您的模型目录。
3. 创建并执行部署脚本（保存为 deploy.sh）。

启动命令：

A2 系列Atlas 300 推理产品

#!/bin/sh
export VLLM_USE_MODELSCOPE=True
export MODEL_PATH="PaddlePaddle/PaddleOCR-VL"
export TASK_QUEUE_ENABLE=1
export CPU_AFFINITY_CONF=1
export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"

vllm serve ${MODEL_PATH} \
          --max-num-batched-tokens 16384 \
          --served-model-name PaddleOCR-VL-0.9B \
          --trust-remote-code \
          --no-enable-prefix-caching \
          --mm-processor-cache-gb 0 \
          --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
          --additional_config '{"enable_cpu_binding":true}' \
          --port 8000

#!/bin/sh
export VLLM_USE_MODELSCOPE=True
export MODEL_PATH="PaddlePaddle/PaddleOCR-VL"
export TASK_QUEUE_ENABLE=1
export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"

vllm serve ${MODEL_PATH} \
          --max_model_len 16384 \
          --served-model-name PaddleOCR-VL-0.9B \
          --trust-remote-code \
          --no-enable-prefix-caching \
          --mm-processor-cache-gb 0 \
          --dtype float16 \
          --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
          --additional_config '{"ascend_compilation_config": {"fuse_norm_quant": false}, "enable_cpu_binding":true}' \
          --port 8000

Note

在 Atlas 300 推理产品上：

• 仅支持 float16 数据类型。
• 添加了 --max_model_len 选项以防止生成注意力算子掩码时出错。
• 图编译（--compilation-config）需要 CANN 版本 >= 9.0.0。如果您的 CANN 版本较低，请通过将 --compilation-config 参数替换为 --enforce-eager 来恢复到 eager 模式。
• fuse_norm_quant 中的 --additional_config 选项被禁用（false），因为此硬件上的图编译不支持该选项。请保持此设置不变。

关键参数说明：

• --max-num-batched-tokens 指定单次前向传播中批处理的最大 token 数量。调整此参数以优化吞吐量。
• --max_model_len 指定最大上下文长度——即单个请求的输入和输出 token 之和。
• --no-enable-prefix-caching 表示禁用前缀缓存。要启用它，请移除此选项。
• --mm-processor-cache-gb 设置多模态处理器缓存的大小（以 GB 为单位）。值为 0 表示禁用缓存。
• --dtype float16 指定模型数据类型。在 Atlas 300 推理产品上，仅支持 float16。
• --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' 启用完整解码图编译以提高性能。在 Atlas 300 推理产品上，fuse_norm_quant 中默认禁用了图编译的 --additional_config。
• --additional_config '{"enable_cpu_binding":true}' 启用 CPU 绑定以提高性能。

常见问题提示：如果遇到启动问题，请参考公共 FAQ 进行故障排除。

5.2 多节点 PD 分离部署

暂不支持。

5.3 特殊部署模式

5.3.1 使用 vLLM 和 PP-DocLayoutV2 进行离线推理

在上面的示例中，我们演示了如何使用 vLLM 推理 PaddleOCR-VL-0.9B 模型。通常，我们还需要集成 PP-DocLayoutV2 模型，以充分发挥 PaddleOCR-VL 模型的能力，使其更符合官方 PaddlePaddle 文档提供的示例。

Note

为 VLLM 和 PP-DocLayoutV2 使用独立的虚拟环境，以避免依赖冲突。

A2 系列Atlas 300 推理产品

A2 系列设备支持使用 PaddlePaddle 框架进行推理。

1. 拉取兼容 PaddlePaddle 的 CANN 镜像

   docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann800-ubuntu20-npu-910b-base-aarch64-gcc84
   

   使用以下命令启动容器：

   docker run -it --name paddle-npu-dev -v $(pwd):/work \
       --privileged --network=host --shm-size=128G -w=/work \
       -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
       -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
       -v /usr/local/dcmi:/usr/local/dcmi \
       -e ASCEND_RT_VISIBLE_DEVICES="0,1,2,3,4,5,6,7" \
       ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann800-ubuntu20-npu-910b-base-$(uname -m)-gcc84 /bin/bash
   

2. 安装 PaddlePaddle 和 PaddleOCR

   python -m pip install paddlepaddle==3.2.0
   wget https://paddle-whl.bj.bcebos.com/stable/npu/paddle-custom-npu/paddle_custom_npu-3.2.0-cp310-cp310-linux_aarch64.whl
   pip  install  paddle_custom_npu-3.2.0-cp310-cp310-linux_aarch64.whl
   python -m pip install -U "paddleocr[doc-parser]"
   pip install safetensors
   

   Note

   可能缺少 OpenCV 组件：
   
   ```bash
   apt-get update
   apt-get install -y libgl1 libglib2.0-0
   ```
   
   CANN-8.0.0 不支持某些版本的 NumPy 和 OpenCV。建议安装指定版本。
   
   ```bash
   python -m pip install numpy==1.26.4
   python -m pip install opencv-python==3.4.18.65
   ```
   

Atlas 300 推理产品仅支持 OM 模型推理。有关过程的详细信息，请参阅 ModelZoo 中提供的指南。

5.3.2 使用 vLLM 作为后端，结合 PP-DocLayoutV2 进行离线推理

from paddleocr import PaddleOCRVL

doclayout_model_path = "/path/to/your/PP-DocLayoutV2/"

pipeline = PaddleOCRVL(vl_rec_backend="vllm-server", 
                       vl_rec_server_url="http://localhost:8000/v1", 
                       layout_detection_model_name="PP-DocLayoutV2",  
                       layout_detection_model_dir=doclayout_model_path,
                       device="npu")

output = pipeline.predict("https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png")

for i, res in enumerate(output):
    res.save_to_json(save_path=f"output_{i}.json")
    res.save_to_markdown(save_path=f"output_{i}.md")

6 功能验证

如果您的服务启动成功，您将看到如下信息：

INFO:     Started server process [87471]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

服务器启动后，您可以使用 OpenAI API 客户端进行查询。

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1",
    timeout=3600
)

# Task-specific base prompts
TASKS = {
    "ocr": "OCR:",
    "table": "Table Recognition:",
    "formula": "Formula Recognition:",
    "chart": "Chart Recognition:",
}

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png"
                }
            },
            {
                "type": "text",
                "text": TASKS["ocr"]
            }
        ]
    }
]

response = client.chat.completions.create(
    model="PaddleOCR-VL-0.9B",
    messages=messages,
    temperature=0.0,
)
print(f"Generated text: {response.choices[0].message.content}")

预期结果：

如果您成功查询服务器，您将看到如下信息（客户端）：

Generated text: CINNAMON SUGAR
1 x 17,000
17,000
SUB TOTAL
17,000
GRAND TOTAL
17,000
CASH IDR
20,000
CHANGE DUE
3,000

7 精度评估

关于 PaddleOCR-VL 的精度评估，请参考官方 ModelZoo 中的评估流程和结果。

8 性能评估

关于 PaddleOCR-VL 的性能评估，请参考官方 ModelZoo 中的基准测试方法和结果。

9 性能调优

9.1 推荐配置

注意：以下配置在特定测试环境中验证，仅供参考。最佳配置取决于最大输入/输出长度、精度要求和实际硬件规格等因素。建议参考第 9.2 节根据实际情况进行调优。

PaddleOCR-VL 是一个轻量级模型，运行在单个 NPU 上。关键调优参数因硬件平台而异。

表 1：场景概览

场景	硬件	*NPU总数	权重版本	关键考量
高吞吐量	A2系列	1	PaddleOCR-VL-0.9B	-
高吞吐量	Atlas 300推理产品	1	PaddleOCR-VL-0.9B	图编译需要 CANN >= 9.0.0

*Total NPUs 表示所有节点使用的 NPU 总数。

表 2：详细节点配置

场景	配置	NPU数	TP	DP	最大模型长度	最大批处理Token数	图编译	dtype
High Throughput	A2 series / Single Machine	1	—	—	—	16384	FULL_DECODE_ONLY	bfloat16 (default)
High Throughput	Atlas 300 inference products / Single Machine	1	—	—	16384	—	FULL_DECODE_ONLY; otherwise enforce-eager	float16

完整的启动命令和参数说明，请参考 第 5.1 节 中的部署示例。

9.2 调优指南

9.2.1 通用调优参考

关于性能调优，请参考公共性能调优文档中的通用调优方法，包括操作系统优化 (jemalloc, tcmalloc)、torch_npu 优化（内存和调度）以及 CANN 优化。

详细的功能描述请参考功能指南。

10 常见问题

关于常见的环境、安装和通用参数问题，请参考公共 FAQ；本章仅涵盖模型特定问题。

• 问：Atlas 300 推理产品的部署要求是什么？

答：在 Atlas 300 推理产品上，仅支持 float16 数据类型。图编译 (--compilation-config) 需要 CANN 版本 >= 9.0.0；如果您的 CANN 版本较低，请改用 --enforce-eager。

• 问：在 Atlas 300 推理产品上安装时遇到依赖冲突怎么办？

答：您可能需要卸载 triton-ascend 以避免依赖冲突。详见第 4.2 节。