端侧AI 模型部署实战四(llama.cpp Android移植)

之前文章有说到几种模型加载的方式方式1 本地PC上 ollama可以直接跑未量化的.bin/.safetensors大模型比如ollama run qwen:3.5-4b-instruct-q4_K_M直接加载模型方式2本地本地PC上llama.cpp 跑量化的大模型比如: build\bin\Release\llama-cli.exe -m D:\workspace\AI\lm_studio_models\lmstudio-community\gemma-3-4b-it-GGUF\gemma-3-4b-it-Q4_K_M.gguf方式3手机上PC通过llama.cpp 跑量化的大模型方式3涉及到llama.cpp Android 移植本文包含的详细的移植步骤和相关踩坑记录。一、编译环境核心依赖必装版本适配优先llama.cpp Android 编译核心依赖 3 类工具版本需严格匹配避免兼容性报错优先推荐稳定版本本文计划中用到的 llama.cpp、Android Studio 环境。1. 基础工具所有系统通用Git用于克隆 llama.cpp 源码版本 ≥ 2.30.0避免源码克隆不完整CMake用于生成编译配置版本 ≥ 3.22.1llama.cpp 最新源码要求低于此版本会报语法错误Android SDK需包含 Android 23 版本对应 API Level 23兼容绝大多数手机建议选择 Android 28适配性最优2. NDK核心依赖交叉编译必备NDK 是实现 C/C 代码编译为 Android 可执行文件so 库的核心版本选择直接决定编译成功率优先推荐以下 2 个稳定版本适配 llama.cpp 最新源码避免 NDK 27 的兼容性 bug推荐版本1NDK r26c首选稳定无报错完美兼容 llama.cpp 交叉编译适配你学习计划中的 Android Studio 环境推荐版本2NDK r25b备选若 r26c 安装失败可选择此版本兼容性强适合旧版 Android Studio安装方式3种可选按需选择Android Studio 内置安装最便捷打开 Android Studio → Tools → SDK Manager → SDK Tools → 勾选 NDK对应版本→ Apply 自动下载安装默认路径Android SDK 路径/ndk/版本号官方单独下载访问 Android NDK 官方下载页根据操作系统选择对应版本解压至自定义路径如 D:\Android\ndk-r26c后续需配置环境变量。SDK Manager 命令行安装已安装 Android SDK Tools 的情况下执行命令sdkmanager ndk;26.1.10909125对应 r26c自动安装至 SDK 目录下。ADB 工具用于将编译后的 so 库、模型文件推送至手机版本 ≥ 34.0.4配置环境变量后可直接在命令行使用。二、三大系统环境搭建步骤详细可复现重点讲解「电脑端 NDK 交叉编译」贴合你 Android APP 开发需求附加 Termux 手机端编译备用方案步骤按优先级排序跟着执行即可跑通。方案1Windows 系统NDK 交叉编译首选步骤1安装基础工具安装 Git官网下载 Git for Windows勾选 Add Git to PATH安装完成后命令行输入git --version验证。安装 CMake官网下载 CMake选择 Add CMake to the system PATH安装后输入cmake --version验证。安装 Android Studio NDK r26c按前文 NDK 安装方式操作记住 NDK 安装路径如 D:\Android\Sdk\ndk\26.1.10909125。步骤2配置环境变量右键此电脑 → 属性 → 高级系统设置 → 环境变量 → 系统变量 → PATH添加以下 3 个路径替换为你的实际路径NDK 路径D:\Android\Sdk\ndk\26.1.10909125NDK 工具链路径D:\Android\Sdk\ndk\26.1.10909125\build\cmake配置完成后重启命令行输入ndk-build --version能正常显示版本即配置成功。步骤3克隆 llama.cpp 源码并编译克隆源码命令行执行git clone https://github.com/ggml-org/llama.cpp.git若克隆缓慢可通过 scp 拷贝源码至本地目录。如果下载太慢可以使用git clone https://gitee.com/mirrors/llama-cpp.git 这个国内镜像速度很快。在源码同级目录创建bat文件(本地使用的window环境结合实际情况进行调整):: 1. 进入源码根目录清理旧构建 cd /d D:\workspace\AI\tools\llama.cpp-android\llama.cpp rmdir /s /q build-android mkdir build-android cd build-android :: 2. 设置环境变量 set ANDROID_NDKD:\workspace\AI\SDK\ndk\28.2.13676358 chcp 65001 nul :: 3. CMake 配置核心使用NDK自带make无相对路径 cmake .. ^ -DCMAKE_TOOLCHAIN_FILE%ANDROID_NDK%/build/cmake/android.toolchain.cmake ^ -DANDROID_ABIarm64-v8a ^ -DANDROID_PLATFORMandroid-28 ^ -DCMAKE_BUILD_TYPERelease ^ -DCMAKE_C_FLAGS-marcharmv8-a ^ -DCMAKE_CXX_FLAGS-marcharmv8-a ^ -DGGML_OPENMPOFF ^ -DGGML_NATIVEOFF ^ -DBUILD_SHARED_LIBSON ^ -DGGML_BUILD_SHAREDON ^ -DLLAMA_BUILD_SHAREDON ^ -G Unix Makefiles ^ -DCMAKE_MAKE_PROGRAM%ANDROID_NDK%/prebuilt/windows-x86_64/bin/make.exe :: 4. 执行编译 cmake --build . -j43. 编译完成生成的 so 库libllama.so、libggml.so位于 llama.cpp\build-android\bin 目录下可直接集成至 Android 项目的 jniLibs 文件夹。三、Android项目创建验证第 1 步新建一个空项目最简单打开 Android Studio点击New Project选择Empty Views Activity空 Activity点击Next名字随便填比如LlamaTest点击Finish第 2 步创建文件并放入 .so 库文件关键找到这个目录app → src → main创建文件jniLibs\arm64-v8a, 编译好的库复制进去第 3 步修改Java及配置文件MainActivity.kt修改如下package com.example.llamatest import android.os.Bundle import android.widget.TextView import androidx.appcompat.app.AppCompatActivity class MainActivity : AppCompatActivity() { companion object { init { System.loadLibrary(ggml) System.loadLibrary(llama) } } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) val text findViewByIdTextView(R.id.tv_status) text.text ✅ 所有库加载成功\nlibggml libllama 正常运行 } }AndroidManifest.xml修改如下?xml version1.0 encodingutf-8? manifest xmlns:androidhttp://schemas.android.com/apk/res/android packagecom.example.llamatest application android:allowBackuptrue android:iconmipmap/ic_launcher android:labelstring/app_name android:themestyle/Theme.AppCompat.Light activity android:name.MainActivity android:exportedtrue intent-filter action android:nameandroid.intent.action.MAIN / category android:nameandroid.intent.category.LAUNCHER / /intent-filter /activity /application /manifest新建文件app/src/main/res/layout/activity_main.xml?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:layout_widthmatch_parent android:layout_heightmatch_parent android:gravitycenter android:orientationvertical TextView android:idid/tv_status android:layout_widthwrap_content android:layout_heightwrap_content android:text验证中... android:textSize24sp/ /LinearLayoutKotlin DSL (build.gradle.kts) 中加入implementation(androidx.appcompat:appcompat:1.6.1) implementation(com.google.android.material:material:1.11.0) implementation(androidx.constraintlayout:constraintlayout:2.1.4)连接手机运行Android studio手机界面成功运行显示如下注意调试的过程中遇到多次应用打开闪退的问题需要抓取logcat进行分析我这边是通过下面方式调试adb shell logcat -cadb shell logcat logcat.txt打开手机中的apk复现crash问题抓取到的logcat.txt错误中找到crash的相关log丢AI工具进行分析也可以自己分析。这篇文章只记录了llama.cpp相关so正常加载大模型需要基于这些so进行推理下一篇文字将继续记录手机端加载大模型加载及推理。