Diffusers CogVideoXTransformer3DModel 深度解析面向视频生成的 3D 专家扩散 Transformer【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文围绕 Diffusers 仓库中 CogVideoX 视频生成模型的核心骨干网络——CogVideoXTransformer3DModel展开完整讲解其架构设计、全部可配置参数、forward 输入输出约定以及加载使用方法并结合仓库源码cogvideox_transformer_3d.py与测试用例进行原理级佐证。读完本文你将掌握如何独立加载、配置与调用该 3D DiTDiffusion Transformer模型理解 Expert Transformer 文本-视频对齐与 3D 全注意力机制并能在文本生成视频、图生视频等管线中正确集成它。CogVideoXTransformer3DModel 是什么CogVideoXTransformer3DModel是专为三维空间 × 时间视频隐变量设计的扩散 Transformer 模型源自清华大学与智谱 AI 提出的 CogVideoX 系列论文《CogVideoX: Text-to-Video Diffusion Models with An Expert Transformer》。在 CogVideoX 的整体架构中视频先经 3D 因果 VAE 压缩为时空潜变量再由该 Transformer 在潜空间执行去噪过程采用3D full attention三维全注意力精确捕捉视频中的运动与时间依赖采用带自适应 LayerNormAdaLayerNorm的 Expert Transformer增强文本与视频的对齐与 3D VAE 结合压缩序列长度、降低训练计算量同时抑制生成视频的闪烁伪影。CogVideoX 提供 2B 与 5B 两种参数量版本详见 CogVideoX 管线文档本文讲解的 Transformer 模型正是这两套权重中负责去噪的核心子模块。快速开始加载模型官方文档给出的最小加载示例来自 cogvideox_transformer3d.md如下import torch from diffusers import CogVideoXTransformer3DModel transformer CogVideoXTransformer3DModel.from_pretrained( THUDM/CogVideoX-2b, subfoldertransformer, dtypetorch.float16, ).to(cuda) # 或 mps、xpu、cpu几点实战说明subfoldertransformer是必需的CogVideoX 检查点目录下同时存放 VAE、文本编码器等组件Transformer 权重单独存放在transformer子目录中dtype推荐使用torch.float162B 模型或torch.bfloat165B 模型可显著降低显存占用.to(cuda)支持多种后端也支持mps、xpu与cpuCPU 推理速度较慢仅作调试用途。若需要按 5B 版本加载只需将仓库 ID 替换为THUDM/CogVideoX-5b其余用法一致。注意from_pretrained返回的是单模型对象可直接独立做前向推理测试也可以作为CogVideoXPipeline的transformer参数注入完整管线。模型架构总览源码级拆解从 cogvideox_transformer_3d.py 的__init__可以看出该模型由四个阶段串接而成Patch Embedding时空分块嵌入self.patch_embed CogVideoXPatchEmbed(...)将视频潜变量与文本嵌入统一投影到 Transformer 的隐空间并叠加 3D 正弦-余弦位置编码时间步嵌入self.time_proj Timesteps(...)与self.time_embedding TimestepEmbedding(...)生成条件化时间步嵌入若配置了ofs_embed_dim还会额外叠加 ofsoffset嵌入仅 CogVideoX1.5-5B I2V 使用时空 Transformer 堆栈self.transformer_blocks nn.ModuleList([CogVideoXBlock(...) for _ in range(num_layers)])默认 30 层专家 Transformer 块输出头norm_finalLayerNorm→norm_outAdaLayerNorm输出2 * inner_dim用于门控调制→proj_out线性层输出 unpatchify 所需的 patch 通道数。代码中inner_dim num_attention_heads * attention_head_dim默认 30 × 64 1920 维。模型的_no_split_modules [CogVideoXBlock, CogVideoXPatchEmbed]这组声明会被分布式/量化工具用于确定切分边界。Patch Embedding 的实现细节CogVideoXPatchEmbed源码位于 embeddings.py 的CogVideoXPatchEmbed类区分两代实现CogVideoX 1.0patch_size_tNone使用nn.Conv2d(in_channels, embed_dim, kernel_sizepatch_size, stridepatch_size)做纯空间分块逐帧处理CogVideoX 1.5使用nn.Linear(in_channels * patch_size * patch_size * patch_size_t, embed_dim)做时空联合分块。文本嵌入则统一经过self.text_proj nn.Linear(text_embed_dim, embed_dim)投影到同一维度随后torch.cat([text_embeds, image_embeds], dim1)拼接成一个联合序列送入注意力层。位置编码由get_3d_sincos_pos_embed生成覆盖空间宽、高与时间三个维度且支持spatial_interpolation_scale/temporal_interpolation_scale插值缩放。CogVideoXBlockExpert Transformer 内部结构CogVideoXBlock同一源码文件中的顶层类是堆叠的核心单元每个块包含norm1 CogVideoXLayerNormZero(time_embed_dim, dim, ...)以时间步嵌入为条件的自适应归一化层同时输出调制后的 hidden states、encoder hidden states 以及两组门控标量gate_msa、enc_gate_msaattn1 Attention(...)默认使用CogVideoXAttnProcessor2_0()注意力处理器支持qk_normlayer_normQK 归一化与image_rotary_emb旋转位置编码注入norm2ff FeedForward(...)同样以时间嵌入为条件激活函数默认为gelu-approximate并将文本序列与视频序列拼接后统一过 FFN再按拼接位置切分回两条流。从CogVideoXBlock.forward源码可见其残差-门控更新方式hidden_states hidden_states gate_msa * attn_hidden_states encoder_hidden_states encoder_hidden_states enc_gate_msa * attn_encoder_hidden_states即每个块维护两条并行流视频 token 流与文本 token 流。注意力同时更新两者实现文本-视频交叉注意力与视频自注意力的融合FFN 阶段将两条流拼接后统一计算再按text_seq_length切回最终通过学习到的门控标量控制残差贡献——这正是 Expert Transformer 提升文本-视频对齐的核心机制。配置参数详解CogVideoXTransformer3DModel的全部关键参数如下默认值与说明均来自源码 docstring 与__init__签名参数默认值说明num_attention_heads30多头注意力头数attention_head_dim64每个注意力头的通道数inner_dim 30 × 64 1920in_channels16输入视频潜变量的通道数对应 3D VAE 的压缩输出out_channels16输出通道数决定proj_out的维度time_embed_dim512时间步嵌入的输出维度ofs_embed_dimNoneofs 偏移嵌入维度仅 CogVideoX1.5-5B I2V 使用text_embed_dim4096文本编码器嵌入的输入维度num_layers30Transformer 块层数dropout0.0嵌入层 dropout 概率attention_biasTrue注意力投影层是否使用 biassample_width90输入潜变量宽度训练分辨率对应的潜空间尺寸sample_height60输入潜变量高度sample_frames49输入潜变量帧数见下方兼容性陷阱说明patch_size2空间分块尺寸patch_size_tNone时间分块尺寸None对应 1.0 权重非None对应 1.5 权重temporal_compression_ratio4时间维度压缩比max_text_seq_length226文本嵌入最大序列长度activation_fngelu-approximateFFN 激活函数timestep_activation_fnsilu时间步嵌入激活函数norm_elementwise_affineTrue归一化层是否使用可学习的逐元素仿射参数norm_eps1e-5归一化层 epsilonspatial_interpolation_scale1.8753D 位置编码空间维缩放因子temporal_interpolation_scale1.03D 位置编码时间维缩放因子use_rotary_positional_embeddingsFalse是否使用旋转位置编码1.5 权重为Trueuse_learned_positional_embeddingsFalse是否使用可学习位置编码patch_biasTruePatch 投影层是否使用 bias其中存在一处显式约束源码在__init__中检查if not use_rotary_positional_embeddings and use_learned_positional_embeddings会直接抛出ValueError原因是没有可用的同时关闭旋转编码又使用可学习位置编码的 CogVideoX 检查点。此外测试配置test_models_transformer_cogvideox.py特别注明num_attention_heads × attention_head_dim的乘积必须能被 16 整除这是 3D 位置嵌入的正确工作前提。sample_frames 的历史兼容性陷阱sample_frames默认值为 49 而非理论值 13这是官方源码中明确记载的向后兼容问题CogVideoX 默认配置下实际一次性处理 13 帧潜变量但由于历史原因该字段被初始化为 49为保证既有权重加载兼容无法更正。源码 docstring 给出的换算公式为正确值 (K - 1) × temporal_compression_ratio 1其中 K 为期望的潜变量帧数。例如 K13、压缩比 4 时得到 13 × 4 - 4 1 49即默认值来源。自定义帧数时务必按此公式计算。forward 输入输出约定forward方法签名源码CogVideoXTransformer3DModel.forward与各张量形状如下参数形状说明hidden_states(batch_size, num_frames, channels, height, width)视频潜变量5 维张量encoder_hidden_states(batch_size, seq_len, embed_dim)文本条件嵌入如来自 T5 编码器timestepint / float / LongTensor去噪步数指示timestep_cond可选额外的条件时间步嵌入会与时间步嵌入求和ofs可选偏移嵌入仅 CogVideoX1.5-5B I2V 使用image_rotary_emb可选(cos, sin)元组预计算的旋转位置编码attention_kwargs可选 dict透传给AttentionProcessor的参数如 LoRA scalereturn_dictTrue为True返回Transformer2DModelOutput否则返回裸元组输出为Transformer2DModelOutput(sample...)定义于 modeling_outputs.py其中sample形状恢复为与输入一致的(batch_size, num_frames, channels, height, width)。前向流程的五个步骤时间步嵌入 → patch 嵌入 → Transformer 堆栈 → 输出头 → unpatchify均有清晰注释在torch.is_grad_enabled()且self.gradient_checkpointing开启时Transformer 块会走_gradient_checkpointing_func以节省显存。从 pipeline_cogvideox.py 的调用方式可以看到管线在每步去噪中把带噪潜变量作为hidden_states、文本嵌入作为encoder_hidden_states传入并取回噪声预测这正是该 Transformer 与 VAE、调度器协作的完整闭环。注意力机制与推理优化3D 全注意力与旋转位置编码CogVideoX 的核心卖点是 3D 全注意力CogVideoXAttnProcessor2_0在Attention层内对时空 patch 序列执行完整注意力配合image_rotary_emb可注入旋转位置编码1.5 版本默认开启。测试文件中CogVideoX15TransformerTesterConfig将use_rotary_positional_embeddings设为True、patch_size_t设为2与 1.5 权重的实际配置保持一致。融合 QKV 投影模型提供fuse_qkv_projections()/unfuse_qkv_projections()两个 API源码中标注为实验性前者将自注意力模块的 Q/K/V 三个投影矩阵融合为一次矩阵乘交叉注意力仅融合 K/V并用FusedCogVideoXAttnProcessor2_0替换默认处理器可提升推理吞吐后者调用set_attn_processor(self.original_attn_processors)还原。使用前提是模型不含 Added KV 投影否则会抛出ValueError。与 LoRA 的结合模型继承PeftAdapterMixin并支持 LoRA 适配forward上的apply_lora_scale(attention_kwargs)装饰器将attention_kwargs中的缩放系数应用到 LoRA 权重上。管线级用法见 CogVideoX 管线文档加载CogVideoXPipeline后调用load_lora_weights(...)与set_adapters(...)即可注入社区 LoRA。训练侧可参考 examples/cogvideo 训练脚本LoRA 注入目标正是本模型。内存优化提示CogVideoX 管线文档给出了实测内存参考enable_model_cpu_offload约 19GB关闭约 33GB、enable_sequential_cpu_offload低于 4GB但推理极慢、enable_tiling在配合模型 offload 时约 11GB。Transformer 独立使用时同样受益于这些手段因为它是管线中参数量最大的模块。测试验证模型行为的有据可查仓库为 本模型 提供了完整的测试套件可当作理解模型行为的权威参照CogVideoXTransformerTesterConfig1.0 版本测试配置patch_size_tNoneinput_shape(1, 4, 8, 8)覆盖TestCogVideoXTransformer前向、MemoryTesterMixin内存、AttentionTesterMixin注意力、TrainingTesterMixin训练含梯度检查点验证CogVideoX15TransformerTesterConfig1.5 版本配置patch_size_t2开启旋转位置编码num_frames2对应四组同名测试类TestCogVideoXTransformerLoRA通过LoraTesterMixin验证 LoRA 适配能力。若需在本地验证模型行为可运行python -m pytest tests/models/transformers/test_models_transformer_cogvideox.py测试中的 dummy 输入直接给出了forward的最小可用示例hidden_states(batch, frames, channels, h, w)、encoder_hidden_states(batch, seq_len, embed_dim)与随机timestep可用于脱离管线单独调试 Transformer。在完整管线中使用若希望端到端生成视频应使用CogVideoXPipelineT2V或CogVideoXImageToVideoPipelineI2V本 Transformer 作为transformer组件注入import torch from diffusers import CogVideoXPipeline from diffusers.utils import export_to_video pipe CogVideoXPipeline.from_pretrained( THUDM/CogVideoX-2b, dtypetorch.float16, ).to(cuda) video pipe( prompt一只木质玩具船在蓝色地毯上滑行模拟海浪起伏, guidance_scale6, num_inference_steps50, ).frames[0] export_to_video(video, output.mp4, fps8)官方提示见 CogVideoX 管线文档T2V 检查点在 1360×768 分辨率下效果最佳I2V 检查点支持宽 768–1360、高 758宽高需能被 16 整除T2V 与 I2V 均推荐 81 或 161 帧并以 16fps 导出。这些分辨率与帧数最终都会反映为 Transformer 的sample_height/sample_width/sample_frames等配置理解本文的参数体系即可准确预判模型的输入约束。参考链接模型 API 文档cogvideox_transformer3d.md源码实现cogvideox_transformer_3d.pyPatch 嵌入实现embeddings.pyCogVideoXPatchEmbed类输出结构定义modeling_outputs.pyTransformer2DModelOutput测试套件test_models_transformer_cogvideox.py管线用法CogVideoX 管线文档训练指南docs/source/en/training/cogvideox.md训练脚本示例train_cogvideox_lora.py 与 train_cogvideox_image_to_video_lora.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），仅供参考 Diffusers CogVideoXTransformer3DModel 深度解析：面向视频生成的 3D 专家扩散 Transformer
Diffusers CogVideoXTransformer3DModel 深度解析面向视频生成的 3D 专家扩散 Transformer【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文围绕 Diffusers 仓库中 CogVideoX 视频生成模型的核心骨干网络——CogVideoXTransformer3DModel展开完整讲解其架构设计、全部可配置参数、forward 输入输出约定以及加载使用方法并结合仓库源码cogvideox_transformer_3d.py与测试用例进行原理级佐证。读完本文你将掌握如何独立加载、配置与调用该 3D DiTDiffusion Transformer模型理解 Expert Transformer 文本-视频对齐与 3D 全注意力机制并能在文本生成视频、图生视频等管线中正确集成它。CogVideoXTransformer3DModel 是什么CogVideoXTransformer3DModel是专为三维空间 × 时间视频隐变量设计的扩散 Transformer 模型源自清华大学与智谱 AI 提出的 CogVideoX 系列论文《CogVideoX: Text-to-Video Diffusion Models with An Expert Transformer》。在 CogVideoX 的整体架构中视频先经 3D 因果 VAE 压缩为时空潜变量再由该 Transformer 在潜空间执行去噪过程采用3D full attention三维全注意力精确捕捉视频中的运动与时间依赖采用带自适应 LayerNormAdaLayerNorm的 Expert Transformer增强文本与视频的对齐与 3D VAE 结合压缩序列长度、降低训练计算量同时抑制生成视频的闪烁伪影。CogVideoX 提供 2B 与 5B 两种参数量版本详见 CogVideoX 管线文档本文讲解的 Transformer 模型正是这两套权重中负责去噪的核心子模块。快速开始加载模型官方文档给出的最小加载示例来自 cogvideox_transformer3d.md如下import torch from diffusers import CogVideoXTransformer3DModel transformer CogVideoXTransformer3DModel.from_pretrained( THUDM/CogVideoX-2b, subfoldertransformer, dtypetorch.float16, ).to(cuda) # 或 mps、xpu、cpu几点实战说明subfoldertransformer是必需的CogVideoX 检查点目录下同时存放 VAE、文本编码器等组件Transformer 权重单独存放在transformer子目录中dtype推荐使用torch.float162B 模型或torch.bfloat165B 模型可显著降低显存占用.to(cuda)支持多种后端也支持mps、xpu与cpuCPU 推理速度较慢仅作调试用途。若需要按 5B 版本加载只需将仓库 ID 替换为THUDM/CogVideoX-5b其余用法一致。注意from_pretrained返回的是单模型对象可直接独立做前向推理测试也可以作为CogVideoXPipeline的transformer参数注入完整管线。模型架构总览源码级拆解从 cogvideox_transformer_3d.py 的__init__可以看出该模型由四个阶段串接而成Patch Embedding时空分块嵌入self.patch_embed CogVideoXPatchEmbed(...)将视频潜变量与文本嵌入统一投影到 Transformer 的隐空间并叠加 3D 正弦-余弦位置编码时间步嵌入self.time_proj Timesteps(...)与self.time_embedding TimestepEmbedding(...)生成条件化时间步嵌入若配置了ofs_embed_dim还会额外叠加 ofsoffset嵌入仅 CogVideoX1.5-5B I2V 使用时空 Transformer 堆栈self.transformer_blocks nn.ModuleList([CogVideoXBlock(...) for _ in range(num_layers)])默认 30 层专家 Transformer 块输出头norm_finalLayerNorm→norm_outAdaLayerNorm输出2 * inner_dim用于门控调制→proj_out线性层输出 unpatchify 所需的 patch 通道数。代码中inner_dim num_attention_heads * attention_head_dim默认 30 × 64 1920 维。模型的_no_split_modules [CogVideoXBlock, CogVideoXPatchEmbed]这组声明会被分布式/量化工具用于确定切分边界。Patch Embedding 的实现细节CogVideoXPatchEmbed源码位于 embeddings.py 的CogVideoXPatchEmbed类区分两代实现CogVideoX 1.0patch_size_tNone使用nn.Conv2d(in_channels, embed_dim, kernel_sizepatch_size, stridepatch_size)做纯空间分块逐帧处理CogVideoX 1.5使用nn.Linear(in_channels * patch_size * patch_size * patch_size_t, embed_dim)做时空联合分块。文本嵌入则统一经过self.text_proj nn.Linear(text_embed_dim, embed_dim)投影到同一维度随后torch.cat([text_embeds, image_embeds], dim1)拼接成一个联合序列送入注意力层。位置编码由get_3d_sincos_pos_embed生成覆盖空间宽、高与时间三个维度且支持spatial_interpolation_scale/temporal_interpolation_scale插值缩放。CogVideoXBlockExpert Transformer 内部结构CogVideoXBlock同一源码文件中的顶层类是堆叠的核心单元每个块包含norm1 CogVideoXLayerNormZero(time_embed_dim, dim, ...)以时间步嵌入为条件的自适应归一化层同时输出调制后的 hidden states、encoder hidden states 以及两组门控标量gate_msa、enc_gate_msaattn1 Attention(...)默认使用CogVideoXAttnProcessor2_0()注意力处理器支持qk_normlayer_normQK 归一化与image_rotary_emb旋转位置编码注入norm2ff FeedForward(...)同样以时间嵌入为条件激活函数默认为gelu-approximate并将文本序列与视频序列拼接后统一过 FFN再按拼接位置切分回两条流。从CogVideoXBlock.forward源码可见其残差-门控更新方式hidden_states hidden_states gate_msa * attn_hidden_states encoder_hidden_states encoder_hidden_states enc_gate_msa * attn_encoder_hidden_states即每个块维护两条并行流视频 token 流与文本 token 流。注意力同时更新两者实现文本-视频交叉注意力与视频自注意力的融合FFN 阶段将两条流拼接后统一计算再按text_seq_length切回最终通过学习到的门控标量控制残差贡献——这正是 Expert Transformer 提升文本-视频对齐的核心机制。配置参数详解CogVideoXTransformer3DModel的全部关键参数如下默认值与说明均来自源码 docstring 与__init__签名参数默认值说明num_attention_heads30多头注意力头数attention_head_dim64每个注意力头的通道数inner_dim 30 × 64 1920in_channels16输入视频潜变量的通道数对应 3D VAE 的压缩输出out_channels16输出通道数决定proj_out的维度time_embed_dim512时间步嵌入的输出维度ofs_embed_dimNoneofs 偏移嵌入维度仅 CogVideoX1.5-5B I2V 使用text_embed_dim4096文本编码器嵌入的输入维度num_layers30Transformer 块层数dropout0.0嵌入层 dropout 概率attention_biasTrue注意力投影层是否使用 biassample_width90输入潜变量宽度训练分辨率对应的潜空间尺寸sample_height60输入潜变量高度sample_frames49输入潜变量帧数见下方兼容性陷阱说明patch_size2空间分块尺寸patch_size_tNone时间分块尺寸None对应 1.0 权重非None对应 1.5 权重temporal_compression_ratio4时间维度压缩比max_text_seq_length226文本嵌入最大序列长度activation_fngelu-approximateFFN 激活函数timestep_activation_fnsilu时间步嵌入激活函数norm_elementwise_affineTrue归一化层是否使用可学习的逐元素仿射参数norm_eps1e-5归一化层 epsilonspatial_interpolation_scale1.8753D 位置编码空间维缩放因子temporal_interpolation_scale1.03D 位置编码时间维缩放因子use_rotary_positional_embeddingsFalse是否使用旋转位置编码1.5 权重为Trueuse_learned_positional_embeddingsFalse是否使用可学习位置编码patch_biasTruePatch 投影层是否使用 bias其中存在一处显式约束源码在__init__中检查if not use_rotary_positional_embeddings and use_learned_positional_embeddings会直接抛出ValueError原因是没有可用的同时关闭旋转编码又使用可学习位置编码的 CogVideoX 检查点。此外测试配置test_models_transformer_cogvideox.py特别注明num_attention_heads × attention_head_dim的乘积必须能被 16 整除这是 3D 位置嵌入的正确工作前提。sample_frames 的历史兼容性陷阱sample_frames默认值为 49 而非理论值 13这是官方源码中明确记载的向后兼容问题CogVideoX 默认配置下实际一次性处理 13 帧潜变量但由于历史原因该字段被初始化为 49为保证既有权重加载兼容无法更正。源码 docstring 给出的换算公式为正确值 (K - 1) × temporal_compression_ratio 1其中 K 为期望的潜变量帧数。例如 K13、压缩比 4 时得到 13 × 4 - 4 1 49即默认值来源。自定义帧数时务必按此公式计算。forward 输入输出约定forward方法签名源码CogVideoXTransformer3DModel.forward与各张量形状如下参数形状说明hidden_states(batch_size, num_frames, channels, height, width)视频潜变量5 维张量encoder_hidden_states(batch_size, seq_len, embed_dim)文本条件嵌入如来自 T5 编码器timestepint / float / LongTensor去噪步数指示timestep_cond可选额外的条件时间步嵌入会与时间步嵌入求和ofs可选偏移嵌入仅 CogVideoX1.5-5B I2V 使用image_rotary_emb可选(cos, sin)元组预计算的旋转位置编码attention_kwargs可选 dict透传给AttentionProcessor的参数如 LoRA scalereturn_dictTrue为True返回Transformer2DModelOutput否则返回裸元组输出为Transformer2DModelOutput(sample...)定义于 modeling_outputs.py其中sample形状恢复为与输入一致的(batch_size, num_frames, channels, height, width)。前向流程的五个步骤时间步嵌入 → patch 嵌入 → Transformer 堆栈 → 输出头 → unpatchify均有清晰注释在torch.is_grad_enabled()且self.gradient_checkpointing开启时Transformer 块会走_gradient_checkpointing_func以节省显存。从 pipeline_cogvideox.py 的调用方式可以看到管线在每步去噪中把带噪潜变量作为hidden_states、文本嵌入作为encoder_hidden_states传入并取回噪声预测这正是该 Transformer 与 VAE、调度器协作的完整闭环。注意力机制与推理优化3D 全注意力与旋转位置编码CogVideoX 的核心卖点是 3D 全注意力CogVideoXAttnProcessor2_0在Attention层内对时空 patch 序列执行完整注意力配合image_rotary_emb可注入旋转位置编码1.5 版本默认开启。测试文件中CogVideoX15TransformerTesterConfig将use_rotary_positional_embeddings设为True、patch_size_t设为2与 1.5 权重的实际配置保持一致。融合 QKV 投影模型提供fuse_qkv_projections()/unfuse_qkv_projections()两个 API源码中标注为实验性前者将自注意力模块的 Q/K/V 三个投影矩阵融合为一次矩阵乘交叉注意力仅融合 K/V并用FusedCogVideoXAttnProcessor2_0替换默认处理器可提升推理吞吐后者调用set_attn_processor(self.original_attn_processors)还原。使用前提是模型不含 Added KV 投影否则会抛出ValueError。与 LoRA 的结合模型继承PeftAdapterMixin并支持 LoRA 适配forward上的apply_lora_scale(attention_kwargs)装饰器将attention_kwargs中的缩放系数应用到 LoRA 权重上。管线级用法见 CogVideoX 管线文档加载CogVideoXPipeline后调用load_lora_weights(...)与set_adapters(...)即可注入社区 LoRA。训练侧可参考 examples/cogvideo 训练脚本LoRA 注入目标正是本模型。内存优化提示CogVideoX 管线文档给出了实测内存参考enable_model_cpu_offload约 19GB关闭约 33GB、enable_sequential_cpu_offload低于 4GB但推理极慢、enable_tiling在配合模型 offload 时约 11GB。Transformer 独立使用时同样受益于这些手段因为它是管线中参数量最大的模块。测试验证模型行为的有据可查仓库为 本模型 提供了完整的测试套件可当作理解模型行为的权威参照CogVideoXTransformerTesterConfig1.0 版本测试配置patch_size_tNoneinput_shape(1, 4, 8, 8)覆盖TestCogVideoXTransformer前向、MemoryTesterMixin内存、AttentionTesterMixin注意力、TrainingTesterMixin训练含梯度检查点验证CogVideoX15TransformerTesterConfig1.5 版本配置patch_size_t2开启旋转位置编码num_frames2对应四组同名测试类TestCogVideoXTransformerLoRA通过LoraTesterMixin验证 LoRA 适配能力。若需在本地验证模型行为可运行python -m pytest tests/models/transformers/test_models_transformer_cogvideox.py测试中的 dummy 输入直接给出了forward的最小可用示例hidden_states(batch, frames, channels, h, w)、encoder_hidden_states(batch, seq_len, embed_dim)与随机timestep可用于脱离管线单独调试 Transformer。在完整管线中使用若希望端到端生成视频应使用CogVideoXPipelineT2V或CogVideoXImageToVideoPipelineI2V本 Transformer 作为transformer组件注入import torch from diffusers import CogVideoXPipeline from diffusers.utils import export_to_video pipe CogVideoXPipeline.from_pretrained( THUDM/CogVideoX-2b, dtypetorch.float16, ).to(cuda) video pipe( prompt一只木质玩具船在蓝色地毯上滑行模拟海浪起伏, guidance_scale6, num_inference_steps50, ).frames[0] export_to_video(video, output.mp4, fps8)官方提示见 CogVideoX 管线文档T2V 检查点在 1360×768 分辨率下效果最佳I2V 检查点支持宽 768–1360、高 758宽高需能被 16 整除T2V 与 I2V 均推荐 81 或 161 帧并以 16fps 导出。这些分辨率与帧数最终都会反映为 Transformer 的sample_height/sample_width/sample_frames等配置理解本文的参数体系即可准确预判模型的输入约束。参考链接模型 API 文档cogvideox_transformer3d.md源码实现cogvideox_transformer_3d.pyPatch 嵌入实现embeddings.pyCogVideoXPatchEmbed类输出结构定义modeling_outputs.pyTransformer2DModelOutput测试套件test_models_transformer_cogvideox.py管线用法CogVideoX 管线文档训练指南docs/source/en/training/cogvideox.md训练脚本示例train_cogvideox_lora.py 与 train_cogvideox_image_to_video_lora.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），仅供参考