PaddleOCR-VL 使用指南

简介

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

安装 vLLM

uv venv
source .venv/bin/activate
# Until v0.11.1 release, you need to install vLLM from nightly build
uv pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly --extra-index-url https://download.pytorch.org/whl/cu129 --index-strategy unsafe-best-match

部署 PaddleOCR-VL

vllm serve PaddlePaddle/PaddleOCR-VL \
    --trust-remote-code \
    --max-num-batched-tokens 16384 \
    --no-enable-prefix-caching \
    --mm-processor-cache-gb 0

使用 OpenAI API 客户端查询

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="https://: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="PaddlePaddle/PaddleOCR-VL",
    messages=messages,
    temperature=0.0,
)
print(f"Generated text: {response.choices[0].message.content}")

使用 vLLM 结合 PP-DocLayoutV2 进行离线推理

在上面的示例中，我们演示了使用 vLLM 进行 PaddleOCR-VL 的推理。通常，我们还需要集成 PP-DocLayoutV2 模型来充分释放 PaddleOCR-VL 模型的强大能力，使其更符合 PaddlePaddle 官方提供的示例。

提示

为 vllm 和 paddlepaddle 使用独立的虚拟环境，以避免依赖冲突。如果遇到 The model PaddleOCR-VL-0.9B does not exist. 错误，请在 vLLM 启动命令中添加 --served-model-name PaddleOCR-VL-0.9B。

安装 PaddlePaddle 和 PaddleOCR

uv pip install paddlepaddle-gpu==3.2.1 --extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu126/
uv pip install -U "paddleocr[doc-parser]"
uv pip install safetensors

使用 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="https://:8000/v1", 
                       layout_detection_model_name="PP-DocLayoutV2",  
                       layout_detection_model_dir=doclayout_model_path)

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")

配置技巧

• 与多轮聊天用例不同，我们不期望 OCR 任务能从前缀缓存或图像重用中显著受益，因此建议关闭这些功能以避免不必要的哈希和缓存。
• 根据您的硬件能力，调整 max_num_batched_tokens 以获得更好的吞吐量性能。
• 请查看官方 PaddleOCR-VL 文档，了解更多关于使用该模型进行各种文档解析任务的详细信息和示例。