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

# 实验配置文件

> defaults 继承、_override_、插值，以及实验文件里该写什么

目录实验用 `experiments/<name>/config.yaml` 调参。格式是 YAML。继承是相对路径，不是 Hydra 那套完整 package。`sf validate` 和 `sf submit` 用的是同一份 `starforge.config_resolve`。

自定义作业如果 `train.sh` 不读这个文件，可以完全不管。目录 adapter 一定会读。

## 只写差异，不要把基底再抄一遍

```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
```

`defaults` 里的路径相对**本文件**。每个被引用的文件会再递归解析（它自己也可以有 `defaults`）。后出现的文件覆盖前面的。实验文件里的键最后覆盖。

脚手架顶部的注释是调参备忘：学习率、batch、序列长度、验证间隔，范围来自 recipe。注释不会被执行。

## 提交时的四层

后写的赢：

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
recipe 模板（sf init 落到 configs/，加上实验脚手架）
└─ experiments/<name>/config.yaml
   └─ 服务端注册表里的硬件 profile（--profile）
      └─ sf submit --set dotted.key=value
```

硬件（FSDP、显存、NCCL、`cluster.num_nodes`）**不要**在实验文件里维护。adapter 会用 `FORGE_CLUSTER_NUM_NODES` / `FORGE_CLUSTER_GPUS_PER_NODE` 覆盖拓扑。4 卡改 8 卡是换 `--profile`，不是改 config。

`--set` 按 recipe 的 `params` 在本地做类型检查。拼错键当场失败。

## 整段替换：`_override_`

默认是深合并。某个 dict 要整段换掉而不是合键，在该映射上写 `_override_: true`。这个标记会被剥掉，不会进训练器。

```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
some_block:
  _override_: true
  only_these: keys
```

## 插值

`${...}` 当字符串保留。`sf validate` 对这类字段跳过数值检查（看不到具体值）。少数 `*_DATA_DIR` 会识别 `${oc.env:GSM8K_DATA_DIR}/train.jsonl` 这种写法，用来检查本地路径在不在。其它带 `${` 的一律放过。

## struct 模式

未知键校验失败。`kl_coef` 拼错会在上集群之前被抓住。recipe 没声明的训练器私有键不要往上塞，除非你走的是自己解析 YAML 的 custom 路径。

## batch 关系（GRPO 一类）

recipe 若声明了 rollout batch 和 train batch 的约束，会检查整除关系。能整除但不相等会给 off-policy 警告。不能整除是错误。

## 本地检查

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf validate my-grpo
sf methods nemo-rl/grpo    # 每个键的类型、默认、范围、说明
```

`sf submit` 会跑同一套校验，除非你传 `--no-validate`。