> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/inference-and-deployment/deploy-llms-phone.md).
# 如何在你的 iOS 或 Android 手机上运行和部署 LLM
使用 ExecuTorch 微调你自己的 LLM，并将其部署到你的 Android 手机或 iPhone 上的教程。
我们很高兴展示你如何训练 LLM，然后 **将它们本地部署** 改为 **Android 手机** 和 **iPhone**。我们与 [ExecuTorch](https://github.com/pytorch/executorch/) 来自 PyTorch 和 Meta，共同打造了一个简化的工作流程，使用量化感知训练（[QAT](/docs/zh/bo-ke/quantization-aware-training-qat.md)），然后将它们直接部署到边缘设备上。借助 [Unsloth](https://github.com/unslothai/unsloth)、TorchAO 和 ExecuTorch，我们展示你可以：
* 使用 Meta 为 Instagram、WhatsApp 上数十亿用户提供支持的同样技术（ExecuTorch）
* 将 Qwen3-0.6B 本地部署到 **Pixel 8** 和 **iPhone 15 Pro 上，速度约 40 tokens/s**
* 通过 TorchAO 应用 QAT，恢复 70% 的准确率
* 获得隐私优先、即时响应和离线能力
* 使用我们的 [免费 Colab Notebook](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 上
" %}
先更新 Unsloth 并安装 TorchAO 和 Executorch。
```bash
pip install --upgrade unsloth unsloth_zoo
pip install torchao==0.14.0 executorch pytorch_tokenizers
```
然后只需使用 `qat_scheme = "phone-deployment"` 来表示我们希望将它部署到手机上。注意我们也设置了 `full_finetuning = True` 用于完整微调！
```python
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，它会 *模拟* 训练过程中对 Linear 层进行 INT8 动态激活量化和 INT4 权重量化（通过伪量化操作），同时保持 16 位计算。训练结束后，模型会被转换为真正的量化版本，因此设备端模型更小，并且通常 **比朴素的 PTQ 保留更好的准确率**.
按照 [Colab 笔记本](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_\(0_6B\)-Phone_Deployment.ipynb)中的说明完成微调后，我们接着将其保存为一个 `.pte` 文件，使用 Executorch：
{% code expandable="true" %}
```bash
# 将权重检查点 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]}'
```
{% endcode %}
### 🏁 训练后部署
现在有了你的 `qwen3_0.6B_model.pte` 文件，大小约 472MB，我们就可以部署它了！选择你的设备，直接开始：
* [#ios-deployment](#ios-deployment "mention") – Xcode 路线，模拟器或真机
* [#android-deployment](#android-deployment "mention") – 命令行路线，无需 Unsloth
## :apple: 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 并下载以便访问模拟器
{% hint style="warning" %}
重要：第一次启动 Xcode 很关键！不要跳过那些额外的组件安装！查看 [这里](https://developer.apple.com/documentation/xcode/downloading-and-installing-additional-xcode-components) 和 [这里](https://developer.apple.com/documentation/safari-developer-tools/adding-additional-simulators) 获取更多帮助。
{% endhint %}
**验证一切是否正常：** `xcode-select -p`
你应该会看到打印出的路径。如果没有，请重复第 3 步。
### Apple Developer 账户设置
**仅适用于实体设备！**
{% hint style="info" %}
如果你只使用 iOS 模拟器，可以跳过这一整部分。只有部署到实体 iPhone 时才需要付费开发者账户。
{% endhint %}
{% columns %}
{% column %}
**创建你的 Apple ID**
还没有 Apple ID？[ 在这里注册](https://support.apple.com/en-us/108647?device-type=iphone).
#### **将你的账户添加到 Xcode**
1. 打开 Xcode
2. 导航到 Xcode → Settings → Accounts
3. 点击 + 按钮并选择 Apple ID
4. 使用你常用的 Apple ID 登录
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
#### **加入 Apple Developer Program**
ExecuTorch 需要 `增加内存限制能力`，这需要付费开发者账户：
1. 访问[ developer.apple.com](https://developer.apple.com)
2. 使用你的 Apple ID 登录
3. 加入 Apple Developer Program
### 设置 ExecuTorch 演示应用
**获取示例代码：**
```bash
# 直接下载 LLM 示例应用
curl -L https://github.com/meta-pytorch/executorch-examples/archive/main.tar.gz | \
tar -xz --strip-components=2 executorch-examples-main/llm/apple
```
{% columns %}
{% column %}
**在 Xcode 中打开**
1. 打开 `apple/etLLM.xcodeproj` 在 Xcode 中
2. 在顶部工具栏中，选择 `iPhone 16 Pro` 模拟器作为你的目标设备
3. 点击播放（▶️）进行构建并运行
🎉 成功！应用现在应该会在模拟器中启动。它还不能正常工作，我们需要添加你的模型。
{% endcolumn %}
{% column %}
:android: Android 部署
本指南介绍如何使用 Linux/Mac 命令行环境，在 Android 设备上构建并安装 ExecuTorch Llama 演示应用（已在 Pixel 8 上测试，也可用于其他 Android 手机）。这种方式将依赖降到最低（无需 Android Studio），并把繁重的构建过程卸载到你的电脑上。
### 要求
确保你的开发机器已安装以下内容：
* Java 17（Java 21 通常是默认值，但可能导致构建问题）
* Git
* Wget / Curl
* Android 命令行工具
* [安装指南](https://www.xda-developers.com/install-adb-windows-macos-linux/) 和设置 `adb` 在你的 Android 设备和电脑上
#### 验证
检查你的 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 # 或 ~/.bashrc，取决于你的 shell
```
### 第 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
```
**修复 `找不到符号` 错误：**
当前代码使用了一个已弃用的方法 `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（有线/无线）
如果你可以 `adb` 访问你的手机：
```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. 进入你的 Download 文件夹。
6. 选择你的 .pte 文件。
7. 选择你的 tokenizer 文件。
完成！你现在可以直接在设备上与 LLM 聊天了。
### 故障排除
* 构建失败？检查 java -version。它必须是 17。
* 模型未加载？确保你同时选择了 `.pte` 以及 `分词器`.
* 应用崩溃？有效的 `.pte` 文件必须专门为 ExecuTorch 导出（CPU 通常使用 XNNPACK 后端）。
### 将模型传输到你的手机
目前， `executorchllama` 我们构建的应用只支持从 Android 上的特定目录加载模型，而该目录无法通过常规文件管理器访问。不过，我们可以使用 adb 将模型文件保存到上述目录。
#### 确保 adb 正常运行并已连接
```shellscript
adb devices
```
{% columns %}
{% column %}
1. 如果你通过无线调试连接，你会看到类似这样的内容：
" %}
{% endcolumn %}
{% column %}
适用于 Gemma 3
{% embed url="" %}
{% endcolumn %}
{% column %}
适用于 Llama 3
{% embed url="" %}
{% endcolumn %}
{% endcolumns %}
前往我们的 [Unsloth 笔记本](/docs/zh/kuai-su-kai-shi/unsloth-notebooks.md) 页面查看所有其他笔记本。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://unsloth.ai/docs/zh/ji-chu-zhi-shi/inference-and-deployment/deploy-llms-phone.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
