# 训练效果不佳 — 排查与改进指南

## 已修复的代码问题（必做）

此前 `train.py` **只读取 `task=storefront/handover` 且 `label=1` 的行**，`task=other` 的负样本全部被忽略，模型相当于「全图都是正类」，验证必然很差。

`prepare_dataset.py` 已改为：**每一帧同时写入 storefront / handover 两行，含 label 0/1**。

请 **重新生成数据并训练**：

```powershell
cd server/snapshot_infer/training
py prepare_dataset.py -c config.yaml
py train.py -c config.yaml
py export_onnx.py -c config.yaml --version 1.0.1
py evaluate.py -c config.yaml --split val
```

训练开始时会打印 `train pos=... neg=...`，**neg 必须 > 0**。

---

## 你当前数据的问题

查看 `data/annotations.jsonl`：

| 问题 | 说明 |
|------|------|
| 仅 **4 条** 标注 | 远低于 POC 建议 80~100 条 |
| 实际只有 **2 个不同视频** | media 1/3 同一文件，2/4 同一文件 |
| train/val **重复同一视频** | 验证指标虚高或失真，无法反映泛化 |
| 场景单一 | 全是「公司」室内，模型学不到真实门头/交付 |

**结论**：即使代码正确，4 条样本也几乎不可能训出可用模型。需要继续标注 **80+ 条真实配送视频**，且 train/val 按 **司机+日期** 分组，不能同一视频进 train 又进 val。

---

## 标注质量检查

1. **门头时刻**：店招/入口最清晰的一帧（不是车内、不是背影）
2. **交付时刻**：货品/交接动作最清晰的一帧
3. 约束：`handover_time_sec > storefront_time_sec + 20s`
4. 有语音标记的视频，可开 ASR 融合（`enable-asr: true`），减轻纯视觉压力

---

## 训练参数建议（`config.yaml`）

```yaml
sampling:
  sample_fps: 1.0          # 与推理 sample-fps 一致
  positive_window_sec: 3.0   # 正样本窗口 ±3s（原 5s 过宽会模糊峰值）
  other_downsample_ratio: 2  # 负样本不要太少

train:
  batch_size: 32
  epochs: 40
  lr: 0.0005               # 全量微调时可略降
  early_stop_patience: 8
  freeze_backbone: true      # 样本 <200 时自动冻结 backbone（已实现）
```

样本量 >300 后，可设 `freeze_backbone: false` 做分层学习率微调。

---

## 评估指标怎么看

`evaluate.py` 输出：

| 指标 | POC 目标 |
|------|----------|
| 门头 MAE | < 8s |
| 交付 MAE | < 8s |
| 顺序正确率 | > 95% |
| 双 5 秒命中率 | > 70% |

若帧级 loss 低但 MAE 仍大：检查 **sample_fps 训练与推理是否一致**、标注时刻是否准。

---

## 短期可用方案（数据不够时）

1. **ASR 为主**：司机到店/交付时清晰说「到店」「交付」，开 `snapshot.infer.enable-asr: true`，视觉仅辅助
2. **人工纠正**：Admin「人工纠正」写入 feedback，积累后再训
3. **dev mock 兜底**：`fail-open-mock: true` 仅用于联调，不是生产方案

---

## 推荐迭代顺序

1. 重新 `prepare_dataset` + `train` + `export`（修复负样本）
2. 标注扩到 50~100 条，去掉 val 与 train 重复视频
3. 跑 `evaluate.py`，记录 MAE
4. 上线 snapshot-infer，用 10 条真实视频人工看「查看快照」效果
5. badcase 人工纠正 → `export_feedback.py` → 合并进 `annotations.jsonl` 增量训练