dsh-runnpu 0.1.0

package/training-mode/preset/skills/training-research/references/research.md

@@ -0,0 +1,76 @@
+# 自动超参研究（Auto-Research 闭环）
+
+用户说「自动调参 / 自动优化 / 帮我研究怎么调」时，按下面的纪律跑闭环。
+判断依据永远是**跟踪平台上的曲线数据**，不是感觉。
+
+## 实验纪律（每轮都要遵守）
+
+1. **先有基线**：账本里最近一次有效 run 就是基线；没有就先原样跑一轮。
+2. **先诊断再动手**：拉基线的关键指标曲线，对照下面的规则表写出**假设**
+   （哪个症状 → 疑因 → 本轮动哪个旋钮、预期什么变化），假设写进该轮账本的 note。
+3. **一次一个变量**（或一组明确耦合的变量，如 lr 与 warmup），否则赢了不知道为什么赢。
+4. **同窗口对比**：轮与轮比同一指标、同一评估口径；每轮实验名可区分（勿依赖默认名）。
+5. **停止准则**：连续两轮相对改进 < 1-2%，或达到用户给的目标，就停——写结论，
+   不要为了「多跑几轮」烧卡。
+6. **收尾产出**：跨 run 对比 + `promote` 赢家、`discard` 输家 + 一句话说清赢家
+   **为什么**赢（对应最初的假设是否成立）。
+
+**数字与形状分两条通道，原始点列一条都不走：**
+
+- **决策数字**（谁赢、差多少、平台没平台）→ `training_compare` 工具：确定性给出
+  每 run × 每指标的终值 / 最优值 / 尾段趋势和按 direction 的赢家与领先幅度。
+  「谁赢了赢多少」是算术，不徒手比，也**不要从图上读数值**（视觉读数不可靠）。
+- **形态诊断**（震荡、尖刺、train/val gap 的形状、warmup 伪影——规则表里的症状
+  本来就是形状词）→ **聚合后出图再看图**：用 swanlab-skill 的现成脚本
+  `scripts/plot_metrics.py --sample 500`（`--sample` 是服务端聚合，大 run 不拉全量点）
+  或多 run 叠加的 `scripts/runs_benchmark.py`，渲染 PNG 后 read_image。
+  **不要自己手写一次性 matplotlib 代码**——不可复用的可视化是反模式，脚本就在那。
+- 原始指标点列**永不整段进上下文**；朴素抽样会抹掉尖刺与 NaN，
+  怀疑有瞬时异常时把 `--sample` 放大再看一次，别在小样本图上下"没有震荡"的结论。
+
+## 诊断规则表（症状 → 疑因 → 首选动作）
+
+| 曲线症状 | 最可能的原因 | 首选动作 |
+|---|---|---|
+| train/loss 几乎不降，且远高于随机水平 | lr 太小，或可训练容量/**优化步数**不足 | 先数一下总优化步数（样本数÷bs×epochs）；lr ×3~10；LoRA 类加 r / 解冻更多层 |
+| loss 剧烈震荡、上冲或 NaN | lr 太大 | lr ÷3~10，加 warmup / 梯度裁剪 |
+| train 持续降、val 不降（gap 拉大） | 过拟合 | 早停、正则/weight decay、数据增强、缩容量 |
+| train/val 同步降但没到平台就结束 | 训练不够长 | 加 epochs（或加 lr 衰减尾段） |
+| val 到平台后长期横盘 | 该配置的收益已尽 | 停这个方向，换结构/数据/特征旋钮 |
+| 曲线形状正常但绝对值离谱 | 数据/标签/预处理有 bug | 回代码查数据管道，别调参 |
+| 首个点就异常好且秒收敛 | 数据泄漏、任务过简，或**设备降级**（见 pipeline.md §3） | 查 train/val 划分与标签；查设备探测日志 |
+
+⚠️ 两个反模式：把多轮曲线数字整段倒进上下文（先出图/统计再判断）；
+每轮改一堆超参然后挑最好的（那是抽奖不是研究，结论不可迁移）。
+
+## 长程闭环（训练超过 ~10 分钟就别占着会话轮询）
+
+短训练（几分钟）可以在会话里直接盯完；再长就用 `schedule_create` 把
+"看曲线→判断"变成周期任务，把会话让出来：
+
+- 提交训练后建一个周期检查（间隔按训练时长取 1/5~1/10；注意工具的**间隔下限是
+  300 秒**，用户要求更短时取最近允许值并如实说明）。每次触发只做三件事：
+  拉关键指标最近若干点 → 按规则表判断（正常继续 / 平台期停 / 发散停）→
+  有结论就执行（停负载、记账本、必要时提交下一轮并重建下一个周期检查），
+  没结论就一句话说明还在正常下行。
+- **必须向用户预告 schedule 的三条限制**（机制如此，不说清楚事后全像 bug）：
+  投递是会话内的，会话关着就积压等待；固定间隔从创建那一刻起算；
+  只有 schedule 挂载后新建的会话才有这个工具。
+- 研究收尾（promote/终止）时**删掉自己建的 schedule**，别留下空转的检查。
+
+## 并行实验（卡够时不必串行）
+
+- 先做预算：查本项目的保底配额与当前占用（命令见平台 skill），
+  **并行度 = 空闲配额张数**，绝不为并行去借可抢占容量跑关键对照组。
+- 并行的前提仍是单变量：2-3 个 run 只在**同一个旋钮的不同取值**上分叉
+  （如 lr 三点扫描），负载名/实验名带取值后缀（`-lr3e3`）。不同旋钮的探索仍然串行。
+- 全部完成后**一次性**对比（`training_compare`），不要拿先跑完的那个提前下结论——
+  快的那个往往只是配置小。
+- 账本一轮一份照写（每个并行 run 一个 seq），假设写在共同的第一份里并互相引用。
+
+## 账本语义（decision 三态）
+
+- `promote`：当前最优，版本卡会标「最优」徽章；
+- `discard`：已证伪的方向，note 里写为什么；
+- `next`：有效但已被后续取代/待迭代。
+判断只能由 `training_run_update` 写（机械字段是后台同步的事，别抢）。