CogVideo: 12.7K Stars — Hướng Dẫn Cài Đặt Text-to-Video Đầy Đủ 2026

{{< resource-info >}}

Biến văn bản và hình ảnh thành video điện ảnh với Diffusion Transformer mã nguồn mở của Zhipu AI. Từ zero đến production trong 30 phút.

Giới Thiệu #

Tạo video từ văn bản đã chuyển từ chủ đề nghiên cứu sang công cụ production trong 2024-2025. Các mô hình mã nguồn mở hiện cạnh tranh với API thương mại về chất lượng trong khi chạy trên GPU ngườì dùng. Vấn đề là: hầu hết repository chỉ cung cấp model weights với tài liệu rải rác. Bạn mất hàng giờ để ghép script inference, flag tối ưu VRAM và pipeline fine-tuning thay vì tạo video.

CogVideo của Zhipu AI giải quyết khác biệt. Với 12.7K GitHub stars, 36 contributors và release active, nó cung cấp toolkit đầy đủ: model pretrained 2B và 5B tham số, tích hợp Diffusers pipeline, fine-tuning SAT, node ComfyUI và 3D causal VAE nén video thành biểu diễn latent hiệu quả. Hướng dẫn này bao gồm mọi thứ từ pip install đến triển khai production với quantized inference và LoRA fine-tuning.

CogVideo Là Gì? #

CogVideo là framework tạo video từ văn bản và hình ảnh mã nguồn mở do Zhipu AI phát triển, dựa trên kiến trúc 3D causal VAE và expert transformer. Series CogVideoX (2024) kế thừa mô hình CogVideo gốc được công bố tại ICLR 2023, cung cấp model 5B tham số tạo video 6 giây 720p từ text prompt hoặc ảnh tĩnh.

CogVideo Hoạt Động Như Thế Nào #

Tổng Quan Kiến Trúc #

CogVideoX sử dụng pipeline ba thành phần:

1. T5 Text Encoder: Mã hóa text prompt thành biểu diễn vector dày đặc (giới hạn 224 token cho CogVideoX-5B, 226 token cho CogVideoX1.5-5B)
2. 3D Causal VAE: Nén video không gian và thờì gian vào latent space — nén không gian 4x và nén thờì gian 4-8x tùy biến thể model
3. Expert Transformer (DiT): Diffusion transformer với 3D full attention denoise biểu diễn video latent qua 50 bước inference

Luồng kiến trúc: Text Prompt → T5 Encoder → Latent Text Embedding → DiT Denoising → 3D VAE Decoder → MP4 Video

Các Biến Thể Model #

Cài Đặt & Thiết Lập #

Yêu Cầu Tiên Quyết #

• Python: 3.10 - 3.12 (bao gồm)
• CUDA: 12.1+ với driver NVIDIA 525+
• GPU: NVIDIA, 5GB+ VRAM cho CogVideoX-2B, 10GB+ cho CogVideoX-5B
• Lưu trữ: 20GB trống cho model weights + dependencies

Cách 1: pip Install (Khuyến nghị, Dưới 5 Phút) #

Bước 1 — Tạo môi trường ảo:

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

Bước 2 — Clone repository và cài dependencies:

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

requirements.txt cài PyTorch, Diffusers, Transformers, Accelerate và toolkit SAT:

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

Bước 3 — Xác minh cài đặt:

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}")

Output mong đợi:

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

Cách 2: Docker Deployment (Production) #

Triển khai reproducible và multi-GPU inference với Docker image:

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"]

Build và run:

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

Multi-GPU inference, thêm device_map="balanced" vào from_pretrained() và bỏ enable_model_cpu_offload():

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

Cách 3: SAT Framework (Nghiên cứu & Fine-tuning) #

Swiss Army Transformer (SAT) là training toolkit của Zhipu AI. Cài để fine-tune và nghiên cứu:

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

Xác minh SAT:

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

Tích Hợp Với Công Cụ Phổ Biến #

Hugging Face Diffusers (Khuyến nghị Cho Ngườì Mới) #

Diffusers pipeline là cách nhanh nhất để tạo video. Script text-to-video đầy đủ:

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

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

# 2. Set scheduler — DPM cho 5B, DDIM cho 2B
pipe.scheduler = CogVideoXDPMScheduler.from_config(
    pipe.scheduler.config, timestep_spacing="trailing"
)

# 3. Bật memory optimizations
pipe.enable_sequential_cpu_offload()  # VRAM thấp nhất
pipe.vae.enable_slicing()
pipe.vae.enable_tiling()

# 4. Generate
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,  # 6 giây ở 8 fps
    height=480,
    width=720,
    generator=torch.Generator().manual_seed(42),
).frames[0]

# 5. Lưu
export_to_video(video, "output.mp4", fps=8)

Image-to-video với 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 Node-Based Workflow #

ComfyUI-CogVideoXWrapper cho phép workflow dạng node trực quan. Cài đặt:

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

Restart ComfyUI và load workflow CogVideoX. Wrapper hỗ trợ mọi biến thể model bao gồm I2V và video-to-video.

SAT Framework Fine-Tuning #

Fine-tune style và concept tùy chỉnh bằng LoRA qua SAT:

Cấu hình 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  # True cho 5B
  fp16:
    enabled: True   # False cho 5B

Chạy fine-tuning trên single GPU:

cd CogVideo/sat
bash finetune_single_gpu.sh

Chuyển đổi SAT LoRA weights sang Hugging Face format:

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/

Load fine-tuned weights trong inference:

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)

Pipeline Tối Ưu Prompt #

CogVideoX được train với prompt dài, mô tả chi tiết. Prompt ngắn cho chất lượng thấp hơn. Dùng script chuyển đổi prompt:

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

Script gọi large language model (GLM-4 Plus hoặc GPT-4o) để mở rộng prompt đơn giản thành mô tả chi tiết. Ví dụ chuyển đổi:

Input: "A girl riding a bike"

Output: "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."

Dùng programmatic:

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)

Quantized Inference Với TorchAO #

Cho deployment VRAM hạn chế, dùng INT8 quantization qua diffusers-torchao:

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
)

# Quantize transformer sang 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]

Quantization giảm VRAM từ 10GB xuống ~7GB cho CogVideoX-5B với ít mất mát chất lượng.

Benchmarks & Use Case Thực Tế #

Tốc Độ Inference (Single A100 80GB) #

Điểm Chất Lượng VBench-2.0 #

Nguồn: Video-BLADE paper (Zhejiang University, 2025)

Use Case Thực Tế #

Studio Sáng Tạo Nội Dung: Studio animation Tokyo dùng CogVideoX-5B-I2V để animate concept art, rút ngắn 60% thờì gian sản xuất storyboard.

Demo Sản Phẩm E-commerce: Nhà bán lẻ nội thất tạo video showcase từ ảnh sản phẩm bằng CogVideoX1.5-5B-I2V, độ phân giải 1360 x 768.

Nội Dung Giáo Dục: Nền tảng MOOC tự động tạo video demo thí nghiệm vật lý từ mô tả văn bản.

Marketing Mạng Xã Hội: Team marketing tạo 50+ video variant mỗi ngày cho A/B testing trên server GPU 16GB VRAM.

Cách Sử Dụng Nâng Cao / Củng Cố Production #

Multi-GPU Parallel Inference #

Phân phối inference qua nhiều GPU cho throughput cao:

import torch
from diffusers import CogVideoXPipeline

pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5B",
    torch_dtype=torch.bfloat16,
    device_map="balanced"  # Auto-distribute qua GPUs
)
# Không gọi enable_model_cpu_offload() với device_map

Multi-GPU giảm memory mỗi GPU xuống ~24GB BF16 cho CogVideoX-5B.

API Server Với FastAPI #

Wrap inference trong production 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"}

Chạy:

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

Checklist Tối Ưu VRAM #

Áp dụng theo thứ tự dựa trên GPU:

1. VAE Slicing: Luôn bật — chia batch lớn
2. VAE Tiling: Bật cho độ phân giải trên 720p
3. Sequential CPU Offload: Dùng khi VRAM < 12GB
4. Model CPU Offload: Dùng khi VRAM 12-16GB
5. INT8 Quantization: Dùng TorchAO cho target VRAM 7-10GB
6. BF16 thay FP32: Luôn dùng BF16 trên Ampere+ GPU

Monitoring Với Prometheus #

Theo dõi metrics inference trong production:

from prometheus_client import Counter, Histogram, start_http_server
import time

INFERENCE_COUNT = Counter('cogvideo_inferences_total', 'Tổng số inference')
INFERENCE_TIME = Histogram('cogvideo_inference_seconds', 'Độ trễ inference')
VRAM_USAGE = Histogram('cogvideo_vram_bytes', 'VRAM peak')

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

So Sánh Với Các Lựa Chọn Khác #

Khi chọn CogVideoX: Khi cần text-following chính xác, tạo video dài (tối đa 10s), I2V với model chuyên dụng, hoặc VRAM thấp nhất. CogVideoX1.5-5B-I2V chạy trên GPU 4GB.

Khi chọn Wan 2.1: Tốt hơn cho workflow song ngữ Trung-Anh với 16GB+ VRAM. Wan 2.1 có chất lượng chuyển động vượt trội.

Khi chọn HunyuanVideo: Chất lượng tổng thể tốt nhất trên VBench-2.0, nhưng cần 24GB+ VRAM.

Khi chọn Open-Sora: Cho linh hoạt nghiên cứu và video rất dài (tối đa 16 giây), chất lượng hình ảnh thấp hơn.

Hạn Chế / Đánh Giá Trung Thực #

CogVideoX có những ràng buộc rõ ràng cần biết trước khi đầu tư:

1. Inference Chậm: Video 5 giây mất ~1000 giây trên A100 với CogVideoX-5B ở 50 bước. Wan 2.1 và HunyuanVideo nhanh hơn.

2. Chỉ Hỗ Trợ Prompt Tiếng Anh: CogVideoX chủ yếu train trên caption tiếng Anh. So với Wan 2.1 hoặc HunyuanVideo xử lý tiếng Trung native, prompt đa ngôn ngữ giảm chất lượng.

3. Chất Lượng Ngườì: Điểm human fidelity VBench-2.0 thấp hơn HunyuanVideo (0.871 vs 0.964). Mặt ngườì và chuyển động cơ thể thờ̀nh thoảng có artifact.

4. Tối Đa 10 Giây: CogVideoX1.5-5B cũng giới hạn 10 giây (161 frames). Nội dung dài hơn cần kỹ thuật mở rộng video hoặc chuyển sang Open-Sora.

5. Yêu Cầu Prompt Engineering: Model cần prompt dài, chi tiết (200+ từ). Không tối ưu prompt qua LLM expansion, chất lượng output giảm đáng kể.

6. Không Có API Video Thương Mại: Khác với Runway hay Kling, CogVideoX chỉ hỗ trợ self-hosted. Bạn tự quản lý GPU infrastructure, scaling và queueing.

Câu Hỏi Thường Gặp #

Q: Cần GPU gì để chạy CogVideoX locally?

A: CogVideoX-2B chạy trên 5GB VRAM với Diffusers + sequential CPU offload. CogVideoX-5B cần 10GB. CogVideoX1.5-5B-I2V chạy trên 4GB. Để trải nghiệm mượt không dùng CPU offload, hướng đến 16GB+ VRAM (RTX 4080/4090 hoặc A100).

Q: Làm sao tăng tốc inference vượt quá 50 bước?

A: Dùng CogVideoXDPMScheduler với timestep_spacing="trailing" và giảm bước xuống 25-30 cho preview. Video-BLADE step distillation đạt 8.89x tốc độ trên CogVideoX-5B. Bật VAE tiling và slicing.

Q: Có thể fine-tune CogVideoX trên dataset riêng không?

A: Có, qua hai đường dẫn. SAT framework hỗ trợ full-parameter fine-tuning và LoRA. Diffusers hỗ trợ LoRA qua train_cogvideox_lora.py. Model 5B cần A100 GPU — model 2B có thể train trên single RTX 4090. Cần 25+ video cho học style hoặc concept mới.

Q: Khác biệt giữa CogVideoX-5B và CogVideoX1.5-5B là gì?

A: CogVideoX1.5-5B là bản cập nhật tháng 11/2024 với độ phân giải cao hơn (1360 x 768 vs 720 x 480), video dài hơn (tối đa 10 giây vs 6 giây), cải thiện xử lý frame (công thức 16N+1 vs 8N+1). Series 1.5 còn có model I2V chuyên dụng.

Q: CogVideoX so với API thương mại như Sora hay Kling?

A: API thương mại dễ truy cập, chất lượng đỉnh cao hơn, đặc biệt về chủ đề ngườì. CogVideoX thắng về chi phí (không phí/video), privacy (local inference), tùy chỉnh (LoRA fine-tuning) và khả năng tái tạo (fixed seeds). Tạo video hàng loạt quy mô lớn, self-hosted CogVideoX thường rẻ hơn 10 lần API billing.

Q: CogVideoX output định dạng file gì?

A: Diffusers pipeline output PyTorch tensors. Dùng export_to_video() từ diffusers.utils để lưu MP4 với H.264 encoding ở 8-16 FPS. Chuyển đổi sang định dạng khác bằng FFmpeg:

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

Q: Có web UI cho ngườì dùng không kỹ thuật không?

A: Có, nhiều lựa chọn. Hugging Face Space chính thức cho online inference không cần setup. ComfyUI với node CogVideoXWrapper cho giao diện workflow trực quan local.

Kết Luận #

CogVideoX cung cấp tạo video từ văn bản cấp production với tính linh hoạt của triển khai mã nguồn mở. Từ GPU ngườì dùng 4GB VRAM đến cluster server đa A100, model mở rộng qua mọi cấp hardware nhờ quantization, CPU offloading và SAT framework fine-tuning.

Hành động để bắt đầu ngay hôm nay:

1. Clone repository: git clone https://github.com/zai-org/CogVideo.git
2. Cài dependencies: pip install -r requirements.txt
3. Chạy generation đầu tiên: python inference/cli_demo.py --prompt "Your prompt here" --model_path THUDM/CogVideoX-5B
4. Tối ưu prompt với convert_demo.py để chất lượng tốt hơn
5. Tham gia cộng đồng Discord để hỗ trợ và chia sẻ workflow

Cho triển khai production, bắt đầu với Docker setup, thêm FastAPI wrapping, và monitor bằng Prometheus.

Tham gia nhóm Telegram để cập nhật mã nguồn AI hàng ngày: @dibi8source

Hosting Và Hạ Tầng Được Đề Xuất #

Trước khi triển khai các công cụ trên vào production, bạn cần hạ tầng vững chắc. Hai lựa chọn dibi8 đang dùng:

• DigitalOcean — Credit miễn phí $200 trong 60 ngày, 14+ khu vực toàn cầu. Lựa chọn mặc định cho dev chạy AI tools open source.
• HTStack — VPS Hong Kong, độ trễ thấp khi truy cập từ Trung Quốc. Cùng IDC đang host dibi8.com.

Liên kết tiếp thị — không tăng chi phí của bạn, giúp dibi8.com hoạt động.

Nguồn & Tài Liệu Tham Khảo #

• CogVideo GitHub Repository: https://github.com/zai-org/CogVideo
• CogVideoX-5B Model Card (Hugging Face): https://huggingface.co/THUDM/CogVideoX-5B
• CogVideoX1.5-5B Model Card: https://huggingface.co/THUDM/CogVideoX1.5-5B
• CogVideoX Paper (arXiv): https://arxiv.org/abs/2408.06072
• Diffusers Documentation: https://huggingface.co/docs/diffusers/main/en/api/pipelines/cogvideox
• Video-BLADE Acceleration Paper: https://arxiv.org/abs/2508.10774
• VBench-2.0 Benchmark Paper: https://arxiv.org/abs/2503.21755
• CogKit Fine-Tuning Framework: https://github.com/zai-org/CogKit
• ComfyUI-CogVideoXWrapper: https://github.com/kijai/ComfyUI-CogVideoXWrapper
• diffusers-torchao Quantization: https://github.com/sayakpaul/diffusers-torchao
• Wan 2.1 Repository: https://github.com/Wan-Video/Wan2.1
• HunyuanVideo Repository: https://github.com/Tencent/HunyuanVideo
• Open-Sora Repository: https://github.com/hpcaitech/Open-Sora