提交qiming-mcp-proxy

qiming-mcp-proxy/document-parser/CUDA_SETUP_GUIDE.md

@@ -0,0 +1,312 @@
+# CUDA环境配置和sglang GPU加速指南
+
+## 概述
+
+本指南专门针对需要GPU加速的用户，详细说明如何在支持CUDA的Linux服务器上配置sglang环境，确保MinerU能够使用GPU加速进行PDF解析。
+
+## 前置条件
+
+### 1. 硬件要求
+- NVIDIA GPU（支持CUDA）
+- 至少8GB GPU内存（推荐16GB+）
+- 足够的系统内存（推荐32GB+）
+
+### 2. 软件要求
+- Linux操作系统（推荐Ubuntu 20.04+）
+- NVIDIA驱动（版本450+）
+- CUDA Toolkit（推荐11.8或12.x）
+- Python 3.8+
+
+## 环境检查
+
+### 1. 检查NVIDIA驱动
+```bash
+# 检查驱动版本
+nvidia-smi
+
+# 预期输出示例：
+# +-----------------------------------------------------------------------------+
+# | NVIDIA-SMI 525.105.17   Driver Version: 525.105.17   CUDA Version: 12.0     |
+# +-----------------------------------------------------------------------------+
+```
+
+### 2. 检查CUDA安装
+```bash
+# 检查CUDA版本
+nvcc --version
+
+# 预期输出示例：
+# nvcc: NVIDIA (R) Cuda compiler driver
+# Copyright (c) 2005-2023 NVIDIA Corporation
+# Built on Wed_Nov_22_10:17:15_PST_2023
+# Cuda compilation tools, release 12.3, V12.3.52
+```
+
+### 3. 检查GPU状态
+```bash
+# 查看GPU详细信息
+nvidia-smi --query-gpu=index,name,memory.total,memory.free,compute_cap --format=csv
+
+# 预期输出示例：
+# 0, NVIDIA GeForce RTX 4090, 24576 MiB, 23552 MiB, 8.9
+```
+
+## 安装sglang
+
+### 1. 激活虚拟环境
+```bash
+# 进入项目目录
+cd /path/to/document-parser
+
+# 激活虚拟环境
+source ./venv/bin/activate
+
+# 验证Python路径
+which python
+# 应该显示: /path/to/document-parser/venv/bin/python
+```
+
+### 2. 安装MinerU（包含兼容的sglang）
+```bash
+# 使用uv安装（推荐）
+uv pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple
+
+# 或者使用pip安装
+pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple
+
+# 安装过程可能需要几分钟，请耐心等待
+```
+
+**重要**：使用 `mineru[all]` 而不是直接安装 `sglang[all]`，确保版本兼容性。
+
+### 3. 验证安装
+```bash
+# 检查sglang版本
+python -c "import sglang; print('SGLang版本:', sglang.__version__)"
+
+# 检查sglang server
+python -m sglang.srt.server --help
+
+# 检查CUDA支持
+python -c "import torch; print('PyTorch版本:', torch.__version__); print('CUDA可用:', torch.cuda.is_available()); print('CUDA设备数:', torch.cuda.device_count())"
+```
+
+## 配置MinerU使用sglang
+
+### 1. 修改配置文件
+编辑 `config.yml` 文件：
+
+```yaml
+# MinerU配置
+mineru:
+  backend: "vlm-sglang-engine"  # 关键：启用sglang后端
+  python_path: "./venv/bin/python"
+  max_concurrent: 2              # GPU环境下建议降低并发数
+  queue_size: 100
+  batch_size: 1
+  quality_level: "Balanced"
+```
+
+### 2. 或者通过环境变量
+```bash
+# 设置环境变量
+export MINERU_BACKEND="vlm-sglang-engine"
+
+# 启动服务
+document-parser server
+```
+
+## 验证GPU加速是否生效
+
+### 1. 启动服务并检查日志
+```bash
+# 启动服务
+document-parser server
+
+# 在另一个终端查看日志
+tail -f logs/log.$(date +%Y-%m-%d)
+```
+
+查找以下关键信息：
+```
+INFO 虚拟环境已自动激活
+INFO MinerU配置: backend=vlm-sglang-engine
+DEBUG MinerU完整命令: .../mineru -p input.pdf -o output -b vlm-sglang-engine
+```
+
+### 2. 实时监控GPU使用
+```bash
+# 在另一个终端监控GPU
+watch -n 1 nvidia-smi
+
+# 或者使用更详细的监控
+nvidia-smi dmon -s pucvmet -d 1
+```
+
+### 3. 测试PDF解析
+上传一个PDF文件进行解析，观察：
+- GPU内存使用是否增加
+- GPU计算单元是否被占用
+- 解析速度是否明显提升
+
+### 4. 检查进程
+```bash
+# 查看MinerU进程
+ps aux | grep mineru
+
+# 查看GPU进程
+nvidia-smi pmon -c 1
+```
+
+## 性能调优
+
+### 1. 并发控制
+根据GPU内存调整并发数：
+```yaml
+mineru:
+  max_concurrent: 1    # 8GB GPU内存
+  max_concurrent: 2    # 16GB GPU内存  
+  max_concurrent: 4    # 24GB+ GPU内存
+```
+
+### 2. 批处理大小
+```yaml
+mineru:
+  batch_size: 1        # 小批次，适合大模型
+  batch_size: 2        # 中等批次
+  batch_size: 4        # 大批次，适合小模型
+```
+
+### 3. 质量级别
+```yaml
+mineru:
+  quality_level: "Fast"        # 快速模式，GPU占用低
+  quality_level: "Balanced"    # 平衡模式（推荐）
+  quality_level: "HighQuality" # 高质量模式，GPU占用高
+```
+
+## 故障排除
+
+### 1. sglang导入失败
+```bash
+# 检查Python版本
+python --version
+
+# 重新安装sglang
+pip uninstall sglang -y
+pip install "sglang[all]"
+
+# 检查依赖
+pip list | grep sglang
+```
+
+### 2. CUDA不可用
+```bash
+# 检查PyTorch CUDA支持
+python -c "import torch; print(torch.cuda.is_available())"
+
+# 如果返回False，重新安装PyTorch
+pip uninstall torch torchvision torchaudio -y
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
+```
+
+### 3. GPU内存不足
+```bash
+# 检查GPU内存使用
+nvidia-smi
+
+# 降低并发数和批处理大小
+# 关闭其他GPU进程
+```
+
+### 4. 版本兼容性问题
+```bash
+# 检查transformers版本
+pip show transformers
+
+# 安装兼容版本
+pip install "transformers>=4.36.0,<4.40.0"
+
+# 重新安装sglang
+pip install "sglang[all]"
+```
+
+## 性能基准测试
+
+### 1. 测试文件
+使用不同大小的PDF文件测试性能：
+- 小文件（<1MB）：测试启动时间
+- 中等文件（1-10MB）：测试处理速度
+- 大文件（>10MB）：测试内存使用
+
+### 2. 性能指标
+- **启动时间**：从命令执行到开始处理的时间
+- **处理速度**：每秒处理的页数或字数
+- **GPU利用率**：GPU计算单元和内存的使用率
+- **内存使用**：GPU和系统内存的峰值使用
+
+### 3. 对比测试
+```bash
+# 测试pipeline后端（CPU）
+mineru -p test.pdf -o output -b pipeline
+
+# 测试sglang后端（GPU）
+mineru -p test.pdf -o output -b vlm-sglang-engine
+
+# 对比处理时间和资源使用
+```
+
+## 监控和维护
+
+### 1. 定期检查
+```bash
+# 检查GPU健康状态
+nvidia-smi --query-gpu=health --format=csv
+
+# 检查温度
+nvidia-smi --query-gpu=temperature.gpu --format=csv
+
+# 检查电源使用
+nvidia-smi --query-gpu=power.draw --format=csv
+```
+
+### 2. 日志分析
+```bash
+# 分析性能日志
+grep "processing_time" logs/log.* | awk '{print $NF}' | sort -n
+
+# 分析错误日志
+grep "ERROR" logs/log.* | tail -20
+```
+
+### 3. 性能优化
+- 根据实际使用情况调整并发参数
+- 监控GPU内存使用，避免OOM错误
+- 定期清理临时文件和缓存
+
+## 常见问题
+
+### Q: 为什么GPU加速没有生效？
+A: 检查以下几点：
+1. sglang是否正确安装
+2. 配置文件中的backend是否为"vlm-sglang-engine"
+3. CUDA环境是否可用
+4. GPU内存是否充足
+
+### Q: 如何知道MinerU正在使用GPU？
+A: 通过以下方式确认：
+1. 查看nvidia-smi输出中的进程列表
+2. 观察GPU内存使用是否增加
+3. 检查日志中的命令参数
+4. 对比CPU和GPU模式的性能差异
+
+### Q: GPU内存不足怎么办？
+A: 可以尝试：
+1. 降低max_concurrent参数
+2. 减小batch_size
+3. 使用"Fast"质量级别
+4. 关闭其他GPU进程
+
+---
+
+**注意**：本指南基于Linux环境编写，Windows用户可能需要调整部分命令。如有问题，请参考主用户手册或运行 `document-parser troubleshoot` 获取帮助。