OCR Agent - 扫描图书 OCR 处理系统

一个基于 PaddleOCR 的高性能扫描图书 OCR 处理系统，支持多格式输出、图片修复、版面分析、质量评估和自动纠错。

✨ 主要特性

• 📄 多格式输出：DOCX、PDF、JSON、TXT
• 🖼️ 图片修复：4x 超分辨率、混合去噪（传统+深度学习）
• 📐 版面分析：自动检测标题、段落、表格、图像等
• ✅ 质量评估：自动评估 OCR 质量并提供改进建议
• 🔧 自动纠错：中英文混淆字自动纠正
• 🎯 高精度：支持中英文混合识别
• 🐳 Docker 部署：开箱即用的容器化部署
• 🚀 Web API：FastAPI 异步服务，支持后台处理

🚀 快速开始

安装

使用 pip

# 克隆项目
git clone https://github.com/your-repo/ocr-agent.git
cd ocr-agent

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -e .

使用 Docker（推荐）

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 访问 API
# http://localhost:8000/docs

基本使用

命令行

# 处理单张图片
ocr-agent process image.png -o ./output

# 处理 PDF
ocr-agent process book.pdf -o ./output --format docx --format pdf

# 启动 Web 服务
ocr-agent serve --port 8000

Python API

from ocr_agent.pipeline import OCRPipeline
from ocr_agent.core.config import Config
from pathlib import Path

# 创建配置
config = Config(
    enable_image_repair=True,
    repair_upscale_factor=4,
    enable_correction=True
)

# 创建 Pipeline
pipeline = OCRPipeline(config)

# 处理图片
image_path = Path("image.png")
document = pipeline.process_image(image_path)

# 输出结果
from ocr_agent.modules.output import OutputModule
output = OutputModule(config)
output.generate_docx(document, Path("output.docx"))
output.generate_pdf(document, {0: str(image_path)}, Path("output.pdf"))

Web API

# 上传文件处理
curl -X POST http://localhost:8000/api/v1/jobs \
  -F "file=@image.png" \
  -F "format=docx" \
  -F "format=json"

# 查询状态
curl http://localhost:8000/api/v1/jobs/{job_id}

# 下载结果
curl http://localhost:8000/api/v1/jobs/{job_id}/results/output.docx \
  -o output.docx

📚 文档

• 使用指南 - 完整的功能说明和使用示例
• Docker 部署 - 容器化部署指南
• 设计文档 - 系统架构和设计
• 实现计划 - 功能实现计划
• 项目进度 - 开发进度和统计

🏗️ 项目结构

ocr-agent/
├── src/ocr_agent/
│   ├── core/
│   │   ├── config.py          # 配置管理
│   │   └── models.py          # 数据模型
│   ├── modules/
│   │   ├── preprocessing.py   # 图像预处理
│   │   ├── ocr.py             # OCR 识别
│   │   ├── repair.py          # 图片修复
│   │   ├── layout.py          # 版面分析
│   │   ├── quality.py         # 质量评估
│   │   ├── correction.py      # 自动纠错
│   │   └── output.py          # 输出生成
│   ├── pipeline.py            # 处理流程
│   ├── cli.py                 # 命令行工具
│   └── api.py                 # Web API
├── tests/                     # 测试用例
├── docs/                      # 文档
├── Dockerfile                 # Docker 镜像
├── docker-compose.yml         # Docker Compose
└── pyproject.toml             # 项目配置

🔧 功能说明

图像预处理

• 灰度转换
• 倾斜校正
• 去噪处理
• 对比度增强
• 自适应二值化

OCR 识别

• 中英文混合识别
• 高精度识别（基于 PaddleOCR 2.9）
• 置信度评分

图片修复

• 低分辨率增强：4x/2x 超分辨率（Real-ESRGAN）
• 混合去噪：轻度用传统方法，重度用深度学习
• 质量评估：自动检测模糊、划痕、水渍

版面分析

• 元素检测（标题、段落、列表、表格、图像）
• 阅读顺序检测
• 表格结构识别

质量评估

• 页面级统计
• 区域级分析
• 改进建议

自动纠错

• 中文混淆字纠正
• 英文混淆字纠正
• 置信度控制

📊 性能指标

操作	时间	内存
处理单页图片（无修复）	2-5 秒	500MB
处理单页图片（4x 修复）	5-10 秒	1.5GB
处理 100 页 PDF	5-10 分钟	2GB
生成 DOCX	< 1 秒	100MB
生成 PDF	1-2 秒	200MB

🐳 Docker 部署

快速启动

# 使用 docker-compose
docker-compose up -d

# 查看日志
docker-compose logs -f ocr-agent

# 停止服务
docker-compose down

生产部署

# 使用 Nginx 反向代理
docker-compose up -d

# 配置 SSL/TLS（可选）
# 详见 docs/DOCKER_DEPLOYMENT.md

🧪 测试

# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/test_repair.py -v

# 生成覆盖率报告
pytest tests/ --cov=src/ocr_agent --cov-report=html

📦 依赖

核心依赖

• opencv-python>=4.8.0 - 图像处理
• numpy>=1.24.0 - 数值计算
• pillow>=10.0.0 - 图像库
• python-docx>=1.1.0 - DOCX 生成
• click>=8.0.0 - CLI 工具
• realesrgan>=0.3.0 - 超分辨率
• basicsr>=1.4.2 - 基础 SR 库

可选依赖

• reportlab>=3.6.0 - PDF 生成
• fastapi>=0.100.0 - Web 框架
• uvicorn>=0.23.0 - ASGI 服务器

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📝 许可证

MIT License - 详见 LICENSE

📞 联系方式

• 提交 Issue：GitHub Issues
• 讨论：GitHub Discussions

🙏 致谢

• PaddleOCR - OCR 识别
• Real-ESRGAN - 超分辨率
• reportlab - PDF 生成

---

最后更新: 2026-05-21

项目统计:

• 📝 代码行数：~3500+
• 🧪 测试用例：118+
• 📚 文档数：11+
• 🐳 Docker 配置：3