modelscope 上PaddleOCR-VL 部署(2026年1月17日亲测可用)

PaddleOCR-VL 部署

创建时间: 2026-01-16

环境: ModelScope PAI-DSW 免费实例

---

环境配置

组件	版本
系统	Ubuntu 22.04
CUDA	12.4.0
Python	3.11.11
PyTorch	2.9.1
cuDNN	1.33.0
CPU	8核
内存	32GB
显存	24GB
剩余额度	13小时30分钟

---

虚拟环境

wget http://qiniu.dywlkj.com/uv_for_linux_x86/install.sh -O - | sh

uv 安装信息

• uv 版本：0.8.22
• 已安装命令：uv 和 uvx

会话管理命令（推荐使用 screen 或 tmux 后台运行）

功能	screen 命令	tmux 命令
新建命名会话	screen -S 名字	tmux new -s 名字
列出所有会话	screen -ls	tmux ls
重新连接会话	screen -r 名字	tmux attach -t 名字
detach（后台运行）	Ctrl+A → D	Ctrl+B → D
退出并关闭会话	exit 或 Ctrl+D	exit 或 Ctrl+D

更换国内镜像源（加速下载）

方法1：临时环境变量（单次生效）

# 使用阿里云镜像源
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
uv pip install [包名]

常用镜像源列表

来源	镜像源
阿里云	https://mirrors.aliyun.com/pypi/simple/
清华大学	https://pypi.tuna.tsinghua.edu.cn/simple/
豆瓣	https://pypi.doubanio.com/simple/
华为云	https://repo.huaweicloud.com/repository/pypi/simple/

示例

wget http://qiniu.dywlkj.com/uv_for_linux_x86/install.sh -O - | sh
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/

or

cat << 'EOF' > uv.toml
[[index]]
name = "aliyun"
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true
EOF

uv pip install modelscope

uv 常用命令

• uv ------ 快速创建虚拟环境、安装包
• uvx ------ 直接运行 Python 工具（如 uvx black）

虚拟环境操作

# 路径
/mnt/workspace/paddleocr-vl/.venv

# 创建命令
mkdir -p /mnt/workspace/paddleocr-vl
cd /mnt/workspace/paddleocr-vl
uv venv --python 3.11

# 激活命令
source .venv/bin/activate

---

PaddleOCR vs PaddleOCR-VL

核心区别

特性	PaddleOCR	PaddleOCR-VL
定位	传统 OCR 工具库	多模态文档理解框架
能力	文本检测+识别	视觉+语言多模态理解
输出	纯文本	结构化数据+问答+理解
架构	CNN + CRNN	Multimodal Transformer (ViT + LLM)
模型	PP-OCR, PP-Structure	NaViT + ERNIE-4.5-0.3B
资源需求	轻量级，CPU可用	需要GPU，较大显存
速度	快	相对较慢
理解能力	文本提取	文档语义理解

联系

PaddleOCR (基础层)
      ↓
      └─> 文本检测/识别能力
           ↓
PaddleOCR-VL (增强层)
      ↓
      └─> 基于PaddleOCR + 多模态大模型
           └─> 文档理解、问答、推理

---

PaddleOCR-VL 核心信息

模型规格

组件	规格
模型名称	PaddleOCR-VL-0.9B
视觉编码器	NaViT 风格动态分辨率
语言模型	ERNIE-4.5-0.3B
多语言支持	109 种语言
识别能力	文本、表格、公式、图表

GitHub & 文档

• GitHub: https://github.com/PaddlePaddle/PaddleOCR-VL
• ModelScope: https://modelscope.cn/models/PaddlePaddle/PaddleOCR-VL

---

安装方案

推荐方案

# 激活环境
source .venv/bin/activate

# 安装 PaddlePaddle-GPU 3.2.0
UV_HTTP_TIMEOUT=3600 uv pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

# 安装 PaddleOCR-VL
UV_HTTP_TIMEOUT=3600 uv pip install -U "paddleocr[doc-parser]"

备选方案（cu126 失败时）

# 使用 cu124 版本
UV_HTTP_TIMEOUT=3600 uv pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu124/
UV_HTTP_TIMEOUT=3600 uv pip install -U "paddleocr[doc-parser]"

验证安装

# 检查 PaddlePaddle 版本和 CUDA 支持
python -c "import paddle; print(paddle.__version__); print(paddle.device.cuda.device_count())"

# 检查 PaddleOCR-VL
python -c "from paddleocr import PaddleOCRVL; print('PaddleOCR-VL installed successfully')"

使用 ModelScope 下载 PaddleOCR-VL 模型

from modelscope import snapshot_download

MODEL_NAME = "PaddlePaddle/PaddleOCR-VL"
MODEL_ID = "PaddleOCR-VL"
SAVE_DIR = f"/mnt/workspace/models/{MODEL_ID}"

if __name__ == "__main__":
    print(f"正在从 ModelScope 下载模型: {MODEL_NAME}")
    print(f"保存目录: {SAVE_DIR}")
    print("-" * 50)

    model_dir = snapshot_download(
        MODEL_NAME,
        cache_dir=SAVE_DIR,
        revision="master",
    )

    print("-" * 50)
    print(f"模型下载完成！")
    print(f"模型路径: {model_dir}")

使用 ModelScope 下载 PP-DocLayoutV2 模型

from modelscope import snapshot_download

MODEL_NAME = "PaddlePaddle/PP-DocLayoutV2"
MODEL_ID = "PP-DocLayoutV2"
SAVE_DIR = f"/mnt/workspace/models/{MODEL_ID}"

if __name__ == "__main__":
    print(f"正在从 ModelScope 下载模型: {MODEL_NAME}")
    print(f"保存目录: {SAVE_DIR}")
    print("-" * 50)

    model_dir = snapshot_download(
        MODEL_NAME,
        cache_dir=SAVE_DIR,
        revision="master",
    )

    print("-" * 50)
    print(f"模型下载完成！")
    print(f"模型路径: {model_dir}")

Key Installation Commands

# Install PaddlePaddle-GPU with CUDA 12.6 support
UV_HTTP_TIMEOUT=3600 uv pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

# Install PaddleOCR-VL with document parser capabilities
UV_HTTP_TIMEOUT=3600 uv pip install -U "paddleocr[doc-parser]"

# Install vLLM server dependencies (for production deployment)
paddleocr install_genai_server_deps vllm

# Install flash-attention for GPU acceleration (from pre-built wheel)
# Check CUDA version first: nvidia-smi | grep "CUDA Version"
pip install https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.3/flash_attn-2.7.3+cu12torch2.8cxx11abiFALSE-cp311-cp311-linux_x86_64.whl

# Or compile from source (if wheel doesn't match your environment)
pip uninstall -y flash_attn
pip install packaging ninja
pip install flash-attn --no-build-isolation

Production Deployment Workflow

Complete Setup Flow (Verified Working)

Step 1: Environment Activation

source .venv/bin/activate

Step 2: Install Dependencies

# Core packages
paddleocr install_genai_server_deps vllm

# Flash-attention (GPU acceleration)
# Download wheel locally first, then install
wget http://qiniu.dywlkj.com/deepseek-ocr-vllm/flash_attn-2.7.3%2Bcu12torch2.8cxx11abiFALSE-cp311-cp311-linux_x86_64.whl 
pip install ./flash_attn-2.7.3+cu12torch2.8cxx11abiFALSE-cp311-cp311-linux_x86_64.whl

# Verify installation
python -c "import flash_attn; print(flash_attn.__version__)"
# Expected output: 2.7.3

Step 3: Start vLLM Server

paddlex_genai_server \
  --model_name PaddleOCR-VL-0.9B \
  --model_dir /mnt/workspace/models/PaddleOCR-VL/PaddlePaddle/PaddleOCR-VL \
  --backend vllm \
  --host 0.0.0.0 \
  --port 8118

Step 4: Verify Server Status

# Check server health
curl http://127.0.0.1:8118/health

# List available models
curl http://127.0.0.1:8118/v1/models

# Expected response:
# {"data":[{"id":"PaddleOCR-VL-0.9B","object":"model",...}],"object":"list"}

PaddleX Layout Parsing API

 paddlex --serve  \
       --pipeline ./config/PaddleOCR-VL.yaml  \
        --host 0.0.0.0   \
        --port 10800 \
        --paddle_model_dir /mnt/workspace/paddleocr-vl