# OCR

**Repository Path**: phoenix_pond_chant/OCR

## Basic Information

- **Project Name**: OCR
- **Description**: 插件化 OCR 平台 - 车牌/身份证/发票/通用文字识别 (PaddleOCR/Tesseract) | Plugin-based OCR platform
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-06-12
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OCR Platform v3.0.0
[![Pipeline](https://gitee.com/phoenix_pond_chant/OCR/badges/master/build.svg)](https://gitee.com/phoenix_pond_chant/OCR/pipelines)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Contributing](https://img.shields.io/badge/contributing-welcome-green)](CONTRIBUTING.md)
[![Changelog](https://img.shields.io/badge/changelog-keepachangelog-blue)](CHANGELOG.md)


> 插件化 OCR 识别平台 —— 车牌 · 身份证 · 发票 · 通用文字

## 功能特性

- **插件化引擎** — PaddleOCR / Tesseract / 百度OCR API，通过注册器按需加载
- **流水线处理** — Pipeline 模式：Image → PreProcess → Detect → Recognize → Extract → Result
- **配置驱动** — Pydantic Settings 管理所有配置，支持环境变量 / YAML / .env
- **异步优先** — FastAPI + asyncio，批量处理用 `asyncio.gather` 替代 threading
- **类型安全** — 全面 Type Hint + Pydantic 模型验证
- **错误分级** — 自定义异常层级：OCRError → EngineError / ProcessError / RecognizeError
- **Docker 就绪** — 多阶段构建，一键部署

## 项目结构

```
ocr_platform/
├── core/              # 引擎抽象、流水线、配置、异常
├── engines/           # PaddleOCR / Tesseract / 百度API 引擎
├── processors/        # 预处理 / 区域检测 / 信息提取
├── recognizers/       # 场景识别器（车牌/身份证/发票/文字）
├── api/               # FastAPI 路由与模型
├── services/          # 批量处理服务
├── utils/             # 图像工具、校验工具
├── config/            # YAML 配置
├── tests/             # 测试套件
├── main.py            # 应用入口
├── Dockerfile         # 多阶段构建
└── docker-compose.yml # 编排文件
```

## 快速开始

### 环境要求

- Python 3.9+
- PaddleOCR（首次运行自动下载模型）

### 安装

```bash
# 克隆仓库
git clone https://gitee.com/phoenix_pond_chant/OCR.git
cd OCR

# 安装依赖
pip install -r requirements.txt

# 可选：安装 Tesseract 引擎
pip install pytesseract

# 可选：安装百度 API 引擎
pip install httpx
```

### 启动服务

```bash
# 直接启动
python main.py

# 或使用 uvicorn
uvicorn main:app --host 0.0.0.0 --port 8080
```

访问 http://localhost:8080/docs 查看交互式 API 文档。

### Docker 部署

```bash
# 生产环境
docker-compose up ocr-api

# 开发环境（支持热重载）
docker-compose up ocr-api-dev
```

## API 文档

### 车牌识别

```bash
curl -X POST http://localhost:8080/api/v1/ocr/plate \
  -F "image=@plate.jpg"
```

### 身份证识别

```bash
curl -X POST http://localhost:8080/api/v1/ocr/id_card \
  -F "image=@id_card.jpg" \
  -F "side=front"
```

### 发票识别

```bash
curl -X POST http://localhost:8080/api/v1/ocr/invoice \
  -F "image=@invoice.jpg" \
  -F "invoice_type=vat"
```

### 通用文字识别

```bash
curl -X POST http://localhost:8080/api/v1/ocr/text \
  -F "image=@document.jpg"
```

### 批量处理

```bash
curl -X POST http://localhost:8080/api/v1/ocr/batch \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["<base64_image_1>", "<base64_image_2>"],
    "recognition_type": "text",
    "engine": "paddleocr"
  }'
```

## 配置

所有配置通过环境变量管理（前缀 `OCR_`），或使用 `.env` 文件：

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| OCR_DEFAULT_ENGINE | paddleocr | 默认引擎 |
| OCR_PADDLE_USE_GPU | false | PaddleOCR GPU |
| OCR_TESSERACT_CMD | tesseract | Tesseract 命令路径 |
| OCR_BAIDU_API_KEY | | 百度 OCR API Key |
| OCR_BAIDU_SECRET_KEY | | 百度 OCR Secret Key |
| OCR_BATCH_MAX_CONCURRENCY | 8 | 批量处理并发数 |
| OCR_LOG_LEVEL | INFO | 日志级别 |

## 开发指南

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 带覆盖率
pytest tests/ -v --cov=ocr_platform
```

### 添加新引擎

1. 在 `ocr_platform/engines/` 下创建新文件，继承 `OCREngine`
2. 实现 `recognize()` 方法
3. 在 `api/app.py` 的 `_register_engines()` 中注册

### 添加新识别场景

1. 在 `ocr_platform/recognizers/` 下创建新文件，继承 `BaseRecognizer`
2. 在 `ocr_platform/processors/extractor.py` 中添加提取规则
3. 在 `ocr_platform/api/routes/` 下创建路由
4. 在 `api/app.py` 中注册路由

## License

[MIT](LICENSE)