FSDP初始化顺序错乱会导致use_orig_params=True失效：必须在模型构建过程中通过auto_wrap_policy逐层wrap，而非事后全局封装；否则PyTorch 2.1会静默忽略该参数，使model.parameters()返回sharded view而非原始参数，引发optimizer构造失败或梯度更新错位。
FSDP 初始化顺序错乱会导致 use_orig_params=True 失效
PyTorch 2.1 中 use_orig_params=True 是启用分片后仍能直接访问原始参数（如 model.named_parameters()）的关键开关，但这个参数必须在 FSDP wrapper 构建前就确定——不是在 FSDP(...) 调用里设，而是在其依赖的 auto_wrap_policy 或子模块构造逻辑中隐式生效。一旦模型已构建完毕、参数已注册进 nn.Module，再套 FSDP 就无法回溯修改参数绑定关系。
- 错误做法：先定义完整模型，再全局 wrap：
FSDP(model, use_orig_params=True)—— 此时 PyTorch 2.1 会静默忽略该参数，后续调用model.parameters()仍返回 sharded view，导致 optimizer 构造失败或梯度更新错位 - 正确做法：使用
transformer_auto_wrap_policy或自定义 policy，在模型构建过程中逐层 wrap，确保每层的nn.Parameter在注册时就被 FSDP 管理 - 验证方式：训练前检查
next(model.parameters()).shape是否与原始参数一致（而非被 reshape 成 sharded shape）；若为torch.Size([hidden_size, vocab_size])而非类似torch.Size([sharded_hidden_size, vocab_size])，说明use_orig_params=True已生效
混合精度配置与 mixed_precision 参数强耦合
PyTorch 2.1 的 FSDP 对 mixed_precision 不再做自动降级兼容。如果你沿用旧代码传入 fp16=True 或 bf16=True 单独开关，会触发 TypeError: __init__() got an unexpected keyword argument 'fp16'。
立即学习“Python免费学习笔记（深入）”；
- 必须改用
mixed_precision=fsdp_mp_policy形式，其中fsdp_mp_policy是torch.distributed.fsdp.MixedPrecision实例 - 常见组合：
MixedPrecision(param_dtype=torch.float16, reduce_dtype=torch.float16, buffer_dtype=torch.float16)（全 fp16）或buffer_dtype=torch.bfloat16（推荐，避免 norm/bias 溢出） - 注意：PyTorch 2.1 中
buffer_dtype默认为torch.float32，若不显式指定，BN/LN 的 running_mean/var 会以 fp32 存储，与 fp16 参数混用可能引发 NaN —— 这是训练突然崩溃最隐蔽的原因之一
ShardingStrategy 与 optimizer 分组不兼容
PyTorch 2.1 的 ShardingStrategy.FULL_SHARD 和 NO_SHARD 对 optimizer 的参数分组（如不同 lr 的 weight decay 设置）有严格限制：它只允许单个参数组，否则会报 RuntimeError: FSDP only supports one param group when sharding is enabled。
- 不能直接用
optim.AdamW([{'params': encoder_params}, {'params': decoder_params, 'lr': 1e-5}]) - 解决方法：先统一所有参数的 lr 和 weight_decay，训练稳定后再用
param_group+no_grad手动冻结部分层；或者改用ShardingStrategy.SHARD_GRAD_OP（仅分片梯度和优化器状态），它支持多参数组 - 性能权衡：
SHARD_GRAD_OP显存节省约 30%（相比 DDP），而FULL_SHARD可达 60%+，但后者牺牲了 optimizer 灵活性
PyTorch 2.1 的 FSDP 配置冲突本质是 API 收敛期的“契约收紧”：它不再容忍模糊的参数传递路径，所有策略必须在模型构建早期就明确声明。最容易被忽略的是 buffer_dtype 和 auto_wrap_policy 的联动——哪怕 policy 写对了，buffer 类型没配准，也会在第 3 个 step 后开始出现梯度 nan。
