# 服务端守护进程脚本

本目录包含所有 OCR 工具的服务端守护进程脚本，用于启动和管理 HTTP API 服务。

## 概述

这些守护进程脚本用于在服务器上启动和管理各种 OCR 服务的 HTTP API 端点。客户端工具（位于 `ocr_tools/*_tool/` 目录）可以通过这些 API 端点调用远程服务进行文档处理。

## 脚本列表

| 脚本文件 | 服务类型 | 默认端口 | 服务 URL |
|---------|---------|---------|---------|
| `mineru_vllm_daemon.sh` | MinerU vLLM | 8121 | http://localhost:8121 |
| `ppstructure_v3_daemon.sh` | PP-StructureV3 API | 8111 | http://localhost:8111/layout-parsing |
| `paddle_vllm_daemon.sh` | PaddleOCR-VL vLLM | 8110 | http://localhost:8110 |
| `dotsocr_vllm_daemon.sh` | DotsOCR vLLM | 8101 | http://localhost:8101 |

## 脚本与客户端工具映射

| 服务端脚本 | 客户端工具 | 服务类型 | 默认端口 | API 端点 |
|-----------|----------|---------|---------|---------|
| `mineru_vllm_daemon.sh` | `mineru_vl_tool/main.py` | MinerU vLLM | 8121 | http://localhost:8121 |
| `ppstructure_v3_daemon.sh` | `ppstructure_tool/api_client.py` | PP-StructureV3 API | 8111 | http://localhost:8111/layout-parsing |
| `paddle_vllm_daemon.sh` | `paddle_vl_tool/main.py` | PaddleOCR-VL vLLM | 8110 | http://localhost:8110 |
| `dotsocr_vllm_daemon.sh` | `dots.ocr_vl_tool/main.py` | DotsOCR vLLM | 8101 | http://localhost:8101 |

## 快速开始

### 基本使用

所有脚本都支持以下命令：

```bash
# 启动服务
./script_name.sh start

# 停止服务
./script_name.sh stop

# 重启服务
./script_name.sh restart

# 查看服务状态
./script_name.sh status

# 查看日志（实时）
./script_name.sh logs

# 查看配置
./script_name.sh config

# 测试 API（如果支持）
./script_name.sh test
```

### 示例

```bash
# 启动 MinerU vLLM 服务
cd ocr_tools/daemons
./mineru_vllm_daemon.sh start

# 查看服务状态
./mineru_vllm_daemon.sh status

# 查看日志
./mineru_vllm_daemon.sh logs
```

## 各脚本详细说明

### 1. mineru_vllm_daemon.sh

**服务类型**：MinerU vLLM 服务

**配置参数**：
- `CONDA_ENV`: conda 环境名称（默认: `mineru2`）
- `PORT`: 服务端口（默认: `8121`）
- `HOST`: 服务主机（默认: `0.0.0.0`）
- `MODEL_PATH`: 模型路径
- `MODEL_NAME`: 模型名称（默认: `MinerU2.5`）
- `GPU_MEMORY_UTILIZATION`: GPU 内存利用率（默认: `0.3`）
- `CUDA_VISIBLE_DEVICES`: 可见的 CUDA 设备（默认: `4`）

**启动方法**：
```bash
./mineru_vllm_daemon.sh start
```

**服务 URL**：
- API 端点: `http://localhost:8121`
- API 文档: `http://localhost:8121/docs`

**依赖环境**：
- conda 环境: `mineru2`
- 需要安装: `mineru-vllm-server`

**客户端使用**：
```bash
# 使用 mineru_vl_tool 调用服务
cd ../mineru_vl_tool
python main.py --input document.pdf --output_dir ./output --server_url http://localhost:8121
```

### 2. ppstructure_v3_daemon.sh

**服务类型**：PP-StructureV3 API 服务

**配置参数**：
- `CONDA_ENV`: conda 环境名称（默认: `paddle`）
- `PORT`: 服务端口（默认: `8111`）
- `CUDA_VISIBLE_DEVICES`: 可见的 CUDA 设备（默认: `7`）
- `SCRIPT_DIR`: PaddleX 脚本目录
- `PIPELINE_CONFIG`: Pipeline 配置文件路径

**启动方法**：
```bash
./ppstructure_v3_daemon.sh start
```

**服务 URL**：
- API 端点: `http://localhost:8111/layout-parsing`
- API 文档: `http://localhost:8111/docs`

**依赖环境**：
- conda 环境: `paddle`
- 需要安装: `paddlex`
- 需要脚本: `start_paddlex_with_adapter.py`（位于 `ocr_tools/paddle_common/` 目录）

**配置说明**：
- 脚本中的 `PADDLE_COMMON_DIR` 需要根据实际部署环境设置为 `ocr_platform/ocr_tools/paddle_common` 的绝对路径
- Pipeline 配置文件可以使用 `paddle_common/config/` 中的配置文件

**客户端使用**：
```bash
# 使用 ppstructure_tool/api_client.py 调用服务
cd ../ppstructure_tool
python api_client.py --input document.pdf --output_dir ./output --api_url http://localhost:8111/layout-parsing
```

### 3. paddle_vllm_daemon.sh

**服务类型**：PaddleOCR-VL vLLM 服务

**配置参数**：
- `CONDA_ENV`: conda 环境名称（默认: `paddle`）
- `PORT`: 服务端口（默认: `8110`）
- `HOST`: 服务主机（默认: `0.0.0.0`）
- `MODEL_NAME`: 模型名称（默认: `PaddleOCR-VL-0.9B`）
- `BACKEND`: 后端类型（默认: `vllm`）
- `GPU_MEMORY_UTILIZATION`: GPU 内存利用率（默认: `0.3`）
- `CUDA_VISIBLE_DEVICES`: 可见的 CUDA 设备（默认: `3`）

**启动方法**：
```bash
./paddle_vllm_daemon.sh start
```

**服务 URL**：
- API 端点: `http://localhost:8110`
- API 文档: `http://localhost:8110/docs`

**依赖环境**：
- conda 环境: `paddle`
- 需要安装: `paddlex` 和 `genai-vllm-server` 插件
  ```bash
  paddlex --install genai-vllm-server
  ```

**客户端使用**：
```bash
# 使用 paddle_vl_tool 调用服务（通过配置文件指定 vLLM 服务器）
cd ../paddle_vl_tool
python main.py --input document.pdf --output_dir ./output \
  --pipeline ../paddle_common/config/PaddleOCR-VL-Client.yaml
```

### 4. dotsocr_vllm_daemon.sh

**服务类型**：DotsOCR vLLM 服务

**配置参数**：
- `CONDA_ENV`: conda 环境名称（默认: `dots.ocr`）
- `PORT`: 服务端口（默认: `8101`）
- `HOST`: 服务主机（默认: `0.0.0.0`）
- `HF_MODEL_PATH`: HuggingFace 模型路径
- `MODEL_NAME`: 模型名称（默认: `DotsOCR`）
- `GPU_MEMORY_UTILIZATION`: GPU 内存利用率（默认: `0.70`）
- `CUDA_VISIBLE_DEVICES`: 可见的 CUDA 设备（默认: `1,2`）
- `DATA_PARALLEL_SIZE`: 数据并行大小（默认: `2`）

**启动方法**：
```bash
./dotsocr_vllm_daemon.sh start
```

**服务 URL**：
- API 端点: `http://localhost:8101`
- API 文档: `http://localhost:8101/docs`

**依赖环境**：
- conda 环境: `dots.ocr`
- 需要安装: `vllm`
- 需要模型: DotsOCR 模型文件

**客户端使用**：
```bash
# 使用 dots.ocr_vl_tool 调用服务
cd ../dots.ocr_vl_tool
python main.py --input document.pdf --output_dir ./output --ip localhost --port 8101
```

## 部署建议

### 1. 环境准备

- 确保所有依赖的 conda 环境已正确安装
- 确保模型文件已下载并放置在正确位置
- 确保 GPU 驱动和 CUDA 已正确安装

### 2. 配置调整

在部署前，请根据实际环境调整脚本中的配置参数：

- **日志目录**：默认使用 `/home/ubuntu/zhch/logs`，可根据需要修改
- **conda 路径**：根据实际 conda 安装路径调整
- **模型路径**：确保模型路径正确
- **GPU 设备**：根据实际 GPU 配置调整 `CUDA_VISIBLE_DEVICES`
- **端口号**：确保端口未被占用

### 3. 权限设置

```bash
# 为所有脚本添加执行权限
chmod +x *.sh
```

### 4. 使用 systemd 管理（推荐）

可以创建 systemd 服务文件来管理这些守护进程，实现自动启动和重启：

```ini
[Unit]
Description=MinerU vLLM Service
After=network.target

[Service]
Type=forking
User=ubuntu
WorkingDirectory=/path/to/ocr_platform/ocr_tools/daemons
ExecStart=/path/to/ocr_platform/ocr_tools/daemons/mineru_vllm_daemon.sh start
ExecStop=/path/to/ocr_platform/ocr_tools/daemons/mineru_vllm_daemon.sh stop
Restart=always

[Install]
WantedBy=multi-user.target
```

### 5. 日志管理

所有服务的日志文件位于 `/home/ubuntu/zhch/logs/` 目录：

- `mineru_vllm.log` - MinerU vLLM 服务日志
- `ppstructurev3.log` - PP-StructureV3 服务日志
- `paddleocr_vl_vllm.log` - PaddleOCR-VL vLLM 服务日志
- `vllm.log` - DotsOCR vLLM 服务日志

建议定期清理或轮转日志文件。

## 故障排查

### 问题：服务启动失败

**可能原因**：
1. conda 环境未正确激活
2. 依赖包未安装
3. 模型文件不存在
4. 端口已被占用
5. GPU 不可用或配置错误

**解决方法**：
1. 使用 `./script_name.sh config` 检查配置
2. 检查 conda 环境是否正确激活：`conda env list`
3. 检查依赖是否安装：`which python`, `which mineru-vllm-server` 等
4. 检查模型路径是否存在
5. 检查端口占用：`netstat -tuln | grep :PORT`
6. 检查 GPU 状态：`nvidia-smi`

### 问题：API 无响应

**可能原因**：
1. 服务未正常启动
2. 服务正在启动中（需要等待）
3. 网络连接问题
4. 防火墙阻止

**解决方法**：
1. 使用 `./script_name.sh status` 检查服务状态
2. 查看日志：`./script_name.sh logs`
3. 等待服务完全启动（通常需要几分钟）
4. 检查防火墙设置

### 问题：GPU 内存不足

**可能原因**：
1. GPU 内存利用率设置过高
2. 多个服务同时运行占用 GPU
3. GPU 显存不足

**解决方法**：
1. 降低 `GPU_MEMORY_UTILIZATION` 参数
2. 使用不同的 GPU 运行不同服务（调整 `CUDA_VISIBLE_DEVICES`）
3. 关闭其他占用 GPU 的程序

### 问题：模型注册失败（DotsOCR）

**可能原因**：
1. vLLM 未正确安装
2. DotsOCR 模型路径不正确
3. PYTHONPATH 设置错误

**解决方法**：
1. 检查 vLLM 安装：`which vllm`
2. 检查模型路径：`ls -la $HF_MODEL_PATH`
3. 检查 PYTHONPATH：`echo $PYTHONPATH`

## 相关文档

- [MinerU vL Tool README](../mineru_vl_tool/README.md)
- [PP-StructureV3 Tool README](../ppstructure_tool/README.md)
- [PaddleOCR-VL Tool README](../paddle_vl_tool/README.md)
- [DotsOCR vL Tool README](../dots.ocr_vl_tool/README.md)

## 注意事项

1. **路径配置**：脚本中的路径（如模型路径、日志路径）需要根据实际部署环境调整
2. **端口冲突**：确保不同服务使用不同的端口，避免冲突
3. **GPU 资源**：合理分配 GPU 资源，避免多个服务竞争同一 GPU
4. **日志管理**：定期清理日志文件，避免磁盘空间不足
5. **服务监控**：建议使用监控工具（如 systemd、supervisor）管理服务，确保服务稳定运行