paddlepaddle--paddleocr/deploy/paddleocr_vl_docker/hps/README.md

PaddleOCR-VL 高性能服务化部署

English

本目录提供一套支持并发请求处理的 PaddleOCR-VL 系列高性能服务化部署方案，适用于 PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6 等产线版本。

本方案目前暂时只支持 NVIDIA GPU，对其他推理设备的支持仍在完善中。

架构

客户端 → FastAPI 网关 → Triton 服务器 → vLLM 服务器

组件	说明
FastAPI 网关	统一访问入口、简化客户端调用、并发控制
Triton 服务器	版面分析模型（如 PP-DocLayoutV3）及产线串联逻辑，负责模型管理、动态批处理、推理调度
vLLM 服务器	VLM，连续批处理推理

Triton 模型：

模型	设备	说明
layout-parsing	推理设备（如 GPU）	版面解析推理
restructure-pages	CPU	多页结果后处理（跨页表格合并、标题层级重分配）

环境要求

• x64 CPU
• NVIDIA GPU，Compute Capability >= 8.0 且 < 10.0
• NVIDIA 驱动支持 CUDA 12.6
• Docker >= 19.03
• Docker Compose >= 2.0

快速开始

1. 拉取 PaddleOCR 源码并切换到当前目录：

git clone https://github.com/PaddlePaddle/PaddleOCR.git
cd PaddleOCR/deploy/paddleocr_vl_docker/hps

2. 准备必要文件：

cp .env.example .env
# 按需修改 .env 中的 HPS_PIPELINE_NAME
bash prepare.sh

prepare.sh 会根据 .env 下载对应 PaddleOCR-VL 版本的高稳定性服务化部署 SDK，并写入 Triton 产线配置。

3. 启动服务：

docker compose up

上述命令将依次启动 3 个容器：

服务	说明	端口
paddleocr-vl-api	FastAPI 网关（对外入口）	8080
paddleocr-vl-pipeline	运行产线的 Triton 推理服务器	8000（内部）
paddleocr-vlm-server	基于 vLLM 的 VLM 推理服务	8080（内部）

首次启动会自动下载并构建镜像，耗时较长；从第二次启动起将直接使用本地镜像，启动速度更快。

配置说明

环境变量

复制 .env.example 到 .env 并根据需要修改。

cp .env.example .env

除了通过 .env 文件设置，也可以直接设置环境变量，如：

export HPS_MAX_CONCURRENT_INFERENCE_REQUESTS=8

产线与 SDK 配置

通过以下变量选择 PaddleOCR-VL 系列中的具体版本（修改后需重新执行 prepare.sh 并重建镜像）：

本方案复用 PaddleX 的高稳定性服务化部署 SDK 作为 Triton 服务的基础模型仓库与客户端依赖，并在其基础上增加 PaddleOCR-VL 专用的 FastAPI 网关和 vLLM 服务编排。

变量	默认值	说明
HPS_PIPELINE_NAME	PaddleOCR-VL-1.6	产线名称
HPS_PADDLEX_VERSION	3.6	PaddleX 版本（仅填 major.minor，如 3.6），同时决定 Triton 基础镜像标签（paddlex${HPS_PADDLEX_VERSION}-gpu）和 SDK 发布目录（v${HPS_PADDLEX_VERSION}），二者保持一致
HPS_SDK_DIR	paddlex_hps_PaddleOCR-VL-1.6_sdk	解压后的 SDK 目录，遵循 paddlex_hps_${HPS_PIPELINE_NAME}_sdk

常见配置示例：

目标版本	HPS_PIPELINE_NAME	HPS_SDK_DIR
PaddleOCR-VL-1.6	PaddleOCR-VL-1.6	paddlex_hps_PaddleOCR-VL-1.6_sdk
PaddleOCR-VL-1.5	PaddleOCR-VL-1.5	paddlex_hps_PaddleOCR-VL-1.5_sdk
PaddleOCR-VL (v1)	PaddleOCR-VL	paddlex_hps_PaddleOCR-VL_sdk

网关与设备

变量	默认值	说明
HPS_MAX_CONCURRENT_INFERENCE_REQUESTS	16	推理操作（版面解析）最大并发请求数
HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS	64	非推理操作（多页重组）最大并发请求数
HPS_INFERENCE_TIMEOUT	600	请求超时时间（秒）
HPS_HEALTH_CHECK_TIMEOUT	5	健康检查超时时间（秒）
HPS_VLM_URL	http://paddleocr-vlm-server:8080	VLM 服务器地址
HPS_LOG_LEVEL	INFO	日志级别（DEBUG, INFO, WARNING, ERROR）
HPS_FILTER_HEALTH_ACCESS_LOG	true	是否过滤健康检查的访问日志
HPS_UVICORN_WORKERS	4	网关 Worker 进程数
HPS_DEVICE_ID	0	使用的推理设备 ID

产线配置调整

如需调整产线相关配置（如模型路径、批处理大小、部署设备等），请参考 PaddleOCR-VL 使用教程 中的产线配置调整说明章节。

API 使用

文档解析

请参考 PaddleOCR-VL 使用教程 中的客户端调用相关章节。

服务支持 PDF 或图像文件（含 TIFF，多页时按页处理）；多页 TIFF 请使用 fileType=1。

健康检查

# 存活检查
curl http://localhost:8080/health

# 就绪检查（验证 Triton 和 VLM 服务是否已准备好处理请求）
curl http://localhost:8080/health/ready

性能调优

并发设置

网关对推理操作和非推理操作各自独立地进行并发控制：

• HPS_MAX_CONCURRENT_INFERENCE_REQUESTS（默认 16）：控制 layout-parsing（版面解析）等推理操作的并发数
  • 过低（4）：推理设备利用率不足，请求不必要地排队
  • 过高（64）：可能导致 Triton 过载，出现 OOM 或超时
  • 默认值 16 允许在当前批次处理时有足够请求排队形成下一批次
  • 如推理设备资源有限，建议适当降低此值
• HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS（默认 64）：控制 restructure-pages（多页重组）等非推理操作的并发数
  • 非推理操作不占用推理设备资源，可以设置更高的并发数
  • 可根据 CPU 核数和内存情况调整

高吞吐配置示例：

# .env
HPS_MAX_CONCURRENT_INFERENCE_REQUESTS=32
HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS=128
HPS_UVICORN_WORKERS=8

低延迟配置示例：

# .env
HPS_MAX_CONCURRENT_INFERENCE_REQUESTS=8
HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS=32
HPS_INFERENCE_TIMEOUT=300
HPS_UVICORN_WORKERS=2

Worker 进程数

每个 Uvicorn Worker 是独立的进程，有自己的事件循环：

• 1 个 Worker：简单，但受限于单进程
• 4 个 Worker：适合大多数场景
• 8+ 个 Worker：适用于高并发、大量小请求的场景

Triton 动态批处理

Triton 自动将请求批处理以提高推理设备利用率。最大批处理大小通过模型配置文件中的 max_batch_size 参数控制（默认：8），配置文件位于模型仓库目录下的 config.pbtxt（如 model_repo/layout-parsing/config.pbtxt）。

Triton 实例数

每个 Triton 模型的并行推理实例数通过 config.pbtxt 中的 instance_group 配置（默认：1）。增加实例数可以提高并行处理能力，但会占用更多设备资源。

# model_repo/layout-parsing/config.pbtxt
instance_group [
  {
      count: 1       # 实例数，增大可提高并行度
      kind: KIND_GPU
      gpus: [ 0 ]
  }
]

实例数与动态批处理之间存在权衡：

• 单实例（count: 1）：动态批处理会将多个请求合并为一个批次并行执行，但同批次的请求需等待最慢的那个完成后才能一起返回，可能导致部分请求的时延升高。同时，单实例同一时刻只能处理一个批次，当前批次未完成时后续请求只能排队等待。适合显存有限或请求耗时较均匀的场景
• 多实例（count: 2+）：多个实例可以同时各自处理不同的批次，能够同时处理更多请求，减少排队等待时间，单个请求的时延也会有所改善。但需注意，同一实例内的批次仍然遵循动态批处理的行为（批内请求一起开始、一起结束）。每增加一个实例会额外占用一份版面分析模型的显存，同时也会增加对 VLM 推理服务的负载以及内存和 CPU 的使用，需根据推理设备的资源情况酌情设置

非推理模型（如 restructure-pages）运行在 CPU 上，可根据 CPU 核数适当增加实例数。

故障排查与解决

服务无法启动

查看各服务的日志以定位问题：

docker compose logs paddleocr-vl-api
docker compose logs paddleocr-vl-pipeline
docker compose logs paddleocr-vlm-server

常见原因包括端口被占用、推理设备不可用或镜像拉取失败。

超时错误

• 增加 HPS_INFERENCE_TIMEOUT（针对复杂文档）
• 如果推理设备过载，减少 HPS_MAX_CONCURRENT_INFERENCE_REQUESTS

内存/显存不足

• 减少 HPS_MAX_CONCURRENT_INFERENCE_REQUESTS
• 确保每个推理设备只运行一个服务
• 检查 compose.yaml 中的 shm_size（默认：4GB）