# paddleocr-fastapi

**Repository Path**: m986883511/paddleocr-fastapi

## Basic Information

- **Project Name**: paddleocr-fastapi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PaddleOCRFastAPI

一个可 Docker (Compose) 部署的, 基于 **FastAPI** 和 **PaddleOCR 3.x** 的简易 OCR Web API.

[English](./README.md)

## 版本选择

| PaddleOCR | Branch |
| :--: | :--: |
| **3.x（当前）** | `master` |
| v2.5 | [paddleocr-v2.5](https://github.com/cgcel/PaddleOCRFastAPI/tree/paddleocr-v2.5) |
| v2.7 | [paddleocr-v2.7](https://github.com/cgcel/PaddleOCRFastAPI/tree/paddleocr-v2.7) |

> `master` 分支已适配 PaddleOCR 3.x 的 `predict` API，并返回 3.0 原生结果格式。

## 接口功能

- [x] 局域网范围内路径图片 OCR 识别
- [x] Base64 数据识别
- [x] 上传文件识别（`.jpg` / `.png`）
- [x] 图片 URL 识别
- [x] Swagger 文档 `/docs`（访问 `/` 自动跳转）

## 项目结构

```text
PaddleOCRFastAPI/
├── paddleocr_fastapi/          # 主代码包
│   ├── app.py                  # FastAPI 应用
│   ├── cli.py                  # 命令行入口
│   ├── models/                 # Pydantic 模型
│   ├── routers/ocr.py          # OCR 路由
│   └── utils/                  # 工具与装饰器
├── setup.py
├── requirements.txt
├── Dockerfile
└── docker-compose.yml
```

## 部署方式

### 直接部署

1. 克隆项目

   ```shell
   git clone https://github.com/cgcel/PaddleOCRFastAPI.git
   cd PaddleOCRFastAPI
   ```

2. （推荐）创建虚拟环境

   ```shell
   python3 -m venv .venv
   source .venv/bin/activate
   ```

3. 安装依赖

```shell
pip install -r requirements.txt
pip install paddlepaddle-gpu==3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu129/
pip install -e .
```

nvidia环境和实际版本
```shell
(paddleocr) rr@x86-amd-7332:~/code/PaddleOCRFastAPI$ nvidia-smi 
Fri Jul 10 06:09:25 2026       
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 595.71.05              Driver Version: 595.71.05      CUDA Version: 13.2     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 5080        Off |   00000000:00:10.0 Off |                  N/A |
| 52%   39C    P8             10W /  360W |       4MiB /  16303MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

(paddleocr) rr@x86-amd-7332:~/code/PaddleOCRFastAPI$ pip list |grep paddle
paddleocr                3.7.0
paddleocr-fastapi        0.1.0       /home/rr/code/PaddleOCRFastAPI
paddlepaddle-gpu         3.3.0
paddlex                  3.7.2
```

   > 首次运行时，PaddleOCR 3.x 会自动下载模型到 `~/.paddlex/official_models/`。

4. 配置 API 密钥（公网部署强烈建议）

   ```shell
   cp .env.example .env
   # 编辑 .env，设置 APP_KEY=你的强随机密钥
   ```

   配置后，所有 `/ocr/*` 接口需在请求头携带：

   ```http
   X-App-Key: 你的密钥
   ```

   Swagger 文档页面可点击 **Authorize** 填入密钥。`APP_KEY` 留空则关闭鉴权。

5. 启动服务

   ```shell
   paddleocr-fastapi
   paddleocr-fastapi --port 9000
   paddleocr-fastapi --port 9000 --host 127.0.0.1
   ```

   也可以使用：

   ```shell
   python -m paddleocr_fastapi --port 8000
   uvicorn paddleocr_fastapi.app:app --host 0.0.0.0 --port 8000
   ```

6. 访问 API 文档

   ```text
   http://localhost:8000/
   ```

### Docker 部署

在 `CentOS 7`、`Ubuntu 20.04`、`Ubuntu 22.04`、`Windows 10`、`Windows 11` 中测试成功，需要先安装好 Docker。

1. 克隆并构建镜像

   ```shell
   git clone https://github.com/cgcel/PaddleOCRFastAPI.git
   cd PaddleOCRFastAPI
   docker build -t paddleocrfastapi:latest --network host .
   ```

2. 按需编辑 `docker-compose.yml`

   ```yaml
   services:
     PaddleOCR:
       container_name: paddle_ocr_api
       image: paddleocrfastapi:latest
       environment:
         - TZ=Asia/Hong_Kong
         - OCR_LANGUAGE=ch
       ports:
         - "8000:8000"
       restart: unless-stopped
   ```

3. 启动容器

   ```shell
   docker compose up -d
   ```

## API 接口

| 方法 | 路径 | 说明 |
| :--: | :-- | :-- |
| GET | `/ocr/predict-by-path?image_path=...` | 识别本地图片路径 |
| POST | `/ocr/predict-by-base64` | 识别 Base64 图片 |
| POST | `/ocr/predict-by-file` | 上传 `.jpg` / `.png` 文件 |
| GET | `/ocr/predict-by-url?imageUrl=...` | 识别图片 URL |

## 返回格式

所有接口统一返回：

```json
{
  "resultcode": 200,
  "message": "Success",
  "data": {
    "rec_texts": ["你好", "世界"],
    "rec_scores": [0.99, 0.98],
    "rec_polys": [[[x, y], ...]],
    "rec_boxes": [[x1, y1, x2, y2]],
    "textline_orientation_angles": [0, 0],
    "model_settings": {
      "use_doc_preprocessor": false,
      "use_textline_orientation": true
    },
    "text_det_params": { "...": "..." }
  }
}
```

`data` 为单张图片的 **PaddleOCR 3.0** 识别结果对象（不是数组）。

常用字段：

| 字段 | 说明 |
| :-- | :-- |
| `rec_texts` | 识别出的文本行 |
| `rec_scores` | 对应置信度 |
| `rec_polys` | 每行文字的四边形坐标 |
| `rec_boxes` | 每行文字的矩形框 `[x1, y1, x2, y2]` |

## 切换语言

启动前设置环境变量：

```shell
export OCR_LANGUAGE=ch
paddleocr-fastapi
```

或修改 `paddleocr_fastapi/routers/ocr.py`：

```python
ocr = PaddleOCR(
    use_textline_orientation=True,
    lang=OCR_LANGUAGE,
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
)
```

支持的语言列表见 [PaddleOCR 多语言文档](https://github.com/PaddlePaddle/PaddleOCR/blob/main/doc/doc_en/multi_languages_en.md)。

## 运行截图

API 文档：`/docs`

![Swagger](./screenshots/Swagger.png)

## Todo

- [x] PaddleOCR 3.x 支持
- [x] 图片 URL 识别
- [x] GPU 模式

## License

**PaddleOCRFastAPI** is licensed under the MIT license. Refer to [LICENSE](./LICENSE) for more information.