光语助手（LuminaAssist）：基于 HarmonyOS 端云双态架构的多模态智能助理——面向视障与高龄用户的 AI 无障碍解决方案

2601_94974376

95人浏览 · 2026-07-29 17:44:03

2601_94974376 · 2026-07-29 17:44:03 发布

光语助手（LuminaAssist）

基于 HarmonyOS 端云双态架构的多模态智能助理
——面向视障与高龄用户的 AI 无障碍解决方案

我们的答案：光语助手（LuminaAssist）——一款运行在 HarmonyOS 手机上的多模态 AI 助理，核心理念是：

零界面门槛 · 全语音控制 · 全场景视觉代偿

维度	说明
目标用户	视障人士、高龄长者
核心能力	语音控制 + 端侧视觉感知 + 云端语义理解 + 多智能体任务编排
运行平台	HarmonyOS (OpenHarmony 5.0 / API 23+)
端侧模型	MobileNetV2（10.9MB，推理 ~100ms）
云端模型	阿里云百炼 Qwen-VL
TTS 引擎	DashScope cosyvoice-v1 / Qwen3-TTS + 系统本地兜底

二、端云双态：核心架构设计

2.1 什么是「端云双态」 align=“center”>

端侧负责感知与执行（快、离线、隐私）

云端负责理解与规划（强、灵活、可迭代）

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  ┌───────────────────────────┐     HTTP     ┌─────────────────┐ │
│  │  端侧 HarmonyOS ArkTS     │◄──────────►│ 云端 Python FastAPI │ │
│  │                           │              │                 │ │
│  │  ● MobileNetV2 分类 ~100ms │              │ ● LLM 意图理解    │ │
│  │  ● <font color="#047857">Camera Kit</font> 静默拍摄     │              │ ● <font color="#7c3aed">Qwen-VL</font> 视觉分析 │ │
│  │  ● <font color="#047857">TTS</font> 语音播报 + 振动      │              │ ● <font color="#7c3aed">API Key</font> 统一托管  │ │
│  │  ● <font color="#047857">离线关键词规则</font> 兜底      │              │ ● 后端<font color="#dc2626">零存储</font>     │ │
│  └───────────────────────────┘              └─────────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

关键设计决策：

API Key 后端托管：端侧禁止直接持有大模型 API Key，经鸿蒙 HUKS 加密后由后端统一管理

Prompt 集中管理：后端统一维护 Prompt，端侧仅管理视觉识别直连所需 Prompt

图像阅后即焚：Base64 仅在 LLM 调用时临时传输，变量退出作用域即解除引用

2.2 三层降级保障体系

这是项目中最具亮点的设计——任何网络条件下应用都能给用户可用反馈：

                      用户发出语音指令
                            │
                            ▼
     ┌──────────────────────────────────────────────────┐
     │  第一层：后端 /api/v1/agent/plan                  │
     │  调用 FastAPI + Qwen-VL，意图理解能力最强            │
     │  ✅ 结构化任务规划 + TTS 播报文本                     │
     └────────────────────┬─────────────────────────────┘
                          │ 网络不可达 / 后端宕机
                          ▼
     ┌──────────────────────────────────────────────────┐
     │  第二层：端侧 LLM 直连大模型                     │
     │  后端挂了但网络还在，端侧自行调用云端模型               │
     │  ✅ 使用与后端一致的 Prompt 产出结构化 tasks           │
     └────────────────────┬─────────────────────────────┘
                          │ <font color="#dc2626">模型不可用 / 网络全断</font>
                          ▼
     ┌──────────────────────────────────────────────────┐
     │  <font color="#047857">第三层：OfflinePlanner 关键词规则</font>               │
     │  纯本地关键词匹配，覆盖 8 类高频场景                   │
     │  ✅ 紧急电话 / 短信 / 打车 / 物品识别 / 读屏          │
     └──────────────────────────────────────────────────┘

视觉识别同样具备三层降级：

端侧 MobileNetV2 (~100ms) ──置信度不足──► 云端 Qwen-VL ──不可达──► 本地 VLM ──失败──► 本地分类兜底

【铁律】 任何异常都必须通过 TTS 语音告知用户，振动作为触觉辅助反馈——绝对禁止静默失败。

三、技术栈全景

3.1 端侧技术选型

层级	技术选型	说明
运行环境	HarmonyOS NEXT API 23+	compileSdk 6.1.1
开发语言	ArkTS（TypeScript 超集）	强类型、Null Safety
UI 框架	ArkUI Stage 模型	声明式 UI，XComponent 相机预览
IDE	DevEco Studio 5.0+	鸿蒙官方 IDE
本地推理	MindSpore Lite	CPU 4 线程推理引擎
端侧模型	MobileNetV2	10.9MB，224×224 输入，~100ms
相机	Camera Kit	后置静默拍摄，双路 Preview+Photo
TTS 云端	DashScope cosyvoice-v1 / Qwen3-TTS	HTTP API，MP3 流 + AVPlayer
TTS 本地	CoreSpeechKit TextToSpeech	系统本地兜底
ASR	CoreSpeechKit SpeechRecognizer	真机按住说话
加密存储	HUKS + Preferences	API Key 加密持久化

3.2 后端技术选型

层级	技术选型	说明
Web 框架	FastAPI (Python 3.10+)	异步高性能，自动 OpenAPI 文档
服务器	Uvicorn	ASGI 服务器，监听 8000 端口
数据校验	Pydantic	请求/响应体 Schema 校验
大模型	阿里云百炼 OpenAI 兼容接口	Qwen-VL + 文本规划
测试	pytest + httpx.AsyncClient	全接口覆盖

3.3 项目规模统计

指标	数据
端侧核心代码	4000+ 行
Agent 层	~700 行
Services 层	~2800 行
后端模块	4 个（routers × 2 / services × 2 / schemas × 2）
类型定义	20+ 接口/类型
意图类型	11 种
动作类型	10 种
药品流水线	6 步全链路

四、功能模块详解

4.1 Agent 智能体层——总指挥部

Agent 层实现「用户指令 → 意图识别 → 任务规划 → 任务执行」的完整闭环。

模块	代码量	职责
`Agent.ets`	单例总指挥	服务注册、意图处理、任务编排
`IntentRouter.ets`	228 行	三层降级路由：后端 → 端侧 LLM → 离线规则
`TaskPlanner.ets`	任务执行器	按 action 字段分发 10 种动作类型
`OfflinePlanner.ets`	152 行	离线关键词匹配，覆盖 8 类高频场景
`types.ets`	294 行	20+ 接口/类型集中定义

支持的 11 种意图类型：

// 意图类型枚举（节选自 types.ets）
export enum Intent {
  READING_ASSIST    = "reading_assist",     // 朗读辅助
  MEDICINE_RECOG    = "medicine_recognition", // 药品识别
  OBJECT_RECOG      = "object_recognition",   // 物品识别
  EMERGENCY         = "emergency",           // 紧急求助
  SCENE_DESCRIPTION = "scene_description",   // 场景描述
  NAVIGATION        = "navigation",          // 无障碍导航
  WEATHER_QUERY     = "weather_query",       // 天气查询
  TIME_QUERY        = "time_query",          // 时间查询
  CONTACT_CALL      = "contact_call",        // 拨打电话
  SEND_MESSAGE      = "send_message",        // 发送短信
  GENERAL_QA        = "general_qa"           // 通用问答
}

4.2 视觉服务——项目最重模块（1553 行）eNetV2 推理 (~100ms)

          │
          ├─ 置信度 ≥ 60% → 直接播报 Top-3 结果
          └─ 置信度不足   → <font color="#7c3aed">云端 Qwen-VL 详细描述 (~2s)</font>


<font color="#1a56db">**药品识别全链路（6 步流水线）**</font>——这是项目中最复杂的单条链路：

┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ① 全场景扫描 │───►│ ② 药品定位 │───►│ ③ 包围框裁剪 │
│ 识别所有物体 │ │ 找出药品+包围框 │ │ 精准裁剪药品区域│
│ 和文字内容 │ │ 多物体画面定位 │ │ Base64 裁剪 │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ⑥ 输出筛选 │◄───│ ⑤ 联网核对 │◄───│ ④ 文字抽取 │
│ LLM 二次审核 │ │ 药监局/说明书 │ │ OCR 提取包装文字│
│ 非药品内容丢弃 │ │ 数据库核实 │ │ 结构化提取 │
└──────────────┘ └──────────────┘ └──────────────┘


> <font color="#dc2626">**为什么需要 6 步？**</font>保证<font color="#dc2626">**只输出与药品相关的信息**</font>，避免 AI 幻觉导致的错误用药建议。第 ⑥ 步是安全闸门。

### 4.3 语音服务（893 行）

**TTS 播报优先级**：

Qwen3-TTS ──不可用──► CosyVoice ──不可用──► 系统本地 TextToSpeech


播报采用串行队列，避免多段 speak 互相打断。ASR 基于 CoreSpeechKit SpeechRecognizer，真机按住说话。

### 4.4 后端服务

| 接口 | 方法 | 说明 |
|---|---|---|
| `/health` | GET | 健康检查，返回 `{status, api_key_configured}` |
| `/api/v1/agent/plan` | POST | 接收用户文本，返回结构化任务计划 |
| `/api/v1/vision/analyze` | POST | 接收图像 Base64，返回 TTS 播报文本 |

后端采用经典三层架构：

routers（请求接入） → services（业务编排） → schemas（数据校验）


---

## 五、无障碍设计：四大原则

这不是锦上添花，而是从<font color="#dc2626">**第一行代码就刻进架构里的基因**</font>：

| 原则 | 描述 | 落地措施 |
|---|---|---|
| VUI 优先 | 语音是第一输入通道 | 全链路 TTS 语音引导，无需看屏幕 |
| 大热区 | 可点击区域 ≥ 96vp×96vp | BigButton 组件，间距 ≥ 16vp |
| 高对比 | WCAG AAA 级对比度 | 暖金 `#E5A93C` 对深黑 `#0A0A0C`，正文 ≥ 20fp |
| <font color="#047857">TTS 兜底</font> | 所有错误必须语音告知 | 所有异常路径调用 `speak()` |

---

## 六、安全与隐私设计

在 AI 应用中，隐私是不可忽视的红线：

| 安全措施 | 实现方式 |
|---|---|
| API Key 安全 | HUKS 加密后写入 Preferences，禁止硬编码 |
| 数据最小化 | 端侧能处理的数据绝不上云 |
| 图像阅后即焚 | Base64 仅在 LLM 调用时临时传输，变量退出作用域即解除引用 |
| <font color="#7c3aed">后端零存储</font> | 后端仅做请求转发，<font color="#7c3aed">不落盘任何用户数据</font> |
| <font color="#1a56db">权限分层</font> | 按需申请 6 项权限，不越界 |

```json5
// 6 项系统权限（module.json5）
{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" },    // 语音输入
    { "name": "ohos.permission.CAMERA" },        // 视觉识别
    { "name": "ohos.permission.INTERNET" },      // 云端通信
    { "name": "ohos.permission.VIBRATE" },       // 触觉反馈
    { "name": "ohos.permission.LOCATION" },      // 紧急定位
    { "name": "ohos.permission.READ_CONTACTS" }  // 紧急联系人
  ]
}

七、交互流程示例

7.1 物品识别完整链路

用户长按说话："前面是什么？"
    │
    ▼
ASR 转文本
    │
    ▼
Agent → IntentRouter.route("前面是什么")
    │
    ▼
第一层：POST /api/v1/agent/plan
    → 返回: { tasks: [{action:"capture_image"}, {action:"image_classify"}],
              tts_message: "好的，帮您看看" }
    │
    ▼
<font color="#ea580c">TTS 播报："好的，帮您看看"</font>
    │
    ▼
<font color="#1a56db">TaskPlanner 执行：</font>
    ① capture_image → VisionService.captureFrame()
       → 后置静默拍照 → base64 JPEG
    ② image_classify → VisionService.classifyImage():
       ├─ <font color="#047857">MobileNetV2 推理 ~100ms</font> → Top-3 结果
       │  置信度 ≥ 60% → <font color="#047857">"画面中可能包含：水杯(92.3%)、桌面(5.1%)..."</font>
       └─ 置信度不足 → <font color="#7c3aed">Qwen-VL (~2s)</font> 详细描述
    │
    ▼
<font color="#dc2626">TTS 播报识别结果</font>

7.2 药品识别多轮问答

用户："帮我看看这个药"
    → 拍照 → 药品全场景扫描 → 定位药品 → 裁剪 → 抽取包装文字
    → 联网核对药监局数据 → 结构化提取
    → TTS："这是阿莫西林胶囊，用于治疗细菌感染，
             一次一粒一日三次，饭前服用"
    → 进入多轮问答模式

用户："有什么副作用？"
    → LLM 复用已有药品上下文，无需重新拍照
    → TTS："可能出现恶心、呕吐、腹泻等不良反应..."

7.3 紧急求助闭环

用户："救命！帮我叫车去最近的医院，告诉我女儿"
    → IntentRouter 解析为 emergency 意图
    → Plan: [get_location, send_sms, <font color="#dc2626">place_call</font>, <font color="#047857">hail_taxi</font>]
    → 并行执行：GPS 定位 → 求助短信 → 拨打 120 → 高德 URI 打车

八、实验验证

项目已通过 8 项系统性功能验证，结果全部通过：

编号	实验场景	结果	关键发现
E-01	后端健康检查	✅ 通过	API Key 配置正常
E-02	任务规划接口	✅ 通过	自然语言可产出结构化 tasks + tts_message
E-03	说明书朗读	✅ 通过	拍摄清晰时朗读可用
E-04	物体识别	✅ 通过	本地分类快，弱网仍可用
E-05	药品识别	✅ 通过	界面卡片与语音一致
E-06	自由问答	✅ 通过	问答路径正常
E-07	后端不可达	✅ 通过	有失败提示，不闪退
E-08	无相机权限	✅ 通过	有反馈说明，应用稳定

结论：端侧感知+执行、后端理解+规划的分工在实践中可行；「永远有声音」的错误兜底机制已生效。

九、项目亮点总结

序号	亮点	详情
①	端云双态架构	端侧 MobileNetV2 (10.9MB/~100ms) 负责 90%+ 日常识别，云端 Qwen-VL 兜底；API Key 后端托管，隐私不离开设备
②	三层降级保障	后端 → 端侧 LLM → 离线关键词规则，任何网络条件下都有可用语音反馈
③	无障碍极致设计	零界面、全语音、大按钮(≥96vp)、WCAG AAA 对比度、TTS 永不静默
④	药品识别全链路	6 步流水线（扫描→定位→裁剪→抽取→核对→筛选），保证只输出药品相关内容
⑤	HarmonyOS 原生集成	MindSpore Lite + CoreSpeechKit + HUKS + Camera Kit，全链路系统原生
⑥	安全设计	HUKS 加密 + 图像阅后即焚 + 后端零存储 + 权限按需申请

十、技术栈速览

层	技术
前端	ArkTS / ArkUI Stage / DevEco Studio
端侧 AI	MindSpore Lite / MobileNetV2 (10.9MB)
后端	Python FastAPI / Uvicorn / Pydantic
云端 AI	阿里云百炼 Qwen-VL / DashScope TTS
语音	CoreSpeechKit (ASR + 本地 TTS)
相机	HarmonyOS Camera Kit（双路静默拍摄）
安全	HUKS 密钥管理 / 图像阅后即焚
测试	pytest + httpx.AsyncClient