feat: 添加PaddleOCR-VL环境说明和完整部署指南文档

zhch/PaddleOCR-VL-说明.md

@@ -0,0 +1,221 @@
+# 环境说明
+在安装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
+
+```