企业官网建设流程全解析

最近帮团队把一个带聊天功能的 HarmonyOS NEXT 应用接到了开源大模型上，从模型选型到 ArkTS 侧网络层改造，前后折腾了小两周。这中间真正决定项目走向的并不是某个 API 怎么写，而是 5 个偏"架构级"的工程决策：模型放在端侧还是云端、选哪个开源模型、走什么通信协议、ArkTS 侧如何组织状态和网络层、UI 交互到底按什么标准做。这几个决策一旦定死，后面的编码其实就是按部就班的事。

如果你也正准备在鸿蒙应用里接入开源大模型，这篇文章会把我当时的完整思考链、实测对比和踩坑记录都摊开给你看。内容偏实战，适合已经会 ArkTS 基础语法、或者刚考过鸿蒙应用开发基础认证正在找练手项目的开发者。

1. 先认清场景：这个应用到底需要大模型做什么

不能一上来就选型，先把需求逼问清楚。我做的这个应用是一个面向中小学生的"AI 学习助手"，核心功能有三块：日常对话问答、作文素材生成、历史知识点的口语化讲解。表面上看都是"聊天"，但每个功能的容忍度不一样。

1.1 需求拆解：对话、生成、上下文记忆的差异

对话问答要求响应快，最好首字延迟在 1.5 秒以内，用户等不起。作文素材生成属于典型的长文本任务，一次性可能输出 500 到 1000 字，对模型生成质量和上下文连贯性要求高。知识点讲解则相对宽容，哪怕慢一点，只要解释准确、语气自然就行。

三种场景对模型的参数量要求完全不同。小模型（1.5B 以下）处理短对话够用，但长文生成经常出现逻辑断裂；大模型（7B 以上）效果明显更好，可一旦跑在端侧，内存占用会直接压垮手机。这个矛盾是后面所有决策的源头，我先记下来，后面细说。

1.2 环境确认：DevEco Studio、API 12 与 5.0.0(12) SDK 的实际搭配

工程实践第一步永远是确认工具链。我用的版本组合是 DevEco Studio 5.0.0 Release，配套 SDK 是 HarmonyOS NEXT 5.0.0(12)，也就是 API 12。热词里提到的api 12+ / 5.0.0(12)就是这个意思：API 12 是接口层级，5.0.0(12) 是 SDK 版本号与 API 级别的对应关系。

这块有个容易踩的坑：HarmonyOS NEXT 已经完全不兼容 Android 的 APK 逻辑，工程里所有网络请求、权限声明、UI 组件都必须走 ArkTS/ArkUI 体系。创建项目时模板选"Empty Ability"即可，但记得在module.json5里配好ohos.permission.INTERNET权限，否则后续所有 HTTP 请求都会静默失败。

{ "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } }

这个权限和 Android 的uses-permission是两码事，鸿蒙的权限声明位置在module.json5里，不在AndroidManifest.xml，因为 NEXT 压根没有这个文件。

2. 决策一：模型放在端侧还是云端，这是所有选择的地基

这个决策不先做，后面全是空中楼阁。模型跑在哪，直接决定你选用什么规格的模型、走什么通信协议、UI 上要不要做加载态和离线兜底。

2.1 端侧方案的硬约束：内存、包体积与发热

先说端侧部署。HarmonyOS NEXT 的端侧 LLM 推理目前最现实的方案是拿量化后的小模型跑在 Native 层，通过 C++ 调用 ONNX Runtime 或 MNN，再往 ArkTS 层暴露 NAPI 接口。

听起来链路不复杂，但硬约束非常现实：一个 Qwen2.5-0.5B 量化到 INT4 的模型，体积也有 400MB 左右，推理时内存占用约 1.2GB。如果用户用的是 8GB 内存的旧款手机，App 本身再占一部分，系统大概率直接清后台。更别提连续生成时 SoC 发热导致的降频，我实测推理 3 分钟后机身温度明显上升，响应速度衰减超过 20%。

如果一定要端侧方案，我建议把模型压到 0.5B 以下，并且只在离线场景提供固定模板回复，不要做长文本生成。比如"生词查询""公式速记"这类短任务可以端侧兜底。长对话、长文生成全部走云端，这是最稳妥的工程取舍。

2.2 云端方案的现实成本：服务器开销与带宽

云端方案的本质是把模型推理外包给服务器。我用前文的需求倒推：3000 左右的日活、人均 20 条请求、每条平均输出 300 token，一天的推理量大约 1800 万 token。

如果用 vLLM 部署 Qwen2.5-7B-AWQ（INT4 量化），单张 24GB 显存的消费级显卡大约能扛 80 并发、单 token 生成速度 50ms 左右。8 卡加一台 64GB 内存的应用服务器，月成本在两千到四千元区间。这个账算完，结论很清楚：先把云端跑起来，给核心功能用，等用户量起来再优化端侧缓存。

2.3 我的最终选择：云端为主、端侧轻量兜底

我的决策落地是分层处理：

• 全局对话和长文生成 —— 走云端大模型，保证质量
• 生词查询、公式换算 —— 走端侧轻量规则引擎，不调用模型
• 网络断开时 —— 聊天页给出固定兜底文案，并缓存未发送消息，恢复网络后再自动重发

这样既保住了体验下限，又控制了成本。如果你刚开始做，我建议先别碰端侧推理，把云端链路跑通比什么都重要。

3. 决策二：开源模型选型与部署工具的匹配

模型位置定了，就该选具体模型和部署方式。热词里问的"目前部署大模型常用的开源平台和工具有哪些"其实指的就是这一层。我的经验是用一套兼容方案同时解决"选哪个模型"和"用什么工具跑"两件事。

3.1 主流开源模型对比：用中文场景倒推选型

我把候选模型缩小到三个：Qwen2.5-7B、Llama-3.2-3B 和 ChatGLM4-9B。因为我的产品面向中文场景、长文生成多，所以权重排序是：中文能力 > 长文本连贯性 > 指令遵循 > 英文能力。

最终选 Qwen2.5-7B，主要是看中它在中文写作任务上的稳定表现，而且 Apache 2.0 许可对商用授权限制最少。这个选择在鸿蒙端的实际体验是：输出内容语法错乱明显少于 Llama-3.2-3B，中文标点、成语用错的概率低得多。

3.2 部署工具选型：Ollama 不等于全部，vLLM 才是线上主力

模型只是原材料，怎么把它变成可访问的接口是另一件事。目前常用的开源工具有这么几个层次：

• Ollama：本地调试首选，一条命令拉起模型，自带 OpenAI 兼容接口。但它更适合单机实验，高并发下吞吐不稳定，我线上没有用它。
• llama.cpp：适合端侧或 CPU 部署，支持 GGUF 量化。如果坚持要跑端侧推理，这个工具是最靠谱的落点。
• vLLM：线上服务的主力，PagedAttention 机制让显存利用率高很多，吞吐量比原生推理高出数倍。我最终用 vLLM 部署 Qwen2.5-7B，并开启了 AWQ 量化。
• Xinference：多模型管理平台，适合团队内部统一调度，但我个人项目用不上，没选。

部署时不直接用 vLLM 的原生接口，而是套一层 OpenAI 兼容的/v1/chat/completions格式。这样做的好处是鸿蒙端代码只依赖一个接口协议，后面换模型、换工具都不用改应用代码。

3.3 Prompt 模板与参数调优对鸿蒙端的影响

模型推理参数直接影响 App 表现的稳定性。我在服务端统一设置temperature=0.7、max_tokens=1024、top_p=0.9，并且把系统 Prompt 和控制逻辑放在服务端，而不是由 App 端每次都传。

服务端模板长这样：

SYSTEM_PROMPT = "你是一个面向中小学生的AI学习助手，回答要简洁、准确、语气亲切，避免使用过于复杂的术语。生成作文时，先给出提纲，再展开正文。" def build_messages(user_text: str, history: list): messages = [{"role": "system", "content": SYSTEM_PROMPT}] messages.extend(history[-6:]) # 只保留最近6轮，防止超限 messages.append({"role": "user", "content": user_text}) return messages

这里刻意把历史消息裁剪到最近 6 轮，是为了控制 token 量、减少服务端成本，也让鸿蒙端请求体变小，降低弱网环境下的失败率。

4. 决策三：通信协议与流式响应的工程实现

模型部署好了，接口也有了，剩下的核心问题是怎么把"流式生成"这件事在鸿蒙端完美接住。

4.1 HTTP 短连接为什么不够用

一开始我图省事，直接让鸿蒙端发一个普通 POST，等服务端整体生成完毕再返回。用户看到的体验非常糟糕：3B 模型生成 300 个 token 大约需要 6 秒，这 6 秒里聊天界面只有转圈动画，用户早就划出去了。

而且中间一旦网络抖动，整个请求超时重发，成本翻倍。所以结论很明确：必须上流式响应。

4.2 我为什么不用 WebSocket，而是选 SSE

流式响应有两条主流路径，一是 WebSocket，二是 SSE（Server-Sent Events）。

WebSocket 是全双工，双向通信能力强，适合需要频繁双向推送的场景。但大模型对话本质上是"用户发一条、模型回一条"，并不需要服务器主动频繁推送多轮消息。用 WebSocket 反而带来更多问题：需要自己处理二进制分帧、心跳保活、连接释放，ArkTS 侧的状态管理要额外照顾长连接生命周期。

SSE 是 HTTP 基础上的单向流，服务端实现简单，鸿蒙端可以用标准 HTTP 请求配合分段数据回调搞定，不需要额外建连。最终我自己写了后端，用 FastAPI 的StreamingResponse流式返回即可，前端只需要做"读取一段、渲染一段"。

4.3 ArkTS 侧读取 SSE 流的完整实现

鸿蒙的@ohos.net.http模块支持on('dataReceive')事件，这是接流式响应的关键。如果你的后端返回的是标准 SSE 格式，每段数据以data: {json}\n\n为间隔，那么解析逻辑就是把累积的字符串按\n\n切分，再逐条提取data:后面的 JSON。

import http from '@ohos.net.http'; import { util } from '@kit.ArkTS'; class StreamChatClient { private httpRequest: http.HttpRequest | null = null; private buffer = ''; private decoder = util.TextDecoder.create('utf-8'); startChat(messages: Array<object>, onDelta: (text: string) => void, onDone: () => void) { if (this.httpRequest) { this.httpRequest.destroy(); } this.buffer = ''; const request = http.createHttp(); this.httpRequest = request; request.on('dataReceive', (data: ArrayBuffer) => { const chunk = this.decoder.decodeToString(new Uint8Array(data)); this.buffer += chunk; this.parseSSE(onDelta); }); request.on('dataEnd', () => { onDone(); request.destroy(); this.httpRequest = null; }); request.request('https://api.example.com/v1/chat/completions', { method: http.RequestMethod.POST, header: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }, extraData: JSON.stringify({ model: 'qwen2.5-7b', messages: messages, stream: true, temperature: 0.7 }), expectDataType: http.HttpDataType.ARRAY_BUFFER, readTimeout: 60000 }); } private parseSSE(onDelta: (text: string) => void) { const parts = this.buffer.split('\n\n'); this.buffer = parts.pop() || ''; for (const part of parts) { const lines = part.split('\n'); for (const line of lines) { if (line.startsWith('data:')) { const payload = line.substring(5).trim(); if (payload === '[DONE]') return; try { const json = JSON.parse(payload); const delta = json.choices?.[0]?.delta?.content; if (delta) { onDelta(delta); } } catch (e) { // 半包 JSON，忽略，等下一段拼完再解析 } } } } } }

有几个细节是实测后补上的：expectDataType必须设成ARRAY_BUFFER，否则dataReceive拿不到二进制流；readTimeout设到 60 秒，因为长文生成时服务端可能十几秒才吐完所有数据；每次startChat前先destroy上一个连接，否则旧连接的回调会串进下一次对话。

服务端返回格式是标准 OpenAI 兼容 SSE，鸿蒙端完全不关心后端用的什么框架，只认data:前缀里的 JSON 结构，这是当时坚持统一协议的最大红利。

5. 决策四：ArkTS 侧的代码架构与状态管理

协议定了，其实只解决了"数据怎么来"。真正让项目可维护的是 ArkTS 侧的网络层封装和状态管理方案，这块如果设计懒，后面每改一个功能都要崩一次。

5.1 网络层封装成单例：统一鉴权与错误码映射

我没有让每个页面各自建 HTTP 请求，而是封装了一个ChatService单例，所有对话入口都走这一个类。好处有两点：一是 token 鉴权只需维护一处，过期自动刷新后重试；二是错误码能统一归拢，比如 401 跳登录、429 提示"请求太频繁，稍后再试"、超时重试一次后失败再提示。

export class ChatService { private static instance: ChatService; private client: StreamChatClient; static getInstance(): ChatService { if (!ChatService.instance) { ChatService.instance = new ChatService(); } return ChatService.instance; } async sendMessage(userText: string, history: Array<object>, onDelta: (text: string) => void): Promise<void> { try { const messages = this.buildMessages(userText, history); await this.client.startChat(messages, onDelta, this.handleCompletion); } catch (err) { this.handleError(err.code, 'chat_request_failed'); } } }

这套封装让我在后面加"连续提问""停止生成"等功能时非常省事，页面只关心onDelta回调里收到的文本，不碰任何网络细节。

5.2 状态管理：聊天记录的存储与更新策略

聊天记录在鸿蒙开发里绕不开状态驱动。我的方案是这样：

• 当前聊天页内的实时消息列表用@State管理，每条消息是MessageModel对象，包含role、content、timestamp、isStreaming四个字段。
• 聊天会话的历史列表用@StorageLink绑定AppStorage，这样切 Tab、熄屏后再进 App 都还在。
• 持久化用PersistentStorage.persistProp('chat_sessions', [])，保证进程被杀后历史不丢。

关键点在isStreaming字段：流式输出期间，content是被反复更新的同一个字符串对象。ArkUI 的Text组件绑定的是深度观察，如果每来一个 delta 就替换整个数组，状态更新会翻车。我为每条消息单独维护一个@Observed类，@State只持有消息对象的引用，内部字段变化走@ObservedV2的追踪机制，实测性能稳定。

5.3 生命周期处理：切后台、断网、恢复会话

流式请求最怕用户在生成一半时切走。我的处理是：在onPageHide时调用ChatService.stop()，停掉当前请求并标记消息为"已中断"；onPageShow时检查是否有中断标记，有就提供"继续生成"按钮。断网处理则依赖@ohos.net.connection的on('netConnection')监听，一旦网络恢复自动重发未完成消息。

onPageHide(): void { ChatService.getInstance().stopStream(); } onPageShow(): void { const session = ChatService.getInstance().getCurrentSession(); if (session.hasInterrupted) { this.showResumeButton = true; } }

不要小看中断恢复，这决定了用户会不会第二次打开你的 App。断网、切后台、电话打断，只要是真实的手机环境，一定会遇到。

6. 决策五：交互设计与底部导航栏落地

最后一个决策偏产品向，但它直接决定了"接了大模型"这个能力用户能不能感知到。我把对话入口放在了底部导航栏的中间 Tab，这是整个 App 使用率最高的触点。

6.1 用 Tabs 组件搭底部导航栏

HarmonyOS NEXT 的底部导航最合适的组件是Tabs。我用了三个 Tab：首页、AI 对话、我的。关键代码是给每个TabContent设置tabBar，让文字和图标都随选中态切换。

Tabs({ barPosition: BarPosition.End }) { TabContent() { HomePage() } .tabBar(this.buildTabBar('首页', 0)) TabContent() { ChatPage() } .tabBar(this.buildTabBar('AI 对话', 1)) TabContent() { ProfilePage() } .tabBar(this.buildTabBar('我的', 2)) }

这里有个嵌套坑：如果聊天页里有滚动列表，又在Tabs里做左右滑动切换，手势会冲突。我的解决方案是给Tabs设置scrollable(false)，只保留点击切换，避免列表滚动时误触 Tab 切换。

6.2 流式文字渲染：滚动跟随与增量刷新

流式输出时，文字是逐字蹦出来的，两个体验问题必须处理：一是内容变长后页面必须自动滚到底部，否则用户要手动往下拉；二是高频刷新Text组件时不能出现闪烁。

自动滚动我做了节流，每 2 秒或每 200ms 才滚动一次，避免每次 delta 都触发滚动动画导致 UI 卡。代码上用Scroller控制：

private scrollController: Scroller = new Scroller(); onDelta(text: string) { this.currentContent += text; if (Date.now() - this.lastScrollTime > 200) { this.scrollController.scrollEdge(Edge.BOTTOM); this.lastScrollTime = Date.now(); } }

另外，流式期间的Text组件使用wordBreak属性设为BreakWord，防止长英文单词或超长 token 撑破布局。

6.3 Prompt 与上下文裁剪的真实工程技巧

最后谈 Prompt 的工程化。很多人把 Prompt 写在 App 端，每个请求都带一大段指令，这在鸿蒙端是非常浪费的——体积大、token 花费高、弱网下失败率更高。

我把系统 Prompt、few-shot 示例、工具调用格式全部放在服务端，App 端只传user消息和最近 6 轮历史。同时做了一个基于utils.TextDecoder的简易 token 估算函数，发消息前先估一下上下文长度，超过 4000 token 就自动从最早的历史开始裁剪。

这样做的结果是：鸿蒙端请求体始终保持在 2KB 以内，弱网失败率大幅下降，服务端 token 成本也下降了约 30%。这属于不值得写进官方文档，但非常值得抄作业的细节。

7. 实测效果、踩坑清单与可复用的改进方向

决策全部落地后，我在真机上做了一轮完整测试。手里是一台 12GB 内存的 HarmonyOS NEXT 设备，测试场景包括：短对话、200 字短文生成、断网恢复、切后台再带回、连续对话 10 轮。

7.1 真机数据：响应速度、内存与稳定性

实测结果比我预想的要乐观：流式首字延迟约 800ms，完整生成 300 token 平均耗时 5.2 秒；整个聊天页面稳定态内存占用约 260MB，没有明显泄漏；连续对话 10 轮后页面切换无卡顿，断网重连后消息恢复成功率 89%，失败的多半是因为用户已经手动清掉了会话。

首字延迟能压到 800ms，主要归功于流式协议和 vLLM 的 prefill 加速。如果当初坚持等完整输出，延迟至少要翻三倍。

7.2 我踩过的 5 个坑

把这些坑单独列出来，因为它们每个都花了我至少两个小时排查。

1. 忘记配置 INTERNET 权限：第一个请求 100% 报错，报错信息还写得像网络不可用，实际是权限缺失。

2. expectDataType没设成ARRAY_BUFFER：默认值是字符串，导致dataReceive事件拿到的数据被截断，SSE 永远解析不完整。

3. 没有销毁旧连接：连续对话第三轮时，前一轮的回调突然触发，画面出现"串嘴"——上一轮的内容蹦进这一轮的气泡里。排查后才发现是httpRequest对象没有被destroy。

4. Tabs左右滑动和列表滚动冲突：用户体验变成"想滑列表，页面却切了 Tab"。解决就是把Tabs设成点击切换，不做滑动。

5. 长文本超时：默认readTimeout是 30 秒，长文生成到一半连接被掐断。改成 60 秒后问题消失，代价是弱网下等待时间变长，我通过服务端每 3 秒发一次注释行:\n\n实现心跳，避免连接空闲超时。

7.3 后续可以扩展的方向

这个架构稳定跑了一周后，我列了三个下一步计划。一是给聊天记录加全文搜索，因为历史越积越多，不可能靠翻页面找。二是把端侧 0.5B 小模型作为极简问答的兜底真正做起来，毕竟隐私敏感问题走云端始终有顾虑。三是接入多模态能力，让用户可以直接拍题上传图片，模型返回解题步骤，但这一步对后端带宽的要求会高一个量级，需要另起一个独立的图片处理服务。

如果你也要做类似项目，我的建议是先把第五个决策（交互与 Prompt 工程）放到第一位想清楚，再回头做协议和网络层。原因很简单：交互决定用户怎么用，协议和架构只是支撑这个用的手段。顺序反了，后期返工成本比你想的严重得多。