用途
本技能用于从源码构建 ExecuTorch,涵盖 Python 包、C++ 运行时、模型 runner、交叉编译以及针对不同后端的构建配置。当需要编译 ExecuTorch 中的任何组件时可使用。
主要能力
- 环境准备:检测并修复 Python 环境(优先 conda,否则使用 venv),校验 Python 与 cmake 版本。
- Python 包构建:通过
./install_executorch.sh --editable完成可编辑安装,支持--minimal最小安装与通过CMAKE_ARGS启用额外后端。 - 模型 runner 构建:使用
make <model>-<backend>构建 LLM / ASR 模型 runner,覆盖 llama、llava、whisper、parakeet、voxtral、gemma3、sortformer、silero-vad 等在 macOS / Linux 上的 CPU、CUDA、Metal 目标。 - C++ 运行时构建:支持 CMake 预设(macos / linux / windows)、LLM 工作流预设(llm-release / llm-release-metal / llm-release-cuda)以及手动 CMake 配置。
- 交叉编译:iOS/macOS frameworks(build_apple_frameworks.sh)与 Android AAR 构建(build_android_library.sh)。
- 关键构建选项:包括 EXECUTORCH_BUILD_XNNPACK、COREML、MPS、METAL、CUDA、KERNELS_OPTIMIZED、KERNELS_QUANTIZED、EXTENSION_MODULE、EXTENSION_LLM、TESTS、DEVTOOLS、OPTIMIZE_SIZE 及 CMAKE_BUILD_TYPE。
- 故障排查:覆盖 submodule 缺失、conda 权限错误、CMake 版本、PEP 668、torch 版本冲突、Python.h 缺失、运行时算子注册、Intel Mac 安装失败、XNNPACK 构建错误、重复 kernel 注册等问题。
- 构建产物说明:Python 包位置、核心运行时与 XNNPACK 后端静态库、executor_runner、模型 runner、iOS frameworks 与 Android AAR 的输出路径。
使用方式
第一步确保 Python 环境。路径 A 使用 conda(推荐):初始化 conda shell hook,检查或创建 executorch 环境(python=3.12),然后激活。路径 B 无 conda 时回退 venv:选用兼容的 Python(3.10–3.13)创建虚拟环境、激活并升级 pip。随后验证 python --version 与 cmake --version,Python 不在 3.10–3.13 则重建环境,cmake 缺失或低于 3.24 则通过 pip 安装 cmake>=3.24。并行任务数在 macOS 使用 $(sysctl -n hw.ncpu),Linux 使用 $(nproc)。
第二步构建,按用户需求路由:涉及 Android 跳转到 Android 交叉编译;涉及 iOS 或 frameworks 跳转到 iOS 交叉编译;涉及具体模型(llama、whisper 等)跳转到 LLM/ASR 模型 runner;涉及 C++ 运行时或 cmake 跳转到 C++ 运行时;否则默认构建 Python 包。Python 包执行 ./install_executorch.sh --editable,后续重建使用 pip install -e . --no-build-isolation,最小安装使用 ./install_executorch.sh --minimal,启用额外后端示例为 CMAKE_ARGS="-DEXECUTORCH_BUILD_COREML=ON -DEXECUTORCH_BUILD_MPS=ON" ./install_executorch.sh --editable,验证命令为 python -c "from executorch.exir import to_edge_transform_and_lower; print('OK')"。
模型 runner 使用 make <model>-<backend>,可通过 make help 查看完整目标列表,输出位于 cmake-out/examples/models/<model>/<runner>。
C++ 运行时推荐使用预设:macOS 执行 cmake -B cmake-out --preset macos(使用 Xcode 生成器,需 Xcode);Linux 执行 cmake -B cmake-out --preset linux -DCMAKE_BUILD_TYPE=Release;Windows 执行 cmake -B cmake-out --preset windows -T ClangCL。随后按平台执行对应 cmake --build。LLM 库可用工作流预设 cmake --workflow --preset llm-release(CPU)、llm-release-metal(macOS Metal)、llm-release-cuda(Linux/Windows CUDA)。手动 CMake 可传入自定义标志组合。cmake --list-presets 可查看全部预设。
交叉编译:iOS/macOS frameworks 使用 ./scripts/build_apple_frameworks.sh --coreml --mps --xnnpack,在 Xcode 中链接需 -all_load 链接器标志。Android 需 ANDROID_NDK 在 PATH 中,验证后设置 ANDROID_ABIS 与 BUILD_AAR_DIR,再执行 sh scripts/build_android_library.sh。
适用场景
- 需要在本地或 CI 中从源码编译 ExecuTorch Python 包。
- 需要构建并运行 LLM / ASR 模型 runner(llama、whisper、gemma3 等)。
- 需要独立构建 C++ 运行时或使用特定 CMake 预设。
- 需要为 iOS/macOS 或 Android 进行交叉编译并产出 frameworks / AAR。
- 需要针对特定后端(XNNPACK、Core ML、MPS、Metal、CUDA)启用构建选项。
限制
- 构建耗时较长,Apple Silicon 上约 10 分钟。
- macOS 预设使用 Xcode 生成器,需要安装 Xcode。
- Android 交叉编译要求 ANDROID_NDK 位于 PATH。
- 基准测试应使用 Release,Debug 会慢 5–10 倍。
- Intel Mac 缺少预构建 PyTorch wheel,需使用
--use-pt-pinned-commit --minimal。 - 文档说明 CMake 需低于 4.0,但实践中 4.0 及以上可正常工作。
- 具体收费、价格、平台支持范围等未在资料中提供。