DeepSeek-OCR 完整应用

基于 DeepSeek-OCR 模型的企业级 OCR 应用（MVP 版本）。

🎯 项目概述

这是一个完整的 OCR (光学字符识别) 应用，包括：

• 后端：FastAPI + SQLAlchemy + Mock OCR 引擎
• 前端：React + TypeScript + Vite
• 测试：Pytest 单元测试

📁 项目结构

/home/ubuntu/ocr/code/
├── backend/                 # 后端服务
│   ├── app/                # 应用代码
│   │   ├── api/v1/        # API 路由
│   │   ├── core/          # OCR 引擎
│   │   ├── models/        # 数据库模型
│   │   ├── schemas/       # Pydantic 模型
│   │   ├── services/      # 业务逻辑
│   │   └── db/            # 数据库配置
│   ├── tests/             # 单元测试
│   ├── requirements.txt   # Python 依赖
│   ├── run.sh             # 启动脚本
│   └── README.md          # 后端文档
│
├── frontend/              # 前端应用
│   ├── src/
│   │   ├── components/    # React 组件
│   │   ├── services/      # API 服务
│   │   └── App.tsx        # 主应用
│   ├── package.json       # 前端依赖
│   └── README.md          # 前端文档
│
└── README.md              # 总文档（本文件）

🚀 快速开始

前置要求

• Python 3.10+
• Node.js 18+
• npm 或 pnpm

1. 启动后端

cd /home/ubuntu/ocr/code/backend

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

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

# 启动服务
./run.sh
# 或
python app/main.py

后端服务将在 http://localhost:8000 启动

API 文档: http://localhost:8000/api/docs

2. 启动前端

打开新终端：

cd /home/ubuntu/ocr/code/frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

前端应用将在 http://localhost:3000 启动

3. 运行测试

cd /home/ubuntu/ocr/code/backend

# 运行所有测试
./run_tests.sh
# 或
pytest -v

📖 使用流程

1. 访问前端: 打开 http://localhost:3000
2. 上传图片: 选择 JPG、PNG、PDF 或 TIFF 格式的图片
3. 等待识别: 系统自动上传并进行 OCR 识别（约 2-3 秒）
4. 查看结果: 识别完成后显示文本内容、置信度等信息

🔧 功能特性

后端功能

• ✅ 文件上传和管理
• ✅ OCR 文字识别（Mock 模式）
• ✅ 任务队列和进度跟踪
• ✅ RESTful API
• ✅ 自动生成 API 文档 (Swagger/ReDoc)
• ✅ SQLite 数据库
• ✅ 完整的单元测试
• ✅ 错误处理和日志记录

前端功能

• ✅ 文件拖拽上传（计划中）
• ✅ 实时进度显示
• ✅ 识别结果展示
• ✅ Markdown 格式支持
• ✅ 响应式设计

📚 API 文档

核心端点

端点	方法	说明
/api/v1/health	GET	健康检查
/api/v1/upload	POST	上传文件
/api/v1/recognize	POST	提交 OCR 任务
/api/v1/recognize/{task_id}/status	GET	查询任务状态
/api/v1/recognize/{task_id}/result	GET	获取识别结果
/api/v1/tasks	GET	任务列表
/api/v1/tasks/statistics	GET	任务统计

详细文档请访问: http://localhost:8000/api/docs

🧪 测试

后端测试

cd backend

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_api/test_health.py

# 查看覆盖率
pytest --cov=app tests/

# 详细输出
pytest -v

测试覆盖：

• ✅ 健康检查 API
• ✅ 文件上传 API
• ✅ OCR 识别流程
• ✅ 任务管理 API

前端测试

cd frontend

# 运行测试（如果配置了）
npm run test

🔄 工作流程

用户上传图片
    ↓
前端调用 /upload API
    ↓
后端保存文件到本地存储
    ↓
前端调用 /recognize API
    ↓
后端创建任务并后台处理
    ↓
OCR 引擎识别文本
    ↓
保存结果到数据库
    ↓
前端轮询 /status API
    ↓
识别完成，显示结果

🎨 技术栈

后端

• FastAPI - 现代 Web 框架
• SQLAlchemy - ORM
• Pydantic - 数据验证
• Pillow - 图像处理
• Pytest - 测试框架

前端

• React 18 - UI 框架
• TypeScript - 类型安全
• Vite - 构建工具
• Axios - HTTP 客户端

📝 配置说明

后端配置

编辑 backend/.env:

# 应用配置
DEBUG=True
PORT=8000

# OCR 模式
USE_MOCK_OCR=True  # True=模拟模式，False=真实OCR

# 数据库
DATABASE_URL=sqlite:///./ocr.db

# 文件存储
UPLOAD_DIR=./storage/uploads

前端配置

编辑 frontend/src/services/api.ts:

const API_BASE_URL = 'http://localhost:8000/api/v1'

🔐 安全注意事项

• ⚠️ 当前版本为 MVP，未包含用户认证
• ⚠️ 生产环境请配置 CORS 白名单
• ⚠️ 生产环境请使用 HTTPS
• ⚠️ 建议限制文件上传大小和类型

📦 生产部署

使用 Docker（推荐）

# 待实现
# docker-compose up -d

手动部署

1. 后端:

   # 使用 gunicorn
   gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker

2. 前端:

   npm run build
   # 使用 nginx 部署 dist/ 目录

🔧 故障排查

问题：后端启动失败

# 检查端口占用
lsof -i :8000

# 检查依赖
pip list

# 查看日志
tail -f logs/app.log

问题：前端无法连接后端

1. 检查后端是否运行: http://localhost:8000/api/v1/health
2. 检查 CORS 配置: backend/app/config.py
3. 检查防火墙设置

问题：测试失败

# 清理环境
rm -rf __pycache__ .pytest_cache

# 重新运行
pytest -v

🚧 后续开发计划

MVP v2.0

• 真实 OCR 引擎集成
• Celery 异步任务队列
• MinIO/S3 对象存储
• 用户认证和授权
• 批量文件处理
• 导出功能（PDF、Word）

未来功能

• 移动端应用
• 多语言识别
• 表格识别
• 公式识别
• API 限流和配额

📄 相关文档

• 后端设计文档
• 前端设计文档
• 项目计划

🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📜 License

MIT License

👥 联系方式

项目地址: /home/ubuntu/ocr/code

---

Happy Coding! 🎉