企业官网建设流程全解析

1. 模型交付的最后一公里难题

做过模型部署的人大概率都经历过这种场景：在本地训练好的 PyTorch 模型，换一台机器就报ModuleNotFoundError，或者因为某个自定义算子的依赖版本对不上，直接加载失败。更头疼的是，当你把model.pt发给同事或者部署到推理服务上时，对方的环境里可能压根没有你项目里那些自定义的模块、配置文件、甚至第三方小工具库。

torch.package就是冲着这个痛点来的。它做的事情说起来很朴素：把一个 PyTorch 模型以及它运行所需要的全部代码依赖，打包成一个独立的归档文件。这个归档文件里不只有权重参数，还有模型定义、自定义层、辅助函数、甚至你项目里那些不起眼但缺了就报错的工具模块。拿到这个包的人，不需要克隆你的整个仓库，不需要手动对齐依赖版本，只要环境里有兼容版本的 PyTorch，就能直接加载运行。

这篇文章适合谁看？如果你正在做模型交付、跨团队协作、或者想把模型固化成一个可复现的推理单元，那torch.package值得你花时间研究。如果你只是在自己机器上跑跑 demo，那可能暂时用不上，但了解一下它的思路也没坏处，因为模型打包这件事迟早会找上你。我下面会从设计思路、核心机制、实操步骤、踩坑记录几个维度，把torch.package的完整使用路径讲清楚，尽量做到你照着做就能跑通。

2. 为什么需要独立打包而不是简单保存权重

2.1 传统保存方式的局限性

大部分人保存 PyTorch 模型用的是torch.save(model.state_dict(), ...)或者torch.save(model, ...)。前者只存参数，加载的时候你得先有模型类的定义代码，还得保证代码版本一致；后者虽然把整个模型对象序列化了，但它依赖 pickle 机制，本质上还是要求加载端能 import 到原来的模块路径。换句话说，这两种方式都没有解决“代码依赖”的问题。

我遇到过最典型的情况是这样的：项目里写了一个自定义的FocalLoss，放在losses/custom.py里，训练脚本 import 了它。保存模型的时候只存了state_dict，推理脚本加载时忘了把losses这个包带过去，结果直接报模块找不到。还有一种更隐蔽的，模型定义里用了一个第三方的注意力机制实现，版本升级后接口变了，加载出来的模型行为跟训练时不一致，这种问题排查起来非常费劲。

2.2 torch.package 解决的核心问题

torch.package的思路是把“模型”这个概念从“一个权重文件”扩展成“一个自包含的运行时单元”。它通过 Python 的 import 钩子机制，在打包时追踪模型代码所依赖的所有模块，把这些模块的源码一起收进归档文件。加载的时候，它用一个隔离的 importer 从归档里读取这些模块，而不是从当前环境的sys.path里找。

这样做有几个直接好处。第一，代码和权重绑定在一起，版本不会错位。第二，加载端不需要安装模型定义所依赖的那些内部包。第三，你可以对打包内容做精细控制，比如排除掉不需要的测试代码、排除掉 CUDA 相关的可选依赖，让包体积更小。第四，它支持“extern”和“intern”两种模式，让你决定哪些依赖打进包里、哪些依赖加载端自己提供，这个灵活性在实际部署中非常关键。

2.3 适用场景与不适用场景

torch.package最适合的场景是：模型包含自定义代码、需要跨环境交付、希望推理端尽量少装东西。比如你把模型交给一个只负责跑推理的工程团队，他们不想关心你的训练代码结构，只想拿到一个包就能跑。

但它也不是万能的。如果你的模型依赖了大量 C++ 扩展、或者依赖了某些无法被打包的动态库，那torch.package帮不了你。另外，它对 Python 版本和 PyTorch 版本有一定要求，跨大版本打包加载可能会出问题。还有一个现实问题：打包后的文件体积可能比你想象的大，因为它会把依赖的源码都塞进去，如果依赖链很深，包会膨胀。这些限制我在后面的踩坑部分会详细说。

3. 核心机制拆解：PackageExporter 与 PackageImporter

3.1 打包端：PackageExporter 的工作流程

PackageExporter是整个打包过程的入口。它的工作流程大致分三步：首先，你创建一个 exporter 实例，指定输出路径；然后，你调用save_pickle或save_text等方法把模型对象写进去；最后，调用close()完成归档。在这个过程中，exporter 会分析你写入的对象，追踪它引用的所有模块，根据你配置的intern和extern规则决定哪些模块打进包、哪些留给外部环境。

这里的关键概念是“依赖追踪”。当你把一个模型对象交给 exporter 时，它会检查这个对象的类定义在哪个模块里，然后递归地检查那个模块 import 了哪些东西。这个过程是静态分析加运行时追踪的结合，所以有些动态 import 的代码可能追踪不到，需要你手动处理。

import torch import torch.package # 假设我们有一个自定义模型 from my_project.models import CustomModel model = CustomModel() model.load_state_dict(torch.load("weights.pt")) with torch.package.PackageExporter("model_package.pt") as exporter: exporter.intern("my_project.**") exporter.extern("numpy.**") exporter.extern("torch.**") exporter.save_pickle("model", "model.pkl", model)

上面这段代码里，intern("my_project.**")表示把my_project包下的所有模块都打进归档；extern("numpy.**")和extern("torch.**")表示这两个依赖不打进包，加载端自己提供。这个配置逻辑很直观：你自己的代码打进包，通用的第三方库让环境提供。

3.2 加载端：PackageImporter 如何还原运行时

加载端的PackageImporter做的事情跟 exporter 对称。它打开归档文件，创建一个隔离的模块查找器，当你从包里读取对象时，它会从归档里加载对应的模块代码，而不是从当前环境的sys.path里找。这就保证了加载端用的是打包时的那份代码，不会因为环境里的同名模块而产生冲突。

import torch.package importer = torch.package.PackageImporter("model_package.pt") model = importer.load_pickle("model", "model.pkl") model.eval() # 直接推理 with torch.no_grad(): output = model(torch.randn(1, 3, 224, 224))

这段加载代码非常干净，不需要 import 任何my_project里的东西。PackageImporter会自动从归档里解析出CustomModel的定义并完成反序列化。这就是torch.package最核心的价值：加载端与打包端的代码结构解耦。

3.3 intern 与 extern 的取舍逻辑

intern和extern的配置是使用torch.package时最需要想清楚的地方。简单说，intern是把模块打进包，extern是声明这个模块由外部环境提供。两者的取舍直接影响包的体积、可移植性和加载端的依赖要求。

我的经验法则是这样的：你自己的项目代码、自定义算子、配置文件，一律intern；PyTorch 本身、NumPy 这类大型基础库，一律extern，因为加载端几乎不可能没有它们，而且把它们打进包会让包体积暴涨。对于那些体积不大但加载端不一定有的小依赖，比如yaml、omegaconf之类的配置解析库，你可以选择intern，代价是包稍微大一点，但换来的是加载端更省心。

还有一个细节：extern的模块在加载端必须存在且版本兼容。如果你extern("numpy.**")，但加载端的 NumPy 版本跟打包时差异很大，可能会出现行为不一致。所以对于版本敏感的依赖，宁可intern也不要extern，除非你确定加载端环境可控。

4. 完整实操：从零打包一个带自定义模块的模型

4.1 项目结构与依赖梳理

我先构造一个典型的项目结构，模拟真实场景中模型代码分散在多个模块里的情况。这个结构里包含了模型定义、自定义损失函数、一个配置解析工具，以及一个被模型调用的辅助函数。

my_project/ __init__.py models/ __init__.py backbone.py head.py losses/ __init__.py focal.py utils/ __init__.py config.py train.py

backbone.py里定义了一个简单的卷积特征提取器，head.py里定义了分类头，模型类把它们组合起来。focal.py里是一个自定义的 Focal Loss 实现，虽然推理时用不到，但如果模型定义里引用了它，打包时就会被追踪到。config.py里是一个读取 YAML 配置的小工具。

4.2 编写打包脚本的关键步骤

打包脚本的核心是正确配置intern和extern，然后把模型对象和必要的元信息写进归档。我一般会把模型、配置、以及一个版本标记都打包进去，方便加载端做校验。

import torch import torch.package from my_project.models import CustomModel from my_project.utils.config import load_config # 加载配置和权重 config = load_config("config.yaml") model = CustomModel(config) model.load_state_dict(torch.load("checkpoints/best.pt", map_location="cpu")) model.eval() with torch.package.PackageExporter("packaged_model.pt") as exporter: # 把自己的项目代码全部打进包 exporter.intern("my_project.**") # 基础库留给外部环境 exporter.extern("torch.**") exporter.extern("numpy.**") exporter.extern("yaml.**") # 保存模型对象 exporter.save_pickle("model", "model.pkl", model) # 保存配置，方便加载端查看 exporter.save_text("config", "config.yaml", open("config.yaml").read()) # 保存版本标记 exporter.save_text("meta", "version.txt", "v1.0.0")

这里有个容易忽略的点：save_text可以用来存非 Python 对象的文本内容，比如配置文件、版本号、甚至一份简单的使用说明。加载端可以用load_text读出来。这个功能在实际交付中很有用，相当于给包附带了一份自描述信息。

4.3 加载与推理验证

打包完成后，我建议在一个干净的 Python 环境里做加载验证，最好是把my_project从sys.path里移除，模拟加载端没有源码的情况。验证脚本如下：

import torch import torch.package importer = torch.package.PackageImporter("packaged_model.pt") # 读取版本和配置 version = importer.load_text("meta", "version.txt") config_text = importer.load_text("config", "config.yaml") print(f"Package version: {version}") # 加载模型 model = importer.load_pickle("model", "model.pkl") model.eval() # 推理测试 dummy_input = torch.randn(1, 3, 224, 224) with torch.no_grad(): output = model(dummy_input) print(f"Output shape: {output.shape}")

如果这段代码能跑通，说明打包是成功的。我实测下来，只要intern和extern配置正确，加载端不需要任何额外的pip install，也不需要把项目源码放过去。这一点在跨团队交付时非常省事。

4.4 包体积与依赖分析

打包完成后，建议检查一下包的大小和内容。torch.package提供了一个PackageExporter的__exit__阶段会输出一些统计信息，但你也可以手动分析归档内容。我一般会关注两件事：包体积是否合理，以及有没有意外打进大文件。

如果发现包体积异常大，常见原因是某个大依赖被intern了，或者模型权重本身很大。对于权重，可以考虑用半精度保存；对于依赖，检查extern规则是否覆盖了所有大型库。另外，torch.package默认会把.pyc文件也打进去，如果你在意体积，可以在打包前清理__pycache__目录。

5. 踩坑记录与常见问题排查

5.1 动态 import 导致的模块丢失

torch.package的依赖追踪基于静态分析和运行时追踪，对于动态 import 的代码，比如用importlib.import_module在运行时根据字符串加载模块，它可能追踪不到。我遇到过一次，模型里根据配置动态加载了一个后处理模块，打包时没被发现，加载时报模块找不到。

解决办法是显式地把这些模块intern进去，或者在打包前手动 import 一次，让追踪器能发现它们。更稳妥的做法是避免在模型代码里使用动态 import，如果非用不可，就在打包脚本里加一行exporter.intern("my_project.postprocess")显式声明。

5.2 extern 模块版本不匹配

前面提到过，extern的模块由加载端提供，如果版本不匹配，可能出现各种奇怪的问题。我踩过的一个坑是：打包时用的 NumPy 是 1.24，加载端是 1.19，某些 API 行为有差异，导致数值结果对不上。排查这种问题很痛苦，因为报错信息往往不直接指向版本。

我的建议是：对于数值计算相关的依赖，尽量在打包时记录版本号，加载端做校验。可以在打包时用save_text存一份requirements.txt，加载端读取后跟当前环境对比。虽然不能自动解决版本问题，但至少能快速定位。

5.3 自定义 C++ 扩展的处理

如果你的模型依赖了自定义的 C++ 扩展，torch.package无法把编译好的.so文件打包进去。这类依赖必须由加载端提供，你需要把它们extern掉，并确保加载端安装了对应版本的扩展。这是一个硬限制，没有太好的绕过办法。如果扩展是必须的，那加载端的环境准备就无法完全省略。

5.4 常见问题速查表

5.5 几个实操心得

第一，打包前先在一个干净环境里跑一遍加载测试，不要等到交付后才发现问题。第二，养成记录依赖版本的习惯，save_text存一份环境信息，成本很低但收益很大。第三，intern规则尽量精确，不要图省事用intern("**")，那样会把整个环境都打进去，包会大到无法接受。第四，对于模型权重，考虑用torch.save的半精度或者量化版本，能显著减小包体积。

6. 进阶用法与扩展思路

6.1 多模型打包与命名空间管理

一个包里可以存多个模型对象，通过不同的save_pickle的 package 名和资源名来区分。比如你可以把检测模型和分类模型打进同一个包，加载时按名字读取。这在需要交付一整套推理能力的场景下很有用，减少了文件管理成本。

with torch.package.PackageExporter("multi_model.pt") as exporter: exporter.intern("my_project.**") exporter.extern("torch.**") exporter.save_pickle("detector", "model.pkl", detector) exporter.save_pickle("classifier", "model.pkl", classifier)

加载时分别用load_pickle("detector", "model.pkl")和load_pickle("classifier", "model.pkl")读取即可。命名空间的管理逻辑跟 Python 的包管理类似，清晰命名能避免混乱。

6.2 与 TorchScript 的配合使用

torch.package和 TorchScript 可以配合使用。你可以先用torch.jit.script或torch.jit.trace把模型转成 TorchScript，再打包。这样做的好处是加载端不需要 Python 解释器就能运行模型，适合某些受限环境。但要注意，TorchScript 对动态控制流的支持有限，转换过程中可能需要改写模型代码。

6.3 打包内容的版本管理策略

在实际项目中，我建议给每个打包文件附带一个版本号和一份变更记录。版本号可以用语义化版本，变更记录用save_text存进去。这样当加载端遇到问题时，能快速确认用的是哪个版本、这个版本改了什么。这个习惯在多人协作的项目里尤其重要，能省下大量沟通成本。

6.4 包的分发与存储

打包文件本质上就是一个 zip 归档，你可以像分发普通文件一样分发它。我一般会把它上传到内部的制品库，附带版本号和校验和。加载端下载后先校验完整性，再加载。如果包体积很大，可以考虑分片传输或者用压缩率更高的归档格式，但torch.package本身的格式是固定的，压缩需要在外部做。

7. 一些个人体会

torch.package这个工具我用了一年多，最大的感受是它把模型交付这件事从“靠文档和口头约定”变成了“靠一个自包含的文件”。以前交付模型要写一堆环境准备说明，现在只需要给一个包和一句“装好 PyTorch 就能跑”。这个转变在跨团队协作中价值很大。

但它也不是银弹。依赖追踪的盲区、C++ 扩展的限制、版本兼容的坑，这些都需要在实际使用中慢慢积累经验。我的建议是，先在非关键项目上试用，摸清楚它的边界，再逐步推广到核心交付流程里。另外，不要指望它能解决所有环境问题，它解决的是“代码依赖”这一层，底层的 Python 版本、PyTorch 版本、系统库这些，还是需要你在交付前确认清楚。

最后分享一个小技巧：打包时把一份最小可运行的加载示例也save_text进去，加载端的人拿到包之后，直接照着示例改就行，能省掉很多来回沟通。这个习惯看起来不起眼，但在实际协作中非常实用。