# ocr-pdf

**Repository Path**: minyang2018/ocr-pdf

## Basic Information

- **Project Name**: ocr-pdf
- **Description**: 这是一个基于Flask的PDF双层转换API服务，集成了OCR识别、图像修复和任务队列管理系统。系统支持PDF、OFD等文档格式的智能转换，提供稳定可靠的异步处理能力。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-13
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PDF双层转换API服务

## 项目概述

这是一个基于Flask的PDF双层转换API服务，集成了OCR识别、图像修复和任务队列管理系统。系统支持PDF、OFD等文档格式的智能转换，提供稳定可靠的异步处理能力。

## 核心特性

### 🚀 文档转换功能
- **多格式支持**: PDF、OFD文档转换
- **智能OCR**: 基于RapidOCR的高精度文字识别
- **图像修复**: 自动图像纠偏和优化处理，采用单例模式优化性能（提升99.99%）
- **双层PDF**: 生成可搜索的双层PDF文档

### ⚡ 任务队列系统
- **异步处理**: 基于任务队列的异步文档转换
- **优先级管理**: 支持任务优先级设置（1-10级）
- **状态跟踪**: 实时任务状态监控和进度查询
- **容错机制**: 自动重试和错误处理
- **队列管理**: 任务查询、删除、插队等管理功能

### 🔒 安全特性
- **API密钥认证**: 基于X-API-Key的身份验证
- **安全中间件**: 请求验证和权限控制
- **日志审计**: 完整的操作日志记录

### 🧹 文件管理
- **自动文件清理**: 删除任务时自动清理相关文件
- **定期清理**: 24小时自动清理已完成任务的临时文件
- **手动清理**: 支持手动批量清理已完成任务
- **模拟运行**: 支持清理操作的模拟运行模式

## 系统架构

```
PDF双层转换API服务
├── API服务器 (Flask)
│   ├── 文档转换接口 (/api/upload)
│   ├── 状态查询接口 (/api/status/<task_id>)
│   ├── 任务队列API (/api/tasks)
│   └── 监控API (/api/monitoring)
├── 任务队列系统
│   ├── 队列管理器 (TaskQueueManager)
│   ├── 任务存储 (TaskStorage)
│   └── 任务处理器 (TaskProcessor)
├── 文档处理服务
│   ├── 文档处理器 (DocumentProcessor)
│   └── 任务处理器 (DocumentTaskProcessor)
└── 工具模块
    ├── 图像处理 (image_utils.py)
    ├── OCR识别 (custom_vis_res.py)
    └── 文件处理 (file_utils.py)
```

## 快速开始

### 环境要求
- Python 3.8+
- 虚拟环境 (推荐)

### 安装依赖

#### 方法一：使用清华源安装依赖（推荐）
```bash
# 使用清华源安装所有依赖
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ -r requirements.txt
```

#### 方法二：配置永久清华源

项目已包含 `pip.conf` 配置文件，你可以将其复制到以下位置之一：

**Windows系统：**
```bash
# 复制到用户目录
copy pip.conf %APPDATA%\pip\pip.ini

# 或者复制到虚拟环境目录
copy pip.conf .venv\pip.ini
```

**配置完成后，直接使用以下命令安装：**
```bash
pip install -r requirements.txt
```

### 启动服务
```bash
python api_server.py
```

服务启动后，默认监听 `http://0.0.0.0:5000`

## API接口文档

### 健康检查接口
- **URL**: `GET /api/health`
- **描述**: 检查服务状态
- **响应**: 
```json
{
    "code": 0,
    "data": {
        "service": "PDF双层转换API服务",
        "status": "healthy",
        "version": "1.0.0",
        "timestamp": "2025-11-13 09:18:39"
    },
    "message": "服务运行正常"
}
```

### 文档上传接口
- **URL**: `POST /api/upload`
- **认证**: 需要X-API-Key头部
- **参数**:
  - `file`: 上传的文档文件
  - `output_format`: 输出格式 (pdf/ofd)
  - `enable_restoration`: 是否启用图像修复（可选，默认为true）
- **响应**:
```json
{
    "code": 0,
    "data": {
        "task_id": "任务唯一标识",
        "status": "pending",
        "message": "任务已提交到队列"
    },
    "message": "文档上传成功"
}
```

### 状态查询接口
- **URL**: `GET /api/status/<task_id>`
- **认证**: 需要X-API-Key头部
- **响应**:
```json
{
    "code": 0,
    "data": {
        "task_id": "任务唯一标识",
        "status": "processing",
        "progress": 50,
        "task_queue_integrated": true,
        "queue_info": {
            "task_type": "document_conversion",
            "priority": 5,
            "created_at": "2025-11-13 09:18:39"
        }
    },
    "message": "状态查询成功"
}
```

### 任务队列API
- **URL**: `GET /api/tasks`
- **认证**: 需要X-API-Key头部
- **描述**: 获取当前任务队列状态
- **响应**:
```json
{
    "code": 0,
    "data": [
        {
            "task_id": "任务ID",
            "task_type": "document_conversion",
            "status": "processing",
            "priority": 5,
            "created_at": "2025-11-13 09:18:39"
        }
    ],
    "message": "任务列表获取成功"
}
```

## 项目依赖说明

### 核心依赖
- **flask**: Web框架
- **rapidocr**: OCR识别核心库
- **opencv-python**: 图像处理
- **numpy**: 数值计算
- **pillow**: 图像处理
- **requests**: 网络请求
- **onnxruntime**: 模型推理
- **rapid_undistorted**: 图像纠偏核心库

### 任务队列依赖
- **sqlite3**: 任务存储数据库
- **threading**: 多线程处理
- **queue**: 队列管理

## 配置说明

### API密钥配置
在请求头中添加X-API-Key进行认证：
```bash
curl -H "X-API-Key: your-api-key" http://localhost:5000/api/health
```

### 任务队列配置
任务队列配置位于 `config.py`，支持自定义：
- 队列容量
- 任务超时时间
- 重试次数
- 优先级设置

## 测试

### 运行集成测试
```bash
python test_integration.py
```

### 运行单元测试
```bash
python -m pytest tests/
```

## 故障排除

### 常见问题
1. **依赖安装失败**: 使用清华源重试
2. **API密钥错误**: 检查请求头中的X-API-Key
3. **任务队列满**: 检查队列容量设置
4. **OCR模型加载失败**: 检查网络连接和模型文件

### 日志文件
- 服务日志: `logs/api_server.log`
- 安全日志: `logs/security_audit.log`

## 贡献指南

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request

## 许可证

本项目采用MIT许可证。