PaddleOCR-VL 本地部署指南
PaddleOCR-VL 是百度开源的轻量级视觉语言模型，支持 OCR 与多模态理解。本地部署不仅能保障数据隐私，还能显著降低调用成本。本文基于 Docker 环境，分享从零到接入 Fastgpt 的完整实战流程。
硬件与环境要求
目前官方版本暂不支持 Mac 和 AMD 显卡，需使用 NVIDIA GPU。
- 推荐配置：RTX 3060 12G 显存及以上。
- 最低体验：8G 显存可运行，但需注意显存占用优化。
- 系统环境：Windows/Linux + Docker。
首次启动可能占用约 11G 显存，后续优化后可降至 6G 左右。
核心部署步骤
1. 准备 Docker 环境
确保已安装 Docker 并开启 GPU 支持。在终端执行以下命令拉取镜像（约 18GB）：
docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server
进入容器后检查 paddlex 版本，建议不低于 3.3.4：
docker run -it --rm --gpus all -p 8118:8118 --network host ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server /bin/bash
pip list | grep paddlex
2. 解决 Flash Attention 依赖问题
镜像精简版未包含 CUDA 编译工具，直接构建 flash-attn 会失败。需安装预编译 wheel 包：
python -m pip install https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.4.11/flash_attn-2.8.3+cu128torch2.8-cp310-cp310-linux_x86_64.whl
3. 启动服务与显存优化
默认启动脚本可能因显存限制报错（OOM）。通过 --backend_config 参数调整 vLLM 显存利用率至 80% 即可解决：
paddleocr genai_server \
--model_name PaddleOCR-VL-0.9B \
--backend vllm \
--port 8118 \
--host 0.0.0.0 \
--backend_config <(echo -e 'gpu-memory-utilization: 0.8')
若希望一键启动且自动处理依赖，可使用以下命令：
docker run -d --rm --gpus all -p 8118:8118 --name paddleocr-vl-server \
ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest \
sh -c "pip install https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.4.11/flash_attn-2.8.3+cu128torch2.8-cp310-cp310-linux_x86_64.whl && paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118 --host 0.0.0.0 --backend_config <(echo -e 'gpu-memory-utilization: 0.8')"
注意：非 50 系显卡用户无需额外配置，上述指令通用。频繁重启会导致 Docker 虚拟空间增长，建议稳定后减少重启频率。
验证与 API 测试
服务启动成功后，访问 Swagger 文档确认状态：
http://localhost:8118/docs
使用 Postman 发送 OpenAI 格式请求进行测试：
{
"model": "PaddleOCR-VL-0.9B",
"messages": [
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}},
{"type": "text", "text": "请识别图片中的文字内容"}
]
}
]
}
接入 Fastgpt 实战
PaddleOCR-VL 兼容 OpenAI API 协议，可直接接入 Fastgpt、Dify 等平台。
- 新增模型：填写模型 ID
PaddleOCR-VL-0.9B。 - 配置地址：请求 URL 设为
http://<Base_URL>:8118/v1/chat/completions。 - 启用图片识别：在应用设置中打开文件上传功能。
- 记忆轮数：建议设置为 0，避免上下文混淆影响识别结果。
接入后响应速度极快，基本可实现秒级输出。若作为知识库的图片理解模型，效果同样出色。
常见问题排查
- 显存溢出：务必添加
--backend_config参数，将利用率调至 0.8 以上。 - 镜像版本：确保
paddlex版本 >= 3.3.4，旧版本可能存在兼容性 bug。 - 网络问题：国内环境拉取镜像建议使用 Baidu 源，如遇超时请检查代理设置。
官方文档参考：PaddleOCR-VL Pipeline Usage
