Configuration Conventions

配置约定

Core Rule

核心规则

YAML is the single source of truth for defaults. Do not set non-

None

defaults in code for configuration values. The loaded YAML (and any user overrides) must supply required values.

YAML是默认配置的唯一可信来源。 不要在代码中为配置值设置非

None

的默认值。加载的YAML（以及任何用户覆盖配置）必须提供所需的值。

Access Config Directly

直接访问配置

For required attributes, write code like

policy_cfg["precision"]

and assume it is present. Do not introduce hidden defaults deep in the code.

对于必填属性，编写类似

policy_cfg["precision"]

的代码，并假设该属性已存在。不要在代码深处设置隐藏的默认值。

Express Optionality via TypedDict

通过TypedDict表达可选性

Use

typing.NotRequired

to mark optional attributes. Optional attributes may be absent/

None

; code may check for their presence.

使用

typing.NotRequired

标记可选属性。可选属性可能不存在或为

None

；代码可以检查它们是否存在。

Where Defaults Live

默认配置的存放位置

Exemplar configs under
```
examples/configs/*.yaml
```
include documented defaults.
Recipe YAMLs under
```
examples/configs/recipes/**/*.yaml
```
are runnable snapshots and may omit documentation.

```
examples/configs/*.yaml
```
下的示例配置包含带文档说明的默认值。
```
examples/configs/recipes/**/*.yaml
```
下的配方YAML是可运行的快照，可能省略文档说明。

Documenting New Config Keys

记录新配置键

When adding a new config key to a

TypedDict

subclass, document:

The key's purpose
Valid values/types
Recommended default (if applicable)

Reflect the default in the exemplar YAMLs under

examples/configs/*.yaml

.

向

TypedDict

子类添加新配置键时，需记录：

该键的用途
有效值/类型
推荐默认值（如适用）

将默认值反映在

examples/configs/*.yaml

下的示例YAML中。

Recipe YAMLs Must Set

defaults

配方YAML必须设置

defaults

Recipe YAMLs under

examples/configs/recipes/**/*.yaml

must set

defaults: <exemplar>.yaml

to inherit from one of the exemplar configs in

examples/configs/*.yaml

. This keeps recipes minimal — they only override what differs from the exemplar.

If a recipe YAML does not have a

defaults

key, run:

bash

uv run ./tools/config_cli.py minimize <recipe.yaml>

This will minimize the config and assign the appropriate

defaults

key.

examples/configs/recipes/**/*.yaml

下的配方YAML必须设置

defaults: <exemplar>.yaml

，以继承

examples/configs/*.yaml

中的某一个示例配置。这样可以让配方保持简洁——它们只需要覆盖与示例配置不同的部分。

如果配方YAML没有

defaults

键，请运行：

bash

uv run ./tools/config_cli.py minimize <recipe.yaml>

这将简化配置并分配合适的

defaults

键。

Accessing NotRequired Fields

访问NotRequired字段

When accessing a

NotRequired

field, use an

in

check or

.get(key)

/

.get(key, None)

. Never provide a non-

None

default — that hides behavior and defeats the purpose of making the field optional.

Do:

python

undefined

访问

NotRequired

字段时，使用

in

检查或

.get(key)

/

.get(key, None)

。绝不要提供非

None

的默认值——这会隐藏行为，违背将字段设为可选的初衷。

正确做法：

python

undefined

.get() with None (not a hidden default)

stop_properly_penalty_coef = cfg.get("stop_properly_penalty_coef", None)

Truthiness check for optional booleans

if master_config.grpo.get("skip_reference_policy_logprobs_calculation"): ...

Nested NotRequired: check presence at each level explicitly

if "megatron_cfg" in policy_config and policy_config["megatron_cfg"]["enabled"]: ...


**Don't:**
```python

if "megatron_cfg" in policy_config and policy_config["megatron_cfg"]["enabled"]: ...


**错误做法：**
```python

Hidden boolean default — should come from YAML

disable_ppo_ratio = cfg.get("disable_ppo_ratio", False)

Hidden non-trivial default — caller has no idea True is the fallback

normalize_rewards = grpo_config.get("normalize_rewards", True)

Chained .get() with hidden defaults at each level

megatron_enable = config.get("megatron_cfg", {}).get("enabled", False)


If a `NotRequired` field is absent, the code should handle that explicitly — not paper over it with a magic default.

megatron_enable = config.get("megatron_cfg", {}).get("enabled", False)


如果`NotRequired`字段不存在，代码应显式处理——不要用魔法默认值掩盖问题。

Forbidden Patterns

禁用模式

Don't:

python

undefined

错误做法：

python

undefined

Hidden default in code

precision = policy_cfg.get("precision", "bfloat16")

Function parameter defaulting a config value

def build_policy(policy_cfg, precision: str = "bfloat16"): ...


**Do:**
```python

def build_policy(policy_cfg, precision: str = "bfloat16"): ...


**正确做法：**
```python

Required attribute: expect it from YAML or user override

precision: str = policy_cfg["precision"]

Optional attribute: check for presence

if "milestones" in scheduler_cfg: configure_milestones(scheduler_cfg["milestones"])


See also: @docs/design-docs/design-and-philosophy.md (TypedDict and Configuration Defaults section).

if "milestones" in scheduler_cfg: configure_milestones(scheduler_cfg["milestones"])


另请参阅：@docs/design-docs/design-and-philosophy.md (TypedDict和配置默认值部分)。

config-conventions

Original

Translation

Configuration Conventions

配置约定

Core Rule

核心规则

Access Config Directly

直接访问配置

Express Optionality via TypedDict

通过TypedDict表达可选性

Where Defaults Live

默认配置的存放位置

Documenting New Config Keys

记录新配置键

Recipe YAMLs Must Set defaults

配方YAML必须设置defaults

Accessing NotRequired Fields

访问NotRequired字段

.get() with None (not a hidden default)

.get() with None (not a hidden default)

Truthiness check for optional booleans

Truthiness check for optional booleans

Nested NotRequired: check presence at each level explicitly

Nested NotRequired: check presence at each level explicitly

Hidden boolean default — should come from YAML

Hidden boolean default — should come from YAML

Hidden non-trivial default — caller has no idea True is the fallback

Hidden non-trivial default — caller has no idea True is the fallback

Chained .get() with hidden defaults at each level

Chained .get() with hidden defaults at each level

Forbidden Patterns

禁用模式

Hidden default in code

Hidden default in code

Function parameter defaulting a config value

Function parameter defaulting a config value

Required attribute: expect it from YAML or user override

Required attribute: expect it from YAML or user override

Optional attribute: check for presence

Optional attribute: check for presence

Recipe YAMLs Must Set
`defaults`

配方YAML必须设置
`defaults`