逐行解读FloodDiffusionTiny的stream_generate:流式生成如何逐chunk实时提交动作

原创2026-10-17 13:13:201,693 阅读

逐行解读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 不需要等待后面任何内容。🌊

核心源码都在这个文件里:

二、决定流式节奏的 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(可选):多段文字各自的结束位置

几行关键逻辑:

  1. L562-L564:若未指定 num_denoise_steps 则用 noise_steps(默认 10),并断言它必须能被 chunk_size 整除——保证"洪水面"移动步长均匀。
  2. L569-L572:把整条序列初始化为纯高斯噪声 torch.randn(B, seq_len + chunk_size, input_dim),多留出的 chunk_size 是尾部冗余,防止越界。
  3. 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):

  1. L653-L656:算出当前时间 t = step * dt,以及过渡带左右边界 start_index(左)和 end_index(右)。
  2. L659-L661:调用 _get_noise_levels 生成三角形噪声水平,核心公式只有一行: noise_level = clip(1 + 位置/chunk_size - t, 0, 1) ——位置在过渡带左边的减成 0(已干净),右边的夹到 1(纯噪声),中间平滑过渡。
  3. L664-L674:只把 generated[:, :, :end_index](截断窗口,只包含已生成部分)送入 WanModel 预测,模型因此天然具备"只看过去"的流式特性。
  4. L677-L688:若 cfg_scale != 1.0,再跑一次空文本分支,按 cfg_scale * 有文本 - (cfg_scale-1) * 空文本 合成。
  5. 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,永久定型了,可以安全输出:

  1. 切片取出 commit_index:start_index 这段,经 postprocess 从 (B,C,T,1,1) 还原为 (B,T,C);
  2. 按每个样本自己的 generated_length 截断多余部分,不足的样本填 None;
  3. 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__ 目前走的就是这条非流式路径,再经 VAE decode 得到最终动作。

五、总结:5 个要点吃透 stream_generate

  1. 三角形噪声调度是 Diffusion Forcing 的核心:clip(1 + 位置/chunk_size - t, 0, 1) 一行公式,左干净、右噪声、中间过渡带。
  2. 每步只更新过渡带内的 chunk_size 个 token,截断窗口输入保证流式(因果)特性。
  3. commit_index 就是"定案线":左边界右移多少,就 yield 多少已定型的动作 chunk。
  4. 默认节奏:约 10 步主循环提交约 5 个 latent token,VAE 解码后约 20 帧动作即可实时使用。
  5. 想无限长流式,用 init_generated + stream_generate_step 状态机接口,配合 VAE stream_decode 组成完整流水线。

掌握这些后,你可以轻松基于 generate_ldf.py 搭建自己的"文字→实时动作"应用,也理解了 FloodDiffusion 论文标题中"Streaming Motion Generation"在代码层面的真实含义。✅

登录后查看全文
FloodDiffusionTiny