根本原因是模型结构与权重文件的键名不匹配，PyTorch的load_state_dict()要求键完全一致；常见于DataParallel训练/推理不一致、层名修改未同步、权重保存字段非默认state_dict等。
为什么加载预训练权重会报 KeyError？
根本原因不是模型没加载成功，而是模型结构和权重文件的键名不匹配。PyTorch 的 load_state_dict() 默认要求键完全一致，哪怕只差一个前缀（比如 backbone.conv1.weight vs module.backbone.conv1.weight），就会直接抛 KeyError。
常见诱因包括：模型用 DataParallel 训练但推理时没包装、权重保存时用了 model.state_dict() 但加载时模型带了额外模块（如自定义 head）、或者微调时改了网络层名但没同步更新权重键。
怎么快速检查键名差异？
别猜，直接打印对比：
print("模型键名示例：", list(model.state_dict().keys())[:3])
print("权重键名示例：", list(checkpoint['state_dict'].keys())[:3])如果发现权重键多了 module. 前缀，说明是多卡训练保存的；如果少了，说明加载时模型被 DataParallel 包裹了。其他常见差异还有：fc vs classifier、layer4 vs backbone.layer4。
立即学习“Python免费学习笔记（深入）”；
- 用
checkpoint.keys()确认权重实际存的是state_dict还是model或net - 有些开源模型（如 Detectron2）把权重存在
model字段下，不是默认的state_dict - 用
set(model_keys) - set(weight_keys)找缺失键，set(weight_keys) - set(model_keys)找多余键
如何安全地加载不匹配的权重？
核心是做键名映射，而不是硬删或硬加键。推荐用 strict=False + 键名重映射：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
checkpoint = torch.load("model.pth")
state_dict = checkpoint.get("state_dict", checkpoint)
<h1>移除 module. 前缀（如果模型没用 DataParallel）</h1><p>state_dict = {k.replace("module.", ""): v for k, v in state_dict.items()}</p><h1>或者统一加前缀（如果模型某部分叫 backbone）</h1><p>state_dict = {"backbone." + k: v for k, v in state_dict.items() if k.startswith("conv")}</p><p>model.load_state_dict(state_dict, strict=False)strict=False 不会中断加载，但要留意控制台警告——它会告诉你哪些键被跳过了、哪些没用上。这些信息比报错更有价值。
- 不要用
pop()删除无关键，容易误删关键参数（比如 BN 的running_mean） - 如果只加载 backbone，明确过滤：
{k: v for k, v in state_dict.items() if k.startswith("backbone.")} - 修改键名后务必再校验维度：
model.state_dict()[k].shape == state_dict[k].shape
从源头避免 KeyError 的习惯
训练时就该考虑加载兼容性，而不是等部署时报错：
- 保存权重统一用
torch.save({"state_dict": model.state_dict()}, path)，别直接存model.state_dict() - 避免在
__init__里动态拼接层名（如self.add_module(f"layer_{i}", ...)），会导致键名不可预测 - 如果用了
nn.Sequential，尽量给子模块命名（用OrderedDict），否则键名是数字索引，极易错位 - 微调时新增层，确保新层名不在原始权重中出现，否则可能意外覆盖
最麻烦的情况不是键名不一致，而是键名一致但 shape 不同（比如分类头从 1000 类改成 10 类）。这种不会报 KeyError，但会静默出错——得靠 strict=True 加载一次来暴露问题。
