pytorch加载权重时keyerror主因是state_dict键名与模型参数名不匹配，如多卡保存含"module."前缀而单卡加载未去除、官方权重结构与自定义模型不一致等；应打印对比键名、用strict=false跳过不匹配项并检查warning，避免误判shape错误为keyerror。
PyTorch加载权重时KeyError的常见触发场景
绝大多数 KeyError 报错不是模型没加载，而是键名对不上——比如你用 torch.load() 读进来的 state_dict 键是 "backbone.conv1.weight"，但模型定义里实际参数名是 "module.backbone.conv1.weight"（多了一层 module. 前缀），或者反过来。这种不匹配在迁移学习、多卡训练保存/单卡加载、模型封装方式变更时高频出现。
检查state_dict键名与模型参数名是否一致
别猜，直接打印对比：
checkpoint = torch.load("model.pth")
print("Checkpoint keys (first 3):", list(checkpoint.keys())[:3])
<p>model = YourModel()
print("Model named_parameters (first 3):", [(name, param.shape) for name, param in model.named_parameters()][:3])</p>
常见差异点：
- 多卡训练保存的模型带
module.前缀，单卡加载时需去掉：{k.replace("module.", ""): v for k, v in checkpoint.items()} - 模型用了
nn.DataParallel但加载时没 wrap，或反之 - 预训练权重来自 Hugging Face 或 torchvision，其键名结构和你自己定义的模型不一致（比如 torchvision 的 ResNet 权重用
"conv1.weight"，而你模型里叫"stem.conv.weight"） - 保存时用了
model.state_dict()，但加载时误用了torch.load("model.pth")["model"]或其他嵌套 key
安全加载：用load_state_dict(strict=False)跳过不匹配项
如果你只关心主干权重，允许部分参数不加载（比如分类头维度不同），必须显式关掉 strict 模式：
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
model.load_state_dict(checkpoint, strict=False)
这时 PyTorch 会打印哪些键被忽略、哪些缺失，比报错更友好。但要注意：
-
strict=False不代表“自动适配”，只是跳过——缺失的参数仍保持初始化值 - 如果关键层（如 backbone 的 conv1）没匹配上，模型基本等于没加载预训练权重
- 务必检查 warning 输出，确认你期望加载的层确实在 loaded keys 里
torchvision等官方模型的权重加载要走专用接口
别自己手动 torch.load + load_state_dict，容易踩键名坑。直接用官方封装：
import torchvision.models as models model = models.resnet18(pretrained=True) # 自动处理键名、下载、校验 # 或指定 weights（新版本推荐） model = models.resnet18(weights=models.ResNet18_Weights.IMAGENET1K_V1)
自定义模型若想复用 torchvision 权重，得手动映射键名——比如把 "conv1.weight" 映射到你的 "backbone.conv1.weight"，用字典推导重命名：
new_sd = {}
for k, v in checkpoint.items():
if k.startswith("conv1."):
new_sd["backbone." + k] = v
else:
new_sd[k] = v
model.load_state_dict(new_sd, strict=False)
最常被忽略的是：预训练权重的输入通道数（比如 1 或 4 通道）和模型定义不一致，会导致 weight 形状不匹配——这时报的不是 KeyError 而是 RuntimeError，但用户常误以为是键名问题，结果花时间查字典却漏了 shape 校验。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
