Default USE_FLAGTUNE to 0 and add fold_scale A/B script with trace shapes

Plain autotune is the common case (fast, same-config A/B); FlagTune's
exhaustive first-run search is now opt-in via USE_FLAGTUNE=1.
ab_fold_test.sh automates the FLAGGEMS_MXFP4_FOLDSCALE=0/1 record-replay
comparison over the four DeepSeek-V4-Flash trace shape sets, which are
now tracked under runs/shape/.

README.md

@@ -28,7 +28,7 @@ softmax:
 
 跑之前先 `nvidia-smi` 确认目标卡空闲——共享机器上别的任务会把 baseline 和被测两边一起等比拖慢，出一份看似自洽实则作废的数据。多卡机器上用 `CUDA_VISIBLE_DEVICES=<空闲卡号>` 明确选卡。
 
-脚本内固定了 `--level core --mode kernel`；`USE_FLAGTUNE` 默认 `1`（FlagTune 扩展调优空间，见"为什么需要 replay"一节），可用环境变量覆盖（`USE_FLAGTUNE=0 bash run_pytest.sh` 走普通 autotune，跳过全量搜索，快速验证时用）；需要改动其它口径时直接编辑 `run_pytest.sh` 中的 pytest 命令行。
+脚本内固定了 `--level core --mode kernel`；`USE_FLAGTUNE` 默认 `0`（普通 autotune，快速出结果），需要 FlagTune 扩展调优空间时用 `USE_FLAGTUNE=1 bash run_pytest.sh`（首跑全量搜索、慢，见"为什么需要 replay"一节）；需要改动其它口径时直接编辑 `run_pytest.sh` 中的 pytest 命令行。
 
 ### 环境变量一览
 
@@ -39,7 +39,7 @@ softmax:
 | `SHAPE_FILE`   | 空（用脚本内置 yaml）       | shape yaml 路径                                   |
 | `FLAGGEMS_DIR` | `/workspace/FlagGems-dev` | FlagGems 仓库路径                                 |
 | `REPLAY_FROM`  | 空（record 模式）          | 指向某次历史 run 目录，replay 其 autotune 选择（见下） |
-| `USE_FLAGTUNE` | `1`                       | `1` 用 FlagTune 扩展调优空间（首跑全量搜索、慢）；`0` 走普通 autotune，跳过搜索、快速验证 |
+| `USE_FLAGTUNE` | `0`                       | `0` 走普通 autotune（跳过搜索、快速验证）；`1` 用 FlagTune 扩展调优空间（首跑全量搜索、慢） |
 | `FLAGGEMS_PERF_COLOR` | 空（按 tty 自动判断） | `always`/`never` 强制开/关终端颜色；`run.log` 始终为去色纯文本 |
 
 ## 输出目录结构
@@ -85,6 +85,17 @@ A/B 两侧的 `USE_FLAGTUNE` 必须取同值：该开关决定调优空间，两
 
 replay 的兜底行为：B 侧遇到记录中没有的 key、或记录的 config 在新编译器下编译失败时，自动回退到现场 autotune 并在 `run.log` 打 `AUTOTUNE_REPLAY_FALLBACK reason=...` 标记——出现该标记的测量点不再满足"同 config"前提，解读时注意。另外 replay 模式的 run 目录不产生 `autotune_records/`，后续 run 的 `REPLAY_FROM` 应始终指向最初 record 的那次 A 侧目录，不要链式指向 replay 产物。
 
+### ab_fold_test.sh：FOLD 开关 A/B（现成示例）
+
+`ab_fold_test.sh` 把上述流程封装成 FlagGems `FLAGGEMS_MXFP4_FOLDSCALE`（fold_scale 优化）开关的 A/B 验证：对 4 个 DeepSeek-V4-Flash 真实 trace shape 集（`runs/shape/DeepSeek-V4-Flash-p{1024,4096,32768,65536}d1024.yaml`，随仓库提供）各跑一对 FOLD=0（基线，record）→ FOLD=1（replay 同 config），共 8 轮：
+
+```bash
+bash ab_fold_test.sh
+# 汇总 log：runs/ab_fold_<时间戳>.log（已去色）；快速对账：grep -E '^#####|FAILED' <log>
+```
+
+对比其它开关 / 算子时可直接改脚本内的循环变量与环境变量，A/B 口径（同 config replay、cudagraph 计时）无需改动。
+
 ### cudagraph 计时的 warmup、回退与精度
 
 **capture 前的显式 warmup**：`do_bench_cudagraph` 自带的内部预热只有 5 次迭代，对首跑要触发 autotune 编译（尤其含 FlagTune 扩展空间）、libtuner 选择、lazy JIT 的算子远远不够——这些一次性开销若漏进被捕获的 graph 或第一个计时迭代，测出的 latency 会 run-to-run 抖动（M=1 多 kernel 路径最明显，实测首轮可低到稳态的 ~1/3）。`_cudagraph_plugin` 因此在 capture 前显式预热：先跑一次并丢弃（吸收 autotune/JIT 编译），再按调用方传入的 warmup 时间预算（`Config.warm_up`）循环稳态预热，然后才 capture。预热次数按稳态单次耗时换算，并夹在 5–200 次之间——亚毫秒 kernel 的实际预热时长因此低于名义预算（1000ms），实测足够；若换新算子仍见首轮抖动，优先调大 `_warmup_before_capture` 里的次数上限。这样首轮即稳态、多轮一致（实测同一 M=1 shape 两轮 speedup 差 <0.1%）。
@@ -134,7 +145,7 @@ libtuner 的持久缓存何时失效：FlagGems kernel 源码改动、tune_confi
 
 **Q: 第一次跑某算子特别慢？**
 
-两个来源：（1）默认 `USE_FLAGTUNE=1`，首跑要在 FlagTune 扩展空间做全量搜索（fused_marlin_moe_mxfp4 单进程可达数分钟甚至十几分钟，期间 GPU 满载、`run.log` 停在测试名不动属正常，不是卡死）；（2）libtuner 算子首跑的全量 sweep（mm 约 50 分钟）。winner 持久化到 `~/.flaggems/config_cache/` 后同 shape 秒级命中（但该缓存会因源码/开关/GPU 变化失效，失效后又需重搜）。快速验证（不追求"各自最优 config"、只看功能/稳定性）时直接 `USE_FLAGTUNE=0 bash run_pytest.sh` 走普通 autotune，单 shape 通常 10 秒级出结果。
+两个来源：（1）开了 `USE_FLAGTUNE=1` 时，首跑要在 FlagTune 扩展空间做全量搜索（fused_marlin_moe_mxfp4 单进程可达数分钟甚至十几分钟，期间 GPU 满载、`run.log` 停在测试名不动属正常，不是卡死）；（2）libtuner 算子首跑的全量 sweep（mm 约 50 分钟）。winner 持久化到 `~/.flaggems/config_cache/` 后同 shape 秒级命中（但该缓存会因源码/开关/GPU 变化失效，失效后又需重搜）。默认 `USE_FLAGTUNE=0` 走普通 autotune，单 shape 通常 10 秒级出结果。
 
 **Q: `--warmup/--iter` 要设吗？**