Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,132 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:58f9f4be2cfa3361254938c9729839079d16175ba89ea5fecc497371dc40ee99
-size 4286
+---
+language:
+  - zh
+  - en
+license: agpl-3.0
+tags:
+  - captcha
+  - ocr
+  - cnn
+  - onnx
+  - phpwind
+pipeline_tag: image-to-text
+model_type: phpwind-captcha-ocr
+metrics:
+  - name: "validation accuracy"
+    type: accuracy
+    value: 0.886
+  - name: "real login success (per-attempt)"
+    type: accuracy
+    value: 0.876
+  - name: "login success with retries"
+    type: accuracy
+    value: 0.999997
+---
+
+# PHPWind Captcha OCR
+
+**中文**：识别 PHPWind 论坛内置验证码的 OCR 模型（4 位数字）。完全本地推理，无外部 API 依赖，4 MB。
+**English**: An OCR model for the built-in PHPWind forum captcha (4 digits). Fully local inference, no external API, 4 MB.
+
+---
+
+## 识别对象 / What it recognizes
+
+**中文**：下面这类 PHPWind 论坛登录验证码（彩色数字 + 干扰线）：
+**English**: The PHPWind forum login captcha (colored digits + noise lines):
+
+![example captcha](assets/example_captcha.png)
+
+```
+示例输入 (example input)  →  模型输出 (model output): 9125
+```
+
+**中文**：验证码是 PHPWind 内置组件（`PwVerifyCode` / `PwGDCode`），彩色数字、干扰线、扭曲均为其标准特征。
+**English**: This is PHPWind's built-in captcha component (`PwVerifyCode`/`PwGDCode`) — colored digits, noise lines and distortion are its standard features.
+
+---
+
+## 快速使用 / Quick Start
+
+### Python (onnxruntime)
+
+```bash
+pip install onnxruntime pillow numpy
+```
+
+```python
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+
+sess = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
+
+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(solve("captcha.png"))   # e.g. "9125"
+```
+
+### Go (onnxruntime_go)
+
+See [docs/INFERENCE.md](docs/INFERENCE.md).
+
+---
+
+## 输入 / 输出规格 (I/O spec)
+
+| 中文 | English |
+|---|---|
+| 输入 `input`：`[batch, 3, 64, 160]` float32 (RGB, [0,1]) | Input `input`: `[batch, 3, 64, 160]` float32 (RGB, [0,1]) |
+| 输出 `logits`：`[batch, 4, 10]`，每位置 argmax → 数字 | Output `logits`: `[batch, 4, 10]`, argmax per position → digit |
+| ONNX opset 18 | ONNX opset 18 |
+| 预处理：RGB → 160x64 (BILINEAR) → /255 | Preprocess: RGB → 160x64 (BILINEAR) → /255 |
+
+---
+
+## 评估结果 / Evaluation
+
+**中文**：用真实论坛登录作为 ground truth（登录成功 = 识别正确）。
+**English**: Evaluated against real forum logins (login success = correct recognition).
+
+| 指标 / Metric | 数值 / Value |
+|---|---|
+| 验证集精度 / Validation accuracy | 88.6% |
+| 真实登录单次命中 / Per-attempt login success | **87.6%** (85/97) |
+| 带重试登录成功率 / With retries | ≈99.9997% |
+
+**中文**：详情见 [docs/EVALUATION.md](docs/EVALUATION.md)。
+**English**: Details in [docs/EVALUATION.md](docs/EVALUATION.md).
+
+---
+
+## 训练 / 微调 (Training & Fine-tuning)
+
+**中文**：997 张人工标注验证码，CNN 从零训练（位置保留架构）。
+**English**: 997 manually-labeled captchas, CNN trained from scratch (position-preserving architecture).
+
+- 数据 / Data: `data/` (997 labeled images)
+- 脚本 / Scripts: `scripts/train_fixed.py`
+- 指南 / Guide: [docs/TRAINING.md](docs/TRAINING.md)
+
+---
+
+## 说明 / Notes
+
+**中文**：
+- 验证码为 PHPWind 内置组件（非站点定制）。
+- 不同 PHPWind 版本参数可能有差异，换站使用前建议对比样例确认风格。
+
+**English**:
+- The captcha is PHPWind's built-in component (not site-custom).
+- Different PHPWind versions may differ; compare samples before use on another site.
+
+---
+
+## 许可证 / License
+
+**中文**：本模型采用 **GNU AGPL-3.0** 许可 —— 可自由使用、修改、分发（含商用），但修改版/衍生作品必须同样以 AGPL 开源；网络服务使用也需提供源码。详见 [LICENSE](LICENSE)。
+**English**: Licensed under the **GNU AGPL-3.0** — free to use, modify and distribute (including commercial use), provided modified/derivative works stay AGPL-licensed; network-server use must offer source. See [LICENSE](LICENSE).