StableAvatar

StableAvatar：无限时长音频驱动的虚拟形象视频生成
涂书源¹、潘月明³、黄寅明¹、韩欣彤⁴、邢震¹、戴琪²、罗冲²、吴祖轩¹、蒋宇刚¹
[¹复旦大学；²微软亚洲研究院；³西安交通大学；⁴腾讯公司]

由StableAvatar生成的音频驱动虚拟形象视频，展示了其合成无限时长且保持身份一致视频的强大能力。所有视频均由StableAvatar直接合成，未使用任何与人脸相关的后处理工具,例如换脸工具FaceFusion或人脸修复模型GFP-GAN和CodeFormer。

StableAvatar与当前最先进（SOTA）的音频驱动虚拟形象视频生成模型的对比结果凸显了StableAvatar在提供无限时长、高保真、身份一致的虚拟形象动画方面的卓越性能。

概述

StableAvatar框架的概览。

目前用于音频驱动虚拟形象视频生成的扩散模型难以合成具有自然音频同步和身份一致性的长视频。本文提出了StableAvatar，这是首个无需后处理即可合成无限时长高质量视频的端到端视频扩散Transformer。StableAvatar以参考图像和音频为条件，集成了定制化的训练和推理模块，从而实现无限时长视频的生成。 我们观察到，现有模型无法生成长视频的主要原因在于其音频建模方式。这些模型通常依赖第三方现成的提取器来获取音频嵌入，然后通过交叉注意力直接将其注入扩散模型中。由于当前的扩散主干网络缺乏任何与音频相关的先验知识，这种方法会导致视频片段之间潜变量分布误差的严重累积，从而使后续片段的潜变量分布逐渐偏离最优分布。 为此，StableAvatar引入了一种新颖的时步感知音频适配器，通过时步感知调制来防止误差累积。在推理过程中，我们提出了一种新的音频原生引导机制，利用扩散模型自身不断演进的联合音频-潜变量预测作为动态引导信号，进一步提升音频同步效果。为了增强无限时长视频的流畅性，我们还引入了一种动态加权滑动窗口策略，用于随时间融合潜变量。基准测试实验表明，StableAvatar在定性和定量两方面均表现出色。

新闻

• [2025-10-12]: 🔥 我们修复了 多GPU 和 单GPU 推理之间的不一致问题。补丁已合并——请更新到最新版本并试用！🙌
• [2025-9-8]:🔥 我们很高兴发布一个有趣的 🔥🔥 全新演示 🔥🔥！生成的视频可以在 YouTube 和 Bilibili 上观看。
• [2025-8-29]:🔥 StableAvatar 公开演示现已在 Hugging Face Spaces 上线。（注意：由于视频生成时间较长，目前该演示仅对 Hugging Face Pro 用户开放。）
• [2025-8-18]:🔥 StableAvatar 只需 10 步即可在 ComfyUI 上运行，速度提升至原来的 3 倍。感谢 @smthemex 的贡献。
• [2025-8-16]:🔥 我们发布了微调代码以及 LoRA 训练/微调代码！其他代码将尽快公开，请持续关注！
• [2025-8-15]:🔥 StableAvatar 可以在 Gradio 界面上运行。感谢 @gluttony-10 的贡献！
• [2025-8-15]:🔥 StableAvatar 可以在 ComfyUI 上运行。感谢 @smthemex 的贡献。
• [2025-8-13]:🔥 添加了支持在全新 Blackwell 系列 Nvidia 芯片上运行 StableAvatar 的更改，包括 RTX 6000 Pro。
• [2025-8-11]:🔥 项目页面、代码、技术报告以及 基础模型检查点 已发布。进一步的 LoRA 训练代码、评估数据集和 StableAvatar-pro 将很快发布。敬请期待！

🛠️ 待办事项

• StableAvatar-1.3B-basic
• 推理代码
• 数据预处理代码（音频提取）
• 数据预处理代码（人声分离）
• 训练代码
• 完整微调代码
• LoRA 训练代码
• LoRA 微调代码
• 带有音频原生引导的推理代码
• StableAvatar-pro

🔑 快速入门

对于基础版本的模型检查点（Wan2.1-1.3B 基础），它支持生成 无限长度的视频，分辨率为 480×832 或 832×480 或 512×512。如果遇到内存不足的问题，可以适当减少动画帧数或降低输出分辨率。

🧱 环境搭建

pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.1.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
# 可选安装 flash_attn 以加速注意力计算
pip install flash_attn

🧱 Blackwell 系列芯片的环境搭建

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
# 可选安装 flash_attn 以加速注意力计算
pip install flash_attn

🧱 下载权重

如果遇到与 Hugging Face 连接问题，可以通过设置环境变量来使用镜像端点：export HF_ENDPOINT=https://hf-mirror.com。 请按以下步骤手动下载权重：

pip install "huggingface_hub[cli]"
cd StableAvatar
mkdir checkpoints
huggingface-cli download FrancisRing/StableAvatar --local-dir ./checkpoints

所有权重应按如下方式组织在 models 文件夹中： 该项目的整体文件结构应如下所示：

StableAvatar/
├── accelerate_config
├── deepspeed_config
├── examples
├── wan
├── checkpoints
│   ├── Kim_Vocal_2.onnx
│   ├── wav2vec2-base-960h
│   ├── Wan2.1-Fun-V1.1-1.3B-InP
│   └── StableAvatar-1.3B
├── inference.py
├── inference.sh
├── train_1B_square.py
├── train_1B_square.sh
├── train_1B_vec_rec.py
├── train_1B_vec_rec.sh
├── audio_extractor.py
├── vocal_seperator.py
├── requirement.txt 

🧱 音频提取

给定目标视频文件 (.mp4)，可以使用以下命令获取对应的音频文件 (.wav)：

python audio_extractor.py --video_path="path/test/video.mp4" --saved_audio_path="path/test/audio.wav"

🧱 人声分离

由于嘈杂的背景音乐可能会在一定程度上影响 StableAvatar 的表现，可以进一步从音频文件中分离出人声，以获得更好的唇形同步效果。 给定音频文件 (.wav) 的路径，可以运行以下命令提取相应的人声信号：

pip install audio-separator[gpu]
python vocal_seperator.py --audio_separator_model_file="path/StableAvatar/checkpoints/Kim_Vocal_2.onnx" --audio_file_path="path/test/audio.wav" --saved_vocal_path="path/test/vocal.wav"

🧱 基础模型推理

我们提供了一个用于测试的示例配置文件 inference.sh。您也可以根据自己的需求轻松修改其中的各项配置。

bash inference.sh

基于 Wan2.1-1.3B 的 StableAvatar 支持三种不同分辨率设置下的音频驱动虚拟人视频生成：512×512、480×832 和 832×480。您可以在 inference.sh 中修改 --width 和 --height 来设置动画的分辨率。--output_dir 指的是生成动画的保存路径。--validation_reference_path、--validation_driven_audio_path 和 --validation_prompts 分别指代提供的参考图像路径、音频文件路径以及文本提示。

提示词同样非常重要。建议按照以下格式填写：“[第一帧描述]-[人物行为描述]-[背景描述（可选）]”。

--pretrained_model_name_or_path、--pretrained_wav2vec_path 和 --transformer_path 分别是预训练的 Wan2.1-1.3B 权重、Wav2Vec2.0 预训练权重以及 StableAvatar 预训练权重的路径。

--sample_steps、--overlap_window_length 和 --clip_sample_n_frames 分别表示总的推理步数、两个上下文窗口之间的重叠长度，以及每个批次/上下文窗口中合成的帧数。

值得注意的是，推荐的 --sample_steps 范围为 [30-50]，步数越多，生成质量越高。而 --overlap_window_length 的推荐范围则是 [5-15]，较长的重叠长度会带来更高的质量，但也会降低推理速度。

--sample_text_guide_scale 和 --sample_audio_guide_scale 分别是文本提示和音频的无分类指导尺度。对于提示和音频的 CFG 值，推荐范围为 [3-6]。您可以适当提高音频的 CFG 值，以更好地实现唇形同步。

此外，您还可以运行以下命令来启动 Gradio 界面：

python app.py

我们在 path/StableAvatar/examples 中提供了 6 个不同分辨率设置下的案例供您验证。❤️❤️欢迎尝试体验，并尽情享受无限长度虚拟人视频生成带来的无穷乐趣❤️❤️！

💡 小贴士

• 基于 Wan2.1-1.3B 的 StableAvatar 权重有两个版本：transformer3d-square.pt 和 transformer3d-rec-vec.pt，它们分别在两种不同分辨率设置的视频数据集上进行训练。这两个版本都支持在三种不同分辨率下生成音频驱动的虚拟人视频：512×512、480×832 和 832×480。您可以通过修改 inference.sh 中的 --transformer_path 来切换这两个版本。

• 如果您的 GPU 资源有限，可以通过修改 inference.sh 中的 --GPU_memory_mode 来调整 StableAvatar 的加载模式。--GPU_memory_mode 的选项包括 model_full_load、sequential_cpu_offload、model_cpu_offload_and_qfloat8 以及 model_cpu_offload。特别地，当您将 --GPU_memory_mode 设置为 sequential_cpu_offload 时，总的 GPU 内存消耗约为 3GB，但推理速度会较慢。 将 --GPU_memory_mode 设置为 model_cpu_offload 可以显著减少 GPU 内存占用，相比 model_full_load 模式大约能节省一半的内存。

• 如果您有多块 GPU，可以通过修改 inference.sh 中的 --ulysses_degree 和 --ring_degree 来进行多 GPU 推理以加速处理。例如，如果您有 8 张 GPU 卡，可以设置 --ulysses_degree=4 和 --ring_degree=2。需要注意的是，ulysses_degree * ring_degree 必须等于 GPU 总数或世界尺寸。此外，您还可以在 inference.sh 中添加 --fsdp_dit 来激活 DiT 中的 FSDP，进一步降低 GPU 内存占用。 您可以运行以下命令：

bash multiple_gpu_inference.sh

在我的设置中，使用了 4 张 GPU 进行推理。

StableAvatar 合成的视频不包含音频。如果您希望获得带有音频的高质量 MP4 文件，我们建议您在 <b>output_path</b> 上使用 ffmpeg 进行处理，具体命令如下：

ffmpeg -i video_without_audio.mp4 -i /path/audio.wav -c:v copy -c:a aac -shortest /path/output_with_audio.mp4

🧱 模型训练

🔥🔥需要注意的是，如果你打算训练一个条件化的视频扩散Transformer（DiT）模型，比如Wan2.1，那么本训练教程同样会对你有所帮助。🔥🔥 训练数据集需要按照以下结构进行组织：

talking_face_data/
├── rec
│   │  ├──speech
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  │  ├──frame_0.png
│   │  │  │  │  ├──frame_1.png
│   │  │  │  │  ├──frame_2.png
│   │  │  │  │  ├──...
│   │  │  │  ├──face_masks
│   │  │  │  │  ├──frame_0.png
│   │  │  │  │  ├──frame_1.png
│   │  │  │  │  ├──frame_2.png
│   │  │  │  │  ├──...
│   │  │  │  ├──lip_masks
│   │  │  │  │  ├──frame_0.png
│   │  │  │  │  ├──frame_1.png
│   │  │  │  │  ├──frame_2.png
│   │  │  │  │  ├──...
│   │  │  ├──00002
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
│   │  ├──singing
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
│   │  ├──dancing
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
├── vec
│   │  ├──speech
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
│   │  ├──singing
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
│   │  ├──dancing
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
├── square
│   │  ├──speech
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
│   │  ├──singing
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
│   │  ├──dancing
│   │  │  ├──00001
│   │  │  │  ├──sub_clip.mp4
│   │  │  │  ├──audio.wav
│   │  │  │  ├──images
│   │  │  │  ├──face_masks
│   │  │  │  ├──lip_masks
│   │  │  └──...
├── video_rec_path.txt
├── video_square_path.txt
└── video_vec_path.txt

StableAvatar是在混合分辨率的视频上进行训练的，其中512x512分辨率的视频存储在talking_face_data/square中，480x832分辨率的视频存储在talking_face_data/vec中，而832x480分辨率的视频则存储在talking_face_data/rec中。在talking_face_data/square、talking_face_data/rec和talking_face_data/vec中的每个文件夹都包含三个子文件夹，分别存放不同类型的视频（演讲、歌唱和舞蹈）。 所有.png格式的图像文件均以frame_i.png的形式命名，例如frame_0.png、frame_1.png等。 00001、00002、00003等编号用于标识不同的视频信息。 在三个子文件夹中，images用于存放RGB帧，face_masks用于存放相应的人脸掩码，而lip_masks则用于存放相应的嘴唇掩码。 sub_clip.mp4和audio.wav分别对应于images中的RGB视频以及对应的音频文件。 video_square_path.txt、video_rec_path.txt和video_vec_path.txt分别记录了talking_face_data/square、talking_face_data/rec和talking_face_data/vec的文件夹路径。 例如，video_rec_path.txt的内容如下：

path/StableAvatar/talking_face_data/rec/speech/00001
path/StableAvatar/talking_face_data/rec/speech/00002
...
path/StableAvatar/talking_face_data/rec/singing/00003
path/StableAvatar/talking_face_data/rec/singing/00004
...
path/StableAvatar/talking_face_data/rec/dancing/00005
path/StableAvatar/talking_face_data/rec/dancing/00006
...

如果你只有原始视频，可以使用ffmpeg从原始视频（如演讲视频）中提取帧，并将其存储在images子文件夹中。

ffmpeg -i raw_video_1.mp4 -q:v 1 -start_number 0 path/StableAvatar/talking_face_data/rec/speech/00001/images/frame_%d.png

提取出的帧将被保存到path/StableAvatar/talking_face_data/rec/speech/00001/images目录下。 关于人脸掩码的提取，请参考StableAnimator仓库。该教程中的“人脸掩码提取”部分提供了现成的代码。 对于嘴唇掩码的提取，可以运行以下命令：

pip install mediapipe
python lip_mask_extractor.py --folder_root="path/StableAvatar/talking_face_data/rec/singing" --start=1 --end=500

--folder_root指定了训练数据集的根路径。 --start和--end则分别指定了所选训练数据集的起始和结束索引。例如，--start=1 --end=500表示嘴唇提取将从path/StableAvatar/talking_face_data/rec/singing/00001开始，到path/StableAvatar/talking_face_data/rec/singing/00500结束。 有关音频提取的详细信息，请参阅“音频提取”部分。 当你的数据集完全按照上述结构组织好后，你就可以通过运行以下命令轻松地训练基于Wan2.1-1.3B的StableAvatar模型：

# 在单台机器上以单一分辨率（512x512）训练StableAvatar
bash train_1B_square.sh
# 在多台机器上以单一分辨率（512x512）训练StableAvatar
bash train_1B_square_64.sh
# 在单台机器上以混合分辨率（480x832和832x480）训练StableAvatar
bash train_1B_rec_vec.sh

# 在多台机器上以混合分辨率设置（480×832 和 832×480）训练 StableAvatar
bash train_1B_rec_vec_64.sh

关于 train_1B_square.sh 和 train_1B_rec_vec.sh 的参数说明：CUDA_VISIBLE_DEVICES 指定使用的 GPU 设备。在我的配置中，我使用 4 张 NVIDIA A100 80G 显卡来训练 StableAvatar（CUDA_VISIBLE_DEVICES=3,2,1,0）。 --pretrained_model_name_or_path、--pretrained_wav2vec_path 和 --output_dir 分别指预训练的 Wan2.1-1.3B 路径、预训练的 Wav2Vec2.0 路径以及训练好的 StableAvatar 检查点保存路径。 --train_data_square_dir、--train_data_rec_dir 和 --train_data_vec_dir 分别是 video_square_path.txt、video_rec_path.txt 和 video_vec_path.txt 的文件路径。 --validation_reference_path 和 --validation_driven_audio_path 分别是验证用参考图像和驱动音频的文件路径。 --video_sample_n_frames 是 StableAvatar 在单个批次中处理的帧数。 --num_train_epochs 是训练轮数。值得注意的是，训练轮数的默认值被设置为无限，当您观察到 StableAvatar 达到最佳性能时，可以手动终止训练过程。 对于 train_1B_square_64.sh 和 train_1B_rec_vec_64.sh 的参数说明，我们在 path/StableAvatar/accelerate_config/accelerate_config_machine_1B_multiple.yaml 中设置了 GPU 配置。在我的配置中，训练环境由 8 个节点组成，每个节点配备 8 张 NVIDIA A100 80GB 显卡，用于训练 StableAvatar。

StableAvatar 训练时的整体文件结构如下：

StableAvatar/
├── accelerate_config
├── deepspeed_config
├── talking_face_data
├── examples
├── wan
├── checkpoints
│   ├── Kim_Vocal_2.onnx
│   ├── wav2vec2-base-960h
│   ├── Wan2.1-Fun-V1.1-1.3B-InP
│   └── StableAvatar-1.3B
├── inference.py
├── inference.sh
├── train_1B_square.py
├── train_1B_square.sh
├── train_1B_vec_rec.py
├── train_1B_vec_rec.sh
├── audio_extractor.py
├── vocal_seperator.py
├── requirement.txt 

值得注意的是，由于采用混合分辨率（480×832 和 832×480）的训练流程，训练 StableAvatar 大约需要 50GB 的显存。 然而，如果您仅使用 512×512 的视频进行训练，显存需求将降低至约 40GB。 此外，所选训练视频的背景应保持静止，这有助于扩散模型准确计算重建损失。 音频应清晰，避免过多背景噪声。

关于基于 Wan2.1-14B 的 StableAvatar 训练，您可以运行以下命令：

# 在多台机器上以混合分辨率设置（480×832、832×480 和 512×512）训练 StableAvatar
huggingface-cli download Wan-AI/Wan2.1-I2V-14B-480P --local-dir ./checkpoints/Wan2.1-I2V-14B-480P
huggingface-cli download Wan-AI/Wan2.1-I2V-14B-720P --local-dir ./checkpoints/Wan2.1-I2V-14B-720P # 可选
bash train_14B.sh

我们使用 DeepSpeed Stage-2 来训练基于 Wan2.1-14B 的 StableAvatar。GPU 配置可以在 path/StableAvatar/accelerate_config/accelerate_config_machine_14B_multiple.yaml 中修改。 DeepSpeed 优化配置和调度器配置位于 path/StableAvatar/deepspeed_config/zero_stage2_config.json。 值得注意的是，我们观察到基于 Wan2.1-1.3B 的 StableAvatar 已经能够合成无限长度的高质量头像视频。而基于 Wan2.1-14B 的骨干网络在训练过程中会显著增加推理延迟和 GPU 内存消耗，表明其性能与资源消耗之间的效率有限。

您还可以运行以下命令进行 LoRA 微调：

# 在单台机器上以混合分辨率设置（480×832 和 832×480）训练 StableAvatar-1.3B
bash train_1B_rec_vec_lora.sh
# 在多台机器上以混合分辨率设置（480×832 和 832×480）训练 StableAvatar-1.3B
bash train_1B_rec_vec_lora_64.sh
# 在多台机器上以混合分辨率设置（480×832、832×480 和 512×512）训练基于 Wan2.1-14B 的 StableAvatar
bash train_14B_lora.sh

您可以通过调整 --rank 和 --network_alpha 来控制 LoRA 微调的质量。

如果您希望训练基于 Wan2.1-1.3B 或 Wan2.1-14B 的 720P 版本 StableAvatar，可以直接在 train_1B_square.py、train_1B_vec_rec.py 或 train_14B.py 中修改数据加载器的高度和宽度（480p→720p）。

🧱 模型微调

对于完整微调 StableAvatar，您可以在 train_1B_rec_vec.sh 或 train_1B_rec_vec_64.sh 中添加 --transformer_path="path/StableAvatar/checkpoints/StableAvatar-1.3B/transformer3d-square.pt"：

# 在单台机器上以混合分辨率设置（480×832 和 832×480）微调 StableAvatar
bash train_1B_rec_vec.sh
# 在多台机器上以混合分辨率设置（480×832 和 832×480）微调 StableAvatar
bash train_1B_rec_vec_64.sh

对于 LoRA 微调 StableAvatar，您可以在 train_1B_rec_vec_lora.sh 中添加 --transformer_path="path/StableAvatar/checkpoints/StableAvatar-1.3B/transformer3d-square.pt"：

# 在单台机器上以混合分辨率设置（480×832 和 832×480）LoRA 微调 StableAvatar-1.3B
bash train_1B_rec_vec_lora.sh

您可以通过调整 --rank 和 --network_alpha 来控制 LoRA 训练/微调的质量。

🧱 显存需求与运行时间

对于一段 5 秒的视频（480×832，帧率 25fps），基础模型（--GPU_memory_mode="model_full_load") 大约需要 18GB 显存，并在 4090 显卡上 3 分钟内完成渲染。

🔥🔥理论上，StableAvatar 能够合成数小时的视频而不会出现明显的质量下降；然而，3D VAE 解码器对 GPU 显存的需求非常大，尤其是在解码 1 万帧以上时。您也可以选择在 CPU 上运行 VAE。🔥🔥

联系方式

如果您有任何建议或认为我们的工作有所帮助，请随时与我联系。

邮箱：francisshuyuan@gmail.com

如果您觉得我们的工作有用，请考虑给这个 GitHub 仓库点个赞 ⭐ 并引用它 ❤️：

@article{tu2025stableavatar,
  title={Stableavatar: Infinite-length audio-driven avatar video generation},
  author={Tu, Shuyuan and Pan, Yueming and Huang, Yinming and Han, Xintong and Xing, Zhen and Dai, Qi and Luo, Chong and Wu, Zuxuan and Jiang, Yu-Gang},
  journal={arXiv preprint arXiv:2508.08248},
  year={2025}
}

StableAvatar 快速上手指南

StableAvatar 是一个端到端的视频扩散 Transformer 模型，能够根据参考图像和音频生成无限长度、高保真且身份一致的虚拟人视频。无需任何面部交换或修复等后处理工具。

1. 环境准备

系统要求

• 操作系统: Linux (推荐) 或 Windows
• GPU: NVIDIA 显卡 (支持 CUDA)
  • 常规显卡：建议显存 16GB 以上（可通过降低分辨率或帧数适配更低显存）
  • Blackwell 系列 (如 RTX 6000 Pro)：需特定版本依赖
• Python: 3.10+

前置依赖

确保已安装 Git 和 FFmpeg（用于音视频处理）。

2. 安装步骤

步骤一：克隆项目

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

步骤二：安装核心依赖

方案 A：常规 NVIDIA 显卡 (CUDA 12.4)

pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.1.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
# 可选：安装 flash_attn 加速注意力计算
pip install flash_attn

方案 B：Blackwell 系列新架构显卡 (CUDA 12.8)

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

国内加速提示：若下载 PyTorch 或 HuggingFace 资源缓慢，可设置镜像环境变量：

export HF_ENDPOINT=https://hf-mirror.com

步骤三：下载模型权重

使用 HuggingFace CLI 下载模型至 checkpoints 目录：

pip install "huggingface_hub[cli]"
mkdir checkpoints
huggingface-cli download FrancisRing/StableAvatar --local-dir ./checkpoints

下载完成后，目录结构应如下：

StableAvatar/
├── checkpoints
│   ├── Kim_Vocal_2.onnx
│   ├── wav2vec2-base-960h
│   ├── Wan2.1-Fun-V1.1-1.3B-InP
│   └── StableAvatar-1.3B
├── inference.sh
└── ... (其他代码文件)

3. 基本使用

步骤一：音频预处理（可选但推荐）

为了获得更好的唇形同步效果，建议先从视频中提取音频并分离人声（去除背景音乐干扰）。

1. 提取音频 (.mp4 -> .wav):

python audio_extractor.py --video_path="path/test/video.mp4" --saved_audio_path="path/test/audio.wav"

2. 分离人声 (.wav -> vocal.wav):

pip install audio-separator[gpu]
python vocal_seperator.py --audio_separator_model_file="checkpoints/Kim_Vocal_2.onnx" --audio_file_path="path/test/audio.wav" --saved_vocal_path="path/test/vocal.wav"

步骤二：运行推理

修改 inference.sh 脚本中的参数以匹配你的文件路径，然后执行：

bash inference.sh

关键参数说明（可在 inference.sh 中调整）：

• --validation_reference_path: 参考人物图片路径。
• --validation_driven_audio_path: 驱动音频路径（推荐使用分离后的人声）。
• --validation_prompts: 文本提示词，格式建议为 [首帧描述]-[人物行为描述]-[背景描述 (可选)]。
• --width / --height: 分辨率，支持 512x512, 480x832, 832x480。
• --sample_steps: 推理步数，推荐范围 [30-50]，步数越多质量越高。
• --overlap_window_length: 滑动窗口重叠长度，推荐 [5-15]，越大越平滑但速度越慢。
• --output_dir: 生成视频的保存路径。

生成完成后，无限长度的虚拟人视频将保存在指定输出目录中。