PaddleOCR-VL 高性能服务化部署HPSFastAPI 网关 Triton vLLM 的三容器并发推理方案【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR本文基于 PaddleOCR 仓库中 deploy/paddleocr_vl_docker/hps/README.md 撰写系统讲解 PaddleOCR-VL 系列模型PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6的高稳定性服务化部署High Performance ServingHPS方案三容器架构的组成与职责、Docker Compose 启动流程、全部环境变量配置项、Triton 动态批处理与实例数的调优权衡以及故障排查方法。读完本文你可以直接在 NVIDIA GPU 机器上拉起一套支持并发请求处理的 PaddleOCR-VL 文档解析服务并针对吞吐或时延目标调整并发、Worker 数与 Triton 批处理参数。注意该方案目前只支持 NVIDIA GPU对其他推理设备的支持仍在完善中环境要求为 x64 CPU、Compute Capability 8.0 且 10.0 的 NVIDIA GPU即 A 系/RTX 系等 Ampere 及以上架构Blackwell 等 sm_120 平台需另行查阅 docs/version3.x/pipeline_usage/PaddleOCR-VL-NVIDIA-Blackwell.md、支持 CUDA 12.6 的 NVIDIA 驱动、Docker 19.03、Docker Compose 2.0。架构三个容器各司其职HPS 方案的请求链路为客户端 → FastAPI 网关 → Triton 服务器 → vLLM 服务器组件说明FastAPI 网关统一访问入口、简化客户端调用、并发控制Triton 服务器运行版面分析模型如 PP-DocLayoutV3及产线串联逻辑负责模型管理、动态批处理、推理调度vLLM 服务器承载 VLM视觉语言模型进行连续批处理推理Triton 服务器内部注册了两个模型模型设备说明layout-parsing推理设备如 GPU版面解析推理restructure-pagesCPU多页结果后处理跨页表格合并、标题层级重分配这个双模型设计是理解整套并发控制策略的钥匙版面解析是占用 GPU 的重推理操作而多页重组是纯 CPU 的轻量后处理二者对资源的需求完全不同因此网关对它们采用独立的两套并发上限详见后文性能调优。从源码结构看方案对 PaddleX 高稳定性服务化部署 SDK 的复用关系在 prepare.sh 中有清晰体现该脚本从 PaddleX 的发布目录下载对应版本的 SDK 压缩包并解压SDK 提供 Triton 服务的基础模型仓库server/目录与 Python 客户端依赖client/目录而 PaddleOCR 在此之上增加了专用的 FastAPI 网关和 vLLM 服务编排。三个容器与依赖顺序compose.yaml 定义了三个服务及其启动依赖关系depends_oncondition: service_healthy即前序服务健康检查通过后才会启动后序服务服务说明端口paddleocr-vl-apiFastAPI 网关对外入口8080paddleocr-vl-pipeline运行产线的 Triton 推理服务器8000内部 HTTP 健康检查、8001内部 gRPC供网关调用paddleocr-vlm-server基于 vLLM 的 VLM 推理服务8080内部不对外发布几个值得注意的编排细节均可在 compose.yaml 中核对paddleocr-vlm-server使用官方镜像paddleocr-genai-vllm-server:latest-nvidia-gpu将 SDK 中的pipeline_config.yaml与 genai_server_entrypoint.sh 以只读方式挂载进容器paddleocr-vl-pipeline与paddleocr-vlm-server均通过deploy.resources.reservations.devices绑定同一张 GPUdevice_ids由HPS_DEVICE_ID指定默认 0即版面分析模型与 VLM 共享同一块推理卡paddleocr-vl-pipeline设置了shm_size: 4gb用于 Triton 进程间共享内存三个服务都配置了healthcheckcurl 探测间隔 10 秒其中 VLM 服务的start_period设为 300 秒VLM 加载耗时较长Triton 为 60 秒。VLM 服务容器的入口脚本 genai_server_entrypoint.sh 会先从挂载的pipeline_config.yaml中解析vl_recognition模块对应的model_name然后执行paddleocr genai_server \ --model_name $VLM_NAME \ --host 0.0.0.0 \ --port 8080 \ --backend vllm即 vLLM 后端由 PaddleOCR 的genai_server命令统一拉起网关侧则通过HPS_VLM_URL访问它。快速开始拉取 PaddleOCR 源码并切换到部署目录git clone https://gitcode.com/GitHub_Trending/pa/PaddleOCR cd PaddleOCR/deploy/paddleocr_vl_docker/hps准备必要文件cp .env.example .env # 按需修改 .env 中的 HPS_PIPELINE_NAME bash prepare.sh启动服务docker compose up首次启动会自动下载并构建镜像耗时较长从第二次启动起将直接使用本地镜像启动速度更快。prepare.sh 具体做了什么prepare.sh 是连接选择哪个版本与容器内容的关键脚本其执行逻辑如下读取.env如存在并以环境变量形式生效随后对未设置的变量回落到默认值HPS_PIPELINE_NAME默认PaddleOCR-VL-1.6、HPS_PADDLEX_VERSION默认3.6、HPS_SDK_DIR默认paddlex_hps_${HPS_PIPELINE_NAME}_sdk、HPS_VLM_URL默认http://paddleocr-vlm-server:8080从 PaddleX 的 SDK 发布目录按v${HPS_PADDLEX_VERSION}版本号下载paddlex_hps_${HPS_PIPELINE_NAME}_sdk.tar.gz并解压检查 SDK 内server/pipeline_config.yaml若vl_recognition模块配置为backend: native则改写为backend: vllm-server并写入server_url: ${HPS_VLM_URL%/}/v1——这一步把 VLM 推理从进程内原生推理切换为外挂独立 vLLM 服务从pipeline_config.yaml中提取 VLM 模型名校验失败则直接报错退出将最终确定的HPS_PIPELINE_NAME、HPS_SDK_DIR、HPS_VLM_URL回写进.env保证后续docker compose up时构建参数与实际下载的 SDK 目录一致。因此修改产线版本后必须重新执行prepare.sh并重建镜像例如docker compose build --no-cache后重新docker compose up。两个镜像的构建内容网关镜像 gateway.Dockerfile基于python:3.10-slim拷贝 gateway/ 应用代码并通过 build 参数HPS_SDK_DIR把 SDK 的client/目录绑定进构建上下文安装requirements.txt、SDK 客户端依赖以及paddlex_hps_client-*.whl客户端包容器最终以uvicorn --host 0.0.0.0 --port 8080 --workers ${HPS_UVICORN_WORKERS} app:app启动。产线镜像 pipeline.Dockerfile以paddlex/hps:paddlex${HPS_PADDLEX_VERSION}-gpu为基座镜像把 SDK 的server/目录拷入/app并执行server.sh启动 Triton。两个镜像都通过HPS_SDK_DIR构建参数引用同一个 SDK 目录这就是HPS_SDK_DIR必须与HPS_PIPELINE_NAME严格对应paddlex_hps_${HPS_PIPELINE_NAME}_sdk的原因——目录名对不上构建阶段就会找不到 SDK 文件。配置说明环境变量全表复制 .env.example 为.env后按需修改cp .env.example .env除了通过.env文件设置也可以直接设置环境变量如export HPS_MAX_CONCURRENT_INFERENCE_REQUESTS8产线与 SDK 配置以下变量决定使用 PaddleOCR-VL 系列中的哪个版本修改后需重新执行prepare.sh并重建镜像变量默认值说明HPS_PIPELINE_NAMEPaddleOCR-VL-1.6产线名称HPS_PADDLEX_VERSION3.6PaddleX 版本仅填 major.minor如3.6同时决定 Triton 基础镜像标签paddlex${HPS_PADDLEX_VERSION}-gpu和 SDK 发布目录v${HPS_PADDLEX_VERSION}二者保持一致HPS_SDK_DIRpaddlex_hps_PaddleOCR-VL-1.6_sdk解压后的 SDK 目录须遵循paddlex_hps_${HPS_PIPELINE_NAME}_sdk常见配置示例目标版本HPS_PIPELINE_NAMEHPS_SDK_DIRPaddleOCR-VL-1.6PaddleOCR-VL-1.6paddlex_hps_PaddleOCR-VL-1.6_sdkPaddleOCR-VL-1.5PaddleOCR-VL-1.5paddlex_hps_PaddleOCR-VL-1.5_sdkPaddleOCR-VL (v1)PaddleOCR-VLpaddlex_hps_PaddleOCR-VL_sdkHPS_PADDLEX_VERSION的双向一致性体现在 compose.yaml 中它既是paddleocr-vl-pipeline的基座镜像标签.../hps:paddlex3.6-gpu也是prepare.sh下载 SDK 时使用的发布目录v3.6保证 Triton 基础镜像与 SDK 版本配套。网关与设备配置变量默认值说明HPS_MAX_CONCURRENT_INFERENCE_REQUESTS16推理操作版面解析最大并发请求数HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS64非推理操作多页重组最大并发请求数HPS_INFERENCE_TIMEOUT600请求超时时间秒HPS_HEALTH_CHECK_TIMEOUT5健康检查超时时间秒HPS_VLM_URLhttp://paddleocr-vlm-server:8080VLM 服务器地址HPS_LOG_LEVELINFO日志级别DEBUG, INFO, WARNING, ERRORHPS_FILTER_HEALTH_ACCESS_LOGtrue是否过滤健康检查的访问日志HPS_UVICORN_WORKERS4网关 Worker 进程数HPS_DEVICE_ID0使用的推理设备 ID这些变量的真实消费点在网关 gateway/app.py 中可以逐一核对启动时通过os.getenv读取如HPS_TRITON_URL、HPS_MAX_CONCURRENT_INFERENCE_REQUESTS、HPS_INFERENCE_TIMEOUT等其中两个并发上限分别初始化为独立的asyncio.Semaphore见 app.py#L107-L119并在生命周期结束时关闭 Triton gRPC 异步客户端。HPS_FILTER_HEALTH_ACCESS_LOG的实现是给uvicorn.access日志器挂一个过滤/health字样的logging.Filter避免探针请求刷满访问日志。.env.example中还给出了 Worker 数的经验值注释每 CPU 核心建议 2~4 个 Worker。产线配置调整如需调整产线相关配置如模型路径、批处理大小、部署设备等请参考 PaddleOCR-VL 使用教程 中的产线配置调整说明章节。在 HPS 方案中产线配置即 SDK 内的${HPS_SDK_DIR}/server/pipeline_config.yaml——prepare.sh的backend改写和 VLM 服务入口的模型名解析都基于该文件vLLM 服务容器也将其只读挂载到/config/pipeline_config.yaml。API 使用文档解析请参考 PaddleOCR-VL 使用教程 中的客户端调用相关章节。服务支持 PDF 或图像文件含 TIFF多页时按页处理多页 TIFF 请使用fileType1。从网关源码看客户端实际面对的是两个 POST 端点见 gateway/app.pyPOST /layout-parsing版面解析推理受推理信号量默认 16 并发约束POST /restructure-pages多页重组后处理受非推理信号量默认 64 并发约束。请求体为 JSON网关会为其补充/沿用logId用于日志串联并调用 SDK 提供的triton_request_async转发到对应 Triton 模型。响应采用 AIStudio 标准格式logId/errorCode/errorMsg 结果数据下游Triton返回的errorCode非 0 时网关原样透传该错误码作为 HTTP 状态码JSON 解析失败返回 400参数校验失败返回 422推理超时含 gRPC 层 Deadline Exceeded返回 504Triton 未就绪或模型未加载返回 503其余异常返回 500。健康检查# 存活检查 curl http://localhost:8080/health # 就绪检查验证 Triton 和 VLM 服务是否已准备好处理请求 curl http://localhost:8080/health/ready/health只表示网关进程存活/health/ready则做完整链路探测见 app.py#L159-L218依次检查 Triton 服务器is_server_ready()、两个模型layout-parsing与restructure-pages的is_model_ready()最后请求 VLM 服务的/health端点任何一环不通过即返回 503 并说明具体原因如Model layout-parsing not ready单项检查超时由HPS_HEALTH_CHECK_TIMEOUT控制。这个端点适合作为负载均衡或 K8s 的就绪探针。性能调优并发设置网关对推理操作和非推理操作各自独立地进行并发控制两个独立信号量见前文源码分析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_REQUESTS32 HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS128 HPS_UVICORN_WORKERS8低延迟配置示例# .env HPS_MAX_CONCURRENT_INFERENCE_REQUESTS8 HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS32 HPS_INFERENCE_TIMEOUT300 HPS_UVICORN_WORKERS2Worker 进程数每个 Uvicorn Worker 是独立的进程有自己的事件循环gateway.Dockerfile 中以 shell 形式展开--workers ${HPS_UVICORN_WORKERS}1 个 Worker简单但受限于单进程4 个 Worker适合大多数场景8 个 Worker适用于高并发、大量小请求的场景。需要注意的是每个 Worker 进程都会各自维护到 Triton 的 gRPC 连接和独立信号量因此 Worker 数影响的是网关侧的连接与事件循环规模而不是 Triton 侧的批处理能力。Triton 动态批处理Triton 自动将请求批处理以提高推理设备利用率。最大批处理大小通过模型配置文件中的max_batch_size参数控制默认8配置文件位于模型仓库目录下的config.pbtxt如model_repo/layout-parsing/config.pbtxt该文件随 SDK 的server/目录提供并经由 pipeline.Dockerfile 的COPY ${HPS_SDK_DIR}/server .进入容器。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常见原因包括端口被占用、推理设备不可用或镜像拉取失败。结合编排细节排查时可留意两点一是paddleocr-vl-api依赖paddleocr-vl-pipeline健康、paddleocr-vl-pipeline依赖paddleocr-vlm-server健康VLM 容器start_period为 300 秒加载期内的探针失败属正常现象二是 prepare.sh 若无法从pipeline_config.yaml解析出 VLM 模型名会直接以非零码退出此时.env不会完成回写需要检查 SDK 是否下载完整。超时错误增加HPS_INFERENCE_TIMEOUT针对复杂文档如果推理设备过载减少HPS_MAX_CONCURRENT_INFERENCE_REQUESTS。对应到网关行为超时既包括triton_request_async抛出的asyncio.TimeoutError也包括 gRPC 的 Deadline Exceeded 异常两者统一映射为 504 Gateway timeout 响应。内存/显存不足减少HPS_MAX_CONCURRENT_INFERENCE_REQUESTS确保每个推理设备只运行一个服务本方案中版面解析与 VLM 默认共同绑定HPS_DEVICE_ID指定的同一张卡多实例instance_group会进一步放大显存占用显存紧张时应优先回调实例数与推理并发检查 compose.yaml 中的shm_size默认4GB见 compose.yaml#L48。小结PaddleOCR 的 HPS 部署方案把文档解析服务拆分为网关—产线—VLM三层FastAPI 网关负责统一入口与分级并发控制Triton 承载版面分析与跨页后处理两个模型并通过动态批处理提升 GPU 利用率vLLM 独立容器专注 VLM 连续批处理推理。版本选择、SDK 下载与产线改写收敛在prepare.sh一个入口中全部运行时行为由.env中一组带明确默认值的HPS_*变量驱动在此基础上按吞吐/时延目标调整推理并发、Worker 数、max_batch_size与instance_group即可在不同显存与并发规模下获得可预期的服务能力。若需扩展到其他硬件平台可参考同目录 accelerators/ 下各加速器的适配说明。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考