# paddle-ocr-service

**Repository Path**: nachao/paddle-ocr-service

## Basic Information

- **Project Name**: paddle-ocr-service
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-20
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PaddleOCR 独立服务

一个基于 PaddleOCR 的独立 OCR 识别服务，提供 RESTful API 接口。

## 功能特点

- ✅ 基于 PaddleOCR，中文识别准确率高
- ✅ RESTful API 接口，易于集成
- ✅ 支持图片上传和 Base64 编码
- ✅ 返回文字内容和位置信息（文本框坐标）
- ✅ 支持中英文混合识别
- ✅ 可配置 GPU/CPU 模式
- ✅ 独立服务，可部署到任意服务器

## 安装

### 快速开始（CPU 模式）

如果只需要 CPU 模式，可以直接安装：

```bash
pip install -r requirements.txt

# 安装固定版本（推荐，确保兼容性）
pip install paddlepaddle==2.6.2 paddleocr==2.7.3 numpy==1.24.3 scipy==1.10.1 scikit-image==0.20.0
```

**⚠️ 版本兼容性说明：**
- PaddlePaddle 3.x 存在 OneDNN 兼容性问题，必须使用 2.6.2
- PaddleOCR 3.x 与 PaddlePaddle 2.x 不兼容，必须使用 2.7.3
- numpy 2.x 与 OpenCV/PaddlePaddle 不兼容，必须使用 1.24.x

### 完整配置指南（GPU 模式）

**⚠️ 重要提示：** GPU 模式配置较为复杂，需要多个步骤。如果遇到问题，请参考以下详细步骤。

#### 步骤 1: Python 环境配置

PaddlePaddle 需要 Python 3.8-3.12，推荐使用 pyenv 管理 Python 版本。

**Windows (使用 pyenv-win):**
```bash
# 安装 pyenv-win
git clone https://github.com/pyenv-win/pyenv-win.git %USERPROFILE%\.pyenv\pyenv-win

# 配置环境变量（添加到 ~/.bashrc）
export PYENV_ROOT="$HOME/.pyenv"
export PYENV="$HOME/.pyenv/pyenv-win"
export PATH="$PYENV/bin:$PYENV/shims:$PATH"

# 安装 Python 3.11.0
pyenv install 3.11.0
pyenv local 3.11.0
```

**Linux/Mac:**
```bash
# 安装 pyenv
curl https://pyenv.run | bash

# 配置环境变量（添加到 ~/.bashrc）
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# 安装 Python 3.11.0
pyenv install 3.11.0
pyenv local 3.11.0
```

#### 步骤 2: 安装 CUDA 和 cuDNN

**Windows:**

1. **安装 CUDA 11.8**
   - 下载: https://developer.nvidia.com/cuda-11-8-0-download-archive
   - 运行安装程序，选择"自定义安装"
   - 确保安装到: `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\`

2. **安装 cuDNN 8.6.x**
   - 下载: https://developer.nvidia.com/cudnn（需要注册 NVIDIA 账号）
   - 解压后，将以下文件复制到 CUDA 目录：
     - `bin\*.dll` → `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin\`
     - `include\*.h` → `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\include\`
     - `lib\*.lib` → `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\lib\`

3. **配置环境变量**
   - 添加到系统 PATH:
     - `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin`
     - `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\libnvvp`

**Linux:**
```bash
# 安装 CUDA 11.8
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
sudo sh cuda_11.8.0_520.61.05_linux.run

# 配置环境变量（添加到 ~/.bashrc）
export PATH=/usr/local/cuda-11.8/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH

# 安装 cuDNN
# 下载 cuDNN 8.6.x for CUDA 11.8，解压后复制到 /usr/local/cuda-11.8/
```

详细步骤请参考: [GPU安装步骤.md](./GPU安装步骤.md)

#### 步骤 3: 安装 PaddlePaddle GPU 版本

```bash
# Windows
pip install paddlepaddle-gpu==2.6.2 -f https://www.paddlepaddle.org.cn/whl/windows/mkl/avx/stable.html

# Linux
pip install paddlepaddle-gpu==2.6.2 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html
```

**重要：** 确保安装的版本与 CUDA 版本兼容。PaddlePaddle 2.6.2 需要 CUDA 11.8。

#### 步骤 4: 安装 PaddleOCR 和依赖

```bash
# 安装兼容版本的 PaddleOCR
pip install paddleocr==2.7.3

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

# 安装兼容版本的 numpy 和 scipy
pip install numpy==1.25.2 scipy==1.11.4
```

**版本兼容性说明：**
- PaddlePaddle 2.6.2 需要 numpy < 2.0
- 推荐使用 numpy 1.25.2 和 scipy 1.11.4

#### 步骤 5: 安装 zlibwapi.dll（Windows GPU 模式必需）

**⚠️ 这是最关键的步骤！** cuDNN v8.3+ 在 Windows 上需要 `zlibwapi.dll`（不是普通的 `zlib.dll`）。

**问题：** 如果缺少此文件，会出现错误：
```
Could not load library zlibwapi.dll. Error code 193.
```

**解决方案：**

1. **下载 zlibwapi.dll**
   - 从 NVIDIA 推荐的源下载: `http://www.winimage.com/zLibDll/zlib123dllx64.zip`
   - 如果链接不可用，可以尝试：
     - 使用 curl: `curl -L -o zlib123dllx64.zip "http://www.winimage.com/zLibDll/zlib123dllx64.zip"`
     - 或从其他可信来源搜索 "zlibwapi.dll x64 download"

2. **解压并找到 DLL**
   ```bash
   unzip zlib123dllx64.zip
   # 在 dll_x64 目录中找到 zlibwapi.dll
   ```

3. **复制到正确位置**
   ```bash
   # 复制到 Python 目录（必需）
   cp dll_x64/zlibwapi.dll "C:\Users\<用户名>\.pyenv\pyenv-win\versions\3.11.0\zlibwapi.dll"
   cp dll_x64/zlibwapi.dll "C:\Users\<用户名>\.pyenv\pyenv-win\versions\3.11.0\DLLs\zlibwapi.dll"
   
   # 复制到 CUDA bin 目录（推荐，需要管理员权限）
   cp dll_x64/zlibwapi.dll "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin\zlibwapi.dll"
   ```

4. **验证安装**
   ```python
   import os
   dll_path = r"C:\Users\<用户名>\.pyenv\pyenv-win\versions\3.11.0\zlibwapi.dll"
   print("DLL 存在:", os.path.exists(dll_path))
   ```

**重要提示：**
- 确保下载的是 **64 位版本**（与 Python 架构匹配）
- 文件大小通常在 87-100 KB
- 如果出现 Error Code 193，说明 DLL 架构不匹配（32位 vs 64位）

#### 步骤 6: 验证 GPU 支持

```python
import paddle

# 检查 PaddlePaddle 是否支持 CUDA
print("CUDA 支持:", paddle.device.is_compiled_with_cuda())

# 尝试使用 GPU
try:
    paddle.device.set_device('gpu')
    print("GPU 设备可用")
except Exception as e:
    print(f"GPU 不可用: {e}")
```

#### 步骤 7: 配置服务

修改 `config.py` 或使用环境变量：

```bash
# 启用 GPU
export USE_GPU=True

# 或修改 config.py
USE_GPU = os.getenv('USE_GPU', 'True').lower() == 'true'
```

### 常见问题排查

#### 问题 1: `Could not load library zlibwapi.dll`

**原因：** 缺少 zlibwapi.dll 或架构不匹配

**解决：** 参考步骤 5，确保安装了正确的 64 位版本

#### 问题 2: `cudnn64_8.dll not found`

**原因：** cuDNN 未正确安装或环境变量未配置

**解决：** 
- 检查 cuDNN 文件是否在 CUDA bin 目录
- 确认环境变量 PATH 包含 CUDA bin 目录

#### 问题 3: `numpy._core.multiarray failed to import`

**原因：** numpy 版本不兼容

**解决：**
```bash
pip uninstall numpy
pip install numpy==1.25.2
```

#### 问题 4: Python 版本不兼容

**原因：** PaddlePaddle 需要 Python 3.8-3.12

**解决：** 使用 pyenv 安装兼容版本（推荐 3.11.0）

#### 问题 5: GPU 模式仍然很慢

**可能原因：**
- GPU 驱动版本过旧
- CUDA/cuDNN 版本不匹配
- 模型首次加载需要时间

**解决：**
- 更新 NVIDIA 驱动到最新版本
- 确认 CUDA 和 cuDNN 版本匹配
- 等待模型首次加载完成（约 10-30 秒）

### 性能对比

- **CPU 模式**: 识别一张图片 1-3 秒
- **GPU 模式**: 识别一张图片 0.1-0.5 秒（快 5-10 倍）

### 安装依赖（通用）

```bash
pip install -r requirements.txt
```

### 3. （可选）提前下载模型文件

默认情况下，服务首次运行时会自动联网下载 PaddleOCR 模型（约 100-200MB）。
如果希望在正式部署前就把模型下载到本地，可执行：

```bash
# 下载中文模型（检测/识别/角度分类），保存到 ./models
python download_models.py --langs ch --with-angle-cls --output-dir ./models

# 或下载多种语言
python download_models.py --langs ch,en --with-angle-cls --output-dir ./models
```

下载完成后，在运行服务前设置 `PPOCR_HOME` 环境变量（或在 systemd 中配置）：

```bash
export PPOCR_HOME=/root/app-web/paddle-ocr-service/models
```

这样即使频繁重置 OCR 实例，也只会从本地目录加载模型，无需重复联网。

### 4. （可选）请求限流/冷却时间

如果需要避免短时间内大量请求导致内存飙升，可以设置请求之间的最小间隔：

```bash
export MIN_REQUEST_INTERVAL_SEC=3  # 每个请求之间至少等待 3 秒
```

在 systemd 服务中也可以通过 `Environment="MIN_REQUEST_INTERVAL_SEC=3"` 的方式配置。服务内部会顺序处理请求，在前一个请求完成后等待指定时间再接受下一个。默认情况下不启用该限制。

## 使用方法

### 方式1: Windows 服务安装（推荐 - 后台常驻 + 开机自启）

**适用于 Windows 系统，实现后台常驻和开机自启：**

1. **安装服务（需要管理员权限）**
   ```cmd
   # 右键点击 install_service.bat，选择"以管理员身份运行"
   install_service.bat
   ```
   
   安装脚本会自动：
   - ✅ 下载并配置 NSSM (Non-Sucking Service Manager)
   - ✅ 注册 Windows 服务
   - ✅ 设置开机自启
   - ✅ 配置自动重启（服务异常时）
   - ✅ 配置日志输出

2. **管理服务**
   ```cmd
   # 启动服务
   manage_service.bat start
   
   # 停止服务
   manage_service.bat stop
   
   # 重启服务
   manage_service.bat restart
   
   # 查看状态
   manage_service.bat status
   
   # 查看日志
   manage_service.bat logs
   ```
   
   或使用 Windows 服务管理器：
   ```cmd
   # 启动服务
   net start PaddleOCRService
   
   # 停止服务
   net stop PaddleOCRService
   
   # 查看状态
   sc query PaddleOCRService
   ```

3. **卸载服务**
   ```cmd
   # 右键点击 uninstall_service.bat，选择"以管理员身份运行"
   uninstall_service.bat
   ```

**服务特性：**
- ✅ 后台常驻运行（不占用命令行窗口）
- ✅ 开机自动启动
- ✅ 异常自动重启（10秒延迟）
- ✅ 日志自动保存到 `logs/` 目录
- ✅ 可通过 Windows 服务管理器管理

### 方式2: 智能启动（临时运行）

智能启动脚本会自动检测GPU、安装依赖、优化配置：

**Windows:**
```cmd
smart_start.bat
```

**Linux/Mac:**
```bash
chmod +x smart_start.sh
./smart_start.sh
```

**或直接运行Python脚本：**
```bash
python smart_start.py
```

智能脚本会自动：
- ✅ 检测是否有NVIDIA GPU
- ✅ 自动安装对应版本的依赖（GPU/CPU）
- ✅ 自动优化配置（GPU模式或关闭角度分类）
- ✅ 以最高效方式启动服务

详细说明请查看 [智能启动指南](README_SMART_START.md)

### 方式3: 手动启动

```bash
python app.py
```

服务默认运行在 `http://localhost:5001`

### 配置

**推荐方式：** 使用智能启动脚本，会自动优化配置

**手动配置：** 可以通过环境变量或修改 `config.py` 进行配置：

```bash
# Windows CMD
set USE_GPU=True
set USE_ANGLE_CLS=False
set RETURN_BOXES=False
set PORT=5001

# Linux/Mac
export USE_GPU=True
export USE_ANGLE_CLS=False
export RETURN_BOXES=False
export PORT=5001

# 日志级别
export LOG_LEVEL=INFO
```

**配置说明：**
- `USE_GPU`: 是否使用GPU（有GPU时设为True可提升5-10倍速度）
- `USE_ANGLE_CLS`: 是否使用角度分类（设为False可提升30-50%速度，但图片方向必须正确）
- `RETURN_BOXES`: 是否返回文字位置信息（设为False可提升10-20%解析速度，仅返回文本内容）
- `PORT`: 服务端口（默认5001）

## API 接口

### 1. 健康检查

```bash
GET /health
```

**响应：**
```json
{
  "status": "ok",
  "service": "paddle-ocr-service",
  "version": "1.0.0",
  "paddleocr_available": true,
  "use_gpu": false
}
```

---

### 2. OCR 识别 - 图片文件上传

**接口地址：** `POST /api/ocr/recognize`

**Content-Type：** `multipart/form-data`

**请求参数：**
- `image`: 图片文件（必需，支持 jpg, png, bmp, gif, webp 等格式）
- `use_angle_cls`: 是否使用角度分类（可选，默认 true，设为 false 可提升30-50%速度）
- `lang`: 识别语言（可选，默认 'ch'，支持 'ch', 'en', 'ch_en' 等）
- `return_boxes`: 是否返回文字位置信息（可选，默认 true，设为 false 可提升10-20%解析速度，仅返回文本内容）

**curl 示例：**
```bash
curl -X POST http://localhost:5001/api/ocr/recognize \
  -F "image=@test.png" \
  -F "use_angle_cls=false" \
  -F "lang=ch"
```

**Python 示例：**
```python
import requests

with open('test.png', 'rb') as f:
    files = {'image': f}
    data = {
        'use_angle_cls': 'false',  # 关闭角度分类提升速度
        'lang': 'ch',
        'return_boxes': 'false'  # 不返回位置信息，提升解析速度
    }
    response = requests.post('http://localhost:5001/api/ocr/recognize', files=files, data=data)
    result = response.json()
    print(result['result']['text'])
```

**JavaScript 示例：**
```javascript
const formData = new FormData();
formData.append('image', fileInput.files[0]);
formData.append('use_angle_cls', 'false');
formData.append('lang', 'ch');

fetch('http://localhost:5001/api/ocr/recognize', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log('识别结果:', data.result.text);
});
```

**响应格式：**
```json
{
  "success": true,
  "result": {
    "text": "识别的文字内容",
    "boxes": [
      {
        "text": "文字1",
        "x": 100,
        "y": 200,
        "width": 150,
        "height": 30,
        "confidence": 0.95
      }
    ]
  },
  "elapsed_time": 0.85
}
```

---

### 3. OCR 识别 - Base64 编码

**接口地址：** `POST /api/ocr/recognize_base64`

**Content-Type：** `application/json`

**请求体：**
```json
{
    "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "use_angle_cls": false,
    "lang": "ch",
    "return_boxes": false
}
```

**Python 示例：**
```python
import requests
import base64

# 读取图片并转换为 Base64
with open('test.png', 'rb') as f:
    image_bytes = f.read()
    image_base64 = base64.b64encode(image_bytes).decode('utf-8')

data = {
    'image_base64': f'data:image/png;base64,{image_base64}',
    'use_angle_cls': False,  # 关闭角度分类提升速度
    'lang': 'ch'
}

response = requests.post(
    'http://localhost:5001/api/ocr/recognize_base64',
    json=data
)
result = response.json()
print(result['result']['text'])
```

**JavaScript 示例：**
```javascript
// 将图片转换为 Base64
const reader = new FileReader();
reader.onload = function(e) {
    const imageBase64 = e.target.result;  // data:image/png;base64,...
    
    fetch('http://localhost:5001/api/ocr/recognize_base64', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            image_base64: imageBase64,
            use_angle_cls: false,
            lang: 'ch'
        })
    })
    .then(response => response.json())
    .then(data => {
        console.log('识别结果:', data.result.text);
    });
};
reader.readAsDataURL(fileInput.files[0]);
```

**响应格式：** 与图片文件上传接口相同

---

### 两种接口对比

| 特性 | 图片文件上传 | Base64 编码 |
|------|------------|------------|
| **Content-Type** | multipart/form-data | application/json |
| **适用场景** | 前端表单上传、文件上传 | 前后端API调用、小程序 |
| **数据大小限制** | 16MB | 16MB（Base64编码后约增加33%） |
| **性能** | 相同 | 相同 |
| **推荐场景** | 网页表单上传 | 前后端API集成 |

**建议：**
- 网页表单上传 → 使用图片文件上传接口
- API调用、小程序 → 使用 Base64 接口
- 两种方式识别效果和速度完全相同

### 4. 批量识别

```bash
POST /api/ocr/batch_recognize
Content-Type: multipart/form-data
```

**请求参数：**
- `images`: 多个图片文件

**响应：**
```json
{
  "success": true,
  "results": [
    {
      "filename": "image1.png",
      "result": { ... }
    },
    {
      "filename": "image2.png",
      "result": { ... }
    }
  ]
}
```

## 集成到现有项目

### Python 示例

```python
import requests

# 上传图片识别
with open('test.png', 'rb') as f:
    files = {'image': f}
    response = requests.post('http://localhost:5001/api/ocr/recognize', files=files)
    result = response.json()
    print(result['result']['text'])

# Base64 识别
import base64
with open('test.png', 'rb') as f:
    image_base64 = base64.b64encode(f.read()).decode('utf-8')
    response = requests.post(
        'http://localhost:5001/api/ocr/recognize_base64',
        json={'image_base64': f'data:image/png;base64,{image_base64}'}
    )
    result = response.json()
```

### JavaScript 示例

```javascript
// 上传图片
const formData = new FormData();
formData.append('image', fileInput.files[0]);

fetch('http://localhost:5001/api/ocr/recognize', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log('识别结果:', data.result.text);
});
```

## 性能优化

### GPU 加速

如果有 NVIDIA GPU，可以启用 GPU 加速：

```bash
export USE_GPU=True
```

**注意：** GPU 模式需要完成完整的配置步骤（见上方"完整配置指南"），包括：
- CUDA 11.8 和 cuDNN 8.6.x 安装
- PaddlePaddle GPU 版本安装
- zlibwapi.dll 配置（Windows）
- 正确的 Python 版本（3.8-3.12）

如果配置不完整，服务会自动回退到 CPU 模式。

### 模型缓存

模型文件会自动缓存到 `~/.paddleocr/` 目录，下次启动无需重新下载。

## 部署

### Docker 部署

```dockerfile
FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 5000
CMD ["python", "app.py"]
```

### 生产环境建议

1. 使用 Gunicorn 或 uWSGI 运行
2. 配置 Nginx 反向代理
3. 启用 HTTPS
4. 配置日志轮转

## 常见问题

### Q: 识别速度慢？
A: 
- 可以尝试启用 GPU（需要完成完整配置）
- 关闭角度分类: `export USE_ANGLE_CLS=False`（可提升 30-50% 速度）
- 使用更快的 CPU

### Q: GPU 模式启动失败？
A: 
- 检查 CUDA 和 cuDNN 是否正确安装
- 确认 zlibwapi.dll 已正确安装（Windows）
- 验证 Python 版本在 3.8-3.12 范围内
- 查看详细错误信息，参考上方"常见问题排查"章节

### Q: 中文识别不准确？
A: 确保图片清晰，可以尝试调整图片预处理参数。

### Q: 内存占用高？
A: PaddleOCR 首次加载模型会占用较多内存，建议至少 2GB 可用内存。

### Q: 如何切换到 CPU 模式？
A: 
```bash
# 方法 1: 环境变量
export USE_GPU=False

# 方法 2: 修改 config.py
USE_GPU = os.getenv('USE_GPU', 'False').lower() == 'true'
```

### Q: Windows 上如何获取 zlibwapi.dll？
A: 
1. 从 NVIDIA 推荐源下载: `http://www.winimage.com/zLibDll/zlib123dllx64.zip`
2. 解压后找到 `dll_x64/zlibwapi.dll`
3. 复制到 Python 目录和 CUDA bin 目录
4. 详细步骤见上方"步骤 5: 安装 zlibwapi.dll"

## 许可证

MIT License

## 自定义模型训练

如果您需要对特定场景进行优化，可以训练自定义识别模型。详细的训练指南请参考：

👉 **[训练指南 (README_TRAINING.md)](./README_TRAINING.md)**

### 快速开始

**一键训练（推荐）**：

```bash
# Linux/Mac
chmod +x train.sh
./train.sh

# Windows
train.bat
```

一键训练脚本会自动：
- ✅ 检查环境和依赖
- ✅ 克隆 PaddleOCR 仓库
- ✅ 准备训练数据
- ✅ 下载预训练模型
- ✅ 开始训练

### 训练流程

1. **准备数据**：将图片放在 `raw_images/` 目录（文件名即为标签）
2. **一键训练**：运行 `./train.sh` 或 `train.bat`
3. **测试模型**：使用 `test_trained_model.py` 测试
4. **部署模型**：将训练好的模型集成到服务中

详细的训练说明、目录结构、参数配置等，请查看 [训练指南](./README_TRAINING.md)。

## 参考

- [PaddleOCR 官方文档](https://github.com/PaddlePaddle/PaddleOCR)
- [PaddleOCR 中文文档](https://paddleocr.readthedocs.io/)
- [PaddleOCR 训练教程](https://github.com/PaddlePaddle/PaddleOCR/blob/release/2.7/doc/doc_ch/recognition.md)