Diffusers项目中HunyuanVideoPipeline生成NaN问题的分析与解决

问题背景

在Diffusers项目的实际应用中，用户报告了一个关键问题：当使用HunyuanVideoPipeline生成视频内容时，输出结果中出现了NaN（非数值）值。这个问题在调用diffusers.utils.export_to_video()函数时尤为明显，系统会抛出警告信息"invalid value encountered in cast"，表明在将图像数据转换为uint8类型时遇到了无效值。

问题表现

通过深入分析，我们发现这个问题在多种硬件配置和软件环境下都会出现：

1. 在AMD MI300X GPU上运行时，无论使用PyTorch 2.5.1还是2.6.0版本，都会产生NaN输出
2. 在CUDA环境下，某些PyTorch版本（如2.4.0）也会出现类似问题
3. 问题表现为最终生成的视频内容全黑或包含无效数据

技术分析

经过开发团队的深入调查，发现问题根源在于Transformer模型中的注意力掩码(attention mask)处理机制。原始实现中存在两个关键缺陷：

1. 注意力掩码的维度设计不合理，导致在某些情况下计算异常
2. 掩码生成逻辑不够健壮，容易在特定条件下产生无效值

具体来说，原始代码创建了一个形状为[batch_size, sequence_length, sequence_length]的布尔类型注意力掩码，这种设计不仅计算效率低，而且在某些边缘情况下可能导致数值不稳定。

解决方案

开发团队提出了一个优雅的解决方案，主要修改包括：

1. 简化注意力掩码的维度，从三维[batch_size, N, N]改为二维[batch_size, N]
2. 优化掩码生成逻辑，确保在所有情况下都能产生有效值
3. 增强数值稳定性检查，防止NaN值传播

修改后的注意力掩码处理代码如下：

attention_mask = torch.zeros(
    batch_size, sequence_length, device=hidden_states.device, dtype=torch.bool
)  # 从[B, N, N]改为[B, N]

effective_condition_sequence_length = encoder_attention_mask.sum(dim=1, dtype=torch.int)
effective_sequence_length = latent_sequence_length + effective_condition_sequence_length

for i in range(batch_size):
    attention_mask[i, : effective_sequence_length[i]] = True
attention_mask = attention_mask.unsqueeze(1)  # 最终形状为[B, 1, N]

验证与效果

该解决方案经过严格测试，验证了以下优势：

1. 兼容性：在PyTorch 2.4.1到2.5.1版本上均能正常工作
2. 性能：相比原始实现有约7%的性能提升（从4.16s/it降到3.89s/it）
3. 稳定性：彻底解决了NaN值问题，确保输出质量

最佳实践建议

基于此次问题的解决经验，我们建议用户：

1. 确保使用最新版本的Diffusers库
2. 对于视频生成任务，推荐使用PyTorch 2.5.1或更高版本
3. 在数据处理管道中加入NaN检查机制，如下例：

def numpy_to_pil(images: np.ndarray) -> List[PIL.Image.Image]:
    # 添加NaN检查
    if np.any(np.isnan(images)):
        raise ValueError("图像数据包含NaN值")
    if np.any(np.isinf(images)):
        raise ValueError("图像数据包含无限值")
    # 其余处理逻辑...

总结

此次HunyuanVideoPipeline生成NaN问题的解决，不仅修复了一个关键缺陷，还优化了模型的运行效率。这体现了Diffusers项目团队对代码质量的严格要求和持续改进的精神。对于深度学习开发者而言，这也提醒我们在设计模型时需要考虑数值稳定性问题，特别是在处理注意力机制等复杂结构时。

建议所有使用HunyuanVideoPipeline的用户更新到包含此修复的版本，以获得更稳定、高效的视频生成体验。