说实话，一个 Flutter 项目要往鸿蒙上迁，UI 适配通常不是最大的坎，真正的麻烦往往藏在“依赖”里。我当时在做一个跨平台智能助手 Demo，需要在鸿蒙设备上提供文案生成、多轮对话、图片理解这类生成式 AI 能力。Flutter 端之前用的是 google_generative_language_api 这个官方 Dart 语言包，也就是团队里习惯叫的 GLAPI 组件，在 Android 和 iOS 上几乎是开箱即用。但当编译目标切到 HarmonyOS 之后，一系列“看似正常、实则诡异”的问题接踵而来——依赖怎么引、权限怎么放、API Key 怎么存、多模型如何调度，以及最容易被忽视的推理治理架构该怎么落。这篇文章就把整套适配方案和踩坑记录完整写下来，给同样被困在鸿蒙适配里的人一个参考。
1. 为什么要在鸿蒙侧接入生成式 AI：项目背景与需求拆解
1.1 一次双端一致性的倒逼
当时的现象很直接：产品要求“同一套智能问答能力，在 Android、iOS、鸿蒙三端表现一致”。这个诉求在工作量上是很残忍的，因为如果每一端都单独接原生 AI SDK，那后续维护的成本基本是乘三在涨。幸运的是，项目本身是 Flutter 跨端架构，Dart 层调用一切能力是天然的选择。于是团队把目光锁定在 google_generative_language_api 上——它在 Dart 生态里算是最正统的大语言模型客户端，支持模型调用、多模态输入、流式输出，接口设计也简洁。
但“官方支持”四个字在鸿蒙这里是不存在的。鸿蒙的 Flutter 运行时和 Android 的 Flutter 运行时并不完全一致，虽然 Dart 层是跨平台的，但插件注册、网络栈、安全存储这些环节都会出现行为差异。所以这个项目表面上是“适配一个组件”，实际拆开是四件事：环境适配、组件接入、调度层设计、推理治理架构。标题里的“生成式 AI 集成”“大语言模型调度”“全场景智能推理治理”三个关键词，正好对应着这四件事中的后三件。
1.2 标题中的三个关键词，拆开看都是需求
先看“生成式 AI 集成”。这个词看起来像是在描述目标，其实它是一堆具体需求的集合：要能接文本生成、要支持多轮对话、要有流式打字机效果、要能处理图片输入。每一个需求背后都有对应的 API 能力，而 google_generative_language_api 恰好把这些能力都覆盖了。
再看“大语言模型调度”。为什么要调度？因为业务不是只用一个大模型。我的认知是，在企业级应用里，没有人会真的把所有流量都打到同一个模型上。成本、延迟、效果都要权衡，所以通常会有多个模型型号，甚至多个服务商并存。调度层的作用就是根据请求的类型、优先级、成本预算，把请求分发给合适的模型，并在超时、失败时自动降级。
最后是“全场景智能推理治理”。这个词看起来像是架构概念，实际落在代码上就是四类工作：凭证怎么管、缓存怎么做、限流怎么控、日志怎么审计。这四件事如果不在架构层面统一处理，等业务闯大了再来治理，就只能靠人肉盯监控了，那是相当痛苦的事情。我把这四块在章节 5 里展开来讲，这里先记住一个结论：治理不是可选项，而是从第一版就要入架构的。
2. 鸿蒙化适配第一步：环境准备与工程搭建
2.1 搭建鸿蒙 Flutter 工程的那些特殊姿势
鸿蒙侧跑 Flutter，不是说装个最新版 Flutter SDK 就能直接编译的。devicenio 上看到的方案是，需要在开发工具里配置一个兼容鸿蒙的 Flutter SDK 分支。实际操作时，我用的是一套社区维护的兼容分支，流程并不复杂，但有几处容易走偏的地方值得说清楚。
第一步，拿到鸿蒙 SDK 的工具链之后，在命令行里做一个版本检查，确认 flutter、dart、鸿蒙工具链的版本是配套的。我踩到的第一个坑就是版本不匹配，当时开发的 Flutter SDK 版本很新，但鸿蒙侧引擎还不支持，编译到一半就开始报平台通道找不到的错误。第二步，需要把自己项目的 Android 工程目录剥离掉——这不是必须的，但鸿蒙编译时如果还带着 Android 的 Gradle 配置，容易引发依赖解析冲突。第三步，在 pubspec.yaml 里不要急着加 AI 组件，先把一个空的 Flutter 工程在鸿蒙模拟器上跑通。这个过程如果 Hello World 都出不来，后面的 AI 调试只会更难定位问题。
实测跑通空工程的时间因人而异，顺利的话一个下午。如果你在鸿蒙上用的是自己的签名，还需要配置证书 profile，这一步在 DevEco 的 GUI 里操作，比较直观。
2.2 引入 google_generative_language_api 依赖
依赖引入本身不复杂，在 pubspec.yaml 里加一行：
dependencies: google_generative_language_api: ^0.1.0然后执行flutter pub get。这个组件依赖了基础的 HTTP 和 JSON 解析库，所以在拉取依赖时，网络仓库连通性要保证。如果出现了下载超时，可以先排查镜像配置，而不是反复删除pubspec.lock——后者只会让问题来得更慢。
这里有个重要的判断：google_generative_language_api 是纯 Dart 实现的，底层走的是 HTTP/HTTPS 协议，没有 Android 和 iOS 的原生插件代码。这在鸿蒙适配里反而是最大的优点。很多 Flutter 组件到了鸿蒙上报错，是因为它们依赖 MethodChannel 调用原生能力，而鸿蒙侧没有对应的原生实现。但 GLAPI 从设计上就不依赖平台原生代码，所以我们只需要确保鸿蒙应用能发 HTTPS 请求、能安全保存密钥，就能跑起来。这也解释了为什么先做空工程验证很重要——空工程验证的是 Flutter 环境，AI 组件验证的是网络与环境。
2.3 网络权限与平台通道检查
鸿蒙应用默认是不带网络权限的。这一点和 Android 很像，但配置位置不同。鸿蒙工程在entry/src/main/module.json5文件里配置权限，需要加上：
{ "name": "ohos.permission.INTERNET" }如果你漏掉这一步，调用 generateContent 的时候不会立刻报错，而是会在网络请求发出时直接抛一个底层异常，错误信息极其隐晦，看起来像 SocketException，实际是权限被拦截。
平台通道这一块，如果要用的组件都是纯 Dart 的，基本就不用担心。但我当时为了统一日志上报，写了一个小的鸿蒙原生插件来桥接 HiLog。一旦引入原生插件，就要格外检查插件在 MainAbility 里的注册顺序。Flutter 引擎初始化完成后，插件注册表如果晚于首帧初始化，第一次调用会静默失败。这个现象的排查成本很高，我的建议是：除非绝对必要，不要在鸿蒙适配的第一版引入原生插件，先用纯 Dart 方案把链路跑通，再考虑增强能力。
3. google_generative_language_api 能力解析与调用范式
3.1 组件核心能力速览
google_generative_language_api 本质上是一个“模型调用客户端”，你可以把它理解成你与大模型之间的快递员。它帮你完成请求组装、鉴权、响应解析，你只需要决定“要什么”。
它的核心 API 模型很简单：GenerativeModel负责配置模型型号、API Key、生成参数（温度、最大 Token 等）；GenerativeModel.generateContent()处理单次请求；GenerativeModel.startChat()维持一个多轮会话上下文；generateContentStream()则返回一个异步流，用于打字机效果。这三个接口基本覆盖了智能助手 90% 的场景。
组件的内部逻辑依赖于 model 服务端的 REST 接口，所以你在代码里填写的模型名称，例如gemini-1.5-flash，必须和服务商的模型列表对得上。如果填错，一个典型的404或者模型不存在错误就会直接抛出来。
3.2 标准调用与流式响应示例
第一次接入的时候，官方文档里的示例已经足够跑通基础功能。核心代码如下：
import 'package:google_generative_language_api/google_generative_language_api.dart'; final model = GenerativeModel( model: 'gemini-1.5-flash', apiKey: '你的API Key', generationConfig: GenerationConfig( temperature: 0.7, maxOutputTokens: 1024, ), ); final response = await model.generateContent( Content.text('帮我写一份周末南京三日游计划'), ); print(response.text);这段代码在鸿蒙上可以直接跑，前提是网络权限已配置、API Key 有效。但生产环境不能只用单次请求。实际体验中，多轮对话和流式输出几乎是必备的。
多轮对话的写法是：
final chat = model.startChat(); await chat.sendMessage(Content.text('我想去南京玩')); await chat.sendMessage(Content.text('预算一千五左右，帮我精简一下'));startChat()内部会维护历史消息列表，每次调用都会携带上下文。这里要特别提醒：会话越长，Token 消耗越大，后面的章节会专门聊治理。
流式输出的代码也不复杂：
final stream = model.generateContentStream( Content.text('用五个点总结鸿蒙开发经验'), ); await for (final chunk in stream) { updateUI(chunk.text ?? ''); }实测下来，流式返回对用户体验的提升非常明显，但副作用是 UI 频繁刷新，如果不加节流控制，鸿蒙设备的帧率会掉，界面显得一顿一顿的。我的做法是在 UI 层做一段 50ms 的节流，把频繁的文本增量合并成一帧一次的更新。
3.3 业务侧的统一门面封装
直接调用 SDK 在 Demo 阶段是没问题的，但一旦进入多模型调度和治理阶段，业务代码就会变得很痛苦。因为每个业务方如果都直接 import 这个包，后续换服务商、切换模型、加缓存和日志都会牵一发动全身。
所以我建议在 adaption 阶段就把“门面”做出来，我自己用的是AIGateway这个抽象类：
abstract class AIGateway { Future<AIResult> generate(String prompt, {AITaskType task = AITaskType.general}); Stream<String> generateStream(String prompt, {AITaskType task = AITaskType.general}); }GLAPI 的具体实现只是其中的一个GLAPIGateway，后续如果接本地端侧模型或另一个服务商，只需要新增实现类。这样做的好处是：调度层真正调度的是你自己的抽象，而不是具体厂商的 SDK。这个思想非常朴素，但能有效隔离底层变化。
4. 大语言模型调度层架构设计
4.1 为什么要单独做一个调度层
如果只有一个模型、一个场景，那调度层就是多余的。但现实中有三个变量会逼迫你去做调度：模型的多样性、成本的可控性、服务的可用性。
我接触过的真实场景是：简单指令用轻量模型，响应快、成本低；复杂推理用重量模型，效果好但慢；图片理解必须用多模态模型。如果代码里把这些逻辑写死在业务方，每一处新需求都要改业务代码，这不叫架构，这叫打补丁。所以调度层的本质是“把模型选择从业务方手里收回来”。
另一个变量是成本。每个模型都有不同的计费策略，真实项目里经常出现某个功能替换模型后成本翻倍的情况。调度层可以在统一入口做预算判断，比如当天 token 用量已到阈值时，临时把优先级路由到更便宜的方案。这在没有调度层时，实现成本极高。
4.2 模型注册表与路由规则
调度层的第一件事是建立模型注册表。用一个配置文件描述每个模型的特征：
{ "models": [ { "id": "flash-lite", "type": "chat", "tags": ["quick", "cheap"], "maxTokens": 1024, "timeoutMs": 15000, "costWeight": 0.3 }, { "id": "pro-heavy", "type": "chat", "tags": ["complex", "reasoning"], "maxTokens": 4096, "timeoutMs": 60000, "costWeight": 1.0 } ], "routes": [ { "task": "SUMMARIZE", "modelId": "flash-lite" }, { "task": "COMPLEX_REASONING", "modelId": "pro-heavy" }, { "task": "IMAGE_UNDERSTANDING", "modelId": "multimodal" } ] }路由规则可以做得简单，也可以做得智能。简单版就是按任务名匹配；进阶一点可以基于输入的长度或关键词做动态判断。我的经验是：先按任务名路由，跑两周线上数据之后再去优化策略，千万不要一开始就上复杂分类模型来选路，收益低且调试难度大。
4.3 优先级队列与超时重试熔断
调度不仅仅是“选模型”，还包含“排队”。交互类请求，比如用户在聊天框等待回复，应该优先于后台异步任务。我的做法是建一个双优先级队列，交互请求权重为 1，后台任务权重为 0.1。队列消费时按权重排序，保证关键路径不被后台任务阻塞。这个实现不需要引入消息中间件，Dart 的StreamController配合一个简单的优先级插入逻辑就够了。
超时与重试的坑我是深有体会。大模型的首次响应延迟因服务端负载波动非常大，尤其在鸿蒙设备上，网络协议栈的细微差异会放大这个问题。最初我按传统 API 的经验设置了 10 秒超时，结果线上频繁出现超时重试，反而让服务端不堪重负。后来我把超时策略调整为两段式：首字返回超时 25 秒，整段返回超时 90 秒。重试则采用指数退避，第一次 1 秒，第二次 2 秒，最多重试 2 次，超过就直接返回友好提示。这个方案在实践中稳定很多。
熔断是第三层。如果一个模型连续失败超过 5 次，熔断器打开，后续请求在接下来 30 秒内直接路由到备用模型。这个策略我用一个很小的 Dart 类实现，维护连续失败计数和打开时间戳即可。
4.4 一次带调度的完整请求链路
调度层的工作可以在一次用户输入中完整串起来。用户在文本框输入“帮我把这段英文总结成三点”，业务层先把任务分类为SUMMARIZE，网关带着任务标签进入调度层。调度层查注册表，命中flash-lite，检查该模型当前熔断状态，再检查优先级队列，然后调用 GLAPI 的实现，把流式文本一段一段吐回来。如果在过程中flash-lite超时，重试一次后还是失败，熔断器计数加一，同时请求降级到pro-heavy——用户感受到的只是响应慢了一点，但不会被失败中断。
这套链路非常实用。不要把调度层想得很复杂，它就三个职责：选路、排队、降级。只要这三个职责清晰，任何大模型客户端都可以接入。
5. 全场景智能推理治理架构落地
5.1 权限与凭证治理
先说最敏感的 API Key。很多人在 Demo 里直接把 Key 写死在 Dart 文件里，这在上线前是必须清掉的。鸿蒙侧没有直接可用的 flutter_secure_storage 官方实现，对 GLAPI 这种纯 Dart 包而言，持久化 Key 需要借助鸿蒙系统能力，或者做一层平台通道。我的建议是在鸿蒙原生侧写一个加密插件，用系统级密钥库加密后存储，Dart 侧通过通道读取。如果不想写原生代码，退而求其次也要用混淆过的配置文件，加上运行时动态拼接，而不是明文写在源码里。
凭证治理的下一步是对 Key 进行分级。可以给不同功能分配不同的 Key 和配额，一旦某个 Key 泄漏或者超额，可以在控制台单独禁用，不影响全局业务。这个方法在成本和风险控制上都非常有效。
5.2 上下文记忆与 Token 治理
所有大模型对话，本质都是“送的上下文越多，花的钱越多”。startChat 虽然帮你管理了上下文，但它不会帮你控制体量。测试阶段你发几句对话没问题，一旦业务聊天持续 20 轮，历史消息列表越来越长，Token 数会快速膨胀。
治理方案是做一个“滑动窗口 + 摘要压缩”。窗口默认保留最近 5 轮对话原文，更早的内容不再直接拼接，而是交一个小模型做摘要。摘要文本替代旧消息进入后续请求。这个方案在保持上下文连贯性的同时，能把 Token 消耗压下来很多。
还有一层是 Token 估算。在发给模型之前，可以从调度层估算出本次请求的 Token 量级，然后用本地配置的限额做检查。如果超限，直接提示用户“本轮对话过长，请开启新话题”，而不是让请求带着超长上下文走到服务端再被拒绝。
5.3 缓存、限流与成本治理
缓存的意义被很多人低估了。对于“同一问题重复提交”这种场景（比如多个用户问“你的使用规则是什么”），缓存可以直接把服务端成本归零。我的缓存策略是：对请求文本做 SHA-256 哈希，缓存一小时内的响应。但要注意，带流式的请求不能简单整体缓存，否则打字机效果就没了。折中方案是对文本生成请求做缓存，对对话类请求不做缓存，只做限流。
限流用的是令牌桶算法。每个用户每分钟的请求令牌数是可配置的，如果令牌耗尽，请求直接返回“请稍后再试”。这个策略对保护下游服务端和成本都非常友好。具体到鸿蒙端，令牌桶可以在内存中实现，也可以在网关侧实现。对单机应用，内存版令牌桶足够用。
5.4 审计日志与隐私兜底
治理体系如果没有日志，等于没治理。我给每个请求生成了一个全链路 traceId，从用户点击到模型返回，这个 traceId 贯穿始终。日志字段包括：用户 ID（可脱敏）、请求来源页面、模型 ID、请求 Token 数、响应 Token 数、耗时、是否命中缓存、是否触发熔断。这些日志在排查问题、成本归因时帮助巨大。
隐私兜底是治理架构里不能省的一环。在把用户输入发往远端模型之前，会先跑三个过滤器：敏感词库检测、个人电话号码和身份证号识别、内容长度限制。一旦命中敏感信息，可以选择脱敏或直接拦截。这个环节在鸿蒙端做的好处是不依赖服务端，响应快，且符合最小化采集原则。
6. 鸿蒙实测中的坑与排查手册
6.1 五个高频问题速查
这部分完全是经验之谈，整理成表格方便你排查。
| 问题现象 | 根因 | 解决方案 |
|---|---|---|
| 首次调用直接抛 SocketException | module.json5 缺少 INTERNET 权限 | 在鸿蒙工程配置中加入网络权限 |
| 模型响应异常慢，且偶发失败 | 初始超时设置过短 | 首字超时调至 25 秒，并加指数退避重试 |
| UI 刷新频繁卡顿 | 流式回调过于密集 | 在 UI 层加 50ms 节流合并更新 |
| API Key 读取失败 | 尝试直接用原生插件读取密钥但插件注册晚于首帧 | 改用纯 Dart 方案先跑通，或延迟到插件注册完成后再初始化网关 |
| 内存缓慢上涨 | 长会话历史消息无节制累积 | 使用滑动窗口 + 摘要压缩策略 |
第一和第四个问题我在不同设备上都遇到过，很典型。尤其是第四个，鸿蒙的插件注册时机和 Android 不完全一致，Android 上正常的代码，在鸿蒙上就变成“首次调用时插件不可用”的幽灵问题。排查它的最好方法不是在代码里加延迟，而是把插件调用异常捕获到日志里，确认根因后再决定方案。
6.2 两个需要重点解释的疑难案例
第一个案例是流式响应中途断掉。用户使用流式回复时，网络偶发抖动，服务端已经把连接断开，但 Dart 流并没有感知到，界面一直停在“正在输入”的状态。这个坑的解决方案不太直观：在鸿蒙端，需要给流式请求增加一个动态的心跳超时，即如果 30 秒内没有任何数据块到达，就主动取消这个订阅并返回失败状态。Dart 的Stream.timeout方法可以把超时处理原子化，不需要改动业务层代码。
第二个案例是 JSON 序列化的类型漂移。我在鸿蒙侧做原生插件日志时，试图把 Dart 的Map<String, dynamic>直接通过 MethodChannel 传到原生侧，结果在鸿蒙上出现了数字类型被自动改成 double 的诡异现象。这是因为鸿蒙的 JSON 解析器处理空值、数值的方式与 Android 存在差异。最终方案是彻底绕开 MethodChannel 传复杂对象，统一改成传递 JSON 字符串，在原生侧再自行解析。这也再次印证了：鸿蒙适配期，最好保持桥接层的数据结构极简。
7. 收尾的个人心得
这套东西做完之后，我最大的体会是：鸿蒙适配本身并没有想象中那么难，真正难的是“不要带着 Android 的思维惯性去写鸿蒙代码”。google_generative_language_api 这个包因为是纯 Dart 实现，在鸿蒙上几乎零改造就能跑，极其适合作为跨端 AI 能力的底座。但也正因为它跑得通，容易让你忽略治理层的重要性——等并发涨上来、成本飙上去、响应质量变差，才想起要做调度和治理，那就只能还技术债了。
最后分享一个细节：在鸿蒙真机上调试流式输出时，一开始无论怎么优化，总感觉首个 token 来得比 Android 慢。后来发现不是模型的问题，而是鸿蒙的 DNS 解析阶段偶发延长，导致连接建立耗时偏高。解决办法是在调度层做了一次“模型预热”，App 启动后空闲阶段主动对模型服务端做一次轻量探测，让 DNS 缓存和连接池提前准备好。这个改动让首字延迟体感降低了很多。类似的坑肯定还有，但只要保持对底层链路的敏感，大部分问题都能在架构层面提前消化。
