report-detect/archive/docs/OCR_INTEGRATION_README.md

OCR异步处理集成说明

概述

本项目实现了基于RabbitMQ和Flask的异步OCR处理架构。Java Spring Boot应用作为任务生产者提交OCR任务，Python消费者处理OCR请求并返回结果。

架构图

┌─────────────────────────────────────────────────────────────────┐
│                    Java Spring Boot App                         │
│  ┌────────────────┐    ┌──────────────────┐   ┌─────────────┐ │
│  │ TaskController │───▶│ FlaskProcessMgr  │───▶│ Flask App   │ │
│  └────────────────┘    │ (Lifecycle Mgmt) │   │ (Auto-start)│ │
│         │              └──────────────────┘   └─────────────┘ │
│         ▼                         │                             │
│  ┌────────────────┐               │                             │
│  │ OCRTaskService │───┐            │                             │
│  └────────────────┘   │            ▼                             │
│         │              │    ┌───────────────┐                     │
│         ▼              │    │ RabbitMQ      │                     │
│  ┌────────────────┐    │    │ Producer      │                     │
│  │ OCRResultConsumer│◀───┘    └───────────────┘                     │
│  └────────────────┘                                                  │
└─────────────────────────────────────────────────────────────────┘
                                   │ HTTP
                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Python Flask API (localhost:8081)              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  /health     │  │ /api/ocr/pdf │  │ RabbitMQ Consumer     │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│         │                  │                     │               │
│         ▼                  ▼                     ▼               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              pdf_processor.py                             │   │
│  │  - PaddleOCRVL (main)                                     │   │
│  │  - PP-OCRv5 (fallback)                                    │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

部署步骤

1. 环境准备

Linux服务器环境要求

• Java 8+
• Python 3.8+
• RabbitMQ 3.x
• PostgreSQL 12+
• 至少10GB可用磁盘空间（用于OCR模型）

安装依赖

安装RabbitMQ (Ubuntu/Debian):

sudo apt-get install rabbitmq-server
sudo systemctl start rabbitmq-server
sudo systemctl enable rabbitmq-server

# 创建用户（可选，默认使用guest/guest）
sudo rabbitmqctl add_user ocr_user ocr_password
sudo rabbitmqctl set_user_tags ocr_user administrator
sudo rabbitmqctl set_permissions -p / ocr_user ".*" ".*" ".*"

安装Python依赖:

cd /path/to/report-detect-backend
pip install -r requirements.txt

2. 配置应用

编辑 src/main/resources/application.yml:

spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: guest
    password: guest

app:
  ocr:
    flask:
      enabled: true
      host: 127.0.0.1
      port: 8081
    async:
      enabled: true

3. 启动服务

方式1: 使用Maven启动

mvn clean package
java -jar target/report-detect-backend-1.0.0.jar

方式2: 手动启动各组件

1. 启动Flask API:

cd python_api
python ocr_api_server.py

2. 启动RabbitMQ消费者:

cd python_api
# 设置环境变量
export FLASK_HOST=127.0.0.1
export FLASK_PORT=8081
python ocr_task_consumer.py

3. 启动Java应用:

java -jar target/report-detect-backend-1.0.0.jar

4. 验证部署

检查Flask服务:

curl http://localhost:8081/health

预期响应:

{
  "status": "ok",
  "vl_model": true,
  "ocr_model": true
}

检查RabbitMQ队列:

sudo rabbitmqctl list_queues

应该看到:

ocr.tasks    0
ocr.results  0

5. 提交测试任务

curl -X POST http://localhost:8080/report-detect-api/api/tasks \
  -H "satoken: YOUR_TOKEN" \
  -F "file=@test.pdf"

配置选项

application.yml配置

配置项	说明	默认值
app.ocr.flask.enabled	是否启用Flask自动启动	true
app.ocr.flask.host	Flask服务地址	127.0.0.1
app.ocr.flask.port	Flask服务端口	8081
app.ocr.async.enabled	是否启用异步OCR	false
app.ocr.resource-dir	Python资源目录	./ocr-resources
app.ocr.models-dir	OCR模型目录	./models

环境变量

Python消费者支持以下环境变量:

变量名	说明	默认值
RABBITMQ_HOST	RabbitMQ地址	localhost
RABBITMQ_PORT	RabbitMQ端口	5672
RABBITMQ_USER	RabbitMQ用户	guest
RABBITMQ_PASS	RabbitMQ密码	guest
FLASK_HOST	Flask服务地址	127.0.0.1
FLASK_PORT	Flask服务端口	8081

故障排查

Flask服务未启动

症状: 日志显示"Flask health check timeout"

解决方案:

1. 检查Python环境: python --version
2. 检查依赖: pip list | grep -E 'flask|paddleocr'
3. 手动启动Flask查看错误:

   cd ocr-resources
   python ocr_api_server.py
   

RabbitMQ连接失败

症状: 日志显示"Failed to connect to RabbitMQ"

解决方案:

1. 检查RabbitMQ状态: sudo systemctl status rabbitmq-server
2. 检查端口: netstat -an | grep 5672
3. 查看RabbitMQ日志: sudo journalctl -u rabbitmq-server

OCR任务卡在PENDING状态

症状: 任务提交后状态一直是ocr_pending

解决方案:

1. 检查RabbitMQ消费者是否运行
2. 查看消费者日志
3. 检查队列: sudo rabbitmqctl list_queues

开发测试

单独测试Flask API

# 启动Flask
cd python_api
python ocr_api_server.py

# 测试
curl -X POST http://localhost:8081/api/ocr/pdf \
  -H "Content-Type: application/json" \
  -d '{"pdf_path": "/path/to/test.pdf", "output_dir": "output"}'

单独测试RabbitMQ消费者

cd python_api
export RABBITMQ_HOST=localhost
python ocr_task_consumer.py

生产环境建议

1. 使用supervisor管理Python进程

创建 /etc/supervisor/conf.d/ocr-flask.conf:

[program:ocr-flask]
command=/usr/bin/python /path/to/ocr-resources/ocr_api_server.py
directory=/path/to/ocr-resources
autostart=true
autorestart=true
stdout_logfile=/var/log/ocr-flask.log
stderr_logfile=/var/log/ocr-flask-err.log
environment=PORT="8081",HOST="0.0.0.0"

创建 /etc/supervisor/conf.d/ocr-consumer.conf:

[program:ocr-consumer]
command=/usr/bin/python /path/to/ocr-resources/ocr_task_consumer.py
directory=/path/to/ocr-resources
autostart=true
autorestart=true
stdout_logfile=/var/log/ocr-consumer.log
stderr_logfile=/var/log/ocr-consumer-err.log
environment=RABBITMQ_HOST="localhost",FLASK_HOST="127.0.0.1"

2. 使用systemd管理Java应用

3. 配置日志轮转 防止日志文件过大

4. 监控: 使用Prometheus + Grafana监控RabbitMQ队列长度和处理时间