PaddleX/zhch/PaddleOCR-VL-说明.md

环境说明

在安装paddlex后，参考README中的说明

conda activate paddle

# 飞桨框架读取 safetensors 格式模型
python -m pip install https://paddle-whl.bj.bcebos.com/nightly/cu126/safetensors/safetensors-0.6.2.dev0-cp38-abi3-linux_x86_64.whl

# 安装 PaddleX
python -m pip install "paddlex[ocr]"
# 安装 vLLM 服务器插件
paddlex --install genai-vllm-server
# 安装 SGLang 服务器插件
# paddlex --install genai-sglang-server

# 安装 GenAI 客户端
paddlex --install genai-client

通过pipeline调用PaddleOCR-VL模型进行图文理解任务

小模型在本地运行，大模型通过vLLM服务器调用

VLRecognition:
  ...
  genai_config:
    backend: vllm-server
    server_url: http://10.192.72.11:8110/v1

正在收集工作区信息正在筛选到最相关的信息您说得对!这正是PaddleOCR-VL的推荐部署方式。让我详细说明这个架构:

PaddleOCR-VL 混合部署架构

架构说明

graph TB
    Client[客户端 PaddleX Pipeline]
    
    subgraph "本地运行 (CPU/GPU)"
        DocPreprocess[文档预处理<br/>DocOrientationClassify<br/>DocUnwarping]
        LayoutDet[版面检测<br/>PP-DocLayoutV2]
    end
    
    subgraph "远程vLLM服务器 (GPU)"
        VLM[视觉语言模型<br/>PaddleOCR-VL-0.9B]
    end
    
    Client -->|1. 输入图像| DocPreprocess
    DocPreprocess -->|2. 校正后图像| LayoutDet
    LayoutDet -->|3. 版面区域| VLM
    VLM -->|4. 文本识别结果| Client

为什么这样设计？

模型类型	部署位置	原因
小模型 (PP-DocLayoutV2)	本地	✅ 模型小(~100MB) ✅ 推理快(CPU可用) ✅ 无网络延迟
大模型 (VL-0.9B)	vLLM服务器	✅ 模型大(~2GB) ✅ 需要GPU加速 ✅ 支持并发请求 ✅ 支持多客户端共享

---

完整部署指南

1. 服务端:启动vLLM服务器

在GPU服务器上运行:

# 激活环境
conda activate paddle

# 安装依赖
paddlex --install genai-vllm-server

# 🎯 启动vLLM服务(后台运行)
nohup paddlex_genai_server \
    --model_name PaddleOCR-VL-0.9B \
    --backend vllm \
    --host 0.0.0.0 \
    --port 8110 \
    --backend_config <(cat <<EOF
gpu-memory-utilization: 0.8
max-num-seqs: 128
tensor-parallel-size: 1
EOF
) > vllm_server.log 2>&1 &

echo "✅ vLLM服务已启动"
echo "📝 查看日志: tail -f vllm_server.log"
echo "🔗 服务地址: http://$(hostname -I | awk '{print $1}'):8110/v1"

验证服务:

curl -X POST http://10.192.72.11:8110/v1/health
# 应返回: {"status": "ok"}

---

2. 客户端:配置PaddleX Pipeline

2.1 安装客户端依赖

# 在客户端机器上
conda activate paddle
paddlex --install genai-client

2.2 获取并修改配置文件

# 获取默认配置
paddlex --get_pipeline_config PaddleOCR-VL

# 修改配置文件

关键配置 (zhch/my_config/PaddleOCR-VL-Client.yaml):

pipeline_name: PaddleOCR-VL

# 🎯 小模型配置 - 本地运行
SubModules:
  LayoutDetection:
    module_name: layout_detection
    model_name: PP-DocLayoutV2
    model_dir: null  # null表示自动下载到本地
    batch_size: 8
    
  # 🎯 大模型配置 - 远程调用
  VLRecognition:
    module_name: vl_recognition
    model_name: PaddleOCR-VL-0.9B
    model_dir: null  # 🔴 不需要本地模型文件
    batch_size: 2048
    genai_config:
      backend: vllm-server  # ✅ 使用vLLM服务器
      server_url: http://10.192.72.11:8110/v1  # ✅ 服务器地址

# 🎯 本地预处理模型(可选)
SubPipelines:
  DocPreprocessor:
    use_doc_orientation_classify: True
    use_doc_unwarping: False
    SubModules:
      DocOrientationClassify:
        model_name: PP-LCNet_x1_0_doc_ori
        model_dir: null  # 本地运行

---

3. 使用示例

CLI调用

paddlex --pipeline zhch/my_config/PaddleOCR-VL-Client.yaml \
        --input test_image.png \
        --device cpu \
        --save_path ./output

Python API调用

from paddlex import create_pipeline

# 创建pipeline(小模型在本地加载)
pipeline = create_pipeline(
    "zhch/my_config/PaddleOCR-VL-Client.yaml",
    device="cpu"  # 小模型用CPU即可
)

# 推理(大模型自动调用远程服务)
for result in pipeline.predict("test_image.png"):
    result.print()
    result.save_to_json("output.json")
    result.save_to_markdown("output.md")

---

性能调优建议

服务端优化

1. GPU显存分配

# vLLM配置
gpu-memory-utilization: 0.8  # 使用80%显存
max-num-seqs: 128  # 最大并发序列数

# linux 10.192.72.11
# 启动ppstructure_v3增强自定义adapter服务
zhch/paddle_vllm_daemon.sh start

# client
python paddleocr_vl_single_process.py --input_file "/Users/zhch158/workspace/data/至远彩色印刷工业有限公司/2023年度报告母公司.pdf" --output_dir "/Users/zhch158/workspace/data/至远彩色印刷工业有限公司/PaddleOCR_VL_Results" --pipeline "./my_config/PaddleOCR-VL-Client.yaml" --no-adapter

# client 流水分析
python paddleocr_vl_single_process.py --input_file "/Users/zhch158/workspace/data/流水分析/A用户_单元格扫描流水.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/A用户_单元格扫描流水/PaddleOCR_VL_Results" --pipeline "./my_config/PaddleOCR-VL-Client.yaml" --no-adapter

python paddleocr_vl_single_process.py --input_file "/Users/zhch158/workspace/data/流水分析/A用户_单元格图片合成.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/A用户_单元格图片合成/PaddleOCR_VL_Results" --pipeline "./my_config/PaddleOCR-VL-Client.yaml" --no-adapter

python paddleocr_vl_single_process.py --input_file "/Users/zhch158/workspace/data/流水分析/B用户_扫描流水.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/B用户_扫描流水/PaddleOCR_VL_Results" --pipeline "./my_config/PaddleOCR-VL-Client.yaml" --no-adapter

python paddleocr_vl_single_process.py --input_file "/Users/zhch158/workspace/data/流水分析/B用户_扫描流水.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/B用户_扫描流水/PaddleOCR_VL_Results" --pipeline "./my_config/PaddleOCR-VL-Client-RT-DETR-H_layout_17cls.yaml"

python paddleocr_vl_single_process.py --input_file "/Users/zhch158/workspace/data/流水分析/B用户_图片合成流水.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/B用户_图片合成流水/PaddleOCR_VL_Results" --pipeline "./my_config/PaddleOCR-VL-Client.yaml" --no-adapter

python paddleocr_vl_single_process.py --input_file "/Users/zhch158/workspace/data/流水分析/对公_招商银行图.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/对公_招商银行图/PaddleOCR_VL_Results" --pipeline "./my_config/PaddleOCR-VL-Client.yaml" --no-adapter

python paddleocr_vl_single_process.py --input_file "//Users/zhch158/workspace/data/流水分析/德_内蒙古银行照.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/德_内蒙古银行照/PaddleOCR_VL_Results" --pipeline "./my_config/PaddleOCR-VL-Client.yaml" --no-adapter

PaddleOCR-VL关键代码位置

paddlex/inference/pipelines/paddleocr_vl/pipeline.py
paddlex/inference/pipelines/paddleocr_vl/result.py
paddlex/inference/pipelines/paddleocr_vl/uilts.py
paddlex/inference/models/common/genai.py
paddlex/inference/models/doc_vlm/predictor.py

# vllm启动服务代码
paddlex/inference/genai/server.py

# 所有分类
paddlex/repo_apis/PaddleDetection_api/object_det/official_categories.py

mineru 关键代码位置

mineru/backend/pipeline/batch_analyze.py