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分钟 |
虚拟环境
wgethttp://qiniu.dywlkj.com/uv_for_linux_x86/install.sh -O -|shuv 安装信息
- 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：临时环境变量（单次生效）
# 使用阿里云镜像源exportUV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ uv pipinstall[包名]常用镜像源列表
| 来源 | 镜像源 |
|---|---|
| 阿里云 | 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/ |
示例
wgethttp://qiniu.dywlkj.com/uv_for_linux_x86/install.sh -O -|shexportUV_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 EOFuv pipinstallmodelscopeuv 常用命令
uv—— 快速创建虚拟环境、安装包uvx—— 直接运行 Python 工具（如uvx black）
虚拟环境操作
# 路径/mnt/workspace/paddleocr-vl/.venv# 创建命令mkdir-p /mnt/workspace/paddleocr-vlcd/mnt/workspace/paddleocr-vl uv venv --python3.11# 激活命令source.venv/bin/activatePaddleOCR 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.0UV_HTTP_TIMEOUT=3600uv pipinstallpaddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/# 安装 PaddleOCR-VLUV_HTTP_TIMEOUT=3600uv pipinstall-U"paddleocr[doc-parser]"备选方案（cu126 失败时）
# 使用 cu124 版本UV_HTTP_TIMEOUT=3600uv pipinstallpaddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu124/UV_HTTP_TIMEOUT=3600uv pipinstall-U"paddleocr[doc-parser]"验证安装
# 检查 PaddlePaddle 版本和 CUDA 支持python -c"import paddle; print(paddle.__version__); print(paddle.device.cuda.device_count())"# 检查 PaddleOCR-VLpython -c"from paddleocr import PaddleOCRVL; print('PaddleOCR-VL installed successfully')"使用 ModelScope 下载 PaddleOCR-VL 模型
frommodelscopeimportsnapshot_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 模型
frommodelscopeimportsnapshot_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 supportUV_HTTP_TIMEOUT=3600uv pipinstallpaddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/# Install PaddleOCR-VL with document parser capabilitiesUV_HTTP_TIMEOUT=3600uv pipinstall-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"pipinstallhttps://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 pipinstallpackaging ninja pipinstallflash-attn --no-build-isolationProduction Deployment Workflow
Complete Setup Flow (Verified Working)
Step 1: Environment Activation
source.venv/bin/activateStep 2: Install Dependencies
# Core packagespaddleocr install_genai_server_deps vllm# Flash-attention (GPU acceleration)# Download wheel locally first, then installwgethttp://qiniu.dywlkj.com/deepseek-ocr-vllm/flash_attn-2.7.3%2Bcu12torch2.8cxx11abiFALSE-cp311-cp311-linux_x86_64.whl pipinstall./flash_attn-2.7.3+cu12torch2.8cxx11abiFALSE-cp311-cp311-linux_x86_64.whl# Verify installationpython -c"import flash_attn; print(flash_attn.__version__)"# Expected output: 2.7.3Step 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\--host0.0.0.0\--port8118Step 4: Verify Server Status
# Check server healthcurlhttp://127.0.0.1:8118/health# List available modelscurlhttp://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\--host0.0.0.0\--port10800\--paddle_model_dir /mnt/workspace/paddleocr-vl
)
