MetaHuman Stream（LiveTalking）保姆级部署教程：实时交互流式数字人引擎，音视频同步对话

本文所有命令与配置均照搬官方仓库 README（原 whyiyhw/metahuman-stream，现迁移为 lipku/LiveTalking，github.com/lipku/LiveTalking），未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

MetaHuman Stream（现名 LiveTalking）是一套实时交互流式数字人引擎，官方 README 定位为"实时交互流式数字人引擎，实现音视频同步对话，已在业内获得广泛商用"。它解决的问题是：让一个虚拟数字人形象能实时"听懂"用户说话/接收文字，并以口型同步、低延迟的方式开口回应，结合大语言模型（LLM）即可构成可对话的数字人客服、虚拟主播、大屏讲解员。

项目最初仓库为 whyiyhw/metahuman-stream，后迁移并更名为 lipku/LiveTalking（国内镜像 Gitee: gitee.com/lipku/LiveTalking、GitCode: gitcode.com/lipku/LiveTalking）。它支持 wav2lip、ernerf、musetalk、Ultralight-Digital-Human 等多种数字人模型，输出走 WebRTC / RTMP / 虚拟摄像头，支持声音克隆、说话被打断、全身视频拼接、动作编排与多并发。官方已在 Ubuntu 22.04、Python 3.12、PyTorch 2.9.1、CUDA 12.8 上测试通过。

二、功能拆解

按官方 README「Features」，核心能力如下：

典型使用场景：24 小时无人直播带货、AI 数字人客服、在线教育讲师分身、智能语音助手、展厅大屏讲解、短视频批量制作。

官方把整条链路概括为：用户输入文字/音频 → LLM 生成回复（可选）→ TTS 合成语音 → 数字人实时口型同步 → 音视频推流输出。其插件系统基于 registry.py 的去中心化注册机制，开发者可自行扩展 TTS、Avatar、Output 三类模块；TTS 层官方已模块化支持 EdgeTTS、GPT-SoVITS、CosyVoice、腾讯云等多种方案。

三、官方/GitHub 链接

• GitHub 仓库（现名）：https://github.com/lipku/LiveTalking
• 原仓库（whyiyhw/metahuman-stream 已重定向）：https://github.com/whyiyhw/metahuman-stream
• 官方文档：https://doc.livetalking.ai
• 国内镜像 Gitee：https://gitee.com/lipku/LiveTalking
• API 文档：https://github.com/lipku/LiveTalking/blob/main/docs/api.md
• 商用版体验：https://www.livetalking.top
• AutoDL 镜像：https://www.codewithgpu.com/i/lipku/livetalking/base

四、环境要求

官方 README「1. 安装」一节原文：

• 操作系统： 已在 Ubuntu 22.04 测试通过；README 徽章同时标注支持 linux、win、mac。
• Python： Python 3.12
• PyTorch： PyTorch 2.9.1（torchvision 0.24.1、torchaudio 2.9.1）
• CUDA： CUDA 12.8（官方原文：运行 nvidia-smi 确认；若 CUDA 版本不是 12.8，需按 PyTorch 官网装对应版本）
• GPU： 官方性能表——wav2lip256 推荐 RTX 3060 及以上；musetalk 推荐 RTX 3080Ti 及以上。
• 端口： 服务端需开放 TCP:8010 与 UDP:1-65536（官方注意事项原文）。

五、部署步骤

步骤 1：克隆仓库并进入

git clone https://github.com/lipku/LiveTalking.git

逐段解释：克隆官方源码仓库。

预期输出参考： 克隆进度。

步骤 2：创建并激活 conda 环境（官方原文）

conda create -n livetalking python=3.12
conda activate livetalking

逐段解释：创建名为 livetalking、Python 3.12 的环境并激活。

预期输出参考： 命令行前缀出现 (livetalking)。

步骤 3：安装 PyTorch（官方原文）

pip install torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 --index-url https://download.pytorch.org/whl/cu128

逐段解释：安装 CUDA 12.8 版的 PyTorch 三件套（torch/torchvision/torchaudio），版本固定为 2.9.1/0.24.1/2.9.1；--index-url 指定从 PyTorch 官方 cu128 源安装。官方注释：若本机 CUDA 不是 12.8，请按 https://pytorch.org/get-started/previous-versions 安装对应版本。

预期输出参考： PyTorch 下载安装日志（约 2–3GB），结束无报错。

步骤 4：安装项目依赖（官方原文）

cd LiveTalking
pip install -r requirements.txt

逐段解释：进入仓库目录，安装项目 requirements.txt 中的其余依赖。

预期输出参考： 依赖安装日志，结束无报错。常见安装问题见官方 FAQ：https://doc.livetalking.ai/docs/faq/ 。

步骤 5：下载模型

官方提供夸克云盘与 Google Drive 两个网盘（README「2.1 下载模型」表格）。下载后按官方要求放置：

1. 将 wav2lip256.pth 拷贝到项目的 models/ 目录下，重命名为 wav2lip.pth
2. 将 wav2lip256_avatar1.tar.gz 解压后整个文件夹拷贝到 data/avatars/ 目录下

逐段解释：第 1 步放口型模型权重；第 2 步放一个示例数字人形象（avatar），解压后目录名 wav2lip256_avatar1 即后续启动命令里的 --avatar_id。

六、配置参数详解

启动命令参数（官方「2.2 启动服务」原文）：

python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1

Web 页面路由（官方「2.4 Web 页面」）：

API 层（官方系统架构）： /human 接收文本（echo 复读 / chat LLM 对话两种模式）；/humanaudio 接收音频文件直接播放；每个连接分配唯一 sessionid。完整接口见 docs/api.md、docs/avatar_api.md、docs/admin_api.md。

七、启动与运维

启动服务（官方原文命令）：

python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1

逐段解释：python app.py 启动数字人服务；--transport webrtc 用 WebRTC 低延迟推流；--model wav2lip 选用 wav2lip 模型；--avatar_id wav2lip256_avatar1 用第 5 步放好的示例形象。

预期输出参考： 官方未在 README 给出完整启动日志原文；正常表现为加载模型、监听 8010 端口。官方注意事项原文："服务端需开放端口 TCP:8010, UDP:1-65536"。

• 客户端接入（官方「2.3」）： 浏览器打开 http://serverip:8010/index.html，点"开始连接"播放数字人视频，在文本框输入文字提交即可驱动。
• 后台常驻 / 开机自启： 官方未提供 systemd/开机自启配置。需要常驻时可用 Linux 通用的 tmux/nohup 或 --restart 类容器策略（平台通用机制，非官方提供）。
• 修改端口： 官方 README 固定使用 8010，未在文档中给出改端口参数；如需变更以 python app.py --help 实际输出为准。
• 性能监控（官方「6. 性能指标」）： 后端日志 inferfps = GPU 推理帧率，finalfps = 最终推流帧率，两者均需 ≥25 才算实时。官方实测：wav2lip256 在 RTX 3060 上 60 FPS、RTX 3080Ti 上 120 FPS；musetalk 在 RTX 3080Ti 上 42、RTX 3090 上 45、RTX 4090 上 72 FPS。
• Docker 运行： 官方提供 AutoDL 与 UCloud 镜像（见官方链接节），README 未给出自建 Dockerfile/compose。

各层职责（官方「系统架构」）：

资源占用规律（官方「6. 性能指标」原文）： 每路视频压缩消耗 CPU，分辨率越高 CPU 消耗越大；每路口型推理消耗 GPU。不说话时并发数取决于 CPU，同时说话并发数取决于 GPU。

客户端接入方式（官方「2.3」）： 官方给出三类接入——① 浏览器：打开 http://serverip:8010/index.html，点"开始连接"播放数字人视频，在文本框输入文字提交即可；② API 调用：参考 docs/api.md 通过 HTTP 接口驱动；③ 桌面客户端：官方提供夸克网盘下载地址。另有 Windows 整合包可直接体验（官方「2.5」）。

开源版与商用版对比（官方「7. 商用版」）： 开源版定位快速体验、二次开发、学习研究，技术栈为 wav2lip / musetalk / ultralight 三款模型；商用付费版在开源版基础上新增 wav2lipls 及性能加速、自适应动作、实时语音互动等增强，面向需要开箱即用商业交付的客户。

八、实操验证

1. 按第五步装好环境、放好模型与 avatar 后启动服务：

python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1

2. 浏览器访问 http://服务器IP:8010/index.html（官方原文）。
3. 点击页面上的"开始连接"，应能看到数字人视频画面加载出来。
4. 在文本框输入一句话并提交，数字人应实时开口朗读该文本，口型与语音同步。
5. 访问 http://服务器IP:8010/admin.html 管理后台，应能看到当前会话状态与全局配置（官方「2.4」）。
6. 访问 http://服务器IP:8010/avatar.html 可上传一段视频自动训练/生成新的数字人形象。

登录与安全（重要）

• 官方默认登录状态： 官方 README 未为 /index.html 与 /admin.html 设置默认账号密码，也未在文档中提供登录鉴权说明——即默认这些页面可直接访问。
• 管理后台 /admin.html： 官方说明其功能为"实时监控会话状态与全局配置"，文档未提供默认密码或鉴权配置。
• 密码重置 / 密码存放位置： 官方 README 未提供账号密码机制，故无默认密码、无密码重置命令、无密码配置文件位置可考。
• 安全提醒： 由于官方默认未对 Web 页面与管理后台做鉴权，公网部署时务必自行在前面加 Nginx 反向代理 + 访问认证（如 Basic Auth），或限制来源 IP，避免 /admin.html 被匿名访问、数字人服务被滥用。接入 LLM/TTS 的 API Key 也应妥善保管，不要硬编码暴露在前端。

九、故障排查

案例 1：CUDA 版本与 PyTorch 不匹配

• 报错原文（常见形式）：CUDA error: no kernel image is available for execution on the device
• 报错原因：官方 README 明确"已在 CUDA 12.8 测试通过"，并提示若 nvidia-smi 显示的 CUDA 不是 12.8，需按 PyTorch 官网装对应版本；直接装 cu128 版 torch 会在低版本 CUDA 上无法运行。
• 分步解决：① nvidia-smi 确认本机 CUDA 版本；② 若不是 12.8，访问 https://pytorch.org/get-started/previous-versions 选择对应 CUDA 的 torch 安装命令替换第 3 步；③ 重新 pip install 对应版本。

案例 2：模型/avatar 路径不对

• 报错原文（常见形式）：FileNotFoundError: models/wav2lip.pth 或 avatar 加载失败
• 报错原因：官方要求 wav2lip256.pth 必须在 models/ 下重命名为 wav2lip.pth，avatar 解压后整个目录放 data/avatars/；文件名/目录名不符即找不到。
• 分步解决：① 确认 models/wav2lip.pth 存在（已重命名）；② 确认 data/avatars/wav2lip256_avatar1/ 目录存在；③ 启动命令 --avatar_id 与该目录名完全一致。

案例 3：浏览器连不上 / WebRTC 黑屏

• 报错现象：页面点"开始连接"后一直转圈或黑屏。
• 报错原因：官方注意事项明确"服务端需开放 TCP:8010, UDP:1-65536"；WebRTC 依赖大量 UDP 端口，若云服务器安全组/防火墙只开了 8010，UDP 不通则视频流建立失败。
• 分步解决：① 云厂商安全组放行 TCP 8010 与 UDP 1-65536；② 确认服务端 nvidia-smi 显示 GPU 正常、日志 inferfps/finalfps ≥25；③ 本地测试可用 http://127.0.0.1:8010/index.html 先排除网络问题。

案例 4：安装依赖报错（官方 FAQ）

• 报错现象：pip install -r requirements.txt 中途编译失败。
• 官方指引：README「1.1 安装依赖」末尾给出"安装常见问题：FAQ（https://doc.livetalking.ai/docs/faq/）"，Linux CUDA 环境搭建参考官方知乎专栏。
• 分步解决：① 查阅官方 FAQ 页对应报错；② 确保在 conda activate livetalking 环境内安装；③ CUDA 基础环境参考官方给的 Linux CUDA 搭建教程。

十、升级、回滚与卸载

升级： 官方未在 README 给出专门升级命令；用 Git 常规更新并重装依赖：

git pull
pip install -r requirements.txt

逐段解释：拉取最新代码、重装依赖。模型/avatar 如有更新按网盘新版重新下载放置。

回滚： 官方未提供回滚命令；git checkout <旧tag/commit> 回退到历史版本即可（官方 Releases: https://github.com/lipku/LiveTalking/releases ）。

卸载： 无系统服务。停止 Ctrl+C 终止 app.py；conda remove -n livetalking --all 删除环境；删除项目目录（含 models/、data/avatars/ 权重与形象）。官方另提供 Windows 整合包与 AutoDL/UCloud 镜像，按对应平台方式销毁实例即可。

十一、商用许可合规说明

• 许可证：Apache License 2.0（仓库 LICENSE 文件与 README 徽章均标注 Apache 2.0）。
• Apache-2.0 允许自由使用、修改、分发与商用，分发时须保留版权声明与许可文本，修改过的文件须标注变更。
• 开源版 vs 商用版： 官方 README「7. 商用版」说明：开源版为 Apache 2.0，定位快速体验、二次开发、学习研究；另有付费商用版（新增 wav2lipls 及性能加速、自适应动作、实时语音互动等增强），详见 https://doc.livetalking.ai/docs/service/ 。
• 官方声明（README「8. 声明」）： 基于本项目开发并发布在 B 站、视频号、抖音等平台的视频，需带上 LiveTalking 水印和标识。商用时请遵守该署名/水印要求及平台规则。