# aocr
**Repository Path**: wang-qiuning/aocr
## Basic Information
- **Project Name**: aocr
- **Description**: 轻量级离线 OCR 识别库，基于 PP-OCRv4/v5 ONNX 模型，支持 PDF 和图片识别，可无缝集成到 Vue、React 等前端框架
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-19
- **Last Updated**: 2025-11-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# AOCR
### 📦 仓库地址
[GitHub](https://github.com/anohanafes/aocr) | [Gitee](https://gitee.com/wang-qiuning/aocr) | [npm](https://www.npmjs.com/package/@anohanafes/aocr)
📖 [使用文档](#-快速开始) | 🐛 [报告问题](https://github.com/anohanafes/aocr/issues)
---
**轻量级离线 OCR 识别库**
基于 PP-OCRv4/v5 ONNX 模型 | 支持 PDF 和图片 | 前后端分离 | 开箱即用
---
## ✨ 特性
- 🚀 **高性能** - v4 模型 6-8秒/页，v5 模型准确率 99%+
- 🎯 **一键切换** - v4/v5 模型只需修改配置文件一行代码
- 📦 **开箱即用** - 无需复杂配置，npm 安装即可使用
- 🔌 **易集成** - 支持 Vue、React 等所有前端框架
- 📱 **完全离线** - 数据不上传云端，保护隐私安全
- 🌐 **跨平台** - Windows、Linux、macOS 全平台支持
- 💾 **离线安装** - 提供 Windows/Linux 离线安装包
---
## 📦 快速开始
> **Python 版本要求：**
> - 在线安装：Python 3.7 - 3.11
> - 离线安装：Python 3.9（离线包针对此版本）
> - 推荐版本：Python 3.9（最稳定）
> **⚠️ 关于离线安装包：**
> - npm 包**不包含**离线安装包（体积过大）
> - 需要离线安装包请使用 **方式二：Git 克隆** 完整仓库
> - 离线包位置：`offline_packages/`（Windows）、`offline_packages_linux/`（Linux）
### 方式一：npm 安装（推荐，需要网络）
```bash
# 安装前端包
npm install @anohanafes/aocr
# 安装后端依赖（需要 Python 3.7+）
cd node_modules/@anohanafes/aocr/backend
pip install -r requirements.txt
# 启动后端服务
python app.py
```
### 方式二：Git 克隆（包含离线安装包）
**从 GitHub 克隆（推荐）：**
```bash
git clone https://github.com/anohanafes/aocr.git
cd aocr
```
**或从 Gitee 克隆（国内加速）：**
```bash
git clone https://gitee.com/wang-qiuning/aocr.git
cd aocr
```
**然后选择安装方式：**
```bash
# 方式 A：在线安装（支持 Python 3.7-3.11）
cd backend
pip install -r requirements.txt
# 方式 B：离线安装（仅支持 Python 3.9）
# Windows:
.\offline_packages\install_offline.bat
# Linux:
chmod +x offline_packages_linux/install_offline.sh
./offline_packages_linux/install_offline.sh
# 启动后端
cd backend # 如果用离线安装，先回到 backend 目录
python app.py
```
后端将在 `http://127.0.0.1:5001` 启动
---
## 🎯 使用示例
### 基础用法
```html
```
### Vue 3 集成
```vue
```
### React 集成
```jsx
import React, { useState } from 'react';
import OCRApi from '@anohanafes/aocr/frontend/ocr-api.js';
function OCRComponent() {
const [text, setText] = useState('');
const ocr = new OCRApi();
const handleFile = async (e) => {
const file = e.target.files[0];
if (!file) return;
const result = await ocr.recognize(file, {
onProgress: (progress) => {
console.log(`进度: ${progress.percent}%`);
}
});
if (result.success) {
setText(result.text);
}
};
return (
);
}
```
---
## 🔧 配置说明
### 模型切换
打开 `frontend/ocr-api-config.js` 修改第 24 行：
```javascript
model: {
version: 'v4', // 'v4' 或 'v5'
// ...
}
```
**性能对比：**
| 模型 | 速度 | 准确率 | 适用场景 |
|------|------|--------|----------|
| **v4** | 6-8秒/页 | 96-98% | 日常文档、批量处理 |
| **v5** | 10-12秒/页 | 99%+ | 重要文档、复杂场景 |
### 后端配置
修改 `backend/app.py` 中的配置：
```python
# 修改端口
app.run(host='0.0.0.0', port=5001)
# 修改最大文件大小
MAX_FILE_SIZE = 50 * 1024 * 1024 # 50MB
```
---
## 📚 API 文档
### OCRApi 类
#### 构造函数
```javascript
const ocr = new OCRApi(config);
```
**参数：**
- `config` (Object, 可选) - 配置对象，默认使用 `ocr-api-config.js` 中的配置
#### recognize(file, options)
识别图片或 PDF 文件中的文字。
```javascript
const result = await ocr.recognize(file, {
onProgress: (progress) => {
console.log(progress.percent, progress.message);
}
});
```
**参数：**
- `file` (File) - 文件对象（图片或 PDF）
- `options.onProgress` (Function, 可选) - 进度回调函数
- `progress.percent` (Number) - 进度百分比 (0-100)
- `progress.message` (String) - 进度消息
- `progress.current` (Number) - 当前页码（仅 PDF）
- `progress.total` (Number) - 总页数（仅 PDF）
**返回值：**
```javascript
{
success: true,
text: "识别的文字内容",
details: [
{
text: "单行文字",
confidence: 0.98,
position: [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
}
],
time: 1.234 // 识别耗时（秒）
}
```
---
## 📁 项目结构
```
aocr/
├── backend/ # 后端服务
│ ├── app.py # Flask API
│ ├── requirements.txt # Python依赖
│ └── uploads/ # 临时文件
├── frontend/ # 前端模块
│ ├── ocr-api.js # OCR API核心
│ ├── ocr-api-config.js # 配置文件
│ └── ocr-api-demo.html # 使用示例
├── models/ # OCR模型
│ ├── ch_PP-OCRv4_det_infer.onnx # v4检测模型
│ ├── ch_PP-OCRv4_rec_infer.onnx # v4识别模型
│ ├── ch_PP-OCRv5_det_infer.onnx # v5检测模型
│ ├── ch_PP-OCRv5_rec_infer.onnx # v5识别模型
│ └── ppocr_keys_v1.txt # v4字典
├── pdfJsSource/ # PDF.js库
│ ├── pdf.min.js
│ ├── pdf.worker.js
│ └── pdf.worker.min.js
├── offline_packages/ # Windows离线包
│ ├── install_offline.bat
│ └── *.whl (30个, 93MB)
├── offline_packages_linux/ # Linux离线包
│ ├── install_offline.sh
│ └── *.whl (30个, 122MB)
└── README.md # 本文档
```
---
## 🔧 常见问题
后端启动失败
```bash
# 检查 Python 版本（在线安装需要 3.7+，离线安装需要 3.9）
python --version
# 重新安装依赖
pip install -r backend/requirements.txt
```
离线包安装失败
**问题：** 提示找不到匹配的包或平台不兼容
**解决方案：**
1. 确认 Python 版本为 3.9（离线包专为此版本构建）
2. 确认平台匹配：
- Windows 使用 `offline_packages/`
- Linux 使用 `offline_packages_linux/`
3. 其他 Python 版本请使用在线安装：
```bash
pip install -r backend/requirements.txt
```
前端无法连接后端
- 检查后端服务是否启动
- 访问 `http://127.0.0.1:5001/api/health` 确认服务可用
- 检查 `ocr-api-config.js` 中的后端地址配置
PDF 识别失败
- 确保已引入 `pdf.min.js` 和配置 Worker
- 检查 PDF 文件大小是否超过限制（默认 50MB）
- 确保 PDF 不是扫描件或图片型 PDF
识别速度慢
- 使用 v4 模型（速度更快）
- 降低图片质量设置
- 增加 CPU 核心数或使用更强的 CPU
Linux 部署
```bash
# 使用 Linux 离线包
chmod +x offline_packages_linux/install_offline.sh
./offline_packages_linux/install_offline.sh
# 或在线安装
pip3 install -r backend/requirements.txt
# 安装系统依赖（PDF支持）
sudo apt-get install poppler-utils # Ubuntu/Debian
sudo yum install poppler-utils # CentOS/RHEL
```
---
## 🛠️ 技术栈
- **后端**: Flask + RapidOCR + ONNX Runtime
- **前端**: 原生 JavaScript（无框架依赖）
- **OCR 引擎**: PP-OCRv4/v5 (PaddleOCR)
- **PDF 处理**: PDF.js + pdf2image
---
## 📝 依赖说明
### Python 版本
- **在线安装**: Python 3.7 - 3.11（pip 会自动下载对应版本的包）
- **离线安装**: Python 3.9（离线包专为此版本构建）
- **推荐版本**: Python 3.9（最稳定，兼容所有安装方式）
### Python 依赖
- Flask - Web 框架
- flask-cors - 跨域支持
- rapidocr-onnxruntime - OCR 引擎
- Pillow - 图像处理
- pdf2image - PDF 转图像
- opencv-python - 图像处理
- onnxruntime - ONNX 推理引擎
### 前端依赖
- pdfjs-dist - PDF 解析（peerDependency）
### 离线包说明
- **Windows**: `offline_packages/` (93 MB, 30个包, Python 3.9)
- **Linux**: `offline_packages_linux/` (122 MB, 30个包, Python 3.9)
- **获取方式**:
- ❌ npm 包不包含（体积太大）
- ✅ Git 克隆完整仓库：
- GitHub: `git clone https://github.com/anohanafes/aocr.git`
- Gitee: `git clone https://gitee.com/wang-qiuning/aocr.git`
- 如需其他 Python 版本，请使用在线安装
---
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
---
## 📄 许可证
本项目采用 [MIT](LICENSE) 许可证。
---
## 🔗 相关链接
- [GitHub](https://github.com/anohanafes/aocr)
- [Gitee 镜像](https://gitee.com/wang-qiuning/aocr)
- [npm 包](https://www.npmjs.com/package/@anohanafes/aocr)
- [问题反馈](https://github.com/anohanafes/aocr/issues)
---
## 👨💻 作者
**anohanafes**
- Email: 519855937@qq.com
- GitHub: [@anohanafes](https://github.com/anohanafes)
---
**如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！**