📱如何在你的 iOS 或 Android 手机上运行和部署 LLM

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

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

• 使用与 Meta 相同的技术（ExecuTorch），它支撑着 Instagram、WhatsApp 上数十亿用户

• 将 Qwen3-0.6B 本地部署到 Pixel 8 和 和 iPhone 15 Pro，上下文处理速度约为 40 tokens/s

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

• 获得隐私优先、即时响应和离线能力

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

iOS 教程Android 教程

Qwen3-4B 部署在一台 iPhone 15 Pro 上

Qwen3-0.6B 运行速度约为 40 tokens/s

🦥 训练你的模型

我们支持 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 ，用于完整微调！

从 unsloth 导入 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，它会在训练期间 模拟 Linear 层的 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 – 命令行路线，无需 Unsloth

iOS 部署

在 iOS 上运行你的模型的教程（已在 iPhone 16 Pro 上测试，但也适用于其他 iPhone）。你需要一台基于 macOS 的实体设备，并且必须能够运行 Xcode 15。

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 需要 增加内存限制能力，这需要付费开发者账户：

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. 点击模拟器上的虚拟 Home 按钮

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. 回到模拟器中的 etLLM 应用。点击它以启动。

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

1. 开始与你微调后的模型聊天吧！🎉

部署到你的实体 iPhone

初始设备设置

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

2. 解锁你的 iPhone 并点击“信任此设备”

3. 在 Xcode 中，前往 Window → Devices and Simulators

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

配置 Xcode 签名

1. 添加你的 Apple 账户：Xcode → Settings → Accounts → +

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

3. 在 TARGETS 下选择 etLLM

4. 前往 Signing & Capabilities 选项卡

5. 勾选“Automatically manage signing”

6. 从下拉菜单中选择你的 Team

将 Bundle Identifier 改为一个唯一的名称（例如 com.yourname.etLLM）。这可以解决 99% 的配置文件错误

添加所需能力

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

2. 搜索“Increased Memory Limit”并添加它

构建并运行

1. 在顶部工具栏中，从设备选择器里选中你的实体 iPhone

2. 点击运行（▶️）或按 Cmd + R

信任开发者证书

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

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

2. 切换为开启

3. 同意并接受提示

4. 重启设备，返回 Xcode 并再次点击运行

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

将模型文件传输到你的 iPhone

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

2. 在侧边栏中选择你的 iPhone

3. 点击“文件”标签

4. 展开 etLLM

5. 将你的 .pte 和 tokenizer.json 文件直接拖放到这个文件夹中

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

加载与聊天

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

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

1. 你微调后的 Qwen3 现在已经原生运行在你的 iPhone 上了！

Android 部署

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

要求

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

• Java 17（Java 21 通常是默认版本，但可能导致构建问题）

• Git

• Wget / Curl

• Android 命令行工具

• 安装指南 和设置 adb 在你的 Android 设备和电脑上

验证

检查你的 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  # 或 ~/.bashrc，取决于你的 shell

第 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（有线/无线）

如果你可以 adb 访问你的手机：

adb install -r app/build/outputs/apk/debug/app-debug.apk

选项 B：直接文件传输

如果你在远程 VM 上，或者没有数据线：

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

2. 在你的手机上下载它

3. 点击安装（如果提示，启用“允许安装未知来源应用”）。

第 8 步：传输模型文件

该应用需要 .pte 模型和 tokenizer 文件。

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

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

3. 选择模型

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

5. 进入你的 Download 文件夹。

6. 选择你的 .pte 文件。

7. 选择你的 tokenizer 文件。

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

故障排除

• 构建失败？检查 java -version。它必须是 17。

• 模型未加载？确保你已同时选择 .pte 和 分词器.

• 应用崩溃？有效的 .pte 文件必须专门为 ExecuTorch 导出（通常是用于 CPU 的 XNNPACK 后端）。

将模型传输到你的手机

目前， executorchllama 我们构建的应用只能从 Android 上一个特定目录加载模型，而该目录无法通过普通文件管理器访问。不过我们可以使用 adb 将模型文件保存到那个目录。

确保 adb 正常运行并已连接

adb devices 

1. 如果你是通过无线调试连接的，你会看到类似这样的内容：

   

   或者如果你是通过线缆连接的：

   

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

   

1. 那么你需要在手机上查看一个类似这样的弹窗（你可能需要允许它）

完成后，现在创建我们需要放置 .pte 和 tokenizer.json 文件的文件夹。

在手机路径上创建所述目录。

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

请验证目录是否已正确创建。

adb shell ls -l /data/local/tmp/llama
总计 0

将内容推送到上述目录。根据你的电脑、连接和手机情况，这可能需要几分钟甚至更久。请耐心等待。

adb push <你电脑上的path_to_tokenizer.json> /data/local/tmp/llama
adb push <你电脑上的path_to_model.pte> /data/local/tmp/llama

1. 打开 executorchllamademo 你在第 5 步安装的应用，然后点击右上角的齿轮图标打开设置。

2. 点击 Model 旁边的箭头打开选择器并选择一个模型。 如果你看到一个空白的白色对话框且没有文件名，你的 ADB 模型推送很可能失败了——请重新执行那一步。另外请注意，它一开始可能显示“未选择模型”。

3. 选择模型后，应用应显示模型文件名。

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

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

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

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

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

📱ExecuTorch 为数十亿人

ExecuTorch 为数十亿人提供端侧 ML 体验 在 Instagram、WhatsApp、Messenger 和 Facebook 上。Instagram Cutouts 使用 ExecuTorch 从照片中提取可编辑贴纸。在 Messenger 等加密应用中，ExecuTorch 支持端侧、注重隐私的语言识别和翻译。ExecuTorch 支持 Apple、Qualcomm、ARM 以及 Meta 的 Quest 3 和 Ray Bans.

其他模型支持

• 所有 Qwen 3 稠密模型（Qwen3-0.6B, Qwen3-4B, Qwen3-32B 等）

• 所有 Gemma 3 模型（Gemma3-270M, Gemma3-4B, Gemma3-27B 等）

• 所有 Llama 3 模型（Llama 3.1 8B, Llama 3.3 70B 指令版 等）

• Qwen 2.5、Phi 4 Mini 模型，以及更多！

你可以自定义 免费 Colab 笔记本 针对 Qwen3-0.6B，以便让上述任意模型都能在手机上部署！

Qwen3 0.6B 主手机部署 notebook

Google Colabcolab.research.google.com

可用于 Gemma 3

Google Colabcolab.research.google.com

可用于 Llama 3

Google Colabcolab.research.google.com

前往我们的 Unsloth 笔记本 页面查看所有其他 notebook。