# 安装与第一次运行

> 从 pip 安装到跑通第一个验证码识别的完整步骤，包括 Docker 方式。

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

## Source Files

- `pyproject.toml`
- `requirements.txt`
- `Dockerfile`
- `docker-compose.yml`
- `ddddocr/__main__.py`
- `examples/basic_ocr.py`

---

<details>
<summary>相关源文件</summary>

以下文件用于生成此维基页面：

- [pyproject.toml](pyproject.toml)
- [requirements.txt](requirements.txt)
- [Dockerfile](Dockerfile)
- [docker-compose.yml](docker-compose.yml)
- [ddddocr/__main__.py](ddddocr/__main__.py)
- [ddddocr/__init__.py](ddddocr/__init__.py)
- [ddddocr/api/app.py](ddddocr/api/app.py)
- [examples/basic_ocr.py](examples/basic_ocr.py)
- [examples/api_client.py](examples/api_client.py)
</details>

# 安装与第一次运行

本页面介绍如何从零开始安装 DdddOcr 并成功运行第一个验证码识别程序。无论你是想在本地 Python 脚本中直接调用，还是通过 Docker 部署一个 HTTP API 服务，这里都有完整步骤。

DdddOcr 是一个离线的通用验证码识别 SDK，核心依赖 ONNX Runtime 做推理，不需要联网即可使用。安装完成后，只需 5 行代码就能识别一张验证码图片。

---

## 环境要求

在安装之前，请确认你的环境满足以下条件：

| 要求 | 最低版本 | 说明 |
|------|----------|------|
| Python | 3.10 | 支持 3.10、3.11、3.12、3.13 |
| 操作系统 | — | Windows 64 位、Linux 64/ARM64、macOS X64 |
| 磁盘空间 | ~200MB | 主要用于 ONNX 模型文件和依赖包 |

> **不支持**：Windows 32 位、Linux 32 位系统。macOS M1/M2/M3 (ARM) 芯片用户需参考 [issue #67](https://github.com/sml2h3/ddddocr/issues/67)。

Sources: [pyproject.toml:10-21](pyproject.toml#L10-L21)

---

## 方式一：从 PyPI 安装（推荐）

最简单的安装方式，一条命令搞定：

```bash
pip install ddddocr
```

安装完成后，`pip` 会自动拉取以下依赖：

| 依赖包 | 用途 |
|--------|------|
| `numpy` | 数值计算 |
| `onnxruntime` | ONNX 模型推理引擎 |
| `Pillow` | 图片读取与处理 |
| `opencv-python` (Windows/macOS) 或 `opencv-python-headless` (Linux) | 图像处理（滑块匹配、颜色过滤等） |

如果需要同时使用内置的 HTTP API 服务功能，安装时加上 `[api]` 额外依赖：

```bash
pip install "ddddocr[api]"
```

这会额外安装 `fastapi`、`uvicorn`、`python-multipart` 和 `pydantic`。

Sources: [pyproject.toml:22-39](pyproject.toml#L22-L39)

---

## 方式二：从源码安装

适合需要修改源码或参与开发的用户：

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

如果需要 API 依赖：

```bash
pip install ".[api]"
```

> **注意**：请勿在 ddddocr 项目根目录内直接 `import ddddocr`，否则会因目录名冲突导致导入失败。请确保你的工作目录名称不是 `ddddocr`。

Sources: [pyproject.toml:44-53](pyproject.toml#L44-L53)

---

## 方式三：Docker 部署（API 服务）

如果你想以 HTTP API 的方式对外提供验证码识别服务，可以使用 Docker 一键部署。

### 构建镜像

```bash
docker build -t ddddocr-api .
```

镜像基于 `python:3.10-slim`，会自动安装系统依赖（`libgl1-mesa-glx`、`libglib2.0-0` 等 OpenCV 所需库）和 Python 依赖。

### 运行容器

```bash
docker run -d --name ddddocr-api -p 8000:8000 ddddocr-api
```

启动后，API 服务默认监听 `0.0.0.0:8000`，可通过环境变量覆盖配置：

```bash
docker run -d --name ddddocr-api \
  -p 8000:8000 \
  -e DDDDOCR_OCR=true \
  -e DDDDOCR_BETA=true \
  -e DDDDOCR_WORKERS=4 \
  ddddocr-api
```

### 使用 Docker Compose

项目提供了 `docker-compose.yml`，启动更简洁：

```bash
docker-compose up -d
```

也可以通过环境变量自定义配置：

```bash
DDDDOCR_BETA=true DDDDOCR_WORKERS=4 docker-compose up -d
```

### Docker 环境变量一览

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `DDDDOCR_HOST` | 0.0.0.0 | 服务绑定地址 |
| `DDDDOCR_PORT` | 8000 | 服务监听端口 |
| `DDDDOCR_WORKERS` | 1 | uvicorn 工作进程数 |
| `DDDDOCR_OCR` | true | 是否启用 OCR |
| `DDDDOCR_DET` | false | 是否启用目标检测 |
| `DDDDOCR_BETA` | false | 是否使用 Beta 模型 |
| `DDDDOCR_USE_GPU` | false | 是否使用 GPU 加速 |
| `DDDDOCR_SHOW_AD` | true | 是否显示广告 |

容器内置健康检查，每 30 秒访问 `http://localhost:8000/health`。

Sources: [Dockerfile:1-77](Dockerfile), [docker-compose.yml:1-80](docker-compose.yml), [ddddocr/api/app.py:319-328](ddddocr/api/app.py#L319-L328)

---

## 第一次运行：本地 Python 脚本

安装完成后，用以下代码识别一张验证码图片：

```python
import ddddocr

# 初始化（只需一次，会加载模型）
ocr = ddddocr.DdddOcr(show_ad=False)

# 读取图片
with open("captcha.jpg", "rb") as f:
    image = f.read()

# 识别
result = ocr.classification(image)
print(result)
```

这就是全部代码。`DdddOcr()` 初始化时会加载内置的 ONNX 模型，第一次调用可能需要几秒钟，之后复用同一个实例即可。

### 使用示例脚本

仓库的 `examples/` 目录提供了多个现成示例：

```bash
# 基础 OCR 识别
python examples/basic_ocr.py path/to/captcha.jpg

# 带概率输出
python examples/basic_ocr.py path/to/captcha.jpg --probability

# 使用 Beta 模型
python examples/basic_ocr.py path/to/captcha.jpg --beta
```

`basic_ocr.py` 的核心逻辑非常简洁：创建 `DdddOcr` 实例，读取图片字节，调用 `classification()` 方法，打印结果。

Sources: [examples/basic_ocr.py:1-82](examples/basic_ocr.py), [ddddocr/__init__.py:1-27](ddddocr/__init__.py)

---

## 第一次运行：HTTP API 服务

如果你更希望通过 HTTP 接口调用，可以启动内置的 API 服务。

### 启动服务

```bash
# 使用默认配置（OCR 模式，端口 8000）
python -m ddddocr api

# 自定义配置
python -m ddddocr api --host 0.0.0.0 --port 8080 --workers 4 --beta true
```

服务启动后，访问 `http://localhost:8000/docs` 可查看 Swagger 交互式文档。

### 调用 API

```python
import requests
import base64

# 读取图片并 Base64 编码
with open("captcha.png", "rb") as f:
    img_base64 = base64.b64encode(f.read()).decode()

# 发送 OCR 请求
response = requests.post(
    "http://localhost:8000/ocr",
    json={"image": img_base64}
)

print(response.json()["result"])
```

或者使用文件上传方式：

```python
import requests

with open("captcha.png", "rb") as f:
    response = requests.post(
        "http://localhost:8000/ocr/file",
        files={"file": f}
    )

print(response.json()["result"])
```

### 主要 API 端点

| 端点 | 方法 | 功能 |
|------|------|------|
| `/ocr` | POST | OCR 文字识别（Base64） |
| `/ocr/file` | POST | OCR 文字识别（文件上传） |
| `/det` | POST | 目标检测 |
| `/slide_match` | POST | 滑块匹配 |
| `/slide_comparison` | POST | 滑块差异比较 |
| `/health` | GET | 健康检查 |
| `/docs` | GET | Swagger 文档 |

Sources: [ddddocr/__main__.py:1-79](ddddocr/__main__.py), [ddddocr/api/app.py:335-404](ddddocr/api/app.py#L335-L404), [examples/api_client.py:1-72](examples/api_client.py)

---

## 初始化参数速查

`DdddOcr` 构造函数的常用参数：

```python
ocr = ddddocr.DdddOcr(
    ocr=True,            # 启用 OCR（默认）
    det=False,           # 启用目标检测
    beta=False,          # 使用 Beta 模型
    show_ad=False,       # 关闭广告（生产环境推荐）
    use_gpu=False,       # GPU 加速（需 onnxruntime-gpu）
)
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `ocr` | True | 文字识别模式 |
| `det` | False | 目标检测模式（与 `ocr` 互斥，`det` 优先） |
| `beta` | False | 使用 Beta 模型，对部分复杂验证码效果更好 |
| `show_ad` | True | 初始化时是否显示广告 |
| `use_gpu` | False | GPU 加速，需额外安装 CUDA + onnxruntime-gpu |
| `import_onnx_path` | "" | 自定义模型路径（需同时设置 `charsets_path`） |

> **重要**：`DdddOcr` 实例只需初始化一次。在循环中反复创建实例会严重影响性能。多线程场景下，每个线程应创建独立的实例。

Sources: [ddddocr/__init__.py:1-4](ddddocr/__init__.py#L1-L4), [pyproject.toml:22-28](pyproject.toml#L22-L28)

---

## 常见问题

### 安装时报错找不到 opencv

Linux 服务器上如果安装 `opencv-python` 失败，可以改用无头版本：

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

项目已根据操作系统自动选择正确的包（`pyproject.toml` 中通过 `sys_platform` 条件指定），通常不需要手动处理。

### 初始化很慢

首次初始化需要加载 ONNX 模型文件（内置于包中），这是正常现象。关键是要**复用实例**，不要每次识别都重新创建。

### macOS M1/M2/M3 芯片兼容性

ARM 架构的 macOS 需要特殊处理，请参考 [GitHub issue #67](https://github.com/sml2h3/ddddocr/issues/67)。

### 在项目根目录 import 报错

确保你的工作目录名称不是 `ddddocr`，否则 Python 会优先导入当前目录而非已安装的包。

---

## 总结

DdddOcr 的安装流程非常简洁：`pip install ddddocr` 即可完成基础安装，5 行代码就能跑通第一个验证码识别。如果需要对外提供 HTTP 服务，`python -m ddddocr api` 一条命令启动 FastAPI 服务器，或者用 Docker 部署到生产环境。整个过程不需要额外下载模型文件——模型已内置于 pip 包中。