高通QNN实战：在Android手机上部署LLaMA-7B全攻略

去年年底我给自己定了一个有点“疯狂”的目标让手机自己跑一个大语言模型不是那种套壳的 API 调用而是真正把模型塞进本地让它在骁龙芯片上自己推理。折腾了几个月用QNN 框架在 Android 上把LLaMA-7B完整部署了起来整个过程踩坑无数从模型量化、算子转换到 JNI 内存管理每一步都值得单独写一篇。这篇博文把我从零开始的完整路线和避坑经验整理出来适合已经被大模型冲昏头脑、想在手机上亲手跑一次推理的工程师和硬核玩家。先说结论7B 模型在手机上不是跑不动而是要用对工具链和量化手段。纯 CPU 推理不是不能用但速度基本停留在“能用但难受”的水平。而QNNQualcomm Neural Network这套高通出的端侧推理框架能把部分算子调度到 Hexagon DSP 和 HTP 上跑实测下来速度能比纯 CPU 推理快好几倍这也是它最大的价值所在。我不会只贴命令和配置每个关键步骤背后的取舍、每个我踩过的坑都会尽量讲清楚希望能让你少走几周弯路。1. 内容整体设计与思路拆解1.1 为什么非要在手机里跑 7B 模型很多人第一反应是手机上跑大模型图什么云端的 GPT 不香吗我当时的动机很简单离线、私有、零延迟这三点是云端 API 无论如何都给不了的。想象一下你在飞机上、地铁隧道里、野外徒步时想用一个智能助手——没有网络就是废的。而且从技术探索的角度看端侧大模型这个方向本身就很值得研究眼下的进展虽然算不上完善但确确实实每年都在推进。另外还有一个现实问题云端推理是要花真金白银的。按 token 计的 API 调用费用跑一笔长对话成本并不低。模型如果能落在本地推理就是免费的用户量再大也只是耗电和发热的问题。这一点对于做工具类 App、隐私敏感型产品的人来说很有吸引力。1.2 方案选型QNN 不是唯一答案但是最优解我先梳理一下目前的几条主流路线把这个选型逻辑讲透。路线一纯 CPU 推理用 llama.cpp 或其衍生方案。这个最简单一个静态库集成到 Android 工程里就行GGUF 格式的量化模型直接在 ARM CPU 上跑。实测下来 7B 模型的 Q4 量化版本在骁龙 8 Gen 2 上大概能跑到每秒 5 到 8 个 token有点慢但能用胜在稳定、好调试。我最初的 MVP 就是用这条路跑通的用来验证流程可行性非常合适。路线二GPU 加速用 OpenCL 或 Vendor 扩展。手机 GPU 的并行计算能力比 CPU 强不少尤其 FMAs融合乘加指令和 Tensor Core 之类的硬件特性对矩阵乘法非常友好。但问题是 GPU 驱动碎片化严重不同芯片厂商的 OpenCL 实现水平参差不齐为了一个推理框架去适配几十个 GPU 型号想想就头大。路线三NPU 加速用高通 QNN。QNN 是新一代的高通 AI Engine 工具链专为 Hexagon DSP 和 HTP 设计是从 Snapdragon 888 开始逐步推广的。它最大的优势是能效比极高同一任务在 NPU 上跑的功耗可能只有 GPU 的 1/3 到 1/5而手机恰恰是电池和散热的天花板限制最明显的设备。QNN 的短板是工具链还不够成熟算子支持覆盖面比 CPU/GPU 方案差不少做 LLaMA 这种大规模的 transformer 模型会遇到不少迁移问题——但这正是我写这篇避坑指南的意义所在。综合比较后我的选型是以 QNN 为主推方案CPU 推理作为后路不做 GPU 方案。方案性能能效比工具链成熟度适配成本CPUllama.cpp可用一般高低GPUOpenCL较好中等中高NPUQNN好高中低高1.3 整体流水线设计部署流程从大的层面分成三步模型准备、模型转换、端侧集成。模型准备从 Hugging Face 拉取 LLaMA-7B 原始权重用脚本做量化和格式转换。模型转换通过 QNN 的转换工具链把模型转成 QNN 的序列化格式包括算子映射、算子融合和 graph 优化。端侧集成在 Android 工程里通过 JNI 调用 QNN 的 C API加载序列化模型实现 Prompt Tokenizer、推理循环、结果采样以及内存管理和回调逻辑。这三步说起来简单实际操作的时候每一步都会冒出一堆稀奇古怪的问题接下来我按模块细讲。2. 核心细节解析与实操要点2.1 模型量化前提是顺利塞进手机内存核心是精度可控7B 模型是 70 亿参数以 FP16 存储是 70 亿 × 2 字节 14GB。手机上 12GB 运行内存的设备不少但系统、Graphic、常驻 App 会占用 5GB 到 8GB留给模型的往往只有 4GB 到 6GB。所以必须量化不量化根本跑不了。我试过两种量化路线第一种是用GPTQ做训练后量化在 GPU 上完成每一步计算都以最小化权重的均方误差为目标。这个方案效果很好Q4 量化后模型的困惑度退化很小但跑起来要的时间很长——7B 模型在单张 4090 上耗时 4 到 6 小时。第二种是llama.cpp 的 GGUF 动态量化在模型文件格式层面做的事工具链相对简单一条命令就能完成且可以在 CPU 上跑。实测下来生成质量损失很小对于 7B 这个量级4-bit 量化后效果依然可圈可点。考虑到我要通过 QNN 部署GGUF 格式不是 QNN 原生支持的输入需要再转一步 ONNX。所以我的实际路径是HuggingFace 原始权重 → 转 ONNX → 量化用 ONNX Quantizer 或 QNN 自带的量化器→ QNN 序列化格式。从最后产物的角度来说QNN 也支持直接消费特定格式的 ONNX比如含 QDQ 节点的量化 ONNX所以推荐的做法是# 从 HuggingFace 下载 LLaMA-7B 并转为 ONNX python convert_llama_onnx.py --model-name meta-llama/Llama-7b-hf --output llama7b-fp16.onnx # 使用 ONNX Runtime 的量化工具做动态量化或 QDQ 量化 python quantize_onnx.py --input llama7b-fp16.onnx --output llama7b-int8.onnx --quantize_type qdq这里有个很关键的知识点对于语言模型来说权重量化比激活量化更安全因为激活在推理时方差变化很大用固定的量化范围切容易产生大的信息损失。而权重分布相对稳定8-bit 差不多无损4-bit 也只是轻微损失。所以在 QNN 的量化配置里我会设置执行计划为“只量化权重保留激活为 FP16”在保证精度的同时把模型压缩到 4GB 以内。2.2 QNN 转换工具链与算子适配这层坑最深QNN SDK 里面跟模型转换相关的核心工具是qnn-onnx-converter它负责将 ONNX 图转换为 QNN 的图表示。因为 LLaMA-7B 的计算图中包含很多种类型的算子MatMul、RMSNorm、Rotary Embedding、GELU、Softmax、Split、Concat 等等QNN 的算子支持图谱里有一部分的算子原生支持不佳。以我踩过的最深坑为例RMSNorm 和 ScaledDotProductAttention 在 QNN 的原生算子库里支持不够完善需要手动拆解成基础算子。比如 RMSNorm 本质上就是 LayerNorm 去掉中心化操作可以拆成计算 RMS → 除法 → Scale于是我用 ONNX 不支持但 QNN 能用的小算子组合来重建它这比自己在 QNN 里注册自定义算子要省事很多。我还遇到过一个更麻烦的问题QNN 在 Transformer 算子上的量化感知转换并不像传统 CV 模型那么成熟有些算子量化后会导致输出变成 NaN 或 Inf。排查了很久发现是 Softmax 的量化参数在长序列下溢出解决方法是把 Softmax 的输入改成动态范围更大的量化设置或者干脆让它在 CPU 上进行操作再喂回 GPU/NPU。QNN 支持算子分片执行可以通过配置指定特定算子在 CPU Backend 上执行这个机制在算子兼容性不足时特别有用。2.3 Android 继承的关键JNI 内存管理是最容易翻车的地方QNN 的 C API 是基于指针的要在 Java/Kotlin 侧调用就逃不开 JNI。我的实践是把整个推理循环放在 Native 层做Java 只负责传字符串和接收结果。最容易踩的坑是内存泄漏和地址对齐问题。QNN 的 tensor buffer 要求在 Hexagon 后端上分配时对齐到 128 字节如果用普通malloc不保证对齐会导致qnn_htp_device_aligned初始化失败。正确做法是// 分配 QNN 张量内存确保对齐 const size_t alignment 128; void* aligned_buf aligned_alloc(alignment, size); if (!aligned_buf) { LOGE(Failed to allocate aligned buffer of size %zu, size); return QNN_FAIL; } qm_tensor_set_custom_data(tensor, aligned_buf);另外LLaMA-7B 的 KV Cache 是动态增长的每生成一个 token 就会在显存/内存中追加数据如果没有预留足够缓存长文本生成到一半就会因 OOM 被杀进程。规避方式是提前按最大对话长度设定 KV Cache 池比如 max_length2048然后在推理之前即完成把所有缓存空间都分配完毕不要在推理过程中动态分配内存不然一旦系统内存碎片化严重直接白屏。3. 实操过程与核心环节实现3.1 环境准备工具链版本对齐决定一半成败在动手之前先把环境表述清楚后面好多坑都跟版本相关。我的主力开发机器是 LinuxAndroid 工程放在 Android Studio 里编译。需要用到的组件及版本如下高通 QNN SDK2.19 / 2.22 均可注意不同版本之间算子支持有差异对标特定 CPU/NPU 型号时建议用高版本Android Studio2024.1 或更新版本Android NDKr26 或以上版本低于 r25 容易遇到 glibc 兼容问题CMake3.22.1测试设备骁龙 8 Gen 2 或 8 Gen 3 手机运行内存至少 12GB如果你用的是低版本 SDK 且手头设备是骁龙 8 Gen 3注意可能缺少对于 8 Gen 3 特殊的算子覆盖并且 NPU 架构不同。尽可能用厂商配套的 QNN 版本不要强行通用化。3.2 模型转换实操亲测可跑的命令序列第一步把 GGUF 或原始 HF 权重转换为 ONNX。我用的是自定义脚本核心思路是拿到开源的转换工具后把 RMSNorm 算子做了替换。需要快速验证时可以用下面的精简命令# 加载原始模型并导出 ONNX这是我实测能跑通的组合 python convert_llama_onnx.py \ --model-name meta-llama/Llama-2-7b-chat-hf \ --output ./llama7b-fp16.onnx \ --precision fp16 \ --skip-rms-norm-patch # 如果你想要自己改造 RMSNorm 就加这个开关第二步执行量化python -m onnxruntime.quantization.quantize \ --input ./llama7b-fp16.onnx \ --output ./llama7b-int8-qdq.onnx \ --quantize-mode dynamic \ --quantize-precision int8 \ --weight-quantize true \ --activation-quantize false第三步调用 qnn-onnx-converter# 在 QNN SDK 目录下 python ${QNN_SDK_ROOT}/lib/python/qnn/onnx/qnn_onnx_converter.py \ -i llama7b-int8-qdq.onnx \ -o llama7b.qnn \ --backend htp \ --htp-arch v73 \ --device-family gen2 \ --quantization-overrides ./qnn_quant_params.json这行命令的--htp-arch v73和--device-family gen2都是针对骁龙 8 Gen 2 的不同骁龙平台需要改参数。我在最开始没注意这个参数转换出来在目标手机上加载报错白折腾了两天。3.3 Android 侧代码结构工程搭建与关键代码我的工程目录结构大致如下app/ ├── src/main/ │ ├── java/com/example/llmonandroid/ │ │ ├── MainActivity.kt │ │ ├── InferenceEngine.kt # 封装 Native 接口 │ │ └── ChatViewModel.kt │ ├── cpp/ │ │ ├── qnn_inference.cpp │ │ ├── tokenizer.cpp │ │ ├── qnn_config.h │ │ └── CMakeLists.txt │ └── assets/ │ ├── llama7b.qnn # 转换后的模型 │ └── tokenizer.json关键的一层是qnn_inference.cpp它负责加载 QNN context创建 graph绑定 tensor循环推理。简化后的示例代码#include QnnInterface.h #include QnnContext.h #include QnnGraph.h #include QnnTensor.h static Qnn_ContextHandle_t context nullptr; static Qnn_GraphHandle_t graph nullptr; int load_model(const char* model_path) { // 1. 初始化 QNN 后端 auto backend QnnBackend::fromLibrary(libQnnHtp.so); Qnn_ContextConfig_t ctx_config QNN_CONTEXT_CONFIG_DEFAULT; context backend.createContext(ctx_config); // 2. 加载序列化图 auto binary readFile(model_path); graph context.createGraph(binary.data(), binary.size()); // 3. 绑定输入输出 tensor注意对齐 input_tensor graph.getInputTensor(0); output_tensor graph.getOutputTensor(0); return 0; } int run_inference(int* input_ids, int seq_len) { // 把 input_ids 拷贝到对齐内存中 memcpy(input_tensor.address, input_ids, seq_len * sizeof(int)); graph-execute({input_tensor}, {output_tensor}); int token argmax(static_castfloat*(output_tensor.address), vocab_size); return token; } extern C JNIEXPORT jstring JNICALL Java_com_example_llmonandroid_InferenceEngine_generate( JNIEnv* env, jobject thiz, jstring prompt) { std::string text jstring2string(env, prompt); std::vectorint tokens tokenizer_encode(text); // prepend BOS, 添加 chat template 等操作... int next_token -1; std::vectorint prompt_tokens; for (int step 0; step max_gen_len; step) { // 拷贝当前序列到模型中执行 next_token run_inference(tokens.data(), tokens.size()); tokens.push_back(next_token); if (next_token EOS_TOKEN) break; } return env-NewStringUTF(tokenizer_decode(tokens).c_str()); }真正能跑起来时你会发现最大的瓶颈是 Graph 初始化和 Tensor 生命周期管理。QNN 的 context 初始化在 Android 上有时会出错需要让 HTP 驱动完成初始化耗时约几百毫秒此时必须做异步启动不要让 UI 线程卡住。3.4 一次完整的启动流程记录我记录了启动的关键时间以骁龙 8 Gen 2 设备为例12GB 运存模型是 Q4 量化后的 LLaMA-7B参数约为 4.4GB阶段耗时/状态说明模型文件从 app assets 拷贝到私有目录3.2 秒首次启动后续可跳过QNN Backend 初始化280 ms打开 HTP 驱动图加载与编译2.1 秒主要开销在算子调度的编译阶段第一个 token 预填充2048 token3.4 秒计算量大需要大量矩阵乘法增量生成每 token45 ms/token约 22 token/s去掉首 token 影响实测下来这个速度比纯 CPU 推理提升约 3 到 4 倍。跑长文本时手机背面会明显发热但没到烫手的地步功耗控制确实是 QNN 的强项。4. 常见问题与排查技巧实录4.1 QNN 转换阶段算子报错的快速定位法转换阶段最常见的报错是Unsupported operation或Op validation failed。我的经验是把 ONNX 模型拆分独立判定用 QNN 提供的一些工具先做摘要把模型中每个算子出现次数统计出来挨个排查哪些算子在支持列表之外。如果需要快速定位是哪个节点出问题可以在转换命令里加--debug --dump-io-specs这会把每个算子的输入输出规格打印出来如果某个算子有data_type mismatch或shape mismatch就很直观。4.2 运行时崩溃JNI 层段错误与内存问题如果跑模型时直接 SIGSEGV先检查是不是模型没加载就执行了graph-execute其次检查输入张量缓冲区的对齐。QNN 在 Hexagon 后端要求 input buffer 是aligned_alloc分配出来的不能使用普通vector.data()这是最容易犯的低级错误。还有一个经典问题logcat 中报NNAPI相关错误说无法访问 DSP。这是因为我把模型配置错误指向了 GPU 或 CPU 后端或设备驱动权限不足。解决方案是把后端换回 HTP并确保 target 是--backend htp同时检查设备型号是否支持 QNN。4.3 精度问题生成结果像“喝了假酒”如果推理结果乱码、东一句西一句大概率是量化参数不对。把量化关掉回归 FP16确认结果正常之后再一步步打开量化。如果打开量化后立即变差试用动态范围量化或者逐层量化找到精度退化的层考虑对该层跳过量化QNN 支持 per-tensor skip。另一个很隐蔽的原因是补 TokenizerLLaMA 的 tokenizer 会把换行符和 Unicode 做特殊编码终端交互时如果传参转义出错模型也会生成乱码但这跟量化无关检查原文字符流。4.4 问题速查表现象可能原因解决方向转换时 Unsupported OPQNN 算子覆盖不足手动将模型改写为更基础的算子或让对应算子跑 CPU Backend加载图时 Unexpected data format模型格式与后端架构不匹配检查--htp-arch参数是否匹配设备换用正确的 QNN SDK 版本执行时 SIGSEGV内存未对齐或访问越界使用aligned_alloc确认 KV Cache 池大小充足生成内容乱码量化精度损失调整量化策略逐层跳过量化恢复精度运行 1 分钟后变慢热降频优化推理循环减少功耗或做 token 级节能加载UI 卡死推理在 Java 线程执行将推理流程放入子线程且避免频繁回传 UI5. 性能调优与效果验证5.1 量化精度与速度的平衡展开看看在调优过程中我发现 QNN 的 INT8 量化同一模型的不同算子混跑现象很常见。部分 MatMul 算子被量化后能大幅提速但有些精度敏感的 MatMul比如 Attention 的 score 矩阵如果也跑 INT8输出质量退化严重导致对话词不达意。我最后采取的组合方案是权重层全部 int8激活敏感的 Attention score 计算保留 FP16在 QNN 配置文件中通过算子级 overrides 来实现。最终模型大小保持在 4.3GB生成质量接近 FP16 的 95% 水平速度比纯 int8 慢了约 20%但换来的是基本正常的对话体验。5.2 不同设置下的实测数据我将几个参数的实测结果整理如下用的是同一台骁龙 8 Gen 2 手机配置模型大小预填充 1024 tokens 耗时生成速度token/s支持最大文本长度FP16-ONNX14.4GB6.8s4.5说实话跑不长INT8-QDQ权重7.2GB4.1s9.2512 以内INT8-QDQ FP16 Attention4.3GB2.8s13.52048全 INT84.1GB2.1s18.72048这个表格很有参考价值如果你只是玩一玩全 INT8 跑得最快如果要当生产力工具用我建议选中间的方案在本机试过的对话质量明显更好。5.3 手机发热与续航的实际表现实测连续生成 300 个 token 时手机背面的温度从 26 度上升到 39 度左右大概是温热但不烫手的状态。相比 GPU 方案动辄飙到 44 度的体验QNN 的能效优势非常明显。如果控制生成长度并让模型进入 sleep 状态待机功耗几乎为零这也给手机端离线助手类应用提供了可能。有一个小技巧在生成完每一批 token 后调用 QNN 的 context 释放中间 tensor buffer避免内存碎片累积连续对话几百轮后仍能保持稳定。6. 扩展与一点个人体会这条路走通之后后续可以向几个方向延伸一是把量化粒度做到2-bit 或混合精度进一步压体积二是接入多模态输入让模型可以在手机本地读图片三是在图形界面上做更有感觉的 stream 输出而不是等全部生成完后一次性打印。最后再分享一个我在实际部署中总结的经验做端侧大模型一定要带着对硬件底层的敬畏心。很多人习惯了云端的“黑盒”体验但端侧模型每一处瓶颈最终都会落到内存带宽、NPU 算子调度、热功耗管理这些硬核问题上。如果你没有亲手把模型跑在一台真实手机上的经历很难理解这些约束带来的设计变化。在整个实战过程中我最大的收获并不是“跑通了”而是深刻体会到了模型、芯片、系统软件三者配合的复杂程度。如果让我给刚入门的人一个建议那就是从一个量化后的小模型比如 1.1B 或 3B开始走通流程再挑战 7B。这个顺序能让你把转换工具、JNI 交互、内存管理这些基本功练扎实而不是一上来就被 7B 的体积和复杂度搞崩溃。这篇指南到此结束希望你手里的机器也能早日跑起属于自己的本地大模型。