# ddddocr-fastapi

**Repository Path**: liao-junfu/ddddocr-fastapi

## Basic Information

- **Project Name**: ddddocr-fastapi
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 DdddOcr API

![DdddOcr Logo](https://cdn.wenanzhe.com/img/logo.png!/crop/700x500a400a500)

> 基于 FastAPI 和 DdddOcr 的高性能 OCR API 服务，提供图像文字识别功能，支持动态模型选择，与新版本的 DdddOcr 模型兼容。
> filter_colors 是1.6.0新增功能，用于过滤颜色，默认值为 None。（还没发布！）
> [自营各类GPT聚合平台](https://juxiangyun.com)

## 📋 目录

- [系统要求](#系统要求)
- [安装和启动](#安装和启动)
- [API 端点](#api-端点)
- [API 调用示例](#api-调用示例)
- [注意事项](#注意事项)
- [故障排除](#故障排除)
- [许可证](#许可证)

## 💻 系统要求

| 组件 | 版本 |
|------|------|
| 操作系统 | Linux（推荐 Ubuntu 20.04 LTS 或更高版本）/ Windows / macOS |
| Python | 3.8 - 3.12 |
| Docker | 20.10 或更高（可选） |
| Docker Compose | 1.29 或更高（可选） |

## 🚀 安装和启动

### 1. 克隆仓库

```bash
git clone https://github.com/your-repo/ddddocr-api.git
cd ddddocr-api
```

### 2. 安装依赖

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

### 3. 启动服务

本项目支持三种启动方式，您可以根据实际需求选择：

#### a. 使用 Python 命令直接运行

```bash
python app/main.py
```

#### b. 使用 Uvicorn（支持热重载，适合开发）

```bash
uvicorn app.main:app --reload
```

#### c. 使用 Docker 启动

1. 构建 Docker 镜像
   ```bash
   docker build -t ddddocr-api .
   ```

2. 启动镜像
   ```bash
   docker run -d -p 8000:8000 --name ddddocr-api-container ddddocr-api
   ```

### 4. 验证服务

```bash
curl http://localhost:8000/docs
```

> 如果成功，您将看到 Swagger UI 文档页面。

### 5. 停止服务

- 如果使用 Python/Uvicorn 直接运行：
  ```bash
  Press CTRL+C
  ```

- 如果使用 Docker：
  ```bash
  docker stop ddddocr-api-container
  ```

- 如果使用 Docker Compose：
  ```bash
  docker-compose down
  ```

### 6. 查看日志

- 如果使用 Docker：
  ```bash
  docker logs ddddocr-api-container
  ```

- 如果使用 Docker Compose：
  ```bash
  docker-compose logs
  ```

## 🔌 API 端点

### 1. OCR 识别

🔗 **端点**：`POST /ocr`

| 参数 | 类型 | 描述 |
|------|------|------|
| `file` | File | 图片文件（可选） |
| `image` | String | Base64 编码的图片字符串（可选） |
| `probability` | Boolean | 是否返回概率（默认：false） |
| `charsets` | String/Integer | 字符集名称、内置字符集编号或模型标识（可选） |
| `png_fix` | Boolean | 是否进行 PNG 修复（默认：false） |
| `custom_model` | String | 自定义模型名称（可选） |
| `filter_colors` | Array[String] | 过滤颜色列表，仅保留指定颜色的像素（可选） |

### 自定义模型配置

要使用自定义模型，您需要将模型文件放在项目根目录下的 `custom_models` 目录中，文件命名格式如下：

- 模型配置文件：`custom1.json`
- 模型权重文件：`custom1.onnx`

然后，在环境变量中配置 `CUSTOM_MODEL_NAMES`，指定要加载的自定义模型名称，多个模型之间用逗号分隔，例如：

```bash
export CUSTOM_MODEL_NAMES="custom1,captcha"
```

### custom_model 参数详细说明

`custom_model` 参数用于直接指定要使用的自定义模型名称，例如：

- `custom1`：使用名称为 `custom1` 的自定义模型
- `captcha`：使用名称为 `captcha` 的自定义模型

> **注意**：如果指定的自定义模型不存在，API 将回退到默认模型。

### probability 参数详细说明

`probability` 参数用于控制 API 是否返回识别结果的概率值：

- 当 `probability=false` 时，返回的结果为纯字符串，例如：`"1234"`
- 当 `probability=true` 时，返回的结果为包含识别结果和概率的字典，例如：`{"result": "1234", "probability": {"1": 0.99, "2": 0.98, "3": 0.97, "4": 0.96}}`

### png_fix 参数详细说明

`png_fix` 参数用于修复 PNG 图片的问题，特别是针对某些特殊格式的 PNG 图片，例如：

1. **透明背景 PNG**：修复透明背景导致的识别问题
2. **压缩过的 PNG**：修复压缩导致的图像失真问题
3. **损坏的 PNG**：修复部分损坏的 PNG 图片

当您遇到 PNG 图片识别效果不佳时，可以尝试将 `png_fix` 参数设置为 `true`，以提高识别准确率。

### charsets 参数详细说明

`charsets` 参数支持三种用法：

1. **内置字符集编号**（整数类型）：
   - `0`：纯整数 0-9
   - `1`：纯小写英文 a-z
   - `2`：纯大写英文 A-Z
   - `3`：小写英文 a-z + 大写英文 A-Z
   - `4`：小写英文 a-z + 整数 0-9
   - `5`：大写英文 A-Z + 整数 0-9
   - `6`：小写英文 a-z + 大写英文 A-Z + 整数 0-9
   - `7`：默认字符库（除了小写英文 a-z、大写英文 A-Z 和整数 0-9 之外的其他字符）

2. **自定义字符集**（字符串类型）：
   传入一段不包含空格的文本，其中的每个字符均为一个待选词，例如：
   - `0123456789`：只识别数字
   - `abcdefghijklmnopqrstuvwxyz`：只识别小写字母
   - `ABCDEFGHIJKLMNOPQRSTUVWXYZ`：只识别大写字母
   - `abcdefghijklmnopqrstuvwxyz0123456789`：只识别小写字母和数字

### filter_colors 参数详细说明

`filter_colors` 参数用于指定要保留的像素颜色，API 会仅保留与指定颜色匹配的像素。支持的颜色包括：

| 颜色名称 | 中文名称 |
|----------|----------|
| `red` | 红色 |
| `blue` | 蓝色 |
| `green` | 绿色 |
| `yellow` | 黄色 |
| `orange` | 橙色 |
| `purple` | 紫色 |
| `cyan` | 青色 |
| `black` | 黑色 |
| `white` | 白色 |
| `gray` | 灰色 |

**使用示例**：

- `["red"]`：只保留红色像素
- `["green", "blue"]`：只保留绿色和蓝色像素

### API 响应格式

API 返回的响应格式为统一的 JSON 格式，包含以下字段：

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | Integer | 响应状态码，200 表示成功，其他表示失败 |
| `message` | String | 响应消息，描述请求的处理结果 |
| `data` | String/Object | 响应数据，包含识别结果 |

### 响应示例

1. **成功响应**（`probability=false`）：
   ```json
   {
     "code": 200,
     "message": "Success",
     "data": "1234"
   }
   ```

2. **成功响应**（`probability=true`）：
   ```json
   {
     "code": 200,
     "message": "Success",
     "data": {
       "result": "1234",
       "probability": {
         "1": 0.99,
         "2": 0.98,
         "3": 0.97,
         "4": 0.96
       }
     }
   }
   ```

3. **失败响应**：
   ```json
   {
     "code": 400,
     "message": "必须提供图片或base64编码字符串!",
     "data": null
   }
   ```

> **注意**：目前仅实现了 OCR 识别功能，滑动验证码匹配和目标检测功能将在后续版本中添加。

## 📘 API 调用示例

### Python

```python
import requests
import base64

url = "http://localhost:8000/ocr"
image_path = "path/to/your/image.jpg"

with open(image_path, "rb") as image_file:
    encoded_string = base64.b64encode(image_file.read()).decode('utf-8')

data = {
    "image": encoded_string,
    "probability": False,
    "png_fix": False,
    "charsets": 0,  # 使用纯数字字符集
    "custom_model": "captcha",  # 使用 captcha 自定义模型
    "filter_colors": ["red"]  # 只保留红色像素
}

response = requests.post(url, data=data)
print(response.json())
```

### Node.js

```javascript
const axios = require('axios');
const fs = require('fs');

const url = 'http://localhost:8000/ocr';
const imagePath = 'path/to/your/image.jpg';

const imageBuffer = fs.readFileSync(imagePath);
const base64Image = imageBuffer.toString('base64');

const data = {
  image: base64Image,
  probability: false,
  png_fix: false,
  charsets: '0123456789',  // 使用数字字符集
  custom_model: 'custom1',  // 使用 custom1 自定义模型
  filter_colors: ['green', 'blue']  // 只保留绿色和蓝色像素
};

axios.post(url, data)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error);
  });
```

### C#

```csharp
using System;
using System.Net.Http;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "http://localhost:8000/ocr";
        var imagePath = "path/to/your/image.jpg";

        var imageBytes = File.ReadAllBytes(imagePath);
        var base64Image = Convert.ToBase64String(imageBytes);

        var client = new HttpClient();
        var content = new MultipartFormDataContent();
        content.Add(new StringContent(base64Image), "image");
        content.Add(new StringContent("false"), "probability");
        content.Add(new StringContent("false"), "png_fix");
        content.Add(new StringContent("0"), "charsets");
        content.Add(new StringContent("captcha"), "custom_model");
        content.Add(new StringContent("red"), "filter_colors");

        var response = await client.PostAsync(url, content);
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}
```

### PHP

```php
<?php

$url = 'http://localhost:8000/ocr';
$imagePath = 'path/to/your/image.jpg';

$imageData = base64_encode(file_get_contents($imagePath));

$data = array(
    'image' => $imageData,
    'probability' => 'false',
    'png_fix' => 'false',
    'charsets' => 'abcdefghijklmnopqrstuvwxyz',
    'custom_model' => 'custom1',
    'filter_colors' => array('red', 'blue')
);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);

echo $result;
?>
```

### Go

```go
package main

import (
    "bytes"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

func main() {
    apiURL := "http://localhost:8000/ocr"
    imagePath := "path/to/your/image.jpg"

    imageData, err := ioutil.ReadFile(imagePath)
    if err != nil {
        panic(err)
    }

    base64Image := base64.StdEncoding.EncodeToString(imageData)

    data := url.Values{}
    data.Set("image", base64Image)
    data.Set("probability", "false")
    data.Set("png_fix", "false")
    data.Set("charsets", "6")
    data.Set("custom_model", "captcha")
    data.Set("filter_colors", "red")

    resp, err := http.PostForm(apiURL, data)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}
```

### 易语言

```易语言
.版本 2

.程序集 调用OCR接口

.子程序 主函数, 整数型
.局部变量 请求头, QQ.HttpHeaders
.局部变量 请求内容, QQ.HttpMultiData
.局部变量 图片路径, 文本型
.局部变量 图片数据, 字节集
.局部变量 HTTP, QQ.Http

图片路径 ＝ "path/to/your/image.jpg"
图片数据 ＝ 读入文件 (图片路径)

请求头.添加 ("Content-Type", "application/x-www-form-urlencoded")

请求内容.添加文本 ("image", 到Base64 (图片数据))
请求内容.添加文本 ("probability", "false")
请求内容.添加文本 ("png_fix", "false")
请求内容.添加文本 ("charsets", "0")
请求内容.添加文本 ("custom_model", "captcha")
请求内容.添加文本 ("filter_colors", "red")

HTTP.发送POST请求 ("http://localhost:8000/ocr", 请求内容, 请求头)

调试输出 (HTTP.获取返回文本())

返回 (0)
```

> **注意**：使用示例前，请确保安装了必要的依赖库，并根据实际环境修改服务器地址和图片路径。

## ⚠️ 注意事项

1. 确保防火墙允许访问 8000 端口。
2. 生产环境建议配置 HTTPS 和适当的身份验证机制。
3. 定期更新 Docker 镜像以获取最新的安全补丁和功能更新。
4. 对于大量请求，建议使用负载均衡来提高服务的可用性和性能。
5. 对于大型图片，建议先进行压缩处理，以提高识别速度和准确性。

## 🔧 故障排除

遇到问题？请检查以下几点：

1. 确保 Docker 服务正在运行（如果使用 Docker）。
2. 检查容器日志（如果使用 Docker）：
   ```bash
   docker logs ddddocr-api-container
   ```
3. 确保没有其他服务占用 8000 端口：
   ```bash
   lsof -i :8000  # Linux/macOS
   netstat -ano | findstr :8000  # Windows
   ```
4. 检查 Python 版本是否符合要求：
   ```bash
   python --version
   ```
5. 检查依赖是否正确安装：
   ```bash
   pip list | grep -E "fastapi|uvicorn|ddddocr"
   ```

> 如果问题仍然存在，请提交 issue 到本项目的 GitHub 仓库。

## 📄 许可证

本项目采用 MIT 许可证。详情请参见 [LICENSE](LICENSE) 文件。

---

<p align="center">
  Made with ❤️ by sml2h3
</p>