# 如何在你的 iOS 或 Android 手机上运行和部署 LLM
我们很高兴展示如何训练大型语言模型（LLM），然后 **将它们部署到本地** 到 **Android 手机** 和 **iPhone**。我们与 [ExecuTorch](https://github.com/pytorch/executorch/) （来自 PyTorch 和 Meta）合作，创建了一个使用量化感知训练（[QAT](https://unsloth.ai/docs/zh/bo-ke/quantization-aware-training-qat)）的简化工作流，然后直接将其部署到边缘设备。通过 [Unsloth](https://github.com/unslothai/unsloth)、TorchAO 和 ExecuTorch，我们展示了你可以：
* 使用 Meta 在 Instagram、WhatsApp 上为数十亿用户提供服务所用的相同技术（ExecuTorch）
* 将 Qwen3-0.6B 本地部署到 **Pixel 8** 和 **iPhone 15 Pro 以约 \~40 令牌/秒 的速度运行**
* 通过 TorchAO 应用 QAT 以恢复 70% 的准确率
* 获得以隐私为先、即时响应和离线功能
* 使用我们的 [免费 Colab 笔记本](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_\(0_6B\)-Phone_Deployment.ipynb) 对 Qwen3 0.6B 进行微调并导出以便在手机上部署
iOS 教程Android 教程
{% columns %}
{% column %}
**Qwen3-4B** 部署在 iPhone 15 Pro 上
{% endcolumn %}
{% endcolumns %}
### 部署到模拟器
**不需要开发者账户。**
**准备你的模型文件**
1. 在 Xcode 中停止模拟器（按停止按钮）
2. 导航到你的 HuggingFace Hub 仓库（如果未本地保存）
3. 下载以下两个文件：
1. `qwen3_0.6B_model.pte` （你导出的模型）
2. tokenizer.json（分词器）
**在模拟器上创建共享文件夹**
1. 点击模拟器上的虚拟主屏按钮
2. 打开“文件”应用 → 浏览 → 在我的 iPhone 上
3. 点击省略号（•••）按钮并创建一个名为 `Qwen3test`
**的新文件夹**
```bash
使用终端传输文件
# 查找模拟器的隐藏文件夹
```
find \~/Library/Developer/CoreSimulator/Devices/ -type d -iname "\*Qwen3test\*"
```bash
当你看到该文件夹时运行以下命令：
cp tokenizer.json /path/to/Qwen3test/tokenizer.json
```
**cp qwen3\_0.6B\_model.pte /path/to/Qwen3test/qwen3\_model.pte**
{% columns %}
{% column %}
1. 加载并聊天
{% endcolumn %}
{% column %}
2\. 返回模拟器中的 etLLM 应用。点击以启动它。
{% endcolumn %}
{% column %}
3\. 从 Qwen3test 文件夹加载模型和分词器
{% endcolumn %}
{% endcolumns %}
### 开始与你的微调模型聊天！🎉
**部署到你的物理 iPhone**
1. 初始设备设置
2. 通过 USB 将 iPhone 连接到 Mac
3. 解锁你的 iPhone 并点击“信任此设备”
4. 在 Xcode 中，转到 Window → Devices and Simulators
**等待你的设备出现在左侧（可能会显示“Preparing”一段时间）**
{% columns %}
{% column %}
1. 配置 Xcode 签名 `+`
2. 添加你的 Apple 账户：Xcode → Settings → Accounts →
3. 在项目导航器中，点击 etLLM 项目（蓝色图标）
4. 在 TARGETS 下选择 etLLM
5. 转到 Signing & Capabilities 选项卡
6. 勾选“Automatically manage signing（自动管理签名）”
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
{% hint style="warning" %}
从下拉菜单中选择你的 Team
{% endhint %}
**将 Bundle Identifier 更改为唯一值（例如 com.yourname.etLLM）。这能解决 99% 的配置描述文件错误**
1. 添加所需功能
2. 仍在 Signing & Capabilities 中，点击 + Capability
**搜索“Increased Memory Limit”并添加它**
1. 构建并运行
2. 在顶部工具栏中，从设备选择器中选择你的物理 iPhone
**点击播放（▶️）或按 Cmd + R**
信任开发者证书
1. 你的第一次构建会失败——这是正常的！
2. 在你的 iPhone 上，进入 设置 → 隐私与安全 → 开发者模式
3. 切换为开启
4. 同意并接受提示
{% hint style="warning" %}
重启设备，返回 Xcode 并再次点击播放
{% endhint %}
**开发者模式允许 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**
{% columns %}
{% column %}
1. 请耐心！这些文件较大，可能需要几分钟
2. 在你的 iPhone 上，切换回 etLLM 应用
{% endcolumn %}
{% column %}
3\. 从应用界面加载模型和分词器
{% endcolumn %}
{% endcolumns %}
## :android: 你微调后的 Qwen3 现在已在你的 iPhone 上原生运行！
Android 部署
### 本指南介绍如何在 Android 设备上构建并安装 ExecuTorch Llama 示例应用（在 Pixel 8 上测试，也适用于其他 Android 手机上），使用 Linux/Mac 命令行环境。此方法将依赖最小化（无需 Android Studio）并将繁重的构建过程交由你的电脑处理。
要求
* 确保你的开发机器已安装以下内容：
* Java 17（Java 21 通常为默认但可能导致构建问题）
* Git
* Wget / Curl
* [Android 命令行工具](https://www.xda-developers.com/install-adb-windows-macos-linux/) 安装指南 `并在你的 Android 设备和电脑上设置` adb
#### 验证
检查你的 Java 版本是否为 17.x：
```bash
# 输出应类似于： openjdk version "17.0.x"
java -version
```
如果不匹配，请通过 Ubuntu/Debian 安装：
```bash
sudo apt install openjdk-17-jdk
```
然后将其设置为默认或导出 `JAVA_HOME`:
```bash
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
```
如果你使用的是不同的操作系统或发行版，你可能需要遵循 [本指南](https://docs.oracle.com/en/java/javase/25/install/overview-jdk-installation.html) 或直接请你喜欢的 LLM 指导你完成。
### 步骤 1：安装 Android SDK 与 NDK
在不安装完整 Android Studio 的情况下设置一个最小的 Android SDK 环境。
1\. 创建 SDK 目录：
```bash
mkdir -p ~/android-sdk/cmdline-tools
cd ~/android-sdk
```
2. 安装 Android 命令行工具
```bash
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`:
```bash
export ANDROID_HOME=$HOME/android-sdk
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$PATH
export PATH=$ANDROID_HOME/platform-tools:$PATH
```
重新加载它们：
```bash
source ~/.zshrc # 或根据你的 shell 使用 ~/.bashrc
```
### 步骤 3：安装 SDK 组件
ExecuTorch 需要特定的 NDK 版本。
```bash
# 接受许可
yes | sdkmanager --licenses
# 安装 API 34 和 NDK 25
sdkmanager "platforms;android-34" "platform-tools" "build-tools;34.0.0" "ndk;25.0.8775105"
```
设置 NDK 变量：
```bash
export ANDROID_NDK=$ANDROID_HOME/ndk/25.0.8775105
```
### 步骤 4：获取代码
我们使用 `executorch-examples` 仓库，其中包含更新的 Llama 示例。
```bash
cd ~
git clone https://github.com/meta-pytorch/executorch-examples.git
cd executorch-examples
```
### 步骤 5：修复常见编译问题
请注意当前代码没有这些问题，但我们以前遇到过，可能对你有帮助：
**修复“未找到 SDK 位置”问题：**
创建一个 `local.properties` 文件以显式告诉 Gradle SDK 在何处：
```bash
echo "sdk.dir=$HOME/android-sdk" > llm/android/LlamaDemo/local.properties
```
**修复 `cannot find symbol` 错误：**
当前代码使用了已弃用的方法 `getDetailedError()`。用以下命令修补：
```bash
sed -i 's/e.getDetailedError()/e.getMessage()/g' llm/android/LlamaDemo/app/src/main/java/com/example/executorchllamademo/MainActivity.java
```
### 步骤 6：构建 APK
此步骤将编译应用和本地库。
1. 进入 Android 项目：
```bash
cd llm/android/LlamaDemo
```
2. 使用 Gradle 构建（明确将 `JAVA_HOME` 设置为 17 以避免工具链错误）：
注意：首次运行会花费几分钟。
```bash
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 设备和电脑上设置` 访问你的手机：
```bash
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 正常运行并已连接
```shellscript
adb devices
```
{% columns %}
{% column %}
1. 如果你通过无线调试连接，你会看到类似如下内容：
{% endcolumn %}
{% endcolumns %}
完成后，是时候创建需要放置 `.pte` 和 `tokenizer.json` 文件的文件夹了。
在手机路径上创建该目录。
```shellscript
adb shell mkdir -p /data/local/tmp/llama
adb shell chmod 777 /data/local/tmp/llama
```
验证该目录是否正确创建。
```shellscript
adb shell ls -l /data/local/tmp/llama
total 0
```
将内容推送到该目录。这可能需要几分钟或更久，具体取决于你的电脑、连接和手机。请耐心等待。
```shellscript
adb push /data/local/tmp/llama
adb push /data/local/tmp/llama
```
{% columns %}
{% column %}
1. 打开你在步骤 5 中安装的 `executorchllamademo` 应用，然后点击右上角的齿轮图标以打开设置。
2. 点击 Model 旁边的箭头以打开选择器并选择一个模型。\
如果你看到一个没有文件名的空白白色对话框，则你的 ADB 模型推送可能失败——请重做该步骤。另请注意，它最初可能显示“未选择模型”。
3. 在你选择模型后，应用应显示模型文件名。
{% endcolumn %}
{% column %}
{% endcolumn %}
{% column %}
6\. 你可能需要根据上传的模型选择模型类型。这里选择的是 Qwen3。
{% endcolumn %}
{% column %}
7\. 选择好两个文件后，点击“Load Model”按钮。
{% endcolumn %}
{% endcolumns %}
{% columns %}
{% column %}
8\. 它会将你带回带有聊天窗口的原始界面，可能会显示“model loading”。根据你手机的内存和存储速度，加载可能需要几秒钟。
{% endcolumn %}
{% column %}
9\. 一旦显示“成功加载模型”，你就可以开始与模型聊天了。\
\
瞧，你现在在 Android 手机上本地运行了一个 LLM！
{% endcolumn %}
{% endcolumns %}
### :mobile\_phone:ExecuTorch 为数十亿人提供动力
ExecuTorch [为数十亿人的设备端机器学习体验提供支持](https://engineering.fb.com/2025/07/28/android/executorch-on-device-ml-meta-family-of-apps/) 在 Instagram、WhatsApp、Messenger 和 Facebook 上。Instagram Cutouts 使用 ExecuTorch 从照片中提取可编辑贴纸。在像 Messenger 这样的加密应用中，ExecuTorch 实现了设备端的隐私感知语言识别和翻译。ExecuTorch 支持跨 Apple、Qualcomm、ARM 以及多种硬件后端， [Meta 的 Quest 3 和 Ray Bans](https://ai.meta.com/blog/executorch-reality-labs-on-device-ai/).
## 其他模型支持
* 所有 Qwen 3 密集模型（[Qwen3-0.6B](https://huggingface.co/unsloth/Qwen3-0.6B), [Qwen3-4B](https://huggingface.co/unsloth/Qwen3-4B), [Qwen3-32B](https://huggingface.co/unsloth/Qwen3-32B) 等）
* 所有 Gemma 3 模型（[Gemma3-270M](https://huggingface.co/unsloth/gemma-3-270m-it), [Gemma3-4B](https://huggingface.co/unsloth/gemma-3-4b-it), [Gemma3-27B](https://huggingface.co/unsloth/gemma-3-27b-it) 等）
* 所有 Llama 3 模型（[Llama 3.1 8B](https://huggingface.co/unsloth/Llama-3.1-8B-Instruct), [Llama 3.3 70B 指令版](https://huggingface.co/unsloth/Llama-3.3-70B-Instruct) 等）
* Qwen 2.5、Phi 4 Mini 模型等更多！
你可以自定义 [**免费 Colab 笔记本**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_\(0_6B\)-Phone_Deployment.ipynb) 以便为上述任何模型允许 Qwen3-0.6B 的手机部署！
{% columns %}
{% column %}
**Qwen3 0.6B 主要手机部署笔记本**
{% embed url="" %}
{% endcolumn %}
{% column %}
兼容 Gemma 3
{% embed url="" %}
{% endcolumn %}
{% column %}
兼容 Llama 3
{% embed url="" %}
{% endcolumn %}
{% endcolumns %}
前往我们的 [unsloth-notebooks](https://unsloth.ai/docs/zh/kai-shi-shi-yong/unsloth-notebooks "mention") 页面以获取所有其他笔记本。
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://unsloth.ai/docs/zh/ji-chu/inference-and-deployment/deploy-llms-phone.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
