ocr_platform/ocr_tools/daemons

服务端守护进程脚本

本目录包含所有 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

快速开始

基本使用

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

# 启动服务
./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

示例

# 启动 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）

启动方法：

./mineru_vllm_daemon.sh start

服务 URL：

• API 端点: http://localhost:8121
• API 文档: http://localhost:8121/docs

依赖环境：

• conda 环境: mineru2
• 需要安装: mineru-vllm-server

客户端使用：

# 使用 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 配置文件路径

启动方法：

./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/ 中的配置文件

客户端使用：

# 使用 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）

启动方法：

./paddle_vllm_daemon.sh start

服务 URL：

• API 端点: http://localhost:8110
• API 文档: http://localhost:8110/docs

依赖环境：

• conda 环境: paddle

• 需要安装: paddlex 和 genai-vllm-server 插件

  paddlex --install genai-vllm-server
  

客户端使用：

# 使用 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）

启动方法：

./dotsocr_vllm_daemon.sh start

服务 URL：

• API 端点: http://localhost:8101
• API 文档: http://localhost:8101/docs

依赖环境：

• conda 环境: dots.ocr
• 需要安装: vllm
• 需要模型: DotsOCR 模型文件

客户端使用：

# 使用 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）

启动方法：

./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)

客户端使用：

# 使用配置文件调用服务
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）

启动方法：

./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)

客户端使用：

# 使用配置文件调用服务
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 量化）

对比测试：

# 可同时启动两个服务进行对比测试
./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. 权限设置

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

4. 使用 systemd 管理（推荐）

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

[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
• PP-StructureV3 Tool README
• PaddleOCR-VL Tool README
• DotsOCR vL Tool README

注意事项

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），建议只运行一个服务