Skip to content

README.zh-CN.md

Latest commit

 

History

History
415 lines (313 loc) · 13.6 KB

README.zh-CN.md

File metadata and controls

415 lines (313 loc) · 13.6 KB

MetaHuman 数字人引擎

MetaHuman Engine

让 AI 拥有实时互动的数字身躯

基于浏览器的 3D 数字人引擎，集成语音、视觉、对话能力
零配置 · 离线可用 · 生产级

CI 状态 在线演示 版本 包体积 React Three.js TypeScript Vite 许可证

快速开始 · 功能 · 性能 · 架构 · 文档 · 更新日志 · English

✨ 在线演示

🚀 立即体验 →

在浏览器中直接体验完整的交互式 3D 数字人。 无需安装或 API Key！

📸 预览

MetaHuman Engine 预览 - 情绪驱动的 3D 数字人和实时对话

情绪驱动的 3D 数字人和实时对话

🚀 Quick Start

前提条件

  • Node.js ≥ 18
  • npm ≥ 9

安装

# 克隆并安装
git clone https://github.com/LessUp/meta-human.git
cd meta-human
npm install

# 启动开发服务器
npm run dev

打开 http://localhost:5173 —— 你的 3D 数字人已就绪！

💡 无需 API Key。 引擎自动降级到本地模拟模式，开箱即用。

🎯 Features

🎭 3D 数字人引擎

功能 说明
GLB/GLTF 支持 加载自定义模型或使用内置程序化形象
情绪驱动 高兴、惊讶、悲伤、愤怒自动映射表情
骨骼动画 挥手、问候、点头、跳舞，由对话触发
自适应性能 60fps 渲染，根据设备能力调节画质 
import { digitalHumanEngine } from './core/avatar';

digitalHumanEngine.perform({
  emotion: 'happy',
  expression: 'smile',
  animation: 'wave',
});

注意： 本项目使用 Vite 路径别名。详见 路径别名 配置。

🗣️ 语音交互

功能 说明
TTS 语音合成 Edge TTS 提供自然流畅的语音
ASR 语音识别 浏览器原生语音转文字
智能静音 用户说话时自动暂停播报
语音检测 录音时提供视觉反馈 
import { ttsService, asrService } from './core/audio';

await ttsService.speak('你好！有什么可以帮您？');

asrService.start({
  onResult: (text) => dialogueService.send(text),
});

🧠 智能对话

功能 说明
多模态响应 返回 { replyText, emotion, action }
流式输出 通过 SSE 实时逐字响应
优雅降级 API 不可用时自动回退 Mock
会话管理 持久化对话上下文 
import { dialogueService } from './core/dialogue';

const response = await dialogueService.send({
  text: '讲个笑话',
  sessionId: 'user-123',
});
// → { replyText: '...', emotion: 'happy', action: 'laugh' }

👁️ 视觉感知

功能 说明
人脸网格 468 个关键点捕捉微表情
姿态估计 上半身手势识别
情绪映射 实时情绪推断
隐私优先 全部在浏览器处理，数据不上传

⚡ Performance

典型设备上的性能基准：

指标 桌面端 移动端（中端） 移动端（低端）
渲染性能 60 FPS 60 FPS 30 FPS
TTS 延迟 < 200ms < 300ms < 500ms
包体积 180 KB (gzipped) 180 KB 180 KB
内存占用 ~120 MB ~80 MB ~60 MB

性能根据设备能力自动调节。详见性能模块文档。

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          UI 层                                   │
│   ChatDock · TopHUD · ControlPanel · SettingsDrawer             │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                        核心引擎层                                │
│   Avatar · Dialogue · Vision · Audio · Performance              │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                         状态层                                   │
│   chatSessionStore · systemStore · digitalHumanStore            │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                        外部服务                                  │
│   Three.js · Web Speech API · MediaPipe · OpenAI API            │
└─────────────────────────────────────────────────────────────────┘

状态管理

三个独立域，最小化重渲染：

Store 职责
chatSessionStore 消息历史、会话生命周期
systemStore 连接状态、错误、性能指标
digitalHumanStore 数字人运行时状态（表情、动画、音频）

📖 架构文档 →

📁 项目结构

src/
├── core/                          # 引擎模块
│   ├── avatar/                    # 3D 渲染与动画
│   │   ├── DigitalHumanEngine.ts  # 统一驱动入口
│   │   └── constants.ts           # 表情、动作常量
│   ├── audio/                     # TTS & ASR 服务
│   ├── dialogue/                  # 对话传输与编排
│   │   ├── dialogueService.ts     # API 客户端
│   │   ├── dialogueOrchestrator.ts
│   │   └── chatTransport.ts       # HTTP/SSE/WebSocket
│   ├── vision/                    # MediaPipe 管道
│   │   ├── visionService.ts
│   │   └── visionMapper.ts
│   └── performance/               # 设备能力检测
├── components/                    # React 组件
│   ├── DigitalHumanViewer.tsx     # 3D 视口
│   ├── ChatDock.tsx               # 聊天界面
│   ├── TopHUD.tsx                 # 状态栏
│   ├── ControlPanel.tsx           # 快捷控制
│   ├── VoiceInteractionPanel.tsx
│   ├── VisionMirrorPanel.tsx
│   └── ui/                        # 共享原语
├── store/                         # Zustand 状态
│   ├── chatSessionStore.ts
│   ├── systemStore.ts
│   └── digitalHumanStore.ts
├── hooks/                         # 自定义 Hooks
├── pages/                         # 路由页面
└── lib/                           # 工具函数

路径别名

本项目使用 Vite 路径别名，配置在 vite.config.ts：

别名 映射路径
@core/* src/core/*
@components/* src/components/*
@store/* src/store/*
@hooks/* src/hooks/*
@lib/* src/lib/*
@pages/* src/pages/*

🌐 部署

GitHub Pages（前端）

npm run build:pages
  1. 在 GitHub 仓库变量中设置 VITE_API_BASE_URL
  2. 推送到 main 或运行 "Deploy Pages" 工作流
  3. 访问：https://lessup.github.io/meta-human/

Render（后端）

Deploy to Render

使用 render.yaml 蓝图：

# 部署 FastAPI 后端：
POST /v1/chat          # OpenAI 兼容对话
POST /v1/chat/stream   # SSE 流式
POST /v1/tts           # 语音合成
POST /v1/asr           # 语音识别
WebSocket /ws          # 实时流

必需环境变量：

变量 说明 是否必需
OPENAI_API_KEY AI 响应 可选（自动降级）
CORS_ALLOW_ORIGINS 前端域名 是

📖 部署指南 →

🛠️ 脚本

开发

npm run dev              # 启动开发服务器（端口 5173）
npm run preview          # 预览生产构建
npm run preview:https    # HTTPS 预览

构建

npm run build            # 生产构建
npm run build:pages      # GitHub Pages 构建
npm run build:mobile     # 移动端优化构建
npm run build:desktop    # 桌面端优化构建
npm run build:ar         # AR 功能构建
npm run build:analyze    # 构建并分析包体积

质量

npm run lint             # ESLint 检查
npm run lint:fix         # 自动修复
npm run format           # Prettier 格式化
npm run format:check     # 仅检查格式化
npm run typecheck        # TypeScript 检查

测试

npm run test             # Vitest 监听模式
npm run test:run         # 运行一次
npm run test:coverage    # 覆盖率报告
npm run test:ui          # Vitest UI 模式

🧰 浏览器支持

功能 Chrome Edge Firefox Safari
核心引擎 90+ ✅ 90+ ✅ 90+ ✅ 15+ ✅
TTS（语音合成） 90+ ✅ 90+ ✅ 90+ ✅ 15+ ✅
ASR（语音识别） 90+ ✅ 90+ ✅ ❌ 不支持 ❌ 不支持
MediaPipe 视觉 90+ ✅ 90+ ✅ 90+ ✅ 15+ ⚠️

ASR 限制： 语音识别功能需要 Chrome 或 Edge 浏览器。Firefox 和 Safari 用户可使用文字输入。

Safari 提示： MediaPipe 视觉功能可能需要开启实验性功能。

📚 文档

🛣️ 路线图

查看 CHANGELOG.zh-CN.md 了解已发布功能，或访问 GitHub Projects 了解开发计划。

  • 核心 3D 数字人渲染
  • 语音交互（TTS/ASR）
  • 视觉感知（MediaPipe）
  • 流式对话
  • 移动端 AR 支持
  • 自定义形象上传
  • 多语言 TTS

🤝 贡献

我们欢迎贡献！请查看我们的贡献指南。

  1. Fork 本仓库
  2. 创建特性分支：git checkout -b feat/amazing-feature
  3. 提交变更：git commit -m 'feat: add amazing feature'
  4. 推送：git push origin feat/amazing-feature
  5. 发起 Pull Request

遵循 Conventional Commits 规范。

📄 许可证

MIT © LessUp

用 ❤️ 打造，让每个人都能拥有自己的数字人

⭐ 在 GitHub 上星标 · 🐦 关注 X