# 安装与环境配置

> PyPI/源码安装方式、Python 版本要求、平台兼容性、GPU 加速配置与依赖说明

- 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

- `pyproject.toml`
- `requirements.txt`
- `ddddocr/utils/exceptions.py`
- `ddddocr/models/model_loader.py`

---

<details>
<summary>相关源文件</summary>
以下文件用于生成此维基页面：
- [pyproject.toml](pyproject.toml)
- [requirements.txt](requirements.txt)
- [ddddocr/utils/exceptions.py](ddddocr/utils/exceptions.py)
- [ddddocr/models/model_loader.py](ddddocr/models/model_loader.py)
- [README.md](README.md)
</details>

# 安装与环境配置

本页面介绍 DdddOcr（ddddocr）的安装方式、Python 版本要求、平台兼容性、GPU 加速配置以及各依赖库的用途说明。DdddOcr 是一个通用验证码离线本地识别 SDK，采用"最简依赖"设计理念，尽量减少用户的配置成本。

## Python 版本要求

DdddOcr 要求 **Python ≥ 3.10**，官方测试覆盖 Python 3.10 至 3.13。

| 分类器声明 | 来源 |
|-----------|------|
| `Programming Language :: Python :: 3.10` | `pyproject.toml:16` |
| `Programming Language :: Python :: 3.11` | `pyproject.toml:17` |
| `Programming Language :: Python :: 3.12` | `pyproject.toml:18` |
| `Programming Language :: Python :: 3.13` | `pyproject.toml:19` |

> **注意**：低于 3.10 的 Python 版本不受支持，pip 在安装时会直接拒绝。

## 平台兼容性

DdddOcr 支持 64 位主流操作系统，不支持 32 位系统。

| 平台 | CPU 支持 | GPU 支持 | 备注 |
|------|---------|---------|------|
| Windows 64 位 | ✓ | ✓ | 部分版本需安装 [VC 运行库](https://www.ghxi.com/yxkhj.html) |
| Linux x86_64 / ARM64 | ✓ | ✓ | — |
| macOS x64（Intel） | ✓ | ✓ | — |
| macOS ARM64（M1/M2/M3） | ✓ | — | 参考 [Issue #67](https://github.com/sml2h3/ddddocr/issues/67) |

OpenCV 依赖按平台自动区分包名（`opencv-python` vs `opencv-python-headless`），详见下文依赖说明。

Sources: [README.md:73-80](README.md), [pyproject.toml:26-28](pyproject.toml)

## 安装方式

### 从 PyPI 安装（推荐）

```bash
pip install ddddocr
```

这是最简单的方式，pip 会自动解析并安装所有依赖。

### 从源码安装

```bash
git clone https://github.com/sml2h3/ddddocr.git
cd ddddocr
pip install .
```

项目使用 `setuptools` 作为构建后端，`pip install .` 会自动读取 `pyproject.toml` 并完成安装。

Sources: [pyproject.toml:1-4](pyproject.toml)

### 安装可选 API 依赖

如需通过 RESTful API 方式使用 DdddOcr，可安装 `api` 额外依赖组：

```bash
pip install "ddddocr[api]"
# 或从源码
pip install ".[api]"
```

`api` 依赖组包含 FastAPI、Uvicorn、Pydantic 等 Web 服务组件。

Sources: [pyproject.toml:34-39](pyproject.toml)

### Docker 部署

项目提供 `Dockerfile` 和 `docker-compose.yml`，可用于容器化部署 API 服务：

```bash
# 构建并运行
docker build -t ddddocr-api .
docker run -d --name ddddocr-api -p 8000:8000 ddddocr-api

# 或使用 docker-compose
docker-compose up -d
```

容器内可通过环境变量（如 `DDDDOCR_OCR`、`DDDDOCR_BETA`、`DDDDOCR_WORKERS` 等）配置服务参数。

## 核心依赖说明

DdddOcr 的核心运行依赖如下：

| 依赖库 | 最低版本 | 用途 |
|--------|---------|------|
| `numpy` | — | 数值计算，图像数组处理 |
| `onnxruntime` | — | ONNX 模型推理引擎，核心推理后端 |
| `Pillow` | — | 图像读取与格式转换 |
| `opencv-python` | — | 图像处理（Windows / macOS） |
| `opencv-python-headless` | — | 图像处理（Linux，无 GUI 依赖） |

Sources: [pyproject.toml:22-28](pyproject.toml), [requirements.txt:1-5](requirements.txt)

**平台特定 OpenCV 包选择**：在 Linux 服务器环境下自动使用 `opencv-python-headless`（无 GUI 依赖），在 Windows 和 macOS 上使用完整的 `opencv-python`。

```toml
# pyproject.toml 中的平台条件依赖
"opencv-python; sys_platform == 'win32' or sys_platform == 'darwin'",
"opencv-python-headless; sys_platform == 'linux'",
```

### 可选 API 依赖

| 依赖库 | 版本要求 | 用途 |
|--------|---------|------|
| `fastapi` | ≥ 0.68.0 | Web API 框架 |
| `uvicorn` | ≥ 0.15.0 | ASGI 服务器 |
| `python-multipart` | ≥ 0.05 | 文件上传支持 |
| `pydantic` | ≥ 1.8.0, < 3 | 请求/响应数据校验 |
| `requests` | ≥ 2.25.0 | HTTP 客户端（requirements.txt 中） |

Sources: [pyproject.toml:34-39](pyproject.toml), [requirements.txt:6-10](requirements.txt)

## GPU 加速配置

DdddOcr 通过 ONNX Runtime 的 `CUDAExecutionProvider` 支持 GPU 加速推理。启用前需满足以下条件：

1. **安装 NVIDIA CUDA Toolkit**：确保系统已安装与 onnxruntime-gpu 兼容的 CUDA 版本。
2. **安装 onnxruntime-gpu**：替换默认的 `onnxruntime` 为 `onnxruntime-gpu`。
3. **初始化时指定 GPU 参数**：

```python
import ddddocr

# 使用 GPU 加速
ocr = ddddocr.DdddOcr(use_gpu=True, device_id=0)

# 多卡环境下使用第二张 GPU
ocr = ddddocr.DdddOcr(use_gpu=True, device_id=1)
```

GPU 模式下的 ONNX Runtime 提供者配置（来自 `ModelLoader._setup_providers`）：

```python
# ddddocr/models/model_loader.py:36-44
providers = [
    ('CUDAExecutionProvider', {
        'device_id': device_id,
        'arena_extend_strategy': 'kNextPowerOfTwo',
        'gpu_mem_limit': 2 * 1024 * 1024 * 1024,  # 2GB
        'cudnn_conv_algo_search': 'EXHAUSTIVE',
        'do_copy_in_default_stream': True,
    }),
    'CPUExecutionProvider'  # GPU 不可用时自动回退
]
```

**GPU 初始化失败回退机制**：如果 GPU 设置失败（如 CUDA 未安装或驱动不兼容），`ModelLoader` 会自动回退到 CPU 模式并输出警告信息，不会导致程序崩溃。

Sources: [ddddocr/models/model_loader.py:31-53](ddddocr/models/model_loader.py)

## OpenCV 导入问题排查

OpenCV 是最容易出现安装问题的依赖。当导入失败时，`exceptions.py` 中的 `handle_opencv_import_error` 会根据操作系统提供针对性的解决方案：

### Linux 系统

```bash
# Ubuntu/Debian
sudo apt-get install build-essential libglib2.0-0 libsm6 libxext6 libxrender-dev libgl1-mesa-glx

# CentOS/RHEL
sudo yum install gcc gcc-c++ make glib2-devel libSM libXext libXrender mesa-libGL
```

### Windows 系统

- 安装 [Visual C++ 运行库](https://www.ghxi.com/yxkhj.html)
- 确保使用 64 位 Python
- 尝试：`pip install opencv-python --force-reinstall`

### macOS 系统

```bash
# 使用 Homebrew
brew install opencv

# 或使用 conda
conda install opencv
```

M1/M2/M3 芯片用户请参考 [Issue #67](https://github.com/sml2h3/ddddocr/issues/67)。

### 通用解决方案

```bash
pip uninstall opencv-python opencv-python-headless
pip install opencv-python-headless
```

Sources: [ddddocr/utils/exceptions.py:31-81](ddddocr/utils/exceptions.py)

## 构建系统

项目使用现代 Python 打包规范：

- **构建后端**：`setuptools ≥ 64` + `wheel`
- **包发现**：自动发现以 `ddddocr` 开头的子包
- **内嵌资源**：ONNX 模型文件（`*.onnx`）、`logo.png`、`README.md` 随包分发
- **CLI 入口点**：`ddddocr` 命令映射到 `ddddocr.__main__:main`

```toml
# pyproject.toml 关键配置
[project.scripts]
ddddocr = "ddddocr.__main__:main"

[tool.setuptools.package-data]
ddddocr = ["*.onnx", "logo.png", "README.md"]
```

Sources: [pyproject.toml:42-53](pyproject.toml)

## 注意事项

1. **目录命名冲突**：请勿在 `ddddocr` 项目根目录内直接 `import ddddocr`，确保你的开发项目目录名称不为 `ddddocr`，否则会导致模块导入冲突。
2. **实例复用**：`DdddOcr` 对象初始化时会加载 ONNX 模型，耗时较长。应避免在循环中反复创建实例，推荐全局复用同一实例。
3. **ONNX 模型随包安装**：模型文件（`common_old.onnx`、`common.onnx`、`common_det.onnx`）内嵌在包中，无需额外下载。