diffusers 中的 LTXVideoTransformer3DModel：LTX 视频扩散 Transformer 架构与加载实战指南

diffusers 中的 LTXVideoTransformer3DModelLTX 视频扩散 Transformer 架构与加载实战指南【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读LTXVideoTransformer3DModel是 Diffusers 为 Lightricks 的 LTX 视频生成模型 提供的 3D 视频扩散 Transformer 主模型DiT它以潜空间视频 token 与文本条件为输入在去噪循环中逐帧预测噪声是 LTX 文生视频/图生视频管线LTXPipeline、LTXImageToVideoPipeline等的核心去噪网络。读完本文你将掌握该模型的加载方式、全部可配置参数及其含义、内部模块结构与前向推理流程并能在 PyTorch 2.0 环境中独立加载、调用和测试该模型。LTX 视频 Transformer 在 diffusers 中的角色LTX-Video 是一套面向视频生成的潜扩散latent diffusion方案其整体结构为文本编码器 VAE 扩散 Transformer 调度器。其中LTXVideoTransformer3DModel承担了扩散模型的去噪主干给定带噪的 3D 视频潜变量、文本嵌入与时间步timestep它输出预测的噪声从而驱动调度器一步步还原出干净视频。在代码层面该模型的完整定义位于 src/diffusers/models/transformers/transformer_ltx.py并通过 src/diffusers/models/transformers/init.py 与 src/diffusers/models/init.py 导出为公共 API。它与 LTX 的 VAEAutoencoderKLLTXVideo、Flow Matching 调度器FlowMatchEulerDiscreteScheduler一同被 LTX 系列管线组装使用见 src/diffusers/pipelines/ltx/pipeline_ltx.py。加载预训练模型官方文档给出的加载方式非常简单——从 Hugging Face Hub 上的Lightricks/LTX-Video仓库中按subfoldertransformer提取 Transformer 权重from diffusers import LTXVideoTransformer3DModel import torch transformer LTXVideoTransformer3DModel.from_pretrained( Lightricks/LTX-Video, subfoldertransformer, dtypetorch.bfloat16, ).to(cuda) # 或 mps、xpu、cpu几点说明subfoldertransformer指向 Hub 仓库中保存该子模型权重与config.json的子目录LTX-Video 仓库同时包含vae、text_encoder、tokenizer等子目录分别对应管线其他组件。dtypetorch.bfloat16是 LTX 官方推荐精度原文档的示例注释中明确支持cuda、mps、xpu、cpu四种后端其中 MPSApple Silicon、XPUIntel 独立显卡上建议搭配对应版本的 PyTorch。从源码结构看该模型同时继承ModelMixin、ConfigMixin、AttentionMixin、FromOriginalModelMixin、PeftAdapterMixin与CacheMixin见 transformer_ltx.py这意味着它不仅支持标准from_pretrained还支持从原始非 diffusers 格式单文件权重加载、LoRA 适配层挂载与注意力缓存机制。此外仓库测试 tests/models/transformers/test_models_transformer_ltx.py 中还提供了单文件single-file加载的验证路径ckpt_path指向ltx-video-2b-v0.9.safetensorspretrained_model_name_or_path为diffusers/LTX-Video-0.9.0表明该模型兼容from_single_file式加载流程。模型配置参数全解LTXVideoTransformer3DModel.__init__见 transformer_ltx.py通过register_to_config将所有构造参数写入config可通过transformer.config查看。各参数含义如下参数默认值说明in_channels128输入带噪视频潜变量的通道数与 LTX VAE 的潜通道数一致out_channels128输出通道数传入None时自动回退为in_channelspatch_size1空间 patch embedding 的 patch 尺寸patch_size_t1时间维 patch embedding 的 patch 尺寸num_attention_heads32多头注意力的头数attention_head_dim64每个注意力头的通道数inner_dim heads × head_dim 2048cross_attention_dim2048交叉注意力文本条件的通道数num_layers28堆叠的 Transformer block 层数activation_fngelu-approximate前馈网络激活函数qk_normrms_norm_across_headsQ/K 归一化方式目前仅支持该取值见 LTXAttentionnorm_elementwise_affineFalse归一化层是否启用逐元素仿射参数norm_eps1e-6归一化层 epsiloncaption_channels4096文本嵌入输入维度适配 T5-XXL 的 4096 维嵌入attention_biasTrue注意力 Q/K/V 线性层是否带 biasattention_out_biasTrue注意力输出线性层是否带 bias这些默认值对应 2B 规模的 LTX-Video 官方权重。测试配置则提供了一个迷你版示例1 层、2 头、caption_channels16可用于快速验证模型逻辑见 test_models_transformer_ltx.py。内部模块结构从源码transformer_ltx.py可以梳理出模型的完整计算图proj_in一个nn.Linear(in_channels, inner_dim)把输入 token 投影到模型宽度inner_dim 2048。time_embedAdaLayerNormSingle把时间步编码为适配层adaLN所需的嵌入temb与embedded_timestepuse_additional_conditionsFalse表示不附带额外条件。caption_projectionPixArtAlphaTextProjection把 4096 维的文本嵌入投影到inner_dim作为交叉注意力条件。ropeLTXVideoRotaryPosEmbed基于视频帧数、高度、宽度生成 3D 旋转位置编码详见下一节。transformer_blocksnum_layers个LTXVideoTransformerBlock堆叠每个 block 内部包含norm1attn1自注意力RMSNorm Q/K 归一化 RoPE并使用 adaLN 的scale_shift_table生成 shift/scale/gate 调制norm2attn2交叉注意力条件来自encoder_hidden_states并支持encoder_attention_maskffGELU 近似的 FeedForward 层同样受 gate 调制。norm_outproj_out输出 LayerNorm 与线性投影恢复为out_channels维即预测噪声。值得注意的机制细节AdaIN 调制每个 Transformer block 有一个scale_shift_table nn.Parameter(torch.randn(6, dim) / dim**0.5)与temb相加后解绑为 6 组(shift, scale, gate)分别调制自注意力、前馈网络与残差门控transformer_ltx.py。输出端同样有一组 2 行的scale_shift_table对最终输出做调制。Q/K 归一化 RoPELTXVideoAttnProcessor在计算注意力前对 query 与 key 做 RMSNorm然后施加旋转位置嵌入再通过dispatch_attention_fn分发到 SDPA 等后端transformer_ltx.py。上下文并行Context Parallel支持_cp_plan定义了hidden_states、encoder_hidden_states、RoPE 与proj_out的切分/聚合策略说明该模型面向长视频序列时可配合上下文并行技术降低单卡显存压力transformer_ltx.py。训练与量化友好声明了_supports_gradient_checkpointing True、_repeated_blocks [LTXVideoTransformerBlock]测试覆盖了梯度检查点、训练、torch.compile与 LoRA 等场景test_models_transformer_ltx.py。3D 旋转位置编码RoPE原理视频 token 序列带有时间与空间双重结构LTXVideoRotaryPosEmbedtransformer_ltx.py负责为其生成 3D 旋转位置编码以base_num_frames20、base_height2048、base_width2048为基准分辨率时间、高度、宽度三个维度的坐标分别按rope_interpolation_scale元组(t, h, w)插值缩放。当分辨率与训练基准不一致时通过该插值尺度实现长度外推。频率采用从 1 到theta10000的对数均匀分布dim // 6个频段乘以π/2后与归一化坐标映射到[-1, 1]相乘最终生成cos_freqs与sin_freqs若维度不能被 6 整除自动补齐 paddingcos 填 1、sin 填 0。计算始终在 fp32 下进行以保证数值稳定性。在前向过程中forward把 RoPE 结果传入每个 Transformer block 的自注意力如果外部传入video_coords预计算坐标则直接复用避免重复计算。前向传播输入、输出与调用方式模型的forward方法签名transformer_ltx.py如下参数形状/类型说明hidden_states(batch, seq_len, in_channels)带噪视频潜 token3D 展平后encoder_hidden_states(batch, seq_len, embed_dims)文本条件嵌入timesteptorch.LongTensor去噪时间步encoder_attention_mask(batch, seq_len)文本注意力的掩码2D 时内部转为 -10000 偏置num_frames/height/widthint计算 RoPE 所需的视频/潜空间尺寸rope_interpolation_scaletuple或TensorRoPE 插值尺度可选video_coordsTensor预计算视频坐标可选attention_kwargsdict透传给注意力处理器的额外参数如 LoRA 缩放return_dictbool为True时返回Transformer2DModelOutput否则返回裸元组输出为形状(batch, seq_len, out_channels)的预测噪声张量Transformer2DModelOutput定义于 src/diffusers/models/modeling_outputs.py仅包含sample一个字段。前向内部依次执行生成 RoPE → 掩码转偏置 →proj_in→ 时间步嵌入 → 文本投影 → 逐 block 前向支持梯度检查点→ 输出调制与投影。注意forward被apply_lora_scale(attention_kwargs)装饰LoRA 缩放会经由attention_kwargs注入注意力处理器。直接调用的最小示例参照测试用例的构造方式test_models_transformer_ltx.py可以像下面这样独立调用模型以小配置为例import torch from diffusers import LTXVideoTransformer3DModel from diffusers.utils.torch_utils import randn_tensor model LTXVideoTransformer3DModel( in_channels4, out_channels4, num_attention_heads2, attention_head_dim8, cross_attention_dim16, num_layers1, caption_channels16, ) model.eval() batch_size, num_frames, height, width 1, 2, 16, 16 seq_len num_frames * height * width # 512 hidden_states randn_tensor((batch_size, seq_len, 4)) encoder_hidden_states randn_tensor((batch_size, 16, 16)) timestep torch.randint(0, 1000, size(batch_size,)) encoder_attention_mask torch.ones((batch_size, 16)).bool() with torch.no_grad(): output model( hidden_stateshidden_states, encoder_hidden_statesencoder_hidden_states, timesteptimestep, encoder_attention_maskencoder_attention_mask, num_framesnum_frames, heightheight, widthwidth, ) print(output.sample.shape) # (1, 512, 4)这里hidden_states的形状为(batch, num_frames * height * width, in_channels)即把视频潜空间按帧 × 高 × 宽展平为 token 序列——这正是 3D Transformer 处理视频的方式。在 LTX 管线中的完整调用链实际使用中绝大多数用户不会直接调用 Transformer而是通过管线整体运行。以LTXPipelinesrc/diffusers/pipelines/ltx/pipeline_ltx.py为例去噪循环中 Transformer 的调用位置在 pipeline_ltx.pywith self.transformer.cache_context(cond_uncond): noise_pred self.transformer( hidden_stateslatent_model_input, encoder_hidden_statesprompt_embeds, timesteptimestep, encoder_attention_maskprompt_attention_mask, num_frameslatent_num_frames, heightlatent_height, widthlatent_width, rope_interpolation_scalerope_interpolation_scale, attention_kwargsattention_kwargs, return_dictFalse, )[0]调用链要点潜空间尺寸换算管线先用 VAE 的时间压缩比vae_temporal_compression_ratio与空间压缩比vae_spatial_compression_ratio把像素级帧数/分辨率换算成潜空间尺寸latent_num_frames、latent_height、latent_width再传入 Transformer。RoPE 插值尺度rope_interpolation_scale (vae_temporal_compression_ratio / frame_rate, vae_spatial_compression_ratio, vae_spatial_compression_ratio)pipeline_ltx.py把时间维度按帧率归一、空间维度按压缩比归一从而支持任意分辨率与帧数的生成。CFG 处理启用无分类器引导时latent_model_input会把条件/无条件潜变量沿 batch 维拼接Transformer 一次前向输出两份预测再在管线层按guidance_scale插值pipeline_ltx.py。缓存上下文cache_context(cond_uncond)是CacheMixin提供的缓存机制用于跨步复用部分中间计算。端到端使用只需加载整个管线LTXPipeline.from_pretrained(Lightricks/LTX-Video, torch_dtypetorch.bfloat16)传入width、height、num_frames、num_inference_steps即可出视频完整示例见 pipeline_ltx.py。除文生视频外仓库中pipelines/ltx/目录下还有图生视频LTXImageToVideoPipeline、条件控制LTXConditionPipeline、多提示长视频LTXImageToVideoLongMultiPromptPipeline与潜空间上采样等变体它们都复用同一个LTXVideoTransformer3DModel作为去噪主干。测试覆盖与验证仓库为LTXVideoTransformer3DModel提供了体系化的测试见 tests/models/transformers/test_models_transformer_ltx.py核心模型测试ModelTesterMixin验证输入/输出形状、序列长度、RoPE 计算与前向/反向正确性显存测试MemoryTesterMixin与训练测试TrainingTesterMixin含梯度检查点生效断言编译测试TorchCompileTesterMixin覆盖torch.compile加速路径LoRA 测试LoraTesterMixin验证PeftAdapterMixin挂载的 LoRA 层可正确参与前向单文件加载测试SingleFileTesterMixin验证从原始ltx-video-2b-v0.9.safetensors加载。此外管线级测试位于 tests/pipelines/ltx/如test_ltx.py、test_ltx_image2video.py把 Transformer 与 VAE、调度器串联做端到端验证。这些测试既是回归保障也为二次开发如自定义注意力处理器、接入量化/编译提供了现成的验证脚手架。小结与最佳实践加载LTXVideoTransformer3DModel.from_pretrained(Lightricks/LTX-Video, subfoldertransformer, dtypetorch.bfloat16)按需选择cuda/mps/xpu/cpuLoRA 与单文件权重可通过PeftAdapterMixin、FromOriginalModelMixin挂载。精度优先使用bfloat16以平衡显存与质量RoPE 内部固定 fp32 计算保证稳定。分辨率与帧数得益于 3D RoPE 插值rope_interpolation_scale模型支持在训练基准20 帧、2048×2048 基准之外的任意尺寸推理管线会自动换算潜空间尺寸。性能优化可启用梯度检查点训练、torch.compile推理/训练加速、上下文并行超长序列并利用CacheMixin的缓存机制减少冗余计算。深入学习继续阅读 transformer_ltx.py 理解 block 内部 adaLN 门控细节配合 pipeline_ltx.py 掌握完整去噪调用链并以 test_models_transformer_ltx.py 为模板验证自己的改动。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考