CogVideo: 12.7K Stars — 2026 완전한 텍스트-비디오 설정 가이드

{{< resource-info >}}

Zhipu AI의 오픈소스 확산 트랜스포머로 텍스트와 이미지를 영화 같은 비디오로 변환하세요. 30분 안에 제로에서 프로덕션까지.

소개 #

2024-2025년에 텍스트-비디오 생성은 연구 주제에서 프로덕션 도구로 발전했습니다. 오픈소스 모델은 이제 상업용 API와 품질에서 경쟁하면서 소비자용 GPU에서 실행됩니다. 문제는: 대부분의 저장소가 흩어진 문서와 함께 알몸 모델 가중치로 배송된다는 것입니다. 비디오를 생성하는 대신 추론 스크립트, VRAM 최적화 플래그, 미세 조정 파이프라인을 조립하는 데 수 시간을 소비합니다.

Zhipu AI의 CogVideo는 다르게 접근합니다. 12.7K GitHub 스타, 36명의 기여자, 활발한 릴리스를 통해 사전 학습된 2B 및 5B 매개변수 모델, Diffusers 파이프라인 통합, SAT 기반 미세 조정, ComfyUI 노드, 비디오를 효율적인 잠재 표현으로 압축하는 3D 인과적 VAE를 포함한 완전한 툴킷을 제공합니다. 이 가이드는 pip install부터 양자화 추론 및 LoRA 미세 조정이 포함된 프로덕션 배포까지 모든 것을 다룹니다.

CogVideo란? #

CogVideo는 Zhipu AI가 개발한 오픈소스 텍스트-비디오 및 이미지-비디오 생성 프레임워크로, 3D 인과적 VAE와 전문가 트랜스포머 아키텍처를 기반으로 합니다. CogVideoX 시리즈(2024)는 ICLR 2023에 발표된 원래 CogVideo 모델을 계승하여, 텍스트 프롬프트나 정지 이미지에서 6초 길이의 720p 비디오를 생성하는 5B 매개변수 모델을 제공합니다.

CogVideo 작동 방식 #

아키텍처 개요 #

CogVideoX는 세 가지 구성 요소 파이프라인을 사용합니다:

1. T5 텍스트 인코더: 텍스트 프롬프트를 밀집 벡터 표현으로 인코딩(CogVideoX-5B는 224 토큰 제한, CogVideoX1.5-5B는 226 토큰)
2. 3D 인과적 VAE: 비디오를 공간 및 시간적으로 잠재 공간으로 압축 — 모델 변형에 따라 4배 공간 압축 및 4-8배 시간 압축
3. 전문가 트랜스포머 (DiT): 50단계 추론 과정에서 잠재 비디오 표현을 디노이징하는 3D 전체 어텐션을 갖춘 확산 트랜스포머

아키텍처 흐름: 텍스트 프롬프트 → T5 인코더 → 잠재 텍스트 임베딩 → DiT 디노이징 → 3D VAE 디코더 → MP4 비디오

모델 변형 #

설치 및 설정 #

전제 조건 #

• Python: 3.10 - 3.12 (포함)
• CUDA: 12.1+, NVIDIA 드라이버 525+
• GPU: NVIDIA, CogVideoX-2B용 5GB+ VRAM, 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) 프레임워크는 Zhipu 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()  # 최소 VRAM
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,  # 8fps에서 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 워크플로우를 로드합니다. 래퍼는 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를 사용한 양자화 추론 #

제한된 VRAM 배포의 경우 diffusers-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
)

# 트랜스포머를 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의 VRAM을 10GB에서 약 7GB로 줄이면서 품질 저하가 최소화됩니다.

벤치마크 및 실제 사용 사례 #

추론 속도 (단일 A100 80GB) #

VBench-2.0 품질 점수 #

출처: Video-BLADE 논문 (Zhejiang University, 2025)

실제 사용 사례 #

콘텐츠 제작 스튜디오: 도쿄 기반 애니메이션 스튜디오는 CogVideoX-5B-I2V를 사용하여 컨셉 아트에 애니메이션을 적용하여 스토리보드 제작 시간을 60% 단축합니다.

전자상거래 제품 데모: 가구 소매업체는 CogVideoX1.5-5B-I2V를 사용하여 단일 제품 사진에서 쇼케이스 비디오를 생성합니다. 모델은 1360 x 768 해상도에서 부드러운 침era 궤도와 자연스러운 조명 전환을 생성합니다.

교육 콘텐츠: MOOC 플랫폼은 텍스트 설명에서 물리 실험 데모 비디오를 자동 생성합니다.

소셜 미디어 마케팅: 마케팅 팀은 프롬프트 최적화된 일괄 생성을 사용하여 16GB VRAM 공유 GPU 서버에서 A/B 테스트를 위해 매일 50개 이상의 짧은 비디오 변형을 생성합니다.

고급 사용법 / 프로덕션 강화 #

다중 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의 GPU당 메모리를 약 24GB BF16으로 줄입니다.

FastAPI를 사용한 API 서버 #

추론을 프로덕션 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

VRAM 최적화 체크리스트 #

GPU에 따라 순서대로 이 최적화를 적용합니다:

1. VAE 슬라이싱: 항상 활성화 — 큰 배치를 분할
2. VAE 타일링: 720p 이상 해상도에서 활성화
3. 순차 CPU 오프로드: VRAM < 12GB에서 사용
4. 모델 CPU 오프로드: VRAM 12-16GB에서 사용
5. INT8 양자화: TorchAO로 7-10GB VRAM 목표
6. FP32 대신 BF16: 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', '최대 VRAM 사용량')

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 모델, 품질 모델 중 최소 VRAM이 필요할 때 선택합니다. CogVideoX1.5-5B-I2V는 4GB GPU에서 실행됩니다.

Wan 2.1을 선택할 때: 중국어/영어 다국어 워크플로우와 16GB+ VRAM이 있을 때 더 나은 선택입니다.

HunyuanVideo를 선택할 때: VBench-2.0에서 최고의 전체 품질과 가장 강한 인간 충실도를 제공하지만 24GB+ VRAM이 필요합니다.

Open-Sora를 선택할 때: 연구 유연성과 매우 긴 비디오 생성(최대 16초)을 위해 선택하지만 시각적 품질이 낮습니다.

한계 / 솔직한 평가 #

CogVideoX에는 커밋하기 전에 알아야 할 명확한 제약이 있습니다:

1. 느린 추론: 단일 5초 비디오가 A100에서 CogVideoX-5B로 ~1000초가 소요됩니다. Wan 2.1과 HunyuanVideo는 동등한 하드웨어에서 더 빠릅니다.

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 VRAM에서 실행됩니다. CogVideoX-5B는 10GB가 필요합니다. CogVideoX1.5-5B-I2V는 4GB에서 작동합니다. CPU 오프로드 없이 원활하게 실행하려면 16GB+ VRAM(RTX 4080/4090 또는 A100)을 목표로 하세요.

Q: 50단계 이상의 추론 속도를 높이려면 어떻게 해야 하나요?

A: CogVideoXDPMScheduler와 timestep_spacing="trailing"을 사용하고 단계를 25-30으로 줄이세요. Video-BLADE 단계 증류는 CogVideoX-5B에서 8.89배 가속을 달성합니다.

Q: 내 데이터셋에서 CogVideoX를 미세 조정할 수 있나요?

A: 네, 두 가지 경로가 있습니다. SAT 프레임워크는 전체 매개변수 및 LoRA 미세 조정을 지원합니다. Diffusers는 LoRA 미세 조정을 지원합니다. 5B 모델은 A100 GPU가 필요 — 2B 모델은 그래디언트 체크포인팅으로 단일 RTX 4090에서 학습할 수 있습니다.

Q: CogVideoX-5B와 CogVideoX1.5-5B의 차이점은 무엇인가요?

A: CogVideoX1.5-5B는 2024년 11월 업데이트로, 더 높은 해상도(1360 x 768 vs 720 x 480), 더 긴 비디오 생성(최대 10초 vs 6초), 향상된 프레임 처리를 제공합니다.

Q: CogVideoX는 Sora나 Kling과 같은 상업용 API와 어떻게 비교되나요?

A: 상업용 API는 더 쉬운 접근성과 더 높은 피크 품질을 제공합니다. CogVideoX는 비용, 프라이버시, 사용자 지정 및 재현성에서 우위를 가집니다. 대규모 배치 생성에서 자체 호스팅 CogVideoX는 일반적으로 API 과금보다 10배 저렴합니다.

Q: CogVideoX는 어떤 파일 형식을 출력하나요?

A: Diffusers 파이프라인은 PyTorch 텐서를 출력합니다. export_to_video()를 사용하여 8-16 FPS의 H.264 인코딩 MP4로 저장합니다.

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

Q: 비기술 사용자를 위한 Web UI가 있나요?

A: 네, 여러 옵션이 있습니다. 공식 Hugging Face Space는 설정 없는 온라인 추론을 제공합니다. ComfyUI와 CogVideoXWrapper 노드로 로컬 사용이 가능합니다.

결론 #

CogVideoX는 오픈소스 배포의 유연성과 함께 프로덕션급 텍스트-비디오 생성을 제공합니다. 4GB VRAM 소비자용 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로 모니터링합니다.

매일 AI 소스 코드 업데이트를 위한 Telegram 그룹 참여: @dibi8source

추천 호스팅 및 인프라 #

위 도구들을 프로덕션에 배포하려면 안정적인 인프라가 필요합니다. dibi8가 직접 사용 중인 두 가지 옵션:

• DigitalOcean — 60일 $200 무료 크레딧, 14개 이상 글로벌 리전. 오픈소스 AI 도구의 기본 선택.
• HTStack — 홍콩 VPS, 중국 본토 저지연 접속. dibi8.com 호스팅 중인 검증된 IDC.

제휴 링크 — 추가 비용 없이 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