82 KiB
Executable File
82 KiB
Executable File
🏠 家庭化全能人工智能助手 —— 完整架构设计方案
一、系统总体架构概览
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📱 客户端层 (Client Layer) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Web App │ │ iOS App │ │Android │ │ Desktop │ │ 智能音箱 │ │
│ │ (React) │ │(SwiftUI) │ │(Kotlin) │ │(Electron)│ │ (嵌入式) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └──────────────┴──────────────┴──────────────┴──────────────┘ │
│ │ │
│ ┌───────────────┴───────────────┐ │
│ │ 🔌 统一通信网关 │ │
│ │ (WebSocket + HTTP/2 + gRPC) │ │
│ └───────────────┬───────────────┘ │
└────────────────────────────────────┼────────────────────────────────────────┘
│
┌────────────────────────────────────┼────────────────────────────────────────┐
│ 🖥️ 服务端层 (Server Layer) │
│ │ │
│ ┌────────────────────────────────┴────────────────────────────────┐ │
│ │ 🚪 API 网关 (API Gateway) │ │
│ │ 认证鉴权 · 限流 · 路由 · 负载均衡 · 协议转换 │ │
│ └────────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ┌─────────────┬───────────────┼───────────────┬─────────────┐ │
│ │ │ │ │ │ │
│ ┌──▼──┐ ┌────▼────┐ ┌─────▼─────┐ ┌────▼────┐ ┌────▼────┐ │
│ │对话 │ │ 语音处理 │ │ 🧠核心AI │ │ 工具调用 │ │ 记忆管理 │ │
│ │管理 │ │ ASR/TTS │ │ 引擎 │ │ &插件 │ │ 系统 │ │
│ │模块 │ │ 模块 │ │ LLM推理 │ │ 系统 │ │ │ │
│ └──┬──┘ └────┬────┘ └─────┬─────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │ │
│ └────────────┴──────────────┼──────────────┴─────────────┘ │
│ │ │
│ ┌──────────────────┼──────────────────┐ │
│ │ │ │ │
│ ┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐ │
│ │ PostgreSQL│ │ Redis │ │ MinIO/ │ │
│ │ (结构化) │ │ (缓存) │ │ S3(文件) │ │
│ └─────────┘ └───────────┘ └───────────┘ │
└───────────────────────────────────────────────────────────────────────────┘
│
┌────────────────────────────────────┼────────────────────────────────────────┐
│ 🏗️ 基础设施 & 外部集成层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ LLM API │ │ TTS/ASR │ │IoT Platform│ │ 跨域设备 │ │第三方服务│ │
│ │(多模型) │ │ 服务 │ │(MQTT/CoAP)│ │ 互联API │ │ (天气等)│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└───────────────────────────────────────────────────────────────────────────┘
二、后端架构详解
2.1 架构设计理念 —— 微服务 + 事件驱动
┌─────────────────────────────────────────────────────────────────┐
│ 🧭 后端技术栈全景 │
├─────────────────────────────────────────────────────────────────┤
│ 语言: Go (核心高性能服务) + Python (AI/ML Pipeline) │
│ 框架: Gin/Fiber (Go) + FastAPI (Python) │
│ 消息队列: NATS / RabbitMQ (事件驱动) │
│ 容器化: Docker + Kubernetes │
│ 配置中心: Consul / etcd │
│ 服务网格: Istio (可选) │
│ 可观测性: Prometheus + Grafana + Jaeger + ELK │
└─────────────────────────────────────────────────────────────────┘
2.2 核心模块详细设计
🔹 模块A：API网关 (Gateway Service)
┌────────────────────────────────┐
│ API Gateway │
│ │
Client ──────────►│ ┌────────────────────────┐ │
│ │ 路由分发 & 协议转换 │ │
│ │ REST / WS / gRPC │ │
│ └────────────────────────┘ │
│ ┌────────────────────────┐ │
│ │ JWT 认证 & 会话管理 │ │
│ └────────────────────────┘ │
│ ┌────────────────────────┐ │
│ │ 限流 & 熔断 & 降级 │ │
│ └────────────────────────┘ │
│ ┌────────────────────────┐ │
│ │ 请求日志 & 链路追踪 │ │
│ └────────────────────────┘ │
└────────────────────────────────┘
职责：
- 统一入口，支持 REST API、WebSocket（实时对话）、gRPC（内部高性能调用）
- JWT 签发与验证，支持多端登录
- 基于令牌桶的限流，防止滥用
- 请求/响应的统一日志记录，注入 TraceID
🔹 模块B：核心AI引擎 (Core AI Engine) ⭐ 最核心
┌─────────────────────────────────────────────────────────────────────┐
│ 🧠 核心AI引擎架构 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 对话编排器 (Orchestrator) │ │
│ │ · 接收用户输入 → 组装上下文 → 调度各子模块 → 生成回复 │ │
│ └──────────┬──────────────────────────────────────┬───────────┘ │
│ │ │ │
│ ┌──────────▼──────────┐ ┌───────────▼───────────┐ │
│ │ 🎭 人格注入模块 │ │ 📋 上下文构建模块 │ │
│ │ Persona Injector │ │ Context Builder │ │
│ │ │ │ │ │
│ │ · 加载知识文档 │ │ · 近期对话历史(N) │ │
│ │ · 角色卡解析 │ │ · 长期记忆摘要(M) │ │
│ │ · 系统Prompt构建 │ │ · 用户画像 │ │
│ │ · 称呼/语气规则 │ │ · 时间/环境上下文 │ │
│ │ · 回复格式约束 │ │ · Token预算管理 │ │
│ └──────────┬──────────┘ └───────────┬───────────┘ │
│ │ │ │
│ ┌──────────▼──────────────────────────────────────▼───────────┐ │
│ │ LLM 适配层 (LLM Adapter) │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ OpenAI │ │Claude │ │ 本地模型 │ │ 自定义 │ │ │
│ │ │ API │ │ API │ │(Ollama/ │ │ 模型 │ │ │
│ │ │ │ │ │ │ vLLM) │ │ │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ │ · 统一接口抽象 (Chat Completion Interface) │ │
│ │ · 流式输出支持 (SSE → WS) │ │
│ │ · 多模型负载均衡 & 故障切换 │ │
│ │ · Function Calling / Tool Use 协议适配 │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 回复策略决策器 (Response Strategist) │ │
│ │ │ │
│ │ · 判断回复形式：纯文字 / 文字+TTS / 纯语音 │ │
│ │ · 判断是否需要断句（语音助手模式 vs 聊天框模式） │ │
│ │ · 判断是否需要调用工具/API │ │
│ │ · 输出格式标记（带断句标记的文本） │ │
│ └──────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
人格注入模块详解：
知识文档结构 (persona.yaml / persona.md):
┌─────────────────────────────────────────┐
│ 角色定义 (Character Definition) │
│ ├─ 名称: 小咪 │
│ ├─ 身份: 家庭AI管家 / 猫娘 │
│ ├─ 性格: 温柔、细心、偶尔傲娇 │
│ ├─ 说话风格: 口语化、带"喵~"口癖 │
│ ├─ 称呼规则: │
│ │ ├─ 对主人: "主人"/"哥哥"/"姐姐" │
│ │ └─ 对陌生人: "客人" │
│ ├─ 背景故事: (赋予角色深度) │
│ └─ 行为准则: (安全边界、伦理约束) │
├─────────────────────────────────────────┤
│ 能力声明 (Capability Declaration) │
│ ├─ 可控制设备列表 │
│ ├─ 可调用API列表 │
│ └─ 能力边界说明 │
├─────────────────────────────────────────┤
│ 回复格式模板 (Response Templates) │
│ ├─ 日常问候模板 │
│ ├─ 任务确认模板 │
│ └─ 错误/无法完成时的模板 │
└─────────────────────────────────────────┘
🔹 模块C：语音处理模块 (Voice Processing)
┌─────────────────────────────────────────────────────────────────┐
│ 🎙️ 语音处理流水线 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 语音输入 (ASR Pipeline) │ │
│ │ │ │
│ │ 音频输入 → VAD检测 → 降噪 → ASR引擎 → 文本输出 │ │
│ │ (Base64) (分段) (RNNoise) (Whisper/ (带时间戳) │ │
│ │ Azure/讯飞) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 语音输出 (TTS Pipeline) │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 聊天框模式 │ │ 语音助手模式 │ │ │
│ │ │ │ │ │ │ │
│ │ │ 整段文本 │ │ 断句引擎 │ │ │
│ │ │ ↓ │ │ · 按句号切分 │ │ │
│ │ │ TTS引擎 │ │ · 生成句子队列│ │ │
│ │ │ ↓ │ │ ↓ │ │ │
│ │ │ 完整音频 │ │ 逐句TTS │ │ │
│ │ │ ↓ │ │ ↓ │ │ │
│ │ │ 返回URL/流 │ │ 流式推送播放 │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ TTS引擎适配: Edge-TTS / VITS / Bert-VITS2 / GPT-SoVITS │ │
│ │ · 支持角色音色定制 (可微调) │ │
│ │ · 支持情感参数 (语速/音调/音量) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
语音助手模式断句与流式播放时序图：
时间轴 ──────────────────────────────────────────────────────────►
LLM输出: "好的主人。我这就帮您打开客厅的灯。现在室温是26度。需要我调低一些吗喵~"
│ │ │ │
▼ ▼ ▼ ▼
断句队列: [句子1] [句子2] [句子3] [句子4]
│ │ │ │
▼ ▼ ▼ ▼
TTS生成: 🔊S1 🔊S2 🔊S3 🔊S4
│ │ │ │
▼ ▼ ▼ ▼
客户端: 播放S1───►播放S2──────────────►播放S3───────────►播放S4
│
▼
用户体验: 听到"好的主人。"时，后续句子已在生成中...
(首句延迟 ~800ms，后续几乎无等待)
🔹 模块D：记忆管理系统 (Memory Management) ⭐ 长期记忆核心
┌─────────────────────────────────────────────────────────────────┐
│ 🧠 记忆管理系统架构 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 记忆提取器 (Memory Extractor) │ │
│ │ │ │
│ │ 对话流 → 关键信息识别 → 实体抽取 → 关系抽取 → 摘要 │ │
│ │ (基于LLM的小模型或规则+LLM混合) │ │
│ └──────────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────▼──────────────────────────────────┐ │
│ │ 记忆分类器 & 分级器 │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ 用户画像 │ │ 事实记忆 │ │ 偏好记忆 │ │ 事件记忆 │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │·姓名 │ │·发生过 │ │·喜欢的 │ │·时间线 │ │ │
│ │ │·年龄 │ │ 的事实 │ │ 事物 │ │ 相关 │ │ │
│ │ │·身份 │ │·家庭成 │ │·习惯 │ │ 事件 │ │ │
│ │ │·关系 │ │ 员信息 │ │·设置 │ │ 记录 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ 重要性分级: 🔴核心(永久) 🟡重要(长期) 🟢普通(中期) │ │
│ │ ⚪临时(会话级) │ │
│ └──────────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────▼──────────────────────────────────┐ │
│ │ 记忆存储层 (Memory Store) │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ PostgreSQL │ │ 向量数据库 │ │ 文件存储 │ │ │
│ │ │ (结构化记忆) │ │ (Milvus/ │ │ (Markdown/ │ │ │
│ │ │ │ │ Qdrant) │ │ JSON) │ │ │
│ │ │ · 用户表 │ │ · 语义检索 │ │ · 原始记录 │ │ │
│ │ │ · 记忆条目表 │ │ · 相似记忆 │ │ · 归档文件 │ │ │
│ │ │ · 关系表 │ │ · 关联推荐 │ │ │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └──────────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────▼──────────────────────────────────┐ │
│ │ 记忆检索器 (Memory Retriever) │ │
│ │ │ │
│ │ 用户输入 → 关键词匹配 + 语义向量检索 → 混合排序 │ │
│ │ → 注入到LLM上下文 (带记忆来源标注) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 记忆文件系统结构 (可迁移设计) │ │
│ │ │ │
│ │ /data/memory/ │ │
│ │ ├── users/ # 按用户分目录 │ │
│ │ │ └── {user_id}/ │ │
│ │ │ ├── profile.json # 用户画像 │ │
│ │ │ ├── facts/ # 事实记忆 │ │
│ │ │ │ ├── core/ # 🔴 核心记忆 │ │
│ │ │ │ ├── important/ # 🟡 重要记忆 │ │
│ │ │ │ └── normal/ # 🟢 普通记忆 │ │
│ │ │ ├── preferences.json # 偏好记忆 │ │
│ │ │ ├── events/ # 事件时间线 │ │
│ │ │ └── conversation_log/ # 对话日志(可配置保留期) │ │
│ │ ├── global/ # 全局记忆(跨用户) │ │
│ │ └── index.db # SQLite索引(快速检索) │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
🔹 模块E：工具调用 & 插件系统 (Tool & Plugin System)
┌─────────────────────────────────────────────────────────────────┐
│ 🔧 工具调用 & 插件系统 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 工具注册中心 (Tool Registry) │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ 内置工具 (Built-in Tools) │ │ │
│ │ │ │ │ │
│ │ │ 🏠 家庭物联网 (IoT) │ │ │
│ │ │ ├─ 灯光控制 (on/off/brightness/color) │ │ │
│ │ │ ├─ 空调/温控 (mode/temp/fan) │ │ │
│ │ │ ├─ 窗帘/窗户 (open/close/percentage) │ │ │
│ │ │ ├─ 智能门锁 (lock/unlock/status) │ │ │
│ │ │ ├─ 摄像头 (snapshot/stream) │ │ │
│ │ │ └─ 传感器查询 (temp/humidity/motion) │ │ │
│ │ │ │ │ │
│ │ │ 🌐 跨域设备互联 │ │ │
│ │ │ ├─ 手机通知推送 │ │ │
│ │ │ ├─ 车载系统交互 │ │ │
│ │ │ ├─ 办公设备控制 │ │ │
│ │ │ └─ 穿戴设备数据读取 │ │ │
│ │ │ │ │ │
│ │ │ 🛠️ 系统操作 │ │ │
│ │ │ ├─ 文件读写 │ │ │
│ │ │ ├─ 程序调用/脚本执行 │ │ │
│ │ │ ├─ 定时任务设置 │ │ │
│ │ │ └─ 网络请求 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ 插件接口 (Plugin Interface) │ │ │
│ │ │ │ │ │
│ │ │ · 热加载/卸载 (动态.so / WASM) │ │ │
│ │ │ · 统一Tool Schema (兼容OpenAI Function Call) │ │ │
│ │ │ · 权限声明 & 沙箱隔离 │ │ │
│ │ │ · 版本管理 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 调用执行引擎 (Execution Engine) │ │
│ │ │ │
│ │ LLM输出 → 解析Function Call → 参数验证 → 权限检查 │ │
│ │ → 执行调用 → 结果序列化 → 注入回对话上下文 │ │
│ │ │ │
│ │ 安全机制: │ │
│ │ · 危险操作需用户二次确认 │ │
│ │ · 操作日志全记录 │ │
│ │ · 调用频率限制 │ │
│ │ · 回滚/撤销支持 │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
🔹 模块F：对话会话管理 (Session Management)
┌─────────────────────────────────────────────────────────────────┐
│ 对话会话管理 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Session 生命周期 │ │
│ │ │ │
│ │ 创建会话 → 维护上下文窗口 → 过期/归档 → 持久化 │ │
│ │ │ │
│ │ · 会话ID: UUID, 关联用户 + 设备 + 平台 │ │
│ │ · 上下文窗口: 滑动窗口 + 智能压缩(摘要化旧消息) │ │
│ │ · 多端同步: 同一用户不同设备可接入同一会话 │ │
│ │ · 会话切换: 支持多会话并存, 用户可切换 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 对话模式识别 & 切换 │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 文字聊天模式 │ │ 语音消息模式 │ │语音助手模式 │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │输入: 文字 │ │输入: 语音 │ │输入: 语音流 │ │ │
│ │ │输出: 文字 │ │输出: 文字 │ │输出: 语音流 │ │ │
│ │ │ +可选TTS │ │ +TTS音频 │ │ +断句流式 │ │ │
│ │ │ │ │ │ │ +文字原文 │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
2.3 数据流全景图
┌──────────────────────────────────────────────────────────────────────────┐
│ 📊 完整数据流 │
│ │
│ 用户输入 │
│ │ │
│ ├── 文字 ──────────────────────────────────────────┐ │
│ │ │ │
│ └── 语音 ──► ASR ──► 文本 ─────────────────────────┤ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 上下文构建器 │ │
│ │ │ │
│ │ ← 人格知识文档 │ │
│ │ ← 长期记忆检索 │ │
│ │ ← 近期对话历史 │ │
│ │ ← 用户画像 │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ LLM 推理 │ │
│ │ │ │
│ │ 需要调用工具? │ │
│ │ ├── 是──►工具调用│ │
│ │ │ 引擎 │ │
│ │ │ │ │ │
│ │ │ IoT/设备API │ │
│ │ │ 程序调用 │ │
│ │ │ │ │ │
│ │ │ 结果返回─────┤ │
│ │ └────────────────┤ │
│ │ │ │
│ │ 生成最终回复 │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌──────────────────┼──────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │ 记忆提取 │ │ 回复策略 │ │文本回复│ │
│ │ &存储 │ │ 决策 │ │ │ │
│ └──────────┘ └────┬─────┘ └───┬────┘ │
│ │ │ │
│ ┌──────────┼──────────┐ │ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ 纯文本 文字+TTS 语音助手 文字 │
│ 回复 回复 模式 输出 │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ 整段TTS 断句引擎 │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ 音频URL 句子队列 │
│ │ │ (流式推送) │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────┐ │
│ │ 返回给客户端 │ │
│ │ { text, audio_url?, │ │
│ │ segments?: [{text,audio}]}│ │
│ └──────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
三、前端架构设计
3.1 跨端架构策略
┌─────────────────────────────────────────────────────────────────┐
│ 📱 跨端架构：渐进式适配策略 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 共享层 (Shared Layer) │ │
│ │ │ │
│ │ · 业务逻辑 (TypeScript) · 状态管理 (Zustand/Pinia) │ │
│ │ · API Client · WebSocket Manager │ │
│ │ · 音频处理 Pipeline · 本地缓存策略 │ │
│ │ · 类型定义 (Proto/TS) · 工具函数库 │ │
│ └──────────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ┌──▼──────┐ ┌────▼─────┐ ┌─────▼─────┐ │
│ │ Web App │ │Mobile App│ │Desktop App│ │
│ │ │ │ │ │ │ │
│ │ React │ │React │ │ Electron │ │
│ │ + Vite │ │Native │ │ + Tauri │ │
│ │ │ │/Flutter │ │ │ │
│ │ PWA支持 │ │ │ │系统托盘 │ │
│ │ │ │ │ │全局快捷键 │ │
│ └─────────┘ └──────────┘ └───────────┘ │
│ │
│ 特色能力: │
│ · PWA: 离线可用, 添加到主屏幕, 推送通知 │
│ · React Native: 原生音频, 后台运行, Widget │
│ · Electron/Tauri: 系统级集成, 本地文件访问, 系统通知 │
└─────────────────────────────────────────────────────────────────┘
3.2 前端核心功能模块
┌─────────────────────────────────────────────────────────────────┐
│ 🖥️ 前端功能模块全景 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🏠 主界面布局 │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────────────────┐ ┌──────────┐ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ 侧边栏 │ │ 对话主区域 │ │ 上下文 │ │ │
│ │ │ │ │ │ │ 面板 │ │ │
│ │ │·会话列表│ │ ┌────────────────┐ │ │ │ │ │
│ │ │·角色切换│ │ │ 消息列表 │ │ │·设备状态│ │ │
│ │ │·设备管理│ │ │ (文字+语音 │ │ │·当前任务│ │ │
│ │ │·记忆查看│ │ │ +图片+卡片) │ │ │·快捷操作│ │ │
│ │ │·设置 │ │ └────────────────┘ │ │·天气时间│ │ │
│ │ │ │ │ ┌────────────────┐ │ │ │ │ │
│ │ │ │ │ │ 输入区域 │ │ │ │ │ │
│ │ │ │ │ │ [文字/语音] │ │ │ │ │ │
│ │ │ │ │ │ [发送] │ │ │ │ │ │
│ │ │ │ │ └────────────────┘ │ │ │ │ │
│ │ └──────────┘ └──────────────────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🎙️ 语音交互模块 │ │
│ │ │ │
│ │ 语音输入: │ │
│ │ · 按住说话 (Push-to-Talk) │ │
│ │ · 语音助手模式 (VAD自动检测, 持续对话) │ │
│ │ · 波形可视化反馈 │ │
│ │ · 降噪处理 (WebAudio API / 原生音频模块) │ │
│ │ │ │
│ │ 语音输出: │ │
│ │ · 流式音频播放 (逐句播放队列) │ │
│ │ · 播放进度指示 │ │
│ │ · 可打断/暂停 │ │
│ │ · 文字原文同步显示 (逐句高亮) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🏠 IoT设备控制面板 │ │
│ │ │ │
│ │ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ │
│ │ │灯光│ │空调│ │窗帘│ │门锁│ │摄像头│ │ │
│ │ │💡 │ │🌡️ │ │🪟 │ │🔐 │ │📷 │ │ │
│ │ │75% │ │26° │ │关闭│ │锁定│ │在线│ │ │
│ │ └────┘ └────┘ └────┘ └────┘ └────┘ │ │
│ │ │ │
│ │ · 实时状态轮询/WebSocket推送 │ │
│ │ · 快捷场景 (回家模式/离家模式/睡眠模式) │ │
│ │ · 设备分组 (按房间) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
3.3 前端技术栈
┌─────────────────────────────────────────────────────────────────┐
│ 🛠️ 前端技术栈推荐 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 核心框架: │
│ ├── React 18+ / Vue 3+ │
│ ├── TypeScript (严格模式) │
│ └── Vite (构建工具) │
│ │
│ UI 框架: │
│ ├── TailwindCSS + shadcn/ui / Ant Design │
│ ├── 响应式设计 (Mobile First) │
│ └── 暗色/亮色主题切换 │
│ │
│ 状态管理: │
│ ├── Zustand (轻量) / Pinia (Vue) │
│ └── TanStack Query (服务端状态) │
│ │
│ 通信层: │
│ ├── WebSocket (实时对话 + 流式音频) │
│ ├── HTTP/2 REST (普通API) │
│ └── Server-Sent Events (LLM流式输出) │
│ │
│ 音频处理: │
│ ├── Web Audio API (浏览器) │
│ ├── expo-av (React Native) │
│ ├── 音频格式: Opus (低延迟) / AAC / MP3 │
│ └── AudioWorklet (低延迟音频处理) │
│ │
│ 跨平台: │
│ ├── PWA (Web → 移动端/桌面端) │
│ ├── React Native / Flutter (原生移动端) │
│ ├── Electron / Tauri (桌面端) │
│ └── Capacitor (Web → 混合移动端) │
│ │
│ 国际化: │
│ └── i18next (多语言支持) │
│ │
│ 测试: │
│ ├── Vitest (单元测试) │
│ ├── Playwright (E2E测试) │
│ └── Storybook (组件文档) │
└─────────────────────────────────────────────────────────────────┘
四、服务端可迁移性设计
┌─────────────────────────────────────────────────────────────────┐
│ 📦 服务端可迁移性设计 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Docker 容器化 (一级保障) │ │
│ │ │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌───────┐ │ │
│ │ │Gateway │ │AI Core │ │TTS/ASR │ │Memory │ │Tool │ │ │
│ │ │ │ │ │ │ │ │ │ │Engine │ │ │
│ │ └────────┘ └────────┘ └────────┘ └────────┘ └───────┘ │ │
│ │ ▲ ▲ ▲ ▲ ▲ │ │
│ │ └──────────┴──────────┴──────────┴──────────┘ │ │
│ │ docker-compose │ │
│ │ │ │
│ │ 单机部署: docker-compose up -d (一行命令启动全部服务) │ │
│ │ 集群部署: Kubernetes Helm Charts │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 数据持久化策略 (二级保障) │ │
│ │ │ │
│ │ · 所有数据挂载外部Volume │ │
│ │ · 数据库: 定期自动备份 + 手动导出 │ │
│ │ · 记忆文件: /data/memory/ → 直接打包迁移 │ │
│ │ · 配置文件: 环境变量 + .env 文件 │ │
│ │ │ │
│ │ 迁移步骤: │ │
│ │ 1. 停止服务 │ │
│ │ 2. 复制 /data/ 目录到新服务器 │ │
│ │ 3. 复制 docker-compose.yml + .env │ │
│ │ 4. docker-compose up -d │ │
│ │ ✅ 完成！ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 配置即代码 (三级保障) │ │
│ │ │ │
│ │ · 所有配置版本化 (Git) │ │
│ │ · 环境变量分层: .env.base / .env.prod / .env.dev │ │
│ │ · 一键部署脚本 (deploy.sh) │ │
│ │ · CI/CD Pipeline (GitHub Actions) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
五、通信协议与API设计
┌─────────────────────────────────────────────────────────────────┐
│ 📡 通信架构设计 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 协议选择与适用场景 │ │
│ │ │ │
│ │ WebSocket ──── 核心对话通道 │ │
│ │ │ · 实时双向通信 │ │
│ │ │ · LLM流式输出推送 │ │
│ │ │ · 语音分句流式推送 │ │
│ │ │ · 设备状态实时推送 │ │
│ │ │ · 心跳保活 │ │
│ │ │ │ │
│ │ HTTP/2 REST ── 非实时操作 │ │
│ │ │ · 文件上传 (音频/图片) │ │
│ │ │ · 历史记录分页查询 │ │
│ │ │ · 配置管理 │ │
│ │ │ · 用户认证 │ │
│ │ │ │ │
│ │ gRPC ──────── 内部服务间通信 │ │
│ │ · AI引擎 ↔ 记忆系统 │ │
│ │ · AI引擎 ↔ 工具引擎 │ │
│ │ · 高性能 + 强类型 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ WebSocket 消息协议设计 (JSON) │ │
│ │ │ │
│ │ // 客户端 → 服务端 │ │
│ │ { │ │
│ │ "type": "message", // message | voice_input │ │
│ │ "session_id": "uuid", // 会话ID │ │
│ │ "mode": "text", // text | voice_msg | │ │
│ │ // voice_assistant │ │
│ │ "content": "打开客厅的灯", // 文本内容 │ │
│ │ "audio_data": null, // Base64音频(语音输入时) │ │
│ │ "timestamp": 1715600000 │ │
│ │ } │ │
│ │ │ │
│ │ // 服务端 → 客户端 │ │
│ │ { │ │
│ │ "type": "response", // response | segment | │ │
│ │ // audio | device_update │ │
│ │ "message_id": "uuid", │ │
│ │ "text": "好的主人，我这就帮您打开客厅的灯喵~", │ │
│ │ "segments": [ // 断句数组(语音助手模式) │ │
│ │ { │ │
│ │ "index": 0, │ │
│ │ "text": "好的主人。", │ │
│ │ "audio_url": "/audio/seg_001.opus", │ │
│ │ "duration_ms": 1200 │ │
│ │ }, │ │
│ │ { │ │
│ │ "index": 1, │ │
│ │ "text": "我这就帮您打开客厅的灯喵~", │ │
│ │ "audio_url": "/audio/seg_002.opus", │ │
│ │ "duration_ms": 1800 │ │
│ │ } │ │
│ │ ], │ │
│ │ "full_audio_url": "/audio/full_resp.opus", // 完整音频 │ │
│ │ "response_mode": "voice_assistant", // 回复模式 │ │
│ │ "tool_calls": [], // 工具调用记录(如有) │ │
│ │ "timestamp": 1715600001 │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
六、客户端跨端能力设计
┌─────────────────────────────────────────────────────────────────┐
│ 🌐 客户端跨端策略矩阵 │
├─────────────┬──────────┬───────────┬───────────┬───────────────┤
│ 能力 │ Web PWA │ React Nat │ Electron │ 智能音箱 │
│ │ │ ive/Flutte│ /Tauri │ (嵌入式) │
│ │ │ r │ │ │
├─────────────┼──────────┼───────────┼───────────┼───────────────┤
│ 文字聊天 │ ✅ │ ✅ │ ✅ │ ❌ │
│ 语音输入 │ ✅ │ ✅ │ ✅ │ ✅ │
│ 语音输出 │ ✅ │ ✅ │ ✅ │ ✅ │
│ 流式音频 │ ✅ │ ✅ │ ✅ │ ✅ │
│ 设备面板 │ ✅ │ ✅ │ ✅ │ ❌ │
│ 后台运行 │ ⚠️有限 │ ✅ │ ✅ │ ✅ │
│ 系统通知 │ ✅ │ ✅ │ ✅ │ ✅ │
│ 离线缓存 │ ✅ │ ✅ │ ✅ │ ⚠️有限 │
│ 本地存储 │ ⚠️有限 │ ✅ │ ✅ │ ⚠️有限 │
│ 全局快捷键 │ ❌ │ ❌ │ ✅ │ ✅(硬件) │
│ 多窗口 │ ❌ │ ❌ │ ✅ │ ❌ │
├─────────────┼──────────┼───────────┼───────────┼───────────────┤
│ 适用场景 │日常聊天 │移动主力 │专业工作站 │无屏交互 │
│ │快速访问 │全功能 │全功能 │纯语音 │
└─────────────┴──────────┴───────────┴───────────┴───────────────┘
七、完整系统时序图 (Mermaid)
以下是核心交互流程的 Mermaid 图表，可在支持 Mermaid 的工具中渲染：
7.1 语音助手模式完整交互流程
sequenceDiagram
participant U as 用户
participant C as 客户端
participant G as API网关
participant A as AI核心引擎
participant M as 记忆系统
participant T as TTS服务
participant I as IoT设备
U->>C: 🎙️ 语音输入"打开客厅的灯"
C->>C: VAD检测 + 降噪
C->>G: WebSocket: {type:voice_input, audio:base64}
G->>A: 转发音频
A->>T: ASR请求
T-->>A: 文本"打开客厅的灯"
A->>M: 检索相关记忆
M-->>A: 用户偏好: 客厅灯光偏好暖色
A->>A: 组装Context:
人格+记忆+历史+用户输入
A->>A: LLM推理
A-->>A: 决定调用工具: light_control
A->>I: 调用IoT API: 客厅灯开+暖色
I-->>A: 成功, 亮度75%, 色温3000K
A->>A: 生成回复:
"好的主人。客厅的灯已经打开了,
调成了您喜欢的暖色。现在亮度是75%喵~"
A->>A: 断句引擎处理:
S1:"好的主人。"
S2:"客厅的灯已经打开了,调成了您喜欢的暖色。"
S3:"现在亮度是75%喵~"
loop 逐句TTS
A->>T: S1文本
T-->>A: S1音频URL
A->>G: 推送 segment {index:0, text, audio_url}
G->>C: WebSocket推送
C->>C: 加入播放队列, 立即播放
C->>U: 🔊 "好的主人。" (同时显示文字)
end
A->>M: 记录: 用户操作了客厅灯
M->>M: 更新记忆索引
C->>U: 显示完整原文
7.2 长期记忆生命周期
flowchart TD
A[对话结束] --> B[记忆提取器]
B --> C{信息是否有价值?}
C -->|无价值| D[丢弃]
C -->|有价值| E[实体抽取 & 关系识别]
E --> F{信息分类}
F -->|用户相关| G1[用户画像更新]
F -->|事实信息| G2[事实记忆]
F -->|偏好习惯| G3[偏好记忆]
F -->|事件| G4[事件时间线]
G1 --> H{重要性评估}
G2 --> H
G3 --> H
G4 --> H
H -->|🔴 核心| I1[/data/memory/users/{id}/facts/core/]
H -->|🟡 重要| I2[/data/memory/users/{id}/facts/important/]
H -->|🟢 普通| I3[/data/memory/users/{id}/facts/normal/]
H -->|⚪ 临时| I4[仅保留在会话上下文]
I1 --> J[(PostgreSQL)]
I1 --> K[(向量数据库)]
I2 --> J
I2 --> K
I3 --> J
J --> L[定期备份到MinIO/S3]
K --> L
L --> M{迁移触发?}
M -->|是| N[复制/data/目录到新服务器]
N --> O[docker-compose up -d]
O --> P[✅ 迁移完成,记忆无损]
7.3 服务部署架构
graph TB
subgraph "用户端"
W[Web PWA]
M[iOS/Android App]
D[Desktop App]
S[智能音箱]
end
subgraph "负载均衡"
LB[Nginx / Traefik]
end
subgraph "服务集群"
GW1[Gateway-1]
GW2[Gateway-2]
AI1[AI Core-1]
AI2[AI Core-2]
TS1[TTS/ASR-1]
TS2[TTS/ASR-2]
MM[Memory Manager]
TE[Tool Engine]
end
subgraph "数据层"
PG[(PostgreSQL)]
RD[(Redis)]
VD[(向量数据库)]
FS[(MinIO 文件存储)]
end
subgraph "外部服务"
LLM[LLM API<br/>OpenAI/Claude/本地]
IOT[IoT Platform<br/>MQTT Broker]
EXT[第三方API<br/>天气/新闻等]
end
W & M & D & S --> LB
LB --> GW1 & GW2
GW1 & GW2 --> AI1 & AI2
AI1 & AI2 --> MM
AI1 & AI2 --> TE
AI1 & AI2 --> TS1 & TS2
AI1 & AI2 --> LLM
TE --> IOT
TE --> EXT
MM --> PG & VD & FS
AI1 & AI2 --> RD
八、项目目录结构建议
family-ai-assistant/
│
├── backend/ # 后端服务
│ ├── gateway/ # API网关服务
│ │ ├── cmd/ # 入口
│ │ ├── internal/
│ │ │ ├── middleware/ # 认证/限流/日志
│ │ │ ├── handler/ # 路由处理
│ │ │ └── ws/ # WebSocket管理
│ │ └── Dockerfile
│ │
│ ├── ai-core/ # 核心AI引擎
│ │ ├── cmd/
│ │ ├── internal/
│ │ │ ├── orchestrator/ # 对话编排器
│ │ │ ├── persona/ # 人格注入
│ │ │ ├── context/ # 上下文构建
│ │ │ ├── llm/ # LLM适配层
│ │ │ ├── strategist/ # 回复策略
│ │ │ └── sentence_splitter/ # 断句引擎
│ │ └── Dockerfile
│ │
│ ├── voice-service/ # 语音处理服务
│ │ ├── cmd/
│ │ ├── internal/
│ │ │ ├── asr/ # 语音识别
│ │ │ ├── tts/ # 语音合成
│ │ │ ├── vad/ # 语音活动检测
│ │ │ └── pipeline/ # 音频流水线
│ │ └── Dockerfile
│ │
│ ├── memory-service/ # 记忆管理服务
│ │ ├── cmd/
│ │ ├── internal/
│ │ │ ├── extractor/ # 记忆提取
│ │ │ ├── classifier/ # 分类分级
│ │ │ ├── retriever/ # 记忆检索
│ │ │ └── store/ # 存储层
│ │ └── Dockerfile
│ │
│ ├── tool-engine/ # 工具调用引擎
│ │ ├── cmd/
│ │ ├── internal/
│ │ │ ├── registry/ # 工具注册
│ │ │ ├── executor/ # 执行引擎
│ │ │ ├── plugins/ # 插件系统
│ │ │ └── adapters/ # IoT/设备适配器
│ │ └── Dockerfile
│ │
│ ├── proto/ # gRPC协议定义
│ │ ├── ai_core.proto
│ │ ├── memory.proto
│ │ ├── voice.proto
│ │ └── tool.proto
│ │
│ ├── data/ # 数据文件(Volume挂载)
│ │ ├── memory/ # 记忆文件系统
│ │ ├── persona/ # 人格知识文档
│ │ │ ├── default.yaml
│ │ │ └── custom/
│ │ └── plugins/ # 第三方插件
│ │
│ ├── docker-compose.yml # 一键部署
│ ├── docker-compose.prod.yml # 生产环境
│ └── .env.example # 环境变量模板
│
├── frontend/ # 前端项目
│ ├── packages/
│ │ ├── shared/ # 共享代码
│ │ │ ├── src/
│ │ │ │ ├── api/ # API客户端
│ │ │ │ ├── ws/ # WebSocket管理
│ │ │ │ ├── audio/ # 音频处理
│ │ │ │ ├── store/ # 状态管理
│ │ │ │ ├── types/ # TypeScript类型
│ │ │ │ └── utils/ # 工具函数
│ │ │ └── package.json
│ │ │
│ │ ├── web/ # Web PWA
│ │ │ ├── src/
│ │ │ │ ├── components/ # UI组件
│ │ │ │ │ ├── chat/ # 聊天组件
│ │ │ │ │ ├── voice/ # 语音组件
│ │ │ │ │ ├── device/ # 设备控制
│ │ │ │ │ └── memory/ # 记忆查看
│ │ │ │ ├── pages/ # 页面
│ │ │ │ ├── hooks/ # 自定义Hook
│ │ │ │ └── workers/ # Web Workers
│ │ │ └── vite.config.ts
│ │ │
│ │ ├── mobile/ # React Native / Flutter
│ │ │ └── ...
│ │ │
│ │ └── desktop/ # Electron / Tauri
│ │ └── ...
│ │
│ └── turbo.json # Turborepo配置
│
├── docs/ # 文档
│ ├── architecture.md # 架构文档
│ ├── api-reference.md # API文档
│ ├── deployment.md # 部署指南
│ └── persona-guide.md # 人格设定指南
│
├── scripts/ # 部署/运维脚本
│ ├── deploy.sh
│ ├── backup.sh
│ ├── migrate.sh
│ └── setup.sh
│
├── .github/ # CI/CD
│ └── workflows/
│ ├── backend-ci.yml
│ └── frontend-ci.yml
│
└── README.md
九、关键技术决策与考量
┌─────────────────────────────────────────────────────────────────┐
│ ⚠️ 关键技术决策矩阵 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. 为什么选择 WebSocket 作为主通信协议？ │
│ ✅ 双向实时通信，适合流式对话 │
│ ✅ 低延迟，支持音频流推送 │
│ ✅ 断线重连机制成熟 │
│ ⚠️ 需处理连接状态管理和心跳 │
│ │
│ 2. 记忆系统为什么用文件+数据库混合？ │
│ ✅ 文件系统：人类可读，直接迁移，备份简单 │
│ ✅ PostgreSQL：结构化查询，关系型数据 │
│ ✅ 向量数据库：语义检索，相似记忆匹配 │
│ ✅ 三层互补，覆盖所有场景 │
│ │
│ 3. 人格系统为什么用 YAML/文档而非代码硬编码？ │
│ ✅ 非技术人员可编辑修改 │
│ ✅ 支持多角色快速切换 │
│ ✅ 版本管理友好 │
│ ✅ 可分享/导入社区角色 │
│ │
│ 4. 语音助手模式断句策略 │
│ ✅ 按句号断句：最自然的分隔点 │
│ ✅ 首句优先：降低首次响应延迟 │
│ ✅ 队列预生成：边播放边合成，无缝衔接 │
│ ⚠️ 需处理无句号的长句（降级策略：按逗号/长度切分） │
│ │
│ 5. LLM 选择策略 │
│ ✅ 云端大模型：复杂推理、知识问答 (GPT-4, Claude) │
│ ✅ 本地小模型：快速响应、离线可用 (Qwen, DeepSeek) │
│ ✅ 混合路由：根据任务复杂度自动选择 │
│ ⚠️ 需维护多模型适配层 │
└─────────────────────────────────────────────────────────────────┘
十、总结与后续推进建议
| 阶段 | 内容 | 产出 |
|---|---|---|
| Phase 1: 最小可用 | 文字对话 + 人格注入 + 基础记忆 + Web PWA | 可聊天的AI助手 |
| Phase 2: 语音交互 | ASR/TTS集成 + 断句流式 + 语音助手模式 | 支持语音对话 |
| Phase 3: 家庭IoT | IoT适配器 + 设备控制面板 + 场景联动 | 家庭管家能力 |
| Phase 4: 深度记忆 | 向量检索 + 记忆可视化 + 智能摘要 | 真正的"记住你" |
| Phase 5: 多端覆盖 | React Native + Electron + 智能音箱 | 全场景覆盖 |
| Phase 6: 跨域互联 | 车机/办公/穿戴设备集成 | 全能助手 |