手机离线跑通大模型：llama.cpp Android 部署与调优指南

手机离线跑通大模型：llama.cpp Android 部署与调优指南

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp

地铁没信号、会议室断网，你照样能在手机上和大模型对话。llama.cpp 是一个 C/C++ 大模型推理引擎，把模型完整跑在本地，无需联网。本文带你走通 Android 上的三条部署路线，重点把第一次离线推理跑通，并给出调参与排错思路。

路线一览：先选路 → Termux 快速上手 → NDK 性能路线 → App 绑定 → 调优与排错。

选路：三种部署路线对比

新手建议从 Termux 路线走通全流程，之后再按性能或集成需求切换。设备要求：Android 7.0 以上、至少 4GB 内存（推荐 8GB）、2GB 以上空闲存储。

路线一：Termux 手机上直接编译

Termux 是一款免 root 的终端模拟器，装好后手机就是一个类 Linux 环境。从 F-Droid 或 Termux 官方发布页安装（Play 商店版本处于实验阶段）。

阶段 1：安装编译工具链

apt update && apt upgrade -y apt install git cmake libandroid-spawn

预期：命令无报错输出。

避坑：如果后续编译时提示缺少工具，优先确认 Termux 版本是最新的，包管理器里的 git、cmake 都来自同一个源。

阶段 2：克隆并编译 llama.cpp

git clone https://gitcode.com/GitHub_Trending/ll/llama.cpp cd llama.cpp cmake -B build cmake --build build -j4 # -j4 为并行度，内存小的手机改为 -j2

预期：build/bin/下生成llama-cli、llama-server等可执行文件。

避坑：手机编译吃内存，进程被杀说明内存不够，把并行度降到-j2并关掉后台应用。

阶段 3：下载一个 GGUF 模型

curl -L {model-url} -o ~/model.gguf # 替换为你选定的 GGUF 模型地址

预期：得到几百 MB 到几 GB 的模型文件。

提示：模型放在 Termux 主目录~/下性能最好。第一遍建议选 2GB 以下、Q4_K_M 量化的小模型（1B–4B 级别），先跑通再换大的。

阶段 4：跑通第一次离线推理

./build/bin/llama-cli -m ~/model.gguf -c 4096 -p "用一句话介绍 llama.cpp" # -m 模型文件 -c 上下文长度 -p 提示词

预期：终端逐字流式输出回答。到这里，你已经在手机上完成了完全离线的大模型推理。

注意：首次运行要把模型载入内存，速度偏慢属正常现象；老设备或内存紧张时先把-c降到 2048。

路线二：NDK 交叉编译，榨干 CPU 性能

Termux 路线省事，但 NDK 路线可以显式指定 ARM 指令集、加载更快的计算内核，是性能上限更高的选择。适合有电脑、愿意一次性配好环境的人。

阶段 1：准备 NDK 环境

安装 Android SDK 与 NDK（可在 Android Studio 的 SDK Manager 中勾选），并让ANDROID_NDK环境变量指向 NDK 根目录。

注意：Android 系统只提供有限的原生库，NDK 构建时 CMake 只能用 NDK 自带的依赖，这一点直接决定了下一步的两个 OFF 开关。

阶段 2：配置交叉编译

cmake \ -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \ -DANDROID_ABI=arm64-v8a \ -DANDROID_PLATFORM=android-28 \ -DCMAKE_C_FLAGS="-march=armv8.7a" \ -DCMAKE_CXX_FLAGS="-march=armv8.7a" \ -DGGML_OPENMP=OFF \ -DGGML_LLAMAFILE=OFF \ -B build-android

-march=armv8.7a启用最新一代 ARM 指令集；两个 OFF 分别因为 OpenMP 无法在 NDK 侧安装、llamafile 不支持 Android。

提示：即使你的手机不支持 armv8.7a 也没关系，llama.cpp 会在运行时检测 CPU 特性并自动回退到兼容内核，这套参数可以直接照用。

阶段 3：构建、安装并推送到设备

cmake --build build-android --config Release -j4 cmake --install build-android --prefix ./install --config Release adb shell "mkdir /data/local/tmp/llama.cpp" adb push ./install /data/local/tmp/llama.cpp/ adb push model.gguf /data/local/tmp/llama.cpp/

接着进入设备 shell 运行：

adb shell cd /data/local/tmp/llama.cpp LD_LIBRARY_PATH=lib ./bin/llama-cli -m model.gguf -c 4096 -p "你好"

预期：与电脑端一致的流式输出。

避坑 ⚠️：Android 不会自动查找lib目录，运行时必须显式设置LD_LIBRARY_PATH，否则报找不到动态库。

路线三：Android Studio 构建 App 绑定

想把模型能力做进自己的应用，就用官方提供的 Kotlin 绑定：把examples/llama.android/目录导入 Android Studio，执行 Gradle 同步即可构建出可运行的最小聊天前端——它能解析 GGUF 元数据、加载模型、自动完成提示词模板化，并通过 Kotlin Flow 流式收集生成 token。

这个绑定会自动检测设备硬件（Arm 最高支持 SME2、x86-64 支持 AMX）并加载匹配的内核，高端机和缺新指令集的老设备都无需手动配置。绑定源码见 examples/llama.android/。

调优：先选模型，再看上下文，最后上硬件加速

大模型推理的主要开销在矩阵乘法，手机上的瓶颈通常是内存带宽。理解这一点，调优顺序就很清楚：

1. 先选模型：4 位量化（Q4_K_M）是质量与速度的平衡点；8 位量化留给质量优先的场景；中低端机型优先换更小参数量，这比换量化档位收益大。
2. 再看上下文：-c与内存占用成正比，4096 够覆盖多数对话场景；长文档场景才需要调大，调大前确认内存余量。
3. 最后上硬件加速：NDK 路线的 armv8.7a 指令集、App 绑定路线的 SME2/AMX 自动检测，都是设备支持即生效，无需额外配置。

排错速查

收尾与延伸

到这里，你已经能选合适的路线在手机上离线运行大模型，并能按需调参、定位常见故障。可以继续深入：

• 官方 Android 部署文档：docs/android.md
• 支持模型与量化选择参考：docs/models.md
• 进阶性能方向——推测解码：docs/speculative.md
• 多模态推理：tools/mtmd/，仓库自带测试图片，例如这张登月报道扫描图：

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp