简介一套面向安卓端大模型部署场景的源码包聚焦基于MLC-LLM框架的InternLM2.5-1.8B轻量模型完整讲解如何在手机端从环境搭建、模型转换与量化、配置生成到打包上线的落地过程。压缩包共包含3个文件以inscode工程配置、HTML说明文档和gitignore规则文件为主整体大小仅为6KB属于轻量级参考代码便于开发者快速定位核心配置与说明。内容覆盖安装Rust与Android Studio、配置环境变量、转换并量化模型、修改gradle构建参数、创建签名以及命令行编译等多个实操节点同时针对App运行时可能出现的兼容或报错问题给出排查思路并提供工程结构上的参考。已有405人学习下载适合具备一定安卓基础、希望在端侧部署轻量大模型的开发者阅读能帮助减少踩坑时间快速搭建属于自己的移动端模型应用。 这两年“端侧大模型”在安卓开发圈里已经不算新词了。手机本地直接跑 LLM从离线翻译、会议纪要总结到智能修图、本地知识库问答真实落地的场景越来越多。很多朋友拿到模型后第一步就卡住模型文件怎么量化源码怎么编译手机内存怎么扛得住我把安卓端部署大模型的完整路子走了一遍从框架选型、模型量化、JNI 封装到 Android 工程编译、真机排错整理成这篇实操笔记。主线用 llama.cpp 这个方案展开会结合一份可运行的最小工程来讲源码结构适合有一定 Android 基础、想自己做端侧 AI 应用的开发者参考新手照着做也能把 demo 跑起来。1. 部署前的思路拆解与方案选型1.1 为什么要把大模型搬到安卓端很多人第一反应是“手机算力这么弱跑大模型不是自己找罪受吗”。但端侧部署带来的好处很实在第一是隐私聊天记录、照片、文档都在本地处理不上传服务器这在企业场景几乎是刚需第二是离线可用地铁、电梯、飞机上没网也能正常提问第三是延迟少了网络请求那一轮往返很多简单任务的响应时间反而比云端快第四是成本省去了按 token 计费的 API 费用。代价当然也明显手机内存有限、存储空间小、CPU/GPU 性能不如服务器还有一个容易被忽略的坑——长时间推理带来的发热降频。所以端侧部署本质上是“在资源约束下做工程取舍”模型体积、量化精度、上下文长度、线程数这些参数都要反复调。可以这么理解云端部署就像租个大仓库随便堆货端侧部署是在自己家客厅摆货架空间小但随取随用麻烦点在于每样东西都得精打细算。1.2 主流端侧推理框架对比这几年安卓端能跑的框架不少最常见的这几个我简单排了个表框架核心特点适合场景上手难度llama.cppGGUF 量化生态成熟CPU/GPU 后端都有Android 示例完整快速在安卓上跑 LLM低MLC-LLM基于 TVM 统一编译GPU 优化激进追求极限性能和 GPU 利用中高ExecuTorchPyTorch 官方移动端方案支持 LLM 导出已有 PyTorch 生态的项目高TFLite / MediaPipe轻量偏传统小模型分类、OCR、语音小模型低我最终选了 llama.cpp理由很直接GGUF 格式的量化模型几乎成了社区事实标准google 一下能找到大量直接可用的权重它的 Android demo 做得比较完整CMake 构建脚本、JNI 层代码都有现成参考而且它支持纯 CPU 推理不依赖 GPU兼容性更好。如果你手里有现成的 PyTorch 模型MLC-LLM 也可以尝试但它的构建链路复杂不少第一次跑通的时间成本更高。1.3 选型结论与参数范围端侧跑大模型参数规模不能贪大。以现在的旗舰手机来看1B 到 3B 的模型跑起来体验最舒服量化后文件体积控制在 2GB 左右比较合适。我这次用 Meta-Llama-3.2-3B-Instruct 做测试Q4_K_M 量化后约 2GB在骁龙 8 Gen 2 上纯 CPU 推理大概能到每秒 10 到 20 个 token。7B 模型端侧也能跑但内存占用高、首 token 延迟明显增加手机发热也比较严重不太推荐入门阶段尝试。量化格式我选了 Q4_K_M这是 llama.cpp 里的 4-bit 量化规格兼顾体积和生成质量。为什么不用更激进的 Q2、Q3因为它们省下来的几百 MB 换来的质量损失太明显文字生成任务很容易暴露语病。为什么不用 FP16体积直接翻三倍手机内存根本扛不住。实际项目里可以在 Q4_K_M 和 Q5_K_M 之间做个对比测试差别不大就选体积小的。2. 环境准备与源码获取2.1 本地编译环境搭建编译安卓原生库之前先把工具链补齐。我用的组合是JDK 17、Android Studio 最新稳定版、Android SDK 33 以上、NDK r26、CMake 3.22.1。这几个版本之间最好保持兼容比如 llama.cpp 新版对 NDK 版本有要求太老的 NDK 编译会报“unknown type name”之类的奇怪错误。SDK Manager 里记得勾选 NDK 和 CMake否则 Gradle 找不到外部构建工具。建议打开“Show Package Details”选定具体版本而不是只装最新版后面切换项目时不容易踩版本不一致的坑。安装完后用gcc --version验证 NDK 自带编译器是否可用就没必要了重点确认 Android Studio 里 SDK Location 路径和 local.properties 一致。2.2 获取 llama.cpp 源码与 Android 工程llama.cpp 的官方仓库地址是https://github.com/ggml-org/llama.cppclone 下来后你会发现examples/llama.android目录下有一个可直接导入 Android Studio 的工程。另外还有一个社区项目feicien/llama.android封装更友好界面现成适合快速跑通。两者原理一样核心都是通过 JNI 调用 llama.cpp 的 C 接口diff 一下源码能学到不少东西。拉代码时建议指定 commit 而不是永远用 master因为主分支经常更新API 也可能变。等你的工程跑通后再考虑更新。源码目录里有几个关键子目录ggml是底层张量计算库src是 llama.cpp 的模型加载和推理逻辑examples/llama.android是安卓壳子。后面改核心逻辑基本只动src和 JNI 层。2.3 模型下载、转换与量化模型可以到 Hugging Face 或 ModelScope 下载。如果你下载的已经是 GGUF 格式直接跳过转换步骤。我这次拿的是官方 PyTorch 权重所以先用 llama.cpp 自带的脚本转格式python3 convert_hf_to_gguf.py ./Meta-Llama-3.2-3B-Instruct \ --outfile llama-3.2-3b-instruct-f16.gguf \ --outtype f16转出来的 FP16 文件大概 6GB太大接着量化./llama-quantize llama-3.2-3b-instruct-f16.gguf \ llama-3.2-3b-instruct-Q4_K_M.gguf \ Q4_K_M量化完成后得到约 2GB 的 GGUF 文件。注意转换脚本依赖 Python 和 torch建议在 Python 3.10 以上的环境执行。如果模型来源是 GGUF 格式但量化级别太高或太低也可以直接拿llama-quantize再转一次。3. 核心细节解析与实操要点3.1 模型如何塞进 APK模型文件处理是整个工程里最影响体验的一步。直接放进assets目录最简单编译时打进 APK首次启动系统会自动释放。但问题也很明显2GB 的模型会让 APK 体积膨胀安装时间边长还容易触发应用商店对包体大小的限制。推荐的做法是首次启动时把模型文件放入应用私有目录filesDir。具体来源可以是用户手动选择、服务器下载或电脑adb push。我测试时用的方式是把模型先放到手机/sdcard/Download/应用启动时用FileInputStream复制到getFilesDir()/models/下。复制过程要做文件长度校验防止中途断掉。模型加载时传给原生层的就是这个私有目录的绝对路径而不是assets路径。3.2 JNI 层封装与 Native 调用Android 应用跑在 Java/Kotlin 层llama.cpp 是 C/C中间必须用 JNI 搭桥。以官方 llama.android 工程为例JNI 层对外暴露loadModel(modelPath)和generate(prompt)两个核心方法。我摘了一段最小封装的骨架extern C JNIEXPORT jstring JNICALL Java_com_example_llama_LLMEngine_generate( JNIEnv* env, jobject thiz, jstring model_path, jstring prompt) { const char* model env-GetStringUTFChars(model_path, nullptr); const char* text env-GetStringUTFChars(prompt, nullptr); llama_model_params model_params llama_model_default_params(); model_params.n_gpu_layers 0; // 纯 CPU 推理 llama_model* lm llama_load_model_from_file(model, model_params); llama_context_params ctx_params llama_context_default_params(); ctx_params.n_ctx 1024; ctx_params.n_threads 4; llama_context* ctx llama_new_context_with_model(lm, ctx_params); // 这里省略了 tokenize、采样和生成循环 std::string result generated result; env-ReleaseStringUTFChars(model_path, model); env-ReleaseStringUTFChars(prompt, text); return env-NewStringUTF(result.c_str()); }这段代码只是展示了 JNI 层怎么把字符串参数传给 C真正的 tokenize、生成循环还需要按 llama.cpp 的common库示例补齐。我的建议是直接改官方llama.android的llama-android.cpp不要从空项目开始手写否则光是 llama.cpp 的 API 参数就能调一整天。调用时 JNI 方法名一定要和 Kotlin 层的包名、类名、方法名严格对齐否则运行时会报UnsatisfiedLinkError。3.3 推理参数、线程数与内存配置llama.cpp 的推理参数决定了生成速度和质量几个关键项必须调n_ctx控制上下文窗口端侧建议 512 到 1024太长会吃掉大量内存n_threads建议设为 CPU 核心数的一半左右比如 8 核手机先试 4太大反而因调度开销降低速度且发热严重temperature默认 0.7 左右追求信息准确性可以降到 0.3追求创造力再往上调top_p保持 0.9 附近比较稳。内存这块要特别留意。3B 模型 Q4 量化后权重占 2GB但推理时的 KV Cache 还会额外吃内存上下文越长占用越大。实测n_ctx1024时峰值内存可能到 3.5GB 以上所以老机型最好把n_ctx降到 512。另外记得在 AndroidManifest 里给进程加上android:largeHeaptrue给应用多申请点堆内存虽然对 native 层帮助有限但至少能减少一些 Java 层 OOM。4. 完整实操流程从源码到真机运行4.1 Gradle 配置与 NDK 编译在 Android Studio 里导入examples/llama.android后先看app/build.gradle。默认配置里已经写好了externalNativeBuild只需要确认 CMake 路径指向src/main/cpp/CMakeLists.txtandroid { defaultConfig { externalNativeBuild { cmake { cppFlags -stdc17 -O3 arguments -DLLAMA_NATIVEOFF } } ndk { abiFilters arm64-v8a } } externalNativeBuild { cmake { path src/main/cpp/CMakeLists.txt } } }这里把abiFilters限定为arm64-v8a因为现在 64 位手机占绝大多数编译 32 位库不仅浪费时间还容易遇到 NDK 兼容问题。-O3优化对推理速度影响很大务必保留。CMakeLists 里会编译出libllama.soGradle 构建时自动打包进 APK。构建命令可以直接用 Android Studio 的 Run也可以在终端执行./gradlew assembleDebug第一次构建要下载依赖耐心等。如果 CMake 报找不到编译器先检查 NDK 版本和 CMake 路径。4.2 界面与交互逻辑官方 demo 的界面很简单一个输入框、一个生成按钮、一个显示区域。我在自定义工程里用 Kotlin 写了个线程池调用 JNI避免阻塞主线程class MainActivity : AppCompatActivity() { private val engine LLMEngine() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) val modelPath File(filesDir, models/llama-3.2-3b-Q4_K_M.gguf).absolutePath engine.loadModel(modelPath) findViewByIdButton(R.id.btn_generate).setOnClickListener { val prompt findViewByIdEditText(R.id.et_prompt).text.toString() thread { val output engine.generate(prompt) runOnUiThread { findViewByIdTextView(R.id.tv_output).text output } } } } }LLMEngine是一个用object声明的单例里面写external方法对应 JNI 层的Java_com_example_llama_LLMEngine_*。这一步最容易出问题建议先写一个只返回字符串“hello”的nativeString()方法跑通完整链路再接入模型推理逐个排查。4.3 真机运行与效果验证把手机通过 USB 连电脑开启开发者选项和 USB 调试Android Studio 识别到设备后直接点 Run。安装成功后先去/sdcard/Download/把模型复制到应用私有目录或者用adb pushadb push llama-3.2-3b-instruct-Q4_K_M.gguf /sdcard/Download/然后应用首次启动会自动完成复制逻辑。输入“用一句话解释什么是大模型”点击生成正常情况下几秒内会看到逐字输出。如果长时间没反应先看 Logcat 有没有llama_model_load相关报错最常见的就是路径不对或内存不足。5. 常见问题与排查技巧实录端侧部署踩坑是常态我把实操中遇到的高频问题整理成一张速查表现象常见原因排查与解决编译报错unknown argument: -fopenmpNDK 默认 OpenMP 配置不对检查 CMakeLists确保链接-fopenmp和libomp加载模型报failed to load model路径错误或文件损坏打印 modelPath确认文件存在且大小正确生成速度极慢线程数设置过高或编译未开优化n_threads改为 4确保-O3生效首 token 延迟高模型文件在外部存储读取慢先把模型复制到 filesDir再用绝对路径加载输出全是乱码prompt 模板不正确或词表不匹配检查模型的 chat template按官方格式拼 prompt内存溢出崩溃n_ctx太大降到 512并给 Application 加android:largeHeaptrue发热严重长时间满载推理限制线程数、降低n_ctx必要时在推理之间加休眠这里有一个非常容易忽视的坑Release 包默认开启代码混淆会把 JNI 相关方法名改掉导致运行时报UnsatisfiedLinkError。真要打 Release记得在proguard-rules.pro里保留原生方法-keepclasseswithmembernames class * { native methods; }另外模型复制过程要用md5或文件长度做完整性校验我曾经因为复制了一半就启动应用卡在加载流程上排查了快一小时最后发现是模型文件少了一块。6. 源码定制与后续扩展6.1 源码结构导读如果你要二次开发先搞清楚 ll ationama.android 工程里每个文件的作用。app/src/main/cpp/llama-android.cpp是 JNI 实现里面把模型加载和对话生成封装成了Java_com_example_llama_*系列方法app/src/main/java/com/example/llama/下的 Java /Kotlin 文件只负责界面和线程调度CMakeLists.txt确定了要编译哪些 C 源文件。改模型路径、调参数、换 prompt 模板都在 JNI 层和 Java 层之间配合。建议动手前先看一遍llama.cpp里的examples/main/main.cpp它是命令行版的完整推理流程里面 tokenize、采样、生成循环都是可运行的参考。把这段逻辑移植到 JNI 里时注意每个 API 函数的生命周期管理尤其是 ctx 和 model 的释放顺序搞反了会出现难查的崩溃。6.2 可以继续扩展的方向跑通最小 demo 后可以往这几个方向延伸流式输出把生成结果一个字一个字推送到界面体验比一次性返回好很多多轮对话需要维护历史消息并正确处理 prompt 模板本地知识库就是 RAG先用向量库检索再拼 prompt能明显提升问答准确性Vulkan 后端把n_gpu_layers设为大于 0让 GPU 参与计算速度能再上个台阶但兼容性要按机型适配。还有一个方向是接入语音输入用系统自带 SpeechRecognizer 把语音转文字再送给大模型体验上就是本地语音助手。整体架构不用变只加一个输入源。这套流程我前后折腾了两天最扎心的不是编译而是模型路径三番五次写错。后来在真机调试时发现把模型放到外部存储、由应用启动时复制到私有目录是最可靠的方案。如果你照着踩过一次坑多半会认同安卓端侧大模型部署真正难的不是模型本身而是工程细节——NDK 版本、ABI、JNI 封装、内存约束、线程调度每一环都不能偷懒。希望这篇记录能帮你省下排查时间。最后再分享一个小技巧先把最简 demo 跑通再逐步加功能比一上来就塞七个模型靠谱得多。本文还有配套的精品资源点击获取