> ## 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.

# 创建和调整实验

> sf new 脚手架、config.yaml 分层继承、本地校验

实验是一个自包含目录：`experiments/<名字>/`，包含 `config.yaml`（调参入口）、`README.md` 与 `recipe.lock.json`（方法锁）。先用 [`sf init`](/zh-Hans/cli/init) 创建仓库，再在仓库内运行下面的命令。磁盘布局和上传排除项：[实验仓库布局](/zh-Hans/concepts/lab-layout)。继承细节：[config.yaml](/zh-Hans/guides/config)。

## 新建实验

<Tabs>
  <Tab title="从方法目录创建">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf new my-grpo --method nemo-rl/grpo
    sf new my-verl --method verl/grpo --framework-version 0.9.0
    sf new my-kto  --method trl/kto
    ```

    脚手架来自 recipe 的官方模板：config 基底、README 调参说明、锁文件一次就位。
  </Tab>

  <Tab title="Fork 现成实验">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf new my-grpo-v2 --from my-grpo
    ```

    继承来源实验的全部配置与锁（`--method` 被忽略）。适合在已收敛的配置上做增量改动。
  </Tab>
</Tabs>

## config.yaml：只写差异

实验 config 用 `defaults` 继承官方基底，只写你要改的键：

```yaml experiments/my-grpo/config.yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
defaults:
  - ../../configs/base/grpo_math_1B.yaml     # 官方基底
  - ../../configs/models/qwen3.5-9b.yaml     # 模型片段

# ── 调参区 ──
policy:
  optimizer:
    kwargs:
      lr: 2.0e-6
grpo:
  num_generations: 8
  kl_coef: 0.01
```

<Note>
  硬件与分布式细节（并行度、显存调优、NCCL）**不写在实验 config**——它们由提交时的 `--profile` 从服务端注册表下发。同一个实验换卡型无需改配置。
</Note>

脚手架顶部有「调参速查」注释块，列出该方法最常改的键（学习率、batch、序列长度、验证周期等）与经验区间。

## 本地校验

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf validate my-grpo
```

校验器按 recipe 声明检查：

* **键合法性**：struct 模式，拼错的配置键立即报错；
* **类型与区间**：学习率、batch 等按声明的类型与取值范围检查；
* **批大小关系**：GRPO 等方法校验 rollout batch 与 train batch 的整除关系（可整除但不等长按 off-policy 给警告，不能整除报错）；
* **数据声明**：verl / TRL 必填的 `--model` / `--train-data` 缺失提前发现。

`sf submit` 会自动跑同一套校验，`--no-validate` 可跳过（不建议）。

## 查看方法与超参

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf methods                # 全部方法：一句话说明 + 支持的框架版本
sf methods nemo-rl/grpo   # 该方法的可调超参：类型、默认值、区间、说明
sf ls                     # 列出本仓库全部实验目录
```

控制台 **方法** 页（`/methods`）有同一份目录的可视化版本。

## 在控制台对比多次作业

项目详情的作业区是高密度对比矩阵：

* 左侧作业名称与状态固定，右侧指标/配置列可横向滚动；
* 行、列均使用虚拟化，数百个 run × 数百列也只渲染视口附近单元格；
* 默认显示全部最新指标和跨 run 有变化的配置，常量配置可从“列”面板打开；
* 支持作业搜索、状态筛选、列搜索/隐藏/置顶，并可勾选 2–4 个 run 进入评审对比。

## 实验目录里还能放什么

| 内容                  | 用途                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `train.sh`          | 仅 custom：训练入口。日志跟 stdout 走，曲线用 `starforge.report`，见[自定义训练](/zh-Hans/guides/custom-training) |
| 自定义环境 / 奖励代码        | `common/environments/`、`common/rewards/` 里的模块按 config 引用，随作业包上传                             |
| `plugins.lock.json` | 引用平台插件（`sf plugin install --exp`），提交时由平台注入                                                  |
| `cluster` 标注文件      | 旧版遗留：默认 profile 记录，现推荐提交时 `--profile` 显式指定                                                  |