企业官网建设流程全解析

• 视频生成
• 媒体生成
• 大模型
• 微调
• AI 应用

本文以 zai-org/CogVideo-code 开源仓库的官方说明文档为主体，系统梳理 CogVideoX 系列文本/图像生成视频模型的完整技术栈：从模型规格对比与选型、提示词优化、diffusers 与 SAT 双推理路线、量化推理与内存优化，到 diffusers LoRA/SFT 微调与 SAT 微调，并结合仓库内的 推理脚本、配置模板 与 训练脚本 等源码进行佐证。读完本文，你将能独立完成 CogVideoX 各版本模型的推理部署、低显存适配与自定义数据集微调。

一、项目概览与版本演进时间线

CogVideoX 是与清影（QingYing）同源的视频生成大模型开源版本，仓库同时维护着 2023 年发布的 Transformer 文生视频模型 CogVideo（ICLR'23）。从文档记录的更新历史可以清晰看到系列模型的演进脉络：

二、快速开始：三条关键前置路径

1. 提示词优化（强烈建议）

CogVideoX 使用长文本提示词训练，提示词质量直接决定生成视频的质量。官方要求在运行模型前先参考 convert_demo.py，用 GLM-4（或 GPT-4 等同等能力大模型）把用户短提示词改写为符合训练分布的详细长描述。

该脚本的调用方式为：

# 文生视频（t2v） python convert_demo.py --prompt "A girl riding a bike." --type "t2v" # 图生视频（i2v），可选提供参考图 python convert_demo.py --prompt "the cat is running" --type "i2v" --image_path "/path/to/your/image.jpg"

从源码看，t2v 分支使用英文系统提示词约束大模型输出"单个视频描述"，并通过 few-shot 示例（如沙滩女孩、足球场慢跑等）引导输出风格；i2v 分支则要求模型"基于输入图像给出极具描述性的视频字幕"，且不得包含镜头切换、视角位移等描述。默认模型为glm-4-plus（gpt-4o亦经测试），采样参数为temperature=0.01, top_p=0.7, max_tokens=250，失败时最多重试 3 次（--retry_times）。

2. SAT 路线

遵循 sat/README.md 的指引。SAT（SwissArmyTransformer）权重包含推理与微调代码，适合希望基于 CogVideoX 模型结构做二次改进的研究者进行快速堆叠与开发。该路线对 Python 版本有硬性要求：3.10 ~ 3.12（含两端）。

3. Diffusers 路线

pip install -r requirements.txt

然后参考 cli_demo.py，其中包含推理代码的详细说明及常用参数含义。仓库根目录 requirements.txt 必须严格遵循，否则可能出现依赖版本不匹配。若需量化推理，可结合 Diffusers 与 TorchAO 实现内存高效推理，并在编译时获得速度提升。

三、模型规格总览（选型核心依据）

下表来自官方文档，汇总了当前提供的全部视频生成模型的基础信息，是选型与参数配置的第一依据：

上述模型均可从 HuggingFace、ModelScope、WiseModel 三个平台获取 diffusers 版权重（1.5 系列 SAT 权重可从 THUDM 的 SAT 镜像仓库获取）。仓库内 inference/cli_demo.py 的RESOLUTION_MAP与表格一一对应：cogvideox1.5-*推荐 768×1360，cogvideox-*推荐 480×720。

官方数据说明与内存优化要点

官方文档对上述指标给出了重要限定，理解这些才能正确解读数据：

• diffusers 指标前提：表格中 diffusers 数据均在启用 diffusers 库全部内置优化下测得，且只在NVIDIA A100 / H100上验证过，一般可适配所有NVIDIA Ampere 及以上架构。若关闭优化，峰值显存约为表中数值的 3 倍，但速度提升约 3~4 倍。可选择性关闭以下优化：

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

• 多卡推理：需关闭enable_sequential_cpu_offload()（cli_demo.py 中提示可通过device_map="balanced"+ 移除 offload 实现多卡）。
• INT8 代价：INT8 会显著降低推理速度，是面向小显存 GPU"保质量换速度"的取舍。
• 精度匹配：CogVideoX-2B 以 FP16 训练、5B 系列以 BF16 训练，推理建议使用训练时的精度。
• 量化工具：PytorchAO 与 Optimum-quanto 可对文本编码器、Transformer、VAE 分别量化，使模型可在免费 T4 Colab 或小显存 GPU 上运行；TorchAO 量化与torch.compile完全兼容，可显著提速。FP8 仅限 NVIDIA H100 及以上设备，需源码安装torch、torchao，建议使用 CUDA 12.4。
• 速度测试前提：上述推理速度同样在启用内存优化时测得，不启用时速度约提升 10%；只有 diffusers 版模型支持量化。
• 语言限制：模型仅支持英文输入，其他语言需经大模型改写为英文。

四、diffusers 推理实战：核心参数逐项解读

inference/cli_demo.py 是 diffusers 路线的主推理解释，一个最小可运行示例为：

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

该脚本的核心逻辑与参数含义如下（均可在源码中得到验证）：

源码中还给出了两个工程细节：

1. Scheduler 选择：默认使用CogVideoXDPMScheduler（timestep_spacing="trailing"），注释建议 2B 可用CogVideoXDDIMScheduler、5B/5B-I2V 推荐 DPM；DPM 调度器下须传use_dynamic_cfg=True。
2. 显存优化：默认启用enable_sequential_cpu_offload()、vae.enable_slicing()、vae.enable_tiling()；若显存充足（如 H100）或使用多卡，可改用enable_model_cpu_offload()甚至直接.to("cuda")换取更快的推理。

量化推理（低显存方案）

inference/cli_demo_quantization.py 提供 int8 / fp8 量化推理：

python cli_demo_quantization.py --prompt "A girl riding a bike." --model_path THUDM/CogVideoX-2b --quantization_scheme fp8 --dtype float16

源码实现上，该脚本对 text_encoder、transformer、vae 三个子模块分别执行int8_weight_only()或quantize_to_float8(..., ActivationCasting.DYNAMIC)，再组装为CogVideoXPipeline。使用前提：torchao与torch需从源码安装；fp8 仅支持 H100 及以上 NVIDIA GPU；所有量化方案均要求 NVIDIA GPU。

五、SAT 路线推理与微调

SAT 版本是官方为研究者提供的另一套完整方案，其说明文档位于 sat/README.md，推理与微调均基于sat/目录下的代码与配置。

1. 推理流程

# 安装依赖 pip install -r requirements.txt # 下载权重（以 1.5 为例，包含 Transformer、VAE、T5 Encoder 三部分） git lfs install git clone https://huggingface.co/THUDM/CogVideoX1.5-5B-SAT # 修改 sat/configs/cogvideox*.yaml 中的模型路径，以及 configs/inference.yaml 中的参数后运行 bash inference.sh

inference.yaml的关键字段（sat/configs/inference.yaml）：load指向 transformer 目录绝对路径；input_type可选txt（读 configs/test.txt，每行一条提示词）或cli（命令行输入）；sampling_num_frames对 1.5-5B 必须是 42 或 22，对 5B/2B 必须是 13、11 或 9；fp16: True用于 2B、bf16: True用于 5B；output_dir默认输出到outputs/。

从 configs/cogvideox1.5_5b_i2v.yaml 可以看出 1.5 系列模型结构的关键差异：num_frames: 81（10 秒时为 161）、num_layers: 42、hidden_size: 3072、num_attention_heads: 48、patch_size: [2,2,2]、in_channels: 32，位置编码使用Rotary3DPositionEmbeddingMixin，采样器为VPSDEDPMPP2MSampler配合DynamicCFG（scale: 6, exp: 5）；而 2B 版本配置（configs/cogvideox_2b.yaml）为num_frames: 49、num_layers: 30、hidden_size: 1920、patch_size: 2、in_channels: 16。

2. SAT 微调

SAT 微调仅针对 transformer 部分，VAE 保持不变，T5 仅作编码器。数据集组织为labels/*.txt（每段视频对应同名标签文件）与videos/*.mp4一一对应；风格微调建议至少准备 50 个相似风格的视频-标签对。

支持 LoRA 与全参数 SFT 两种方式，通过在 configs/sft.yaml 中配置：load指向 transformer 路径、train_iters: 1000、save: ckpts、split: 1,0,0、deepspeed.bf16/fp16按 2B/5B 切换；LoRA 模式需额外在cogvideox_*_lora.yaml中启用lora_config（target: sat.model.finetune.lora2.LoraMixin，示例r: 256）。运行方式：

bash finetune_single_gpu.sh # 单卡 bash finetune_multi_gpus.sh # 多卡

微调后的 SAT 权重不能直接合并，推理时使用configs/cogvideox_<参数>_lora.yaml配置运行bash inference.sh。权重格式转换与导出工具见下文"工具链"。

六、diffusers 微调（LoRA 与 SFT）

diffusers 版微调指南见 finetune/README_ja.md，其核心信息包括硬件需求、数据集格式、脚本用法与最佳实践。

硬件需求速查表（官方实测）

注意：由于微调相关代码尚未合入 diffusers 官方 release，需基于 diffusers 仓库的 main 分支安装：git clone https://github.com/huggingface/diffusers.git && pip install -e .。

数据集格式

T2V 与 I2V 的数据集结构略有差异：

. ├── prompts.txt # 提示词文本 ├── videos/ # .mp4 视频文件 ├── videos.txt # videos/ 内视频文件列表 ├── images/ # (可选，I2V) .png 参考图 └── images.txt # (可选，I2V) 参考图文件列表

I2V 若不提供images/，默认使用视频首帧作为参考图像。训练前应遵守：帧数必须是 8 的倍数 +1（如 49、81）；分辨率建议使用模型默认尺寸（CogVideoX 为 480×720，CogVideoX1.5 为 768×1360）；不匹配的样本会被自动 resize，可能造成宽高比变形，建议预先做 crop+resize 处理。为提升训练效率，训练前会将视频编码为 latent 缓存到磁盘；训练后若修改数据，需删除videos/下的latent缓存目录。

LoRA 与 SFT 启动

bash train_ddp_t2v.sh # 文生视频 LoRA bash train_ddp_i2v.sh # 图生视频 LoRA bash train_zero_t2v.sh # 文生视频 SFT（Zero 配置） bash train_zero_i2v.sh # 图生视频 SFT（Zero 配置）

以 finetune/train_ddp_t2v.sh 为例，需要修改的核心参数包括：--output_dir（输出目录）、--data_root（数据根目录）、--caption_column（提示词文件）、--image_column（I2V 参考图列表，删除则默认用视频首帧）、--video_column（视频列表）、--train_resolution（如81x768x1360）、--mixed_precision（仅 2B 支持 fp16）、--checkpointing_steps、--do_validation等。SFT 的 Zero 配置（configs/zero2.yaml等，由 accelerate_config.yaml 的deepspeed_config_file指定）需与脚本内batch_size、gradient_accumulation_steps、mixed_precision保持一致。

SFT 训练的两条注意点：验证阶段不使用模型 offload，24GB 以下显存建议禁用验证；Zero-3 会拖慢验证，同样建议禁用。

微调最佳实践（官方建议）

• 25 条以上视频对新概念/风格训练效果最优（官方实验使用 70 条 200×480×720 的视频，并通过跳帧构造 49 帧与 16 帧子集加速实验）；
• 使用--id_token指定标识 token（类似 DreamBooth）可提升效果，但普通微调也可正常运行；
• lora_alpha官方默认 1 在多次运行中效果不佳，建议设为rank或rank // 2；
• rank 建议不小于 64。

微调完成后，加载方式见 cli_demo.py（--lora_path参数）；SFT 模型需先用checkpoint-*/zero_to_fp32.py合并权重。

七、项目结构导览：一条龙资源索引

官方文档将仓库划分为如下模块，对应各自的说明文档与示例代码：

Colab 快速上手

官方提供了可直接在免费 Colab T4 上运行的 Notebook：CogVideoX-5B 文生视频、5B INT8 量化文生视频（单次约 30 分钟）、5B 图生视频、5B 视频续写（V2V）。

Inference（inference/）

• cli_demo.py：diffusers 推理解释最详尽，含常用参数含义；
• cli_demo_quantization.py：量化推理，可在低显存设备运行，改参后可支持 FP8；
• cli_vae_demo.py：单独运行 VAE 推理（当前需要较多显存，后续将优化）；
• gradio_composite_demo：与 HuggingFace Space 相同的 GUI 代码，内置帧插值（RIFE）与超分工具，运行方式见其 README（python app.py，需配置OPENAI_API_KEY等环境变量）；
• convert_demo.py：提示词转换；
• gradio_web_demo.py：简单的 Gradio Web UI，支持 2B/5B 文生视频；
• ddim_inversion.py：DDIM 反转，用于视频重建/编辑（基于 5B 模型，2B 效果不佳）。

（上图：仓库内置的 Gradio Web Demo 界面截图，来源于官方文档的 Inference 章节）

finetune（finetune/）

• finetune/README_ja.md：diffusers 版微调方法详解，可用自己的数据集微调 CogVideoX；
• 训练脚本 train_ddp_t2v.sh / train_zero_t2v.sh、配置模板 configs/zero2.yaml 等均在此目录。

sat（sat/）

• sat/README.md：SAT 权重推理与微调代码说明，适合基于 CogVideoX 结构做快速扩展与研究的开发者。

工具链（tools/）

• convert_weight_sat2hf.py：SAT 权重 → HuggingFace 权重；
• export_sat_lora_weight.py：SAT 微调权重导出为 diffusers 格式 LoRA Adapter；
• load_cogvideox_lora.py：加载 diffusers 版微调 LoRA Adapter；
• caption：视频理解与文字描述生成工具（对应 CogVLM2-Caption）；
• llm_flux_cogvideox：开源本地大模型 + Flux + CogVideoX 自动生成视频；
• parallel_inference_xdit.py：基于 xDiT 的多 GPU 并行推理。

八、社区适配生态

官方文档列出多个已完成 CogVideoX 适配的社区项目，可作为扩展能力的选择：RIFLEx-CogVideoX（一行代码将视频长度外推一倍）、CogVideoX-Fun（灵活分辨率与多种启动方式的改良管线）、CogStudio（功能更丰富的 Gradio Web UI）、Xorbits Inference（分布式推理一键部署）、ComfyUI-CogVideoXWrapper（ComfyUI 工作流集成）、VideoSys（高性能视频生成基础设施）、AutoDL 镜像（社区提供的 Space 一键部署镜像）、室内设计微调模型、xDiT（多 GPU 集群 DiT 并行推理引擎）、CogVideoX-Interpolation（关键帧插值）、DiffSynth-Studio（重构文本编码器/UNet/VAE 的扩散引擎）、CogVideoX-Controlnet（ControlNet 模块）、VideoTuna（多模型 AI 视频生成聚合仓库）、ConsisID（基于 5B 的身份保持文生视频模型）等。

九、CogVideo（ICLR'23）：系列前身

CogVideo 是基于 Transformer 的大规模文生视频模型，官方论文《CogVideo: Large-scale Pretraining for Text-to-Video Generation via Transformers》对应的代码位于仓库CogVideo分支。该模型支持较高帧率视频生成（如 32 帧、4 秒片段），其在线演示原始输入为中文。

十、引用与许可证

若本项目工作对你有帮助，官方建议为仓库点赞并引用两篇论文，BibTeX 引用条目可直接在 README_ja.md 的「引用」章节获取（CogVideoX 论文 arXiv:2408.06072，CogVideo 论文 arXiv:2205.15868）。

许可证方面：本仓库代码以Apache 2.0发布（见 LICENSE）；CogVideoX-2B 模型（含 Transformer 与 VAE 模块）同样为 Apache 2.0；CogVideoX-5B 系列模型（含 T2V 与 I2V 版本）则适用独立的 CogVideoX 模型许可证（见 MODEL_LICENSE）。使用前请务必确认所选模型对应的许可条款。

• 视频生成
• 媒体生成
• 大模型
• 微调
• AI 应用