不踩坑的 PyTorch 部署：详解 state_dict 优势，对比 TorchScript/ONNX 适用场景

前言：被忽视的 "最后一公里" 难题

在深度学习工程中，模型从训练完成到生产部署的“最后一公里”常被忽视。很多团队曾遇到训练环境精度达标，但部署到生产环境却报 ModuleNotFoundError，或因直接保存完整模型导致跨版本失效。这类问题的根源在于对模型保存与加载策略的轻视。

本文将系统解析 PyTorch 模型保存与加载方法，从 state_dict 到 TorchScript/ONNX，提供经得起生产环境检验的工程化方案。

第一章 核心结论：先明确 "做什么" 与 "不做什么"

在展开技术细节前，先明确经过大量工程实践验证的核心结论，为后续讨论奠定基础：

• 推荐方案：训练阶段仅保存模型参数（state_dict），部署阶段通过独立维护的模型结构定义加载参数。这是兼顾灵活性与稳定性的最优选择。

• 不推荐方案：使用torch.save(model)直接保存完整模型对象。这种方式对训练环境存在强依赖，在跨环境迁移时极易失效。

• 进阶方案：跨语言 / 框架部署时，优先导出为 TorchScript 或 ONNX 格式；追求极致性能（如 GPU 推理加速）可结合 TensorRT 等优化引擎进一步处理。

• 新兴趋势：对于安全性要求高的场景，建议采用safetensors格式替代传统的torch.save，规避 pickle 序列化的安全风险。

这些结论并非凭空得出，而是源于对 PyTorch 序列化机制、部署环境特性及工程化需求的深度理解。接下来，我们将从 "为什么不推荐完整模型保存" 入手，逐步展开分析。

第二章 陷阱：直接保存完整模型的风险根源

许多开发者在模型训练完成后，会下意识地使用torch.save(model, "model.pt")保存完整模型对象。这种方式在实验环境中看似便捷，但在生产部署中却隐藏着多重风险。要理解这些风险，需先从 PyTorch 的序列化机制说起。

2.1 序列化机制：pickle 的 "路径依赖" 陷阱

PyTorch 保存完整模型时依赖 Python 的pickle模块，而pickle的序列化逻辑存在一个关键特性：它不保存对象本身的代码，只保存对象的类路径和实例数据。

具体来说，当你执行torch.save(model, "full_model.pt")时，序列化的内容包含：

• 模型实例的所有属性值（包括参数、缓冲区等）

• 模型类的完整路径（如train.models.ResNet）

• 类定义所在模块的引用信息

这意味着，当你在部署环境中使用torch.load("full_model.pt")加载时，Python 解释器必须能通过保存的类路径（如train.models.ResNet）找到完全一致的类定义。哪怕只是将训练时的train/models.py文件移动到部署环境的deploy/model_def.py，都会导致加载失败 —— 因为类路径从train.models.ResNet变成了deploy.model_def.ResNet，pickle无法找到匹配的类定义，从而抛出ModuleNotFoundError。

更隐蔽的问题在于版本依赖：如果训练环境使用的 PyTorch 版本与部署环境存在差异（如训练用 1.10，部署用 2.0），某些内置模块的类路径可能发生变化，同样会导致反序列化失败。

2.2 生产环境中的其他致命缺陷

除了路径依赖，直接保存完整模型还有以下不适应生产环境的缺陷：

• 环境敏感性过强：完整模型序列化包含大量与环境相关的元数据（如 Python 版本、依赖库版本），任何微小的环境差异都可能导致加载失败。某团队曾因部署环境的numpy版本比训练环境低 0.1 个版本，导致模型加载时触发类型不兼容错误。

• 冗余信息膨胀：完整模型对象包含大量与推理无关的训练时数据，如优化器引用、反向传播缓存、中间变量指针等。这些信息会使模型文件体积增加 30%~50%，不仅浪费存储，还会延长加载时间。

• 部署镜像臃肿：由于依赖训练时的类路径，部署环境必须安装所有训练相关依赖（如数据加载库、日志工具、分布式训练组件等），导致容器镜像体积从数百 MB 膨胀到数 GB，显著增加部署成本和启动时间。

• 结构优化受阻：完整模型将结构与参数强绑定，若后期需要对模型结构进行轻量化改造（如移除训练专用层、调整激活函数），必须重新训练并保存完整模型，无法基于已有参数进行灵活调整。

这些问题在实验室环境中可能被掩盖，但在规模化生产部署中，会逐渐演变为系统稳定性的 "定时炸弹"。

第三章 正道：基于 state_dict 的参数与结构分离方案

既然完整模型保存存在诸多风险，那么更可靠的方案是什么？PyTorch 提供的state_dict机制，正是为解决这一问题而设计的轻量级方案。

3.1 state_dict 的本质：参数与结构的解耦

state_dict是 PyTorch 中用于存储模型参数的特殊字典对象，其核心特性是仅包含与模型推理相关的参数数据，不包含任何类路径或环境依赖信息。

具体来说，一个典型的state_dict结构如下：

{
    "conv1.weight": tensor([[[[...]]]]),  # 卷积层权重
    "conv1.bias": tensor([...]),         # 卷积层偏置
    "bn1.running_mean": tensor([...]),   # BatchNorm运行均值（缓冲区）
    "bn1.running_var": tensor([...]),    # BatchNorm运行方差（缓冲区）
    "fc.weight": tensor([[...]])         # 全连接层权重
}

它包含两类关键数据：

• 可学习参数：模型训练过程中通过反向传播优化的权重（weight）和偏置（bias）

• 缓冲区（buffers） ：模型训练过程中自动更新的统计量（如 BatchNorm 的running_mean、running_var，或 PyTorch 2.0 + 中的num_batches_tracked）

state_dict的精妙之处在于与模型结构的解耦：它不存储任何关于模型类定义的信息，仅通过参数名称（如 "conv1.weight"）与模型结构建立映射关系。这意味着，只要部署环境中的模型结构与训练时的模型结构在 "参数名称" 和 "参数形状" 上保持兼容，就能顺利加载参数，而无需关心类路径、文件位置或环境差异。

3.2 标准工作流程：从训练导出到部署加载

基于state_dict的模型保存与加载，需遵循一套标准化流程，确保训练端与部署端的协同性。

3.2.1 训练端：精准导出所需参数

训练端的核心任务是将模型参数从训练环境中导出，需区分 "推理权重" 和 "训练检查点" 两种场景：

场景 1：仅导出推理所需权重
当目标是部署模型进行推理时，只需保存模型的state_dict，无需包含优化器、学习率调度器等训练组件：

# 确保模型处于评估模式（避免BatchNorm等层的状态异常）
model.eval()

# 保存推理权重（推荐使用.pth或.pt作为扩展名）
torch.save(model.state_dict(), "inference_weights.pth")

场景 2：保存训练检查点（用于续训）
若需保存中间结果以便后续继续训练，则需要包含更多训练状态，但需与推理权重分离存储：

# 训练检查点应包含的关键信息
checkpoint = {
    "model": model.state_dict(),           # 模型参数
    "optimizer": optimizer.state_dict(),   # 优化器状态（如动量、学习率）
    "epoch": current_epoch,                # 当前 epoch
    "scaler": scaler.state_dict() if use_amp else None,  # 混合精度训练状态
    "loss": last_loss                      # 最近的损失值（便于监控）
}

# 保存检查点（建议包含epoch信息，便于版本管理）
torch.save(checkpoint, f"checkpoint_epoch_{current_epoch}.pth")

工程实践建议：训练流水线中应自动区分两种文件，推理权重存储在 "部署资产库"，检查点存储在 "训练缓存区"，避免混淆。

3.2.2 部署端：规范加载参数并验证

部署端的核心任务是基于独立定义的模型结构，正确加载参数并验证可用性：

步骤 1：独立定义模型结构
在部署环境中，需单独维护与训练时兼容的模型结构定义（通常放在deploy/model_defs/目录下）：

# deploy/model_defs/classifier.py
import torch.nn as nn

class ImageClassifier(nn.Module):
    def __init__(self, num_classes=10):
        super().__init__()
        self.features = nn.Sequential(
            nn.Conv2d(3, 32, kernel_size=3, padding=1),
            nn.ReLU(),
            nn.MaxPool2d(2, 2),
            nn.BatchNorm2d(32)
        )
        self.classifier = nn.Linear(32 * 16 * 16, num_classes)
    
    def forward(self, x):
        x = self.features(x)
        x = x.view(x.size(0), -1)
        return self.classifier(x)

这个结构定义无需与训练端的文件路径一致，只需保证层名称和参数形状与训练时的模型完全匹配（如训练时的 "features.0.weight" 对应部署时的同名称参数）。

步骤 2：加载参数并处理设备兼容
使用torch.load加载参数文件，并通过map_location参数解决跨设备加载问题：

import torch
from deploy.model_defs.classifier import ImageClassifier

# 1. 初始化模型结构（此时参数为随机值）
model = ImageClassifier(num_classes=10)

# 2. 加载参数文件（map_location指定加载设备）
# 场景A：从GPU训练环境加载到CPU部署环境
state_dict = torch.load("inference_weights.pth", map_location="cpu")

# 场景B：从CPU训练环境加载到GPU部署环境
# state_dict = torch.load("inference_weights.pth", map_location="cuda:0")

# 3. 将参数加载到模型（strict参数控制是否严格匹配所有参数）
model.load_state_dict(state_dict, strict=True)

strict=True是默认值，要求部署模型的所有参数都能在state_dict中找到对应项，且反之亦然。若需兼容模型结构的部分调整（如新增可选层），可设为strict=False，但需后续手动验证关键参数是否加载成功。

步骤 3：设置评估模式并验证
加载完成后，必须将模型设置为评估模式，并通过测试样例验证正确性：

# 设置为评估模式（关键！禁用Dropout、切换BatchNorm到推理模式）
model.eval()

# 验证：使用最小测试样例检查输出是否合理
with torch.no_grad():  # 禁用梯度计算，加速推理
    test_input = torch.randn(1, 3, 32, 32)  # 符合输入形状的随机张量
    output = model(test_input)
    assert output.shape == (1, 10), "输出形状与预期不符"
    print("模型加载验证通过")

model.eval()的作用常被忽视：它会固定 BatchNorm 的统计量（使用训练时的running_mean和running_var），并禁用 Dropout 层，确保推理结果的一致性。若忘记设置，可能导致相同输入产生不同输出，影响线上效果。

第四章 对比实验：完整模型 vs state_dict 的部署差异

为更直观地理解两种方案的差异，我们通过一个模拟生产环境的对比实验来说明。

4.1 实验环境设置

• 训练环境：

  • 目录结构：train/（包含model.py、train.py）
  • 模型类路径：train.model.MyModel

• 部署环境：

  • 目录结构：deploy/（包含model_def.py）
  • 模型类路径：deploy.model_def.MyModel（与训练端路径不同）

4.2 训练端代码实现

# train/model.py
import torch.nn as nn

class MyModel(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = nn.Linear(10, 2)  # 输入维度10，输出维度2
    
    def forward(self, x):
        return self.fc(x)

# train/train.py
from model import MyModel
import torch

# 初始化并训练模型（简化流程）
model = MyModel()
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
# 训练循环（省略）...

# 两种保存方式
torch.save(model, "full_model.pt")         # 完整模型保存（不推荐）
torch.save(model.state_dict(), "weights.pth")  # state_dict保存（推荐）

4.3 部署端代码与结果对比

部署端模型结构定义：

# deploy/model_def.py
import torch.nn as nn

# 与训练端功能相同，但路径不同的模型结构
class MyModel(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = nn.Linear(10, 2)  # 层名称和形状与训练端一致
    
    def forward(self, x):
        return self.fc(x)

测试 1：加载完整模型（失败）

# deploy/load_full_model.py
import torch

try:
    model = torch.load("full_model.pt")
except ModuleNotFoundError as e:
    print(f"加载失败：{e}")
    # 输出：No module named 'train.model'

失败原因：部署环境中不存在train.model.MyModel类路径，pickle无法找到对应的类定义。

测试 2：加载 state_dict（成功）

# deploy/load_state_dict.py
import torch
from model_def import MyModel

# 初始化模型结构
model = MyModel()

# 加载参数
state_dict = torch.load("weights.pth", map_location="cpu")
model.load_state_dict(state_dict)

# 验证
model.eval()
with torch.no_grad():
    x = torch.randn(1, 10)
    output = model(x)
    print(f"推理成功，输出：{output}")
    # 输出：推理成功，输出：tensor([[...]]])

成功原因：state_dict仅依赖参数名称（如 "fc.weight"）与部署端模型结构匹配，与类路径无关。

4.4 关键差异总结

维度	完整模型保存（torch.save (model)）	state_dict 保存（torch.save (model.state_dict ())）
存储内容	模型结构 + 参数 + 环境元数据	仅参数（权重 + 缓冲区）
环境依赖	强依赖训练环境（类路径、版本）	无环境依赖，仅依赖参数名称和形状
部署灵活性	极低（路径变化即失效）	高（支持结构微调，只需参数兼容）
文件体积	大（含冗余信息）	小（仅必要参数）
生产环境适应性	差	优

第五章 进阶方案：跨环境部署的专用格式

当部署场景超出 Python 环境（如 C++ 后端、移动端、跨框架集成）时，state_dict需配合模型结构定义才能使用的特性会带来限制。此时，专用的部署格式（TorchScript、ONNX）成为更优选择。

5.1 TorchScript：PyTorch 生态的跨端部署利器

TorchScript 是 PyTorch 内置的模型序列化格式，它将模型转换为一种可序列化的静态图表示，支持在 Python 和 C++ 环境中加载执行，是 PyTorch 生态内跨端部署的首选方案。

5.1.1 核心优势与适用场景

TorchScript 的核心价值在于：

• 脱离 Python 解释器：转换后的模型可在 C++ 环境中运行，无需依赖 Python，适合高性能后端或嵌入式设备

• 静态图优化：支持自动融合算子、消除冗余计算，提升推理性能

• 版本兼容性：对 PyTorch 版本的敏感性低于完整模型保存，跨版本兼容性更好

适用场景包括：

• C++ 后端部署（如高性能服务器）
• 移动端 / 嵌入式设备（配合 PyTorch Mobile）
• 需要规避 Python GIL 瓶颈的高并发场景

5.1.2 导出方法：trace 与 script 的选择

TorchScript 提供两种导出方式，需根据模型特性选择：

方法 1：torch.jit.trace（跟踪式导出）
适用于无数据依赖控制流的模型（如纯卷积、全连接网络）：

import torch
from model_def import MyModel

# 1. 初始化并加载参数
model = MyModel()
model.load_state_dict(torch.load("weights.pth", map_location="cpu"))
model.eval()

# 2. 准备示例输入（需与实际输入形状一致）
example_input = torch.randn(1, 10)  # 批次大小1，输入维度10

# 3. 跟踪模型计算过程，生成静态图
traced_model = torch.jit.trace(model, example_input)

# 4. 保存TorchScript模型
torch.jit.save(traced_model, "model_traced.ts")

trace通过记录模型对示例输入的计算过程生成静态图，优点是实现简单，但无法处理依赖输入数据的控制流（如if x.sum() > 0: ...）。

方法 2：torch.jit.script（脚本式导出）
适用于包含复杂控制流的模型（如 Transformer 中的掩码逻辑、动态路由网络）：

# 1. 同上，初始化并加载模型
model = MyModel()
model.load_state_dict(torch.load("weights.pth", map_location="cpu"))
model.eval()

# 2. 直接解析模型代码，生成支持控制流的静态图
scripted_model = torch.jit.script(model)

# 3. 保存模型
torch.jit.save(scripted_model, "model_scripted.ts")

script通过解析模型的 Python 代码生成静态图，支持if、for等控制流，但要求模型代码符合 TorchScript 的语法规范（如类型注解、避免某些 Python 特性）。

5.1.3 加载与使用

Python 环境加载：

loaded_model = torch.jit.load("model_scripted.ts")
loaded_model.eval()

with torch.no_grad():
    output = loaded_model(torch.randn(1, 10))

C++ 环境加载（核心代码）：

#include <torch/script.h>
#include <iostream>

int main() {
    // 加载模型
    torch::jit::Module module = torch::jit::load("model_scripted.ts");
    
    // 创建输入张量
    std::vector<torch::jit::IValue> inputs;
    inputs.push_back(torch::randn({1, 10}));
    
    // 推理
    at::Tensor output = module.forward(inputs).toTensor();
    std::cout << output << std::endl;
    return 0;
}

5.2 ONNX：跨框架部署的通用语言

ONNX（Open Neural Network Exchange）是一种跨深度学习框架的中间表示格式，旨在解决不同框架间模型迁移的兼容性问题。PyTorch 支持将模型导出为 ONNX 格式，使其能在 TensorFlow、MXNet、TensorRT 等多种框架和引擎中运行。

5.2.1 核心优势与适用场景

ONNX 的核心价值在于：

• 跨框架兼容性：一次导出，多框架可用（如 PyTorch→TensorRT→NVIDIA GPU 加速）

• 生态丰富：支持多种硬件（CPU、GPU、FPGA）和推理引擎（ONNX Runtime、TensorRT）

• 标准化算子：定义统一的算子规范，减少框架间的语义差异

适用场景包括：

• 跨框架部署（如 PyTorch 模型需在 TensorFlow Serving 中运行）
• 极致性能优化（通过 TensorRT 等引擎进行 GPU 加速）
• 多硬件平台适配（同一模型部署到不同芯片）

5.2.2 导出方法与关键参数

PyTorch 通过torch.onnx.export导出 ONNX 模型，需注意以下关键参数：

import torch
from model_def import MyModel

# 1. 初始化并加载模型
model = MyModel()
model.load_state_dict(torch.load("weights.pth", map_location="cpu"))
model.eval()

# 2. 示例输入（需与实际输入一致）
example_input = torch.randn(1, 10)

# 3. 导出ONNX模型
torch.onnx.export(
    model,                          # 模型对象
    example_input,                  # 示例输入
    "model.onnx",                   # 输出路径
    input_names=["input"],          # 输入节点名称（便于后续调试）
    output_names=["output"],        # 输出节点名称
    opset_version=17,               # ONNX算子集版本（影响算子支持度）
    dynamic_axes={                  # 动态轴设置（支持可变批次大小）
        "input": {0: "batch_size"},
        "output": {0: "batch_size"}
    },
    do_constant_folding=True        # 折叠常量节点，优化计算图
)

关键参数说明：

• opset_version：指定 ONNX 算子集版本，版本越高支持的算子越多（如 PyTorch 2.0 推荐使用 17+），但需与目标推理引擎兼容。
• dynamic_axes：定义可变维度（如批次大小），避免模型被固定为单一输入形状。
• input_names/output_names：为输入输出节点命名，便于后续使用 ONNX Runtime 等工具时指定输入。

5.2.3 验证与优化

导出后需验证 ONNX 模型的正确性，并可通过优化工具提升性能：

验证导出结果：

import onnx
import onnxruntime as ort
import torch

# 1. 检查ONNX模型完整性
onnx_model = onnx.load("model.onnx")
onnx.checker.check_model(onnx_model)  # 无异常则模型结构合法

# 2. 对比PyTorch与ONNX推理结果
model = MyModel()
model.load_state_dict(torch.load("weights.pth"))
model.eval()

with torch.no_grad():
    torch_output = model(example_input)

# 使用ONNX Runtime推理
ort_session = ort.InferenceSession("model.onnx")
onnx_output = ort_session.run(
    None,
    {"input": example_input.numpy()}  # 输入名称需与导出时一致
)[0]

# 计算差异（L2距离）
l2_diff = torch.norm(torch.tensor(onnx_output) - torch_output).item()
print(f"PyTorch与ONNX输出差异：{l2_diff}")  # 应小于1e-5

性能优化：
对于 GPU 部署，可将 ONNX 模型转换为 TensorRT 引擎进一步加速：

import tensorrt as trt

# 简化示例：使用TensorRT转换ONNX模型
TRT_LOGGER = trt.Logger(trt.Logger.WARNING)
builder = trt.Builder(TRT_LOGGER)
network = builder.create_network(1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))
parser = trt.OnnxParser(network, TRT_LOGGER)

with open("model.onnx", "rb") as f:
    parser.parse(f.read())

config = builder.create_builder_config()
serialized_engine = builder.build_serialized_network(network, config)

# 保存TensorRT引擎
with open("model.trt", "wb") as f:
    f.write(serialized_engine)

第六章 工程化最佳实践：从规范到校验

模型保存与加载的工程化，不仅需要技术方案的选择，更需要一套标准化的流程和规范，确保模型资产在全生命周期内的可维护性。

6.1 模型工件的分层存储策略

一个健全的模型资产管理系统应包含三类核心工件，按用途分层存储：

1. 推理权重（核心资产）

   • 内容：仅包含模型state_dict和必要元数据
   • 格式：.pth（或safetensors）
   • 存储位置：生产级资产库（如 MLflow Model Registry、阿里云 OSS）
   • 生命周期：与线上服务绑定，需长期保存

2. 部署专用格式（衍生资产）

   • 内容：TorchScript（.ts）、ONNX（.onnx）、TensorRT 引擎（.trt）等
   • 存储位置：与推理引擎绑定的缓存区
   • 生命周期：可根据基础权重和引擎版本重新生成，无需长期保存

3. 训练检查点（临时资产）

   • 内容：包含模型、优化器、训练状态等完整信息
   • 格式：.pth
   • 存储位置：训练缓存区（如本地磁盘、临时对象存储）
   • 生命周期：训练结束后保留一段时间（如 30 天），用于问题追溯

6.2 元数据管理：模型的 "身份证"

模型工件必须附带详细的元数据，作为跨团队协作的 "契约"。推荐的元数据结构如下：

# 保存模型时同时存储元数据
meta = {
    "model_name": "image_classifier",
    "version": "v1.2.0",
    "framework": "pytorch",
    "framework_version": torch.__version__,
    "input_spec": {
        "shape": (None, 3, 32, 32),  # None表示动态批次
        "dtype": "float32",
        "normalization": {"mean": [0.485, 0.456, 0.406], "std": [0.229, 0.224, 0.225]}
    },
    "output_spec": {
        "shape": (None, 10),
        "dtype": "float32",
        "classes": ["cat", "dog", ..., "bird"]  # 类别映射表
    },
    "training": {
        "dataset": "imagenet-mini",
        "accuracy": 0.923
    },
    "export_time": "2023-10-01T12:00:00Z",
    "author": "cv-team"
}

# 合并参数与元数据保存
torch.save({
    "state_dict": model.state_dict(),
    "meta": meta
}, "image_classifier-v1.2.0.pth")

元数据的核心作用：

• 输入输出校验：部署时验证输入形状、预处理方式是否匹配
• 版本追溯：明确模型版本、框架版本，便于问题定位
• 业务对齐：类别映射表等信息确保模型输出与业务逻辑一致

6.3 命名规范：可读且可追溯

模型文件命名应遵循 "自描述" 原则，推荐格式：

{模型名称}-v{版本号}-{框架版本}-{类型}.{扩展名}

示例：

• text_classifier-v2.1-py310-torch2.0-state_dict.pth

• object_detector-v1.0-torch1.13-onnx_opset17.onnx

• checkpoint_epoch_50-lr_0.001.pt

命名要素说明：

• 模型名称：明确模型用途（如text_classifier）
• 版本号：遵循语义化版本（如v2.1.0）
• 框架信息：便于跨环境兼容检查
• 类型标识：区分state_dict、checkpoint、onnx等
• 扩展：使用标准扩展名（.pth、.onnx等）

6.4 自动化校验：部署前的 "安全网"

任何模型在部署前必须通过自动化校验流程，关键校验点包括：

1. 参数完整性校验

   def check_state_dict_completeness(model, state_dict):
       model_keys = set(model.state_dict().keys())
       state_dict_keys = set(state_dict.keys())
       missing = model_keys - state_dict_keys
       unexpected = state_dict_keys - model_keys
       assert not missing, f"模型缺少参数：{missing}"
       assert not unexpected, f"state_dict包含多余参数：{unexpected}"
   

2. 输出一致性校验
   对比原模型与部署模型（如 ONNX）的输出差异，确保 L2 距离小于阈值（如 1e-5）。

3. 环境兼容性校验
   在目标部署环境（如特定 PyTorch 版本、CUDA 版本）中执行加载和推理测试。

4. 性能基准校验
   记录模型的推理延迟、内存占用基准值，避免部署后性能退化。

这些校验应集成到 CI/CD 流水线中，例如使用 GitHub Actions 或 Jenkins 自动执行：

# 简化的CI配置示例
jobs:
  model-validation:
    runs-on: ubuntu-latest
    steps:
      - name: Load model and validate
        run: |
          python validate_model.py --model_path image_classifier-v1.2.0.pth
      - name: Export and check ONNX
        run: |
          python export_onnx.py --model_path image_classifier-v1.2.0.pth
          python check_onnx_consistency.py --onnx_path model.onnx

第七章 总结与展望：从 "能跑" 到 "稳健"

模型保存与加载看似简单，却是深度学习工程化中 "牵一发而动全身" 的关键环节。从本文的分析可以得出：

• 基础方案：state_dict通过参数与结构的解耦，解决了跨环境迁移的核心痛点，是绝大多数 Python 环境部署的首选。其核心优势在于轻量、灵活且对环境依赖极低。

• 进阶方案：TorchScript 和 ONNX 各有侧重 ——TorchScript 适合 PyTorch 生态内的跨端部署，ONNX 则是跨框架和高性能优化的最佳选择。但需注意，这些格式的导出和维护成本高于state_dict，应根据实际需求选择。

• 工程化关键：模型资产管理不仅需要技术方案，更需要标准化的元数据、命名规范和自动化校验流程，才能从 "能跑" 提升到 "稳健"。

未来趋势方面，safetensors格式的兴起值得关注。作为torch.save的替代方案，它采用更安全的序列化方式（不可执行），加载速度更快，且支持跨语言读取，正在被 Hugging Face 等主流平台采用。对于安全性要求高的生产环境，这可能成为新的标准。

最终，选择模型保存与加载策略的核心原则是：以最小的维护成本，确保模型在训练与部署环境中的一致性和可迁移性。遵循本文所述的最佳实践，能帮助团队避开常见陷阱，构建更可靠的深度学习系统。