备注
点击此处下载完整示例代码
保存和加载模型 ¶
创建于：2025 年 4 月 1 日 | 最后更新：2025 年 4 月 1 日 | 最后验证：2024 年 11 月 5 日
作者：Matthew Inkawhich
本文档提供了关于保存和加载 PyTorch 模型的各种用例的解决方案。您可以阅读整个文档，也可以直接跳到您需要的用例的代码。
当涉及到保存和加载模型时，有三个核心函数需要熟悉：
torch.save：将序列化对象保存到磁盘。此函数使用 Python 的 pickle 实用工具进行序列化。可以使用此函数保存模型、张量以及各种类型的字典对象。
torch.load：使用 pickle 的解序列化功能将序列化的对象文件反序列化到内存中。此函数还支持将数据加载到指定的设备中（参见跨设备保存和加载模型）。
torch.nn.Module.load_state_dict：使用反序列化的 state_dict 加载模型的参数字典。有关 state_dict 的更多信息，请参阅什么是 state_dict？。
内容：
什么是 state_dict ？¶
在 PyTorch 中， torch.nn.Module 模型的可学习参数（即权重和偏置）包含在模型的参数中（通过 model.parameters() 访问）。状态字典（state_dict）实际上是一个 Python 字典对象，它将每个层映射到其参数张量。请注意，只有具有可学习参数（卷积层、线性层等）和已注册缓冲区（如 batchnorm 的 running_mean）的层才会在模型的状态字典中有条目。优化器对象（ torch.optim ）也有状态字典，其中包含有关优化器状态以及使用的超参数的信息。
由于状态字典对象是 Python 字典，因此可以轻松地保存、更新、修改和恢复，这为 PyTorch 模型和优化器提供了大量的模块化。
示例：
让我们看看在《训练分类器教程》中使用的简单模型的状态字典。
# Define model
class TheModelClass(nn.Module):
def __init__(self):
super(TheModelClass, self).__init__()
self.conv1 = nn.Conv2d(3, 6, 5)
self.pool = nn.MaxPool2d(2, 2)
self.conv2 = nn.Conv2d(6, 16, 5)
self.fc1 = nn.Linear(16 * 5 * 5, 120)
self.fc2 = nn.Linear(120, 84)
self.fc3 = nn.Linear(84, 10)
def forward(self, x):
x = self.pool(F.relu(self.conv1(x)))
x = self.pool(F.relu(self.conv2(x)))
x = x.view(-1, 16 * 5 * 5)
x = F.relu(self.fc1(x))
x = F.relu(self.fc2(x))
x = self.fc3(x)
return x
# Initialize model
model = TheModelClass()
# Initialize optimizer
optimizer = optim.SGD(model.parameters(), lr=0.001, momentum=0.9)
# Print model's state_dict
print("Model's state_dict:")
for param_tensor in model.state_dict():
print(param_tensor, "\t", model.state_dict()[param_tensor].size())
# Print optimizer's state_dict
print("Optimizer's state_dict:")
for var_name in optimizer.state_dict():
print(var_name, "\t", optimizer.state_dict()[var_name])
输出：
Model's state_dict:
conv1.weight torch.Size([6, 3, 5, 5])
conv1.bias torch.Size([6])
conv2.weight torch.Size([16, 6, 5, 5])
conv2.bias torch.Size([16])
fc1.weight torch.Size([120, 400])
fc1.bias torch.Size([120])
fc2.weight torch.Size([84, 120])
fc2.bias torch.Size([84])
fc3.weight torch.Size([10, 84])
fc3.bias torch.Size([10])
Optimizer's state_dict:
state {}
param_groups [{'lr': 0.001, 'momentum': 0.9, 'dampening': 0, 'weight_decay': 0, 'nesterov': False, 'params': [4675713712, 4675713784, 4675714000, 4675714072, 4675714216, 4675714288, 4675714432, 4675714504, 4675714648, 4675714720]}]
保存和加载推理模型 ¶
保存/加载 state_dict （推荐） ¶
保存：
torch.save(model.state_dict(), PATH)
加载：
model = TheModelClass(*args, **kwargs)
model.load_state_dict(torch.load(PATH, weights_only=True))
model.eval()
备注
PyTorch 1.6 版本将 torch.save 转换为基于新 zip 文件格式的格式。 torch.load 仍然保留加载旧格式文件的能力。如果出于任何原因想要 torch.save 使用旧格式，请传递 kwarg 参数 _use_new_zipfile_serialization=False 。
保存用于推理的模型时，只需保存训练模型的学习参数。使用 torch.save() 函数保存模型的 state_dict 将为以后恢复模型提供最大的灵活性，这也是推荐保存模型的方法。
PyTorch 的常见约定是使用 .pt 或 .pth 文件扩展名保存模型。
记住，在运行推理之前必须调用 model.eval() 将 dropout 和批量归一化层设置为评估模式。否则，将导致推理结果不一致。
备注
注意， load_state_dict() 函数接受一个字典对象，而不是保存对象的路径。这意味着您必须在将状态字典传递给 load_state_dict() 函数之前反序列化保存的状态。例如，您不能使用 model.load_state_dict(PATH) 来加载。
备注
如果您只想保留表现最好的模型（根据获得的验证损失），请记住 best_model_state = model.state_dict() 返回的是状态的引用，而不是其副本！您必须序列化 best_model_state 或使用 best_model_state = deepcopy(model.state_dict()) ，否则您的最佳 best_model_state 将不断被后续的训练迭代更新。结果，最终的模型状态将是过拟合模型的最终状态。
保存/加载整个模型
保存：
torch.save(model, PATH)
加载：
# Model class must be defined somewhere
model = torch.load(PATH, weights_only=False)
model.eval()
此保存/加载过程使用最直观的语法，代码量最少。以这种方式保存模型将使用 Python 的 pickle 模块保存整个模块。这种方法的缺点是序列化数据绑定到保存模型时使用的特定类和精确的目录结构。这是因为 pickle 不保存模型类本身，而是保存包含类的文件路径，该路径在加载时使用。因此，当在其他项目或重构后使用时，您的代码可能会以各种方式出现错误。
PyTorch 的常见约定是使用 .pt 或 .pth 文件扩展名保存模型。
记住，在运行推理之前必须调用 model.eval() 将 dropout 和批量归一化层设置为评估模式。否则，将导致推理结果不一致。
导出/加载 TorchScript 格式模型
使用 TorchScript 进行推理是一种常见方法，它是 PyTorch 模型的中间表示形式，可以在 Python 以及 C++等高性能环境中运行。实际上，TorchScript 是推荐用于大规模推理和部署的模型格式。
备注
使用 TorchScript 格式，您将能够加载已导出的模型并运行推理，而无需定义模型类。
导出:
model_scripted = torch.jit.script(model) # Export to TorchScript
model_scripted.save('model_scripted.pt') # Save
加载：
model = torch.jit.load('model_scripted.pt')
model.eval()
记住，在运行推理之前必须调用 model.eval() 将 dropout 和批量归一化层设置为评估模式。否则，将导致推理结果不一致。
如需有关 TorchScript 的更多信息，请访问专门的教程。您将熟悉跟踪转换，并学习如何在 C++环境中运行 TorchScript 模块。
保存和加载通用检查点以进行推理或恢复训练 ¶
保存：¶
torch.save({
'epoch': epoch,
'model_state_dict': model.state_dict(),
'optimizer_state_dict': optimizer.state_dict(),
'loss': loss,
...
}, PATH)
加载：¶
model = TheModelClass(*args, **kwargs)
optimizer = TheOptimizerClass(*args, **kwargs)
checkpoint = torch.load(PATH, weights_only=True)
model.load_state_dict(checkpoint['model_state_dict'])
optimizer.load_state_dict(checkpoint['optimizer_state_dict'])
epoch = checkpoint['epoch']
loss = checkpoint['loss']
model.eval()
# - or -
model.train()
当保存通用检查点以用于推理或恢复训练时，除了保存模型的 state_dict 之外，还必须保存优化器的 state_dict。因为其中包含随着模型训练而更新的缓冲区和参数。您可能还想保存的其它项目包括您离开的 epoch、最新的记录训练损失、外部 torch.nn.Embedding 层等。因此，这样的检查点通常比模型本身大 2~3 倍。
要保存多个组件，请将它们组织成字典，并使用 torch.save() 进行序列化。PyTorch 的常见约定是使用 .tar 文件扩展名来保存这些检查点。
加载项目时，首先初始化模型和优化器，然后使用 torch.load() 在本地加载字典。从这里，您可以轻松访问保存的项目，就像您预期的那样查询字典。
记住，在运行推理之前，您必须调用 model.eval() 将 dropout 和批量归一化层设置为评估模式。如果不这样做，将产生不一致的推理结果。如果您想继续训练，请调用 model.train() 以确保这些层处于训练模式。
在一个文件中保存多个模型
保存：¶
torch.save({
'modelA_state_dict': modelA.state_dict(),
'modelB_state_dict': modelB.state_dict(),
'optimizerA_state_dict': optimizerA.state_dict(),
'optimizerB_state_dict': optimizerB.state_dict(),
...
}, PATH)
加载：¶
modelA = TheModelAClass(*args, **kwargs)
modelB = TheModelBClass(*args, **kwargs)
optimizerA = TheOptimizerAClass(*args, **kwargs)
optimizerB = TheOptimizerBClass(*args, **kwargs)
checkpoint = torch.load(PATH, weights_only=True)
modelA.load_state_dict(checkpoint['modelA_state_dict'])
modelB.load_state_dict(checkpoint['modelB_state_dict'])
optimizerA.load_state_dict(checkpoint['optimizerA_state_dict'])
optimizerB.load_state_dict(checkpoint['optimizerB_state_dict'])
modelA.eval()
modelB.eval()
# - or -
modelA.train()
modelB.train()
当保存由多个 torch.nn.Modules 组成的模型，例如 GAN、序列到序列模型或模型集成时，您应遵循与保存一般检查点相同的方法。换句话说，保存每个模型的状态_dict 和相应的优化器。如前所述，您可以通过简单地将其他可能帮助您恢复训练的项目附加到字典中来保存任何其他项目。
PyTorch 的一个常见约定是使用 .tar 文件扩展名保存这些检查点。
加载模型时，首先初始化模型和优化器，然后使用 torch.load() 本地加载词典。从这里开始，您可以像预期的那样轻松访问保存的项目。
记住，在运行推理之前，您必须调用 model.eval() 将 dropout 和批量归一化层设置为评估模式。如果不这样做，将导致推理结果不一致。如果您想继续训练，请调用 model.train() 将这些层设置为训练模式。
使用不同模型的参数启动模型
保存：¶
torch.save(modelA.state_dict(), PATH)
加载：¶
modelB = TheModelBClass(*args, **kwargs)
modelB.load_state_dict(torch.load(PATH, weights_only=True), strict=False)
在迁移学习或训练新的复杂模型时，部分加载模型或加载部分模型是常见的场景。利用训练好的参数，即使只有少数可用，也有助于预热训练过程，并可能帮助您的模型比从头开始训练更快地收敛。
无论您是从缺少一些键的部分状态字典加载，还是加载比要加载到模型中的状态字典有更多键的状态字典，您都可以在 load_state_dict() 函数中将 strict 参数设置为 False 来忽略不匹配的键。
如果您想从一个层加载参数到另一个层，但某些键不匹配，只需将您要加载的状态字典中的参数键名称更改为与您要加载到模型中的键匹配即可。
穿越设备保存和加载模型
在 GPU 上保存，在 CPU 上加载
保存：
torch.save(model.state_dict(), PATH)
加载：
device = torch.device('cpu')
model = TheModelClass(*args, **kwargs)
model.load_state_dict(torch.load(PATH, map_location=device, weights_only=True))
当在 CPU 上加载用 GPU 训练的模型时，请将 torch.device('cpu') 传递给 map_location 函数的 torch.load() 参数。在这种情况下，张量底层的存储会使用 map_location 参数动态重新映射到 CPU 设备。
在 GPU 上保存，在 GPU 上加载 ¶
保存：
torch.save(model.state_dict(), PATH)
加载：
device = torch.device("cuda")
model = TheModelClass(*args, **kwargs)
model.load_state_dict(torch.load(PATH, weights_only=True))
model.to(device)
# Make sure to call input = input.to(device) on any input tensors that you feed to the model
当在 GPU 上加载在 GPU 上训练和保存的模型时，只需将初始化的 model 转换为 CUDA 优化的模型使用 model.to(torch.device('cuda')) 。同时，务必使用 .to(torch.device('cuda')) 函数对所有模型输入进行数据准备。请注意，调用 my_tensor.to(device) 会返回 my_tensor 在 GPU 上的新副本。它不会覆盖 my_tensor 。因此，请记住手动覆盖张量： my_tensor = my_tensor.to(torch.device('cuda')) 。
在 CPU 上保存，在 GPU 上加载 ¶
保存：
torch.save(model.state_dict(), PATH)
加载：
device = torch.device("cuda")
model = TheModelClass(*args, **kwargs)
model.load_state_dict(torch.load(PATH, weights_only=True, map_location="cuda:0")) # Choose whatever GPU device number you want
model.to(device)
# Make sure to call input = input.to(device) on any input tensors that you feed to the model
当在 GPU 上加载在 CPU 上训练和保存的模型时，请将 torch.load() 函数中的 map_location 参数设置为 cuda:device_id 。这将模型加载到指定的 GPU 设备上。接下来，务必调用 model.to(torch.device('cuda')) 将模型的参数张量转换为 CUDA 张量。最后，务必使用 .to(torch.device('cuda')) 函数处理所有模型输入，以准备数据供 CUDA 优化的模型使用。请注意，调用 my_tensor.to(device) 会在 GPU 上返回 my_tensor 的新副本。它不会覆盖 my_tensor 。因此，请记住手动覆盖张量： my_tensor = my_tensor.to(torch.device('cuda')) 。
保存 torch.nn.DataParallel 模型
保存：
torch.save(model.module.state_dict(), PATH)
加载：
# Load to whatever device you want
torch.nn.DataParallel 是一个模型包装器，它能够实现并行 GPU 利用。为了通用地保存 DataParallel 模型，请保存 model.module.state_dict() 。这样，您就可以以任何方式加载模型到任何设备上。
脚本总运行时间：（0 分钟 0.000 秒）
