> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 跑一组超参 sweep

> 网格展开批量提交，控制台按组聚合对比

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf sweep my-grpo --profile h200:4 \
  -g policy.optimizer.kwargs.lr=1e-6,2e-6,5e-6 \
  -g grpo.kl_coef=0.01,0.05 \
  -s grpo.num_generations=8
```

`-g/--set-grid` 声明网格轴（可重复，多轴取**笛卡尔积**——上例 3×2=6 个变体）；`-s/--set` 是所有变体共用的固定覆盖。每个变体走一次**标准提交**：校验、配额、排队全部照常生效，不存在绕过配额的批量通道。

## 先看再提：--dry-run

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf sweep my-grpo -g policy.optimizer.kwargs.lr=1e-6,2e-6 --dry-run
```

只打印变体列表（每个变体的完整覆盖集合），不提交。网格大时先 dry-run 确认再放行。

## 分组与追踪

* 所有变体带同一个 `sweep_id`，默认分组名 `sweep-<实验名>-<时间戳>`（`-p` 自定义）；
* 控制台**作业**页给 sweep 成员打徽标，**项目**页按项目聚合曲线对比；
* 一键停止整组：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf job stop-sweep <SWEEP_ID>     # 停止该 sweep 全部活跃作业
```

## 实践建议

<AccordionGroup>
  <Accordion title="先粗后细" icon="target">
    第一轮跨量级扫学习率（1e-6 / 1e-5 / 1e-4），锁定量级后第二轮在量级内细扫。盲目全网格是烧卡最快的方式。
  </Accordion>

  <Accordion title="用 --limit 思维控制成本" icon="coins">
    sweep 变体建议先把 `max_num_steps` 降到能看出趋势的最小值（如 200 步），选出前 2 名再全量训练。
  </Accordion>

  <Accordion title="配额是按变体计的" icon="scale">
    6 变体 × 4 卡 = 24 卡并发需求。超出配额的变体会排队而不是失败——但也意味着组内变体不是同时开跑的，对比时注意数据版本一致。
  </Accordion>
</AccordionGroup>

## 早停：砍掉明显没戏的变体

网格里通常有一半配置在前几百步就能看出不行。RL 一跑几十 GPU 小时，让它们跑完是在烧钱。

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf sweep my-grpo -g policy.lr=1e-6,1e-5,1e-4 -g grpo.kl=0.01,0.05 \
  --profile h200:4 --early-stop
```

开了之后，平台在若干个 **step 梯级** 上比一次，把该梯级上垫底的变体停掉，剩下的继续跑到下一个梯级：

| 参数              | 缺省            | 说明                              |
| --------------- | ------------- | ------------------------------- |
| `--stop-metric` | 方法声明的首要指标     | 看哪个指标。方向（越大越好 / 越小越好）也取自方法的指标契约 |
| `--rungs`       | `100,300,900` | 梯级（step），逗号分隔                   |
| `--keep`        | `3`           | 每级保留 1/3。砍太狠会误伤慢热的配置            |

被停的变体会在作业详情页写明**第几步、跟几个变体比、排第几**——「被早停」三个字说明不了任何事。

<Note>
  四条刻意的保守取舍：

  **只在梯级上裁决**，不逐步比较——每步都比会因为曲线的正常抖动砍掉一个恰好在低谷的变体。

  **只跟到过同一梯级的变体比**——拿跑到 100 步的和跑到 900 步的比，比的是谁跑得久。

  **同梯级少于 4 个变体不裁决**——两个里砍一个等于抛硬币，而损失是真金白银。

  **每级至少留一个**——`--keep` 再大也不会把一个梯级上的变体全砍光。

  部署级急停：`FORGE_SWEEP_EARLY_STOP_ENABLED=false` 关掉全平台的早停，不用改任何 sweep。
</Note>