Back to Details

config-conventions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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)

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

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

Truthiness check for optional booleans

Truthiness check for optional booleans

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

Nested NotRequired: check presence at each level explicitly

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

Hidden boolean default — should come from YAML

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

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

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

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

Chained .get() with hidden defaults at each level

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

Hidden default in code

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

Function parameter defaulting a config value

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

Required attribute: expect it from YAML or user override

precision: str = policy_cfg["precision"]
precision: str = policy_cfg["precision"]

Optional attribute: check for presence

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和配置默认值部分)。