1. 为什么要在鸿蒙端侧跑大模型

去年年底接手一个鸿蒙应用项目，需求方希望在设备本地完成文本摘要和意图识别，数据不出端。这个需求放在两年前，第一反应肯定是"调云端接口就完了"，但现在情况变了——HarmonyOS NEXT 的端侧算力、ArkTS 的并发能力、加上开源大模型量化技术的成熟，让端侧推理从"能跑"变成了"值得跑"。

先说清楚这件事的定位。端侧大模型不是要把云端的千亿参数模型塞进手机，那不现实。它解决的是三类具体问题：一是隐私敏感场景，比如个人笔记摘要、健康数据理解，数据不出设备是硬性合规要求；二是弱网或离线场景，地铁、电梯、工厂车间里网络不稳定，但功能不能停；三是响应延迟敏感场景，比如输入法的联想补全、语音助手的即时反馈，走云端一个来回至少几百毫秒，端侧可以压到几十毫秒。

适合读这篇的人有三类：正在做 HarmonyOS NEXT 应用、需要集成 AI 能力的开发者；手里有开源模型、想往端侧迁移的算法同学；以及在做技术选型、需要判断"端侧到底能不能扛"的架构师。我会把整个过程中做的 5 个关键工程决策拆开讲，包括当时纠结了什么、最后怎么选的、踩了哪些坑。这些决策没有标准答案，但每个都有明确的取舍逻辑，你可以对照自己的场景套用。

需要提前说明的是，端侧大模型在鸿蒙上目前还属于"能落地但需要精细调优"的阶段，不是调个 API 就完事。下面所有内容基于 HarmonyOS NEXT API 12 及以上版本、ArkTS 语言、以及实际项目中的验证结果，涉及参数的地方我会给出计算过程，涉及操作的地方我会说明意图，方便你复现和调整。

2. 决策一：模型选型——参数量、量化与任务匹配的三角平衡

2.1 先明确任务边界，再谈模型大小

很多人一上来就问"鸿蒙上能跑多大的模型"，这个问题问反了。应该先问"我的任务需要多大的模型"。端侧大模型的任务大致分四档：

这个表格是我在实际项目中反复验证后总结的。关键逻辑是：参数量每翻一倍，推理延迟大约增加 1.8-2.2 倍，内存占用线性增长。而端侧设备的可用内存（扣除系统和其他应用）通常在 2GB-4GB 之间，7B 模型量化到 4bit 后约 3.5GB，已经逼近上限，留给 KV Cache 和运行时开销的空间非常紧张。

我当时的任务是笔记摘要加意图分类，属于第三档，最终选了 3B 级别的模型。为什么不上 7B？因为实测下来 7B 在目标设备上首 token 延迟超过 2 秒，用户体验不可接受。为什么不下 1B？因为 1B 模型在摘要任务上的输出质量明显下降，会出现事实性错误和逻辑断裂。3B 是质量和速度的平衡点。

2.2 量化方案的选择逻辑

量化是端侧部署的必修课。原始 FP16 模型体积是参数量的 2 倍（3B 模型约 6GB），根本放不下。量化到 4bit 后体积降到约 1.8GB，8bit 约 3GB。但量化不是免费的午餐，精度损失是必然的。

常见的量化方案有几种，我在项目里对比过：

• INT8 量化：精度损失最小，通常掉点 1%-2%，但体积压缩只有 2 倍，3B 模型仍有 3GB，内存压力大。
• INT4 量化：体积压缩 4 倍，精度损失 3%-5%，是端侧的主流选择。但要注意分组大小（group size），group size 越小精度越高、体积略大，常用 128 或 64。
• 混合量化：对敏感层（如 attention 的 QKV 投影）用 INT8，其余用 INT4，兼顾精度和体积。实现复杂度高，适合对精度要求苛刻的场景。

我最终选了 INT4、group size 128 的方案。理由是：3B 模型 INT4 后约 1.8GB，加上 KV Cache（按 2048 上下文算约 200MB）和运行时开销，总占用控制在 2.5GB 以内，目标设备能扛住。精度方面，在自建的 500 条测试集上，INT4 相比 FP16 的 ROUGE 分数下降约 4%，但在可接受范围内。

注意：量化后的模型必须重新做一轮任务评测，不能直接拿原始模型的评测结果。我见过有人量化完直接上线，结果模型在特定输入上开始"胡言乱语"，排查半天才发现是量化把某些层的权重压到了异常值。

2.3 模型格式与推理框架的绑定关系

选模型时还要考虑格式。开源模型常见的有 PyTorch 的 .pt/.pth、SafeTensors、GGUF、ONNX 等。鸿蒙端侧目前没有官方的统一推理框架，实际项目中通常走两条路：

一条是把模型转成 ONNX，再用支持 ONNX Runtime 的端侧方案（需要确认目标设备是否有对应的 NNAPI 或硬件加速后端）。另一条是转成 GGUF 格式，配合轻量级推理引擎。两条路各有优劣：ONNX 生态成熟、算子覆盖广，但运行时体积较大；GGUF 专为端侧优化、内存映射加载快，但算子支持取决于具体引擎。

我选的是 ONNX 路线，原因是项目里还需要做模型的部分层替换（后面会讲），ONNX 的图结构更容易操作。如果你的场景不需要改图，GGUF 的加载速度优势更明显。

3. 决策二：推理引擎的接入方式——Native 还是 ArkTS

3.1 两种接入路径的本质区别

这是鸿蒙端侧开发特有的决策点。HarmonyOS NEXT 的应用层用 ArkTS 写，但推理引擎通常是 C/C++ 实现的。怎么把两者接起来，有两条路：

路径 A：Native 层集成。把推理引擎编译成 .so 动态库，通过 NAPI（Native API）暴露接口给 ArkTS 调用。推理全程在 Native 层完成，ArkTS 只负责传参和收结果。

路径 B：纯 ArkTS 实现。用 ArkTS 重写推理逻辑，或者找纯 ArkTS 的推理库。这条路理论上可行，但实际中很少走通，因为 ArkTS 的数值计算能力和内存控制能力远不如 C++，性能会差一个数量级。

我选的是路径 A。但这里有个细节：NAPI 的调用是有开销的，如果每次推理都跨语言调用，频繁的小推理会有明显损耗。我的做法是把整个推理会话（session）的生命周期管理放在 Native 层，ArkTS 只调用"初始化""推理""释放"三个接口，中间过程不跨语言。

3.2 NAPI 接口设计的几个关键点

设计 NAPI 接口时，我踩过几个坑，这里直接给结论：

第一，输入输出用 ArrayBuffer 而不是 Array。ArkTS 的 number 数组传到 Native 层需要逐个转换，开销巨大。用 ArrayBuffer 传二进制数据，Native 层直接拿指针，零拷贝。

第二，异步接口必须用 napi_create_async_work。推理是耗时操作，如果在主线程同步调用，UI 会卡死。鸿蒙的 NAPI 提供了异步工作队列，把推理任务丢到工作线程，完成后回调 ArkTS。

第三，内存管理要明确所有权。Native 层分配的模型内存，释放时机必须由 Native 层控制，不能让 ArkTS 的 GC 介入。我在接口里显式提供了release()方法，在页面销毁时调用。

// ArkTS 侧调用示例 import nativeInfer from 'libnative_infer.so'; // 初始化，传入模型路径和配置 const sessionId = nativeInfer.init(modelPath, { threads: 4, contextSize: 2048, useGPU: false }); // 异步推理 nativeInfer.inferAsync(sessionId, inputBuffer, (result: ArrayBuffer) => { // 处理结果 const text = decodeResult(result); console.info('推理结果:', text); }); // 页面销毁时释放 aboutToDisappear() { nativeInfer.release(this.sessionId); }

3.3 线程模型的取舍

推理线程数不是越多越好。我实测过 2、4、6、8 线程的情况：4 线程时吞吐最高，6 线程开始出现线程调度开销超过并行收益，8 线程反而比 4 线程慢 15%。原因是移动端 CPU 通常是大核加小核的异构架构，小核参与计算会拖后腿。

我的建议是：线程数设为大核数量。比如某设备是 1+3+4 的架构（1 超大核 + 3 大核 + 4 小核），线程数设 4 比较合适。如果拿不准，就设 4，这是移动端的经验值。

另外，推理线程的优先级要调高。鸿蒙的 Native 层可以通过pthread_setschedparam设置线程优先级，把推理线程设为较高优先级，避免被其他任务抢占导致延迟抖动。

4. 决策三：内存管理策略——端侧最稀缺的资源

4.1 内存占用的构成拆解

端侧推理的内存占用分四块，必须逐块算清楚：

模型权重：量化后的模型文件大小，加载后基本等于文件大小（如果做了内存映射则更少）。3B INT4 约 1.8GB。

KV Cache：这是容易被低估的部分。KV Cache 大小 = 2 × 层数 × 头数 × 头维度 × 上下文长度 × 数据类型字节数。以 3B 模型、32 层、32 头、头维度 128、上下文 2048、FP16 为例：2 × 32 × 32 × 128 × 2048 × 2 字节 ≈ 1.07GB。这个数字很吓人，实际中会用分组查询注意力（GQA）来降低，但仍然是几百 MB 级别。

运行时开销：推理引擎的中间张量、算子工作区等，通常 100MB-300MB。

应用其他部分：ArkTS 运行时、UI 渲染、业务逻辑等，视应用复杂度而定。

四块加起来，3B 模型的实际峰值内存可能到 3GB 以上。这就是为什么我说 7B 模型在移动端很吃力——光 KV Cache 就可能超过 2GB。

4.2 降低内存占用的四个手段

针对上面的构成，我用了四个手段来压内存：

手段一：内存映射加载模型。不要把整个模型文件读进堆内存，用mmap映射到虚拟地址空间，让操作系统按需换页。这样模型权重不占常驻内存，只在访问到时才加载。代价是首次推理会慢一些（触发缺页中断），但后续推理速度正常。

手段二：限制上下文长度。上下文从 4096 降到 2048，KV Cache 直接减半。对于摘要、分类这类任务，2048 通常够用。如果确实需要长上下文，考虑滑动窗口或分段处理。

手段三：KV Cache 量化。把 KV Cache 从 FP16 量化到 INT8，内存再减半。精度损失很小（通常 1% 以内），性价比很高。

手段四：及时释放。推理完成后立即释放中间张量，不要等 GC。Native 层手动管理内存，ArkTS 层在页面不可见时调用释放接口。

实操心得：鸿蒙系统对单个应用的内存有上限，超过会被系统杀掉。我在开发阶段用hidumper命令监控内存，命令是hidumper --mem <pid>，能看到详细的内存分布。建议在推理前后各打一次，确认峰值没有超标。

4.3 内存与并发的冲突处理

如果应用需要同时处理多个推理请求（比如用户快速连续输入），不能简单地为每个请求开一个推理会话，那样内存会爆炸。我的做法是维护一个推理队列，串行处理请求，同时限制队列长度（比如最多 3 个待处理）。超出队列长度的请求直接返回"繁忙"状态，让上层决定是等待还是降级。

这个策略的代价是吞吐降低，但端侧场景下，用户通常不会同时发起大量推理请求，串行处理的实际体验反而更稳定。如果确实需要并发，可以考虑多会话共享模型权重、各自维护 KV Cache 的方案，但实现复杂度高，我建议先用串行方案验证需求。

5. 决策四：性能优化——从"能跑"到"好用"的关键

5.1 首 token 延迟与生成速度的分离优化

端侧推理的性能指标有两个：首 token 延迟（TTFT）和生成速度（tokens/s）。这两个指标的优化手段不同，必须分开看。

首 token 延迟主要受模型加载、prompt 处理影响。优化手段包括：预热（应用启动时先跑一次空推理，把模型加载到内存）、prompt 缓存（相同前缀的 prompt 复用 KV Cache）、以及减少 prompt 长度。

生成速度主要受计算量和内存带宽影响。优化手段包括：算子融合（把多个小算子合并成一个大算子，减少内存访问）、量化（INT4 比 FP16 快约 2 倍）、以及硬件加速（如果设备支持 NPU，把部分算子卸载到 NPU）。

我在项目里的实测数据：3B INT4 模型，在目标设备上首 token 延迟约 800ms（预热后），生成速度约 12 tokens/s。这个速度对于摘要任务（输出 100-200 token）意味着 8-16 秒的等待，体验一般。后来通过算子融合和 KV Cache 量化，生成速度提到 18 tokens/s，等待时间压到 6-11 秒，勉强可接受。

5.2 预热策略的设计

预热是提升首 token 延迟最有效的手段，但要做对。我的预热方案是：应用启动后，在后台线程加载模型并跑一次短推理（输入"你好"，输出限制 1 个 token）。这样模型权重被加载到内存，算子被初始化，后续真实请求的首 token 延迟能降低 60% 以上。

预热的时机很关键。太早（应用启动时立即预热）会拖慢启动速度，太晚（用户触发推理时才预热）就失去了意义。我的做法是在首页渲染完成后、用户还在浏览时，延迟 2 秒启动预热。这样既不阻塞启动，又能在用户真正使用前完成。

注意：预热会占用内存和 CPU，如果设备本身内存紧张，预热可能导致系统杀后台。建议在预热前检查设备内存状态，低于阈值时跳过预热，改为懒加载。

5.3 降级策略的必要性

端侧推理不可能保证 100% 成功。内存不足、设备过热、系统调度都会导致推理失败或超时。必须有降级策略：

• 超时降级：推理超过设定时间（比如 10 秒）未完成，中断并返回简化结果或提示用户。
• 内存降级：检测到内存不足时，切换到更小的模型或更短的上下文。
• 功能降级：端侧推理失败时，如果网络可用，静默切换到云端接口（前提是业务允许）。

我在项目里实现了超时降级和功能降级。超时阈值设为 15 秒，超过就中断。功能降级方面，因为业务要求数据不出端，所以没有走云端，而是返回"当前无法处理，请稍后重试"的提示。如果你的业务允许云端兜底，降级策略会更灵活。

6. 决策五：工程化与可维护性——别让 Demo 变成技术债

6.1 模型版本管理与热更新

端侧模型不能像云端那样随时更新，但也不能永远不更新。我的方案是：模型文件放在应用的资源目录，随应用版本发布。同时预留一个"模型下载"通道，允许从服务端下载新版本模型到应用沙箱，运行时优先加载沙箱中的模型。

这个方案的关键是版本管理。每个模型文件带一个版本号，应用启动时对比本地版本和服务端版本，不一致时触发下载。下载完成后校验文件完整性（MD5 或 SHA256），校验通过才替换。

// 模型版本检查与下载的简化逻辑 async function checkModelUpdate() { const localVersion = await getLocalModelVersion(); const remoteInfo = await fetchModelInfo(); if (remoteInfo.version !== localVersion) { const modelPath = await downloadModel(remoteInfo.url); const valid = await verifyChecksum(modelPath, remoteInfo.checksum); if (valid) { await switchModel(modelPath); } } }

实操心得：模型文件通常几百 MB 到几 GB，下载耗时长。建议用断点续传，并且在 Wi-Fi 环境下才触发下载。另外，下载过程中要保证旧模型可用，不能出现"下载到一半旧模型被删了"的情况。

6.2 推理服务的封装与测试

不要把推理逻辑散落在各个页面里，封装成独立的服务模块。我的做法是建一个InferenceService类，对外暴露init、infer、release三个方法，内部管理会话生命周期、队列、降级逻辑。页面只依赖这个服务，不直接接触 Native 接口。

测试方面，端侧推理的测试比云端麻烦，因为依赖具体设备。我的做法是：在开发机上用模拟器跑功能测试（验证接口正确性），在真机上跑性能测试（验证延迟和内存）。性能测试要覆盖不同设备档次，低端机上的表现才是真实下限。

6.3 日志与监控

端侧推理出问题时，排查比云端困难，因为没有服务端日志。必须在应用内埋点，记录每次推理的输入长度、输出长度、耗时、内存占用、是否降级等信息。这些日志在开发阶段输出到控制台，在线上可以上报到服务端（注意脱敏，不要上传用户输入内容）。

我埋的关键指标有：TTFT、生成速度、峰值内存、降级触发次数。这些指标能覆盖 90% 的问题场景。比如 TTFT 突然升高，可能是内存不足导致频繁换页；降级次数增多，可能是模型和设备不匹配。

7. 常见问题与排查技巧实录

7.1 推理结果异常的问题排查

问题一：输出乱码或重复。最常见的原因是量化精度损失过大，或者 prompt 模板与模型训练时不一致。排查方法：先用 FP16 模型跑同样的输入，如果正常，说明是量化问题，尝试提高量化精度或调整 group size；如果 FP16 也异常，检查 prompt 模板。

问题二：推理速度突然变慢。可能是设备过热触发降频，或者内存不足触发换页。排查方法：用hidumper看内存，用系统 API 看 CPU 频率。如果是过热，考虑降低推理频率或增加散热；如果是内存，参考第 4 节的优化手段。

问题三：应用崩溃。端侧推理崩溃通常是内存越界或空指针。排查方法：在 Native 层加断言，用hilog输出关键日志。鸿蒙的崩溃日志在/data/log/faultlog/目录下，能看到 Native 层的调用栈。

7.2 常见问题速查表

7.3 几个容易忽略的坑

坑一：忽略了模型加载时间。模型加载（从磁盘读到内存）本身就要几秒，如果每次推理都重新加载，体验极差。必须做会话复用，加载一次，多次推理。

坑二：prompt 拼接引入了额外开销。如果每次推理都重新拼接 prompt 字符串，字符串操作的开销可能超过推理本身。建议预编译 prompt 模板，只替换变量部分。

坑三：没有处理特殊字符。用户输入可能包含 emoji、控制字符等，直接传给模型可能导致异常。必须在输入前做清洗和转义。

坑四：忽略了设备差异。同一份代码在不同设备上表现可能差几倍。必须做设备分级，低端设备用更小的模型或更保守的配置。

8. 端侧大模型在鸿蒙上的后续演进方向

从项目落地到现在，我持续在关注几个方向。一是鸿蒙系统本身对 AI 能力的支持在加强，后续可能会有更原生的推理接口，减少自己集成引擎的工作量。二是端侧硬件在进化，NPU 算力逐年提升，现在需要 INT4 才能跑的模型，明年可能 INT8 就能跑，精度和速度都会改善。三是模型压缩技术在进步，稀疏化、蒸馏等手段能让小模型的质量逼近大模型，端侧能承载的任务范围会扩大。

如果你现在要启动类似的项目，我的建议是先用最小可行方案验证需求——选一个 1B 左右的模型，跑通端到端流程，确认端侧推理在你的场景下确实有价值，再逐步优化模型大小和性能。不要一上来就追求 7B 模型加全套优化，那样很容易在工程细节里迷失，忘了最初要解决什么问题。

我在实际项目里最大的体会是：端侧大模型的工程决策，本质上是在质量、速度、内存三个约束下找平衡点，而这个平衡点因设备、因任务、因用户预期而异。没有万能方案，只有适合当前场景的方案。把每个决策的取舍逻辑想清楚，比照搬别人的配置更重要。