# fqy-paddleocr

**Repository Path**: azer-coder/fqy-paddleocr

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PaddleOCR Local Service

基于 PaddleOCR 的本地 OCR 识别服务，通过 HTTP API 对外提供文字识别能力，供 Java 等后端工程调用。

---

## 环境要求

| 项目       | 要求                |
|-----------|---------------------|
| OS        | Windows 10 / 11 x64 |
| Python    | 3.12.x              |
| CPU/GPU   | CPU 即可运行，无需 GPU |
| 磁盘空间   | >= 2 GB（模型文件会自动下载缓存到 `~/.paddleocr/`） |

---

## 项目结构

```
fqy-paddleocr/
├── server.py           # 服务入口，FastAPI 应用
├── requirements.txt    # Python 依赖清单
├── API.md              # 接口文档
└── README.md           # 项目文档（本文件）
```

---

## 技术栈

| 组件          | 版本       | 说明                          |
|--------------|-----------|-------------------------------|
| PaddlePaddle | 3.0.0     | 深度学习推理引擎                |
| PaddleOCR    | 2.9.1     | OCR 识别库（兼容 Python 3.12）  |
| FastAPI      | 0.115.12  | HTTP 框架                     |
| Uvicorn      | 0.34.2    | ASGI 服务器                    |

> **版本说明**: PaddleOCR 3.x 依赖 paddlex，其中 pandas<=1.5.3 与 Python 3.12 不兼容，因此选用 2.9.1。

---

## 快速开始

### 1. 安装依赖

```bash
cd fqy-paddleocr
pip install -r requirements.txt
```

### 2. 启动服务

```bash
python server.py
```

启动后输出：

```
INFO:     Initializing PaddleOCR engine (lang=ch) ...
INFO:     PaddleOCR engine (lang=ch) ready.
INFO:     Uvicorn running on http://0.0.0.0:8089 (Press CTRL+C to quit)
```

- 默认端口：**8089**
- 默认监听：**0.0.0.0**（局域网可访问）
- 启动时预加载中文模型，首次启动会自动下载模型文件

### 3. 验证服务

```bash
curl http://localhost:8089/health
# {"status":"ok"}
```

Swagger 在线文档：http://localhost:8089/docs

---

## API 接口

详见 [API.md](API.md)，以下为概览：

| 方法   | 路径          | 说明              |
|--------|-------------|-------------------|
| GET    | /health     | 健康检查           |
| POST   | /ocr/file   | 上传图片文件识别    |
| POST   | /ocr/base64 | Base64 图片识别    |

### 响应格式

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "full_text": "识别到的完整文本",
    "items": [
      {
        "text": "单行文本",
        "confidence": 0.9972,
        "box": [[x1,y1],[x2,y2],[x3,y3],[x4,y4]]
      }
    ]
  }
}
```

---

## Java 调用示例

### Spring RestTemplate

```java
@Service
public class OcrService {

    private final RestTemplate restTemplate = new RestTemplate();
    private static final String OCR_URL = "http://localhost:8089/ocr/file";

    /**
     * 识别图片文件
     */
    public String ocr(File imageFile) {
        MultiValueMap<String, Object> params = new LinkedMultiValueMap<>();
        params.add("file", new FileSystemResource(imageFile));
        params.add("lang", "ch");

        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.MULTIPART_FORM_DATA);

        HttpEntity<MultiValueMap<String, Object>> request =
            new HttpEntity<>(params, headers);

        ResponseEntity<String> response =
            restTemplate.postForEntity(OCR_URL, request, String.class);

        return response.getBody();
    }

    /**
     * 识别 Base64 图片
     */
    public String ocrBase64(byte[] imageBytes) {
        String base64 = Base64.getEncoder().encodeToString(imageBytes);

        MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
        params.add("image", base64);
        params.add("lang", "ch");

        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

        HttpEntity<MultiValueMap<String, String>> request =
            new HttpEntity<>(params, headers);

        ResponseEntity<String> response =
            restTemplate.postForEntity(
                "http://localhost:8089/ocr/base64", request, String.class);

        return response.getBody();
    }
}
```

### OkHttp

```java
OkHttpClient client = new OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(60, TimeUnit.SECONDS)
    .build();

// File upload
File imageFile = new File("/path/to/image.png");
RequestBody body = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("file", imageFile.getName(),
        RequestBody.create(imageFile, MediaType.parse("image/png")))
    .addFormDataPart("lang", "ch")
    .build();

Request request = new Request.Builder()
    .url("http://localhost:8089/ocr/file")
    .post(body)
    .build();

try (Response response = client.newCall(request).execute()) {
    String json = response.body().string();
}
```

---

## 支持的语言

| lang 值    | 语言          |
|-----------|---------------|
| ch        | 中文 + 英文混合 |
| en        | 英文           |
| japan     | 日文           |
| korean    | 韩文           |
| french    | 法文           |
| german    | 德文           |
| arabic    | 阿拉伯文       |
| cyrillic  | 西里尔文       |

> 首次使用某语言时会自动下载对应模型文件，后续请求使用缓存模型。

---

## 架构说明

```
Java Application
       |
       | HTTP (POST multipart/form-data)
       v
+------------------+
|  FastAPI Server   |  :8089
|  (server.py)     |
+------------------+
       |
       | Python call
       v
+------------------+
|   PaddleOCR      |
|   (PaddlePaddle) |
+------------------+
       |
       | Read model
       v
  ~/.paddleocr/
  (local model cache)
```

- **服务层**：FastAPI + Uvicorn 提供高性能异步 HTTP 服务
- **引擎层**：PaddleOCR 封装文本检测 + 方向分类 + 文本识别三阶段 pipeline
- **模型缓存**：按语言懒加载，同一语言的引擎全局单例复用，避免重复加载

---

## 常见问题

### Q: 启动报 `ModuleNotFoundError: No module named 'setuptools'`

```bash
pip install setuptools
```

Python 3.12 默认不再内置 setuptools，PaddlePaddle 运行时需要它。

### Q: 首次请求响应慢

首次请求某个语言会触发模型加载（中文模型约 1-2 秒）。默认启动时已预加载 `ch` 模型，后续请求正常响应。

### Q: 如何修改端口

编辑 `server.py` 最后的 `uvicorn.run()` 调用，修改 `port` 参数：

```python
uvicorn.run(app, host="0.0.0.0", port=9000, log_level="info")
```

### Q: 识别结果为空

- 确认图片中包含可识别的文字
- 确认 `lang` 参数与图片中的文字语言匹配
- 确认图片文件未损坏，格式为 png/jpg/bmp/tiff

### Q: Windows 上出现 ccache 警告

```
UserWarning: No ccache found.
```

此警告无影响，仅与 C++ 扩展编译缓存相关，OCR 推理不受影响，可忽略。