README.md

# Wan2\.1\-T2V\-1\.3B 稀疏注意力\+DMD2蒸馏模型
# 模型效果演示

为直观展示本稀疏注意力\+DMD2蒸馏模型的真实生成效果，我们采用两组写实风格英文提示词进行测试推理。模型在轻量化蒸馏后，依旧具备优秀的细节刻画、光影渲染与动态时序建模能力，画面稳定无闪烁、细节丰富、语义贴合度高，完整演示效果如下：

**Prompt 1**：`A translucent jellyfish pulses rhythmically in the deep blue ocean, its tentacles trailing like silk ribbons in the current.`

**视频效果展示**：模型完美呈现了深邃幽蓝的深海环境，光影穿透水体的质感真实且富有层次。半透明水母的躯体晶莹剔透，内部结构隐约可见，其律动收缩的节奏平稳而富有生命力。触须如丝绸般在暗流中优雅舒展、飘动，物理模拟极其细腻，无僵硬或穿模现象。整体画面静谧而梦幻，色彩过渡柔和自然，充分展现了模型在处理复杂流体动态、半透明材质渲染以及微观生物细节方面的卓越能力。
![Demo Video](./videos/output.gif)

**Prompt 2**：`A fluffy red panda clings to a moss-covered branch in a misty bamboo forest, its tail curled tightly around the wood for balance.`

**视频效果展示**：模型完美营造出雾气氤氲的竹林氛围感，林间雾气朦胧柔和、质感通透。画面中的小熊猫体态蓬松柔软，紧紧攀附在布满青苔的树枝上，尾部缠绕枝干保持平衡的动作细节精准还原，肢体动态自然真实。场景光影柔和细腻，植被、青苔、雾气细节质感拉满，时序画面高度稳定，展现出模型对复杂自然场景与精细生物动态的优秀建模能力。

![Demo Video](./videos/2.gif)

# 模型简介

本模型基于**Wan2\.1\-T2V\-1\.3B**官方文本生成视频基座模型，采用**稀疏注意力（Video Sparse Attn）\+ DMD2**双优化策略完成模型蒸馏。在完整保留原模型视频生成画质、文本对齐能力、动态画面表现力的前提下，大幅降低模型推理算力开销、提升视频生成速度，适配单卡/多卡轻量化推理部署场景，兼顾生成质量与推理效率。

模型蒸馏训练全程基于4卡GPU完成，通过精细化的时序蒸馏、稀疏化注意力优化、动态去噪策略优化，解决了原生大模型推理延迟高、显存占用大的痛点，可高效生成320×576分辨率、48帧时长的高清短视频，适配通用文生视频创作场景。

# 核心蒸馏创新点

## 1\. 稀疏注意力优化（VSA）

训练全程启用 `FASTVIDEO_ATTENTION_BACKEND=VIDEO_SPARSE_ATTN` 稀疏注意力后端，区别于原生Torch SDPA密集注意力机制，通过**VSA稀疏度0\.8**的精细化配置，过滤视频时序冗余注意力计算，在几乎无损生成画质的基础上，大幅减少时序维度计算量，有效降低推理显存占用与运算耗时。

## 2\. DMD2动态多尺度蒸馏策略

采用DMD2专属蒸馏方案，配置多阶段去噪步骤 `1000,757,522`，结合时序比例阈值（0\.02\~0\.98）约束，实现模型多尺度时序特征学习。通过生成器迭代更新、真实分数引导缩放（3\.5）的组合优化，让蒸馏模型精准复刻原模型的视频光影、运动趋势、细节纹理特征，避免蒸馏后画面模糊、动态卡顿、文本对齐偏差等问题。

## 3\. 分布式精细化蒸馏训练

基于4卡GPU分布式训练，通过HSDP分层分片复制策略优化并行计算逻辑，搭配完整的梯度检查点、混合精度训练、梯度裁剪等优化手段，保障大规模蒸馏训练的稳定性，同时最大化保留原模型的生成能力，实现高效、高质量的模型轻量化蒸馏。

# 训练超参与环境配置

## 1\. 硬件与环境

- **训练设备**：单节点4卡GPU

- **注意力后端**：Video Sparse Attn（稀疏注意力）

- **精度模式**：bf16混合精度训练，模型推理核心精度fp32

- **日志监控**：Weights \& Biases 在线监控训练过程

## 2\. 核心训练参数

- **总训练步数**：4000步

- **批次大小**：训练batch\_size=1，梯度累积步数=1

- **学习率**：2e\-6

- **权重衰减**：0\.01，最大梯度范数：1\.0

- **生成参数**：隐式时序数12，分辨率320×576，最大帧数48

- **验证策略**：每800步验证一次，采样步数3，引导系数6\.0

- **DMD核心参数**：VSA稀疏度0\.8、真实分数引导缩放3\.5、生成器更新间隔5

- **流偏移系数**：8，随机种子：1000

# 模型能力与效果优势

- **画质无损**：完全继承Wan2\.1\-T2V\-1\.3B原生高清生成能力，画面细节、色彩还原、动态流畅度与原模型一致

- **推理高效**：稀疏注意力大幅降低计算冗余，推理速度显著提升，显存占用更低，适配消费级、轻量服务器部署

- **时序稳定**：DMD2多尺度去噪蒸馏，有效改善短视频生成卡顿、跳帧、动态模糊问题

- **泛化性强**：适配通用文本生成视频场景，支持风景、人物、创意场景、写实画面等多类型视频生成



# 快速使用示例

本模型兼容Diffusers架构，可直接通过Modelscope、Diffusers快速加载推理，基础调用示例如下：

```shell
#下载fastvideo推理框架
pip install fastvideo
#下载vsa注意力
pip install vsa --index-url https://pypi.tuna.tsinghua.edu.cn/simple
#下载模型权重
modelscope download --model HZNing/Wan2.1-DMD2 --local_dir ./Wan2.1-DMD2-Local
```

```python
import os
import time
from fastvideo import VideoGenerator

def main():
    # ==========================
    # 1. Environment Setup
    # ==========================
    os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "VIDEO_SPARSE_ATTN"
    # 如果显存不足，可以尝试切换回 TORCH_SDPA
    # os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "TORCH_SDPA"

    # ==========================
    # 2. Configuration
    # ==========================
    MODEL_PATH = "./Wan2.1-DMD2-Local"
    OUTPUT_DIR = "my_videos/"
    NUM_GPUS = 1
    
    # 生成参数 (根据模型能力调整)
    GENERATE_KWARGS = {
        "num_frames": 81,       # 视频帧数
        "height": 480,          # 高度
        "width": 832,           # 宽度
        "guidance_scale": 6.0,  # 引导系数
        "num_inference_steps": 30, # 推理步数
    }

    # ==========================
    # 3. Prompts List
    # ==========================
    prompts = [
        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes wide with interest.",
        "A fluffy red panda clings to a moss-covered branch in a misty bamboo forest, its tail curled tightly around the wood for balance.",
    ]

    # ==========================
    # 4. Initialize Generator
    # ==========================
    print(f"Loading model from: {MODEL_PATH}")
    generator = VideoGenerator.from_pretrained(
        MODEL_PATH,
        num_gpus=NUM_GPUS,
    )
    print("Model loaded successfully.\n")

    # Create output directory if it doesn't exist
    os.makedirs(OUTPUT_DIR, exist_ok=True)

    # ==========================
    # 5. Batch Generation
    # ==========================
    total_prompts = len(prompts)
    
    for idx, prompt in enumerate(prompts, 1):
        print(f"[{idx}/{total_prompts}] Generating video for prompt:")
        print(f"  Prompt: {prompt[:80]}...")  # 打印前80个字符
        
        # 生成安全的文件名 (使用索引 + 简短描述)
        # 替换空格和特殊字符为下划线
        safe_name = f"video_{idx:03d}"
        output_path = os.path.join(OUTPUT_DIR, safe_name)
        
        start_time = time.time()
        
        try:
            # 生成视频
            video = generator.generate_video(
                prompt=prompt,
                output_path=output_path,
                save_video=True,
                **GENERATE_KWARGS  # 传入额外参数
            )
            
            elapsed_time = time.time() - start_time
            print(f"  ✅ Success! Saved to: {output_path}.mp4 (Time: {elapsed_time:.2f}s)\n")
            
        except Exception as e:
            elapsed_time = time.time() - start_time
            print(f"  ❌ Failed! Error: {str(e)} (Time: {elapsed_time:.2f}s)\n")
            # 继续下一个，不中断流程
            continue

    print("="*50)
    print("Batch generation completed!")
    print(f"Output directory: {os.path.abspath(OUTPUT_DIR)}")

if __name__ == '__main__':
    main()

```

# 模型限制与说明

- 模型为**蒸馏轻量化版本**，主打高效推理，极致超高清、超长时序视频生成效果略逊于原版完整模型；

- 最优生成分辨率为320×576、48帧，超出该参数可能出现画面比例失调、细节丢失；

- 不支持暴力超长视频生成，适合短视频创意、内容素材生成场景。

# 开源与致谢

本模型基于 **Wan2\.1\-T2V\-1\.3B** 开源基座进行二次蒸馏优化，仅供学术研究、非商业场景使用。感谢原项目团队的开源贡献，欢迎各位开发者基于本模型进行二次优化、迭代与应用拓展。

# 更新日志

- 2026\.06：完成基于稀疏注意力\+DMD2的全流程蒸馏训练，正式上传Modelscope模型权重

> （注：部分内容可能由 AI 生成）