iOS端PyTorch模型部署实战：从TorchScript导出到LibTorch集成

1. 先别急着写代码：iOS 端跑 PyTorch 的路线和我的选型逻辑

在 PyTorch 里把图像分类模型训到 95% 的准确率，和把这个模型真正塞进 iPhone 的 App 里跑起来，中间隔着一条很难一眼看到的沟。最近我做一个 iOS 原生图像分类组件，需要在端上识别商品图片并返回 Top-5 结果，算是把 PyTorch 部署到 iOS 的全流程走了一遍。这篇是 PyTorch 实战系列的第 32 篇，我把从模型导出、Xcode 集成、加载推理到性能调优的完整过程写下来，希望能帮你少踩几个我踩过的坑。

如果你是第一次听到“LibTorch”，不用慌。它就是 PyTorch 的 C++ 版本接口，在 iOS 上跑 PyTorch 模型时，App 里实际链接的是这个库，而不是平时训练用的 Python 包。整篇文章按我实际执行的顺序来写，从选型、导出模型，到真机调试，每一步都尽量把原因讲清楚。这样哪怕你没有做过移动端推理，也能照着落地一个最小可用工程。

1.1 PyTorch 模型上 iOS 的三条主流路线

PyTorch 训练好的模型要跑在 iOS 上，业界常见的方案大概有三条路。

第一条路是把 PyTorch 模型转成 Core ML，然后用 Apple 的 Core ML Framework 加载。这条路优点是系统集成度好，苹果设备上有 ANE（Apple Neural Engine）等硬件加速，性能潜力最大。缺点也很直接：转换过程有算子兼容性风险。你的网络里一旦出现自定义层、动态控制流，或者比较新的注意力结构，coremltools 很可能直接报错，或者转出来的模型结果对不上。

第二条路是先把模型转成 ONNX，再用 ONNX Runtime 的 iOS SDK 去加载。好处是生态中立，模型不被绑定在某一个训练框架上。坏处是多了一层转换，调试链变长。你不仅要保证 PyTorch 到 ONNX 的算子映射正确，还要在 iOS 侧确认 ONNX Runtime 移动版是否包含你需要的算子。遇到问题之后，需要同时排查三个环节，定位起来比较费劲。

第三条路就是直接在 App 里集成 LibTorch，加载 PyTorch 导出的 TorchScript 模型。这条路最大的好处是训练和部署语言统一，Python 侧能跑通的模型，导出后基本能在 iOS 侧跑通，不需要反复处理编译器兼容问题。缺点是包体积会大一些，而且你要自己写 ObjC++ 的桥接代码。我这次商品识别项目选的就是这条路线，核心原因很简单：少一次转换，就少一类错误。

1.2 为什么我弃用 Core ML，直接选择 LibTorch

Core ML 在 iOS 端确实香，系统级优化和 ANE 加速都是实打实的优势。但这次项目必须用一个自己训练的分支模型，里面有一段自定义的 Top-K 筛选逻辑，还有几个数据相关的控制流。我用 coremltools 转了好几次，都卡在算子映射上。为了一个自定义算子去写 Custom Operator，工程量和维护成本比直接引 LibTorch 高得多。

另一个现实问题是迭代节奏。训练团队会频繁调整模型结构，如果转换核心 ML 流程每天都能稳定运行还好，可一旦遇到不支持的算子，一调就是半天。使用 LibTorch 之后，训练团队只需要在保存权重时额外导出一次 TorchScript 文件，iOS 端直接替换模型资源即可。我判断，这个可维护性收益比包体积多出几十 MB 的代价更划算。尤其在国内的 App 发布环境下，多一个动态下发模型的通道，比每次模型更新都走发版要灵活很多。

1.3 这个实战项目的目标和运行环境

这次写的 Demo 对应一个更完整的工程：输入一张相册或相机拍摄的图片，在 iPhone 上跑一次 MobileNetV3-Small 前向推理，输出置信度最高的前 5 个类别名称和分数。为了贴近真实业务，模型输入统一为 3×224×224 的 RGB 图像，预处理使用 ImageNet 的 mean=0.485, 0.456, 0.406 和 std=0.229, 0.224, 0.225。

硬件和软件方面，我的主力调试机是 iPhone 13 和一台 iPhone 8，系统分别覆盖了 iOS 16 和 iOS 15。开发环境是 macOS 14 + Xcode 15.2，PyTorch 使用 1.13.0 版本，对应的 iOS LibTorch Pod 也固定在这个版本。这里提前强调一点：PyTorch 2.x 发布后，LibTorch 的 iOS 支持也在持续更新，但部署逻辑没有本质变化。为了避免把新版本引入的变量混入排查过程，我这次按 1.13 的稳定组合来写。

2. 从权重文件到 TorchScript：写在最前面的模型转换

接下来要解决第一个问题：训练用的权重是 .pth，iOS 端无法直接加载。TorchScript 是 PyTorch 的序列化模型格式，可以脱离 Python 运行时被 C++ 加载。在 iOS 上，LibTorch 加载的就是这种格式。很多人第一次做部署时，会以为这步只是“把权重另存一下”，其实远没有这么简单。

2.1 TorchScript 不是简单的模型快照

TorchScript 不仅保存权值，还把模型的计算图变成一种可序列化、可执行的结构。导出后的文件不仅包含参数，更包含 forward 的完整逻辑。这样，iOS 加载后不需要任何 Python 环境，也能执行推理。你可以把它理解成一份“编译过”的模型包：既保留了权重，也保留了计算流程。

这个特性带来一个容易被忽略的好处：模型导出过一次之后，iOS 端的行为和 Python 端是一致的，因为执行的是同一份图逻辑。当然，前提是导出时没有把 preprocessing 和 postprocessing 混进去。我一般只会导出网络主体，把归一化、缩放、softmax 这些操作留在客户端代码里显式控制，这样线上调整预处理时不用重复导出模型。

2.2 trace 还是 script，我建议先用 trace

TorchScript 有两种导出方式：torch.jit.trace 和 torch.jit.script。trace 用一组示例输入跟踪一次 forward 执行并记录计算路径，适合没有数据依赖分支的模型；script 则直接解析 Python 源码，能处理 if、for 等控制流，但对代码写法要求很高，很多模型用 script 会报语法不支持。

MobileNetV3 没有动态分支，所以 trace 足够，而且 trace 一次不会改变原模型的运算语义，出错概率小。如果你的模型里有基于输入 shape 的 if-else，或者循环次数是动态的，那才需要认真评估 script。实际工程里，我见过不少团队对动态模型强行 trace，结果导出的模型在特殊输入下直接崩掉，排查起来非常痛苦。所以选型时先问自己：我的模型存在动态控制流吗？如果没有，trace 是最稳妥的起点。

2.3 导出并优化 MobileNetV3 的完整代码

按下面这段代码导出并优化 MobileNetV3：

python复制import torch
from torchvision.models import mobilenet_v3_small, MobileNet_V3_Small_Weights

model = mobilenet_v3_small(weights=MobileNet_V3_Small_Weights.IMAGENET1K_V1)
model.eval()

example_input = torch.rand(1, 3, 224, 224)
traced_model = torch.jit.trace(model, example_input)
traced_model = torch.jit.freeze(traced_model)

from torch.utils.mobile_optimizer import optimize_for_mobile
optimized_model = optimize_for_mobile(traced_model)
optimized_model.save("mobilenet_v3_small.pt")

这段代码里有几个关键细节。model.eval() 必须调用，否则 BN 层和 dropout 在导出后会保持训练模式，模型输出可能与线上不一致。torch.jit.freeze 会把 BN 和权重融合、去掉不需要的梯度计算，减小模型体积并提升速度。optimize_for_mobile 是专门为移动端设计的优化器，会把部分算子替换成移动端支持的实现，对控制包体积和提升推理速度都有帮助。

2.4 导出后你不能跳过的一致性校验

模型导出完毕，不能直接拖进 Xcode 就完事。我在一个语义分割项目里吃过亏：某个模型转完以后输出和 Python 端看似一致，但分割结果边缘总是偏几像素，最后发现是导出前的预处理和后处理不一致。这种问题在真机上很难肉眼定位，所以最稳的办法是在导出时就把一致性校验跑掉。

校验方法很简单：

python复制with torch.no_grad():
    y_py = model(example_input)
    y_ts = optimized_model(example_input)

print("max abs diff:", (y_py - y_ts).abs().max().item())

如果最大差异在 1e-5 量级以内，说明导出没有问题。若差异明显，不要急着调 iOS，先回到转换流程排查。另外，建议多准备几张不同亮度的示例图，一起跑一遍对比，尽量避免只验证单张输入造成的偶然一致。我在项目上线前会用一批固定测试图生成回归报告，核心就是保证每次导出的模型行为一致。

3. Xcode 集成 LibTorch：环境配置的每一步都值得记录

模型文件拿到手后，就开始搭 iOS 工程。这一步是大部分纯 PyTorch 用户最不熟悉的部分，也是报错重灾区。我自己第一次配的时候，光是链接问题就折腾了一个晚上。

3.1 用 CocoaPods 引入 LibTorch 最省事

官方提供两种接入方式：手动下载 framework 拖进工程，或使用 CocoaPods。手动方式的好处是不依赖包管理工具，坏处是文件大、升级需要自己动手。在工作项目里，我推荐用 CocoaPods，升级版本、清理缓存都会方便很多。Podfile 如下：

ruby复制platform :ios, '12.0'

target 'TorchMobileDemo' do
  use_frameworks!
  pod 'LibTorch', '~> 1.13.0'
end

执行 pod install 之后，必须打开 .xcworkspace，而不是 .xcodeproj。很多人第一次都会卡在这里。如果一个不留意直接打开旧工程文件，你会发现所有 Pod 相关配置都没有生效，头文件全都找不到。

3.2 必须关闭 Bitcode，并处理 C++ 标准库

LibTorch 在现有版本里并不支持 Bitcode，所以必须到 Build Settings 里找到 Enable Bitcode，设置为 NO。否则链接阶段会报一堆 bitcode 相关错误。另一个重要的点是：所有会调用 LibTorch 的文件最好使用 .mm 扩展名，也就是 Objective-C++ 源文件。这样能把 C++ 接口和 OC 代码放在同一个文件里写，少绕一层封装。

如果你的工程有多个 target，还要留意 Podfile 里 target 是否一致。我一开始把 Pod 加在主 target，却在 Extension 里调用推理，结果链接期找不到符号，浪费了小半天。后来把 pod 同时加到需要使用的 target 下，问题就消失了。

3.3 一个能跑通的模型加载代码

模型文件放进 Xcode 的 Main Bundle 后，可以用如下代码加载：

objc复制#import <LibTorch/LibTorch.h>

std::string modelPath = [[NSBundle mainBundle] pathForResource:@"mobilenet_v3_small" ofType:@"pt"].UTF8String;
torch::jit::script::Module module = torch::jit::load(modelPath);

这不是完整 App，只是最小可跑通的示例。可以看到，加载接口非常直接。但要注意：如果 App 运行时输出日志 File ... not found 或者直接崩溃，第一排查项是模型文件有没有被拷贝进 Main Bundle，第二才是路径编码问题。我见过有人把 .pt 文件放进了 Assets.xcassets，结果运行时路径一直不对，因为 Asset Catalog 会重写资源路径。

ObjC++ 源文件里导入 LibTorch 头文件时，放在 #import <Foundation/Foundation.h> 之后即可。如果报头文件找不到，去检查 Podfile 里的 use_frameworks! 是否写了——这一行决定了头文件是以 framework module 方式暴露给工程的。

4. 从 UIImage 到推理结果：核心流程拆解

工程环境通了，接下来是真正有业务价值的部分：图像转 tensor，推理，输出结果。这里也是最容易出错的地方，因为 iOS 的像素格式和 PyTorch 的 tensor 布局之间有明显的“文化差异”。

4.1 图像转 Tensor 时最容易错的地方

iOS 拿到 UIImage 后，先要重采样到 224×224，再取出 RGB 通道并归一化。很多坑出在两点：第一，UIKit 的 UIImage 默认坐标系和内存排列与 PyTorch 不同；第二，从 CGImage 取出的像素格式可能是 RGBA、BGRA 或 ARGB，需要判断清楚，不能想当然。

我用的是 Core Graphics 方式，可以一次完成缩放和像素读取：

objc复制CGImageRef cgImage = image.CGImage;
CGContextRef context = CGBitmapContextCreate(bytes,
    224, 224, 8, 224 * 4,
    CGImageGetColorSpace(cgImage),
    kCGImageAlphaPremultipliedLast | kCGByteOrder32Big);
CGContextDrawImage(context, CGRectMake(0, 0, 224, 224), cgImage);

这样做得到的 bytes 按每像素 4 字节排列，通常是 RGBA。然后需要把它转成浮点 tensor。PyTorch 模型输入是 NCHW，也就是 channel 维度在最前面。不熟悉的人很容易把 HWC 数据当成 NCHW 直接用，模型倒不会崩，但输出会完全不对。实际转换时，我会先把 RGBA 字节拆成 RGB，再逐通道写入浮点 buffer：

objc复制std::vector<float> data(3 * 224 * 224);
for (int y = 0; y < 224; y++) {
    for (int x = 0; x < 224; x++) {
        int offset = (y * 224 + x) * 4;
        data[0 * 224 * 224 + y * 224 + x] = (bytes[offset + 0] / 255.0f);
        data[1 * 224 * 224 + y * 224 + x] = (bytes[offset + 1] / 255.0f);
        data[2 * 224 * 224 + y * 224 + x] = (bytes[offset + 2] / 255.0f);
    }
}

4.2 预处理参数必须和训练完全一致

我的模型用 ImageNet 预训练权重，所以 mean 和 std 固定为 0.485, 0.456, 0.406 和 0.229, 0.224, 0.225。如果你是自己训练的模型，一定要把训练代码里的 transform 拿过来逐行对照。少用一个归一化或通道顺序搞错，模型准确率会立刻掉到接近随机水平。

实际操作中，我见过一个案例：同学把辨别的 std 除反了，模型输出分数全部集中在一个类别，排了两天才发现。还有一个常见问题是图像方向。用相机拍到竖屏照片时，CGImage 可能带方向信息，如果不先归一化方向，直接重采样，会导致图像旋转 90 度，推理结果自然全错。所以在预处理前，我习惯先把 image.imageOrientation 纠正成 UIImageOrientationUp，再进入后续流程。

4.3 推理与 Top-5 结果的解析

tensor 准备好后，执行推理：

objc复制torch::NoGradGuard no_grad;
std::vector<torch::jit::IValue> inputs;
inputs.emplace_back(input_tensor);
at::Tensor output = module.forward(inputs).toTensor();
at::Tensor scores = output.softmax(1);

这里写上 torch::NoGradGuard 是很多教程不会提的细节。推理时不需要梯度，关闭梯度计算能减少内存占用和潜在的算子开销。之后如果只想要 Top-1，直接用 scores.argmax(1).item<int64_t>() 即可。如果想要 Top-5，我建议先把 scores 拷贝到 std::vector<float>，然后用部分排序算法取前 5 个，这样比在 tensor 上做复杂操作更可控，也更容易把索引映射到类别名。

4.4 绝对不要在主线程跑推理

MobileNetV3-Small 在 iPhone 上看起来轻量，但也需要几十毫秒。如果在主线程直接调用 module.forward，UI 会明显卡顿，用户滑动列表时就能感到掉帧。我建议用 dispatch_async 把整套推理放到后台队列，完成后再回到主线程更新界面：

objc复制dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
    // 图像转换 + 推理 + 结果解析
    dispatch_async(dispatch_get_main_queue(), ^{
        // 更新 UI
    });
});

如果你的 App 里有多个模块同时使用 LibTorch，还需要考虑并发安全。这里最简单有效的办法是给推理入口加一个串行队列，保证同时只有一个线程在调用 module.forward。多个线程同时跑同一个 Module 实例，在线程池场景下不一定崩溃，但结果可能不可复现，排查起来非常麻烦。

5. 真机性能实测与内存调优

模型能跑通只是第一步。对 iOS 应用来说，流畅度、内存、包体大小会影响用户要不要留下这个 App。我在这部分花的时间，甚至比模型转换还要多。

5.1 我在不同 iPhone 上测到的真实耗时时长

同样的模型、同样的 Xcode Release 配置，我在两台真机上分别测了 50 次，去掉最高和最低后取平均：

这个数据只代表我的环境和预处理链路，不代表你的工程也一定一样。但趋势很明确：老设备的推理耗时明显更长。如果产品要覆盖 iPhone 8 这代机型，单帧 78ms 还能接受，但已经不适合做实时视频逐帧识别。如果你的业务对实时性要求高，就要考虑模型压缩、量化，或者使用 Metal 后端来提升性能。

5.2 Release 和 Debug 的差异可以大到三倍

我刚开始在 Xcode 里用 Debug 模式跑真机，iPhone 13 上的耗时一度达到 98ms，被吓了一跳。后来把 Scheme 切到 Release，耗时直接降到 35ms 左右。原因是 Debug 模式关闭了大部分编译器优化，而且会保留更多调试符号，模型推理这种计算密集操作受此影响特别明显。

所以这里给一个硬建议：做性能评估时，一律用 Release 模式，并且把 Scheme 的 Run 配置改成 Release。否则测出来的数据没有参考价值。如果要在 Instruments 里做 CPU 采样，也务必用 Release 模式跑，不然 Profile 结果会被调试逻辑污染。

5.3 控制内存峰值的几个操作

LibTorch 推理期间会分配中间 tensor，频繁调用时内存峰值可能上升。建议在每轮推理外层加 @autoreleasepool，尤其是在循环处理多张图片时：

objc复制@autoreleasepool {
    // 图像预处理 + 推理 + 结果解析
}

因为 UIImage、CGContext 和字节 buffer 都走 autorelease 机制，一个循环里如果不手动排空，内存水位会一直上升，直到系统发出内存警告。我在项目里曾经因为忽略这个细节，在连续识别 30 张图片后 App 被系统杀掉，加了 autoreleasepool 后问题就消失了。

另外，torch::from_blob 构造 tensor 时不会复制数据，而是直接指向外部 buffer。如果这个 buffer 在推理完成前被释放，就会得到未定义行为。稳妥做法是 from_blob(...).clone()，或者确保 buffer 生命周期覆盖到推理结束。为了性能，我会提前申请一个固定大小的 buffer，在 App 启动后常驻，后续每次推理都复用，把内存分配次数降到最低。

5.4 用 Instruments 定位 CPU 热点

我用 Instruments 的 Time Profiler 对 100 次推理做了采样，结果里 at::native:: 下面的算子占大头，这是正常现象。如果发现 malloc 和 free 占比异常，说明内存分配太频繁，可以先做 tensor buffer 复用。如果发现 dispatch_async 占了不少时间，说明任务切得过于频繁，可以一次多处理几帧再返回结果。

有一个容易被忽略的坑：真机连着 Xcode 调试时，如果开启了 Metal API Validation，GPU 相关操作会明显变慢。你可以在 Edit Scheme 里关闭 Metal API Validation，再去测性能。我最初不知道这个开关，性能数据一直偏高，排查了很久才发现是它在影响。

6. 模型更新与后续扩展

在 iOS 上构建 PyTorch 应用，不是一次发布就结束了。模型迭代、兼容性、App 包体控制都是持续要做的事情。这一部分我想分享几个在实战中摸出来的经验，有些是后来踩坑才补上的。

6.1 用远程下发模型替代频繁发版

这次项目做到后期，我发现每次模型更新都要重新提审，周期太长。于是我把模型文件放到远端服务器，App 启动后检查版本号，再下载到 Application Support 目录。这样训练团队改完模型，iOS 端只需要做一轮文件校验即可，不需要 App 发版。需要特别注意的是，远程模型一定要做完整性校验，至少比对 md5，避免下载了损坏文件导致启动崩溃。

下载逻辑也不复杂，但要注意文件写入目录。Main Bundle 是只读的，不能往里写；Documents 目录会被系统备份，不适合放模型；我一般放到 Library/Application Support，并设置 NSURLIsExcludedFromBackupKey 为真。这样既能保证可写，又不会被 iCloud 备份拖慢同步。

6.2 旧 App 加载新模型的兼容性事故

有一次，训练团队把模型结构里的一个 ReLU6 换成了自定义激活函数，然后直接导出了新版本。结果很多用户还在旧版本 App 上，加载新模型后直接崩溃。这个教训让我意识到：模型文件升级和 App 版本之间必须有契约。具体做法是在模型文件内增加一个版本号输入，加载后先检查版本，不匹配就走提示升级或者继续用旧模型的逻辑。

我更建议在服务端维护一份模型版本和最低 App 版本的映射表。比如模型 v3 需要 App 1.2.0 以上才能使用，那么低版本 App 请求时，服务端继续下发旧模型，或者返回一个“更新 App”的提示。这比单纯在客户端判断版本号要灵活，可以避免用户下载了模型却跑不了的问题。

6.3 关于 Xcode 打包发布和真机调试的几个提醒

很多从 Python 转过来的同学，第一次用 Xcode 打包发布时，会忽略证书和签名配置。LibTorch 本身没有特殊签名要求，但如果你的项目开启了 App Sandbox 或者使用了 Extension，需要为每个 target 单独配置签名。真机调试时如果报 unable to install，多半是开发证书信任问题，到手机设置里手动信任一下即可。

还有一个常见的坑：模型文件放在 Main Bundle 后，如果你用了 Xcode 的Copy Bundle Resources，但模型文件超过一定体积，Xcode 可能在打包时做某些压缩。实测下来，.pt 格式一般没问题，但为了保险，我会在启动后打印模型路径和文件大小，确认加载的是完整文件。如果发现文件大小不对，优先检查 Build Phase 里的资源拷贝规则。

6.4 最后分享几个模型侧的小技巧

如果你需要进一步压缩包体，可以尝试 PyTorch 的量化能力，把 FP32 权重转成 INT8。量化之后模型体积可以减少到原来的四分之一左右，但需要重新在 iOS 端做精度验证。另一个方向是蒸馏，把大模型的知识迁移到小模型里，MobileNetV3-Small 只是一个起点，实际业务里可以考虑更小的 EfficientNet-Lite0。

最后再提一个我自己很受用的习惯：每次改动模型导出代码或 iOS 推理代码后，都跑一遍“同一张测试图输出类别是否一致”的回归。这个回归脚本我放在仓库里，只要一行命令就能跑。模型部署这件事，最怕的不是报错，而是“看起来没报错，但行为已经变了”。有这样的回归脚本在，我迭代起来会安心很多。

如果你也想在 iOS 上部署 PyTorch 模型，建议先从一个小分类 Demo 开始，把模型转换、Xcode 集成、推理调用这条链路跑通，再替换成自己的业务模型。这条链路我走过一遍，最大的感受是：模型转换和 Xcode 工程配置是最容易卡住人的地方，但只要把这两关过了，后面基本都是常规工程问题。希望这篇实战记录能帮你少走一些弯路。