CogVideoX：智谱AI开源视频生成模型安装与使用指南

官方信息

项目背景

CogVideoX 是由清华大学知识工程实验室（THUDM）和智谱AI联合开发的开源视频生成模型系列。智谱AI在大语言模型领域（GLM系列）已经家喻户晓，CogVideoX是他们在视频生成领域的开源力作。项目从2022年的CogVideo初代开始，经过多轮迭代，到CogVideoX已经是第三代。

CogVideoX 采用"多规格+多能力"的产品线策略，提供多个版本以适配不同场景：

• CogVideoX-2B：20亿参数轻量版，消费级显卡可跑，480p分辨率
• CogVideoX-5B：50亿参数标准版，质量与速度平衡，720p分辨率
• CogVideoX-5B-I2V：图生视频版本，从图片生成动态视频
• CogVideoX1.5：更新版本，支持更长视频（10秒）和更高分辨率

与其他视频模型相比，CogVideoX的优势在于：中文支持优秀（基于GLM文本编码器）、生态成熟（智谱提供完整文档和商用API）、多种规格可选。它采用CogVideoX团队自研的3D VAE（Compressive Video Tokenizer），压缩效率高，视频解码质量好。模型采用Apache 2.0 / 智谱开放协议，可免费商用。

智谱同时提供了闭源的CogVideo商用API（清影），质量比开源版更高，但开源版已经足够个人创作者和中小企业使用。

核心特性

• 多规格产品线：2B轻量版（消费级显卡）、5B标准版（720p）、I2V图生视频版
• 优秀中文支持：基于GLM文本编码器，中文提示词理解领先
• 自研3D VAE：高压缩比+高画质解码，视频流畅自然
• 5-10秒视频：原生支持最长10秒（CogVideoX1.5）
• 智谱生态完善：完整文档、商用API、社区支持
• Diffusers原生支持：HuggingFace Diffusers一键调用
• 多种部署方式：源码/Diffusers/ComfyUI/API齐全

环境要求

详细部署步骤

方式一：Diffusers Pipeline（推荐）

1. 创建环境

   conda create -n cogvideo python=3.10 -y
   conda activate cogvideo
   
   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
   pip install -U diffusers transformers accelerate sentencepiece

2. CogVideoX-2B 文生视频（消费级显卡）

   import torch
   from diffusers import CogVideoXPipeline
   from diffusers.utils import export_to_video
   
   pipe = CogVideoXPipeline.from_pretrained(
       "THUDM/CogVideoX-2b",
       torch_dtype=torch.bfloat16
   )
   pipe.enable_model_cpu_offload()  # 12GB显存建议开启
   pipe.vae.enable_tiling()
   
   prompt = "一只大熊猫在竹林中悠闲地吃竹子，阳光透过树叶洒下斑驳光影"
   
   video = pipe(
       prompt=prompt,
       num_videos_per_prompt=1,
       num_inference_steps=50,
       num_frames=81,  # 约5秒
       guidance_scale=6,
       generator=torch.Generator("cuda").manual_seed(42)
   ).frames[0]
   
   export_to_video(video, "cogvideo_2b_output.mp4", fps=24)

3. CogVideoX-5B 高质量版（24GB+显存）

   pipe = CogVideoXPipeline.from_pretrained(
       "THUDM/CogVideoX-5b",
       torch_dtype=torch.bfloat16
   )
   pipe.to("cuda")
   pipe.vae.enable_tiling()
   
   video = pipe(
       prompt="航拍视角，桂林山水甲天下，江水清澈，游船划过，云雾缭绕",
       num_inference_steps=50,
       num_frames=81,
       guidance_scale=6
   ).frames[0]
   
   export_to_video(video, "cogvideo_5b_output.mp4", fps=24)

4. 图生视频（I2V）

   from diffusers import CogVideoXImageToVideoPipeline
   from diffusers.utils import load_image
   
   pipe = CogVideoXImageToVideoPipeline.from_pretrained(
       "THUDM/CogVideoX-5b-I2V",
       torch_dtype=torch.bfloat16
   )
   pipe.to("cuda")
   
   image = load_image("portrait.jpg")
   
   video = pipe(
       image=image,
       prompt="人物微笑着转头，微风吹动头发",
       num_inference_steps=50,
       num_frames=81,
       guidance_scale=6
   ).frames[0]
   
   export_to_video(video, "cogvideo_i2v_output.mp4", fps=24)

方式二：官方源码部署

1. 克隆仓库

   git clone https://github.com/THUDM/CogVideo.git
   cd CogVideo

2. 安装依赖

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. 下载模型（ModelScope国内推荐）

   pip install modelscope
   
   # 2B版本
   modelscope download --model ZhipuAI/CogVideoX-2b --local_dir ./checkpoints/CogVideoX-2b
   
   # 5B版本
   modelscope download --model ZhipuAI/CogVideoX-5b --local_dir ./checkpoints/CogVideoX-5b
   
   # 或HuggingFace
   huggingface-cli download THUDM/CogVideoX-5b --local-dir ./checkpoints/CogVideoX-5b

4. 启动Gradio Web Demo

   python inference/gradio_web_demo.py \
     --model-path ./checkpoints/CogVideoX-5b \
     --port 7860 \
     --share  # 可选

   浏览器打开 http://127.0.0.1:7860 即可使用。

5. 命令行推理

   python inference/cli_demo.py \
     --model_path ./checkpoints/CogVideoX-2b \
     --prompt "赛博朋克城市夜景，霓虹灯闪烁，雨中街道" \
     --output_path ./results/cyberpunk.mp4 \
     --num_frames 81 \
     --steps 50

方式三：ComfyUI 部署

1. 安装ComfyUI-CogVideoX节点

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

2. 下载模型到ComfyUI目录

   # CogVideoX DiT模型 → ComfyUI/models/diffusion_models/
   # VAE → ComfyUI/models/vae/
   # 文本编码器（GLM）→ ComfyUI/models/text_encoders/

3. 重启ComfyUI，加载CogVideoX工作流。

方式四：智谱商用API（无需本地GPU）

如果没有GPU，可以直接调用智谱的CogVideo商用API：

import zhipuai

zhipuai.api_key = "你的API Key"

# 提交视频生成任务
response = zhipuai.CogVideo.create(
    prompt="一只猫在窗台上晒太阳",
    quality="720p",
    duration=5
)

# 轮询获取结果
task_id = response.data.task_id
result = zhipuai.CogVideo.retrieve(task_id)
print(result.data.video_url)

API按秒计费，无需本地GPU，适合快速商用。

使用方法

提示词技巧

• CogVideoX中文支持优秀，直接用中文写自然语言描述即可
• 描述公式：主体 + 动作 + 环境 + 镜头 + 风格
• 示例："一只橘猫（主体）趴在窗台晒太阳（动作），窗外是北京胡同（环境），固定镜头（镜头），温暖治愈（风格）"
• 加上运动描述："树叶随风飘动"、"水波荡漾"、"人物微笑"
• 负面提示词："模糊，低质量，变形，闪烁，多余肢体"

生成时间参考

显存优化

• pipe.enable_model_cpu_offload()：省10GB+显存
• pipe.vae.enable_tiling()：VAE分块解码
• 使用FP8量化权重
• 减少帧数：81帧→49帧（约3秒）

常见问题（FAQ）

Q1: 12GB显存能跑CogVideoX吗？

可以跑2B版本，480p分辨率、81帧、50步。5B版本在12GB显存上会OOM，建议用FP8量化版+CPU offload，但速度会很慢。

Q2: CogVideoX和HunyuanVideo/Wan2.1比哪个好？

各有优势：CogVideoX的优势是中文支持优秀、智谱生态完善（有商用API）、多种规格可选。HunyuanVideo质量最高（13B参数），Wan2.1可商用协议最宽松（Apache 2.0）。如果中文是刚需，CogVideoX是好选择。

Q3: 模型下载太慢怎么办？

国内用户用ModelScope（魔搭）下载，速度可达10MB/s以上。也可以用hf-mirror.com镜像。

Q4: 支持图生视频吗？

支持。下载CogVideoX-5b-I2V权重，传入一张图片作为起始帧，模型会基于图片生成动态视频。适合让静态照片动起来。

Q5: 可以商用吗？

开源版CogVideoX采用智谱开放模型许可，个人和中小企业可免费商用。如果需要更高质量和SLA保障，可以使用智谱的CogVideo商用API（清影）。

跳转链接

• GitHub 仓库：https://github.com/THUDM/CogVideo
• 智谱AI官网：https://www.zhipuai.cn
• HuggingFace模型页：https://huggingface.co/THUDM
• ModelScope模型页：https://modelscope.cn/models/ZhipuAI
• 智谱API文档：https://open.bigmodel.cn/dev/api/cogvideo
• ComfyUI节点：https://github.com/kijai/ComfyUI-CogVideoXWrapper