做鸿蒙 AI App 的这两年踩过的坑比写过的代码还多。市面上谈鸿蒙开发的文章不少可真正把“AI 能力怎么融进鸿蒙架构”讲透的没几个。这篇文章我把自己的技术架构笔记整理出来——从分层设计、核心模块拆解到落地实操和问题排查全部基于真实项目经验希望对正在做或准备做鸿蒙 AI 应用的同行有帮助。1. 鸿蒙 AI App 的整体架构设计思路1.1 为什么鸿蒙 AI App 值得单独做架构设计很多团队习惯把安卓/iOS 的 AI 应用直接“翻译”到鸿蒙上这是最大的误区。鸿蒙不是换了个壳的安卓它的分布式能力、原子化服务、统一生态底座决定了 AI 应用的架构逻辑从底层就要重新思考。拿我自己的项目举例最开始试图用 WebView 套壳把已有的 AI 对话页面直接搬过来结果发现两个致命问题——端侧模型推理的延迟完全不可控跨设备流转时 UI 状态和 AI 会话上下文根本对不齐。后来痛定思痛完全按照鸿蒙的原生架构重构才真正跑通。鸿蒙 AI App 的核心架构分层我总结为五层应用表现层ArkUI 声明式界面 状态管理AI 能力接入层大模型 API、端侧推理、Agent 编排数据服务层端云协同、分布式数据库、偏好存储系统能力层分布式软总线、原子化服务、权限安全基础运行层ArkTS 运行时、方舟编译器、元能力框架这不是为了分层而分层而是为了应对鸿蒙特有的“一次开发多端部署 跨设备协同”。AI 会话在手机上发起流转到平板上继续这个过程如果没有清晰的分层光是状态同步就能把团队逼疯。1.2 架构选型ArkTS Stage 模型背后的道理鸿蒙应用开发现在有两种主流选择FA 模型旧和 Stage 模型新。新项目一律用 Stage 模型这不是追新而是 AI 应用对后台任务、长时运行、多实例管理的要求Stage 模型天然更合适。Stage 模型的 UIAbility 组件是面向“用户可感知的交互”设计的比如 AI 对话界面就是一个 UIAbility。而 AI 推理、模型加载这类重计算任务应该放到后台 ServiceExtensionAbility 或公共事件机制中避免阻塞 UI 线程。ArkTS 这门语言本质上是 TypeScript 的超集加上声明式 UI 能力写起来像 TS但编译走的是方舟编译器的静态路径性能接近原生。需要特别强调的是AI 应用里不要把所有逻辑都塞进 UIAbility 的上下文里。数据管理、AI 服务调用、模型生命周期这些要拆出去独立管理。我见过不少新手项目在 MainAbility 里又是起线程又是管理模型最后内存直接爆炸原因就是责任不清。1.3 架构设计要解决的三个核心矛盾端侧 AI 与云侧 AI 的矛盾大模型在端侧跑性能不够全放云端延迟和隐私问题又突出。架构上需要用“端云协同”策略简单任务端侧处理如语音识别、文本分类复杂推理走云端大模型并且通过统一的接口抽象让上层无感知切换。跨设备流转与状态一致性的矛盾鸿蒙主打的分布式能力对 AI 应用来说是把双刃剑。会话迁移过去模型上下文和历史记录都得跟着走架构必须在数据层做“可迁移快照”。动态权限与用户信任的矛盾AI 应用需要麦克风、相册、位置等敏感权限鸿蒙的权限管控非常严格架构上必须设计出“最小权限 场景触发”的申请机制而不是启动时全量弹窗。2. 核心技术模块与关键实现机制2.1 AI 能力接入层的架构抽象AI 能力接入是所有鸿蒙 AI App 的命门。我把它抽象成三层接口第一层是Provider 层定义统一的 AI 服务协议不管背后是接华为云盘古大模型、第三方 API还是端侧 MindSpore Lite 模型都走同一套接口。上层业务不需要知道底层是哪种实现。第二层是Router 层做请求分发和降级策略。比如端侧模型置信度不足自动切换到云端云端超时自动走缓存策略。这个路由逻辑要支持配置化否则每次调整策略都要发版。第三层是Session 层管理 AI 会话上下文。鸿蒙 AI App 的会话不只是简单的一问一答要支持多轮对话上下文窗口、会话历史持久化、会话跨设备迁移。实操上我强烈建议用工厂模式 策略模式组合来实现这套抽象。每种 AI 能力实现一个 Provider注册到工厂里Router 按策略动态选择。这样加法做起来非常舒服——今天接入一个文生图模型只需要新增一个 Provider零侵入。2.2 端侧推理与 MindSpore Lite 的集成细节端侧 AI 推理是鸿蒙 AI App 区别于传统移动应用的亮点之一。鸿蒙生态里最成熟的端侧推理框架是 MindSpore Lite它支持模型转换、量化压缩也能够利用 NPU神经网络处理单元加速。集成 MindSpore Lite 有几点实操经验模型转换训练好的 PyTorch/TensorFlow 模型先用 MindSpore 的转换工具转成.ms格式注意转换时要把动态 shape 固定下来否则推理性能会打折扣。量化选择int8 量化比 fp16 体积减少 50% 以上精度损失对于分类、情感分析这类任务可以忽略不计但对生成式任务影响比较大需要跑测试集评估。生命周期管理模型加载是很重的操作不能每次推理都加载一次要做一个单例模型管理器App 冷启动时预加载保持在内存中。我踩过一个典型的坑在 HarmonyOS 的 WebView 里跑 JavaScript 版模型性能惨不忍睹。后来换成 ArkTS 调 MindSpore Lite 原生接口推理耗时才真正降下来减少了约 80%。2.3 云侧大模型接入的通道设计现在几乎所有鸿蒙 AI App 都要接云端大模型。这块的通道设计要解决三个问题认证安全、流量成本和响应式交互。认证方面不要把你的 API Key 直接写死在客户端代码里那样抓个包就泄露了。正确的做法是走影子密钥机制—— 客户端向自建后端换取短期 token后端保真实密钥。鸿蒙侧的网络请求用 Axios 或者 HarmonyOS 自带的ohos.net.http都行但一定要做统一的拦截器自动附加 token 和埋点信息。流量成本控制方面AI 对话的 token 消耗在架构上要设计“预算机制”。每条用户消息进来先做路由判断——简单意图查询走轻量级关键词匹配只有复杂任务才调用大模型。这个预判逻辑可以做成规则引擎也可以训练一个小的意图分类模型。响应式交互可能是最影响体验的一环。大模型流式返回SSE在鸿蒙上实现要用TextInput配合Text组件增量刷新同时要处理好“正在思考”的状态动画。千万不能在主线程等待完整响应ArkTS 的异步任务TaskPool或ohos.aip必须用起来。2.4 分布式软总线给 AI 架构带来的特殊机遇鸿蒙的分布式能力如果只用在一个设备上等于白费。架构上我把 AI 能力做成了“分布式服务”——手机上跑不了的超大模型推理可以调度到平板上执行手表上发起的语音提问可以在手机端完成大模型处理后再返回结果。技术上用到了鸿蒙的分布式数据管理和跨设备调用。AI 会话上下文不再是本地变量而是存在分布式数据库里设备切换时自动同步。这个架构的难点在于设备可信组网的建立、数据的加密传输、以及异常断开时的回退机制。做架构设计时一定要把“远端不可用”当作常态来设计所有分布式调用都要有本地兜底方案。3. 实操过程搭建一个鸿蒙 AI App 的核心架构3.1 环境准备与工程初始化工欲善其事必先利其器。做鸿蒙 AI App 开发环境这块有几个硬性要求DevEco Studio必须用最新稳定版当前推荐 5.x老版本对 ArkTS 语法和 Stage 模型的模板支持不完整HarmonyOS SDK建议安装 API 12 以上的版本端侧 AI 相关接口在低版本上缺失很严重真机强烈建议准备一台鸿蒙 Next 设备模拟器对 NPU 和分布式能力的模拟非常有限创建工程时选择“Empty Ability”模板即可无用代码少从零搭建架构最干净。工程创建后先干三件事配置签名证书真机调试必需、设置权限声明module.json5、初始化依赖仓库ohpm。3.2 基于 Stage 模型的工程骨架搭建Stage 模型的目录结构要理清楚AppScope/ ├── app.json5 // 应用级配置 entry/ ├── src/main/ │ ├── module.json5 // 模块配置、权限声明 │ ├── ets/ │ │ ├── entryability/ // UIAbility 入口 │ │ ├── pages/ // 页面 │ │ ├── ai/ // AI 能力接入层 │ │ │ ├── provider/ // Provider 实现 │ │ │ ├── router/ // AI 路由 │ │ │ └── session/ // 会话管理 │ │ ├── common/ // 公共组件、工具类 │ │ └── model/ // 数据模型 │ └── resources/ // 资源文件代码层面入口 UIAbility 保持轻量只是创建一个WindowStage加载主页面。AI 能力接入层独立成一个模块用AppStorage或全局单例做状态共享避免能力层和 UI 层耦合。3.3 数据层设计本地优先、云上协同AI 应用的数据层有三个存储目标会话记录、用户偏好、模型缓存。会话记录使用 HarmonyOS 的关系型数据库RDB按用户 ID 与会话 ID 建索引支持分页查询用户偏好轻量级数据用首选项Preferences比如模型选择、温度参数、历史条数设置模型缓存文件系统管理下载的模型文件存到应用沙箱目录做好版本管理和校验MD5对于分布式场景可以用分布式数据服务DDS把会话快照同步到登录的同一账号设备上。注意 DDS 的同步粒度是记录级别适合存“会话摘要”而不是“完整上下文”否则带宽会被撑爆。3.4 权限申请与隐私合规实践AI 应用权限这块没有捷径必须稳扎稳打。我主要遇到三类权限麦克风权限用于语音输入必须在用户点击语音输入按钮时才申请不要进 App 就弹窗相册权限用于图片理解多模态 AI鸿蒙受限权限的申请需要额外说明用途网络权限基础权限但要注意鸿蒙对后台联网管控比较严格长时间 AI 请求不要挂在前台 Service 上隐私合规方面AI 对话内容绝对不能明文存本地数据库至少要用 SQLCipher 或鸿蒙自带的加密能力做字段级加密。另外做 AI 训练数据回传时一定要做匿名化处理用户协议里也要写清楚。3.5 核心代码实现AI 服务接入层直接贴我项目里的一段核心逻辑做了隐私脱敏处理。这是一个基于工厂模式的 AI Provider 管理框架// ai_provider_factory.ets import { AIProvider } from ./AIProvider; import { CloudLLMProvider } from ./CloudLLMProvider; import { OnDeviceProvider } from ./OnDeviceProvider; export class AIProviderFactory { private static providers: Mapstring, AIProvider new Map(); static registerProvider(key: string, provider: AIProvider): void { this.providers.set(key, provider); } static getProvider(key: string): AIProvider { return this.providers.get(key); } static initDefault(): void { this.registerProvider(cloud, new CloudLLMProvider()); this.registerProvider(device, new OnDeviceProvider()); } } // AIProvider.ets 统一接口 export interface AIProvider { streamChat(sessionId: string, userInput: string): PromiseStreamData; isAvailable(): boolean; getLatencyEstimate(): number; }核心思路是所有实际业务代码依赖AIProvider接口不依赖具体实现。调试时可以用 MockProvider 代替真实模型跑通整个 UI 交互后再接真模型。3.6 AI 请求路由实现路由层最关键的逻辑是降级策略。我实现了一个简单的智能路由// ai_router.ets import { AIProviderFactory } from ./AIProviderFactory; export class AIRouter { static async routeRequest(input: string, sessionId: string): PromiseStreamData { const deviceProvider AIProviderFactory.getProvider(device); if (deviceProvider.isAvailable()) { // 尝试端侧轻量推理置信度够高就直接返回 const localResult await deviceProvider.streamChat(sessionId, input); if (localResult.confidence 0.75) { return localResult; } // 置信度不够降级到云端 } const cloudProvider AIProviderFactory.getProvider(cloud); if (cloudProvider.isAvailable()) { return await cloudProvider.streamChat(sessionId, input); } throw new Error(all_providers_unavailable); } }这套路由看似简单实际打下了整个 AI 架构的稳定基调。后续增加“本地知识库优先查询”等逻辑就是在这个 Router 里加一个步骤而已。3.7 会话状态管理与跨页共享AI 对话场景的特殊之处在于状态多、交互频繁ArkTS 的状态管理机制要善于利用。我项目里的会话管理用Observed类 AppStorage结合Observed export class ChatSession { sessionId: string ; messages: ChatMessage[] []; status: idle | thinking | responding idle; appendMessage(msg: ChatMessage): void { this.messages.push(msg); } }页面侧用StorageLink或Watch监听会话变化保证 AI 消息边生成边刷新的体验。这里我踩过坑如果你用普通的State去存一个Observed对象的引用内部属性变化不一定能触发刷新必须用Observed 正确使用ObjectLink。4. 常见问题与排查技巧实录4.1 ArkTS 与 TypeScript 的语法陷阱ArkTS 是静态类型语言与 TS 的最大差异在于它不允许使用any和鸭子类型。AI 相关代码里经常要处理复杂 JSON 结构直接JSON.parse()返回any类型会报编译错误。解决办法是定义一个Model类把动态 JSON 手动映射成类的实例。比较笨但是稳定class AIResponseModel { content: string ; confidence: number 0; finishReason: string ; static fromJson(json: object): AIResponseModel { let model new AIResponseModel(); model.content json[content] ?? ; model.confidence json[confidence] ?? 0; model.finishReason json[finish_reason] ?? ; return model; } }如果团队里 ArkTS 对第三方 JS 库的兼容性有疑问最好的验证方式是直接编译不要想当然。4.2 端侧模型推理性能瓶颈排查端侧模型跑得慢通常不是模型本身的问题而是下面几个地方模型加载时机如果每次推理前才加载模型IO 开销惊人。应该在 App 空闲时预加载并配合内存警告回调动态释放输入数据预处理文本转 Token 的过程涉及大量字符串运算不要用低效的循环拼接能用TextEncoder就用NPU 使用率模型转换时把算子分配到 CPU 上跑了NPU 闲着典型原因是算子类型不支持 NPU需要更换模型版本或添加回调算子排查工具方面DevEco Studio 自带的 Profiler 一定要用起来重点看 CPU 线程调度和内存分配。我还习惯在关键推理路径打上hilog时间戳粗粒度定位再细粒度 profile。4.3 跨设备流转时的会话上下文丢失分布式场景下 AI 会话迁移最头疼的是上下文丢失。排查方向确认分布式数据库同步是否成功在远端设备上自己查一下数据库如果键值已经同步过去说明是读取时序问题UI 层的状态刷新是否完成设备迁移完成之前旧设备如果还在继续写入会话可能产生数据覆盖同一个 UIAbility 实例多设备拉起时创建了多个实例需要按sessionId判断恢复还是新建我的解决思路是增加一个会话迁移协议迁移时将上下文序列化成一个 JSON 包包含消息列表、模型参数、知识库引用位置目标设备收到包后校验完整性再写入本地。这样不依赖底层同步机制逻辑完全自主可控。4.4 权限弹窗失灵或重复触发鸿蒙的权限弹窗有个规则如果用户拒绝两次系统会直接不再弹窗转而在设置里开启。很多 AI 应用不理解这个机制导致用户误触“拒绝”后完全无法使用语音输入功能。正确的处理逻辑是每次申请权限前都检查abilityAccessCtrl的授权状态如果已经被永久拒绝引导用户到设置页打开而不是反复弹申请框。另外权限申请界面要写清楚“为什么需要这个权限”降低用户的警惕心理。4.5 应用被系统杀后台导致 AI 会话丢失用户正在跟 AI 对话切到后台几分钟回来发现整个 App 被杀了会话全部丢失。这在鸿蒙上很常见尤其是低内存设备。架构层面对策有两个实现状态保存与恢复UIAbility 的onSaveState回调里把会话列表和当前 Session ID 写入持久化存储onCreate时读取并恢复使用后台长任务如果确实需要后台持续运行 AI 任务申请ohos.permission.KEEP_BACKGROUND_RUNNING并配合ContinuousTask机制显示系统通知否则系统会判定为异常后台行为现在我的项目里AI 对话过程中的所有消息都在本地 RDB 里落库一条不丢崩溃和杀进程都不怕。5. 架构演进从单一 AI 功能到 AI Agent 平台5.1 鸿蒙 AI App 的下一步Agent 化AI 应用不会止步于简单的问答机器人Agent智能体化是当前最明确的演进方向。所谓 Agent不再是被动地“你问我答”而是能自主拆解任务、调用工具、执行动作的 AI 主体。在鸿蒙的架构里做 Agent我建议在 AI 能力接入层之上再加一层Agent 编排层。它的职责包括意图拆解把复杂指令拆成多个子任务工具注册与调用让 AI 能调用系统的日历、地图、备忘录能力任务状态追踪子任务执行进度可视化多 Agent 协同主 Agent 调度子 Agent各自负责一个领域鸿蒙系统的原子化服务和卡片恰好是 Agent 能力对外输出的绝佳载体。让 Agent 的每一个决策结果都生成一张服务卡片放到桌面上用户可以直接交互体验比传统 App 内页面强一个量级。5.2 多模态与端云协同的深化当前鸿蒙 AI App 大多是文本交互多模态是明确的增量。图片理解、语音克隆、视频摘要这些能力接入架构时沿用已有的 Provider 模式非常顺手——每次新增模态能力新增一个 Provider 实现即可路由层几乎不用动。端云协同深化的方向是“端侧预判 云端精排”。端侧跑一个小模型先给回复打分如果分低才请求云端云端返回后再做一次蒸馏把高质量回复反哺端侧模型做增量训练。这个飞轮转起来用户量越大端侧模型越聪明长期成本会快速下降。5.3 隐私计算与用户信任架构最后想谈谈容易被忽略但越来越重要的隐私设计。做架构规划时就要把“隐私优先”落到实处不是只靠隐私政策文档那种表面功夫。我在项目里落地的几个实践所有敏感数据本地加密存储密钥放在鸿蒙的HUKS通用密钥库系统中不上传云端端侧模型优先处理敏感信息必要时才用联邦学习式的聚合上报而不是原始数据直传用户可以对 AI 的“记忆”做可视化管理和删除透明可操作这套隐私架构还有个额外价值当产品出海或在企业内部部署时面对各种合规审计有一整套完整的技术文档和实现支撑会从容很多。最后再分享几个实操心得做了这么久的鸿蒙 AI App 架构最大的感受是架构不是画出来的是改出来的。不要试图在第一版就设计出完美的分层和抽象先让一个最小闭环跑通——UI 能发消息、AI 能回复、会话能存储——然后慢慢叠加路由、分布式、端云协同。每一步踩到坑架构才真正长成该有的样子。工具链上DevEco Studio 的预览器和 Profiler 现在比早期版本成熟不少但依然建议所有关键 AI 路径都要真机验证。模拟器测不了 NPU 加速分布式能力更是只能在真机组网环境里调试。如果你正准备启动鸿蒙 AI App 项目我建议先明确一个问题你的差异化是靠端侧 AI 的低延迟体验还是靠分布式场景的跨设备协同还是靠 Agent 化的主动服务能力这个回答会决定你的架构要偏重哪一层。想清楚了再动手比什么设计模式都管用。
