第一次运行必读：Live Avatar快速开始注意事项

1. 硬件要求与显存限制说明

1.1 显存需求是硬门槛

在你准备启动 Live Avatar 数字人模型之前，必须明确一个关键事实：目前该模型对显存的要求非常高，单张显卡至少需要 80GB 显存才能正常运行。

这并不是建议配置，而是最低门槛。即使你拥有 5 张 4090（每张 24GB），合计 120GB 显存，依然无法完成实时推理任务。原因在于模型架构和并行策略的特殊性。

很多用户第一次尝试时会误以为“总显存够就行”，但实际情况并非如此。Live Avatar 使用的是 FSDP（Fully Sharded Data Parallel）等分布式策略，在推理过程中需要将分片参数重新组合（unshard），这个过程会在单个 GPU 上产生额外的显存压力。

以实测数据为例：

模型加载时每张 GPU 分摊约 21.48 GB
推理 unshard 阶段需额外增加 4.17 GB
总需求达到25.65 GB / GPU
而 RTX 4090 可用显存为 22.15 GB 左右

因此，即便使用多卡，也无法满足瞬时峰值显存需求。

1.2 当前可用的硬件方案

根据官方文档和测试反馈，以下是目前可行的运行配置：

GPU 数量	单卡显存	总显存	是否支持
1	80GB	80GB	支持（单卡模式）
5	80GB	400GB	支持（多卡 TPP）
4~5	24GB	96~120GB	❌ 不支持

重要提示：不要试图用 4×或 5×4090 运行此模型，已有多位用户验证失败。这不是配置问题，而是根本性的资源不足。

1.3 替代方案建议

如果你暂时没有 80GB 显卡，可以考虑以下三种替代路径：

接受现实，等待优化版本发布
官方团队正在针对 24GB 显卡进行适配优化，未来可能会推出轻量化或分步推理版本。现阶段强行运行只会浪费时间。
使用 CPU Offload（牺牲速度换取可行性）
在infinite_inference_single_gpu.sh脚本中设置--offload_model True，启用 CPU 卸载机制。虽然速度极慢（可能几分钟生成一帧），但可以在低显存环境下勉强运行。
租用云服务临时体验
借助云端 A100/H100 实例（如阿里云、AWS、Lambda Labs）进行短期部署测试。这类平台通常提供按小时计费的高配实例，适合初次体验。

2. 快速启动流程与模式选择

2.1 启动前必备条件

确保已完成以下准备工作：

已克隆项目代码并安装依赖
所有模型文件已下载至ckpt/目录
CUDA 驱动和 PyTorch 环境正确配置
显卡驱动版本 ≥ 535.129.03

推荐使用 Python 3.10 + PyTorch 2.3+ + CUDA 12.1 组合环境。

2.2 根据硬件选择运行脚本

根据你的设备情况，选择对应的启动脚本：

多 GPU 配置（仅限 80GB 显卡）

# 5 GPU 并行推理 bash infinite_inference_multi_gpu.sh # Gradio Web UI 模式（5 GPU） bash gradio_multi_gpu.sh

单 GPU 配置（80GB 显卡）

# 单卡推理 bash infinite_inference_single_gpu.sh # 单卡 Web UI bash gradio_single_gpu.sh

特殊情况：4×24GB GPU 用户

# 使用 TPP 优化策略（仍受限于显存） ./run_4gpu_tpp.sh ./run_4gpu_gradio.sh

注意：4×24GB 方案虽存在脚本支持，但实际运行成功率极低，仅作为实验性尝试。

2.3 访问 Web 界面

成功启动后，打开浏览器访问：

http://localhost:7860

如果页面无法加载，请检查：

端口是否被占用（可用lsof -i :7860查看）
防火墙是否阻止本地连接
脚本是否因 OOM 错误提前退出

3. 关键参数详解与调优建议

3.1 输入控制参数

这些是你最常需要修改的核心输入项。

--prompt（文本提示词）

描述你希望数字人呈现的内容风格。建议格式：

"A cheerful dwarf in a forge, laughing heartily, warm lighting, Blizzard cinematics style"

写作技巧：

包含人物特征、动作、场景、光照、艺术风格
使用具体形容词而非抽象词汇
英文表达更稳定，避免中英混杂

--image（参考图像）

用于定义角色外观。要求：

清晰正面照，分辨率 ≥ 512×512
光照均匀，避免过曝或阴影过重
推荐使用.jpg或.png格式

示例路径：examples/dwarven_blacksmith.jpg

--audio（音频驱动）

控制口型同步与表情变化。要求：

WAV 或 MP3 格式
采样率 ≥ 16kHz
尽量减少背景噪音

示例路径：examples/dwarven_blacksmith.wav

3.2 视频生成参数

--size（分辨率）

格式为"宽*高"，注意是星号*而非字母x。

常见选项：

横屏：704*384,688*368,384*256
竖屏：480*832
方形：704*704

显存影响显著：分辨率越高，显存占用越大。首次运行建议从384*256开始测试。

--num_clip（片段数量）

决定视频总长度。计算公式：

总时长 = num_clip × infer_frames / fps

例如：100 片段 × 48 帧 / 16 fps = 300 秒（5分钟）

推荐值：

快速预览：10–20
正常输出：50–100
长视频：1000+

--sample_steps（采样步数）

默认为 4（DMD 蒸馏）。可选范围 3–6。

步数	效果	速度
3	较快，质量略低	⚡⚡⚡
4	平衡推荐	⚡⚡
5–6	更细腻，更慢	⚡

首次运行建议保持默认值 4。

--sample_guide_scale（引导强度）

控制提示词遵循程度，默认为 0（无引导）。

0：速度快，自然感强
5–7：更强地匹配 prompt 描述
7：可能导致画面过度饱和或失真

新手建议保持 0。

4. 常见问题排查指南

4.1 CUDA Out of Memory（OOM）

典型错误信息：

torch.OutOfMemoryError: CUDA out of memory

解决方法：

降低分辨率：改用--size "384*256"
减少帧数：--infer_frames 32
降低采样步数：--sample_steps 3
启用在线解码：--enable_online_decode
实时监控显存：watch -n 1 nvidia-smi

4.2 NCCL 初始化失败

错误表现：

NCCL error: unhandled system error

解决方案：

检查 GPU 可见性：
```
nvidia-smi echo $CUDA_VISIBLE_DEVICES
```
禁用 P2P 通信：
```
export NCCL_P2P_DISABLE=1
```
启用调试日志：
```
export NCCL_DEBUG=INFO
```
检查端口冲突（默认 29103）：
```
lsof -i :29103
```

4.3 进程卡住无响应

现象：程序启动后无输出，显存已占用但无进展。

应对措施：

确认所有 GPU 可用：

import torch print(torch.cuda.device_count())

增加心跳超时：

export TORCH_NCCL_HEARTBEAT_TIMEOUT_SEC=86400

强制终止并重启：
```
pkill -9 python ./run_4gpu_tpp.sh
```

4.4 生成质量差或不同步

可能原因：

输入图像模糊或角度不佳
音频有噪声或采样率太低
提示词描述不清

改进方向：

使用高质量正面照
提升音频清晰度
优化 prompt 描述细节
尝试提高--sample_steps至 5

检查模型文件完整性：

ls -lh ckpt/Wan2.2-S2V-14B/ ls -lh ckpt/LiveAvatar/

4.5 Gradio 界面打不开

症状：浏览器无法访问http://localhost:7860

排查步骤：

检查进程是否运行：
```
ps aux | grep gradio
```
查看端口占用：
```
lsof -i :7860
```
修改端口号（编辑脚本）：
```
--server_port 7861
```
开放防火墙：
```
sudo ufw allow 7860
```

5. 实用场景配置推荐

5.1 场景一：快速效果预览

目标：快速验证流程是否通畅，查看基础效果。

配置建议：

--size "384*256" --num_clip 10 --sample_steps 3 --enable_online_decode

预期结果：

视频时长：约 30 秒
处理时间：2–3 分钟
显存占用：12–15GB/GPU

适合首次运行验证整体链路。

5.2 场景二：标准质量输出

目标：生成可用于展示的中等质量视频。

配置建议：

--size "688*368" --num_clip 100 --sample_steps 4

预期结果：

视频时长：约 5 分钟
处理时间：15–20 分钟
显存占用：18–20GB/GPU

适用于大多数常规用途。

5.3 场景三：长视频生成

目标：制作超过 10 分钟的连续内容。

配置建议：

--size "688*368" --num_clip 1000 --sample_steps 4 --enable_online_decode

注意事项：

处理时间长达 2–3 小时
必须启用--enable_online_decode防止显存累积溢出
建议分批生成，避免中途崩溃导致全盘重来

5.4 场景四：高分辨率输出

目标：追求最佳视觉质量。

配置建议：

--size "704*384" --num_clip 50 --sample_steps 4

硬件要求：

5×80GB GPU 或更高配置
更长等待时间（约 10–15 分钟处理 2.5 分钟视频）

6. 总结：给第一次使用者的关键提醒

6.1 最重要的三点认知

80GB 显存是底线
不要幻想用 4090 多卡跑通——不是配置问题，是架构限制。当前版本就是为 H100/A100 级别设计的。
先小规模测试再放大
第一次运行务必使用最小分辨率（384*256）、最少片段（10–20）、最低步数（3），确认流程畅通后再逐步提升参数。
Web UI 和 CLI 各有优势
- CLI 适合批量处理和自动化
- Gradio 适合交互调试和直观预览初学者建议先用 CLI 看懂参数逻辑，再切换到 Web UI 提升效率。