StableAvatar

环境要求

• 已安装 Python 与 pip 的 Linux/Windows 环境
• NVIDIA GPU 及匹配的 CUDA 驱动（普通卡用 cu124，Blackwell 系列用 cu128）
• 基础模型（model_full_load 模式）生成 5 秒 480x832、25fps 视频约需 18GB 显存
• 足够的磁盘空间用于存放仓库依赖与模型权重

安装与启动步骤

1. 1获取项目代码

   从 GitHub 拉取 StableAvatar 仓库，后续所有环境安装命令都在仓库根目录执行。

   git clone https://github.com/Francis-Rings/StableAvatar.git
   cd StableAvatar

   复制

2. 2安装 PyTorch 基础环境

   按 README 指定版本安装基于 CUDA 12.4 的 torch、torchvision、torchaudio，版本号勿随意改动。

   pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.1.1 --index-url https://download.pytorch.org/whl/cu124

   复制

3. 3安装项目依赖

   安装仓库 requirements.txt 中列出的全部依赖，需在项目根目录执行。

   pip install -r requirements.txt

   复制

4. 4可选：安装 flash_attn

   README 标注为可选项，用于加速注意力计算；编译失败可跳过，不影响基本使用。

   pip install flash_attn

   复制

5. 5Blackwell 芯片替代方案

   若使用 Blackwell 系列显卡，改用 CUDA 12.8 版本的 PyTorch 组合，再装依赖与可选的 flash_attn。

   pip install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 --index-url https://download.pytorch.org/whl/cu128
   pip install -r requirements.txt
   pip install flash_attn

   复制

6. 6按显存调整参数

   显存不足时适当减少生成帧数或降低输出分辨率；基础版支持 480x832、832x480、512x512。

关键配置

如何确认成功

pip 安装无报错，执行 python -c "import torch;print(torch.cuda.is_available())" 输出 True 即环境就绪。

常见问题

注意事项

• torch 与 CUDA 版本必须按 README 匹配，普通卡用 cu124 组合，Blackwell 系列用 cu128 组合。
• 性能参考：5 秒 480x832、25fps 的视频在 4090 上约需 18GB 显存、耗时约 3 分钟。
• README 节选中未给出具体推理/启动脚本命令，实际生成命令需查阅仓库内脚本与参数说明。
• 全量加载（model_full_load）显存占用较高，长视频解码建议考虑将 VAE 放 CPU。