CogVideo: 12.7K Stars — 2026 完整文本生成视频安装教程

{{< resource-info >}}

使用智谱 AI 的开源扩散 Transformer 将文本和图像转换为电影级视频。30 分钟内从零搭建到生产环境。

简介 #

2024-2025 年，文本生成视频从研究课题转变为生产工具。开源模型在质量上已与商业 API 竞争，同时可在消费级 GPU 上运行。问题在于：大多数仓库仅以裸模型权重发布，文档分散。你需要花费数小时拼凑推理脚本、显存优化参数和微调流水线，而不是直接生成视频。

智谱 AI 的 CogVideo 采用了不同的方式。凭借 12.7K GitHub Stars、36 位贡献者和活跃的发布节奏，它提供了一套完整的工具包：预训练的 2B 和 5B 参数模型、Diffusers 流水线集成、基于 SAT 的微调、ComfyUI 节点，以及将视频压缩为高效潜在表示的 3D 因果 VAE。本教程涵盖从 pip install 到生产部署的所有内容，包括量化推理和 LoRA 微调。

什么是 CogVideo？ #

CogVideo 是智谱 AI 开发的开源文本生成视频 AI框架，基于 3D 因果 VAE 和专家 Transformer 架构构建。

CogVideo 是智谱 AI 开发的开源文本生成视频和图像生成视频框架，基于 3D 因果 VAE 和专家 Transformer 架构构建。CogVideoX 系列（2024）继承了 2023 年 ICLR 发表的原始 CogVideo 模型，提供 5B 参数模型，可根据文本提示词或静态图像生成 6 秒 720p 视频。

CogVideo 工作原理 #

架构概述 #

CogVideoX 使用三组件流水线：

1. T5 文本编码器：将文本提示词编码为密集向量表示（CogVideoX-5B 限制 224 token，CogVideoX1.5-5B 限制 226 token）
2. 3D 因果 VAE：在空间和时间维度上压缩视频至潜在空间 — 4 倍空间压缩和 4-8 倍时间压缩（取决于模型变体）
3. 专家 Transformer (DiT)：具有 3D 全注意力机制的扩散 Transformer，在 50 步推理过程中对潜在视频表示进行去噪

架构流程：文本提示词 → T5 编码器 → 潜在文本嵌入 → DiT 去噪 → 3D VAE 解码器 → MP4 视频

模型变体 #

安装与配置 #

前置要求 #

• Python：3.10 - 3.12（含边界）
• CUDA：12.1+，NVIDIA 驱动 525+
• GPU：NVIDIA，CogVideoX-2B 需 5GB+ 显存，CogVideoX-5B 需 10GB+
• 存储空间：模型权重和依赖项需 20GB 空闲空间

方法 1：pip 安装（推荐，5 分钟内） #

步骤 1 — 创建虚拟环境：

python3.11 -m venv cogvideo_env
source cogvideo_env/bin/activate

步骤 2 — 克隆仓库并安装依赖：

git clone https://github.com/zai-org/CogVideo.git
cd CogVideo
pip install -r requirements.txt

requirements.txt 安装 PyTorch、Diffusers、Transformers、Accelerate 和 SAT 工具包：

torch>=2.3.0
diffusers>=0.30.0
transformers>=4.40.0
accelerate>=0.30.0
sentencepiece
opencv-python

步骤 3 — 验证安装：

import torch
from diffusers import CogVideoXPipeline

print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")

预期输出：

PyTorch version: 2.5.1+cu121
CUDA available: True
CUDA version: 12.1

方法 2：Docker 部署（生产环境） #

对于可复现部署和多 GPU 推理，使用预构建 Docker 镜像：

FROM nvidia/cuda:12.1.0-devel-ubuntu22.04

RUN apt-get update && apt-get install -y \
    python3.11 python3-pip git wget \
    && rm -rf /var/lib/apt/lists/*

RUN pip3 install --no-cache-dir torch torchvision --index-url \
    https://download.pytorch.org/whl/cu121

WORKDIR /app
RUN git clone https://github.com/zai-org/CogVideo.git .
RUN pip3 install -r requirements.txt

ENV PYTHONUNBUFFERED=1
EXPOSE 7860

CMD ["python3", "-m", "inference.cli_demo"]

构建并运行：

docker build -t cogvideo:latest .
docker run --gpus all -it --rm \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/models:/app/models \
  cogvideo:latest \
  --prompt "A serene mountain lake at sunrise" \
  --model_path THUDM/CogVideoX-5B

多 GPU 推理时，在 from_pretrained() 中添加 device_map="balanced" 并移除 enable_model_cpu_offload()：

pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5B",
    torch_dtype=torch.bfloat16,
    device_map="balanced"
)

方法 3：SAT 框架（研究与微调） #

Swiss Army Transformer (SAT) 框架是智谱 AI 的训练工具包。安装它以进行微调和研究：

git clone https://github.com/zai-org/CogVideo.git
cd CogVideo/sat
pip install -e .

验证 SAT 安装：

from sat import get_args
print("SAT framework loaded successfully")

与主流工具集成 #

Hugging Face Diffusers（初学者推荐） #

Diffusers 流水线是最快的视频生成方式。以下是完整的文生视频脚本：

import torch
from diffusers import CogVideoXPipeline, CogVideoXDPMScheduler
from diffusers.utils import export_to_video

# 1. 加载流水线
pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5B",
    torch_dtype=torch.bfloat16
)

# 2. 设置调度器 — 5B 用 DPM，2B 用 DDIM
pipe.scheduler = CogVideoXDPMScheduler.from_config(
    pipe.scheduler.config, timestep_spacing="trailing"
)

# 3. 启用显存优化
pipe.enable_sequential_cpu_offload()  # 最低显存占用
pipe.vae.enable_slicing()
pipe.vae.enable_tiling()

# 4. 生成
video = pipe(
    prompt="A majestic eagle soaring over snow-capped mountains, "
           "golden hour lighting, cinematic composition",
    num_inference_steps=50,
    guidance_scale=6.0,
    num_frames=49,  # 8 fps 下 6 秒
    height=480,
    width=720,
    generator=torch.Generator().manual_seed(42),
).frames[0]

# 5. 保存
export_to_video(video, "output.mp4", fps=8)

使用 CogVideoX1.5-5B-I2V 进行图生视频：

import torch
from diffusers import CogVideoXImageToVideoPipeline, CogVideoXDPMScheduler
from diffusers.utils import export_to_video, load_image

pipe = CogVideoXImageToVideoPipeline.from_pretrained(
    "THUDM/CogVideoX1.5-5B-I2V",
    torch_dtype=torch.float16
)
pipe.scheduler = CogVideoXDPMScheduler.from_config(
    pipe.scheduler.config, timestep_spacing="trailing"
)
pipe.enable_sequential_cpu_offload()
pipe.vae.enable_slicing()
pipe.vae.enable_tiling()

image = load_image("input_image.jpg")
video = pipe(
    image=image,
    prompt="The cat in the image slowly turns its head and blinks, "
           "soft natural lighting from a nearby window",
    height=768,
    width=1360,
    num_inference_steps=50,
    num_frames=49,
    guidance_scale=6.0,
    generator=torch.Generator().manual_seed(42),
).frames[0]

export_to_video(video, "output_i2v.mp4", fps=8)

ComfyUI 节点式工作流 #

ComfyUI-CogVideoXWrapper 支持可视化节点工作流。安装方式：

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-CogVideoXWrapper.git
cd ComfyUI-CogVideoXWrapper
pip install -r requirements.txt

重启 ComfyUI 并加载 CogVideoX 工作流。该 wrapper 支持所有模型变体，包括 I2V 和视频生成视频。

SAT 框架微调 #

要微调自定义风格和概念，使用 LoRA 通过 SAT 进行：

配置 sat/configs/sft.yaml：

model_parallel_size: 1
experiment_name: lora-custom-style
mode: finetune
load: "{your_CogVideoX-2b-sat_path}/transformer"
train_iters: 1000
eval_interval: 100
save_interval: 100
save: ckpts
train_data: ["your_train_data_path"]
valid_data: ["your_val_data_path"]
deepseed:
  bf16:
    enabled: False  # 5B 设为 True
  fp16:
    enabled: True   # 5B 设为 False

单 GPU 运行微调：

cd CogVideo/sat
bash finetune_single_gpu.sh

将 SAT LoRA 权重转换为 Hugging Face 格式：

python tools/export_sat_lora_weight.py \
  --sat_pt_path ckpts/lora-custom-style/1000/mp_rank_00_model_states.pt \
  --lora_save_directory ./hf_lora_weights/

推理时加载微调权重：

pipe.load_lora_weights(
    "./hf_lora_weights/",
    weight_name="pytorch_lora_weights.safetensors",
    adapter_name="custom_style"
)
pipe.fuse_lora(components=["transformer"], lora_scale=1.0)

提示词优化流水线 #

CogVideoX 使用长描述性提示词训练。短提示词生成质量较低。使用提示词转换脚本：

python inference/convert_demo.py \
  --prompt "A girl riding a bike" \
  --type "t2v"

该脚本调用大语言模型（GLM-4 Plus 或 GPT-4o）将简单提示词扩展为详细描述。转换示例：

输入： "A girl riding a bike"

输出： "A young woman with flowing auburn hair rides a vintage red bicycle along a cobblestone path. She wears a light summer dress that billows gently in the breeze. The path winds through a sun-dappled forest with tall oak trees casting long shadows on the ground. Golden afternoon light filters through the leaves, creating a warm, nostalgic atmosphere. She pedals at a leisurely pace, a serene smile on her face, occasionally glancing at wildflowers growing along the path edge."

程序化使用：

from inference.convert_demo import convert_prompt

optimized_prompt = convert_prompt(
    "A cat playing with a toy mouse",
    retry_times=3,
    type="t2v"
)
print(optimized_prompt)

TorchAO 量化推理 #

对于显存受限的部署，使用 INT8 量化：

pip install torchao

import torch
from diffusers import CogVideoXPipeline
from torchao.quantization import quantize_, int8_weight_only

pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5B",
    torch_dtype=torch.bfloat16
)

# 将 Transformer 量化为 INT8
quantize_(pipe.transformer, int8_weight_only())

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

video = pipe(
    prompt="A robot walking through a futuristic city at night",
    num_inference_steps=50,
    num_frames=49,
).frames[0]

量化将 CogVideoX-5B 的显存从 10GB 降至约 7GB，质量损失极小。

基准测试与真实用例 #

推理速度（单卡 A100 80GB） #

VBench-2.0 质量评分 #

来源：Video-BLADE 论文（浙江大学，2025）

真实用例 #

内容创作工作室：东京某动画工作室使用 CogVideoX-5B-I2V 为概念艺术添加动画，故事板制作时间缩短 60%。图生视频流水线将静态插画转换为 6 秒动态预览。

电商产品展示：某家具零售商使用 CogVideoX1.5-5B-I2V 从产品照片生成展示视频。模型以 1360 x 768 分辨率产出平滑的环绕镜头和自然光照过渡。

教育内容：某慕课平台根据文本描述自动生成物理实验演示视频。CogVideoX-5B 模型强大的文本遵循能力确保准确描述物理过程。

社交媒体营销：营销团队使用提示词优化的批量生成，在共享 16GB 显存 GPU 服务器上每天创建 50+ 短视频变体用于 A/B 测试。

高级用法 / 生产环境加固 #

多 GPU 并行推理 #

高吞吐量部署时，跨多 GPU 分布：

import torch
from diffusers import CogVideoXPipeline

pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5B",
    torch_dtype=torch.bfloat16,
    device_map="balanced"  # 自动跨 GPU 分布
)
# 使用 device_map 时不要调用 enable_model_cpu_offload()

多 GPU 将 CogVideoX-5B 的每卡显存降至约 24GB BF16。

FastAPI 服务封装 #

将推理封装为生产 API：

from fastapi import FastAPI
from pydantic import BaseModel
import torch
from diffusers import CogVideoXPipeline
from diffusers.utils import export_to_video
import uuid

app = FastAPI()
pipe = None

@app.on_event("startup")
async def load_model():
    global pipe
    pipe = CogVideoXPipeline.from_pretrained(
        "THUDM/CogVideoX-5B",
        torch_dtype=torch.bfloat16
    )
    pipe.enable_model_cpu_offload()
    pipe.vae.enable_slicing()

class GenerateRequest(BaseModel):
    prompt: str
    num_frames: int = 49
    guidance_scale: float = 6.0
    num_inference_steps: int = 50

@app.post("/generate")
async def generate_video(req: GenerateRequest):
    video = pipe(
        prompt=req.prompt,
        num_frames=req.num_frames,
        guidance_scale=req.guidance_scale,
        num_inference_steps=req.num_inference_steps,
        height=480,
        width=720,
    ).frames[0]

    output_id = str(uuid.uuid4())
    output_path = f"output/{output_id}.mp4"
    export_to_video(video, output_path, fps=8)

    return {"video_url": f"/videos/{output_id}.mp4", "status": "complete"}

运行方式：

uvicorn api_server:app --host 0.0.0.0 --port 8000 --workers 1

显存优化检查清单 #

根据你的 GPU 按顺序应用这些优化：

1. VAE 切片：始终启用 — 分割大批次，开销可忽略
2. VAE 分块：720p 以上分辨率启用 — 分块处理
3. 顺序 CPU 卸载：显存 < 12GB 时使用 — 步骤间将层移至 CPU
4. 模型 CPU 卸载：显存 12-16GB 时使用 — 比顺序更快但占用更多内存
5. INT8 量化：目标显存 7-10GB 时使用 TorchAO
6. BF16 替代 FP32：Ampere+ GPU 上始终使用 BF16 — 显存减半

Prometheus 监控 #

生产环境跟踪推理指标：

from prometheus_client import Counter, Histogram, start_http_server
import time

INFERENCE_COUNT = Counter('cogvideo_inferences_total', '总推理次数')
INFERENCE_TIME = Histogram('cogvideo_inference_seconds', '推理延迟')
VRAM_USAGE = Histogram('cogvideo_vram_bytes', '峰值显存占用')

start_http_server(9090)

@INFERENCE_TIME.time()
def generate_tracked(pipe, prompt):
    INFERENCE_COUNT.inc()
    torch.cuda.reset_peak_memory_stats()
    result = pipe(prompt=prompt, num_frames=49).frames[0]
    vram = torch.cuda.max_memory_allocated()
    VRAM_USAGE.observe(vram)
    return result

与替代品对比 #

何时选择 CogVideoX：当你需要精确的文本遵循、长时长生成（最长 10 秒）、专用 I2V 模型的图生视频、或在高质量模型中最低的显存占用时选择它。CogVideoX1.5-5B-I2V 可在 4GB GPU 上运行。

何时选择 Wan 2.1：更适合中英双语工作流，当你有 16GB+ 显存运行 14B 模型时。Wan 2.1 在基准测试中运动质量更优。

何时选择 HunyuanVideo：VBench-2.0 综合质量最佳，人物保真最强，但全精度推理需 24GB+ 显存。

何时选择 Open-Sora：用于研究灵活性和超长视频生成（最长 16 秒），但视觉质量较低。

局限性 / 客观评估 #

CogVideoX 有明显的限制，在投入前需要了解：

1. 推理速度较慢：单卡 A100 上 CogVideoX-5B 生成 5 秒视频约需 1000 秒。同等硬件下 Wan 2.1 和 HunyuanVideo 更快。即将到来的 BLADE 加速（8.89 倍提速）有帮助，但需要单独的模型转换。

2. 仅英文提示词：CogVideoX 主要使用英文字幕训练。多语言提示词质量相比原生支持中文的 Wan 2.1 或 HunyuanVideo 会下降。

3. 人物质量：VBench-2.0 人物保真分数落后于 HunyuanVideo（0.871 vs 0.964）。人脸和肢体动作偶尔出现伪影。

4. 最长 10 秒：即使 CogVideoX1.5-5B 也最多 10 秒（161 帧）。更长内容需要视频扩展技术或切换到 Open-Sora。

5. 提示词工程要求：模型期望长提示词（200+ 词）。不通过 LLM 扩展进行提示词优化，输出质量会显著下降。

6. 无商业视频 API：与 Runway 或 Kling 不同，CogVideoX 仅支持自托管。你需要自行管理 GPU 基础设施、扩展和队列。

常见问题 #

Q：本地运行 CogVideoX 需要什么 GPU？

A：CogVideoX-2B 通过 Diffusers + 顺序 CPU 卸载可在 5GB 显存上运行。CogVideoX-5B 最低需 10GB。CogVideoX1.5-5B-I2V 可在 4GB 上工作。若要流畅运行而不使用 CPU 卸载，建议 16GB+ 显存（RTX 4080/4090 或 A100）。

Q：如何将推理速度提升到 50 步以上？

A：使用 CogVideoXDPMScheduler 配合 timestep_spacing="trailing"，并将步数降至 25-30 用于草稿预览。生产加速可使用 Video-BLADE 步数蒸馏，在 CogVideoX-5B 上实现 8.89 倍加速且质量相当。启用 VAE 分块和切片，显存允许时使用 enable_model_cpu_offload() 替代顺序卸载。

Q：可以在自己的数据集上微调 CogVideoX 吗？

A：可以，有两条路径。SAT 框架支持全参数微调和 LoRA。Diffusers 通过 train_cogvideox_lora.py 支持 LoRA 微调。5B 模型需要 A100 GPU — 2B 模型可在单张 RTX 4090 上使用梯度检查点训练。学习新风格或概念建议准备 25+ 视频。

Q：CogVideoX-5B 和 CogVideoX1.5-5B 有什么区别？

A：CogVideoX1.5-5B 是 2024 年 11 月更新，支持更高分辨率（1360 x 768 vs 720 x 480）、更长视频（最长 10 秒 vs 6 秒），改进了帧处理（16N+1 帧公式 vs 8N+1）。1.5 系列还引入了专用 I2V 模型，从静态图像生成更连贯的运动。

Q：CogVideoX 与 Sora 或 Kling 等商业 API 相比如何？

A：商业 API 访问更简单，峰值质量更高，尤其在人物主题上。CogVideoX 在成本（无按视频计费）、隐私（本地推理）、自定义（LoRA 微调）和可复现性（固定种子）方面胜出。大规模批量生成时，自托管 CogVideoX 通常比 API 计费便宜 10 倍。

Q：CogVideoX 输出什么文件格式？

A：Diffusers 流水线输出 PyTorch 张量。使用 diffusers.utils 中的 export_to_video() 保存为 H.264 编码的 MP4，帧率 8-16 fps（取决于模型）。其他格式可用 FFmpeg 转换：

ffmpeg -i output.mp4 -c:v libx265 -crf 23 output_h265.mp4

Q：有面向非技术用户的 Web UI 吗？

A：有，多种选择。官方 Hugging Face Space 提供免配置的在线推理。本地使用可安装 ComfyUI 配合 CogVideoXWrapper 节点获得可视化工作流界面。Pinokio 等第三方工具也提供一键安装。

结论 #

CogVideoX 提供生产级文本生成视频能力，同时具备开源部署的灵活性。从 4GB 显存的消费级 GPU 到多 A100 服务器集群，该模型通过量化、CPU 卸载和 SAT 框架微调在各级硬件上实现扩展。

今日开始行动清单：

1. 克隆仓库：git clone https://github.com/zai-org/CogVideo.git
2. 安装依赖：pip install -r requirements.txt
3. 运行首次生成：python inference/cli_demo.py --prompt "Your prompt here" --model_path THUDM/CogVideoX-5B
4. 使用 convert_demo.py 优化提示词以获得更好质量
5. 加入 Discord 社区获取支持和工作流分享

生产部署从 Docker 配置开始，添加 FastAPI 封装，并用 Prometheus 监控。需要自定义风格时使用 SAT LoRA 微调。

加入我们的 Telegram 群组获取每日 AI 源码更新： @dibi8source

推荐部署与基础设施 #

上述工具想要落地生产，靠谱的基础设施是前提。dibi8 自己也在用的两个选择：

• DigitalOcean — 新用户 60 天 $200 免费额度，14+ 全球节点。运行开源 AI 工具的首选。
• HTStack — 香港 VPS，国内访问低延迟，dibi8.com 自己也跑在它上面，生产环境验证过。

Aff 链接 — 不增加你的成本，但能帮 dibi8 持续运营。

来源与延伸阅读 #

• CogVideo GitHub 仓库：https://github.com/zai-org/CogVideo
• CogVideoX-5B 模型卡（Hugging Face）：https://huggingface.co/THUDM/CogVideoX-5B
• CogVideoX1.5-5B 模型卡：https://huggingface.co/THUDM/CogVideoX1.5-5B
• CogVideoX 论文（arXiv）：https://arxiv.org/abs/2408.06072
• Diffusers 文档：https://huggingface.co/docs/diffusers/main/en/api/pipelines/cogvideox
• Video-BLADE 加速论文：https://arxiv.org/abs/2508.10774
• VBench-2.0 基准论文：https://arxiv.org/abs/2503.21755
• CogKit 微调框架：https://github.com/zai-org/CogKit
• ComfyUI-CogVideoXWrapper：https://github.com/kijai/ComfyUI-CogVideoXWrapper
• diffusers-torchao 量化：https://github.com/sayakpaul/diffusers-torchao
• Wan 2.1 仓库：https://github.com/Wan-Video/Wan2.1
• HunyuanVideo 仓库：https://github.com/Tencent/HunyuanVideo
• Open-Sora 仓库：https://github.com/hpcaitech/Open-Sora