逐行解读FloodDiffusionTiny的stream_generate:流式生成如何逐chunk实时提交动作
逐行解读FloodDiffusionTiny的stream_generate:流式生成如何逐chunk实时提交动作
FloodDiffusionTiny 是一款基于 Diffusion Forcing 的文生人体动作生成模型精简版,其核心接口 stream_generate 支持流式动作生成:每生成一小段就立刻输出,无需等整段动作完成。本文逐行解读 stream_generate 源码,讲清楚动作是如何像"洪水"一样从左向右推进去噪、又如何逐 chunk 实时提交的。
一、先理解核心概念:什么是"流式动作生成"
传统扩散模型(Diffusion Model)生成动作的流程是:整段序列从头到尾一起去噪,最后一次性输出。对于 10 秒以上的长动作,你必须等全部算完才能看到第一帧。
FloodDiffusion 的做法完全不同,它采用 Diffusion Forcing 三角形噪声调度:
- 序列左边的 token 已经是干净的(噪声水平为 0)
- 右边的 token 还是纯噪声(噪声水平为 1)
- 中间只有一条约一个 chunk 宽的过渡带,噪声水平从 0 平滑过渡到 1
随着时间步 t 不断前进,这条"过渡带"从左向右移动,就像洪水的水面一样推进——左边被"淹没"过的区域已经去噪完成,可以立即提交输出。这就是"流式"低延迟的来源:第一个 chunk 不需要等待后面任何内容。🌊
核心源码都在这个文件里:
- 主模型与
stream_generate:diffusion_forcing_wan_tiny.py - 模型配置:ldf.yaml
- 推理入口:generate_ldf.py
- HuggingFace 封装:hf_pipeline.py
二、决定流式节奏的 5 个关键参数
读懂 ldf.yaml 里的这些参数,是理解 stream_generate 的前提:
| 参数 | 默认值 | 含义 |
|---|---|---|
chunk_size |
5 | 过渡带宽度(latent token 数),也决定每次提交的 chunk 大小 |
noise_steps |
10 | 默认去噪步数,dt = 1/10,必须是 chunk_size 的整数倍 |
input_dim |
4 | VAE 潜空间维度,stream_generate 全程在这个低维空间里运算 |
cfg_scale |
5.0 | Classifier-Free Guidance 强度 |
prediction_type |
"vel" | 模型预测速度场,用欧拉步 x += v * dt 推进 |
配合 VAE 理解长度:263 维 HumanML3D 特征被压缩成 4 维 latent,解码时又上采样 4 倍帧数(length=60 → 约 240 帧)。所以每次提交约 5 个 latent token,解码后约 20 帧动作——在 20 FPS 下就是约 1 秒的实时动作片段。
三、逐行解读 stream_generate:从纯噪声到逐 chunk 提交
stream_generate 定义在 diffusion_forcing_wan_tiny.py#L539,它是一个 generator(生成器),用 yield 逐段产出结果。下面分四段拆解。
3.1 输入解析与时间轴初始化(L539-L579)
输入是一个字典 x:
feature_length:每个样本要生成的 latent token 数(torch.tensor)text:字符串列表,或嵌套列表(表示多段文字在时间轴上切换)feature_text_end(可选):多段文字各自的结束位置
几行关键逻辑:
- L562-L564:若未指定
num_denoise_steps则用noise_steps(默认 10),并断言它必须能被chunk_size整除——保证"洪水面"移动步长均匀。 - L569-L572:把整条序列初始化为纯高斯噪声
torch.randn(B, seq_len + chunk_size, input_dim),多留出的chunk_size是尾部冗余,防止越界。 - L575-L579:计算总推进幅度
max_t = 1 + (seq_len-1)/chunk_size、步长dt = 1/num_denoise_steps和总步数total_steps。以length=60, chunk_size=5, steps=10为例:max_t = 12.8,dt = 0.1,共 128 步。
3.2 文本条件构建(L582-L645)
这一段把文字变成每个 latent token 对应的条件向量:
- 单段文字(L630-L634):直接走 encode_text_with_cache,相同文字会命中 CPU 缓存,避免重复过 T5 编码器。
- 多段文字切换(L584-L629):把每段文字按
feature_text_end的时长展开,一个 token 一个条件,尾部用最后一段文字填充。这是"走路→转身→跑回"这类动作自然衔接的关键。 - L642-L645:额外编码一条空文本,供后面的 CFG(Classifier-Free Guidance)做无条件分支。
3.3 主循环:推进"洪水面"(L651-L718)
这是整个函数的灵魂,for step in range(total_steps):
- L653-L656:算出当前时间
t = step * dt,以及过渡带左右边界start_index(左)和end_index(右)。 - L659-L661:调用 _get_noise_levels 生成三角形噪声水平,核心公式只有一行:
noise_level = clip(1 + 位置/chunk_size - t, 0, 1)——位置在过渡带左边的减成 0(已干净),右边的夹到 1(纯噪声),中间平滑过渡。 - L664-L674:只把
generated[:, :, :end_index](截断窗口,只包含已生成部分)送入 WanModel 预测,模型因此天然具备"只看过去"的流式特性。 - L677-L688:若
cfg_scale != 1.0,再跑一次空文本分支,按cfg_scale * 有文本 - (cfg_scale-1) * 空文本合成。 - L690-L718:只更新过渡带内的 token。本模型
prediction_type="vel",即generated[start:end] += 预测速度 * dt,一次小小的欧拉步。
注意:每一步只有过渡带那 5 个 token 被更新,其余区域纹丝不动——左边是"已定案"的干净区,右边还是等待淹没的纯噪声。
3.4 逐 chunk 提交:commit_index 机制(L720-L747)
提交判断只有一句:
if commit_index < start_index:
output = generated[:, :, commit_index:start_index]
含义是:过渡带左边界 start_index 每向右挪一步,左边新暴露的那段 token 噪声水平已经降到 0,永久定型了,可以安全输出:
- 切片取出
commit_index:start_index这段,经postprocess从(B,C,T,1,1)还原为(B,T,C); - 按每个样本自己的
generated_length截断多余部分,不足的样本填None; yield {"generated": [...]}把这一 chunk 交给调用方,同时把commit_index推到新位置。
按默认参数估算提交节奏:
| 阶段 | 洪水面位置 t | 新提交 |
|---|---|---|
| 每前进 10 步 | 过渡带右移 1 个 chunk | 约 5 个 latent token(≈20 帧) |
| 循环结束(L737-L747) | 尾部剩余 | 最后一段兜底 yield |
也就是说,每约 10 次主循环迭代,你就能拿到约 1 秒的可解码动作,而不是等 128 步全部走完。⚡
四、stream_generate 外部怎么用
- 调用封装:generate_ldf.py 的
generate_feature_stream负责组装输入字典x,然后for step_output in generator: yield step_output,把生成器原样透传出去,消费方next()一次就拿到一个 chunk。 - VAE 流式解码:latent 不是帧,需再解码。VAEWanModel 专门提供了带缓存的 stream_decode(底层实现在 wan_vae_1d.py),首段传
first_chunk=True,之后每 chunk 增量解码,与"逐 chunk 提交"完美对齐。 - 交互/超长流式变体:init_generated + stream_generate_step 提供了状态机版本——每次调用提交 1 个 token,内部用
2×seq_len的环形缓冲区滚动续接(L922-L942 处丢弃已提交前缀、尾部补新噪声),理论上可以无限流式生成,适合"边推理边执行"的机器人场景。 - 非流式对照:同文件里的 generate 循环逻辑与
stream_generate几乎一致,只是不 yield、最后一次性返回——对比阅读能更清楚"流式"到底改了什么。hf_pipeline.py 的__call__目前走的就是这条非流式路径,再经 VAEdecode得到最终动作。
五、总结:5 个要点吃透 stream_generate
- 三角形噪声调度是 Diffusion Forcing 的核心:
clip(1 + 位置/chunk_size - t, 0, 1)一行公式,左干净、右噪声、中间过渡带。 - 每步只更新过渡带内的
chunk_size个 token,截断窗口输入保证流式(因果)特性。 - commit_index 就是"定案线":左边界右移多少,就
yield多少已定型的动作 chunk。 - 默认节奏:约 10 步主循环提交约 5 个 latent token,VAE 解码后约 20 帧动作即可实时使用。
- 想无限长流式,用
init_generated+stream_generate_step状态机接口,配合 VAEstream_decode组成完整流水线。
掌握这些后,你可以轻松基于 generate_ldf.py 搭建自己的"文字→实时动作"应用,也理解了 FloodDiffusion 论文标题中"Streaming Motion Generation"在代码层面的真实含义。✅