PowerInfer 在 Android 上的构建与本地部署指南：Termux 设备端编译与 NDK 交叉编译全流程

• 人工智能
• 大模型
• 推理引擎
• 本地部署

本文以 smallthinker/docs/android.md 为骨架，结合仓库内的 README、构建文档与源码实现，系统讲解在 Android 平台上编译并运行 PowerInfer（llama.cpp 生态的本地大模型推理引擎）的两种主流路径：无需 root 的 Termux 设备端构建，以及宿主机上基于 Android NDK 的交叉编译。读完本文，你将掌握在手机/平板上直接构建、用 adb 推送部署、配置推理上下文参数，并理解 PowerInfer 针对 Android 平台（如骁龙 8 Elite）的稀疏模型专属编译与运行要点。

两条路径概览：在 Android 上运行 PowerInfer 的两种方式

Android 并非桌面 Linux，但其内核与 Linux 同源，这为在移动设备上运行完整的本地大模型推理引擎提供了两条成熟路径：

1. 设备端构建（Termux）：在手机上安装 Termux 终端模拟器（无需 root），将其当作一个小型 Linux 环境，直接通过apt安装编译工具链，在设备本机上完成从源码到可执行文件的构建，适合快速体验与调试。
2. 宿主机交叉编译（Android NDK）：在 PC 上使用 Android NDK 提供的 CMake 工具链文件，为指定 ABI（如arm64-v8a）交叉编译出二进制，再通过adb push部署到设备，适合面向多设备分发、集成进 Android 应用，以及追求更严格编译控制的场景。

无论选择哪条路径，产物都是同一套基于 llama 库 的可执行程序。仓库中该分支的工程根目录为 smallthinker，下文涉及源码路径均以此为准。

路径一：在 Termux 中直接构建 PowerInfer

安装 Termux 与基础工具链

Termux 是一款 Android 终端模拟器与 Linux 环境应用，无需 root 权限。截至文档撰写时，Termux 在 Google Play Store 中处于实验性发布状态，也可以从其项目仓库或 F-Droid 获取安装包。

安装并进入 Termux shell 后，先完成系统包更新，再安装git与cmake：

$ apt update && apt upgrade -y $ apt install git cmake

git用于拉取源码，cmake则是本仓库默认的构建系统生成器（关于 CMake 构建的完整说明可参考仓库内的 构建指南）。

克隆源码并执行 CMake 构建

Termux 环境与 Linux 高度相似，因此可以直接复用常规的 CMake 构建流程。在 Termux 的 home 目录下克隆本仓库，随后执行标准的两步构建：

$ cmake -B build -DCMAKE_BUILD_TYPE=Release $ cmake --build build --config Release -j4

提示：-j4指定并行编译任务数，可按设备 CPU 核数调整以加快编译速度；Termux 环境下通常不涉及 GPU 后端，保持纯 CPU 构建即可。

下载模型并放置到 home 目录

构建完成后，下载你选定的模型文件（例如 GGUF 格式的量化模型）。建议将模型放置在~/（home）目录下以获得最佳性能——这是因为 home 目录通常位于设备内部存储，读写性能优于通过 FUSE 挂载的共享存储分区。

$ curl -L {model-url} -o ~/{model}.gguf

运行推理

进入仓库目录后，即可调用编译产物运行模型：

$ ./build/bin/llama-cli -m ~/{model}.gguf -c {context-size} -p "{your-prompt}"

• -m：指定 GGUF 模型文件路径；
• -c：上下文大小（context-size）；
• -p：初始提示词。

文档特别强调：务必先将context-size设置为一个合理的数值（例如 4096）再开始运行。上下文越大，KV 缓存占用的内存越多；若一次性设置过大，内存可能瞬间飙升并把你的终端进程杀死。

这里以llama-cli为例，但理论上 examples 目录下的任一可执行程序（如llama-server、llama-simple）都可以用同样的方式运行。

路径二：使用 Android NDK 交叉编译

设备端构建适合快速验证，但如果你希望为特定设备定制最优化指令集、或将 PowerInfer 集成到自己的 Android App 中，则应在宿主机上通过 CMake + Android NDK 进行交叉编译。

前置条件

• 已准备好面向 Android 的交叉编译环境，即安装了 Android SDK 与 NDK。
• 理解 Android 平台的库约束：与桌面环境不同，Android 只内置了有限的系统原生库，因此使用 NDK 构建时，CMake 仅能链接到这些可用的库（可参考 Android NDK 稳定 API 文档）。

配置 CMake 工程

在项目目录下执行如下 CMake 配置命令：

$ 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

关键参数含义：

Notes（原文档强调的两个已知限制）：

• 较新版本的 Android NDK 虽然自带 OpenMP 运行时，但 CMake 仍需要将 OpenMP 作为依赖单独安装，而这一点目前并不被支持，因此这里显式关闭GGML_OPENMP。
• llamafile目前不支持 Android 设备，故需关闭GGML_LLAMAFILE。这也与仓库中 Android 示例工程 的 CMake 参数保持一致（该工程同样传入了-DGGML_LLAMAFILE=OFF）。

关于指令集与运行时特性检测

上述命令以-march=armv8.7a为现代设备配置了最具性能的编译选项。即使你的设备并非 ARMv8.7a，也无需担心：PowerInfer 的底层计算内核（ggml）在运行时会对可用 CPU 特性进行检测，自动选择合适的内核。

从源码看，这一机制体现在 ggml-cpu.c 中：初始化时会读取AT_HWCAP辅助向量解析 ARM 特性标志（如HWCAP_ASIMDDP对应 dotprod 支持），并通过ggml_cpu_has_neon()、ggml_cpu_has_dotprod()等接口暴露；ggml-cpu.cpp 与 ggml-cpu-aarch64.cpp 中则依据这些标志在编译进二进制的一组候选内核里动态挑选执行路径。

构建与安装

配置完成后，执行构建与安装：

$ cmake --build build-android --config Release -j{n} $ cmake --install build-android --prefix {install-dir} --config Release

• -j{n}：n为宿主机并行编译任务数；
• --prefix {install-dir}：指定安装目录，将头文件、库与可执行文件集中输出，便于后续整体推送。

部署到设备并运行

安装完成后，在宿主机下载你选定的模型，然后通过 adb 将安装目录与模型推送到设备：

$ adb shell "mkdir /data/local/tmp/llama.cpp" $ adb push {install-dir} /data/local/tmp/llama.cpp/ $ adb push {model}.gguf /data/local/tmp/llama.cpp/ $ adb shell

进入adb shell后：

$ cd /data/local/tmp/llama.cpp $ LD_LIBRARY_PATH=lib ./bin/llama-simple -m {model}.gguf -c {context-size} -p "{your-prompt}"

这里以llama-simple为例（llama-simple是仓库 examples 下最精简的推理示例，适合验证部署链路）。关于context-size的取值建议与其余 examples 的用法，参照上文 Termux 一节。

重要提醒：Android 系统不会自动查找lib目录下的共享库路径，必须显式设置LD_LIBRARY_PATH=lib才能运行安装后的可执行程序。Android 在较新的 API 级别上已支持RPATH，未来这一行为可能发生变化。

PowerInfer 在 Android 上的专属编译要点（骁龙 8 Elite 示例）

本仓库在 Android 上的构建还包含了 PowerInfer 稀疏推理引擎的专属配置。以骁龙 8 Elite（Qualcomm 8 Elite）设备为例，smallthinker/README.md 给出了完整流程：由于稀疏推理依赖异步 I/O，需要先将仓库自带的libaio与liburing交叉编译并安装进 NDK sysroot，随后再执行 CMake 配置：

cmake -S . -B build_a \ -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \ -DANDROID_ABI=arm64-v8a \ -DANDROID_PLATFORM=android-34 \ -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DBUILD_SHARED_LIBS=OFF \ -DGGML_OPENMP=OFF \ -DLLAMA_CURL=OFF \ -DAZ_ENABLE_PERFETTO=ON \ -DPOWERINFER_NO_FFN_REPACK=ON \ -DDISABLE_ARM_FEATURE_CHECK=ON \ -DCMAKE_C_FLAGS="-march=armv8.6-a -D__USE_GNU -Ofast -flto" \ -DCMAKE_CXX_FLAGS="-march=armv8.6-a -D__USE_GNU -Ofast -flto" cmake --build build_a --config RelWithDebInfo --target llama-cli -j32

对比通用 NDK 构建，这里出现了几个 PowerInfer 专属开关：

• -DPOWERINFER_NO_FFN_REPACK=ON：关闭 FFN 权重重打包（该选项在仓库其他 ARM 平台如 rk3588 等交叉编译示例 中同样被设置）；
• -DDISABLE_ARM_FEATURE_CHECK=ON：禁用 ARM 特性运行时检查，配合固定的-march编译标志；
• -DAZ_ENABLE_PERFETTO=ON：启用 Perfetto 性能追踪；
• -DBUILD_SHARED_LIBS=OFF：静态链接，减少部署时的库文件管理负担。

Android 上运行稀疏模型的注意事项

PowerInfer 在移动端运行时（README 中同样适用于 Termux）还有几点值得注意：

• 运行需要使用Q4_0 量化的稀疏模型，且线程数建议不超过 8（-t 4是文档示例值）；
• 如需低内存运行模式，可先用GENERATE_EXPERT_BUNDLE环境变量生成专家包（expert bundle），再用 get_no_moe_weights_ffn.py 从 GGUF 中剥离 MoE 权重，最后以EXPERT_BUNDLE_PATH与MAX_N_CACHED环境变量（按内存上限调节缓存矩阵数，如 4B 模型 1GB 限制下取 768）启动；
• 在 Termux 中运行内存高效版本时可能需要 root 权限；
• 稀疏 lm_head 可能带来轻微精度损失，如需关闭可修改 llama-model.cpp 中的对应条件，但推理速度会变慢。

将 PowerInfer 集成进 Android 应用的官方示例

如果你的目标不是命令行工具，而是将推理能力嵌入 Android App，仓库提供了现成的示例工程 examples/llama.android：包含一个 Android Library 模块（llama/）与一个演示 App（app/）。其中 build.gradle.kts 展示了通过 Gradle 的externalNativeBuild直接调用 CMake 的方式，并显式传入-DLLAMA_CURL=OFF、-DLLAMA_BUILD_COMMON=ON、-DGGML_LLAMAFILE=OFF、-DCMAKE_BUILD_TYPE=Release等参数，minSdk设为 33，NDK 的 CMake 版本要求 3.22.1——这些参数与本文前述 NDK 命令行构建一脉相承，可作为 App 集成时的参考基线。

常见问题与调试建议

1. 内存暴涨导致终端被杀：几乎总是-c上下文设置过大所致。建议从 4096 起步，根据设备可用内存逐步上调。
2. lib找不到 / 动态库加载失败：Android 不会自动搜索lib目录，务必在运行前设置LD_LIBRARY_PATH=lib。
3. OpenMP / llamafile 报错：NDK 路径下两者均不可用，按上文参数显式关闭即可。
4. 设备端构建速度慢：Termux 在手机本机编译耗时较长，可适当减小-j防止过热降频；追求速度应改用宿主机 NDK 交叉编译。
5. 指令集不匹配：即使目标设备不支持编译时指定的-march，ggml 的运行时 CPU 特性检测（见 ggml-cpu.c）会兜底选择可用内核，但为获得最佳性能，仍建议按实际设备调整 ABI 与架构标志。

总结

在 Android 上部署 PowerInfer 有两条清晰的路径：Termux 设备端构建适合快速上手与原型验证，全程无需 PC；NDK 交叉编译则适合追求性能优化、批量分发与 App 集成。两者共享同一套 CMake 构建体系，核心差异在于工具链与运行约束。对 PowerInfer 用户而言，结合 smallthinker/README.md 中的稀疏模型编译与运行参数（POWERINFER_NO_FFN_REPACK、DISABLE_ARM_FEATURE_CHECK、MAX_N_CACHED等），即可在骁龙 8 Elite 等现代旗舰 SoC 上获得完整的本地大模型推理体验。

• 人工智能
• 大模型
• 推理引擎
• 本地部署