PaddleOCR-VL‑ 是 SOTA 级文档视觉语言模型，在实际落地时常遇到以下痛点：

• 再看环境依赖混乱。不同硬件需要对应的驱动、CUDA、Docker Toolkit，手动搭建极易出错。
• 再看显存占用高。模型约 10 GB/6 GB，在资源受限的机器上容易 OOM。
• 部署方式多样。却缺乏“一键”指引，导致研发和运维团队反复踩坑。
• 版本不匹配的观点是，Compute Capability、CUDA 与 PaddleOCR‑VL 的要求不一致时推理服务启动失败。

下面提供两种主流部署方案。并针对上述痛点给出详细的解决步骤，让你快速跑通 PaddleOCR‑VL 推理服务。老实说，

概览

• 主页：
• 代码：
• 文档：

官方支持一键部署多种硬件后端。并可无缝集成 Dify、RAGFlow、Pathway 和 Cherry Studio。按理说，

部署方式对比

• 官方 Docker 方式官方推荐看看。以最大程度避免环境冲突，适合需要 vLLM 推理的场景。
• 社区 ONNX 方式基于 Python 环境的推理，脱离 Paddle 官方工程依赖；怎么说呢，适合已有 ONNX 基础设施或想自行定制推理栈的使用者。

Docker 方式部署

至于前置条件。准备 Docker 环境

如果本机尚未安装 Docker，请先完成以下步骤；已装好则直接进入容器启动。

1️⃣ 安装 Docker Engine 与 Compose

$ docker -v
Docker version 24.0.5,build abcdefg
$ docker compose version
Docker Compose version v5.0.2

2️⃣ 添加当前使用者至 docker 组

# 创建 docker 组
sudo groupadd docker
# 将当前使用者加入 docker 组
sudo usermod -aG docker $USER
# 重新加载组信息
newgrp docker

3️⃣ 安装 NVIDIA Container Toolkit

# 安装工具链
distribution=$
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
# 重启 Docker 服务并验证
sudo systemctl restart docker
docker run --rm --gpus all nvidia/cuda:12.1-base nvidia-smi

启动 PaddleOCR‑VL 推理服务

确保机器满足 Compute Capability ≥ 8.0 且 CUDA ≥ 12.0否则可能出现兼容性错误。 怎么说呢，

docker run -it --rm \
--gpus all \
--network host \
paddleocr genai_server \
--model_name PaddleOCR-VL-.9B \
--host 0.0.0.0 \
--port 9000 \
--backend vllm

启动日志示例：

 INFO - :: Starting vLLM API server on http://0.0.0.0:9000/v1...
INFO的观点是，Started server process
再看INFO，Waiting for application startup.
INFO这方面，Application startup complete.
INFO的观点是。GET /health HTTP/1.1" 200 OK
paddleocr INFO: The PaddleOCR GenAI server has been started.
You can eir:
• Set server URL in your pipeline and call PaddleOCR CLI or Python API,e.g.
paddleocr doc_parser --input demo.png \
--vl_rec_backend vllm-server \
--vl_rec_server_url http://localhost:9000/v1
• Make raw HTTP requests directly or via OpenAI compatible client libraries.

显存占用约为 10 GB请预留足够显存或使用模型并行 / 分片技术。

更多资源

ONNX 方式部署

前置条件的观点是。Conda 环境准备

If you don’t have a Conda environment yet,follow steps below;orwise jump straight to model preparation.

1️⃣ 安装 Miniconda 并配置国内镜像源

# 下载并安装 Miniconda
curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh # 按提示全部 yes
# 配置清华镜像。加速 pip 安装
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/

2️⃣ 创建专属虚拟环境并激活

conda create -n ppocr python=3.10 -y
conda activate ppocr

准备 ONNX 项目代码

git clone --depth 1 https://github.com/devymex/paddleocr-vl-green.git
cd paddleocr-vl-green
# 修改 requirements.txt：注释掉 onnxruntime，打开 onnxruntime-gpu，以使用 GPU 加速。sed -i 's/^onnxruntime$/# onnxruntime/' requirements.txt
sed -i 's/^# onnxruntime-gpu$/onnxruntime-gpu/' requirements.txt
pip install -r requirements.txt

下载模型文件至 /ppocr/​

• 再看版面检测模型，pp_doclayoutv3.onnx
• 朝向检测模型的观点是。pp_lcnet_doc_ori.onnx
• PaddleOCR‑VL 主模型：
  1. A1： 使用 HuggingFace CLI

     
     unset http_proxy https_proxy all_proxy # 防止代理冲突
     huggingface-cli download PaddlePaddle/PaddleOCR-VL-.9B \
     --local-dir ppocr/paddleocr-vl-
     

  2. A2： 使用 Git LFS

     
     git lfs install
     git clone https://huggingface.co/PaddlePaddle/PaddleOCR-VL-.9B \
     ppocr/paddleocr-vl-
     

启动 ONNX 推理服务

CUDA_VISIBLE_DEVICES=0 python -m scripts.server \
--model-path ppocr/paddleocr-vl- \
--layout-onnx ppocr/pp_doclayoutv3.onnx \
--orientation-onnx ppocr/pp_lcnet_doc_ori.onnx \
--device cuda:0 \
--port 9001

显存占用约为 6 GB**，相较 Docker 模式节省约40%显存**，但需要自行保证 onnxruntime‑gpu 与 CUDA 的兼容性。

测试推理接口

import base64,json。requests

with open as f: img_b64 = base64.b64encode).decode

payload = { "image": f"data:image/jpeg;base64,{img_b64}","format": "json","layout": True,"orientation": True,}

url = "http://127.0.0.1:9001/process" resp = requests.post

print print,indent=2。ensureascii=False)) """ Expected response : { "blocks": } """ """