FloodDiffusionTiny完全指南：文本生成动作的Diffusion Forcing模型，一句话生成12秒人体运动

FloodDiffusionTiny 是一款轻量级的文本生成动作（Text-to-Motion）模型，基于 Diffusion Forcing（扩散强制）技术，只需输入一句自然语言描述（如 "a person walking forward"），就能生成约 12 秒（240 帧 @ 20 FPS）的高保真人体运动序列。它是原版 FloodDiffusion 的 Tiny 版本，架构更小巧，适合快速体验和二次开发。

🧩 项目亮点

• 一句话生成动作：文本驱动，输出 263 维 HumanML3D 运动特征，或直接输出 22 个关节坐标
• 流式生成能力：基于 Diffusion Forcing，支持按块（chunk）流式生成，可扩展到更长的动作序列
• 动作平滑过渡：支持多条文本按时间轴切换，实现"走 → 转身 → 跑"的连贯动作
• 模型小巧：Tiny 版本仅 8 层 Transformer，显存门槛约 16GB GPU

📂 仓库结构一览

文件/目录	作用
model.safetensors	主模型权重（Diffusion Forcing 主干）
vae.safetensors	1D VAE 权重，负责潜在空间与运动特征的互转
ldf_models/diffusion_forcing_wan_tiny.py	核心生成模型 DiffForcingWanModel
ldf_models/vae_wan_1d.py	1D 运动 VAE（编码/解码 263 维特征）
hf_pipeline.py	HuggingFace 推理管线，提供 LDFModel 接口
generate_ldf.py	命令行生成脚本与模型加载入口
ldf.yaml	模型超参数配置（层数、chunk_size 等）
ldf_utils/motion_process.py	263 维特征 → 22 关节坐标的恢复工具

🚀 快速安装：三步跑通

环境要求：Python 3.8+、CUDA GPU（建议 16GB+ 显存）、16GB+ 内存。

第 1 步：克隆仓库

git clone https://gitcode.com/hf_mirrors/AlayaLab/FloodDiffusionTiny.git

第 2 步：安装基础依赖

pip install torch transformers huggingface_hub
pip install lightning diffusers omegaconf ftfy numpy

依赖清单见 requirements.txt。

第 3 步：安装 Flash Attention（必装）

Flash Attention 是该模型的硬性依赖，需 CUDA 环境并可能涉及编译：

pip install flash-attn --no-build-isolation

💡 如果安装失败，请按照 flash-attention 官方安装指南排查（通常是 CUDA 版本不匹配导致）。

✍️ 最快上手：三行代码生成动作

加载模型并生成第一个动作，代码极简：

from transformers import AutoModel

model = AutoModel.from_pretrained(
    "ShandaAI/FloodDiffusionTiny",
    trust_remote_code=True
)

motion = model("a person walking forward", length=60)
print(motion.shape)  # (240, 263) 约 12 秒 @ 20 FPS

其中 length=60 表示生成 60 个潜在 token，经 VAE 上采样后输出帧数约为 length × 4 = 240 帧。

批量生成多条动作（支持不同长度）：

texts = [
    "a person walking forward",
    "a person running quickly",
    "a person jumping up and down",
]
lengths = [60, 50, 40]
motions = model(texts, length=lengths)

🎬 进阶玩法：多文本动作过渡

这是 Diffusion Forcing 模型最有意思的用法——在一个连续动作序列中按时序切换文本指令，模型会自动补出平滑的过渡动作：

motion = model(
    text=[["walk forward", "turn around", "run back"]],
    length=[120],
    text_end=[[40, 80, 120]]  # 每条文本的结束位置（潜在 token）
)
print(motion[0].shape)  # 约 480 帧，三个动作无缝衔接

⚠️ 注意：text_end 的长度必须与文本条数一致，且按升序排列，否则会抛出 ValueError。

⚙️ 参数速查表

调用接口定义在 hf_pipeline.py：

参数	默认值	说明
text	必填	文本描述；支持单条、列表（批量）、嵌套列表（动作过渡）
length	60	潜在 token 数，输出帧数 ≈ length × 4
text_end	None	多文本切换点，仅配合嵌套 text 使用
num_denoise_steps	None	去噪步数，推荐 10~50，越大质量越高但更慢
output_joints	False	False 输出 263 维特征；True 输出 (帧数, 22, 3) 关节坐标
smoothing_alpha	1.0	关节 EMA 平滑系数（0.0~1.0），推荐 0.5 获得更顺滑的动画

直接获取关节坐标用于可视化：

joints = model(
    "a person walking forward",
    length=60,
    output_joints=True,
    smoothing_alpha=0.5,
)
print(joints.shape)  # (240, 22, 3)

263 维特征到 22 关节坐标的转换由 ldf_utils/motion_process.py 中的 StreamJointRecovery263 完成，逐帧处理并可叠加 EMA 平滑。

🔬 架构简析

整个推理链路分为三阶段（详见 ldf.yaml 配置）：

1. 文本编码：使用 T5 编码器（google/umt5-base）把描述文字转为语义向量，并带缓存加速重复调用
2. 潜在扩散生成：核心模型 DiffForcingWanModel（ldf_models/diffusion_forcing_wan_tiny.py）在 4 维潜在空间上做 Diffusion Forcing 去噪——Tiny 版本仅 8 层、hidden_dim=256、chunk_size=5，可按块流式生成
3. VAE 解码：1D VAE（ldf_models/vae_wan_1d.py）把 4 维潜在变量解码回 263 维 HumanML3D 运动特征，4 倍上采样

📝 相关论文：FloodDiffusion: Tailored Diffusion Forcing for Streaming Motion Generation（arXiv:2512.03520）。

💡 常见问题

Q：为什么必须安装 flash-attn？ A：主干 Transformer 的注意力计算依赖 Flash Attention 实现，这是硬性要求。

Q：生成动作偏抖动怎么办？ A：使用 output_joints=True 时把 smoothing_alpha 调低（如 0.5），可明显平滑关节轨迹。

Q：length 和秒数怎么换算？ A：输出帧数 ≈ length × 4，按 20 FPS 计：length=60 → 240 帧 ≈ 12 秒。

Q：能输出更长动作吗？ A：增大 length 即可；核心模型本身支持 stream_generate 流式接口（见 generate_ldf.py），适合逐块产出超长序列。

📌 小结

FloodDiffusionTiny 用极小的模型体量实现了"一句话生成 12 秒人体动作"的完整闭环：T5 文本编码 → Diffusion Forcing 潜在去噪 → 1D VAE 解码，再配合关节恢复工具即可直接驱动骨骼动画。无论是做动作数据合成、游戏动画原型，还是研究流式运动生成，它都是一个上手极快的起点。