PaddleOCR-VL + vLLM 高性能推理实践：踩坑与调优全记录

1. 背景

PaddleOCR-VL 是一个基于视觉语言模型的 OCR 引擎，支持图像中的文字检测、识别和表格解析。为了提升推理速度，特别是单张图片场景下的响应延迟，我们尝试启用 vLLM 作为其 VLM 后端（enable_hpi=True 或 vl_rec_backend="vllm-server"）。本文记录了从安装到调优的全过程，以及遇到的各种问题和解决方案。

2. 环境信息

• 操作系统：Linux (Ubuntu 20.04)
• GPU：NVIDIA 20GB 显存（如 RTX 4090 或 A4500）
• CUDA 驱动：12.9
• Python 虚拟环境：venv (Python 3.11)

3. 第一阶段：安装 vLLM 并解决 CUDA 版本冲突

3.1 错误现象

安装 vLLM 后运行服务，报错：

ImportError: libcudart.so.13: cannot open shared object file: No such file or directory

3.2 原因分析

• 新版本 vLLM（≥0.20）默认预编译包基于 CUDA 13。
• 但系统环境实际是 CUDA 12.9（nvidia-smi 显示的版本）。
• 即使使用 --extra-index-url https://download.pytorch.org/whl/cu129 安装 PyTorch，vLLM 仍会拉取 CUDA 13 的依赖。

3.3 解决方案

方法一：强制安装 CUDA 12.9 兼容的 vLLM wheel

# 激活虚拟环境
source /home/ps/venv-vllm/bin/activate
# 直接下载指定 wheel
uv pip install "https://github.com/vllm-project/vllm/releases/download/v0.21.0/vllm-0.21.0+cu129-cp38-abi3-manylinux_2_34_x86_64.whl" --torch-backend=cu129

我这里是直接pip install vllm==0.19

第二阶段：PaddleOCR-VL 启用 HPI 失败

错误现象

pipeline = PaddleOCRVL(enable_hpi=True)

报错：

ValueError: Model 'PaddleOCR-VL-1.5-0.9B' does not support engine 'hpi'. Supported engines: ['paddle_dynamic', 'transformers', 'genai_client'].

原因分析
PaddleOCR-VL-1.5-0.9B 是高版本模型，不再支持内置 HPI 引擎。

官方推荐改用外部推理服务（vLLM / SGLang / FastDeploy）作为 VLM 后端。

解决方案

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL(
    vl_rec_backend="vllm-server",
    vl_rec_server_url="http://127.0.0.1:8000"
)

同时需要确保 vLLM 服务端的模型名称与客户端请求一致（见下一阶段）。

第三阶段：vLLM 服务与 PaddleOCR 客户端连接问题

错误现象

Connection error

404 - Not Found

The model 'PaddleOCR-VL-1.5-0.9B' does not exist.

原因分析
vLLM 启动时未指定 --served-model-name，导致对外公开的模型名与客户端请求名不一致。

客户端默认发送模型名 PaddleOCR-VL-1.5-0.9B，而服务端实际名称可能是文件夹名或 HuggingFace 原始名称。

端口不匹配（vLLM 默认 8000，客户端可能写 8080）。

解决方案
启动 vLLM 服务时显式命名

vllm serve /path/to/local/model \
    --served-model-name PaddleOCR-VL-1.5-0.9B \
    --trust-remote-code

客户端配置

pipeline = PaddleOCRVL(
    vl_rec_backend="vllm-server",
    vl_rec_server_url="http://127.0.0.1:8000",
    model="PaddleOCR-VL-1.5-0.9B"   # 与服务端 --served-model-name 一致
)

验证连通性

curl http://127.0.0.1:8000/v1/models

应返回包含 “PaddleOCR-VL-1.5-0.9B” 的模型列表

第四阶段：显存不足与性能调优（单张图片/少量 PPT）

初始显存不足错误

ValueError: Free memory on device cuda:0 (14.34/19.56 GiB) on startup is less than desired GPU memory utilization (0.9, 17.6 GiB).

快速修复：降低显存利用率

vllm serve ... --gpu-memory-utilization 0.6

针对单张图片的低延迟优化
vLLM 默认配置偏向高吞吐批量处理，对单张图片推理不友好。以下配置经过实测，可显著降低首包时间（TTFT）：

vllm serve PaddlePaddle/PaddleOCR-VL-1.5 \
    --trust-remote-code \
    --served-model-name PaddleOCR-VL-1.5-0.9B \
    --max-num-seqs 1 \
    --max-num-batched-tokens 8192 \
    --gpu-memory-utilization 0.6 \
    --mm-processor-cache-gb 1 \
    --mm-processor-kwargs '{"max_pixels": 768*768}' \
    --enable-prefix-caching \
    --enforce-eager \
    --enable-chunked-prefill \
    --max-model-len 8192

参数解读

参数 作用
–max-num-seqs 1 限制并发序列，避免调度开销
–max-num-batched-tokens 8192 降低单批 token 上限，加速首响应
–gpu-memory-utilization 0.6 预留显存，防止 OOM
–mm-processor-cache-gb 1 缓存图像编码结果，避免重复计算
–mm-processor-kwargs ‘{“max_pixels”: 768*768}’ 限制图片最大像素（保留关键信息同时降低开销）
–enable-prefix-caching 复用固定提示词的 KV cache
–enforce-eager 禁用 CUDA graph（多模态场景可能更优）
–enable-chunked-prefill 分块预填充，改善 TTFT
–max-model-len 8192 模型最大序列长度，适合 3 页 PPT
关于 max_model_len 的选型建议（针对 3 页 PPT）
推荐值：8192 —— 留有足够余量，且不会过度消耗显存。

保守值：4096 —— 如果 GPU 显存紧张可尝试，一般也能处理三页 PPT。

调试技巧：启动后查看日志中的 “encoder cache will be initialized with a budget of X tokens”，X 即为实际 token 长度。

为什么不能用多卡并行？
单张图片场景下，张量并行（TP）带来的卡间通信开销远大于计算收益，反而增加延迟。

只有当模型单卡放不下或高并发时，才适合多卡。