# 环境说明
在安装paddlex后，参考README中的说明
```bash
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服务器调用
```json
VLRecognition:
  ...
  genai_config:
    backend: vllm-server
    server_url: http://10.192.72.11:8110/v1
```
正在收集工作区信息正在筛选到最相关的信息您说得对!这正是PaddleOCR-VL的推荐部署方式。让我详细说明这个架构:

## PaddleOCR-VL 混合部署架构

### 架构说明

```mermaid
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)<br>✅ 推理快(CPU可用)<br>✅ 无网络延迟 |
| **大模型** (VL-0.9B) | vLLM服务器 | ✅ 模型大(~2GB)<br>✅ 需要GPU加速<br>✅ 支持并发请求<br>✅ 支持多客户端共享 |

---

## 完整部署指南

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

在**GPU服务器**上运行:

```bash
# 激活环境
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"
```

**验证服务**:
```bash
curl -X POST http://10.192.72.11:8110/v1/health
# 应返回: {"status": "ok"}
```

---

### 2. 客户端:配置PaddleX Pipeline

#### 2.1 安装客户端依赖

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

#### 2.2 获取并修改配置文件

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

# 修改配置文件
```

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

```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调用

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

#### Python API调用

```python
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显存分配

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

```bash
# 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.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关键代码位置
```bash
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

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

### mineru 关键代码位置
```bash
mineru/backend/pipeline/batch_analyze.py
```