ExecuTorch 集成指南

本文档说明如何将 ExecuTorch 端侧推理框架集成到 SmartServe，并以导出 Qwen3-0.6B 模型为例，指导如何将模型导出为 .pte 格式，并在 OpenHarmony 平台上进行部署和推理。

目录

• ExecuTorch 简介
• 从源码构建 ExecuTorch
• 导出大语言模型 (LLMs)
• 导出视觉语言模型（VLMs）
• 编译部署 SmartServe
• 运行测试用例
• 常见问题
• 演示
• 性能指标
• 相关资料

---

ExecuTorch 简介

ExecuTorch 是 Meta 推出的开源端侧 AI 推理框架，旨在为资源受限的边缘设备提供高效的 PyTorch 模型运行能力。作为 PyTorch Edge 生态的重要组成，该框架已支撑 Meta 在 Quest 3、Ray-Ban 智能眼镜、Instagram、WhatsApp 等产品上的设备端 AI 能力。

核心特点：

• 端侧优先（On-device First）：ExecuTorch 针对在设备端（而非云端）运行模型进行优化，适用于手机、IoT 设备、AR/VR 头显等场景，在隐私保护、低延迟和离线可用性方面具有明显优势。

• 与 PyTorch 无缝集成：开发者可沿用熟悉的 PyTorch 工作流进行模型训练与验证，再通过 PyTorch 导出工具（如 torch.export）将模型转换为可在边缘设备上执行的格式（.pte 文件）。

• 轻量级 C++ Runtime：运行时由 C++ 实现、不依赖 Python，体积小，适合内存与算力有限的设备。

• 静态图与确定性执行：模型在导出时被编译为静态计算图，执行路径固定，避免动态控制流带来的不确定性。

• 广泛的后端支持：ExecuTorch 为多种硬件提供加速支持，常用后端包括 XNNPACK（Arm/x86 CPU）、Core ML（iOS）、Vulkan（Android GPU）、Qualcomm（Qualcomm 平台 Android 设备）等，完整列表见 Choosing a Backend。

---

从源码构建 ExecuTorch

环境要求

构建环境：本文档在 WSL2 (Windows 下的 Ubuntu 22.04) 下验证。需满足：

• conda 或其他虚拟环境管理器，推荐使用 conda
• g++ 7 或更高版本，clang++ 5 或更高版本，或任何其他兼容 C++17 的工具链。
• Python 3.10 - 3.13
• ccache (可选) — 编译器缓存工具，可加速重新编译

注意：ExecuTorch 安装路径中不得包含 .，否则可能报错。WSL2 安装见 How to install Linux on Windows with WSL。

环境设置

1. 安装 Conda，创建并激活环境。ExecuTorch 源码由 SmartServe 通过 Git Submodule 管理（版本见 README 依赖表），请先进入 SmartServe 仓库根目录并拉取子模块：

conda create -yn executorch python=3.10.0
conda activate executorch

cd ~/OpenHarmony/foundation/resourceschedule/smart_serve
./scripts/init_submodules.sh --engine executorch

如不使用脚本，也可执行：git submodule update --init --recursive third-party/executorch，并初始化图像加载依赖 git submodule update --init third-party/stb。

2. （可选）安装 ccache 以加速重复编译：

# Ubuntu/Debian
sudo apt install ccache

安装 ExecuTorch 包

在 ExecuTorch 仓库根目录执行（会安装 ExecuTorch pip 包及其依赖）：

# Install ExecuTorch pip package and its dependencies.
./install_executorch.sh

install_executorch.sh 脚本支持以下参数：

• 清理构建产物：删除旧构建与 pip 安装，详见下节「清理构建系统」。

  ./install_executorch.sh --clean
  

• 最小依赖安装：仅安装运行 ExecuTorch 所需的基础依赖，不安装示例相关依赖。

  ./install_executorch.sh --minimal
  

• 指定后端：通过 CMAKE_ARGS 启用或关闭后端，例如：

  # Enable the MPS backend
  CMAKE_ARGS="-DEXECUTORCH_BUILD_MPS=ON" ./install_executorch.sh
  
  # Disable the XNNPACK backend
  CMAKE_ARGS="-DEXECUTORCH_BUILD_XNNPACK=OFF" ./install_executorch.sh
  

• 固定 PyTorch 版本：使用 PyTorch 的特定版本提交（pinned commit）来安装 ExecuTorch，避免版本不兼容。

  ./install_executorch.sh --use-pt-pinned-commit
  

• 开发模式（可编辑安装）：

  ./install_executorch.sh --editable
  # 若依赖已安装，也可运行：
  # pip install -e . --no-build-isolation
  

清理构建系统

从上游执行 git pull 或 git fetch 更新 SmartServe 后，建议同步子模块并清理 ExecuTorch 旧构建：

cd ~/OpenHarmony/foundation/resourceschedule/smart_serve
git submodule sync
./scripts/init_submodules.sh --engine executorch

cd third-party/executorch
./install_executorch.sh --clean

--clean 会删除旧构建产物和 pip 安装，若已安装 ccache 也会清空其缓存。

OpenHarmony 交叉编译

OpenHarmony NDK 的获取与解压步骤请参阅 OpenHarmony 平台构建指南 中的「编译依赖」一节。交叉编译前需先处理工具链与 ExecuTorch 的兼容问题，具体解决方法见 常见编译问题和解决方法。

交叉编译前的重要提示

在开始应用补丁和执行 CMake 配置之前，建议先阅读 常见编译问题和解决方法——问题 4，确认当前 OpenHarmony NDK 工具链是否已经处理系统侧与应用侧 C++ 标准库 ABI 不兼容问题。

如果仍在使用 OpenHarmony SDK 原始 ohos.toolchain.cmake，很可能会在 SmartServe 链接 NDK 交叉编译的 ExecuTorch 时遇到 std::__h / std::__n1 混用导致的 undefined symbol。本仓库在 toolchains/ohos 目录下提供了一个已做兼容性修改的 ohos.toolchain.custom.cmake，使用方式见 toolchains/ohos/README.md。

建议流程如下：

1. 先按 toolchains/ohos/README.md 的说明，将 ohos.toolchain.custom.cmake 放入 OpenHarmony SDK 的 build/cmake/ 目录
2. 再应用 patches/patches-for-executorch/ 下的 OpenHarmony 适配补丁
3. 最后执行下文的 CMake 配置与交叉编译

应用 OpenHarmony 适配补丁

SmartServe 在 patches/patches-for-executorch/ 下提供面向 OpenHarmony aarch64（arm64-v8a） 交叉编译的 ExecuTorch 适配补丁。请先确保 third-party/executorch 的版本与项目主文档 README 中列出的依赖版本（release/1.1 对应提交）一致，然后再按顺序应用补丁并开始交叉编译。

1）ExecuTorch 主仓库补丁（0001–0005）

在 ExecuTorch 仓库根目录（third-party/executorch）执行（只应用 0001–0005，避免把 XNNPACK 子模块补丁混进 git am）：

cd ~/OpenHarmony/foundation/resourceschedule/smart_serve/third-party/executorch

git am ../../patches/patches-for-executorch/000[1-5]-*.patch

说明：

• git am 会按补丁中的作者、说明等信息依次生成提交；若某一步失败，可用 git am --abort 放弃本次应用，解决冲突后对该补丁单独执行 git am <文件路径>，或对已部分成功的系列使用 git am --continue。
• 若仅需打补丁而不保留提交记录，可改用 git apply -p1 <patch>（需对每个 .patch 依次执行），但维护上更推荐与上游区分清晰的 git am 提交历史。
• 补丁与上游版本强相关：升级 ExecuTorch 版本后需重新核对补丁是否仍适用。

补丁说明：

序号	Patch 文件	作用说明
1	0001-ohos-aarch64-cmake-minimum-3.28.patch	将 cmake_minimum_required 从 3.29 降为 3.28，与 OpenHarmony NDK 自带的 CMake 版本对齐，避免配置阶段失败
2	0002-ohos-aarch64-c10-macros-h-assert-fail-non-glibc.patch	在非 glibc 环境（如 OHOS / musl）下使 __assert_fail 的前向声明与系统 assert.h 一致，避免声明不匹配导致编译错误
3	0003-ohos-aarch64-cmake-torch-headeronly-overlay.patch	在包含链中优先使用 ExecuTorch 自带的 torch/headeronly（依赖补丁 0005），避免与 PyTorch 安装目录中的 c10 混用导致宏不一致
4	0004-ohos-aarch64-optimized-kernels-aten-vec-compat.patch	为 optimized kernels 引入 ATen vec 兼容头并前置包含，修复非 glibc 工具链下的编译兼容问题
5	0005-ohos-aarch64-add-cmake-helper-for-torch-headeronly.patch	定义 executorch_torch_headeronly_overlay_include_dir，为补丁 0003 提供 CMake 辅助函数（否则会出现 Unknown CMake command）

XNNPACK 子模块补丁

backends/xnnpack/third-party/XNNPACK 会在编译时触发 clock_gettime / CLOCK_MONOTONIC 未声明的问题（与 OHOS / 非 glibc 头文件行为有关），见 常见编译问题和解决方法——问题 3。该问题发生在 XNNPACK 子模块内部，因此需要在子模块目录上应用补丁（不要用 ExecuTorch 根目录的 git am）。

在 third-party/executorch 根目录执行：

cd ~/OpenHarmony/foundation/resourceschedule/smart_serve/third-party/executorch

git -C backends/xnnpack/third-party/XNNPACK apply \
  ../../../../../../patches/patches-for-executorch/0006-ohos-aarch64-xnnpack-runtime-clock-gettime-posix.patch

如果重复执行导致 patch 无法再次应用（提示已应用/冲突），先回滚再重放即可：

git -C backends/xnnpack/third-party/XNNPACK apply -R \
  ../../../../../../patches/patches-for-executorch/0006-ohos-aarch64-xnnpack-runtime-clock-gettime-posix.patch

git -C backends/xnnpack/third-party/XNNPACK apply \
  ../../../../../../patches/patches-for-executorch/0006-ohos-aarch64-xnnpack-runtime-clock-gettime-posix.patch

交叉编译

1. 配置环境变量

   以下路径请按实际 OpenHarmony SDK 存放位置修改：

   export PATH=~/OpenHarmony/sdk/ohos-sdk/linux/native/build-tools/cmake/bin:$PATH
   

2. 配置并编译

   在 SmartServe 仓库内的 ExecuTorch 子目录中创建构建目录并执行构建配置与编译。这里的 CMAKE_TOOLCHAIN_FILE 应显式指向 OpenHarmony SDK 目录下的 ohos.toolchain.custom.cmake。

   cd ~/OpenHarmony/foundation/resourceschedule/smart_serve/third-party/executorch
   
   mkdir -p cmake-out && cd cmake-out
   
   # 可选：使用 -DCMAKE_C(XX)_FLAGS=-Wno-unused-command-line-argument 完全禁用警告
   cmake .. \
     -DCMAKE_TOOLCHAIN_FILE=~/OpenHarmony/sdk/ohos-sdk/linux/native/build/cmake/ohos.toolchain.custom.cmake \
     -DOHOS_PLATFORM=OHOS \
     -DOHOS_ARCH=arm64-v8a \
     -DOHOS_STL=c++_system \
     -DOHOS_USE_LINUX_SYSTEM_NAME=ON \
     -DCMAKE_BUILD_TYPE=Debug \
     -DEXECUTORCH_OPTIMIZE_SIZE=OFF \
     -DCMAKE_C_FLAGS="-Wno-error=unused-command-line-argument -fexceptions" \
     -DCMAKE_CXX_FLAGS="-Wno-error=unused-command-line-argument -fexceptions -frtti" \
     -DBUILD_TESTING=OFF \
     -DEXECUTORCH_BUILD_TESTS=OFF \
     -DEXECUTORCH_ENABLE_LOGGING=ON \
     -DEXECUTORCH_BUILD_EXTENSION_MODULE=ON \
     -DEXECUTORCH_BUILD_EXTENSION_DATA_LOADER=ON \
     -DEXECUTORCH_BUILD_EXTENSION_FLAT_TENSOR=ON \
     -DEXECUTORCH_BUILD_EXTENSION_NAMED_DATA_MAP=ON \
     -DEXECUTORCH_BUILD_EXTENSION_LLM=ON \
     -DEXECUTORCH_BUILD_EXTENSION_LLM_RUNNER=ON \
     -DEXECUTORCH_BUILD_EXTENSION_TENSOR=ON \
     -DEXECUTORCH_BUILD_KERNELS_LLM=ON \
     -DEXECUTORCH_BUILD_KERNELS_OPTIMIZED=ON \
     -DEXECUTORCH_BUILD_KERNELS_QUANTIZED=ON \
     -DEXECUTORCH_BUILD_XNNPACK=ON \
     -DEXECUTORCH_XNNPACK_SHARED_WORKSPACE=ON \
     -DEXECUTORCH_BUILD_EXECUTOR_RUNNER=OFF
   
   cmake --build . --config Release -j$(nproc)
   

   主要参数说明：

   参数	说明
   CMAKE_TOOLCHAIN_FILE	OpenHarmony NDK 工具链配置文件路径
   OHOS_PLATFORM=OHOS	指定目标平台为 OHOS
   OHOS_ARCH=arm64-v8a	目标 CPU 架构（ARM64 / AArch64）
   OHOS_STL=c++_system	C++ 标准库类型
   CMAKE_BUILD_TYPE=Release	构建类型
   EXECUTORCH_OPTIMIZE_SIZE=ON	开启编译体积优化，减小二进制体积
   CMAKE_C_FLAGS / CMAKE_CXX_FLAGS	建议加上 -Wno-error=unused-command-line-argument，否则在当前 OHOS 工具链下可能报错
   EXECUTORCH_ENABLE_LOGGING=ON	开启 ExecuTorch 日志
   EXECUTORCH_BUILD_EXTENSION_LLM_RUNNER=ON	构建 LLM Runner 扩展，用于 LLM 推理
   EXECUTORCH_BUILD_XNNPACK=ON	启用 XNNPACK 后端

链接编译产物

如何将上述交叉编译得到的 ExecuTorch 库与头文件接入 SmartServe 的构建，见仓库中的 plugin/BUILD.gn 配置。

---

导出大语言模型 (LLMs)

在 SmartServe 中使用 ExecuTorch 进行推理前，需先将模型导出为 .pte（PyTorch ExecuTorch）格式并部署到设备。模型优化主要依赖后端委派与量化，后文将分别说明。

ExecuTorch 原生支持的 LLM 包括：

• Llama 2/3/3.1/3.2
• Qwen 2.5/3
• Phi 3.5/4-mini
• SmolLM2
• 其他支持的 LLM 见 ModelType

LLM 导出依赖 pytorch_tokenizers。若出现 ModuleNotFoundError: No module named 'pytorch_tokenizers'错误，请先安装：

pip install pytorch-tokenizers

# 或从源码安装
pip install -e ./extension/llm/tokenizers/

注意：若需导出上述列表之外的模型（如 Gemma、Mistral、BERT、T5、Whisper 等），请参考 Exporting LLMs with HuggingFace's Optimum ExecuTorch，通过 Optimum ExecuTorch 支持更多模型类型。

后端委托 (Backend Delegation)

后端概述

ExecuTorch 的后端为特定硬件提供加速能力，使模型能在各类设备（如 Android、iOS、嵌入式平台）上高效运行。导出时，ExecuTorch 会按所选后端对模型做优化，并生成针对该硬件的 .pte 文件。不同后端在硬件要求、支持的算子与模型范围上各不相同，因此通常需要为每个目标后端分别生成对应的 .pte 文件。

生成 .pte 时，ExecuTorch 会识别可由该后端执行的模型分区。不支持的算子会通过降级（例如回退到 XNNPACK）执行，从而在兼容性前提下实现部分加速。后端本质上是导出模型与运行硬件之间的桥梁，选择合适的后端有助于充分利用设备能力，在性能、兼容性和资源占用之间取得平衡。详见 Backend Overview。

ExecuTorch Delegate

Backend Delegation（后端委托） 是 ExecuTorch 提供的一种机制：硬件厂商或编译器开发者可将自有的加速器或优化编译器接入 ExecuTorch 的推理流程。其目的在于：一方面利用专用硬件（NPU/CPU/GPU/DSP）或优化库（如 XNNPACK）提升性能与能效，另一方面对上层保持透明、统一的编程接口。详见 Understanding Backends and Delegates。

量化

量化通过降低模型中权重的数值精度（常见做法是从 32 位浮点降至 8 位整数）来减小显存/内存占用、加快推理并降低功耗，多数情况下对精度的影响可以接受。在边缘设备上部署时，算力、内存等资源往往受限，量化能显著提升模型在资源受限环境下的可部署性。

ExecuTorch 以 PyTorch 生态的 TorchAO 作为量化实现，且量化与后端绑定：各后端按自身硬件能力定义量化方式（如 XNNPACKQuantizer、CoreMLQuantizer）。更完整的说明见 Quantization in ExecuTorch。

两种量化入口：

1. TorchAO quantize API： 直接修改模型的 nn.Module 结构，支持动态量化（如 8da4w）。常见用法包括：

   • Weight-only：仅量化权重（int8/int4），激活保持 FP16/FP32；
   • 动态激活量化：权重与激活动态量化为 int8；
   • 超低位量化：float8、uint1~uint7 等实验性格式。

2. PT2E quantization ： 基于 PyTorch 2 Export，将量化作为图变换（graph pass）插入量化/反量化节点，不改动原始模型代码。

export_llm API

export_llm 是 ExecuTorch 为 LLM 提供的高级导出 API，参数可通过 CLI args（命令行）或 YAML 配置文件指定，配置字段的定义见 LlmConfig。本节以导出 Qwen3-0.6B 为例说明用法。

1. 编写配置文件

   在 config.yaml 中指定模型类、量化与后端等，例如：

   base:
     model_class: qwen3_0_6b
     params: /path/to/executorch/examples/models/qwen3/config/0_6b_config.json
     metadata: '{"get_bos_id": 151644, "get_eos_ids":[151645]}'
   
   model:
     use_kv_cache: True
     use_sdpa_with_kv_cache: True
     dtype_override: fp32
   
   quantization:
     qmode: 8da4w
   
   backend:
     xnnpack:
       enabled: True
       extended_ops: True  # Expand the selection of ops delegated to XNNPACK.
   
   debug:
     verbose: True
   

   上述示例启用了 8da4w 量化、XNNPACK 后端与 KV Cache，params 路径请按实际存放目录修改。

2. 执行导出

   在 executorch 仓库根目录下执行（/path/to/config.yaml 替换为实际文件路径）：

   python -m extension.llm.export.export_llm --config /path/to/config.yaml
   

   生成的 .pte 文件会落在当前工作目录（executorch 根目录）下。

使用 ExecuTorch pybindings 测试模型

ExecuTorch pybindings 是 ExecuTorch 运行时的 Python 绑定，用于在 Python 中加载并执行 .pte 文件，便于在宿主机上做模型验证、调试与性能测试。下面以上一步导出的 Qwen3-0.6B 为例说明使用步骤。

1. 准备 tokenizer

   从 Qwen3-0.6B 的 Hugging Face 仓库 下载 tokenizer.json 与 tokenizer_config.json。

2. 运行 Runner

   在 executorch 仓库根目录下执行（将 /path/to/ 替换为 tokenizer 与配置的实际路径）：

   cd executorch
   
   python -m examples.models.llama.runner.native \
   --model qwen3_0_6b \
   --pte qwen3_0_6b.pte \
   --tokenizer /path/to/tokenizer.json \
   --tokenizer_config /path/to/tokenizer_config.json \
   --prompt "<|im_start|>user\nWhere is the capital of China?<|im_end|>\n<|im_start|>assistant\n" \
   --params examples/models/qwen3/config/0_6b_config.json \
   --max_len 128 \
   -kv \
   --temperature 0.6
   

运行结果示例如下：

---

导出视觉语言模型（VLMs）

除文本生成模型外，ExecuTorch 还支持多种视觉语言模型（Vision-Language Model, VLM）的导出与部署。支持的模型列表位于 executorch/examples/models 目录，当前已支持的 VLM 模型包括：

• Gemma3-4B
• LLaVA1.5-7B
• Llama3.2-vision
• SmolVLM

各模型的详细导出步骤、配置参数和运行方法请在 ExecuTorch 上游仓库中查阅 examples/models/ 下每个模型各自子目录里的 README.md（如 executorch/examples/models/llava/README.md）。导出前请以对应模型子目录下的 README 为准。

---

编译部署 SmartServe

完成模型导出后，需要将 SmartServe 编译并部署到目标设备。完整的构建步骤、依赖配置和部署流程请参考 OpenHarmony 平台构建指南。

编译注意事项：

• 编译 SmartServe 时，需要确保构建 test_executorch 测试用例，用于验证 ExecuTorch 插件的功能。

• 在运行 Qwen3 模型前，需将以下文件部署至开发板的 /data/local/tmp/executorch/qwen3 目录：

  • 导出的 .pte 模型文件
  • 模型对应的 tokenizer.json 文件

• 对于 LLaVA 模型，文件应部署至 /data/local/tmp/executorch/llava 目录，包括：

  • .pte 模型文件
  • tokenizer.bin tokenizer 文件
  • 图片

详细的模型推送步骤请参考 OpenHarmony 平台构建指南 中的「部署模型文件」一节。

---

运行测试用例

连接设备

在 Windows 终端通过 hdc shell 命令连接开发板：

hdc shell

执行测试用例

进入目录并运行测试程序：

cd /data/smart_serve/

# 运行 ExecuTorch 测试用例
./test_executorch

测试程序将依次执行 TestLLMRunnerFunctionTest 和 TestLLaVARunnerFunctionTest 两个测试用例，验证文本生成和视觉语言模型的功能。

test_executorch 运行输出示例：

---

常见问题

构建和部署过程中可能遇到的问题及解决方案，请参阅：常见编译问题和解决方法

---

演示

Qwen3-0.6B 运行演示

以下展示了 Qwen3-0.6B 模型在 OpenHarmony 平台上的实际运行效果：

---

性能指标

测试环境说明：

• 硬件平台：Orange Pi 5 Plus（RK3588，16GB RAM）
• 操作系统：OpenHarmony v6.0 Release
• 测试模型：Qwen3-0.6B 使用上述导出配置；LLaVA1.5-7B 导出方式与 官方教程 一致
• 所有性能指标均为三次独立实验的平均值

	Qwen3	LLaVA1.5
模型参数	0.6B	7B
优化方式	XNNPACK 后端、8da4w 量化	XNNPACK 后端、8da4w 量化等
首 Token 延迟	0.17 s	30.34 s
Prefill	82.81 Tokens/sec	20.30 Tokens/sec
Decode	34.76 Tokens/sec	1.40 Tokens/sec

---

相关资料

• ExecuTorch 1.1 - Quick Start
• ExecuTorch 1.1 - Building from Source
• ExecuTorch 1.1 - Exporting LLMs