Upload docs/TRAINING.md with huggingface_hub

docs/TRAINING.md

@@ -1,24 +1,20 @@
-# 训练与微调 (TRAINING.md)
+# 训练与微调 / Training & Fine-tuning
 
-> **English summary**: Train from scratch with `scripts/train_fixed.py` — a position-preserving CNN
-> (4 digit heads) on 160x64 RGB images, CrossEntropy loss, Adam + ReduceLROnPlateau.
-> 997 human-labeled samples reached 88.6% validation / 87.6% real login accuracy.
-> To fine-tune, place a `.pt` checkpoint at the output path and the script resumes from it.
-> Key lessons: use RGB (not grayscale), **do NOT denoise**, keep per-column pooling (never global
-> average pooling), human labels >> auto labels, and skip Gaussian noise augmentation.
+---
 
-## 环境
+## 中文
+
+### 环境
 
 ```bash
-# Python 3.10+ (测试于 3.14)
 pip install torch onnx onnxscript pillow numpy opencv-python
 ```
 
-## 从零训练
+### 从零训练
 
-### 1. 准备数据
+**1. 准备数据**
 
-标签格式 `labels.json`:
+标签格式 `labels.json`：
 ```json
 {
   "captcha_001.png": {"label": "4821"},
@@ -26,9 +22,9 @@ pip install torch onnx onnxscript pillow numpy opencv-python
 }
 ```
 
-图片目录: 150x60 左右的 RGB 验证码 PNG，文件名与标签键一致。
+图片目录：150x60 左右的 RGB 验证码 PNG，文件名与标签键一致。
 
-### 2. 训练
+**2. 训练**
 
 ```bash
 python scripts/train_fixed.py \
@@ -39,7 +35,7 @@ python scripts/train_fixed.py \
   rgb       # 输入 RGB (关键: 不要用灰度)
 ```
 
-命令示例:
+示例：
 ```bash
 python scripts/train_fixed.py \
   data/1000_labels.json data/1000_raw \
@@ -47,11 +43,11 @@ python scripts/train_fixed.py \
   0.08 500 1 rgb
 ```
 
-产物:
+产物：
 - `<输出>.onnx` — 最终 ONNX 模型
 - `<输出>.onnx.pt` — 最优 epoch 的 PyTorch 权重 (best val)
 
-### 3. 推理 (验证)
+**3. 推理验证**
 
 ```python
 import numpy as np, onnxruntime as ort
@@ -63,50 +59,123 @@ logits = sess.run(None, {"input": x})[0]
 code = "".join(str(int(logits[0,p].argmax())) for p in range(4))
 ```
 
-## 微调 (Fine-tune)
+### 微调 (Fine-tune)
 
-模型从零训练即可，但如果要针对**变体生成器**微调，推荐从 checkpoint 续训：
+从 checkpoint 续训（`train_fixed.py` 检测到 `<输出>.onnx.pt` 存在会自动加载权重）：
 
 ```bash
-# 先把要微调的 .pt 放到输出路径 (train_fixed.py 会自动加载它)
 cp models/captcha_1000_raw.onnx.pt models/finetuned.onnx.pt
-
-python scripts/train_fixed.py \
-  <新标签.json> <新图目录> \
-  models/finetuned.onnx \
-  0.08 200 1 rgb   # 更少 epoch, 小学习率思想: 续训用的是已有权重
+python scripts/train_fixed.py <新标签.json> <新图目录> models/finetuned.onnx 0.08 200 1 rgb
 ```
 
-> `train_fixed.py` 检测到 `<输出>.onnx.pt` 已存在时会加载权重续训
-> (优化器状态会重置，因此等效于"带预热的微调")。
-
-### 微调建议
+- 只标少量新样本（50-200 张）即可适配小幅变化
+- 生成器变化大时建议新旧数据混合训练，避免灾难性遗忘
+- 保持同样的预处理（RGB 160x64 /255，不去噪）和增强配置
 
-- **只标少量新样本** (50-200 张) 即可适配小幅变化（颜色/字体微调）
-- 若生成器变化大，建议**混合旧数据 + 新数据**一起训练，避免灾难性遗忘
-- 保持同样的预处理（RGB 160x64 /255，**不去噪**）和增强配置
-
-## 配置参数详解
+### 参数说明
 
 | 参数 | 默认 | 说明 |
 |---|---|---|
 | val_frac | 0.1 | 验证集比例 |
 | epochs | 400 | 总训练轮数 |
-| aug | 1 | 增强开关 (0=关) |
-| rgb | - | 传 `rgb` 启用 3 通道输入 (推荐) |
+| aug | 1 | 增强开关 |
+| rgb | - | 传 `rgb` 启用 3 通道输入（推荐） |
 
-## 关键经验 (踩过的坑)
+### 关键经验（踩过的坑）
 
 1. **必须用 RGB，不要灰度** — 验证码数字是彩色的，灰度丢信息。
-2. **不要图像去噪** — 形态学开运算砍掉细笔画，val 88.6%→79.8%。数据量足够时模型自己学会过滤干扰线。
-3. **位置保留架构，不要 Global Average Pooling** — GAP 丢空间位置导致 val 归零；按列分组池化 (20列→4位置) 后立即泛化到 45%。
+2. **不要图像去噪** — 形态学开运算砍掉细笔画，val 从 88.6% 掉到 79.8%。数据量足够时模型自己学会过滤干扰线。
+3. **位置保留架构，不要 Global Average Pooling** — GAP 丢空间位置导致 val 归零；按列分组池化（20列→4位置）后立即泛化。
 4. **人类标注 >> 视觉模型自动标注** — 自动标注 ~35% 噪声会把模型带崩到 0% 命中；手工 100% 干净标签才能学到真实分布。
 5. **增强不要加高斯噪声** — 验证码本身有干扰线，再加随机噪声会让训练样本面目全非。
 
-## 数据增强 (train_fixed.py 内)
+---
+
+## English
+
+### Environment
+
+```bash
+pip install torch onnx onnxscript pillow numpy opencv-python
+```
+
+### Training from scratch
+
+**1. Prepare data**
+
+Label format `labels.json`:
+```json
+{
+  "captcha_001.png": {"label": "4821"},
+  "captcha_002.png": {"label": "9037"}
+}
+```
+
+Image dir: ~150x60 RGB captcha PNGs; filenames must match label keys.
+
+**2. Train**
+
+```bash
+python scripts/train_fixed.py \
+  <labels.json> <image_dir> <output.onnx> \
+  0.08      # val fraction
+  500       # epochs
+  1         # augmentation on/off (1=on)
+  rgb       # RGB input (important: do NOT use grayscale)
+```
+
+Example:
+```bash
+python scripts/train_fixed.py \
+  data/1000_labels.json data/1000_raw \
+  models/my_model.onnx \
+  0.08 500 1 rgb
+```
+
+Outputs:
+- `<output>.onnx` — final ONNX model
+- `<output>.onnx.pt` — best-epoch PyTorch weights
+
+**3. Verify inference**
 
 ```python
-# 旋转 ±6° (fillcolor=255 白底)
-# 仿射: 缩放 0.92-1.08, 平移 ±3px (fillcolor=255)
-# 可选 AUG_NOISE=1 环境变量加高斯噪声 (默认关, 不推荐)
+import numpy as np, onnxruntime as ort
+from PIL import Image
+sess = ort.InferenceSession("my_model.onnx", providers=["CPUExecutionProvider"])
+im = Image.open("captcha.png").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]
+code = "".join(str(int(logits[0,p].argmax())) for p in range(4))
+```
+
+### Fine-tuning
+
+`train_fixed.py` auto-loads an existing `<output>.onnx.pt` and resumes from it:
+
+```bash
+cp models/captcha_1000_raw.onnx.pt models/finetuned.onnx.pt
+python scripts/train_fixed.py <new_labels.json> <new_image_dir> models/finetuned.onnx 0.08 200 1 rgb
 ```
+
+- 50-200 new labeled samples are enough for small changes.
+- Mix old + new data when the generator changes a lot, to avoid catastrophic forgetting.
+- Keep the same preprocessing (RGB 160x64 /255, no denoise) and augmentation.
+
+### Parameters
+
+| Param | Default | Description |
+|---|---|---|
+| val_frac | 0.1 | validation fraction |
+| epochs | 400 | total epochs |
+| aug | 1 | augmentation toggle |
+| rgb | - | pass `rgb` for 3-channel input (recommended) |
+
+### Key lessons
+
+1. **Use RGB, not grayscale** — the digits are colored; grayscale loses information.
+2. **Do NOT denoise** — morphological opening removes thin strokes, dropping val from 88.6% to 79.8%. With enough data the model learns to ignore noise lines itself.
+3. **Position-preserving architecture, never global average pooling** — GAP destroys spatial position (val → 0%); per-column grouped pooling (20 cols → 4 positions) restores generalization.
+4. **Human labels >> auto vision labels** — auto labels with ~35% noise crashed the model to 0%; clean manual labels are essential.
+5. **No Gaussian noise augmentation** — the captcha already has noise lines; adding more obscures the training signal.
+
+---