Live Avatar部署记录：todo.md文件使用说明
1. 模型背景与硬件限制
Live Avatar是由阿里联合高校开源的数字人模型，专注于高质量、低延迟的实时数字人视频生成。它融合了扩散模型（DiT）、文本编码器（T5）和变分自编码器（VAE），支持文本+图像+音频三模态驱动，可生成自然口型、流畅动作、风格一致的数字人视频。
但必须明确一个关键现实：该模型对显存要求极为严苛。当前镜像版本需要单卡80GB显存才能稳定运行。我们实测过5张NVIDIA RTX 4090（每卡24GB显存），依然无法完成推理——不是配置问题，而是底层内存模型存在硬性瓶颈。
根本原因在于FSDP（Fully Sharded Data Parallel）在推理阶段的“unshard”机制：模型加载时虽按GPU分片（约21.48GB/GPU），但推理前需将全部参数重组到单卡显存中参与计算，额外占用约4.17GB，总需求达25.65GB，远超RTX 4090的22.15GB可用显存。
代码中虽有offload_model参数，但它控制的是整个模型向CPU卸载，并非FSDP级别的细粒度CPU offload。因此，设置为False是多卡模式下的合理选择，但无法解决单卡显存不足的本质矛盾。
1.1 当前可行路径建议
- 接受现实：24GB GPU暂不支持此配置，无需反复尝试不同并行策略
- 降速保用：启用单GPU + CPU offload（
--offload_model True），可运行但速度极慢，仅适合调试验证 - 等待优化：官方已在todo.md中明确标注“24GB GPU support”，建议关注后续版本更新
注意：这不是部署错误，而是模型架构与当前消费级GPU规格之间的客观鸿沟。强行压测不仅失败，还可能触发CUDA异常中断，浪费调试时间。
2. todo.md文件的核心作用
todo.md不是待办清单，而是Live Avatar项目组公开的技术日志与路线图。它不面向终端用户展示功能，而是为开发者、部署工程师和高校研究者提供真实、透明、可追溯的工程进展记录。理解它，等于掌握该项目当前能力边界与演进方向。
文件结构清晰分为三类条目：
Done：已落地的关键优化（如4GPU TPP模式上线、Gradio UI集成）🛠 In Progress：正在开发但尚未合入主干的功能（如24GB GPU适配、量化推理支持）Planned：中长期规划，含技术预研与跨团队协作事项（如WebRTC实时推流、LoRA微调工具链）
你不需要逐行阅读所有条目，但应重点关注与你硬件环境直接相关的条目。例如，在🛠 In Progress下搜索关键词24GB，你会看到：
- [ ] Support for 24GB GPUs via memory-efficient unsharding (Q4 2025) - Investigating partial parameter recomposition - Benchmarking CPU-GPU hybrid inference latency这说明：官方已启动专项优化，目标Q4交付，且方案聚焦于“部分参数重组”这一关键技术点——意味着未来可能通过牺牲少量质量换取显存释放，而非简单粗暴的模型裁剪。
2.1 如何高效使用todo.md
- 部署前必查：运行
git pull && cat todo.md | grep -A 3 "24GB"，确认最新进展 - 故障定位参考：若遇到OOM，立即搜索
memory或unshard，查看是否已有对应修复方案 - 避免重复造轮子：发现某项优化已在
In Progress中，不必自行实现，可订阅PR通知 - 贡献指引：文件末尾附有
Contributing to todo.md章节，说明如何提交有效issue与PR
重要提醒：
todo.md中的时间标注（如Q4 2025）是研发计划，非承诺交付日期。实际进度受算法突破、硬件适配、测试验证等多重因素影响。
3. 运行模式与脚本选择指南
Live Avatar提供三种运行模式，但模式选择本质是硬件能力的映射，而非功能差异。CLI与Gradio只是交互层，核心推理引擎完全一致。选错模式不会报错，但会导致显存溢出或性能断崖式下跌。
| 硬件配置 | 推荐模式 | 启动脚本 | 关键特征 |
|---|---|---|---|
| 单卡80GB（A100/H100） | 单GPU推理 | bash infinite_inference_single_gpu.sh | --offload_model True，启用CPU offload；--num_gpus_dit 1；禁用VAE并行 |
| 4×24GB（4090） | 4GPU TPP | ./run_4gpu_tpp.sh | --offload_model False；--num_gpus_dit 3；--ulysses_size 3；启用VAE并行 |
| 5×80GB（A100） | 5GPU多卡推理 | bash infinite_inference_multi_gpu.sh | --num_gpus_dit 4；--ulysses_size 4；最大分辨率支持（720×400） |
3.1 脚本执行前的强制检查项
在运行任何.sh脚本前，请务必执行以下三步验证，耗时不到30秒，却能避免90%的启动失败：
GPU可见性检查
echo $CUDA_VISIBLE_DEVICES # 应输出0,1,2,3（4卡）或空（单卡） nvidia-smi -L # 确认GPU型号与数量匹配模型路径校验
ls -d ckpt/Wan2.2-S2V-14B/ ckpt/LiveAvatar/ # 必须存在两个目录端口冲突扫描（尤其Gradio模式）
lsof -i :7860 2>/dev/null || echo "Port 7860 is free"
若任一检查失败，请先修正环境再执行脚本。不要跳过——run_4gpu_tpp.sh在检测到CUDA_VISIBLE_DEVICES为空时，会静默回退至单卡模式，导致显存超限崩溃。
4. 核心参数实战解析
参数文档易读，但真正决定成败的是参数间的耦合关系。以下直击高频误用点，用真实案例说明：
4.1--size与--num_clip的显存陷阱
很多人认为--size "384*256"一定比"704*384"省显存，这是对的；但若同时设--num_clip 1000，显存峰值反而更高——因为片段数增加会线性提升中间缓存（尤其是VAE解码缓冲区）。
正确做法：
- 预览测试：
--size "384*256" --num_clip 10（显存≈12GB） - 生产生成：
--size "688*368" --num_clip 100（显存≈19GB） - 长视频：
--size "688*368" --num_clip 1000 --enable_online_decode（显存≈19GB，无累积）
❌ 错误组合：--size "384*256" --num_clip 1000→ 显存飙升至23GB+，4090必然OOM
4.2--sample_steps的边际效应
默认值4（DMD蒸馏）是速度与质量的黄金平衡点。实测表明：
--sample_steps 3：速度↑25%，质量↓15%（细节模糊，边缘轻微锯齿）--sample_steps 5：速度↓35%，质量↑5%（仅在4K屏放大观察时可辨）--sample_steps 6：速度↓60%，质量无显著提升（信噪比饱和）
结论：除非你有专业审片需求，否则坚持默认值4。把优化精力放在提示词和素材质量上，收益远高于调参。
4.3--offload_model的隐藏开关
该参数仅在单GPU模式下生效。多卡模式下设为True会被忽略，且可能引发NCCL通信异常。它的真正价值在于：
- 单卡80GB场景：设为
False（默认），榨干显存性能 - 单卡24GB调试：设为
True，虽慢但能跑通，用于验证流程正确性
关键提示：修改此参数后，必须同步调整
--num_gpus_dit为1，否则脚本会因GPU数量不匹配而退出。
5. 故障排查：从症状到根因
当系统报错时，别急着重装。Live Avatar的错误信息高度结构化，按以下三步定位，80%问题可在5分钟内解决：
5.1 第一步：看错误类型归类
| 错误类型 | 典型报错片段 | 优先检查项 |
|---|---|---|
| CUDA OOM | torch.OutOfMemoryError: CUDA out of memory | --size,--num_clip,--infer_frames |
| NCCL通信失败 | NCCL error: unhandled system error | CUDA_VISIBLE_DEVICES,NCCL_P2P_DISABLE |
| 模型加载失败 | OSError: Unable to load weights... | ckpt_dir路径、磁盘空间、文件完整性 |
| Gradio无法访问 | 浏览器显示This site can’t be reached | lsof -i :7860, 防火墙、端口占用 |
5.2 第二步：用最小集复现
抛弃所有自定义参数，用最简命令验证基础功能：
# CLI模式最小集（4卡） ./run_4gpu_tpp.sh --prompt "a person" --image examples/dwarven_blacksmith.jpg --audio examples/dwarven_blacksmith.wav --size "384*256" --num_clip 5 # Gradio模式最小集（4卡） ./run_4gpu_gradio.sh --prompt "a person"若最小集成功，则问题出在你的参数组合；若失败，则是环境或模型问题。
5.3 第三步：查todo.md找答案
搜索报错关键词，例如：
- 搜索
NCCL→ 找到[Planned] NCCL timeout tuning for multi-node inference - 搜索
VAE→ 找到[In Progress] VAE memory optimization for 24GB GPUs
这能帮你判断：是已知问题（等修复），还是配置错误（需调整）。
6. 性能优化：务实主义指南
不要追求理论峰值，Live Avatar的优化目标很朴素：在你现有硬件上，用最少时间生成可交付质量的视频。以下是经实测验证的四条铁律：
6.1 分辨率是第一杠杆
显存占用与分辨率呈平方关系。704*384（27万像素）比384*256（9.8万像素）显存多占约1.8倍。但人眼对384*256的观感，在社交媒体传播中几乎无损。推荐工作流：
- 初稿/预览：
384*256→ 2分钟出片，快速验证创意 - 终稿交付：
688*368→ 平衡画质与效率，4090友好 - 宣传大片：
704*384→ 仅限80GB GPU，且需预留30%显存余量
6.2 在线解码（--enable_online_decode）是长视频唯一解
生成1000片段视频时，若不启用该选项，VAE解码缓冲区会持续累积，最终OOM。启用后，每生成一个片段即刻写入磁盘并释放内存，显存恒定在19GB左右。代价是总耗时增加约12%，但换来的是稳定性。
6.3 批量处理请用脚本，而非GUI
Gradio界面适合单次调试，批量任务请用CLI+Shell脚本。示例安全批处理（防OOM）：
#!/bin/bash # safe_batch.sh for audio in audio/*.wav; do echo "Processing $(basename $audio)..." # 强制小分辨率+短片段，确保每轮显存可控 ./run_4gpu_tpp.sh \ --audio "$audio" \ --size "384*256" \ --num_clip 20 \ --sample_steps 3 \ --prompt "professional speaker, clear voice, studio lighting" sleep 10 # 给GPU冷却时间 done6.4 监控比猜测更有效
运行时执行：
watch -n 1 'nvidia-smi --query-gpu=memory.used,utilization.gpu --format=csv,noheader,nounits'观察两列数据：
- 若
memory.used持续>95%，立即降低--size - 若
utilization.gpu长期<30%，说明CPU或IO成为瓶颈，可增加--num_workers
7. 总结：理性看待当前能力边界
Live Avatar是一项前沿技术，它的惊艳效果背后是真实的工程约束。本文档不回避硬件门槛，因为掩盖问题只会延长试错周期。当你面对5张4090仍无法运行时，请记住：
- 这不是你的错，是模型规模与当前GPU生态的阶段性错位
todo.md是你的盟友，它坦诚记录了“哪里不行”和“何时可能行”- 最高效的部署，是选择与硬件匹配的模式（4GPU TPP），而非强行挑战单卡极限
- 真正的生产力提升，来自标准化工作流（预览→调试→交付），而非单次参数调优
下一步行动建议：
- 立即检查
todo.md中24GB GPU条目的最新状态 - 用
--size "384*256" --num_clip 10运行最小集，建立信心 - 将
safe_batch.sh脚本加入你的自动化流水线
技术的价值不在于它能做什么，而在于它如何帮你在现实约束下达成目标。Live Avatar正在路上，而你，已经站在了正确的起点。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
