README_zh.md

---
language:
  - zh
license: agpl-3.0
library_name: onnxruntime
tags:
  - captcha
  - ocr
  - cnn
  - onnx
  - phpwind
pipeline_tag: image-to-text
model_type: phpwind-captcha-ocr
metrics:
  - name: validation accuracy
    type: accuracy
    value: 0.8861
---

# PHPWind 验证码识别

[![Hugging Face 模型](https://img.shields.io/badge/Hugging%20Face-Model-FFD21E?logo=huggingface&logoColor=000)](https://huggingface.co/FlanChanXwO/phpwind-captcha-ocr)
[![ONNX](https://img.shields.io/badge/Runtime-ONNX-005CED?logo=onnx&logoColor=fff)](https://onnx.ai/)
[![PHPWind](https://img.shields.io/badge/Target-PHPWind-3776AB)](https://github.com/alibaba/phpwind)
[![许可证：AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)

针对一个旧版 PHPWind 部署的四位数字验证码图片训练的 ONNX OCR 模型。模型完全在本地运行，
不依赖外部 API，也不需要 GPU。

**PHPWind 参考实现源码**：[alibaba/phpwind](https://github.com/alibaba/phpwind)，其中包含本模型
对应的 `PwVerifyCode` 与 `PwGDCode` 类。

**English version**: [README.md](README.md)

![PHPWind 验证码样例](assets/example_captcha.png)

> **上图验证码的正确答案：** `9125`

## 适用范围与负责任使用

本模型面向 PHPWind 站点的运营者、开发者及研究者，用于其自有或已获明确授权的
PHPWind 部署。适合本地集成测试、无障碍研究，或评估自身验证码实现；不得用于
自动化账户登录或绕过访问控制。

不同 PHPWind 版本及自定义主题可能生成外观不同的验证码。部署前请以有授权的代表性
样本验证实际效果。

## 版本支持

此 checkpoint 仅使用目标部署页脚显示为 `v0.7β` 的四位数字验证码图片训练。该页脚内容
只是观测到的部署标识，**不能**视为 PHPWind 官方发布版本号。

| 部署或版本标识 | 状态 | 依据 | 说明 |
|---|---|---|---|
| 目标部署——页脚标识 `v0.7β` | 已训练范围 | 997 张人工标注图片；留出验证集准确率 88.61% | 训练数据和参考评估数据中唯一包含的验证码视觉配置。 |
| 其他 PHPWind 发行版、分支、主题或验证码生成器 | 未验证 | 无按版本划分的评估 | 请先使用有授权的代表性样本验证；视觉分布不同时需进行微调。 |

## 快速开始

安装运行时：

```bash
pip install onnxruntime pillow numpy
```

对已获授权处理的验证码图片执行本地推理：

```python
import numpy as np
import onnxruntime as ort
from PIL import Image

session = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])

def predict_captcha(path: str) -> str:
    image = Image.open(path).convert("RGB").resize((160, 64), Image.BILINEAR)
    inputs = np.asarray(image, dtype=np.float32).transpose(2, 0, 1)[None] / 255.0
    logits = session.run(None, {"input": inputs})[0]
    return "".join(str(int(logits[0, position].argmax())) for position in range(4))

print(predict_captcha("captcha.png"))
```

## 模型接口

| 项目 | 规格 |
|---|---|
| 输入 | `input`：`[batch, 3, 64, 160]`，`float32`，RGB 值域 `[0, 1]` |
| 输出 | `logits`：`[batch, 4, 10]`；逐位置 argmax 得到一位数字 |
| 预处理 | RGB → 缩放至 `160 × 64`（双线性）→ 除以 `255` |
| 格式 | ONNX，opset 18 |
| 运行环境 | 支持 CPU，无 GPU 依赖 |

## 评估

已发布 checkpoint 在来自目标页脚标识 `v0.7β` 部署的 997 张人工标注图片留出集上达到
**88.61% 验证集准确率**。该值仅是模型卡参考指标，不保证其他 PHPWind 版本、主题或
部署环境中的表现。评估范围与复现要求见[评估说明](docs/zh/EVALUATION.md)。

## 文档

- [推理指南](docs/zh/INFERENCE.md) —— Python 与 Go 集成细节
- [训练与微调](docs/zh/TRAINING.md) —— 数据准备及模型训练
- [评估说明](docs/zh/EVALUATION.md) —— 离线验证方法
- [文档索引](docs/zh/README.md)

## 训练数据与许可证

该 checkpoint 使用位置保留 CNN 从零训练，训练数据为 997 张人工标注图片。需要适配时，
请只使用自有或已获授权的 PHPWind 部署所产生的验证码图片。

本项目采用 [GNU AGPL-3.0](LICENSE) 许可。修改版或通过网络提供服务的衍生作品须满足
许可证的对应源码提供义务。