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

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

我们很高兴展示如何训练大型语言模型（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 开发者计划

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

1. 访问 developer.apple.com

2. 使用你的 Apple ID 登录

3. 加入 Apple 开发者计划

设置 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：直接文件传输

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

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

2. 在手机上下载它

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

步骤 8：传输模型文件

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

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

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

3. 选择模型

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

5. 导航到你的下载文件夹。

6. 选择你的 .pte 文件。

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

完成！你现在可以直接在设备上与 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
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

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

2. 点击 Model 旁边的箭头以打开选择器并选择一个模型。 如果你看到一个没有文件名的空白白色对话框，则你的 ADB 模型推送可能失败——请重做该步骤。另请注意，它最初可能显示“未选择模型”。

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

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

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

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

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

1. 一旦显示“成功加载模型”，你就可以开始与模型聊天了。 瞧，你现在在 Android 手机上本地运行了一个 LLM！

📱ExecuTorch 为数十亿人提供动力

ExecuTorch 为数十亿人的设备端机器学习体验提供支持 在 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 主要手机部署笔记本

Google Colabcolab.research.google.com

兼容 Gemma 3

Google Colabcolab.research.google.com

兼容 Llama 3

Google Colabcolab.research.google.com

前往我们的 ——并了解每个超参数如何影响模型性能。 页面以获取所有其他笔记本。