# 运行时错误：FSDP 检查点加载失败：状态字典中存在意外键："module._fsdp_wrapped_module.flat_param"

- **ID:** `pytorch/fsdp-unexpected-key`
- **领域:** pytorch
- **类别:** module_error
- **验证级别:** ai_generated
- **修复率:** 82%

## 根因

状态字典包含 FSDP 内部键（例如 flat_param），加载到非 FSDP 模型时这些键是意外的，或者保存和加载时的 FSDP 包装层次不匹配。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| torch>=2.0.0 | active | — | — |
| FSDP>=1.12 | active | — | — |

## 解决方案

1. ```
   Save the model state_dict with `state_dict` method instead of the FSDP wrapped module's state_dict, using `model.state_dict()` after unwrapping.
   ```
2. ```
   Use `torch.distributed.fsdp.FullyShardedDataParallel.summon_full_params(model)` to get a full state_dict without FSDP keys.
   ```

## 无效尝试

- **** — Simply ignoring the unexpected keys with strict=False may lead to incorrect model weights. (80% 失败率)
- **** — Renaming state_dict keys manually often introduces errors and is not scalable. (90% 失败率)