目录
  • 文档 >
  • 在 Apple 平台上集成和运行 ExecuTorch
快捷方式

在 Apple 平台上集成和运行 ExecuTorch

作者： Anthony Shoumikhin

适用于 iOS 和 macOS 的 ExecuTorch 运行时以预构建的 .xcframework 二进制目标集合形式分发。这些目标与 iOS 和 macOS 设备及模拟器兼容，并提供发布和调试模式

  • executorch - 主要运行时组件

  • backend_coreml - Core ML 后端

  • backend_mps - MPS 后端

  • backend_xnnpack - XNNPACK 后端

  • kernels_custom - LLM 的自定义内核

  • kernels_optimized - 优化内核

  • kernels_portable - 可移植内核（用作参考的朴素实现）

  • kernels_quantized - 量化内核

将您的二进制文件与 ExecuTorch 运行时以及导出的 ML 模型使用的任何后端或内核链接。建议将核心运行时链接到直接使用 ExecuTorch 的组件，并将内核和后端链接到主应用程序目标。

注意： 要访问日志，请链接到 ExecuTorch 运行时的 Debug 构建版本，即 executorch_debug 框架。为了获得最佳性能，始终链接到交付物的 Release 版本（那些没有 _debug 后缀的版本），这些版本已移除所有日志记录开销。

集成

Swift Package Manager

预构建的 ExecuTorch 运行时、后端和内核以 Swift PM 包的形式提供。

Xcode

在 Xcode 中，转到 File > Add Package Dependencies。将 ExecuTorch 仓库 的 URL 粘贴到搜索栏中并选择它。确保将分支名称更改为所需的 ExecuTorch 版本，格式为 “swiftpm-”，（例如 “swiftpm-0.5.0”），或格式为 “swiftpm-.<year_month_date>”（例如 “swiftpm-0.5.0-20250130”）的分支名称，用于特定日期的 nightly 构建。

然后选择哪个 ExecuTorch 框架应链接到哪个目标。

点击下面的屏幕截图，观看演示视频，了解如何添加包并在 iOS 上运行简单的 ExecuTorch 模型。

Integrating and Running ExecuTorch on Apple Platforms

CLI

将包和目标依赖项添加到 ExecuTorch 到您的包文件中，如下所示

// swift-tools-version:5.9
import PackageDescription

let package = Package(
  name: "YourPackageName",
  platforms: [
    .iOS(.v17),
    .macOS(.v10_15),
  ],
  products: [
    .library(name: "YourPackageName", targets: ["YourTargetName"]),
  ],
  dependencies: [
    // Use "swiftpm-<version>.<year_month_day>" branch name for a nightly build.
    .package(url: "https://github.com/pytorch/executorch.git", branch: "swiftpm-0.5.0")
  ],
  targets: [
    .target(
      name: "YourTargetName",
      dependencies: [
        .product(name: "executorch", package: "executorch"),
        .product(name: "backend_xnnpack", package: "executorch"),
        .product(name: "kernels_portable", package: "executorch"),
        // Add other backends and kernels as needed.
      ]),
  ]
)

然后检查一切是否正常工作

cd path/to/your/package

swift package resolve

# or just build it
swift build

本地构建

集成 ExecuTorch 运行时的另一种方法是从本地源构建必要的组件并链接到它们。这条路线更复杂，但肯定可行。

  1. 安装 Xcode 15+ 和 Command Line Tools

xcode-select --install

  1. 克隆 ExecuTorch

git clone https://github.com/pytorch/executorch.git --depth 1 --recurse-submodules --shallow-submodules && cd executorch

  1. 设置 Python 3.10+ 并激活虚拟环境

python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip

  1. 安装所需的依赖项，包括构建后端所需的依赖项，如 Core ML 或 MPS（如果您计划也构建它们）

./install_requirements.sh --pybind coreml mps xnnpack

# Optional dependencies for Core ML backend.
./backends/apple/coreml/scripts/install_requirements.sh

# And MPS backend.
./backends/apple/mps/install_requirements.sh

  1. 安装 CMake

从 CMake 网站 下载 macOS 二进制发行版，打开 .dmg 文件，将 CMake.app 移动到 /Applications 目录，然后运行以下命令安装 CMake 命令行工具

sudo /Applications/CMake.app/Contents/bin/cmake-gui --install

  1. 使用提供的脚本构建 .xcframeworks

./build/build_apple_frameworks.sh --help

例如，以下调用将为 Apple 平台构建 ExecuTorch 运行时和所有当前可用的内核和后端

./build/build_apple_frameworks.sh --coreml --mps --xnnpack --custom --optimized --portable --quantized

如果需要，在上述命令中附加 --Debug 标志以使用调试符号构建二进制文件。

构建成功完成后，可以在 cmake-out 目录中找到生成的框架。将它们复制到您的项目中并将它们链接到您的目标。

链接

ExecuTorch 在应用程序启动期间通过在静态字典中注册后端和内核（运算符）来初始化它们。如果您在运行时遇到类似“未注册内核”或“未注册后端”的错误，您可能需要显式强制加载某些组件。在您的 Xcode 构建配置中使用 -all_load 或 -force_load 链接器标志，以确保组件尽早注册。

以下是 Xcode 配置文件 (.xcconfig) 的示例

ET_PLATFORM[sdk=iphonesimulator*] = simulator
ET_PLATFORM[sdk=iphoneos*] = ios
ET_PLATFORM[sdk=macos*] = macos

OTHER_LDFLAGS = $(inherited) \
    -force_load $(BUILT_PRODUCTS_DIR)/libexecutorch-$(ET_PLATFORM)-release.a \
    -force_load $(BUILT_PRODUCTS_DIR)/libbackend_coreml-$(ET_PLATFORM)-release.a \
    -force_load $(BUILT_PRODUCTS_DIR)/libbackend_mps-$(ET_PLATFORM)-release.a \
    -force_load $(BUILT_PRODUCTS_DIR)/libbackend_xnnpack-$(ET_PLATFORM)-release.a \
    -force_load $(BUILT_PRODUCTS_DIR)/libkernels_optimized-$(ET_PLATFORM)-release.a \
    -force_load $(BUILT_PRODUCTS_DIR)/libkernels_quantized-$(ET_PLATFORM)-release.a

对于 Debug 构建配置，请在库文件名中将 release 替换为 debug。请记住，即使其他组件是为 Release 构建的，也要在 Debug 模式下链接到 ExecuTorch 运行时 (libexecutorch)，以便在需要时保留日志。

您可以在 Xcode 中将此类配置文件分配给您的目标

  1. 将 .xcconfig 文件添加到您的项目。

  2. 导航到项目的 Info 选项卡。

  3. 在 Release（或 Debug）模式的构建配置中选择配置文件。

运行时 API

查看 C++ 运行时 API 和 张量 教程，了解更多关于如何加载和运行导出的模型。建议对 macOS 或 iOS 使用 C++ API，如果需要为其他组件公开它，可以使用 Objective-C++ 和 Swift 代码进行包装。请参考 演示应用 作为此类设置的示例。

一旦链接到 executorch 运行时框架，目标现在可以导入所有 ExecuTorch 公共头文件。例如，在 Objective-C++ 中

#import <ExecuTorch/ExecuTorch.h>
#import <executorch/extension/module/module.h>
#import <executorch/extension/tensor/tensor.h>

或在 Swift 中

import ExecuTorch

注意： 导入 ExecuTorch umbrella 头文件（或 Swift 中的 ExecuTorch 模块）仅提供对日志记录 API 的访问权限。您仍然需要根据需要显式导入其他运行时头文件，例如 module.h。除了下面描述的日志记录之外，Objective-C 或 Swift 中不支持其他运行时 API。

注意： 日志在 ExecuTorch 框架的发布版本中被剥离。要保留日志记录，请在开发期间使用调试版本。

日志记录

我们为 Objective-C 和 Swift 中的日志记录提供了额外的 API，作为内部 ExecuTorch 机制的轻量级包装器。要使用它，只需在 Objective-C 中导入主框架头文件。然后使用 ExecuTorchLog 接口（或 Swift 中的 Log 类）订阅您自己的 ExecuTorchLogSink 协议（或 Swift 中的 LogSink）的实现，以监听日志事件。

#import <ExecuTorch/ExecuTorch.h>
#import <os/log.h>

@interface MyClass : NSObject<ExecuTorchLogSink>
@end

@implementation MyClass

- (instancetype)init {
  self = [super init];
  if (self) {
#if DEBUG
    [ExecuTorchLog.sharedLog addSink:self];
#endif
  }
  return self;
}

- (void)dealloc {
#if DEBUG
  [ExecuTorchLog.sharedLog removeSink:self];
#endif
}

#if DEBUG
- (void)logWithLevel:(ExecuTorchLogLevel)level
           timestamp:(NSTimeInterval)timestamp
            filename:(NSString *)filename
                line:(NSUInteger)line
             message:(NSString *)message {
  NSString *logMessage = [NSString stringWithFormat:@"%@:%lu %@", filename, (unsigned long)line, message];
  switch (level) {
    case ExecuTorchLogLevelDebug:
      os_log_with_type(OS_LOG_DEFAULT, OS_LOG_TYPE_DEBUG, "%{public}@", logMessage);
      break;
    case ExecuTorchLogLevelInfo:
      os_log_with_type(OS_LOG_DEFAULT, OS_LOG_TYPE_INFO, "%{public}@", logMessage);
      break;
    case ExecuTorchLogLevelError:
      os_log_with_type(OS_LOG_DEFAULT, OS_LOG_TYPE_ERROR, "%{public}@", logMessage);
      break;
    case ExecuTorchLogLevelFatal:
      os_log_with_type(OS_LOG_DEFAULT, OS_LOG_TYPE_FAULT, "%{public}@", logMessage);
      break;
    default:
      os_log(OS_LOG_DEFAULT, "%{public}@", logMessage);
      break;
  }
}
#endif

@end

Swift 版本

import ExecuTorch
import os.log

public class MyClass {
  public init() {
    #if DEBUG
    Log.shared.add(sink: self)
    #endif
  }
  deinit {
    #if DEBUG
    Log.shared.remove(sink: self)
    #endif
  }
}

#if DEBUG
extension MyClass: LogSink {
  public func log(level: LogLevel, timestamp: TimeInterval, filename: String, line: UInt, message: String) {
    let logMessage = "\(filename):\(line) \(message)"
    switch level {
    case .debug:
      os_log(.debug, "%{public}@", logMessage)
    case .info:
      os_log(.info, "%{public}@", logMessage)
    case .error:
      os_log(.error, "%{public}@", logMessage)
    case .fatal:
      os_log(.fault, "%{public}@", logMessage)
    default:
      os_log("%{public}@", logMessage)
    }
  }
}
#endif

注意： 在示例中，当代码不是为 Debug 模式构建时，即 DEBUG 宏未定义或等于零时，日志被有意剥离。

调试

如果您链接到 ExecuTorch 框架的 Debug 构建版本，请配置您的调试器以使用调试会话中的以下 LLDB 命令正确映射源代码

settings append target.source-map /executorch <path_to_executorch_source_code>

故障排除

执行缓慢

确保导出的模型正在使用适当的后端，例如 XNNPACK、Core ML 或 MPS。如果调用了正确的后端但性能问题仍然存在，请确认您链接到的是后端的 Release 构建版本。

为了获得最佳性能，也请在 Release 模式下链接 ExecuTorch 运行时。如果需要调试，您可以将 ExecuTorch 运行时保持在 Debug 模式，这对性能的影响很小，但可以保留日志记录和调试符号。

Swift PM

如果您遇到 Swift PM 的校验和不匹配错误，请使用 Xcode 菜单 (File > Packages > Reset Package Caches) 或以下命令清除包缓存

rm -rf <YouProjectName>.xcodeproj/project.xcworkspace/xcshareddata/swiftpm \
  ~/Library/org.swift.swiftpm \
  ~/Library/Caches/org.swift.swiftpm \
  ~/Library/Caches/com.apple.dt.Xcode \
  ~/Library/Developer/Xcode/DerivedData

注意： 确保在运行终端命令之前完全退出 Xcode，以避免与活动进程冲突。

文档

访问 PyTorch 的全面开发者文档

查看文档

教程

获取面向初学者和高级开发者的深入教程

查看教程

资源

查找开发资源并获得问题解答

查看资源

为了分析流量和优化您的体验，我们在本网站上使用 Cookie。通过点击或导航，您同意允许我们使用 Cookie。作为本网站的当前维护者，Facebook 的 Cookie 政策适用。了解更多信息，包括关于可用控件：Cookie 政策。