# livehuman **Repository Path**: fakerlove/livehuman ## Basic Information - **Project Name**: livehuman - **Description**: No description available - **Primary Language**: Unknown - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-02 - **Last Updated**: 2026-09-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # LiveHuman **可插拔、可拓展的实时数字人中台框架** Python 后端 · React 前端 · 云边端协同 · 模型热插拔 > 把数字人从「绑定某一家云」变成「一套标准流水线 + 可替换插件」。ASR / LLM / TTS / THG 各自独立，换供应商不改业务代码。 **运行指南**（百炼 ASR + DeepSeek Key、前后端启动、ngrok）：见 [`docs/RUN.md`](docs/RUN.md)。 --- ~~~bash # backend cd e:\cursor-demo\livehuman\backend uvicorn app.main:app --reload --port 8000 ~~~ ~~~bash # frontend cd e:\cursor-demo\livehuman\frontend npm run dev ~~~ ## 为什么做这个 行业现状：数字人链路往往和特定云厂商绑死，换模型难、本地化贵、模块耦合重。 LiveHuman 要解决的是： | 痛点 | 框架做法 | | --- | --- | | 厂商锁定 | Provider 适配器 + 统一协议，配置切换即可 | | 模块耦合 | 插件隔离，单点故障不拖垮整条链路 | | 云 / 本地割裂 | 同一接口支持云 API 与本地开源模型 | | 场景难复用 | 编排层与业务场景解耦，教师 / 主播 / 客服共用底座 | --- ## 核心特性 - **插件化 AI 能力**：ASR · LLM · TTS · THG · Intent · VC，统一 Plugin 接口 - **模型热插拔**：`provider: aliyun | local | openai | custom`，运行时切换 - **全时流式交互**：语音进 → 文本流 + 数字人视频出，端到端目标延迟 < 2s - **主动 + 被动双模式**：日程唤醒播报 / 实时打断对话 - **故障熔断与回退**：本地挂了自动切云端，对前端透明 - **前后端分离**：FastAPI 编排 + React WebRTC 播放器，各自可独立演进 --- ## 技术栈 | 层 | 选型 | | --- | --- | | 后端 | Python 3.10+ · FastAPI · Uvicorn · Pydantic | | 前端 | React 18 · TypeScript · Vite · WebRTC | | 通信 | REST（控制面）+ WebSocket（文本/音频流）+ WebRTC（音视频） | | 部署 | Docker · Docker Compose · CUDA（可选本地 GPU） | 默认推荐云方案（阿里云 ASR / 通义 / TTS / 灵眸），本地备选 Whisper · Edge-TTS · Wav2Lip 等，均可插件接入。 --- ## 架构一览 ``` ┌─────────────────────────────────────────────────────────┐ │ React 前端 │ │ 播放器 · 控制台 · WebRTC 采集/播放 · 会话 UI │ └───────────────────────┬─────────────────────────────────┘ │ REST / WS / WebRTC ┌───────────────────────▼─────────────────────────────────┐ │ Gateway · 鉴权 · 路由 │ └───────────────────────┬─────────────────────────────────┘ │ ┌───────────────────────▼─────────────────────────────────┐ │ Orchestrator（编排引擎） │ │ Session · 日程触发 · 打断 · Fallback · Plugin Registry │ └───┬─────────┬─────────┬─────────┬─────────┬─────────────┘ │ │ │ │ │ ASR LLM TTS THG Intent / VC 插件 插件 插件 插件 插件 │ │ │ │ │ 云 / 本地 云 / 本地 云 / 本地 云 / 本地 … ``` ### 分层职责 1. **接入层**：React UI + WebRTC / WebSocket 2. **编排层**：会话状态、链路调度、日程、熔断回退 3. **插件层**：标准化 AI 原子能力（可热插拔） 4. **基础设施**：GPU / 对象存储 / 会话持久化 --- ## 仓库结构（规划） ``` livehuman/ ├── backend/ # Python 后端 │ ├── app/ │ │ ├── main.py # FastAPI 入口 │ │ ├── gateway/ # 网关、鉴权、路由 │ │ ├── orchestrator/ # 编排引擎、Session、日程 │ │ ├── plugins/ # 插件体系 │ │ │ ├── base.py # Plugin 基类与协议 │ │ │ ├── registry.py # 注册 / 发现 / 热加载 │ │ │ ├── asr/ # ASR 适配器（aliyun / whisper / …） │ │ │ ├── llm/ # LLM 适配器（qwen / openai / local） │ │ │ ├── tts/ # TTS 适配器 │ │ │ ├── thg/ # 数字人驱动（灵眸 / Wav2Lip / …） │ │ │ ├── intent/ # 意图识别 │ │ │ └── vc/ # 音色克隆 │ │ ├── api/ # REST / WebSocket 路由 │ │ └── core/ # 配置、日志、健康检查 │ ├── configs/ # 环境与 provider 配置 │ ├── pyproject.toml │ └── Dockerfile ├── frontend/ # React 前端 │ ├── src/ │ │ ├── components/ # 播放器、控制台、聊天气泡 │ │ ├── hooks/ # WebRTC / WS / 会话 hooks │ │ ├── services/ # API 客户端 │ │ ├── stores/ # 会话与数字人状态 │ │ └── plugins/ # 前端扩展点（主题、面板、工具栏） │ ├── package.json │ └── Dockerfile ├── docker-compose.yml └── README.md ``` --- ## 插件协议（核心设计） 每个 AI 能力模块实现同一套契约，业务层只认接口，不认厂商。 ```python # backend/app/plugins/base.py（示意） from abc import ABC, abstractmethod from typing import AsyncIterator, Any class ASRPlugin(ABC): name: str provider: str @abstractmethod async def transcribe(self, audio_stream: AsyncIterator[bytes]) -> AsyncIterator[str]: ... class LLMPlugin(ABC): name: str provider: str @abstractmethod async def chat(self, messages: list[dict], **kwargs) -> AsyncIterator[str]: ... class TTSPlugin(ABC): name: str provider: str @abstractmethod async def synthesize(self, text: str, **kwargs) -> AsyncIterator[bytes]: ... class THGPlugin(ABC): name: str provider: str @abstractmethod async def drive(self, audio_stream: AsyncIterator[bytes], avatar_id: str) -> AsyncIterator[Any]: """音频进 → 视频帧 / WebRTC track 出""" ... ``` ### 配置切换示例 ```yaml # configs/providers.yaml plugins: asr: active: aliyun # 或 whisper fallback: whisper llm: active: qwen fallback: openai tts: active: aliyun fallback: edge_tts thg: active: lingmou # 阿里云灵眸 fallback: wav2lip ``` 改配置 → 重启或热加载 → 业务代码零改动。 ### 写一个自定义插件 ```python # backend/app/plugins/llm/my_provider.py from app.plugins.base import LLMPlugin from app.plugins.registry import register @register("llm", "my_provider") class MyLLMPlugin(LLMPlugin): name = "my_llm" provider = "my_provider" async def chat(self, messages, **kwargs): async for chunk in self._client.stream(messages): yield chunk ``` 前端同样预留扩展点：主题、控制面板、工具栏动作均可挂载为前端插件。 --- ## 核心链路 ### 实时交互（被动） ``` 麦克风 / 文本 → ASR（可选） → Orchestrator + LLM（流式文本回前端） → TTS（PCM） → THG（唇形 + 表情 + 画面） → WebRTC 推流到浏览器 ``` 支持随时语音打断；打断后清空播报队列并重新走交互链路。 ### 自动播报（主动） ``` 日程 / 管理接口创建任务 → 定时触发 → 跳过 ASR/LLM（可按需） → TTS → THG → 推流 ``` 适用于新闻播报、每日简报、定时问候。 ### 故障回退 编排层健康检查：本地超时 / 错误计数超阈值 → 自动切 `fallback` provider，前端无感。 --- ## 功能需求速览 | ID | 能力 | 说明 | | --- | --- | --- | | FR-01 | 文字交互 | Web 文本 Query → 流式 LLM 回复 | | FR-02 | 语音交互 | WebRTC 音频 → ASR → 对话 → 数字人视频流 | | FR-03 | 管理控制 | 音色 / 语速 / 形象 / Temperature 等 REST 配置 | | FR-04 | 自动播报 | 文本 / SSML → 情感语音 + 驱动 | | FR-05 | THG 驱动 | PCM/WAV 音频驱动唇形、微表情、上半身动作 | | FR-06 | 意图路由 | 天气 / 设备控制 / 闲聊等下游分流 | | FR-07 | 模型匹配 | 工厂 + Registry 动态加载 Provider | | FR-08 | 语音克隆 | 短音频微调 → 专属音色实时调用 | ### 非功能目标 | 维度 | 指标 | | --- | --- | | 延迟 | 端到端 < 2s（不含网络抖动） | | 并发 | 单 GPU 节点约 4~8 路（视模型而定） | | 可用性 | 模块隔离 + Fallback | | 扩展性 | 新增适配器即可接 HuggingFace / 任意 API | | 资源 | 环境变量限制各模块 GPU 显存上限 | --- ## 业务场景 - **虚拟教师**：课件驱动讲解，学生随时语音打断提问 - **虚拟主播**：新闻稿多情感播报，7×24 连续输出 - **主动对话**：日程闹钟 / 每日简报主动唤醒 - **形象定制**：2D 照片克隆 / 3D 建模，形象库一键切换 --- ## 快速开始（规划） > 脚手架落地后按此流程启动。当前仓库以方案与协议为准，代码持续补齐。 ### 环境要求 - Python 3.10+ - Node.js 18+ - Docker（推荐） - NVIDIA GPU + CUDA（仅本地 THG / 本地 LLM 需要） ### 后端 ```bash cd backend python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate pip install -e . cp configs/providers.example.yaml configs/providers.yaml # 填入 API Key / 本地模型路径 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` ### 前端 ```bash cd frontend npm install npm run dev ``` ### Docker 一键 ```bash docker compose up --build ``` 默认端口规划： | 服务 | 端口 | | --- | --- | | Gateway | 80 / 443 | | Orchestrator | 8000 | | LLM 适配 | 8001 | | ASR 适配 | 8002 | | THG | 8003 | --- ## 云方案 vs 本地方案 | 模块 | 云（默认） | 本地备选 | | --- | --- | --- | | ASR | 阿里云 NLS | Whisper / FunASR | | LLM | 通义千问 | vLLM + Qwen / OpenAI 兼容接口 | | TTS | 阿里云 TTS | Edge-TTS / 开源声码器 | | THG | ~~灵眸数字人~~（费用高，默认不用） | **HuggingFace Wav2Lip**（权重缓存 `model/`） | **THG 云方案**：后端推送 16kHz PCM → 云端唇形推理与超分 → H.264 经 WebRTC 回前端。适合把重渲染从本地 GPU 卸载出去。 切换原则：插件协议统一，**只换适配器，不改编排**。 --- ## 形象管理 - **云端**：上传含人脸视频 → 重建数字分身 → 返回 `AvatarID` - **本地**：关键点 / 特征向量（`.pt` / `.npy`）→ THG 加载驱动 - **形象库服务**：维护 `AvatarID` ↔ 云项目 ID / 本地 Checkpoint 映射 --- ## 实施路线 | 阶段 | 周期 | 交付 | | --- | --- | --- | | Phase 1 | 1~2 周 | FastAPI + React 脚手架、WS 打通、云账号鉴权 | | Phase 2 | 3~4 周 | 云全链路 DEMO：语音进、视频出；播报接口可用 | | Phase 3 | 5~6 周 | 本地模型适配、配置热切换、显存评估 | | Phase 4 | 7~8 周 | 意图 / 日程主动对话、WebRTC 画质与延迟优化 | | Phase 5 | 9~10 周 | 部署手册、API 文档、容灾演练 | --- ## 扩展指南（给二次开发者） 1. **加新 ASR / LLM / TTS / THG**：实现对应 `*Plugin` 基类 → `@register` → 写配置项 2. **加新业务场景**：在 Orchestrator 挂 Pipeline / Graph，复用现有插件 3. **加前端面板**：实现 `frontend/src/plugins` 约定接口，注册到控制台槽位 4. **加意图下游**：Intent 插件返回 route key → 编排层转发到业务 webhook / 内部服务 约定： - 插件无状态或会话状态外置（Redis / Session Store） - 禁止插件直接依赖其他插件的具体实现，只依赖协议类型 - 错误必须上抛或转为标准 `PluginError`，由编排层决定 Fallback --- ## 资源建议（AutoDL / 自建） | 资源 | 建议 | 用途 | | --- | --- | --- | | GPU | RTX 3090 / A4000 24GB | 本地 THG / 并发 | | CPU | 8 vCPU | WS、编解码 | | RAM | 32GB | 容器 + Redis 等 | 默认走云能力时，可把本地显存主要留给 THG 容灾或并发。 --- ## 设计原则 1. **协议优于实现**：业务只认 Plugin 契约 2. **编排与能力分离**：Orchestrator 不写模型细节 3. **可观测**：每个插件暴露健康检查与延迟指标 4. **可回退**：每个 active provider 配 fallback 5. **可替换**：云 ↔ 本地、开源 ↔ 商业，同一流水线 --- ## License 待定。贡献与 Issue 欢迎，插件 PR 优先合并。 --- **一句话**：LiveHuman = 数字人流水线中台。插件进、场景出；Python 管脑子，React 管脸和交互。