# 技术概览

> ddddocr 项目定位、整体架构、核心入口与模块职责全景图

- Repository: sml2h3/ddddocr
- GitHub: https://github.com/sml2h3/ddddocr
- Human wiki: https://grok-wiki.com/public/wiki/sml2h3-ddddocr-10e2eae686bf
- Complete Markdown: https://grok-wiki.com/public/wiki/sml2h3-ddddocr-10e2eae686bf/llms-full.txt

## Source Files

- `README.md`
- `pyproject.toml`
- `ddddocr/__init__.py`
- `ddddocr/compat/v1.py`
- `ddddocr/core/__init__.py`
- `ddddocr/core/base.py`

---

<details>
<summary>相关源文件</summary>
以下文件用于生成此维基页面：
- [README.md](README.md)
- [pyproject.toml](pyproject.toml)
- [ddddocr/__init__.py](ddddocr/__init__.py)
- [ddddocr/__main__.py](ddddocr/__main__.py)
- [ddddocr/compat/v1.py](ddddocr/compat/v1.py)
- [ddddocr/core/__init__.py](ddddocr/core/__init__.py)
- [ddddocr/core/base.py](ddddocr/core/base.py)
- [ddddocr/core/ocr_engine.py](ddddocr/core/ocr_engine.py)
- [ddddocr/core/detection_engine.py](ddddocr/core/detection_engine.py)
- [ddddocr/core/slide_engine.py](ddddocr/core/slide_engine.py)
- [ddddocr/api/app.py](ddddocr/api/app.py)
- [ddddocr/models/model_loader.py](ddddocr/models/model_loader.py)
- [ddddocr/utils/__init__.py](ddddocr/utils/__init__.py)
</details>

# 技术概览

本文梳理 ddddocr（v1.6.1）的整体定位、包结构、核心引擎职责以及对外入口形态，帮助开发者在阅读源码前建立全局认知。

---

## 项目定位

ddddocr 是一个**离线、本地运行**的通用验证码识别 Python SDK，由 sml2h3 与 kerlomz 共同开发。项目通过大批量随机数据训练深度网络，以 ONNX 格式分发模型，推理层完全依赖 `onnxruntime`，无需联网即可工作。

核心设计原则是**最简依赖**——`pyproject.toml` 声明的运行时依赖仅 `numpy`、`onnxruntime`、`Pillow` 和 `opencv-python`（或 `opencv-python-headless`），Python 版本要求 ≥ 3.10。

**来源:** [pyproject.toml:6-28]() | [README.md:62-69]()

---

## 功能矩阵

ddddocr 通过初始化参数组合切换三种工作模式：

| 模式 | 典型参数 | 公开方法 | 说明 |
|------|----------|----------|------|
| OCR 文字识别 | `ocr=True, det=False`（默认） | `classification()` | 识别英数、中文、特殊字符验证码 |
| 目标检测 | `ocr=False, det=True` | `detection()` | 返回目标边界框坐标 `[[x1,y1,x2,y2], ...]` |
| 滑块验证码 | `ocr=False, det=False` | `slide_match()` / `slide_comparison()` | 边缘匹配或图像差异比较 |

此外支持 `import_onnx_path` + `charsets_path` 导入自定义模型（由 [dddd_trainer](https://github.com/sml2h3/dddd_trainer) 训练），此时 `ocr`/`det` 参数被忽略。

**来源:** [README.md:107-174]() | [ddddocr/compat/v1.py:72-93]()

---

## 包结构与模块职责

```
ddddocr/
├── __init__.py          # 公开 API 入口，从 compat.v1 导入 DdddOcr
├── __main__.py          # CLI 入口（ddddocr api 子命令）
├── compat/
│   └── v1.py            # 向后兼容外观类 DdddOcr，组合三大引擎
├── core/
│   ├── base.py          # BaseEngine 抽象基类（initialize/predict/switch_device/cleanup）
│   ├── ocr_engine.py    # OCREngine — 文字识别
│   ├── detection_engine.py  # DetectionEngine — 目标检测
│   └── slide_engine.py  # SlideEngine — 滑块匹配（不依赖模型）
├── models/
│   ├── model_loader.py  # ModelLoader — ONNX 模型加载与 Provider 管理
│   └── charset_manager.py  # CharsetManager — 字符集管理与范围过滤
├── preprocessing/
│   ├── image_processor.py  # 图像预处理（尺寸、格式转换）
│   └── color_filter.py     # HSV 颜色过滤
├── utils/
│   ├── image_io.py      # 图片加载、PNG 透明通道修复
│   ├── exceptions.py    # DDDDOCRError / ModelLoadError / ImageProcessError
│   ├── validators.py    # 输入校验（图片、模型配置）
│   └── compat.py        # 向后兼容常量与别名
└── api/
    ├── app.py           # FastAPI 应用定义与全部路由
    ├── server.py        # uvicorn 启动逻辑
    ├── models.py        # Pydantic 请求/响应模型
    └── routes.py        # 路由分组（若存在）
```

**来源:** 通过 `find` 命令枚举 `ddddocr/` 目录下所有 `.py` 文件得到。

---

## 核心架构：兼容层 → 引擎层 → 模型层

### 兼容层（compat/v1.py）

`DdddOcr` 类是唯一的用户入口。它在 `__init__` 中根据参数决定初始化哪个引擎：

```python
# ddddocr/compat/v1.py:72-93
if det:
    self.detection_engine = DetectionEngine(use_gpu, device_id)
elif ocr or import_onnx_path:
    self.ocr_engine = OCREngine(...)
else:
    pass  # 滑块模式，不需要模型
self.slide_engine = SlideEngine()  # 滑块引擎始终可用
```

`classification()`、`detection()`、`slide_match()`、`slide_comparison()` 等方法均为委托调用，先检查模式合法性再转发到对应引擎。

**来源:** [ddddocr/compat/v1.py:72-93]() | [ddddocr/compat/v1.py:95-127]()

### 引擎层（core/）

`BaseEngine`（`core/base.py`）定义了所有引擎的公共接口：

- `initialize()` — 抽象方法，子类实现模型加载
- `predict()` — 抽象方法，子类实现推理逻辑
- `switch_device()` — 运行时切换 CPU/GPU
- `cleanup()` — 释放 `onnxruntime.InferenceSession`

| 引擎 | 文件 | 继承自 BaseEngine | 依赖模型 | 关键方法 |
|------|------|-------------------|----------|----------|
| `OCREngine` | `core/ocr_engine.py` | ✓ | ✓（ONNX） | `predict(image, png_fix, probability, colors)` |
| `DetectionEngine` | `core/detection_engine.py` | ✓ | ✓（ONNX） | `predict(image)` → `List[List[int]]` |
| `SlideEngine` | `core/slide_engine.py` | ✓ | ✗ | `slide_match()` / `slide_comparison()` |

`SlideEngine` 比较特殊——它不调用父类 `__init__`，不需要模型加载器，仅依赖 OpenCV 的边缘检测和图像差分算法。

**来源:** [ddddocr/core/base.py:15-43]() | [ddddocr/core/slide_engine.py:20-29]()

### 模型层（models/）

`ModelLoader`（`models/model_loader.py`）负责：
1. 根据 `use_gpu` 选择 `CUDAExecutionProvider` 或 `CPUExecutionProvider`
2. 从包内资源（`*.onnx` 文件）或自定义路径加载模型
3. 管理 `onnxruntime.InferenceSession` 的生命周期

`CharsetManager`（`models/charset_manager.py`）管理字符集的加载、过滤（`set_ranges()` 支持 0-7 预设或自定义字符串）。

**来源:** [ddddocr/models/model_loader.py:16-30]() | [pyproject.toml:51-52]()

---

## 入口形态

### Python SDK

```python
import ddddocr
ocr = ddddocr.DdddOcr()          # 初始化（加载模型）
result = ocr.classification(img)  # 识别
```

`ddddocr/__init__.py` 将 `DdddOcr` 从 `compat.v1` 导入并重新导出，同时导出 `DdddOcrInputError`、`InvalidImageError` 等异常类和 `base64_to_image`、`get_img_base64` 工具函数。

**来源:** [ddddocr/__init__.py:1-26]()

### CLI（python -m ddddocr api）

`__main__.py` 提供 `ddddocr api` 子命令，将命令行参数写入环境变量后调用 `ddddocr.api.main()` 启动 uvicorn 服务。

**来源:** [ddddocr/__main__.py:8-69]()

### REST API（FastAPI）

`api/app.py` 定义 FastAPI 应用，暴露以下端点：

| 端点 | 方法 | 功能 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/ocr`、`/ocr/file` | POST | 文字识别（Base64 / 文件上传） |
| `/det`、`/det/file` | POST | 目标检测 |
| `/slide_match` | POST | 滑块边缘匹配 |
| `/slide_comparison` | POST | 滑块图像差异比较 |
| `/set_charset_range` | POST | 设置字符范围 |
| `/config` | GET | 查看当前配置与活跃实例数 |

API 层通过 `get_ocr_instance()` 按配置键缓存 `DdddOcr` 实例，并在每次请求后通过 `BackgroundTasks` 异步清理超过 1 小时不活跃的实例。

**来源:** [ddddocr/api/app.py:300-307]() | [ddddocr/api/app.py:330-333]() | [ddddocr/api/app.py:335-404]()

---

## 数据流概览

以 OCR 识别为例，请求从入口到结果的完整路径：

```
用户代码 / HTTP 请求
       │
       ▼
  DdddOcr.classification(image)          ← compat/v1.py
       │
       ▼
  OCREngine.predict(image, ...)          ← core/ocr_engine.py
       │
       ├─ validate_image_input()          ← utils/validators.py
       ├─ load_image_from_input()         ← utils/image_io.py
       ├─ png_rgba_black_preprocess()     ← PNG 透明通道修复
       ├─ ColorFilter.apply()             ← 颜色过滤（可选）
       ├─ ImageProcessor.preprocess()     ← 尺寸/格式预处理
       ├─ session.run()                   ← onnxruntime 推理
       └─ CharsetManager.decode()         ← 索引→字符解码
              │
              ▼
         返回 str 或 {charsets, probability}
```

---

## 运行时依赖与兼容性

| 依赖 | 用途 |
|------|------|
| `onnxruntime` | ONNX 模型推理（CPU/GPU） |
| `numpy` | 图像张量处理 |
| `Pillow` | 图片加载与格式转换 |
| `opencv-python` / `opencv-python-headless` | 预处理、边缘检测、滑块匹配 |

支持平台：Windows 64 位、Linux 64/ARM64、macOS X64（含 Apple Silicon 适配），最大 Python 版本 3.12。不支持 32 位系统。

**来源:** [pyproject.toml:22-28]() | [README.md:73-80]()

---

## 小结

ddddocr 采用**兼容层 → 引擎层 → 模型层**的三层架构：兼容层（`compat/v1.py`）提供稳定的 `DdddOcr` 类接口；引擎层（`core/`）将 OCR、目标检测、滑块匹配三种能力封装为独立引擎，共享 `BaseEngine` 抽象基类；模型层（`models/`）负责 ONNX 模型加载与字符集管理。项目同时提供 Python SDK、CLI 和 FastAPI 三种入口形态，通过最少的依赖实现离线验证码识别的全流程覆盖。