CogVideoX 视频生成模型仓库全景指南：模型矩阵、推理调优与 LoRA/SFT 微调实战

CogVideoX 是智谱 AI「清影」同源的开源视频生成模型系列，覆盖文本生成视频（T2V）、图像生成视频（I2V）与视频续写（V2V）三大任务，配套 SAT 与 Diffusers 两套推理/微调代码路径。本文以仓库根目录 README_zh.md 为骨架，结合 推理入口、提示词优化脚本、微调文档 与 SAT 文档 等源码细节，系统讲解模型选型、推理参数、显存/量化优化以及 LoRA 与全参 SFT 微调流程，帮助读者从零上手该仓库并完成可复现的实战部署。

项目概览与版本更新脉络

仓库同时托管了 CogVideoX（2024 年发布，T2V/I2V 扩散模型）与早期 CogVideo（ICLR 2023 论文模型，位于 CogVideo 分支）两条技术线。从项目更新记录可以清晰看到模型家族的演进节奏：

• 2024/8/6：开源首个 CogVideoX 系列模型 CogVideoX-2B，并同步开源可几乎无损重构视频的 3D Causal VAE；CogVideoX-2B 的协议随后调整为 Apache 2.0。
• 2024/8/27：发布更大规模的 CogVideoX-5B，大幅优化推理性能，官方称可在 GTX 1080TI 等早期显卡运行 2B 模型、在 RTX 3060 桌面卡运行 5B 模型，并要求严格按照 requirements.txt 更新依赖。
• 2024/9/19：开源图生视频模型 CogVideoX-5B-I2V，可将一张图像作为背景结合提示词生成视频；同时开源用于把视频数据转成文本描述的训练配套 Caption 模型 CogVLM2-Caption。
• 2024/11/8：发布升级版 CogVideoX1.5-5B 系列，支持 10 秒视频与更高分辨率，其中 CogVideoX1.5-5B-I2V 支持任意分辨率生成；CogVideoX1.5 的 SAT 代码已更新，diffusers 版本于 2024/11/15 发布，只需调整少量参数即可沿用旧代码。
• 2025/1/8：更新基于 diffusers 版本的 LoRA 微调代码，占用显存更低。
• 2025/2/28：DDIM Inverse 已支持 CogVideoX-5B 与 CogVideoX1.5-5B，详见 inference/ddim_inversion.py。
• 2025/3/24：推出 CogKit 微调与推理工具包（覆盖 CogView4、CogVideoX 系列），官方建议后续微调工作迁移至 CogKit 维护。

模型矩阵：CogVideoX 系列规格对照

下表（来自 README_zh.md）汇总了当前提供的五个模型的核心规格，是选型与参数设置的第一手依据：

模型名	CogVideoX1.5-5B (最新)	CogVideoX1.5-5B-I2V (最新)	CogVideoX-2B	CogVideoX-5B	CogVideoX-5B-I2V
发布时间	2024/11/8	2024/11/8	2024/8/6	2024/8/27	2024/9/19
视频分辨率	1360×768	Min(W,H)=768，768≤Max(W,H)≤1360，Max(W,H)%16=0	720×480	720×480	720×480
帧数	16N+1，N≤10（默认 81）	同左	8N+1，N≤6（默认 49）	同左	同左
推理精度	BF16（推荐）、FP16、FP32、FP8*、INT8（不支持 INT4）	同左	FP16（推荐）*、BF16、FP32、FP8*、INT8（不支持 INT4）	BF16（推荐）、FP16、FP32、FP8*、INT8（不支持 INT4）	同左
单 GPU 显存	SAT BF16：76GB；diffusers BF16：10GB 起*；diffusers INT8(torchao)：7GB 起*	同左	SAT FP16：18GB；diffusers FP16：4GB 起*；diffusers INT8(torchao)：3.6GB 起*	SAT BF16：26GB；diffusers BF16：5GB 起*；diffusers INT8(torchao)：4.4GB 起*	同左
多 GPU 推理显存	BF16：24GB* (diffusers)	同左	FP16：10GB* (diffusers)	BF16：15GB* (diffusers)	同左
推理速度 (Step=50, FP/BF16)	单卡 A100：约 1000 秒（5 秒视频）；单卡 H100：约 550 秒	同左	单卡 A100：约 90 秒；单卡 H100：约 45 秒	单卡 A100：约 180 秒；单卡 H100：约 90 秒	同左
提示词语言	English*（统一）	同左	同左	同左	同左
提示词长度上限	224 Tokens	224 Tokens	226 Tokens	226 Tokens	226 Tokens
视频长度	5 秒或 10 秒	同左	6 秒	6 秒	6 秒
帧率	16 fps	16 fps	8 fps	8 fps	8 fps
位置编码	3d_rope_pos_embed	3d_rope_pos_embed	3d_sincos_pos_embed	3d_rope_pos_embed	3d_rope_pos_embed + learnable_pos_embed

要点解读：

• 帧数是硬约束：1.5 系列必须是 16N+1（默认 81，10 秒对应 161 帧），1.0 系列必须是 8N+1（默认 49）。若想自定义帧数必须遵循该公式，否则会与模型训练时的时序结构不匹配。
• 训练精度与推理精度需对齐：CogVideoX-2B 以 FP16 训练，其余 5B 系列以 BF16 训练，官方推荐使用与训练一致的精度进行推理。
• 1.5-I2V 支持任意分辨率（长边 768~1360 且能被 16 整除），其余模型建议使用默认分辨率，自定义分辨率会在推理脚本中被自动回退。

快速开始：两条代码路径

仓库为 CogVideoX 提供了 SAT 与 Diffusers 两套可运行方案，前者适合结构改进与研究迭代，后者上手门槛更低、生态兼容性更好。

提示词优化（强烈建议先行）

模型是在长提示词下训练的，提示词质量直接决定视频质量。仓库提供的 inference/convert_demo.py 使用 GLM-4（或同级别的 GPT-4 等大模型）把用户的简短输入扩写为符合训练分布的长描述，官方文档明确强调这一步"很重要"。

从源码可见其关键设计（inference/convert_demo.py）：

• T2V 模式：使用 sys_prompt_t2v 系统提示词，通过 few-shot 示例（海滩上的女子、足球场跑步、舞蹈等示例）引导 LLM 输出"极其详细且描述性"的单段视频描述，调用 glm-4-plus 模型（源码注释表明 glm-4-plus 和 gpt-4o 均经过测试），参数为 temperature=0.01、top_p=0.7、max_tokens=250。
• I2V 模式：使用 sys_prompt_i2v 系统提示词，把输入图片以 base64 形式（image_to_url 函数）随用户输入一起发给 gpt-4o，提示词要求输出"以当前图像为第一帧、描述后续动作"的英文视频描述，并明确禁止"镜头切换/视角变化"。
• 脚本内置 retry_times=3 重试机制，请求失败时回退返回原始提示词。

运行方式：

# 文本生成视频的提示词优化
python inference/convert_demo.py --prompt "A girl riding a bike." --type "t2v"

# 图像生成视频的提示词优化
python inference/convert_demo.py --prompt "the cat is running" --type "i2v" --image_path "/path/to/your/image.jpg"

此外，模型仅支持英文输入，其他语言建议通过大模型润色时翻译为英文。

Diffusers 路线

环境要求：Python 版本需在 3.10 至 3.12 之间（含两端）。安装依赖后即可开始推理：

pip install -r requirements.txt

requirements.txt 中的关键依赖包括：diffusers>=0.35.2、accelerate>=1.11.0、transformers>=4.57.1、torch>=2.8.0、torchvision>=0.23.0、sentencepiece、SwissArmyTransformer>=0.4.12、gradio>=5.49.1、imageio、imageio-ffmpeg、openai>=2.2.0、moviepy、scikit-video、pydantic>=2.12.0。详细推理参数见下文。

SAT 路线

查看 sat/README_zh.md，内含 SAT 权重的推理与微调代码。SAT 是研究型路径，推荐基于 CogVideoX 模型结构做改进的开发者使用（详见后文专节）。

推理实战：cli_demo 参数全解

inference/cli_demo.py 是官方提供的最详细推理示例，一个脚本支持三种生成类型：

• t2v（文本生成视频）：使用 CogVideoXPipeline，支持 THUDM/CogVideoX-5b、THUDM/CogVideoX-2b、THUDM/CogVideoX1.5-5b；
• i2v（图像生成视频）：使用 CogVideoXImageToVideoPipeline，支持 THUDM/CogVideoX-5b-I2V、THUDM/CogVideoX1.5-5b-I2V；
• v2v（视频续写）：使用 CogVideoXVideoToVideoPipeline，将已有视频作为背景结合提示词继续生成。

命令行调用示例：

python inference/cli_demo.py --prompt "A girl riding a bike." --model_path THUDM/CogVideoX1.5-5b --generate_type "t2v"

脚本内部维护了一张推荐分辨率表（RESOLUTION_MAP），未显式指定 width/height 时会按模型自动填充默认分辨率；对非 I2V 模型传入自定义分辨率会被警告并回退到默认值：

RESOLUTION_MAP = {
    "cogvideox1.5-5b-i2v": (768, 1360),
    "cogvideox1.5-5b": (768, 1360),
    "cogvideox-5b-i2v": (480, 720),
    "cogvideox-5b": (480, 720),
    "cogvideox-2b": (480, 720),
}

全部命令行参数

参数	默认值	说明
--prompt	必填	视频内容描述（建议先经 LLM 润色为长提示词）
--model_path	THUDM/CogVideoX1.5-5B	预训练模型路径（HuggingFace 仓库名或本地目录）
--image_or_video_path	None	i2v 的输入图片路径 / v2v 的输入视频路径
--generate_type	t2v	生成类型：t2v / i2v / v2v
--num_inference_steps	50	推理步数，越多质量越高、耗时越长
--num_frames	81	生成帧数；1.0 系列 49 帧（6 秒 @8fps），1.5 系列 81/161 帧（5/10 秒 @16fps）
--guidance_scale	6.0	无分类器引导强度，越高与提示词对齐越紧
--width / --height	None	自定义分辨率（仅 1.5-5B-I2V 生效）
--fps	16	输出视频帧率
--num_videos_per_prompt	1	每个提示词生成的视频数量
--lora_path	None	微调 LoRA 权重路径
--lora_rank	128	LoRA 秩
--dtype	bfloat16	计算精度（float16 或 bfloat16）
--seed	42	随机种子，保证可复现性
--output_path	./output.mp4	输出视频保存路径

关键实现细节（代码级）

• 调度器：默认使用 CogVideoXDPMScheduler.from_config(pipe.scheduler.config, timestep_spacing="trailing")；注释提示可换为 CogVideoXDDIMScheduler，官方建议 2B 用 DDIM、5B/5B-I2V 用 DPM。使用 DPM 调度器时管道调用需传 use_dynamic_cfg=True（DDIM 下应置 False），对应 SAT 版配置中的 DynamicCFG 引导器。
• 显存优化三件套（默认开启）：

pipe.enable_sequential_cpu_offload()
pipe.vae.enable_slicing()
pipe.vae.enable_tiling()

显存充足（如 H100）或多卡场景下可改为 pipe.to("cuda") / pipe.enable_model_cpu_offload() 以换取速度；多 GPU 推理时必须在 from_pretrained 中加 device_map="balanced" 并关闭 enable_sequential_cpu_offload()。

• LoRA 加载：微调后的权重通过 pipe.load_lora_weights(lora_path, weight_name="pytorch_lora_weights.safetensors", adapter_name="test_1") 加载，再用 pipe.fuse_lora(components=["transformer"], lora_scale=1.0) 融合。
• 生成与导出：pipe(...) 返回 .frames[0]，经 export_to_video(video_generate, output_path, fps=fps) 写入 mp4。

显存优化与量化推理

README 的数据注释（"数据解释"）补充了与上表配套的重要前提，实际部署时必须理解：

• 上表 diffusers 显存数字是在启用全部 diffusers 自带优化的前提下测得，仅在 NVIDIA A100/H100 上验证过，一般可适配所有安培架构以上的 NVIDIA 设备。若关闭优化，峰值显存约为表格值的 3 倍，但速度提升 3~4 倍，可选择性关闭上文的三项优化。
• INT8 推理是为低显存显卡保留画质而设计，会大幅降低推理速度。
• 只有 diffusers 版本模型支持量化。量化工具包括 PytorchAO 与 Optimum-quanto，可量化文本编码器、Transformer 与 VAE 模块，这让模型有机会跑在免费的 T4 Colab 或更小显存的 GPU 上；TorchAO 量化与 torch.compile 完全兼容，可显著提升推理速度。
• FP8 精度仅在 NVIDIA H100 及以上设备必须使用，且需要从源码安装 torch、torchao Python 包（建议 CUDA 12.4）；FP8 仅测试通过，官方不建议在生产环境中使用。
• 推理速度测试同样基于上述显存优化方案；不采用优化时速度提升约 10%。

仓库还提供量化专用脚本 inference/cli_demo_quantization.py，可在显存较低设备上运行，也可基于它修改以支持 FP8 等精度；若只需单独执行 VAE 编解码验证，可参考 inference/cli_vae_demo.py。

微调实战：LoRA 与 SFT（diffusers 版本）

官方微调方案见 finetune/README_zh.md，覆盖 LoRA 与 全参 SFT 两种训练方式。注意：由于相关代码尚未合入 diffusers 发行版，需要基于 diffusers 的 main 分支安装：

git clone https://github.com/huggingface/diffusers.git
cd diffusers
pip install -e .

硬件要求速查

以下为文档给出的官方训练硬件基线（loRA rank=128）：

模型	训练类型	分布式策略	混合精度	训练分辨率(帧数x高x宽)	硬件要求
cogvideox-t2v-2b	lora	DDP	fp16	49x480x720	16G 显存 (NVIDIA 4080)
cogvideox-{t2v,i2v}-5b	lora	DDP	bf16	49x480x720	24G 显存 (NVIDIA 4090)
cogvideox1.5-{t2v,i2v}-5b	lora	DDP	bf16	81x768x1360	35G 显存 (NVIDIA A100)
cogvideox-t2v-2b	sft	DDP	fp16	49x480x720	36G 显存 (NVIDIA A100)
cogvideox-t2v-2b	sft	1卡 zero-2 + opt offload	fp16	49x480x720	17G 显存 (NVIDIA 4090)
cogvideox-t2v-2b	sft	8卡 zero-2	fp16	49x480x720	17G 显存 (NVIDIA 4090)
cogvideox-t2v-2b	sft	8卡 zero-3	fp16	49x480x720	19G 显存 (NVIDIA 4090)
cogvideox-t2v-2b	sft	8卡 zero-3 + opt and param offload	bf16	49x480x720	14G 显存 (NVIDIA 4080)
cogvideox-{t2v,i2v}-5b	sft	1卡 zero-2 + opt offload	bf16	49x480x720	42G 显存 (NVIDIA A100)
cogvideox-{t2v,i2v}-5b	sft	8卡 zero-2	bf16	49x480x720	42G 显存 (NVIDIA 4090)
cogvideox-{t2v,i2v}-5b	sft	8卡 zero-3	bf16	49x480x720	43G 显存 (NVIDIA 4090)
cogvideox-{t2v,i2v}-5b	sft	8卡 zero-3 + opt and param offload	bf16	49x480x720	28G 显存 (NVIDIA 5090)
cogvideox1.5-{t2v,i2v}-5b	sft	1卡 zero-2 + opt offload	bf16	81x768x1360	56G 显存 (NVIDIA A100)
cogvideox1.5-{t2v,i2v}-5b	sft	8卡 zero-2	bf16	81x768x1360	55G 显存 (NVIDIA A100)
cogvideox1.5-{t2v,i2v}-5b	sft	8卡 zero-3	bf16	81x768x1360	55G 显存 (NVIDIA A100)
cogvideox1.5-{t2v,i2v}-5b	sft	8卡 zero-3 + opt and param offload	bf16	81x768x1360	40G 显存 (NVIDIA A100)

数据集格式

T2V 与 I2V 的数据集结构略有差异（I2V 可选提供参考图像目录）：

.
├── prompts.txt      # 提示词
├── videos           # .mp4 视频文件
├── videos.txt       # videos 目录中的视频文件列表
├── images           # (可选, I2V) 参考图像
└── images.txt       # (可选, I2V) 参考图像列表

I2V 若不提供 images，代码会从视频中提取第一帧作为参考图像。示例数据集可参考迪士尼汽船威利号视频生成数据集；如需训练时验证，需额外提供与训练集同格式的验证数据集。

分辨率与数据预处理约束

1. 帧数必须是 8 的倍数 +1（8N+1），例如 49、81……；
2. 建议使用模型默认分辨率：CogVideoX 为 480x720（高 x 宽），CogVideoX1.5 为 768x1360；
3. 不满足分辨率的样本在代码中会被直接 resize，可能造成宽高比形变、影响训练效果，建议提前用 crop + resize 保持宽高比。
4. 重要：训练前代码会自动对视频 encode 并将 latent 缓存到磁盘；若训练后修改了数据，务必删除 videos 目录下的 latent 子目录以使用最新数据。

LoRA 微调

修改 finetune/train_ddp_t2v.sh 或 finetune/train_ddp_i2v.sh 中的配置后运行：

bash finetune/train_ddp_t2v.sh  # 文本生成视频 (T2V) 微调
bash finetune/train_ddp_i2v.sh  # 图像生成视频 (I2V) 微调

脚本中需要重点修改的参数（与文档及脚本实际参数一一对应）：

参数	说明
--model_path	基础模型，如 THUDM/CogVideoX1.5-5B / THUDM/CogVideoX1.5-5B-I2V
--model_name	如 cogvideox1.5-t2v / cogvideox1.5-i2v
--model_type	t2v 或 i2v
--training_type	lora（本小节）或 sft
--output_dir	输出目录
--data_root	数据集根目录
--caption_column	提示词文件路径（prompt.txt）
--video_column	视频文件列表路径（videos.txt）
--image_column	I2V 可选；注释掉该行则默认使用视频第一帧作为 image condition
--train_resolution	训练分辨率，格式 帧数x高x宽（如 81x768x1360）
--train_epochs	训练轮数（默认 10）
--batch_size / --gradient_accumulation_steps	批量大小与梯度累积
--mixed_precision	bf16 / fp16 / no（仅 CogVideoX-2B 支持 fp16 训练）
--checkpointing_steps / --checkpointing_limit	保存 checkpoint 步数与保留上限
--resume_from_checkpoint	从 checkpoint 恢复训练（默认注释）
--do_validation / --validation_dir / --validation_steps	训练中验证开关与配置（validation_steps 应为 checkpointing_steps 的倍数）
--gen_fps	验证生成视频的帧率（16）

SFT 全参微调

仓库在 finetune/configs 目录提供 zero 系列配置模板（zero2.yaml、zero2_offload.yaml、zero3.yaml、zero3_offload.yaml），在 finetune/accelerate_config.yaml 中通过 deepspeed_config_file 选项切换即可。启动脚本为：

bash finetune/train_zero_t2v.sh  # 文本生成视频 (T2V) 微调
bash finetune/train_zero_i2v.sh  # 图像生成视频 (I2V) 微调

使用 SFT 训练注意两点（文档明确提示）：

1. SFT 训练时 validation 不会使用 model offload，显存峰值可能超过 24GB，24GB 以下显卡建议关闭 validation；
2. 开启 zero-3 时 validation 较慢，同样建议关闭。

另外，需确保 zero 配置文件与 bash 脚本中的 batch_size、gradient_accumulation_steps、mixed_precision 等参数保持一致。

加载微调后的模型

• LoRA 微调结果可直接参考 inference/cli_demo.py 的 --lora_path 参数加载。
• SFT 全参训练产物是 DeepSpeed checkpoint，需先使用 checkpoint-*/ 目录下的 zero_to_fp32.py 脚本合并权重后再用于推理。

官方微调最佳实践

文档 finetune/README_zh.md 给出了社区实践沉淀的经验：

• 数据集规模：25 个及以上概念相似、分辨率约为 200x480x720（帧数 x 高 x 宽）的训练视频，在训练新概念与风格时效果最佳；
• 建议使用 --id_token 指定的标识符 token 进行训练（类似 Dreambooth），但常规微调不使用也能工作；
• lora_alpha 官方原值 1 在多轮运行中效果不佳，建议设为与 rank 相同或 rank // 2；
• LoRA rank 建议 64 及以上。

SAT 版本：推理与微调

SAT 文档 对应 sat 目录，基于 SwissArmyTransformer 权重体系，仅支持 CogVideoX1.5 系列（1.0 版本见仓库 v1.0 标签）。SAT 路径对 transformer 结构研究者更友好，便于快速堆叠和开发。

权重下载与目录组织

以 CogVideoX1.5 为例（git lfs 克隆会同时下载 Transformer、VAE、T5 Encoder 三个模型）：

git lfs install
git clone https://huggingface.co/THUDM/CogVideoX1.5-5B-SAT

CogVideoX-2B/5B 的旧版本模型需按文档从清华云盘下载 vae.zip、transformer.zip 并解压，最终整理为如下结构（latest 指向当前 mp_rank_00_model_states.pt 所在目录）：

.
├── transformer
│   ├── 1000 (or 1)
│   │   └── mp_rank_00_model_states.pt
│   └── latest
└── vae
    └── 3d-vae.pt

T5 文本编码器不参与训练但必须使用，可克隆 THUDM/CogVideoX-2b 后将 text_encoder/ 与 tokenizer/ 内容合并进 t5-v1_1-xxl 目录，得到含 model-*.safetensors、spiece.model 等 8 个文件的完整目录，避免 DeepSpeed 微调时读入报错。

推理配置与运行

修改 sat/configs/cogvideox_*.yaml 中的模型配置（first_stage_config.ckpt_path 指向 vae 权重、conditioner_config 中 model_dir 指向 t5 目录），再修改 sat/configs/inference.yaml：

args:
  latent_channels: 16
  mode: inference
  load: "{absolute_path}/transformer"      # Transformer 权重绝对路径
  batch_size: 1
  input_type: txt                          # 也可改为 cli 从命令行输入
  input_file: configs/test.txt
  sampling_num_frames: 13                  # CogVideoX1.5-5B 必须为 42 或 22；CogVideoX-5B/2B 必须为 13/11/9
  sampling_fps: 8
  fp16: True                               # CogVideoX-2B 用 FP16
  # bf16: True                             # CogVideoX-5B 用 BF16
  output_dir: outputs/
  force_inference: True

然后运行 bash sat/inference.sh。若使用 txt 输入，每行一个提示词（建议先用 convert_demo.py 润色）；若希望自定义分辨率或使用 I2V，可在 yaml 中调整 sampling_image_size 等参数。

SAT 微调与权重导出

SAT 微调仅针对 transformer 部分，VAE 固定不变，T5 仅作 Encoder。支持 LoRA 与全参两种方式：

• 全参 SFT：修改 sat/configs/sft.yaml（含 train_iters、save_interval、train_data、deepspeed 的 bf16/fp16 开关等），并切换运行脚本中的配置组合：

  torchrun --standalone --nproc_per_node=8 train_video.py --base configs/cogvideox_2b.yaml configs/sft.yaml --seed $RANDOM
  

• LoRA：在 cogvideox_*_lora.yaml 中取消 not_trainable_prefixes: ['all'] 与 lora_config（target: sat.model.finetune.lora2.LoraMixin，r: 256）的注释，再切换启动脚本：

  torchrun --standalone --nproc_per_node=8 train_video.py --base configs/cogvideox_2b_lora.yaml configs/sft.yaml --seed $RANDOM
  

• 单卡/多卡分别使用 bash sat/finetune_single_gpu.sh / bash sat/finetune_multi_gpus.sh 启动；风格微调建议准备至少 50 条风格相似的视频与标签。

微调后的权重需转换才能在 diffusers 生态中使用：

python tools/convert_weight_sat2hf.py                              # SAT -> HF 全量权重
python tools/export_sat_lora_weight.py --sat_pt_path {args.save}/{experiment_name}-*/1000/mp_rank_00_model_states.pt --lora_save_directory {args.save}/export_hf_lora_weights_1/

LoRA 导出时，tools/export_sat_lora_weight.py 会把 SAT 的 attention.query_key_value.matrix_A/B 等结构映射为 HF 的 attn1.to_q/to_k/to_v.lora_A/B.weight 等键名，导出后用 tools/load_cogvideox_lora.py 即可加载推理。

完整项目代码结构导览

仓库按功能划分为五大区块，官方给出如下导航（相对路径均已在本文转换为仓库根目录视角）：

Colab 快速使用

免费 Colab T4 可直接运行的四个示例：CogVideoX-5B-T2V、CogVideoX-5B-T2V-Int8（量化推理，单次约 30 分钟）、CogVideoX-5B-I2V、CogVideoX-5B-V2V。

inference（推理）

• inference/cli_demo.py：最详细的推理讲解，常见参数含义均在此提及；
• inference/cli_demo_quantization.py：量化推理代码，可运行于低显存设备，也可修改以支持 FP8 精度（FP8 需源码安装 torch-nightly 与 torchao，不建议生产环境使用）；
• inference/cli_vae_demo.py：单独执行 VAE 推理；
• inference/gradio_composite_demo：HuggingFace Space 同款 GUI 代码，内置插帧（RIFE）与超分工具，快速部署入口为 inference/gradio_composite_demo/app.py；
• inference/convert_demo.py：用户输入到长提示词的转换脚本（默认 GLM-4，可替换为 GPT、Gemini 等任意 LLM）；
• inference/ddim_inversion.py：DDIM Inverse 支持脚本。

finetune（微调）

finetune/README_zh.md：diffusers 版本 CogVideoX 模型微调方案与细节，LoRA/SFT 的完整流程见上文专节。

sat（SAT 权重推理与微调）

sat/README_zh.md：SAT 权重的推理与微调代码，适合结构改进研究。

tools（工具链）

• tools/convert_weight_sat2hf.py：SAT 权重转 HuggingFace 权重；
• tools/export_sat_lora_weight.py：SAT LoRA Adapter 导出为 diffusers 格式；
• tools/load_cogvideox_lora.py：加载 diffusers 版微调 LoRA Adapter；
• tools/caption/README_zh.md：视频理解 Caption 工具（CogVLM2-Caption）说明；
• tools/llm_flux_cogvideox/llm_flux_cogvideox.py：开源本地大模型 + Flux + CogVideoX 的自动化视频生成；
• tools/parallel_inference/parallel_inference_xdit.py：基于 xDiT 的多 GPU 并行视频生成。

历史模型 CogVideo（ICLR'23）

CogVideo（论文 CogVideo: Large-scale Pretraining for Text-to-Video Generation via Transformers）是首个开源的基于 Transformer 的大型文本生成视频模型，其官方实现位于仓库的 CogVideo 分支，能够生成高帧率视频（如 32 帧的 4 秒片段），官方演示站点支持中文提示词输入体验。该模型与当前的 CogVideoX 扩散模型系列共同构成了仓库的两代技术积淀。

引用与模型协议

若工作受益于本项目，可引用以下两篇论文（BibTeX 见 README_zh.md）：

• CogVideoX: Text-to-Video Diffusion Models with An Expert Transformer（arXiv:2408.06072，2024）
• CogVideo: Large-scale Pretraining for Text-to-Video Generation via Transformers（arXiv:2205.15868，2022）

协议要点：仓库代码按 Apache 2.0 发布；CogVideoX-2B 模型（含 Transformer 与 VAE 模块）同样为 Apache 2.0；CogVideoX-5B 系列模型（含 I2V 与 T2V 的 Transformer 模块）则按 CogVideoX 专属 LICENSE 发布，商用前需核对相应条款。

结语

从模型矩阵到两条推理路径，从显存/量化优化到 LoRA 与 SFT 微调，本仓库为 CogVideoX 提供了完整的开箱即用体验：研究结构改进走 sat 路径，快速落地与生态集成走 diffusers 路径，数据集打磨与超参经验则沉淀在 finetune/README_zh.md。上手时牢记三条主线——长提示词先行润色、帧数遵循 8N+1/16N+1 约束、训练精度与推理精度对齐，即可把官方基准快速复现到自己的视频生成与微调任务中。