PyTorch torch.load 升级：解析weights_only与安全迁移指南

前两个月我把训练环境的 PyTorch 从 1.x 升到 2.x，原本一切正常，直到有一天 CI 日志里突然出现一行FutureWarning，内容是torch.load在未来会把weights_only的默认值从False翻转为True。说实话，第一眼看到这个警告时我也愣了一下：weights_only是什么？我从来没有主动传过这个参数，为什么会突然警告？等查完 release notes 和序列化源码，我才意识到这不是一个普通的默认值调整，而是在修复 pickle 反序列化带来的安全漏洞。

这件事适合所有还在用torch.load加载模型文件的人关注。无论你是做 CV、NLP 还是强化学习，每天都在和模型权重、checkpoint 打交道，但这个参数平时几乎不会有人主动设置。好消息是，现在动手迁移完全来得及，而且迁移成本比想象中低。这篇内容会从警告现场开始，拆解weights_only的实现原理、安全风险、迁移方案，以及我在实际项目中踩过的几个坑。

1. 警告出现了：先认识问题现场

1.1 警告长什么样，为什么现在才看到

如果你用的 PyTorch 版本比较新，并且代码里直接写过类似这样的语句：

ckpt = torch.load("model.pth")

那训练或者推理时可能会看到这样一段输出：

FutureWarning: You are using `torch.load` with `weights_only=False` (the current default value), which uses the pickle module implicitly. It is possible to construct malicious pickle data which will execute arbitrary code during unpickling. In a future release, the default value will be flipped to `True`. Explicitly pass `weights_only` to silence this warning.

这个警告的核心意思是：你正在使用的torch.load默认值weights_only=False在底层会隐式调用 pickle 模块，而 pickle 反序列化存在安全隐患，未来版本会把默认值改为True。它不是报错，也不是你的代码有问题，而是 PyTorch 在提前告诉你，你的代码所依赖的“默认行为”即将改变。

为什么以前没有警告，升级到 2.x 之后才出现？因为weights_only参数并不是 2.x 才引入的，它在比较早的版本里就已经存在，只是默认值一直是False，也没有发出过提醒。PyTorch 2.x 的某个版本开始，官方在默认路径上加上了这个FutureWarning，目的就是给所有用户一个缓冲期，避免未来默认值直接翻转时大量项目突然崩溃。说白了，这是一次带着预告的 breaking change，类似“我提前一年告诉你，明年这里要变，大家赶紧改”。

1.2 警告背后的目标：把默认值从“危险”翻成“安全”

理解这个警告，最关键的一点是要明白 PyTorch 为什么要改变默认值。官方想做的是把序列化的安全模型从“默认允许任意对象”切换成“默认只允许权重等基础对象”。

原因很简单：torch.load不仅是读取张量，它会尝试重建整个文件里保存的 Python 对象。一个恶意构造的.pth文件，完全可以在反序列化过程中执行任意代码。这类问题不是理论上的，安全领域对 pickle 模块“不要加载不可信数据”的警告已经存在了很多年。而torch.load的默认行为恰好违背了这个原则，等于在模型共享、模型下载、数据集发布这些场景里打开了一扇门。

所以这个FutureWarning的本质是安全策略调整。weights_only=False作为当前默认值，强调的是“兼容性优先”；未来的weights_only=True，强调的是“安全优先”。我们要做的不是抱怨警告烦人，而是理解这个转向背后的合理性，然后把属于自己的代码调整到新默认值能接受的状态。

2. 核心参数拆解：weights_only是什么，为什么重要

2.1 从 pickle 反序列化说起

要讲清楚weights_only，必须先讲 pickle。pickle 是 Python 自带的序列化模块，可以把 Python 对象转换成字节流，也能从字节流恢复对象。它的能力非常强，强到“你想恢复什么类型，它就能恢复什么类型”。

但能力越强，风险越大。pickle 反序列化时，不仅会恢复数据，还可能会执行对象里包含的__reduce__方法。一个精心构造的 pickle 数据流，可以让torch.load在加载文件时调用eval、exec，甚至直接执行系统命令。更麻烦的是，这种攻击很难通过简单的“检查文件内容”来防御，因为恶意代码被编码在 pickle 流里。

PyTorch 很早就面临这个取舍：模型权重本身是张量，张量反序列化是安全的，但如果用户保存了一个完整的模型对象、自定义配置对象，甚至一个 lambda 函数，这些都需要 pickle 的“完整恢复”能力。weights_only=False就代表完全信任 pickle 的恢复能力，而weights_only=True则把恢复范围限制在一个白名单里，白名单之外的类型都拒绝反序列化。

2.2weights_only=False的安全风险

我之前维护的一个老项目里，有段时间是直接把完整模型对象和训练状态混在一起保存的，代码很省事，一个torch.save全部搞定。后来做安全检查时才发现，这种文件如果被别人传了一个恶意的版本，加载方几乎没有防御能力。

为什么风险这么高？因为weights_only=False时，torch.load实际上的行为等同于：“文件里说什么类型，我就恢复什么类型”。而模型文件常常是公开的、会被多人下载的。如果攻击者替换了文件，普通用户只要执行一次torch.load，就有可能在加载过程中被植入后门。尤其是现在很多教程里都写着“加载预训练模型”这种操作，模型文件往往互相信任，这种信任很容易被滥用。

weights_only=True要做的就是切断这条路径。它只允许加载一些基础类型，比如张量、基础容器、字符串、数字等，这些类型在反序列化过程中不会触发任意的代码执行，所以即使文件是恶意的，也无法利用 pickle 执行危险操作。

2.3 源码层面的实现要点：白名单机制

在 PyTorch 的序列化实现里，weights_only=True不是简单地“不解析代码”，而是替换了底层的Unpickler，传入一个受限的find_class方法。pickle 反序列化时，遇到自定义类会调用find_class来找到对应的类对象。默认情况下，这个方法是全局查找任何可导入的类；而 weights_only 模式下，find_class会被拦截，只允许白名单内的类型通过。

这就可以解释为什么有些人设置weights_only=True后，加载纯权重文件没问题，但加载包含自定义类的 checkpoint 会立刻报错。因为自定义类不在默认白名单里，find_class被拒绝了。从 2.x 开始，PyTorch 还提供了torch.serialization.add_safe_globals这样的 API，允许用户把特定的自定义类手动加入白名单。

理解了这个机制，你就能自己判断哪些文件能安全加载，哪些文件必须显式选择方案。不是所有torch.load都不能用weights_only=True，而是要分情况处理。

3. 迁移工具箱：如何安全、顺手地升级到新默认

3.1 止血：显式设置weights_only

最简单的第一步，是把所有裸的torch.load调用改成显式声明参数。这样警告会消失，代码也具备了“未来默认值改变后不崩溃”的稳定性。

如果你确定你的文件只包含模型权重和基本数据，直接写：

state_dict = torch.load("model.pth", weights_only=True)

如果文件里就是包含自定义对象或者历史遗留的完整模型，先别急着开True，你可以显式写：

ckpt = torch.load("model.pth", weights_only=False)

在这个阶段，显式写False不是为了对抗未来默认值，而是为了告诉读者和 PyTorch：这个加载行为是经过确认的，我知道自己在做什么。警告的目的是“不要默默依赖默认值”，而不是“永远禁止用 False”。

实操中我会先在项目里全局搜索一下所有torch.load调用，统计这些调用加载的文件类型，再决定哪些改成True，哪些保留False。如果只看警告去改代码，很容易改出新的运行时错误。

3.2 根治：调整保存与加载的方式

显式设置参数只是止血，真正要做的应该是调整保存逻辑，让加载方越来越安全。最推荐的做法是：只保存模型权重和必要的张量，不要保存完整模型对象。

完整模型对象的问题在于，它绑定了模型类的定义。以后你改了项目结构、改了类名，这个文件可能就废了；加载时还要求环境里存在一模一样的类定义，否则会报错。把模型类定义和权重数据混在一起，是一种高耦合、低安全的设计。

更稳的保存格式是这样：

torch.save( { "model_state_dict": model.state_dict(), "optimizer_state_dict": optimizer.state_dict(), "epoch": 12, "best_metric": 0.891, "arch": "resnet50", }, "checkpoint.pth", )

这种 checkpoint 里的内容都是基本类型和state_dict张量，weights_only=True基本都能顺利加载，既安全又能保证长期兼容。加载时直接：

ckpt = torch.load("checkpoint.pth", weights_only=True) model.load_state_dict(ckpt["model_state_dict"]) optimizer.load_state_dict(ckpt["optimizer_state_dict"])

我个人强烈建议，所有新旧项目从现在开始就按这个思路来。保存时少一点“偷懒”，加载时就能少很多麻烦。

3.3 兼容新旧版本：写一个通用加载器

如果项目里既有新保存的文件，又有一堆历史遗留文件，可以在加载入口写一个兼容函数，先尝试安全的加载方式，失败再回退。

import torch from torch.serialization import add_safe_globals def load_checkpoint(path, weights_only=True, fallback=False): try: return torch.load(path, weights_only=weights_only) except Exception: # 这里可以根据项目需要，选择记录日志或直接回退 if fallback: return torch.load(path, weights_only=False) raise

调用时先不要轻易开fallback。我建议先跑一遍测试，看看哪些文件在weights_only=True下真的会失败。如果失败比例很高，可以暂时用上面的函数做过渡，同时排期修复那些文件的保存格式。需要注意的是，回退加载等于放弃了安全防护，所以在加载外部来源的模型文件时，绝对不要开fallback。

如果失败原因是文件里包含了某个自定义配置类，而这个类本身是可信且无害的，不要立刻回退到False，优先试试手动注册白名单。

class ExperimentConfig: def __init__(self, lr=0.001, batch_size=32): self.lr = lr self.batch_size = batch_size add_safe_globals([ExperimentConfig]) ckpt = torch.load("config_ckpt.pth", weights_only=True)

add_safe_globals是 PyTorch 提供的白名单扩展入口。它允许你在保持weights_only=True安全模式的前提下，放行你确认可信的类。白名单里注册的类越多，安全性会相应下降，所以只注册真正有必要的类，不要图省事把一堆东西都塞进去。

4. 常见坑位与排查实录

4.1 一开weights_only=True就报错怎么办

这是最常遇到的问题：明明以前torch.load用得好好的，一改成weights_only=True就报错。常见的错误包括：

PickleUnpicklingError: Weights only load failed, unsupported class: some_module.MyModel

或者：

AttributeError: Can't get attribute 'MyConfig' on <module ...>

出现这种情况，说明文件里确实保存了自定义类。你可以看看报错里提到的类名，回想一下它是不是真的有必要保存。如果是模型内部状态的一部分，并且你在加载时需要恢复它，就考虑用状态字典代替；如果只是附带的元数据，尽量简化成 Python 的基本类型，比如dict或str。

我见过的一个项目，会把数据处理管道里的一个对象直接塞进 checkpoint 保存，导致weights_only=True怎么都过不去。后来改了保存逻辑，把那个对象序列化成 JSON 再存，加载就顺畅了。所以遇到这个报错时，先想清楚“这个自定义对象非保留不可吗”，多数情况下答案不是。

4.2 新旧版 PyTorch 之间加载模型的行为差异

不同版本的 PyTorch 对weights_only的支持程度不太一样。在比较老的版本里，weights_only=True能加载的类型更少，用add_safe_globals可能还会提示函数不存在。我不能确定每个小版本的精确差异，但从我实测过的几个版本看，越新的版本白名单越完整，体验越好。

如果你的项目需要在多个 PyTorch 版本之间兼容，建议写一个小的版本判断，只在新版本里尝试weights_only=True，老版本还是走原来的逻辑。这样能避免在新版本上被迫修改，而老版本环境中又因为 API 缺失而崩溃。

还有一个容易忽略的点：保存文件的 PyTorch 版本和加载文件的 PyTorch 版本不一致时，文件里的张量存储格式可能不同。这跟weights_only没有直接关系，但如果你升级到 2.x 后立刻开始调整torch.load参数，连续遇到奇奇怪怪的报错，先分清楚哪些是版本兼容问题，哪些是weights_only问题，别混在一起排查。

4.3 实际项目中的一次“惊魂”记录

有一次我在跑一个很久没动过的训练任务，升级完环境后训练代码没有改，直接加载旧模型，突然发现程序执行到一半输出了很多异常内容。排查之后发现，问题不是weights_only本身，而是那个 checkpoint 文件是用很老的设计保存的，里面除了权重之外，还保存了一个自定义类，我的训练脚本在加载后访问那个类的新字段时，因为类定义已经变了，导致运行时崩溃。

之后我把 checkpoint 重新设计成了“权重 + 元数据”的简单结构，并改用weights_only=True加载。整个过程看上去多写了几行保存代码，但从此再也不用担心外部文件加载安全问题，也再没有被“类定义不匹配”折磨过。

另一个小技巧是：加载模型文件后，先检查一下对象的类型和 keys，再交给模型加载。不要盲目信任文件内容。示例：

ckpt = torch.load("model.pth", weights_only=True) assert isinstance(ckpt, dict), "unexpected checkpoint format" assert "model_state_dict" in ckpt, "missing model_state_dict"

这套检查看起来不起眼，却能帮你捕获很多低级错误，尤其是在多人协作、模型文件由别人导出的场景里。

5. 保存格式与weights_only的兼容矩阵

5.1 不同保存内容的加载效果对比

我整理了一个非常实用的对照表，方便你在改代码前快速判断某个加载路径是否安全。

这个表是我在实际项目中总结出来的，不是完整的官方文档，但覆盖了最常见的场景。测试时可以用一个很小的脚本，把各种保存内容都用weights_only=True加载一遍，快速建立规则感。

5.2 带元数据的 checkpoint 实战

我在线上项目里常用的 checkpoint 结构是这样的：

torch.save( { "model_state_dict": model.state_dict(), "optimizer_state_dict": optimizer.state_dict(), "epoch": epoch, "best_score": best_score, "hyperparameters": { "lr": 1e-3, "batch_size": 64, "model_name": "resnet50", }, "created_at": "2025-01-01", }, "best_model.pth", )

这个 checkpoint 里的所有内容都是安全类型：字典、张量、字符串、整数、浮点数。它既方便写测试，也方便部署推理。加载时直接使用：

ckpt = torch.load("best_model.pth", weights_only=True)

没有警告，没有报错，未来默认值翻转也不受影响。如果你的项目还不确定怎么调整，直接参考这种结构基本不会出错。

如果你有更复杂的配置，建议单独存成一个 JSON 或 YAML 文件，不要塞进.pth文件里。这样模型文件保持纯净，配置文件的读取也有更多选择，还能避免 pickle 反序列化带来的风险。

5.3 自定义类的白名单管理

有些场景下确实没法避免自定义类。例如某些历史 checkpoint 里保存了数据增强的配置类，或者一个带状态的验证器。这种情况下，正确做法是明确注册白名单，而不是关掉weights_only。

import torch from torch.serialization import add_safe_globals # 确认这是自己项目里的可信配置类 from my_project.config import AugmentConfig, LRPolicy add_safe_globals([AugmentConfig, LRPolicy]) ckpt = torch.load("legacy.pth", weights_only=True)

我建议把add_safe_globals的调用集中放在一个文件里，比如serialization_compat.py，方便统一审查。不要在加载函数的深处零散注册，那样时间一长，自己都分不清注册了哪些类。集中管理还有一个好处：未来如果代码库清理了某个类，你可以在一个地方同步移除注册。

6. 一点长期维护的建议

这段内容不算代码层面的硬核知识，而是我在更新了大量项目后的一点切身感受。PyTorch 这次对torch.load默认值的调整，本质上是在给所有用户补一堂安全课。以前大家习惯把torch.load当成一个简单的“读模型”接口，很少有人关心底层 pickle 逻辑。现在官方用了FutureWarning这种温和的方式提醒大家，算是非常体面了。

在维护自己的项目时，我把这条规则纳入了代码规范：凡是涉及加载外部模型文件的代码，默认使用weights_only=True；凡是使用weights_only=False的地方，必须在代码注释里写清楚为什么，并且确认文件的来源可信。因为时间久了，项目里的新成员可能不清楚哪些文件是外部传入的，如果他们看到一个人人都用的加载函数默认是False，很容易形成“反正大家都这么做”的错觉。

如果你手头有一个长期维护的代码库，我建议尽早启动迁移，不要等到 PyTorch 默认值真正翻转之后再做。到时候全仓库突然出现大面积加载失败，排查起来会非常被动。把显式设置weights_only当成一次代码清理，顺带把所有裸的torch.load检查一遍，其实不会花太多时间，但能避免很长时间的心惊肉跳。

最后分享一个小经验：升级 PyTorch 版本之后，第一次运行测试时不要只关注有没有报错，也要留意警告输出。像FutureWarning这类信息往往是在提前预演未来的变化，越早处理越省心。这次weights_only的调整就是一个很典型的例子，它给足了缓冲时间，就看我们有没有认真对待。