执行摘要

• 一句话：修复 FSDP --config 不生效并拒绝未知键
• 推荐动作：值得精读：这是 CLI 配置优先级设计的一个小而完整的范例。重点看两点：一是 set_defaults + 二次解析如何在不引入自定义比对逻辑的情况下实现 CLI > YAML > dataclass；二是用首次 parse 的 vars(args) 作为已知键全集，天然覆盖 extra_args_provider 扩展键。若后续要为其他后端引入 YAML 配置，可直接复用这套模式。

功能与动机

PR 说明指出 --config <yaml> 被文档化为 FSDP 后端的配置机制（docs/developer/experimental-features.md:59），但 load_fsdp_args 仅在 if not hasattr(args, k) 时应用配置条目，而 parser 为 FSDPArgs 每个字段都注册了 argparse action，条件对已声明字段永远为假，于是 'the config file silently dropped every key it was supposed to honor, and silently absorbed every key it was supposed to reject'——YAML 里的 lr 从不生效，拼错的 weigth_decay 则变成无人读取的新属性，训练继续用默认值跑，而且这个错误沿两个方向同时发生。

实现拆解

1. 拆分 parser 构建：在 miles/backends/fsdp_utils/arguments.py 中把原 parse_fsdp_cli 的 parser 构造逻辑抽出为 build_fsdp_parser(extra_args_provider)，返回 parser 对象；parse_fsdp_cli 退化为薄包装 build_fsdp_parser(...).parse_args()，对外名称、签名与既有两个测试调用方完全不变。

2. 两次解析实现优先级：load_fsdp_args 先 build_fsdp_parser 并 parse 一次，拿到包含全部注册 dest 的 vars(args)；若存在 --config 则读 YAML，先做未知键校验，再 parser.set_defaults(**data) 把 YAML 条目写回 parser 默认值并二次 parse。显式 CLI 标志在第二遍解析时覆盖默认值，因此优先级为 CLI > YAML > dataclass，且 extra_args_provider 注入的键也自然进入已知键集合。

3. 未知键拒绝与纠错：新增 reject_unknown_config_keys，用 difflib.get_close_matches 对每个未知键给出 did-you-mean 建议，抛 ValueError 直接终止启动，把「拼错即新属性」的旧行为改成「拼错即报错」。

4. 测试与验证配套：新增 tests/fast/backends/test_fsdp_config_precedence.py，8 个用例覆盖标量与双向 bool 的 YAML 优先级、CLI 反超、未知键/拼写错误拒绝、无 --config 场景；其中两个用例在旧逻辑下会失败，形成承重测试。作者在 H200 上对三棵树验证：main 上 tests/fast/backends/ 全部 467 个用例通过、恢复旧 YAML 逻辑后两个优先级用例如预期变红、叠上 #2384 rebase 后仍全绿。

关键文件：

• miles/backends/fsdp_utils/arguments.py（模块 参数解析；类别 source；类型 core-logic；符号 build_fsdp_parser, parse_fsdp_cli, load_fsdp_args, reject_unknown_config_keys）: FSDP 参数解析主路径：修复 --config 双重失效，新增 build_fsdp_parser 与 reject_unknown_config_keys，并改写 load_fsdp_args 为 set_defaults + 二次解析。
• tests/fast/backends/test_fsdp_config_precedence.py（模块 配置优先级；类别 test；类型 test-coverage；符号 _config, _load, test_config_beats_the_dataclass_default, test_cli_beats_the_config）: 新增 8 个测试钉死配置优先级与未知键拒绝行为，其中两个用例在旧逻辑下会失败，承担防回归职责。

关键符号：build_fsdp_parser, parse_fsdp_cli, load_fsdp_args, reject_unknown_config_keys

关键源码片段

miles/backends/fsdp_utils/arguments.py

FSDP 参数解析主路径：修复 --config 双重失效，新增 build_fsdp_parser 与 reject_unknown_config_keys，并改写 load_fsdp_args 为 set_defaults + 二次解析。

# miles/backends/fsdp_utils/arguments.py
# 修复要点：把 parser 构建与解析拆开，再用「重设默认值 + 二次解析」实现 CLI > YAML > dataclass 优先级。
​
def build_fsdp_parser(extra_args_provider=None) -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser('FSDP SFT Training (miles)')
    # 先注册 --config 本身，它不来自 FSDPArgs 的字段循环
    parser.add_argument('--config', type=str, default=None, help='YAML config path')
    for f in dataclasses.fields(FSDPArgs):
        if f.name == 'config':
            continue # 跳过书签字段，避免与 --config 重复注册
        # Union 类型（如 int | None）取非 None 分支作为 argparse 的 type
        if hasattr(f.type, '__args__'):
            non_none_types = [t for t in f.type.__args__ if t is not type(None)]
            arg_type = non_none_types[0] if non_none_types else str
        else:
            arg_type = f.type
        # keep_fp32_master 注册为反向开关 --disable-fp32-master（store_false）
        if f.name == 'keep_fp32_master':
            parser.add_argument('--disable-fp32-master', dest=f.name, action='store_false',
                                default=f.default, help='Disable the FP32 master copy')
        elif arg_type is bool:
            # store_true 的默认值是 False，可在二次解析时被 set_defaults 改写
            parser.add_argument(f'--{f.name.replace("_", "-")}', action='store_true')
        else:
            parser.add_argument(f'--{f.name.replace("_", "-")}', type=arg_type, default=f.default)
    # 真实 RL 入口通过 extra_args_provider 注入 add_miles_arguments 等额外参数
    if extra_args_provider is not None:
        parser = extra_args_provider(parser)
    return parser
​
​
def reject_unknown_config_keys(data: dict, known: set[str]) -> None:
    unknown = sorted(set(data) - known)
    if not unknown:
        return
    described = []
    for key in unknown:
        # 用 difflib 找最接近的已知键，拼写错误时直接给出修正建议
        close = difflib.get_close_matches(key, known, n=1)
        described.append(f'{key!r} (did you mean {close[0]!r}?)' if close else repr(key))
    raise ValueError(f'unknown key(s) in the YAML config: {", ".join(described)}')
​
​
def load_fsdp_args(extra_args_provider=None):
    parser = build_fsdp_parser(extra_args_provider)
    args = parser.parse_args() # 第一次解析：vars(args) 恰好包含每个注册 action 的 dest
    if args.config:
        with open(args.config) as f:
            data = yaml.safe_load(f) or {}
        # 先拒绝未知键，避免 typo 变成无人读取的属性而静默跑错实验
        reject_unknown_config_keys(data, set(vars(args)))
        # 把 YAML 条目写回 parser 默认值：显式 CLI 标志在第二次解析时依然优先
        parser.set_defaults(**data)
        args = parser.parse_args()
    args.bf16 = not args.fp16 # bf16 是 fp16 的互补开关，保持原有派生逻辑
    return args

tests/fast/backends/test_fsdp_config_precedence.py

新增 8 个测试钉死配置优先级与未知键拒绝行为，其中两个用例在旧逻辑下会失败，承担防回归职责。

# tests/fast/backends/test_fsdp_config_precedence.py
# 通过 monkeypatch 改写 sys.argv 驱动 load_fsdp_args，验证每一层优先级。
import sys
from pathlib import Path
​
import pytest
import yaml
​
from miles.backends.fsdp_utils.arguments import FSDPArgs, load_fsdp_args
​
​
def _config(tmp_path: Path, **entries) -> str:
    # 把任意键值对写成临时 YAML，返回文件路径
    path = tmp_path / 'fsdp.yaml'
    path.write_text(yaml.safe_dump(entries))
    return str(path)
​
​
def _load(monkeypatch: pytest.MonkeyPatch, *argv: str):
    # 模拟命令行，例如 _load(monkeypatch, '--config', cfg, '--lr', '7e-5')
    monkeypatch.setattr(sys, 'argv', ['prog', *argv])
    return load_fsdp_args()
​
​
def test_config_beats_the_dataclass_default(monkeypatch, tmp_path):
    # YAML 里的 lr 必须压过 dataclass 默认值（旧逻辑下该用例失败）
    assert FSDPArgs.lr != 5e-5
    args = _load(monkeypatch, '--config', _config(tmp_path, lr=5e-5))
    assert args.lr == 5e-5
​
​
def test_cli_beats_the_config(monkeypatch, tmp_path):
    # 显式 --lr 必须压过 YAML 里的 lr（一字修改的变体会让该用例失败）
    args = _load(monkeypatch, '--config', _config(tmp_path, lr=5e-5), '--lr', '7e-5')
    assert args.lr == 7e-5
​
​
def test_a_misspelled_key_names_the_field_it_almost_matched(monkeypatch, tmp_path):
    # 拼错 weigth_decay 时，错误信息应提示 weight_decay
    with pytest.raises(ValueError, match='did you mean .*weight_decay'):
        _load(monkeypatch, '--config', _config(tmp_path, weigth_decay=0.1))

评论区精华

本 PR 没有实际 review 评论，合并者 Rockdu 直接 APPROVED 并标注 LGTM。设计权衡主要体现在 PR 说明文档自身的论证：其一，去掉 not 的一字修复不可取，因为 argparse 无法区分「用户显式传入」与「默认值」，无条件 setattr 会让 YAML 覆盖显式 CLI 标志；其二，未知键从 namespace 透传改为抛 ValueError 是有意的 breaking change，因为这是 --config 唯一真正生效过的行为，而程序不认识的键更可能是 typo 而非特性，真正的插件参数应通过 extra_args_provider 注册。

• 为什么一字修复（去掉 not）不可取 (design): 采用 set_defaults + 二次解析：显式 CLI 标志在第二遍 parse 时仍优先，形成 CLI > YAML > dataclass。
• 未知键从静默透传改为抛异常的 breaking change 权衡 (design): 接受 breaking change，未知键抛 ValueError 并附 difflib did-you-mean；真正的插件参数应通过 extra_args_provider 注册。
• 测试的承重性验证 (testing): 在 H200 上对三棵树验证：main 全绿、恢复旧逻辑两用例变红、叠上 #2384 后仍全绿。

风险与影响

• 风险：
  1. 外部配置 breaking change：仓库外仍在使用 --config 的配置只要含未知键（此前透传是唯一实际生效行为）就会从静默透传变成启动即 ValueError，需要一次性体检现有 YAML 的拼写与遗留键。
  2. 已知键集合包含 --config 自身：首次 parse 的 vars(args) 含 --config 键，若 YAML 中出现 config 键会被接受并覆盖路径，但不会触发二次读文件，属于低风险边界情况。
  3. 类型失败方式变化：YAML 值与 argparse 注册类型不匹配（如 lr 传字符串）原本静默透传，现在会在 parse 阶段由 argparse 报错，失败更合理但错误文案来自 argparse 而非自定义逻辑。
  4. 同函数合并面：build_fsdp_parser 同时被 #2384（store_true 覆盖 bool 默认值）修改，作者已验证两种合并顺序下 tests/fast/backends/ 全部通过。
     - 影响：影响范围集中在 FSDP 后端参数入口 miles/backends/fsdp_utils/arguments.py。仓库内没有任何调用点传 --config，因此现有代码路径无行为变化；外部通过 --config 管理 FSDP 训练配置的用户从「半生效的静默透传」切换到「完全生效 + 严格校验」，需要迁移配置。测试面新增 8 个快速用例，覆盖迁移前后的全部优先级组合，能有效防止回归。对团队而言，该 PR 让实验特性文档与真实行为第一次对齐，并为 FSDP 后端后续演进提供了可依赖的配置语义。
     - 风险标记：核心参数解析路径变更, 未知键由透传改为报错（breaking change）, 仓库内无 --config 调用点, 与 #2384 同函数区域修改

关联脉络

• PR #2384 fix(fsdp): stop store_true from shadowing bool defaults in FSDPArgs: 与本 PR 修改同一文件同一函数区域（parser 的布尔参数注册），PR 说明明确在 #2384 之上 rebase 并双向验证合并；二者合并后共同消除 argparse 默认值被隐式改写的问题。
• PR #2386 fix: drop context parallelism from the FSDP backend: 同属 FSDP 后端参数收敛清理，改动 fsdp_utils/arguments.py 与 parallel.py，与本 PR 形成连续的重构脉络。
• PR #2382 fix: drop duplicated rematerialize validation call: 仓库近期集中整理参数解析/校验路径的又一例（miles/utils/arguments.py），与本 PR 反映同一维护脉络。