为什么Python环境下的PyTorch权重保存建议使用state

state_dict保存能避开modulenotfounderror，因为其仅存储张量映射而不含模块路径；而torch.save(model)会序列化完整类路径，加载时依赖原环境导入。

为什么python环境下的pytorch权重保存建议使用state_dict方式？

state_dict保存为什么能避开ModuleNotFoundError

直接 torch.save(model) 会把模型类的完整导入路径（比如 myproject.models.ResNetBlock）写进文件，加载时 Python 必须能 import 到那个模块。一旦路径改了、包没装、或只是重命名了文件，就会报 ModuleNotFoundError: No module named 'myproject' —— 这不是模型坏了，是 pickle 把环境“刻”进去了。

model.state_dict() 只返回一个 dict，键是字符串（如 'layer1.0.conv1.weight'），值是 tensor，不带任何模块引用。加载时只要模型类定义存在、层名一致，就能灌进去，和原始代码在哪、叫什么名完全无关。

适合 CI/CD 流水线：训练机和部署机不用共享同一套源码目录结构
适合 Docker 镜像：镜像里只放模型权重和推理脚本，不用打包训练时的整个项目
适合 Hugging Face 或 Model Zoo 分发：用户只需按文档实现对应结构，不依赖你本地的模块路径

跨 PyTorch 版本加载失败大概率出在完整模型保存上

PyTorch 2.0+ 默认启用新序列化格式（_use_new_zipfile_serialization=True），但旧版本保存的完整模型，在新版本中可能因内部类结构变更（比如 nn.Sequential 的属性名调整）而反序列化失败。错误常表现为 AttributeError 或 pickle.UnpicklingError。

state_dict 是纯张量映射，参数格式自 v1.0 起就高度稳定。v1.8 训练的 ResNet 权重，用 v2.3 加载几乎不会出问题——只要你用的模型类本身兼容新版本 API。

Li Python Sec Check

Python 安全规范检查工具：基于 CloudBase 规范、腾讯安全指南，LLM 智能分析（默认禁用，优先本地执行）

下载

团队升级 PyTorch 时，历史 checkpoint 不用重训
论文复现实验：别人用 v1.12 发布的 .pth，你用 v2.3 能直接 load
注意例外：如果用了自定义 torch.nn.Module 且其 __init__ 逻辑在新版中被删改，那即使 state_dict 加载成功，forward 也可能出错

state_dict 支持 selective load 和 mismatch 容忍

微调、迁移学习、多任务头替换等场景下，你往往不需要加载全部参数。比如给预训练 ViT 加一个新分类头，原 state_dict 里没有 'head.weight'，但你可以设 strict=False：

model.load_state_dict(checkpoint, strict=False)

它会跳过缺失或多余的 key，只加载匹配的部分。而完整模型保存做不到这点——要么全加载，要么报 KeyError 或类型不匹配。

可只加载 backbone：{k:v for k,v in sd.items() if 'backbone' in k}
可重映射层名：sd['classifier.weight'] = sd.pop('fc.weight')
可冻结部分参数：加载后对特定层调用 param.requires_grad = False

文件体积和存储成本差异明显

一个 ResNet50 的 state_dict 文件通常 90–100 MB；完整模型保存则常达 130–150 MB，多出来的主要是模型类字节码、闭包变量、调试信息等。这些对推理毫无用处，却会拖慢上传、下载、缓存命中率。

尤其在频繁迭代的训练 pipeline 中，每轮保存 checkpoint 若都用完整模型，磁盘空间和对象存储费用会快速攀升。而 state_dict + optimizer.state_dict() + epoch + loss 的 checkpoint 结构，既轻量又保留恢复所需全部信息。