最近关于安卓端运行本地大模型的讨论越来越多很多人会直接把“安卓 LLM 框架”和 Ollama 放在一起比较甚至期待在手机上装一个 Ollama 就能跑起来。真实情况是Ollama 官方并没有提供可以直接安装的安卓原生 App它主攻的是桌面端和服务端场景。而在安卓手机上本地推理通常要走的是一条完全不同的技术路线涉及 NDK、C 推理引擎、GGUF 模型格式、JNI 封装、量化精度和内存预算。这篇文章不打算继续争论“谁吊打谁”而是从实际开发视角把安卓端 LLM 框架选型、运行原理、最小 Demo、性能观测和常见坑梳理清楚。读完你会理解 Ollama 在移动端的真实定位也知道在安卓里集成本地大模型时最应该关注的是哪几个环节。1. 移动端跑大模型先看清 Ollama 的真实边界1.1 安卓本地推理和 Ollama 解决的问题不一样Ollama 的本质是一套本地大模型的管理与推理服务工具。它把模型下载、模型仓库、HTTP API、命令行交互整合在一起让开发者可以用一个命令拉起 Qwen、Llama、DeepSeek 等模型然后通过ollama run或者 REST API 调用。但 Ollama 当前主要支持 macOS、Linux、Windows 这三大平台。安卓端想要使用它通常只有两种间接方式在局域网或服务器上部署 Ollama安卓 App 通过 HTTP 接口调用远程服务。在安卓设备上借助 Termux 或容器方案安装 Linux 环境再尝试运行但这会受到 CPU 架构、内存、存储和特权限制的影响体验并不好。真正意义上的“安卓本地 LLM 推理”指的是模型文件下载到手机内存推理计算也发生在手机 CPU、GPU 或 NPU 上。这个场景需要的是推理引擎库而不是一个服务管理工具。所以把 Ollama 当作安卓端推理框架来对比本身就不太公平。1.2 手机端不是 PC 端内存、电量、NPU 都是约束PC 上跑 Ollama 时16GB 或 32GB 内存很常见GPU 显存也能支撑 7B 甚至 14B 模型的量化版本。手机端的约束要严苛得多约束项典型 PC 环境典型安卓手机环境可用内存16GB 至 64GB8GB 至 16GB且系统和其他应用占用后剩余有限GPU 生态NVIDIA CUDA 生态成熟高通 Adreno、Arm Mali、Mali、IMG 等碎片化NPU部分 PC 有专用 AI 加速单元但生态不统一手机 SoC 普遍集成 NPU但各家 SDK 不通用散热空间大风扇或水冷无主动散热持续推理会导致降频电量外接电源基本不敏感电池供电推理功耗直接影响可用时间这些约束决定了安卓端主要选择小参数模型例如 1B 到 4B 的量化模型并且对推理框架的 CPU 优化、内存复用、算子融合要求很高。1.3 三种可行技术路线在实际项目里安卓端使用 LLM 一般有三种路线本地原生推理集成 llama.cpp、MLC LLM、MediaPipe LLM Inference 等推理引擎直接加载量化模型。适合对隐私、离线、低延迟有要求的场景。远程服务调用服务端部署 Ollama 或 vLLM安卓 App 作为客户端请求接口。适合模型较大、手机性能不足、需要多人共享的场景。混合路线默认走本地小模型遇到复杂任务再请求云端大模型。适合追求体验和成本平衡的产品。三种路线各有取舍没有绝对优劣。下面从工程角度对比主流方案的适配情况。2. 找对框架四大方案对比与选型依据2.1 方案横向对比集成到安卓工程时常见的四个方向如下方案技术形态适合人群集成难度特点llama.cppC/C 推理引擎支持 Android NDK 编译需要底层掌控、追求速度和可移植性的团队较高模型格式为 GGUF跨平台能力强社区活跃MLC LLM基于 TVM 的编译式推理方案希望一套代码覆盖 Android/iOS/Web 的团队高通过编译优化算子支持多平台部署MediaPipe LLM InferenceGoogle 提供的端侧 LLM 推理 API已经使用 MediaPipe 的安卓开发者中等封装程度高API 简洁但可调参数有限Ollama 远程服务 安卓客户端服务端部署 Ollama手机通过 REST API 调用需要在手机端快速接入大模型能力的团队低手机只做请求展示推理压力和模型空间都在服务端从社区热度和对开发者控制力来看llama.cpp 是目前安卓本地推理绕不开的基础方案。很多商业化的安卓端 AI 应用底层推理引擎要么直接使用 llama.cpp要么是从它派生出来的分支。2.2 选型判断步骤选型不要只看“哪个框架火”建议按以下顺序判断模型规模如果必须跑 7B 以上模型优先考虑远程服务或高端设备上的混合方案。部署形态产品要求完全离线就选本地推理允许联网则远程调用更简单。开发团队团队熟悉 C 和 NDK可以选 llama.cpp团队以 Java/Kotlin 为主先考虑 MediaPipe 这类封装更完整的 SDK。跨端需求如果同时要支持 iOS、WebMLC LLM 或 llama.cpp 的跨平台能力更有价值。性能验证同一模型在真实设备上跑一分钟记录 token/s 和内存占用再决定。选型的关键判断是手机本地推理的意义在于离线、隐私和低延迟如果不依赖这些特性远程调用总是更容易维护。2.3 开发环境准备SDK、NDK、CMake 与模型文件无论选择哪种本地方案都要先确认安卓开发环境。推荐环境如下实际版本以你安装的为准工具建议版本用途Android Studio最新稳定版创建和管理安卓工程Android SDKAPI 26 或以上兼容更多机型Android NDKr25 或 r26编译 C/C 推理引擎CMake3.22 或以上配置 native 编译Gradle与 Android Studio 匹配打包构建模型文件GGUF 格式的量化模型实际推理使用注意不要等到编译报错才去查 NDK 版本。llama.cpp 这类项目对 NDK 和 CMake 版本有要求先用sdkmanager装好再导入工程能省掉大量时间。模型文件方面国内下载官方模型有时较慢。建议通过 Ollama 或 Hugging Face 的镜像站提前在 PC 上下载好 GGUF 文件再用 adb 推到手机存储中避免在手机上反复下载大文件。3. 以 llama.cpp 为主线跑通安卓端最小推理流程下面用一个最小示例说明集成思路。示例中的代码只用于展示整体链路实际工程需要根据你的包名、目录结构和依赖版本调整。3.1 准备 GGUF 模型并完成量化llama.cpp 使用 GGUF 格式的模型文件。如果手头是 Hugging Face 上的原始权重需要先转换为 GGUF再进行量化。这一步通常在 PC 上完成。# 下载 llama.cpp 源码 git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp # 编译转换和量化工具 mkdir build cd build cmake .. cmake --build . --config Release -j # 先转换模型格式这里以 Hugging Face 目录结构为例 python3 ../convert_hf_to_gguf.py /path/to/your/model \ --outfile your-model.gguf \ --outtype f16 # 再量化到 Q4_K_M文件体积和显存占用更小 ./bin/llama-quantize your-model.gguf your-model-q4_k_m.gguf q4_k_m量化精度会直接影响内存占用和生成质量。Q4_K_M 是场景比较均衡的选择适合 4B 以下模型在手机上跑。如果手机内存紧张可以继续尝试 Q4_0 或 Q3 系列但要接受回答质量下降。3.2 创建安卓工程并配置 CMake 与 NDK在 Android Studio 中新建一个包含 Native C 的工程然后把 llama.cpp 源码放到cpp目录下例如app/src/main/cpp/ ├── llama.cpp/ # llama.cpp 源码 ├── CMakeLists.txt └── native_llm.cpp # JNI 封装CMakeLists.txt 的关键配置如下cmake_minimum_required(VERSION 3.22) project(native_llm) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 仅编译运行需要的平台减小 APK 体积 set(ANDROID_ABI arm64-v8a) add_library(llama STATIC llama.cpp/ggml.c llama.cpp/ggml-alloc.c llama.cpp/ggml-backend.c llama.cpp/ggml-quants.c llama.cpp/llama.cpp llama.cpp/unicode.cpp llama.cpp/unicode-data.cpp ) add_library(native_llm SHARED native_llm.cpp ) target_include_directories(native_llm PRIVATE llama.cpp llama.cpp/include ) target_link_libraries(native_llm llama android log )这里要注意llama.cpp 的源码文件列表会随着版本变化而变化。不要照抄应该以你拉取版本的实际.cpp和.c文件为准。编译前先看一眼llama.cpp/Makefile或 CMake 配置确认需要参与编译的源文件。3.3 通过 JNI 封装推理接口JNI 层的作用是让 Kotlin 能调用 C 推理函数。下面是一个简化封装#include jni.h #include string #include llama.h extern C JNIEXPORT jlong JNICALL Java_com_example_androidllm_NativeLlm_createContext( JNIEnv *env, jobject /* this */, jstring modelPath, jint threads) { const char *path env-GetStringUTFChars(modelPath, nullptr); llama_model_params modelParams llama_model_default_params(); llama_model *model llama_load_model_from_file(path, modelParams); env-ReleaseStringUTFChars(modelPath, path); if (!model) { return 0; } llama_context_params ctxParams llama_context_default_params(); ctxParams.n_ctx 2048; ctxParams.n_threads threads; ctxParams.n_batch 512; llama_context *ctx llama_new_context_with_model(model, ctxParams); return reinterpret_castjlong(ctx); } extern C JNIEXPORT jstring JNICALL Java_com_example_androidllm_NativeLlm_generate( JNIEnv *env, jobject /* this */, jlong ctxPtr, jstring prompt) { llama_context *ctx reinterpret_castllama_context *(ctxPtr); const char *input env-GetStringUTFChars(prompt, nullptr); std::string output; // 这里做 tokenize、推理循环、解析文本伪代码只示意流程 // auto tokens llama_tokenize(ctx, input, true); // 循环调用 llama_decode并不断取 token 追加到 output env-ReleaseStringUTFChars(prompt, input); return env-NewStringUTF(output.c_str()); }这个封装省略了 tokenize、采样参数设置、停止词判断等逻辑。真实项目里建议把整个推理循环放到一个独立的 C 类里避免 JNI 函数体过于庞大。3.4 在 Kotlin 侧加载模型并发起对话Kotlin 侧通过声明external fun调用 native 方法package com.example.androidllm class NativeLlm { companion object { init { System.loadLibrary(native_llm) } external fun createContext(modelPath: String, threads: Int): Long external fun generate(contextPtr: Long, prompt: String): String } }Activity 或 ViewModel 中的调用示例val modelPath ${filesDir}/models/qwen2.5-1.5b-instruct-q4_k_m.gguf val ctx NativeLlm.createContext(modelPath, 4) val result NativeLlm.generate(ctx, 用一句话介绍杭州) runOnUiThread { textView.text result }这里有几个易错点createContext返回的指针需要作为 Long 保存并在不再使用时调用专门的释放函数不要让generate在 UI 线程执行否则会卡住界面模型加载耗时长首次打开 App 时要做好 loading 状态。3.5 验证推理结果与性能记录跑通后在真机上验证以下几点模型能正常加载不闪退。中文输出没有乱码。连续生成 20 个 token 左右界面不长时间无响应。在终端中通过 logcat 观察是否有 native 层异常。adb logcat --pid$(adb shell pidof com.example.androidllm) -v time同时可以用下面命令查看进程真实内存占用adb shell dumpsys meminfo com.example.androidllm记录几个关键数字加载耗时、首 token 延迟、平均 token/s、最大内存占用。不同机型差异很大不要拿网上看到的数字直接对标。4. 推理参数与性能观测为什么同样模型体验差很多4.1 关键参数及其影响同样是 GGUF 模型在手机上的体验差异可能来自推理参数配置。常用参数如下参数含义常见值调大影响调小影响n_ctx上下文窗口长度2048内存占用增大可处理更长对话超过长度后历史被截断n_threads推理线程数4 或 6多核 CPU 利用率更高但发热也更快速度下降发热降低n_batch单次批量处理的 token 数512提示词处理更快内存占用略增提示词处理变慢temperature采样温度0.7输出更随机输出更确定top_p核采样阈值0.9候选范围更大候选范围更小线程数并不是越大越好。手机是大小核架构如果线程数超过性能核数量反而会增加调度开销而且满负荷推理会让手机迅速发热降频。4.2 观测指标token/s、内存、温度、卡顿性能验证不能只看“能不能输出”。建议记录四个指标token/s每秒生成 token 数直接影响用户等待体验。首 token 延迟从用户点击发送到屏幕上出现第一个字的时间。对话体验对这项指标比平均速度更敏感。峰值内存推理过程中dumpsys meminfo显示的进程内存防止多任务场景下被系统杀死。设备温度连续推理 5 分钟后手机后盖是否明显发烫是否触发降频。如果在真机上发现速度越来越慢通常不是框架问题而是散热和降频导致的。4.3 参数调优顺序在手机上做推理调优建议按这个顺序先确定模型量化和大小确保能稳定加载。再调 n_threads以实测 token/s 为准。然后调 n_batch观察长文本提示词的处理时间。最后调采样参数优化回答质量和多样性。每调整一个参数都用相同 prompt 和相同模型重新测一次避免把模型内容差异误判成框架性能问题。5. 安卓 LLM 实践中的高频坑与排查链路5.1 模型路径异常找不到文件、加载失败现象App 启动后提示模型加载失败或者 JNI 层返回 0。可能原因模型文件没有放到应用私有目录。文件名大小写不一致。sd 卡或外部存储没有读取权限。模型文件损坏或下载不完整。检查方式adb shell run-as com.example.androidllm ls files/models/处理建议统一把模型放在filesDir/models下加载前先检查文件大小是否和下载时一致最好在模型文件旁保存一份 SHA-256 校验值。5.2 native 闪退内存不足与不支持指令集现象加载模型后 App 直接退出logcat 中出现Fatal signal 6或SIGSEGV。可能原因abiFilters配置了x86_64或armeabi-v7a但模型推理库只适合arm64-v8a。模型体积过大超出设备可用内存。JNI 中指针被提前释放导致野指针。设备 CPU 不支持某些指令集扩展。检查方式先看崩溃日志中的 signal 类型再用adb shell getprop ro.product.cpu.abilist确认设备架构。处理建议只保留arm64-v8a构建用 1B 量化模型先验证链路JNI 层对指针回归测试不在生成完成前销毁 context。5.3 NDK、CMake 和 Gradle 版本不匹配现象编译时报Unsupported option --android或CMAKE_ANDROID_NDK相关错误。常见原因Gradle、AGP、NDK、CMake 四者版本不匹配或 NDK 路径包含中文和空格。处理建议使用 Android Studio 自带的 SDK Manager 安装 NDK r25 或 r26。在local.properties中显式配置ndk.dir。不要复制网上的 AGP 版本使用 Android Studio 项目模板生成的版本。注意llama.cpp 上游代码更新很快如果你的编译错误信息是某个源码文件找不到先检查是否只拷贝了部分源码目录常见的像是缺少unicode-data.cpp。5.4 输出乱码、重复或终止符不生效现象中文输出变成乱码或者模型一直生成不停不下来。可能原因没有正确解码 UTF-8 字节。采样参数没配置|endoftext|等停止词。上下文窗口耗尽后模型进入退化循环。检查方式在 JNI 层打印原始字节日志对比 UI 层编码。处理建议使用llama_token_to_piece时注意多字节字符边界不能按单字节拼接设置llama_sampler的 stop words对长对话做历史裁剪。5.5 连接 Ollama 服务超时与镜像下载问题如果你走的是“安卓 App 连接 Ollama 服务”的路线常见问题是请求超时。现象App 配置了 Ollama 服务地址但请求一直超时或返回connection refused。排查顺序确认手机和 Ollama 服务端在同一网络且服务端监听地址不是127.0.0.1。确认 Ollama 服务端口11434在防火墙中放行。用手机浏览器直接访问http://服务端IP:11434看是否能返回响应。如果是公网部署还要确认域名解析和 HTTPS 证书链完整。模型下载慢的问题主要是模型文件体积大、官方源网络不稳定。建议在 PC 上提前下载 GGUF 文件再通过 adb 推送。如果使用 Ollama 拉取镜像可以配置国内合规镜像地址具体以官方文档为准。6. 从 Demo 到可用产品工程化建议6.1 学习环境与生产环境的差距学习环境里Demo 能跑通就结束了。生产环境还要考虑模型文件升级用户手机上旧模型如何替换。崩溃监控native crash 需要接入 breakpad 等工具收集符号信息。隐私合规模型输入可能包含用户数据是否允许上传日志。进程生命周期低内存时系统可能回收进程推理状态需要恢复。电量策略推理是高功耗操作需要在前台或前台服务中执行。6.2 模型资源管理下载、校验、缓存与版本不要把模型直接打包进 APK否则 APK 体积会急剧膨胀。推荐做法首次启动时从服务器或对象存储下载模型。下载完成后校验 SHA-256。采用“下载到临时文件再改名”的方式防止下载中断导致半文件被加载。App 升级时保留模型目录避免重复下载。val tempFile File(filesDir, models/tmp_qwen.gguf) val targetFile File(filesDir, models/qwen.gguf) // 下载完成后校验 sha256 if (tempFile.exists() tempFile.length() 0) { tempFile.renameTo(targetFile) }6.3 推理线程、前台服务与 UI 生命周期推理算法绝对不能放到 UI 线程。建议用HandlerThread或协程的Dispatchers.IO执行。遇到耗时的长对话需要把推理放到前台服务并给用户显示进度通知否则 App 退到后台很容易被系统杀掉。释放资源时要小心不要在推理循环中随意释放 context。可以设计一个状态机标记IDLE、LOADING、GENERATING、READY、RELEASED释放操作只在IDLE或RELEASED状态下执行。6.4 接入 Ollama 服务端的混合架构如果最终产品希望兼顾本地和云端可以采用混合架构请求类型处理方式简单任务、离线场景、隐私敏感数据本地 llama.cpp 推理复杂推理、长文档、代码生成请求服务端 Ollama 或云端大模型服务端不可用自动降级到本地小模型这种架构的难点在于如何判断请求适合本地还是云端。常见做法是设置一个“简洁模式”和“深度模式”由用户手动选择或者用关键词、问题长度、任务类型做简单路由。6.5 发布前检查清单发布前至少检查以下项目每一项都直接关系到线上体验检查项验收标准模型加载断网环境下能成功加载本地模型权限不需要不合理的存储、定位权限内存主流中端机运行 10 分钟不因内存被杀电量连续推理 5 分钟耗电量可接受无明显发热崩溃覆盖加载失败、生成中途退出、进程杀死恢复网络策略远程服务超时有明确文案和重试机制合规用户协议说明模型能力边界和数据处理方式版本更新模型文件版本和 App 版本能独立维护7. 结论并没有“最强框架”只有最匹配的场景安卓端大模型框架的核心不是“谁更火”而是你能否在手机的内存、算力、电量和网络约束下找到一个可维护的部署方式。Ollama 在桌面端和服务端是好工具但安卓端本地推理的主力仍是 llama.cpp、MLC LLM 这类底层推理引擎。对大多数开发者来说先通过 llama.cpp 跑通一个 GGUF 模型的 Demo理解 JNI、NDK 和推理参数之间的关系比纠结“最强框架”更有价值。下一步可以沿着三条线继续深入一是研究量化精度对模型回答质量的影响二是在真机上做不同模型的性能压测建立自己的设备性能基线三是尝试接入 NPU 的 SDK逐渐把部分算子从 CPU 迁移到 NPU 上。真正能提升产品体验的往往不是换一个框架而是把模型、量化、调度和交互细节打磨到位。 安卓端本地大模型推理：从Ollama边界到llama.cpp实践
最近关于安卓端运行本地大模型的讨论越来越多很多人会直接把“安卓 LLM 框架”和 Ollama 放在一起比较甚至期待在手机上装一个 Ollama 就能跑起来。真实情况是Ollama 官方并没有提供可以直接安装的安卓原生 App它主攻的是桌面端和服务端场景。而在安卓手机上本地推理通常要走的是一条完全不同的技术路线涉及 NDK、C 推理引擎、GGUF 模型格式、JNI 封装、量化精度和内存预算。这篇文章不打算继续争论“谁吊打谁”而是从实际开发视角把安卓端 LLM 框架选型、运行原理、最小 Demo、性能观测和常见坑梳理清楚。读完你会理解 Ollama 在移动端的真实定位也知道在安卓里集成本地大模型时最应该关注的是哪几个环节。1. 移动端跑大模型先看清 Ollama 的真实边界1.1 安卓本地推理和 Ollama 解决的问题不一样Ollama 的本质是一套本地大模型的管理与推理服务工具。它把模型下载、模型仓库、HTTP API、命令行交互整合在一起让开发者可以用一个命令拉起 Qwen、Llama、DeepSeek 等模型然后通过ollama run或者 REST API 调用。但 Ollama 当前主要支持 macOS、Linux、Windows 这三大平台。安卓端想要使用它通常只有两种间接方式在局域网或服务器上部署 Ollama安卓 App 通过 HTTP 接口调用远程服务。在安卓设备上借助 Termux 或容器方案安装 Linux 环境再尝试运行但这会受到 CPU 架构、内存、存储和特权限制的影响体验并不好。真正意义上的“安卓本地 LLM 推理”指的是模型文件下载到手机内存推理计算也发生在手机 CPU、GPU 或 NPU 上。这个场景需要的是推理引擎库而不是一个服务管理工具。所以把 Ollama 当作安卓端推理框架来对比本身就不太公平。1.2 手机端不是 PC 端内存、电量、NPU 都是约束PC 上跑 Ollama 时16GB 或 32GB 内存很常见GPU 显存也能支撑 7B 甚至 14B 模型的量化版本。手机端的约束要严苛得多约束项典型 PC 环境典型安卓手机环境可用内存16GB 至 64GB8GB 至 16GB且系统和其他应用占用后剩余有限GPU 生态NVIDIA CUDA 生态成熟高通 Adreno、Arm Mali、Mali、IMG 等碎片化NPU部分 PC 有专用 AI 加速单元但生态不统一手机 SoC 普遍集成 NPU但各家 SDK 不通用散热空间大风扇或水冷无主动散热持续推理会导致降频电量外接电源基本不敏感电池供电推理功耗直接影响可用时间这些约束决定了安卓端主要选择小参数模型例如 1B 到 4B 的量化模型并且对推理框架的 CPU 优化、内存复用、算子融合要求很高。1.3 三种可行技术路线在实际项目里安卓端使用 LLM 一般有三种路线本地原生推理集成 llama.cpp、MLC LLM、MediaPipe LLM Inference 等推理引擎直接加载量化模型。适合对隐私、离线、低延迟有要求的场景。远程服务调用服务端部署 Ollama 或 vLLM安卓 App 作为客户端请求接口。适合模型较大、手机性能不足、需要多人共享的场景。混合路线默认走本地小模型遇到复杂任务再请求云端大模型。适合追求体验和成本平衡的产品。三种路线各有取舍没有绝对优劣。下面从工程角度对比主流方案的适配情况。2. 找对框架四大方案对比与选型依据2.1 方案横向对比集成到安卓工程时常见的四个方向如下方案技术形态适合人群集成难度特点llama.cppC/C 推理引擎支持 Android NDK 编译需要底层掌控、追求速度和可移植性的团队较高模型格式为 GGUF跨平台能力强社区活跃MLC LLM基于 TVM 的编译式推理方案希望一套代码覆盖 Android/iOS/Web 的团队高通过编译优化算子支持多平台部署MediaPipe LLM InferenceGoogle 提供的端侧 LLM 推理 API已经使用 MediaPipe 的安卓开发者中等封装程度高API 简洁但可调参数有限Ollama 远程服务 安卓客户端服务端部署 Ollama手机通过 REST API 调用需要在手机端快速接入大模型能力的团队低手机只做请求展示推理压力和模型空间都在服务端从社区热度和对开发者控制力来看llama.cpp 是目前安卓本地推理绕不开的基础方案。很多商业化的安卓端 AI 应用底层推理引擎要么直接使用 llama.cpp要么是从它派生出来的分支。2.2 选型判断步骤选型不要只看“哪个框架火”建议按以下顺序判断模型规模如果必须跑 7B 以上模型优先考虑远程服务或高端设备上的混合方案。部署形态产品要求完全离线就选本地推理允许联网则远程调用更简单。开发团队团队熟悉 C 和 NDK可以选 llama.cpp团队以 Java/Kotlin 为主先考虑 MediaPipe 这类封装更完整的 SDK。跨端需求如果同时要支持 iOS、WebMLC LLM 或 llama.cpp 的跨平台能力更有价值。性能验证同一模型在真实设备上跑一分钟记录 token/s 和内存占用再决定。选型的关键判断是手机本地推理的意义在于离线、隐私和低延迟如果不依赖这些特性远程调用总是更容易维护。2.3 开发环境准备SDK、NDK、CMake 与模型文件无论选择哪种本地方案都要先确认安卓开发环境。推荐环境如下实际版本以你安装的为准工具建议版本用途Android Studio最新稳定版创建和管理安卓工程Android SDKAPI 26 或以上兼容更多机型Android NDKr25 或 r26编译 C/C 推理引擎CMake3.22 或以上配置 native 编译Gradle与 Android Studio 匹配打包构建模型文件GGUF 格式的量化模型实际推理使用注意不要等到编译报错才去查 NDK 版本。llama.cpp 这类项目对 NDK 和 CMake 版本有要求先用sdkmanager装好再导入工程能省掉大量时间。模型文件方面国内下载官方模型有时较慢。建议通过 Ollama 或 Hugging Face 的镜像站提前在 PC 上下载好 GGUF 文件再用 adb 推到手机存储中避免在手机上反复下载大文件。3. 以 llama.cpp 为主线跑通安卓端最小推理流程下面用一个最小示例说明集成思路。示例中的代码只用于展示整体链路实际工程需要根据你的包名、目录结构和依赖版本调整。3.1 准备 GGUF 模型并完成量化llama.cpp 使用 GGUF 格式的模型文件。如果手头是 Hugging Face 上的原始权重需要先转换为 GGUF再进行量化。这一步通常在 PC 上完成。# 下载 llama.cpp 源码 git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp # 编译转换和量化工具 mkdir build cd build cmake .. cmake --build . --config Release -j # 先转换模型格式这里以 Hugging Face 目录结构为例 python3 ../convert_hf_to_gguf.py /path/to/your/model \ --outfile your-model.gguf \ --outtype f16 # 再量化到 Q4_K_M文件体积和显存占用更小 ./bin/llama-quantize your-model.gguf your-model-q4_k_m.gguf q4_k_m量化精度会直接影响内存占用和生成质量。Q4_K_M 是场景比较均衡的选择适合 4B 以下模型在手机上跑。如果手机内存紧张可以继续尝试 Q4_0 或 Q3 系列但要接受回答质量下降。3.2 创建安卓工程并配置 CMake 与 NDK在 Android Studio 中新建一个包含 Native C 的工程然后把 llama.cpp 源码放到cpp目录下例如app/src/main/cpp/ ├── llama.cpp/ # llama.cpp 源码 ├── CMakeLists.txt └── native_llm.cpp # JNI 封装CMakeLists.txt 的关键配置如下cmake_minimum_required(VERSION 3.22) project(native_llm) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 仅编译运行需要的平台减小 APK 体积 set(ANDROID_ABI arm64-v8a) add_library(llama STATIC llama.cpp/ggml.c llama.cpp/ggml-alloc.c llama.cpp/ggml-backend.c llama.cpp/ggml-quants.c llama.cpp/llama.cpp llama.cpp/unicode.cpp llama.cpp/unicode-data.cpp ) add_library(native_llm SHARED native_llm.cpp ) target_include_directories(native_llm PRIVATE llama.cpp llama.cpp/include ) target_link_libraries(native_llm llama android log )这里要注意llama.cpp 的源码文件列表会随着版本变化而变化。不要照抄应该以你拉取版本的实际.cpp和.c文件为准。编译前先看一眼llama.cpp/Makefile或 CMake 配置确认需要参与编译的源文件。3.3 通过 JNI 封装推理接口JNI 层的作用是让 Kotlin 能调用 C 推理函数。下面是一个简化封装#include jni.h #include string #include llama.h extern C JNIEXPORT jlong JNICALL Java_com_example_androidllm_NativeLlm_createContext( JNIEnv *env, jobject /* this */, jstring modelPath, jint threads) { const char *path env-GetStringUTFChars(modelPath, nullptr); llama_model_params modelParams llama_model_default_params(); llama_model *model llama_load_model_from_file(path, modelParams); env-ReleaseStringUTFChars(modelPath, path); if (!model) { return 0; } llama_context_params ctxParams llama_context_default_params(); ctxParams.n_ctx 2048; ctxParams.n_threads threads; ctxParams.n_batch 512; llama_context *ctx llama_new_context_with_model(model, ctxParams); return reinterpret_castjlong(ctx); } extern C JNIEXPORT jstring JNICALL Java_com_example_androidllm_NativeLlm_generate( JNIEnv *env, jobject /* this */, jlong ctxPtr, jstring prompt) { llama_context *ctx reinterpret_castllama_context *(ctxPtr); const char *input env-GetStringUTFChars(prompt, nullptr); std::string output; // 这里做 tokenize、推理循环、解析文本伪代码只示意流程 // auto tokens llama_tokenize(ctx, input, true); // 循环调用 llama_decode并不断取 token 追加到 output env-ReleaseStringUTFChars(prompt, input); return env-NewStringUTF(output.c_str()); }这个封装省略了 tokenize、采样参数设置、停止词判断等逻辑。真实项目里建议把整个推理循环放到一个独立的 C 类里避免 JNI 函数体过于庞大。3.4 在 Kotlin 侧加载模型并发起对话Kotlin 侧通过声明external fun调用 native 方法package com.example.androidllm class NativeLlm { companion object { init { System.loadLibrary(native_llm) } external fun createContext(modelPath: String, threads: Int): Long external fun generate(contextPtr: Long, prompt: String): String } }Activity 或 ViewModel 中的调用示例val modelPath ${filesDir}/models/qwen2.5-1.5b-instruct-q4_k_m.gguf val ctx NativeLlm.createContext(modelPath, 4) val result NativeLlm.generate(ctx, 用一句话介绍杭州) runOnUiThread { textView.text result }这里有几个易错点createContext返回的指针需要作为 Long 保存并在不再使用时调用专门的释放函数不要让generate在 UI 线程执行否则会卡住界面模型加载耗时长首次打开 App 时要做好 loading 状态。3.5 验证推理结果与性能记录跑通后在真机上验证以下几点模型能正常加载不闪退。中文输出没有乱码。连续生成 20 个 token 左右界面不长时间无响应。在终端中通过 logcat 观察是否有 native 层异常。adb logcat --pid$(adb shell pidof com.example.androidllm) -v time同时可以用下面命令查看进程真实内存占用adb shell dumpsys meminfo com.example.androidllm记录几个关键数字加载耗时、首 token 延迟、平均 token/s、最大内存占用。不同机型差异很大不要拿网上看到的数字直接对标。4. 推理参数与性能观测为什么同样模型体验差很多4.1 关键参数及其影响同样是 GGUF 模型在手机上的体验差异可能来自推理参数配置。常用参数如下参数含义常见值调大影响调小影响n_ctx上下文窗口长度2048内存占用增大可处理更长对话超过长度后历史被截断n_threads推理线程数4 或 6多核 CPU 利用率更高但发热也更快速度下降发热降低n_batch单次批量处理的 token 数512提示词处理更快内存占用略增提示词处理变慢temperature采样温度0.7输出更随机输出更确定top_p核采样阈值0.9候选范围更大候选范围更小线程数并不是越大越好。手机是大小核架构如果线程数超过性能核数量反而会增加调度开销而且满负荷推理会让手机迅速发热降频。4.2 观测指标token/s、内存、温度、卡顿性能验证不能只看“能不能输出”。建议记录四个指标token/s每秒生成 token 数直接影响用户等待体验。首 token 延迟从用户点击发送到屏幕上出现第一个字的时间。对话体验对这项指标比平均速度更敏感。峰值内存推理过程中dumpsys meminfo显示的进程内存防止多任务场景下被系统杀死。设备温度连续推理 5 分钟后手机后盖是否明显发烫是否触发降频。如果在真机上发现速度越来越慢通常不是框架问题而是散热和降频导致的。4.3 参数调优顺序在手机上做推理调优建议按这个顺序先确定模型量化和大小确保能稳定加载。再调 n_threads以实测 token/s 为准。然后调 n_batch观察长文本提示词的处理时间。最后调采样参数优化回答质量和多样性。每调整一个参数都用相同 prompt 和相同模型重新测一次避免把模型内容差异误判成框架性能问题。5. 安卓 LLM 实践中的高频坑与排查链路5.1 模型路径异常找不到文件、加载失败现象App 启动后提示模型加载失败或者 JNI 层返回 0。可能原因模型文件没有放到应用私有目录。文件名大小写不一致。sd 卡或外部存储没有读取权限。模型文件损坏或下载不完整。检查方式adb shell run-as com.example.androidllm ls files/models/处理建议统一把模型放在filesDir/models下加载前先检查文件大小是否和下载时一致最好在模型文件旁保存一份 SHA-256 校验值。5.2 native 闪退内存不足与不支持指令集现象加载模型后 App 直接退出logcat 中出现Fatal signal 6或SIGSEGV。可能原因abiFilters配置了x86_64或armeabi-v7a但模型推理库只适合arm64-v8a。模型体积过大超出设备可用内存。JNI 中指针被提前释放导致野指针。设备 CPU 不支持某些指令集扩展。检查方式先看崩溃日志中的 signal 类型再用adb shell getprop ro.product.cpu.abilist确认设备架构。处理建议只保留arm64-v8a构建用 1B 量化模型先验证链路JNI 层对指针回归测试不在生成完成前销毁 context。5.3 NDK、CMake 和 Gradle 版本不匹配现象编译时报Unsupported option --android或CMAKE_ANDROID_NDK相关错误。常见原因Gradle、AGP、NDK、CMake 四者版本不匹配或 NDK 路径包含中文和空格。处理建议使用 Android Studio 自带的 SDK Manager 安装 NDK r25 或 r26。在local.properties中显式配置ndk.dir。不要复制网上的 AGP 版本使用 Android Studio 项目模板生成的版本。注意llama.cpp 上游代码更新很快如果你的编译错误信息是某个源码文件找不到先检查是否只拷贝了部分源码目录常见的像是缺少unicode-data.cpp。5.4 输出乱码、重复或终止符不生效现象中文输出变成乱码或者模型一直生成不停不下来。可能原因没有正确解码 UTF-8 字节。采样参数没配置|endoftext|等停止词。上下文窗口耗尽后模型进入退化循环。检查方式在 JNI 层打印原始字节日志对比 UI 层编码。处理建议使用llama_token_to_piece时注意多字节字符边界不能按单字节拼接设置llama_sampler的 stop words对长对话做历史裁剪。5.5 连接 Ollama 服务超时与镜像下载问题如果你走的是“安卓 App 连接 Ollama 服务”的路线常见问题是请求超时。现象App 配置了 Ollama 服务地址但请求一直超时或返回connection refused。排查顺序确认手机和 Ollama 服务端在同一网络且服务端监听地址不是127.0.0.1。确认 Ollama 服务端口11434在防火墙中放行。用手机浏览器直接访问http://服务端IP:11434看是否能返回响应。如果是公网部署还要确认域名解析和 HTTPS 证书链完整。模型下载慢的问题主要是模型文件体积大、官方源网络不稳定。建议在 PC 上提前下载 GGUF 文件再通过 adb 推送。如果使用 Ollama 拉取镜像可以配置国内合规镜像地址具体以官方文档为准。6. 从 Demo 到可用产品工程化建议6.1 学习环境与生产环境的差距学习环境里Demo 能跑通就结束了。生产环境还要考虑模型文件升级用户手机上旧模型如何替换。崩溃监控native crash 需要接入 breakpad 等工具收集符号信息。隐私合规模型输入可能包含用户数据是否允许上传日志。进程生命周期低内存时系统可能回收进程推理状态需要恢复。电量策略推理是高功耗操作需要在前台或前台服务中执行。6.2 模型资源管理下载、校验、缓存与版本不要把模型直接打包进 APK否则 APK 体积会急剧膨胀。推荐做法首次启动时从服务器或对象存储下载模型。下载完成后校验 SHA-256。采用“下载到临时文件再改名”的方式防止下载中断导致半文件被加载。App 升级时保留模型目录避免重复下载。val tempFile File(filesDir, models/tmp_qwen.gguf) val targetFile File(filesDir, models/qwen.gguf) // 下载完成后校验 sha256 if (tempFile.exists() tempFile.length() 0) { tempFile.renameTo(targetFile) }6.3 推理线程、前台服务与 UI 生命周期推理算法绝对不能放到 UI 线程。建议用HandlerThread或协程的Dispatchers.IO执行。遇到耗时的长对话需要把推理放到前台服务并给用户显示进度通知否则 App 退到后台很容易被系统杀掉。释放资源时要小心不要在推理循环中随意释放 context。可以设计一个状态机标记IDLE、LOADING、GENERATING、READY、RELEASED释放操作只在IDLE或RELEASED状态下执行。6.4 接入 Ollama 服务端的混合架构如果最终产品希望兼顾本地和云端可以采用混合架构请求类型处理方式简单任务、离线场景、隐私敏感数据本地 llama.cpp 推理复杂推理、长文档、代码生成请求服务端 Ollama 或云端大模型服务端不可用自动降级到本地小模型这种架构的难点在于如何判断请求适合本地还是云端。常见做法是设置一个“简洁模式”和“深度模式”由用户手动选择或者用关键词、问题长度、任务类型做简单路由。6.5 发布前检查清单发布前至少检查以下项目每一项都直接关系到线上体验检查项验收标准模型加载断网环境下能成功加载本地模型权限不需要不合理的存储、定位权限内存主流中端机运行 10 分钟不因内存被杀电量连续推理 5 分钟耗电量可接受无明显发热崩溃覆盖加载失败、生成中途退出、进程杀死恢复网络策略远程服务超时有明确文案和重试机制合规用户协议说明模型能力边界和数据处理方式版本更新模型文件版本和 App 版本能独立维护7. 结论并没有“最强框架”只有最匹配的场景安卓端大模型框架的核心不是“谁更火”而是你能否在手机的内存、算力、电量和网络约束下找到一个可维护的部署方式。Ollama 在桌面端和服务端是好工具但安卓端本地推理的主力仍是 llama.cpp、MLC LLM 这类底层推理引擎。对大多数开发者来说先通过 llama.cpp 跑通一个 GGUF 模型的 Demo理解 JNI、NDK 和推理参数之间的关系比纠结“最强框架”更有价值。下一步可以沿着三条线继续深入一是研究量化精度对模型回答质量的影响二是在真机上做不同模型的性能压测建立自己的设备性能基线三是尝试接入 NPU 的 SDK逐渐把部分算子从 CPU 迁移到 NPU 上。真正能提升产品体验的往往不是换一个框架而是把模型、量化、调度和交互细节打磨到位。