SkyEye — 天气图片分类

基于 ConvNeXt V2 Base@384 → 跨分辨率知识蒸馏 → ConvNeXt V2 Tiny@224 → ONNX FP32 的天气分类管线。

功能

对输入天气图片进行分类预测（当前 4 类 + 1 兜底）：

类名	中文	训练状态
cloudy	多云	✓
rainy	雨天	✓
snowy	雪天	✓
sunny	晴天	✓
other	其他（foggy/thundery/dew/rime/sandstorm/... 自动归入）	⏭ 跳过

技术方案

ConvNeXt V2 Base 384 (Teacher)
    ↓ DKD (TCKD + NCKD, T=3.0, β=8.0) + 多尺度特征对齐 (reductions 8/16/32)
ConvNeXt V2 Tiny 224 (Student)  ← Teacher384Wrapper 上采样
    ↓ ONNX Export (FP32)
CPU Inference (ONNX Runtime)

Teacher/Student 统一使用 timm 原生 head（GAP → LayerNorm → Linear(init×0.001)），跨分辨率蒸馏通过 Teacher384Wrapper 将学生 224 输入上采样到 384。Teacher LLRD layer_decay=0.8，Per-step Warmup(2ep) → Cosine(8ep, eta_min=1e-6)，动态 MixUp（α=0.2, warmup 2ep, off epoch 7），DropPath=0.3, LabelSmoothing=0.1, WD=0.05，无 EMA；蒸馏共 12 轮，LR warmup 2 轮，DKD（T=3.0, α=1.0, β=8.0）前 4 轮升权，并以 0.5 的固定权重按 reduction 8/16/32 对齐 3 个 Stage 特征（L2 归一化 MSE）。

训练本地 GPU 不限时，推理 CPU 总时限 70 分钟。

运行环境

组件	版本
Python	3.13.13
PyTorch	2.12.0
torchvision	0.27.0
timm	1.0.27
onnx	1.21.0
onnxruntime	1.26.0
平台	Windows 11 + AMD Ryzen 9 9955HX + RTX 5070 (Blackwell, CUDA 13.0)

预训练模型下载已配置 HF 镜像 (hf-mirror.com)，国内可正常访问。

项目结构

SkyEye/
├── main.ipynb                     # Jupyter Notebook 入口，按顺序执行训练管线
├── scripts/
│   ├── eval_full.py               # 模型评估（holdout / 全量）
│   ├── collect_hard_samples.py    # 错误分析：收集错分/低 margin 样本
│   └── benchmark_cpu_holdout.py   # CPU 受限环境 ONNX 测速 + 评估
├── submission/
│   └── main.py                    # 比赛自包含推理入口（TTA + 最小化 WeatherClassifier）
├── config.py                      # 超参数统一管理 + HF 镜像配置
├── data/
│   ├── file_index.py              # 五步索引管线（扫描→分裂→平衡→移动→清理）
│   ├── augmentations.py           # Train/Val 增强策略 (RandAugment + RandomErasing)
│   └── dataset.py                 # ImageFolder + DataLoader + 类别权重
├── models/
│   ├── weather_classifier.py     # WeatherClassifier: timm 骨干封装 + 中间层 hook
│   └── distill_wrapper.py        # DKD + 特征蒸馏训练器 (L2 归一化 MSE)
├── training/
│   ├── train_teacher.py          # 教师训练 (动态 MixUp + LLRD + BF16)
│   └── distill_student.py        # 跨分辨率知识蒸馏入口 (Teacher384Wrapper)
├── inference/
│   ├── export_onnx.py            # ONNX 导出 + 可选 INT8 量化 + CPU 测速
│   └── infer.py                  # 单张/批量推理（ONNX → PyTorch 三级回退）
└── utils/
    ├── checkpoint.py             # 训练备份/恢复（v2 格式，含 RNG + DataLoader 状态）
    ├── artifacts.py              # ONNX 部署产物清单与 SHA-256 新鲜度校验
    ├── metrics.py                # F1 / 混淆矩阵 / 混淆率
    └── logger.py                 # TensorBoard 日志（优雅降级）

数据集

训练集 4 类 × ~8,700 张 ≈ 34,700 张（去重后）。测试集 4 类 × 1,600 张 = 6,400 张（Kaggle 外部数据源 + 训练集补充，15% holdout）。

数据管线为五步索引驱动（data/file_index.py）：扫描建指纹（SHA-256）→ 按源名分裂 train/test → 精确比例平衡 → 移动 → 清理。缓存 .skyeye_index.json 使得二次运行仅需 0.1s。

class_aliases 自动映射异名类别（如 cloud→cloudy, Rain→rainy, Shine→sunny），未能匹配的类别自动跳过。

训练流程（本地不限时）

阶段	内容	预估耗时
1. Train Teacher	ConvNeXt V2 Base@384, 10 epochs	待实测
2. Distillation	ConvNeXt V2 Base@384 → Tiny@224, 12 epoch DKD + Feature	待实测
3. ONNX Export	FP32 ONNX（动态 INT8 默认关闭）	~3 min
4. CPU Inference	ONNX Runtime CPUExecutionProvider	<70 min/6k

训练监控（TensorBoard）

每个阶段自动写入 results/tb_results/，训练中/结束后均可查看：

tensorboard --logdir results/tb_results/
# 浏览器打开 http://localhost:6006

SCALARS 页可对比各阶段的 loss / F1 / Accuracy / per-class F1 曲线。

依赖安装

pip install -r requirements.txt

Jupyter Notebook 中按顺序执行各 Cell 即可完成训练管线。

相关文档

文档	说明
CLAUDE.md	项目开发指南（配置、数据集、训练策略）
docs/接口文档.md	模块 API 接口文档
docs/competition-rules.md	比赛规则
docs/competition-faq.md	比赛 FAQ