# 服务端守护进程脚本

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

## 概述

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

## 脚本列表

### 远程 vLLM 服务（Linux/GPU）

| 脚本文件 | 服务类型 | 默认端口 | 服务 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 |

### 本地 GGUF 模型服务（macOS/Metal）

| 脚本文件 | 服务类型 | 默认端口 | 服务 URL |
|---------|---------|---------|---------|
| `glmocr_local_daemon.sh` | GLM-OCR Q8_0 (llama.cpp) | 8080 | http://localhost:8080 |
| `paddleocr_local_daemon.sh` | PaddleOCR-VL-1.5 (llama.cpp) | 8081 | http://localhost:8081 |

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

| 服务端脚本 | 客户端工具 | 服务类型 | 默认端口 | 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
```

### 5. glmocr_local_daemon.sh

**服务类型**：GLM-OCR 本地 GGUF 模型服务（macOS/Metal）

**配置参数**：
- `CONDA_ENV`: conda 环境名称（默认: `mineru2`）
- `PORT`: 服务端口（默认: `8080`）
- `HOST`: 服务主机（默认: `0.0.0.0`）
- `MODEL_PATH`: GGUF 模型路径（默认: `~/Library/Caches/llama.cpp/ggml-org_GLM-OCR-GGUF_GLM-OCR-Q8_0.gguf`）
- `MMPROJ_PATH`: 多模态投影器路径（默认: `~/Library/Caches/llama.cpp/ggml-org_GLM-OCR-GGUF_mmproj-GLM-OCR-Q8_0.gguf`）
- `CONTEXT_SIZE`: 上下文长度（默认: `16384`）
- `GPU_LAYERS`: Metal GPU 层数（默认: `99`，全部）
- `THREADS`: CPU 线程数（默认: `8`）

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

**服务 URL**：
- API 端点: `http://localhost:8080`
- OpenAI 兼容 API: `http://localhost:8080/v1/chat/completions`
- Models 端点: `http://localhost:8080/v1/models`

**依赖环境**：
- macOS (M4 Pro 推荐)
- Homebrew 安装 llama.cpp: `brew install llama.cpp`
- conda 环境: `mineru2`
- 模型文件位于: `~/Library/Caches/llama.cpp/`

**模型大小**：
- 主模型: 950MB (GLM-OCR-Q8_0.gguf)
- 多模态投影器: 484MB (mmproj-GLM-OCR-Q8_0.gguf)

**客户端使用**：
```bash
# 使用配置文件调用服务
cd ../universal_doc_parser
python parse.py --input document.pdf \
  --config config/bank_statement_yusys_local.yaml --debug

# 或直接调用 API
curl -X POST http://localhost:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "glm-ocr",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Table Recognition:"},
        {"type": "image_url", "image_url": {"url": "file://test.png"}}
      ]
    }],
    "max_tokens": 16384
  }'
```

**特点**：
- 🚀 本地运行，无需网络访问
- 🍎 Metal GPU 加速（macOS）
- 📊 OpenAI 兼容 API
- 🎯 确定性输出（--temp 0）
- 💾 低内存占用（GGUF Q8_0 量化）

### 6. paddleocr_local_daemon.sh

**服务类型**：PaddleOCR-VL-1.5 本地 GGUF 模型服务（macOS/Metal）

**配置参数**：
- `CONDA_ENV`: conda 环境名称（默认: `mineru2`）
- `PORT`: 服务端口（默认: `8081`）
- `HOST`: 服务主机（默认: `0.0.0.0`）
- `MODEL_PATH`: GGUF 模型路径（默认: `~/Library/Caches/llama.cpp/PaddlePaddle_PaddleOCR-VL-1.5-GGUF_PaddleOCR-VL-1.5.gguf`）
- `MMPROJ_PATH`: 多模态投影器路径（默认: `~/Library/Caches/llama.cpp/PaddlePaddle_PaddleOCR-VL-1.5-GGUF_PaddleOCR-VL-1.5-mmproj.gguf`）
- `CONTEXT_SIZE`: 上下文长度（默认: `16384`）
- `GPU_LAYERS`: Metal GPU 层数（默认: `99`，全部）
- `THREADS`: CPU 线程数（默认: `8`）

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

**服务 URL**：
- API 端点: `http://localhost:8081`
- OpenAI 兼容 API: `http://localhost:8081/v1/chat/completions`
- Models 端点: `http://localhost:8081/v1/models`

**依赖环境**：
- macOS (M4 Pro 推荐)
- Homebrew 安装 llama.cpp: `brew install llama.cpp`
- conda 环境: `mineru2`
- 模型文件位于: `~/Library/Caches/llama.cpp/`

**模型大小**：
- 主模型: 936MB (PaddleOCR-VL-1.5.gguf)
- 多模态投影器: 882MB (PaddleOCR-VL-1.5-mmproj.gguf)

**客户端使用**：
```bash
# 使用配置文件调用服务
cd ../universal_doc_parser
python parse.py --input document.pdf \
  --config config/bank_statement_paddleocr_local.yaml --debug

# 或直接调用 API
curl -X POST http://localhost:8081/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "paddleocr-vl",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Table Recognition:"},
        {"type": "image_url", "image_url": {"url": "file://test.png"}}
      ]
    }],
    "max_tokens": 16384
  }'
```

**特点**：
- 🚀 本地运行，无需网络访问
- 🍎 Metal GPU 加速（macOS）
- 📊 OpenAI 兼容 API
- 🎯 确定性输出（--temp 0）
- 💾 低内存占用（GGUF 量化）

**对比测试**：
```bash
# 可同时启动两个服务进行对比测试
./glmocr_local_daemon.sh start      # 端口 8080
./paddleocr_local_daemon.sh start   # 端口 8081

# 检查状态
./glmocr_local_daemon.sh status
./paddleocr_local_daemon.sh status
```

## 部署建议

### 1. 环境准备

#### Linux/GPU 环境（vLLM 服务）
- 确保所有依赖的 conda 环境已正确安装
- 确保模型文件已下载并放置在正确位置
- 确保 GPU 驱动和 CUDA 已正确安装

#### macOS/Metal 环境（本地 GGUF 服务）
- 安装 llama.cpp: `brew install llama.cpp`
- 确保 conda 环境 `mineru2` 已创建
- 模型文件自动下载到 `~/Library/Caches/llama.cpp/` 或手动下载：
  - GLM-OCR: https://huggingface.co/ggml-org/GLM-OCR-GGUF
  - PaddleOCR-VL: https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.5-GGUF
- 推荐硬件: Mac M4 Pro 或更高（至少 16GB RAM）

### 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. 日志管理

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

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

#### 本地 GGUF 服务日志（macOS）
日志文件位于 `~/workspace/logs/` 目录：

- `glmocr_llamaserver.log` - GLM-OCR llama-server 日志
- `glmocr_llamaserver.pid` - GLM-OCR 进程 PID
- `paddleocr_llamaserver.log` - PaddleOCR-VL llama-server 日志
- `paddleocr_llamaserver.pid` - PaddleOCR-VL 进程 PID

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

## 故障排查

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

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

**可能原因（本地 GGUF 服务）**：
1. llama-server 未安装或版本不兼容
2. 模型文件不存在于 `~/Library/Caches/llama.cpp/`
3. 端口已被占用
4. conda 环境未激活

**解决方法（vLLM）**：
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`

**解决方法（本地 GGUF）**：
1. 检查 llama-server: `which llama-server`, `llama-server --version`
2. 检查模型文件: `ls -lh ~/Library/Caches/llama.cpp/`
3. 检查端口占用: `lsof -i :8080` 或 `lsof -i :8081`
4. 查看日志: `./glmocr_local_daemon.sh logs`
5. 手动下载模型（如果缓存目录为空）

### 问题：llama-server 文件访问错误

**可能原因**：
1. 使用绝对路径而非相对路径
2. --media-path 设置不正确
3. 文件路径包含中文或特殊字符

**解决方法**：
1. 确保 --media-path 设置为基准目录（如 `/Users/zhch158/workspace`）
2. 图片路径使用相对路径：`file://test.png` 而非 `file:///Users/...`
3. 避免路径中包含中文字符
4. 测试: `./glmocr_local_daemon.sh test`

### 问题：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)

## 注意事项

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

### 本地 GGUF 服务（macOS/Metal）
1. **端口分离**：GLM-OCR 使用 8080，PaddleOCR-VL 使用 8081，可同时运行
2. **文件路径**：使用相对路径（相对于 `--media-path`），而非绝对路径
3. **内存要求**：每个服务约占用 2-3GB 内存，确保足够 RAM
4. **Metal 加速**：自动使用 Metal GPU，无需 CUDA 配置
5. **模型下载**：首次运行可能需要下载模型文件（约 1.5-2GB）
6. **确定性输出**：使用 `--temp 0` 确保 OCR 结果一致性
7. **API 兼容性**：完全兼容 OpenAI vision API 格式

### 模型选择建议
- **GLM-OCR**: 适合通用 OCR 场景，特别是英文和图表识别
- **PaddleOCR-VL**: 适合中文 OCR 场景，表格识别效果好
- **对比测试**: 可同时运行两个服务，对比识别效果后选择
- **资源限制**: 如果内存有限（<16GB），建议只运行一个服务