# RuntimeError: FSDP 参数在多个 rank 间不匹配。期望参数 'model.fc.weight' 的形状为 [100, 256]，但在 rank 2 上得到 [100, 128]。

- **ID:** `pytorch/fsdp-param-mismatch`
- **领域:** pytorch
- **类别:** config_error
- **验证级别:** ai_generated
- **修复率:** 82%

## 根因

完全分片数据并行（FSDP）期望所有 rank 上的模型架构相同；层维度不匹配表示模型初始化不一致或不同进程加载了不同的模型文件。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| torch>=1.12 | active | — | — |
| torch>=2.0 | active | — | — |
| CUDA 11.x+ | active | — | — |
| NCCL 2.10+ | active | — | — |

## 解决方案

1. ```
   Ensure identical model definition across all ranks by loading the same checkpoint: if rank == 0: torch.save(model.state_dict(), 'init.pt'); torch.distributed.barrier(); model.load_state_dict(torch.load('init.pt', map_location='cpu'))
   ```
2. ```
   Use torch.distributed.barrier() after model creation to synchronize before FSDP wrapping: model = MyModel(); torch.distributed.barrier(); fsdp_model = FullyShardedDataParallel(model)
   ```

## 无效尝试

- **Setting FSDP sync_module_states=True without fixing architecture** — sync_module_states broadcasts parameters from rank 0 but does not resolve shape mismatches; it will fail with the same error. (95% 失败率)
- **Using different random seeds on each rank** — Random seeds affect weight initialization but not model architecture; shape mismatch persists regardless of seed. (80% 失败率)