# 运行时错误：FSDP参数在各rank间不匹配：期望参数'layer.0.weight'但得到参数'module.layer.0.weight'

- **ID:** `pytorch/fsdp-parameter-mismatch`
- **领域:** pytorch
- **类别:** runtime_error
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

全分片数据并行（FSDP）检测到各分布式rank上的模型参数名称不同，通常由于在FSDP之前将模型包装在额外模块中（例如nn.DataParallel或DDP），或模型初始化不一致。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| pytorch>=2.0 | active | — | — |
| torchvision>=0.15 | active | — | — |
| cuda>=11.7 | active | — | — |
| nccl>=2.14 | active | — | — |

## 解决方案

1. ```
   Remove any extra wrappers (e.g., DataParallel, DDP) before applying FSDP: model = MyModel(); model = FSDP(model) directly, not model = FSDP(DataParallel(model))
   ```
2. ```
   Ensure consistent model initialization across ranks by using the same random seed and loading the same checkpoint: torch.manual_seed(42); model.load_state_dict(torch.load('checkpoint.pt'))
   ```
3. ```
   Use a flat parameter naming scheme by setting param_init_fn in FSDP to avoid prefixes: FSDP(model, param_init_fn=lambda m: m.to_empty(device=torch.cuda.current_device()))
   ```

## 无效尝试

- **Adding more FSDP wrapping layers to fix the mismatch** — Extra wrapping adds more prefixes to parameter names, worsening the mismatch. (95% 失败率)
- **Ignoring the error and continuing training with torch.distributed.barrier()** — Parameter mismatch leads to incorrect gradient synchronization and model corruption. (100% 失败率)