📱如何在 iOS 或 Android 手机上运行并部署 LLM

将您自己的 LLM 微调并使用 ExecuTorch 在 Android 或 iPhone 上部署的教程。

我们很高兴展示如何训练大语言模型（LLM），然后 将它们本地部署 到 Android 手机 和 iPhone。我们与 ExecuTorch （来自 PyTorch 和 Meta）合作，创建了一个使用量化感知训练（QAT）的简化工作流，然后将其直接部署到边缘设备。 借助Unsloth、TorchAO 和 ExecuTorch，我们展示了你可以：

• 使用与 Meta 在 Instagram、WhatsApp 上为数十亿用户提供服务相同的技术（ExecuTorch）

• 在本地部署 Qwen3-0.6B 到 Pixel 8 和 iPhone 15 Pro，约 ~40 令牌/秒

• 通过 TorchAO 应用 QAT 恢复 70% 的准确度

• 获得以隐私为先、即时响应和离线功能

• 使用我们的 免费 Colab 笔记本 对 Qwen3 0.6B 进行微调并将其导出以用于手机部署

iOS 教程Android 教程

Qwen3-4B 部署在 iPhone 15 Pro 上

Qwen3-0.6B 运行约 ~40 令牌/秒

🦥 训练你的模型

我们支持 Qwen3、Gemma3、Llama3、Qwen2.5、Phi4 以及许多其他可用于手机部署的模型！按照 免费 Colab 笔记本 进行 Qwen3-0.6B 部署：

Google Colabcolab.research.google.com

首先更新 Unsloth 并安装 TorchAO 和 ExecuTorch。

pip install --upgrade unsloth unsloth_zoo
pip install torchao==0.14.0 executorch pytorch_tokenizers

然后只需使用 qat_scheme = "phone-deployment" 来表示我们希望将其部署到手机。注意我们还设置了 full_finetuning = True 用于完整微调！

from unsloth import FastLanguageModel
import torch
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/Qwen3-0.6B",
    max_seq_length = 1024,
    full_finetuning = True,
    qat_scheme = "phone-deployment", # 手机部署的标志
)

我们正在使用 qat_scheme = "phone-deployment" 实际上我们内部使用 qat_scheme = "int8-int4" 在底层启用 Unsloth/TorchAO 的 QAT，该方案 模拟 在训练期间通过假量化操作对线性层进行 INT8 动态激活量化与 INT4 权重量化，同时保持 16 位计算。训练后，模型会被转换为真实的量化版本，从而使设备上的模型更小，并且通常 比简单的 PTQ 更好地保留准确性.

按照 Colab 笔记本中描述的微调后，我们将其保存为一个 .pte 文件，通过 ExecuTorch：

# 将权重检查点 state dict 的键转换为 ExecuTorch 所期望的格式
python -m executorch.examples.models.qwen3.convert_weights "phone_model" pytorch_model_converted.bin
# 从 ExecuTorch 仓库下载模型配置
curl -L -o 0.6B_config.json https://raw.githubusercontent.com/pytorch/executorch/main/examples/models/qwen3/config/0_6b_config.json
# 导出为 ExecuTorch pte 文件
python -m executorch.examples.models.llama.export_llama \
    --model "qwen3_0_6b" \
    --checkpoint pytorch_model_converted.bin \
    --params 0.6B_config.json \
    --output_name qwen3_0.6B_model.pte \
    -kv --use_sdpa_with_kv_cache -X --xnnpack-extended-ops \
    --max_context_length 1024 --max_seq_length 128 --dtype fp32 \
    --metadata '{"get_bos_id":199999, "get_eos_ids":[200020,199999]}'

🏁 训练后部署

现在有了你的 qwen3_0.6B_model.pte 文件（大约 472MB），我们就可以部署它了！选择你的设备并直接开始：

• Run LLMs on your Phone – Xcode 路线，模拟器或真实设备

• Run LLMs on your Phone – 命令行路线，无需 Studio

iOS 部署

在 iOS 上运行模型的教程（在 iPhone 16 Pro 上测试，但也适用于其他 iPhone）。你需要一台能运行 Xcode 15 的物理 macOS 设备。

macOS 开发环境设置

安装 Xcode 与命令行工具

1. 从 Mac App Store 安装 Xcode（必须为 15 版或更高）

2. 打开终端并验证你的安装： xcode-select -p

3. 安装命令行工具并接受许可：

   1. xcode-select --install

   2. sudo xcodebuild -license accept

4. 首次启动 Xcode 并在提示时安装任何额外组件

5. 如果被要求选择平台，选择 iOS 18 并下载以便访问模拟器

重要：首次启动 Xcode 至关重要！不要跳过那些额外组件的安装！查看 此处 和 此处 以获取更多帮助。

验证一切是否正常： xcode-select -p

你应该看到打印出的路径。如果没有，请重复第 3 步。

Apple 开发者账号设置

仅适用于真实设备！

如果你只使用 iOS 模拟器，请跳过整节。只有将应用部署到真实 iPhone 才需要付费开发者账号。

创建你的 Apple ID

没有 Apple ID？ 在这里注册.

将你的账号添加到 Xcode

1. 打开 Xcode

2. 导航到 Xcode → Settings → Accounts

3. 点击 + 按钮并选择 Apple ID

4. 使用你的常规 Apple ID 登录

报名加入 Apple Developer Program

ExecuTorch 需要 increased-memory-limit 功能，这需要付费开发者账号：

1. 访问 developer.apple.com

2. 使用你的 Apple ID 登录

3. 报名加入 Apple Developer Program

设置 ExecuTorch 示例应用

获取示例代码：

# 直接下载 LLM 示例应用
curl -L https://github.com/meta-pytorch/executorch-examples/archive/main.tar.gz | \
  tar -xz --strip-components=2 executorch-examples-main/llm/apple

在 Xcode 中打开

1. 打开 apple/etLLM.xcodeproj 在 Xcode 中

2. 在顶部工具栏，选择 iPhone 16 Pro 模拟器 作为目标设备

3. 点击播放（▶️）以构建并运行

🎉 成功！应用现在应在模拟器中启动。但它尚无法工作，我们需要添加你的模型。

部署到模拟器

不需要开发者账号。

准备你的模型文件

1. 在 Xcode 中停止模拟器（按停止按钮）

2. 导航到你的 HuggingFace Hub 仓库（如果未本地保存）

3. 下载这两个文件：

   1. qwen3_0.6B_model.pte （你导出的模型）

   2. tokenizer.json（分词器）

在模拟器上创建共享文件夹

1. 点击模拟器上的虚拟主屏按钮

2. 打开文件应用 → 浏览 → 在我的 iPhone 上

3. 点击省略号（•••）按钮并创建一个名为 Qwen3test

的新文件夹

使用终端传输文件
# 找到模拟器的隐藏文件夹

find ~/Library/Developer/CoreSimulator/Devices/ -type d -iname "*Qwen3test*"

当你看到该文件夹时运行以下命令：
cp tokenizer.json /path/to/Qwen3test/tokenizer.json

cp qwen3_0.6B_model.pte /path/to/Qwen3test/qwen3_model.pte

1. 加载并聊天

1. 返回模拟器中的 etLLM 应用，点击以启动。

1. 从 Qwen3test 文件夹加载模型和分词器

开始与你的微调模型聊天！🎉

部署到你的真实 iPhone

1. 初始设备设置

2. 通过 USB 将你的 iPhone 连接到 Mac

3. 解锁 iPhone 并点击“信任此设备”

4. 在 Xcode 中，转到 Window → Devices and Simulators

等待你的设备出现在左侧（可能会显示“Preparing”一会儿）

1. 配置 Xcode 签名 +

2. 添加你的 Apple 帐户：Xcode → Settings → Accounts →

3. 在项目导航器中，点击 etLLM 项目（蓝色图标）

4. 在 TARGETS 下选择 etLLM

5. 转到 Signing & Capabilities 选项卡

6. 勾选“Automatically manage signing”

从下拉菜单中选择你的 Team

将 Bundle Identifier 更改为唯一的标识（例如：com.yourname.etLLM）。这能解决 99% 的配置文件错误

1. 添加所需的功能

2. 仍在 Signing & Capabilities 中，点击 + Capability

搜索“Increased Memory Limit”并添加它

1. 构建并运行

2. 在顶部工具栏的设备选择器中选择你的真实 iPhone

点击播放（▶️）或按 Cmd + R

信任开发者证书

1. 你的第一次构建会失败——这是正常的！

2. 在 iPhone 上，前往 设置 → 隐私与安全 → 开发者模式

3. 打开开关

4. 同意并接受提示

重启设备，返回 Xcode 并再次点击播放

开发者模式允许 Xcode 在你的 iPhone 上运行并安装应用

1. 将模型文件传输到你的 iPhone

2. 应用运行后，在 Mac 上打开 Finder

3. 在侧栏中选择你的 iPhone

4. 点击 Files 选项卡

5. 展开 etLLM

6. 将你的 .pte 和 tokenizer.json 文件直接拖放到该文件夹中

cp qwen3_0.6B_model.pte /path/to/Qwen3test/qwen3_model.pte

1. 请耐心等待！这些文件很大，可能需要几分钟

1. 在你的 iPhone 上切换回 etLLM 应用

1. 从应用界面加载模型和分词器

你微调后的 Qwen3 现在已在你的 iPhone 上本地运行！

Android 部署

本指南介绍如何在 Android 设备上构建并安装 ExecuTorch 的 Llama 示例应用（在 Pixel 8 上测试，但也适用于其他 Android 手机），使用 Linux/Mac 命令行环境。该方法将依赖最小化（无需 Android Studio）并将繁重的构建过程放到你的电脑上。

要求

• 确保你的开发机器已安装以下内容：

• Java 17（Java 21 常为默认，但可能导致构建问题）

• Git

• Wget / Curl

• Android 命令行工具 的安装指南 并在你的 android 设备和电脑上设置 adb

验证

检查你的 Java 版本是否为 17.x：

# 输出应类似于：openjdk version "17.0.x"
java -version

如果不匹配，请在 Ubuntu/Debian 上安装：

sudo apt install openjdk-17-jdk

然后将其设置为默认或导出 JAVA_HOME:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

如果你使用的是不同的操作系统或发行版，可能需要参考 本指南 或直接让你喜欢的 LLM 指导你完成。

第 1 步：安装 Android SDK 与 NDK

在不安装完整 Android Studio 的情况下设置一个最小的 Android SDK 环境。

1. 创建 SDK 目录：

mkdir -p ~/android-sdk/cmdline-tools
cd ~/android-sdk

1. 安装 Android 命令行工具

wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
unzip commandlinetools-linux-*.zip -d cmdline-tools

# 重要：重组以满足 SDK 结构要求
mv cmdline-tools/cmdline-tools cmdline-tools/latest

第 2 步：配置环境变量

将这些添加到你的 ~/.bashrc 或 ~/.zshrc:

export ANDROID_HOME=$HOME/android-sdk
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$PATH
export PATH=$ANDROID_HOME/platform-tools:$PATH

重新加载它们：

source ~/.zshrc  # 或根据你的 shell 使用 ~/.bashrc

第 3 步：安装 SDK 组件

ExecuTorch 需要特定的 NDK 版本。

# 接受许可
yes | sdkmanager --licenses

# 安装 API 34 和 NDK 25
sdkmanager "platforms;android-34" "platform-tools" "build-tools;34.0.0" "ndk;25.0.8775105"

设置 NDK 变量：

export ANDROID_NDK=$ANDROID_HOME/ndk/25.0.8775105

第 4 步：获取代码

我们使用 executorch-examples 仓库，其中包含更新的 Llama 示例。

cd ~
git clone https://github.com/meta-pytorch/executorch-examples.git
cd executorch-examples

第 5 步：修复常见的编译问题

注意当前代码没有这些问题，但我们之前遇到过，以下可能对你有帮助：

修复“找不到 SDK 位置”问题：

创建一个 local.properties 文件以显式告诉 Gradle SDK 所在位置：

echo "sdk.dir=$HOME/android-sdk" > llm/android/LlamaDemo/local.properties

修复 cannot find symbol 错误：

当前代码使用了已弃用的方法 getDetailedError()。用下面的命令修补：

sed -i 's/e.getDetailedError()/e.getMessage()/g' llm/android/LlamaDemo/app/src/main/java/com/example/executorchllamademo/MainActivity.java

第 6 步：构建 APK

此步骤会编译应用及本地库。

1. 导航到 Android 项目：

   cd llm/android/LlamaDemo

2. 使用 Gradle 构建（显式将 JAVA_HOME 设置为 17 以避免工具链错误）：

   注意：首次运行将需要几分钟时间。

   export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
   ./gradlew :app:assembleDebug

3. 生成的最终 apk 位于：

   app/build/outputs/apk/debug/app-debug.apk

第 7 步：在你的 Android 设备上安装

你有两种安装应用的选项。

选项 A：使用 ADB（有线/无线）

如果你可以访问你的手机： 并在你的 android 设备和电脑上设置 adb install -r app/build/outputs/apk/debug/app-debug.apk

选项 B：直接文件传输

如果你在远程虚拟机上或没有数据线：

将 app-debug.apk 上传到手机可下载的位置

1. 在手机上下载它

2. 点击安装（如果提示则启用“允许从未知来源安装”）。

3. 第 8 步：传输模型文件

应用需要 .pte 模型和分词器文件。

传输文件：将你的 model.pte 和 tokenizer.bin（或 tokenizer.model）移动到手机存储（例如 Downloads 文件夹）。

1. 打开 LlamaDemo 应用：在手机上启动该应用。

2. 选择模型

3. 点击设置（齿轮图标）或文件选择器。

4. 导航到你的 Downloads 文件夹。

5. 选择你的 .pte 文件。

6. 选择你的分词器文件。

7. 完成！你现在可以在设备上直接与 LLM 聊天。

故障排查

构建失败？检查 java -version。必须为 17。

• 模型无法加载？确保你同时选择了

• 和 .pte 分词器 应用崩溃？有效的.

• 文件必须针对 ExecuTorch 专门导出（通常为 CPU 的 XNNPACK 后端）。 .pte 将模型传到你的手机

目前，

executorchllama 我们构建的应用仅支持从 Android 上的一个特定目录加载模型，该目录不幸的是常规文件管理器无法访问。但我们可以使用 adb 将模型文件保存到该目录。 确保 adb 正常运行并已连接

adb devices

如果你通过无线调试连接，你会看到类似如下的输出： 

1. 或者如果通过数据线连接：

   

   如果你还没有授予电脑访问手机的权限：

   

   那么你需要检查手机上是否有弹出对话框（你可能需要允许）

   

1. 完成后，就该创建我们需要放置

tokenizer.json .pte 和 文件的文件夹了。 在手机路径上创建该目录。

adb shell mkdir -p /data/local/tmp/llama

adb shell chmod 777 /data/local/tmp/llama
验证目录是否已正确创建。

adb shell ls -l /data/local/tmp/llama

total 0
将内容推送到该目录。这可能需要几分钟或更长时间，取决于你的电脑、连接和手机。请耐心等待。

adb push <path_to_tokenizer.json on your computer> /data/local/tmp/llama

adb push <path_to_model.pte on your computer> /data/local/tmp/llama
打开你在第 5 步安装的

1. executorchllamademo 应用，然后点击右上角的齿轮图标打开设置。 点击 Model 旁的箭头以打开选择器并选择一个模型。 如果你看到一个没有文件名的空白白色对话框，说明你的 ADB 模型推送可能失败——请重做该步骤。另请注意，它最初可能显示“未选择模型”。

2. 在你选择模型后，应用应显示模型文件名。

3. 现在对分词器重复相同操作。点击 tokenizer 字段旁的箭头并选择对应文件。

1. 你可能需要根据上传的模型选择模型类型。此处选择的是 Qwen3。

1. 在你选择好两个文件后，点击“Load Model”按钮。

1. 它会带你回到带有聊天窗口的主界面，可能会显示“model loading”。根据你手机的内存和存储速度，加载可能需要几秒钟。

1. 一旦显示“successfully loaded model”，你就可以开始与模型聊天。 瞧，你现在在 Android 手机上原生运行了一个 LLM！

1. ExecuTorch 为数十亿用户提供动力

📱为数十亿人的设备端机器学习体验提供动力

ExecuTorch 在 Instagram、WhatsApp、Messenger 和 Facebook 上。Instagram Cutouts 使用 ExecuTorch 从照片中提取可编辑的贴纸。在像 Messenger 这样的加密应用中，ExecuTorch 实现了设备端的隐私感知语言识别与翻译。ExecuTorch 支持跨 Apple、Qualcomm、ARM 等十余种硬件后端，且支持 Meta 的 Quest 3 和 Ray Bans 其他模型支持.

所有 Qwen 3 密集模型（

• Qwen3-32BQwen3-0.6B, Qwen3-4B, 等） 所有 Gemma 3 模型（

• Gemma3-270MGemma3-4B, Gemma3-27B, 所有 Llama 3 模型（ 所有 Gemma 3 模型（

• Llama 3.1 8BLlama 3.3 70B Instruct, Qwen 2.5、Phi 4 Mini 模型，等等！ 所有 Gemma 3 模型（

• 你可以为 Qwen3-0.6B 自定义

以允许上述任何模型的手机部署！ 免费 Colab 笔记本 Qwen3 0.6B 主要手机部署笔记本

适用于 Gemma 3

Google Colabcolab.research.google.com

适用于 Llama 3

Google Colabcolab.research.google.com

前往我们的

Google Colabcolab.research.google.com

页面以查看所有其他笔记本！ Unsloth 笔记本 🌵 部署到适用于手机的 Cactus

Cactus

是一个针对移动设备、Mac 以及 Raspberry Pi 等 ARM 芯片的开源推理引擎。 在 INT8 下，Cactus 可运行

• LFM2-1.2B Qwen3-0.6B 和 以 60-70 toks/sec 的速度 在 iPhone 17 Pro 上， 在预算型 Pixel 6a 上为 13-18 toks/sec。

• 针对特定任务的 INT8 微调（Task-Specific INT8）对 Gemma3-270m 达到了 150 toks/sec 在 iPhone 17 Pro 上，以及 23 toks/sec 在 Raspberry Pi 上。

快速开始

1. 训练（Google Colab / GPU）

使用提供的笔记本或你自己的 Unsloth 训练脚本：

from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/gemma-3-4b-it",
    max_seq_length=2048,
    load_in_4bit=True,
)

model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
    lora_alpha=16,
    lora_dropout=0,
    use_gradient_checkpointing="unsloth",
)

# ... 使用 SFTTrainer 进行训练 ...

# 保存 adapter
model.save_pretrained("my-lora-adapter")
tokenizer.save_pretrained("my-lora-adapter")

# 推送到 Hub（可选）
model.push_to_hub("username/my-lora-adapter")

2. 设置 Cactus

git clone https://github.com/cactus-compute/cactus && cd cactus && source ./setup

3. 为 Cactus 转换

# 从本地 adapter：使用正确的基础模型！
cactus convert Qwen/Qwen3-0.6B ./my-qwen3-0.6b --lora ./my-lora-adapter 

# 从 HuggingFace Hub：使用正确的基础模型！
cactus convert Qwen/Qwen3-0.6B ./my-qwen3-0.6b  --lora username/my-lora-adapter 

4. 运行

在 Mac 上测试你的模型：

cactus run ./my-qwen3-0.6b

5. 在 iOS/macOS 应用中使用

构建本机库：

cactus build --apple

构建完成！
总用时：58 秒
静态库：
  设备：/Users/henry/Desktop/cactus/apple/libcactus-device.a
  模拟器：/Users/henry/Desktop/cactus/apple/libcactus-simulator.a
XCFrameworks：
  iOS：/Users/henry/Desktop/cactus/apple/cactus-ios.xcframework
  macOS：/Users/henry/Desktop/cactus/apple/cactus-macos.xcframework
Apple 构建完成！
(venv) henry@Henrys-MacBook-Air cactus % 

链接 cactus-ios.xcframework 到你的 Xcode 项目，然后：

import Foundation

// 从应用包加载模型
let modelPath = Bundle.main.path(forResource: "my-model", ofType: nil)!
let model = cactus_init(modelPath, 2048, nil)

// 运行补全
let messages = "[{\"role\":\"user\",\"content\":\"Hello!\"}]"
var response = [CChar](repeating: 0, count: 4096)
cactus_complete(model, messages, &response, response.count, nil, nil, nil, nil)
print(String(cString: response))

// 清理
cactus_destroy(model)

现在你可以使用以下代码构建 iOS 应用，但要在测试时查看任何设备上的性能，请将任意 iPhone 插入你的 Mac，然后运行 cactus 测试：

cactus test --<model-path-or-name> --ios 

Cactus 演示应用最终会扩展为使用你自定义的微调模型。此外， cactus run 将允许插入手机，使交互会话使用手机芯片，这样你可以在完全构建应用之前进行测试。

6. 在 Android 应用中使用

构建本机库：

cactus build --android

构建完成！
共享库位置：/Users/henry/Desktop/cactus/android/libcactus.so
静态库位置：/Users/henry/Desktop/cactus/android/libcactus.a
Android 构建完成！
(venv) henry@Henrys-MacBook-Air cactus % 

复制 libcactus.so 到 app/src/main/jniLibs/arm64-v8a/，然后：

class CactusWrapper {
    init { System.loadLibrary("cactus") }

    external fun init(modelPath: String, contextSize: Long, corpusDir: String?): Long
    external fun complete(model: Long, messagesJson: String, bufferSize: Int): String
    external fun destroy(model: Long)
}

// 用法
val cactus = CactusWrapper()
val model = cactus.init("/data/local/tmp/my-model", 2048, null)
val response = cactus.complete(model, """[{"role":"user","content":"Hello!"}]""", 4096)
cactus.destroy(model)

现在你可以使用以下代码构建 Android 应用，但要在测试时查看任何设备上的性能，请将任意 Android 手机插入你的 Mac，然后运行 cactus 测试：

cactus test --<model-path-or-name> --android 

Cactus 演示应用最终会扩展为使用你自定义的微调模型。此外， cactus run 将允许插入手机，使交互会话使用手机芯片，这样你可以在完全构建应用之前进行测试。

资源

• 支持的基础模型： Qwen3、Gemma3、LFM2、SmolLM2

• 完整 API 参考： Cactus 引擎

• 了解更多并报告错误： 是一个针对移动设备、Mac 以及 Raspberry Pi 等 ARM 芯片的开源推理引擎。