@anohanafes/aocr

v1.0.0

Published

8 months ago

轻量级离线 OCR 识别库，基于 PP-OCRv4/v5 ONNX 模型，支持 PDF 和图片识别，可无缝集成到 Vue、React 等前端框架

0High
0Medium
0Low

ocr pdf image-recognition text-recognition paddleocr rapidocr pp-ocr onnx vue react chinese-ocr offline-ocr frontend-ocr

AOCR

npm GitHub Stars

📦 仓库地址

GitHub | Gitee | npm

📖 使用文档 | 🐛 报告问题

轻量级离线 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 安装（推荐，需要网络）

# 安装前端包
npm install @anohanafes/aocr

# 安装后端依赖（需要 Python 3.7+）
cd node_modules/@anohanafes/aocr/backend
pip install -r requirements.txt

# 启动后端服务
python app.py

方式二：Git 克隆（包含离线安装包）

从 GitHub 克隆（推荐）：

git clone https://github.com/anohanafes/aocr.git
cd aocr

或从 Gitee 克隆（国内加速）：

git clone https://gitee.com/wang-qiuning/aocr.git
cd aocr

然后选择安装方式：

# 方式 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 启动

🎯 使用示例

基础用法

<!DOCTYPE html>
<html>
<head>
    <script src="pdfJsSource/pdf.min.js"></script>
    <script src="node_modules/@anohanafes/aocr/frontend/ocr-api-config.js"></script>
    <script src="node_modules/@anohanafes/aocr/frontend/ocr-api.js"></script>
</head>
<body>
    <input type="file" id="fileInput" accept="image/*,application/pdf">
    <div id="result"></div>

    <script>
        // 初始化 PDF.js Worker
        pdfjsLib.GlobalWorkerOptions.workerSrc = 'pdfJsSource/pdf.worker.min.js';
        
        // 创建 OCR 实例
        const ocr = new OCRApi();
        
        // 监听文件选择
        document.getElementById('fileInput').addEventListener('change', async (e) => {
            const file = e.target.files[0];
            if (!file) return;
            
            // 识别文件
            const result = await ocr.recognize(file, {
                onProgress: (progress) => {
                    console.log(`${progress.percent}% - ${progress.message}`);
                }
            });
            
            // 显示结果
            if (result.success) {
                document.getElementById('result').innerText = result.text;
            } else {
                alert('识别失败：' + result.message);
            }
        });
    </script>
</body>
</html>

Vue 3 集成

<template>
  <div>
    <input type="file" @change="handleFile" accept="image/*,application/pdf">
    <div>{{ ocrText }}</div>
  </div>
</template>

<script setup>
import { ref } from 'vue';
// 确保已引入 pdf.min.js 和配置 Worker
import OCRApi from '@anohanafes/aocr/frontend/ocr-api.js';

const ocrText = ref('');
const ocr = new OCRApi();

const handleFile = async (event) => {
  const file = event.target.files[0];
  if (!file) return;
  
  const result = await ocr.recognize(file, {
    onProgress: (progress) => {
      console.log(`进度: ${progress.percent}%`);
    }
  });
  
  if (result.success) {
    ocrText.value = result.text;
  }
};
</script>

React 集成

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 (
    <div>
      <input type="file" onChange={handleFile} accept="image/*,application/pdf" />
      <div>{text}</div>
    </div>
  );
}

🔧 配置说明

模型切换

打开 frontend/ocr-api-config.js 修改第 24 行：

model: {
    version: 'v4',  // 'v4' 或 'v5'
    // ...
}

性能对比：

| 模型 | 速度 | 准确率 | 适用场景 | |------|------|--------|----------| | v4 | 6-8秒/页 | 96-98% | 日常文档、批量处理 | | v5 | 10-12秒/页 | 99%+ | 重要文档、复杂场景 |

后端配置

修改 backend/app.py 中的配置：

# 修改端口
app.run(host='0.0.0.0', port=5001)

# 修改最大文件大小
MAX_FILE_SIZE = 50 * 1024 * 1024  # 50MB

📚 API 文档

OCRApi 类

构造函数

const ocr = new OCRApi(config);

参数：

config (Object, 可选) - 配置对象，默认使用 ocr-api-config.js 中的配置

recognize(file, options)

识别图片或 PDF 文件中的文字。

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）

返回值：

{
    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                        # 本文档

🔧 常见问题

# 检查 Python 版本（在线安装需要 3.7+，离线安装需要 3.9）
python --version

# 重新安装依赖
pip install -r backend/requirements.txt

问题： 提示找不到匹配的包或平台不兼容

解决方案：

确认 Python 版本为 3.9（离线包专为此版本构建）
确认平台匹配：
- Windows 使用 offline_packages/
- Linux 使用 offline_packages_linux/
其他 Python 版本请使用在线安装：
```
pip install -r backend/requirements.txt
```

检查后端服务是否启动
访问 http://127.0.0.1:5001/api/health 确认服务可用
检查 ocr-api-config.js 中的后端地址配置

确保已引入 pdf.min.js 和配置 Worker
检查 PDF 文件大小是否超过限制（默认 50MB）
确保 PDF 不是扫描件或图片型 PDF

使用 v4 模型（速度更快）
降低图片质量设置
增加 CPU 核心数或使用更强的 CPU

# 使用 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！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 许可证

本项目采用 MIT 许可证。

🔗 相关链接

👨‍💻 作者

anohanafes

Email: [email protected]
GitHub: @anohanafes

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！