Upload README_zh.md with huggingface_hub

README_zh.md

@@ -2,7 +2,6 @@
 language:
   - zh
 license: agpl-3.0
-library_name: onnxruntime
 tags:
   - captcha
   - ocr
@@ -11,93 +10,82 @@ tags:
   - 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 内置四位数字验证码组件（`PwVerifyCode` / `PwGDCode`）的 ONNX OCR
-模型。模型完全在本地运行，不依赖外部 API，也不需要 GPU。
-
-**PHPWind 参考实现源码**：[alibaba/phpwind](https://github.com/alibaba/phpwind)，其中包含本模型
-对应的 `PwVerifyCode` 与 `PwGDCode` 类。
+识别 **PHPWind 论坛内置验证码**（4 位数字）的 OCR 模型。完全本地推理、无外部 API 依赖、ONNX 模型仅 4 MB。
 
 **English version**: [README.md](README.md)
 
-![PHPWind 验证码样例](assets/example_captcha.png)
-
-> **上图验证码的正确答案：** `9125`
-
-## 适用范围与负责任使用
+![验证码样例](assets/example_captcha.png)
 
-本模型面向 PHPWind 站点的运营者、开发者及研究者，用于其自有或已获明确授权的
-PHPWind 部署。适合本地集成测试、无障碍研究，或评估自身验证码实现；不得用于
-自动化账户登录或绕过访问控制。
+```
+示例输入  →  模型输出: 9125
+```
 
-不同 PHPWind 版本及自定义主题可能生成外观不同的验证码。部署前请以有授权的代表性
-样本验证实际效果。
+这是 PHPWind 论坛软件的内置验证码组件（`PwVerifyCode` / `PwGDCode`），彩色数字、干扰线、扭曲都是它的标准特征。
 
-## 快速开始
+## 快速使用
 
-安装运行时：
+### Python (onnxruntime)
 
 ```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"])
+sess = 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))
+def solve(path):
+    im = Image.open(path).convert("RGB").resize((160, 64), Image.BILINEAR)
+    x = np.asarray(im, dtype=np.float32).transpose(2, 0, 1)[None] / 255.0
+    logits = sess.run(None, {"input": x})[0]
+    return "".join(str(int(logits[0, p].argmax())) for p in range(4))
 
-print(predict_captcha("captcha.png"))
+print(solve("captcha.png"))   # 例如 "9125"
 ```
 
-## 模型接口
+### Go (onnxruntime_go)
+
+见 [docs/zh/INFERENCE.md](docs/zh/INFERENCE.md)。
+
+## 输入 / 输出规格
+
+| 项 | 规格 |
+|---|---|
+| 输入 `input` | `[batch, 3, 64, 160]` float32，RGB，取值 `[0, 1]` |
+| 输出 `logits` | `[batch, 4, 10]`，每位置 argmax → 数字 |
+| ONNX opset | 18 |
+| 预处理 | RGB → 缩放到 160x64（双线性）→ 除以 255 |
+
+## 评估结果
+
+用**真实论坛登录**作为 ground truth（登录成功 = 识别正确）。详见 [docs/zh/EVALUATION.md](docs/zh/EVALUATION.md)。
 
-| 项目 | 规格 |
+| 指标 | 数值 |
 |---|---|
-| 输入 | `input`：`[batch, 3, 64, 160]`，`float32`，RGB 值域 `[0, 1]` |
-| 输出 | `logits`：`[batch, 4, 10]`；逐位置 argmax 得到一位数字 |
-| 预处理 | RGB → 缩放至 `160 × 64`（双线性）→ 除以 `255` |
-| 格式 | ONNX，opset 18 |
-| 运行环境 | 支持 CPU，无 GPU 依赖 |
+| 验证集精度 | 88.6% |
+| 真实登录单次命中 | **87.6%** (85/97) |
+| 带重试登录成功率 | ≈99.9997% |
 
-## 评估
+## 训练 / 微调
 
-已发布 checkpoint 在 997 张人工标注的 PHPWind 验证码图片留出集上达到
-**88.61% 验证集准确率**。该值仅是模型卡参考指标，不保证特定 PHPWind 版本、主题或
-部署环境中的表现。评估范围与复现要求见[评估说明](docs/zh/EVALUATION.md)。
+997 张人工标注验证码，CNN 从零训练（位置保留架构）。
 
-## 文档
+- 数据集（997 张已标注图片）：[FlanChanXwO/phpwind-captcha-dataset](https://huggingface.co/datasets/FlanChanXwO/phpwind-captcha-dataset)
+- 脚本：`scripts/train_fixed.py`
+- 指南：[docs/zh/TRAINING.md](docs/zh/TRAINING.md)
 
-- [推理指南](docs/zh/INFERENCE.md) —— Python 与 Go 集成细节
-- [训练与微调](docs/zh/TRAINING.md) —— 数据准备及模型训练
-- [评估说明](docs/zh/EVALUATION.md) —— 离线验证方法
-- [文档索引](docs/zh/README.md)
+## 说明
 
-## 训练数据与许可证
+- 验证码为 PHPWind 内置组件（非站点定制）。
+- 不同 PHPWind 版本参数可能有差异，换站使用前建议对比样例确认风格。
 
-该 checkpoint 使用位置保留 CNN 从零训练，训练数据为 997 张人工标注图片。需要适配时，
-请只使用自有或已获授权的 PHPWind 部署所产生的验证码图片。
+## 许可证
 
-本项目采用 [GNU AGPL-3.0](LICENSE) 许可。修改版或通过网络提供服务的衍生作品须满足
-许可证的对应源码提供义务。
+GNU AGPL-3.0 —— 可自由使用、修改、分发（含商用），但修改版/衍生作品必须同样以 AGPL 开源；网络服务使用也需提供源码。详见 [LICENSE](LICENSE)。