CogVideoX 설치 및 사용 가이드 (Mac)

개요

이 가이드는 Apple Silicon(M1/M2/M3/M4) Mac에서 CogVideoX 영상 생성 모델을 설치하고 사용하는 방법을 설명한다. Mac의 GPU는 PyTorch의 MPS(Metal Performance Shaders) 백엔드를 통해 가속된다. HuggingFace diffusers 라이브러리를 기반으로 하며, 별도의 CUDA GPU 없이도 Apple Silicon의 통합 메모리를 활용해 영상을 생성할 수 있다.

주의: 안정적인 실행을 위해 64GB 통합 메모리 이상을 권장한다. 32GB에서는 메모리 부족으로 생성이 실패하거나 매우 느릴 수 있다.

사전 요구사항

항목	최소 요구사항	권장 사항
칩	Apple M1	M3 Pro / M4 Pro 이상
통합 메모리	32GB	64GB 이상
저장 공간	30GB 이상	50GB 이상
macOS	macOS 13 Ventura 이상	macOS 14 Sonoma 이상
Python	3.10 이상	3.11
PyTorch	2.1 이상 (MPS 지원)	최신 안정 버전

설치 방법

1단계: Python 가상 환경 생성

1# Python 3.11 기준 (pyenv 또는 conda 사용 권장)2python3 -m venv cogvideox-env3source cogvideox-env/bin/activate

2단계: PyTorch 설치 (MPS 지원 버전)

Apple Silicon에서 MPS 가속을 사용하려면 PyTorch 2.1 이상이 필요하다. pip를 통해 최신 버전을 설치한다.

1pip install --upgrade pip2pip install torch torchvision torchaudio

설치 후 MPS 사용 가능 여부를 확인한다.

1import torch2print(torch.backends.mps.is_available())   # True 여야 함3print(torch.backends.mps.is_built())       # True 여야 함

3단계: diffusers 및 의존 패키지 설치

1pip install diffusers transformers accelerate imageio imageio-ffmpeg

4단계: 모델 다운로드 (선택 사항 — 자동 캐시)

diffusers는 처음 실행 시 모델을 자동으로 다운로드하여 ~/.cache/huggingface/에 캐시한다. 미리 다운로드하려면 아래를 사용한다.

1# CogVideoX-2B (약 9GB, Apache 2.0)2huggingface-cli download THUDM/CogVideoX-2b3 4# CogVideoX-5B (약 20GB, 비상업적 라이선스)5huggingface-cli download THUDM/CogVideoX-5b

Apple Silicon MPS 설정

Mac에서 CogVideoX를 실행할 때는 다음 두 가지 환경 변수를 반드시 설정해야 한다.

1# MPS 미지원 연산을 CPU로 자동 폴백2export PYTORCH_ENABLE_MPS_FALLBACK=13 4# MPS 메모리 제한 해제 (통합 메모리를 최대한 활용)5export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0

Python 코드 내에서 설정하는 경우:

1import os2os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"3os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"

torch.autocast MPS 호환성 패치

PyTorch의 torch.autocast()는 MPS 디바이스를 지원하지 않아 RuntimeError가 발생할 수 있다. 직접 파이프라인을 수정하는 경우 아래와 같이 처리한다.

1from contextlib import nullcontext2import torch3 4device = "mps"5# MPS는 autocast 미지원 → nullcontext로 대체6autocast_ctx = nullcontext() if device == "mps" else torch.autocast(device)7 8with autocast_ctx:9    output = pipeline(...)

T2V (텍스트→영상) 기본 사용법

CogVideoX-2B (경량, Apache 2.0)

1import os2os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"3os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"4 5import torch6from diffusers import CogVideoXPipeline7from diffusers.utils import export_to_video8 9pipe = CogVideoXPipeline.from_pretrained(10    "THUDM/CogVideoX-2b",11    torch_dtype=torch.float16,12)13pipe.to("mps")14 15# 메모리 최적화 활성화16pipe.enable_model_cpu_offload()17pipe.enable_vae_slicing()18pipe.enable_vae_tiling()19 20prompt = (21    "A serene mountain lake at sunrise. "22    "The calm water reflects the golden light and surrounding pine trees. "23    "A gentle mist rises from the surface as birds begin to chirp."24)25 26video = pipe(27    prompt=prompt,28    num_frames=25,          # Mac 권장: 25~30프레임29    height=480,30    width=720,31    num_inference_steps=20, # Mac 권장: 20~30스텝32    guidance_scale=6.0,33).frames[0]34 35export_to_video(video, "output_t2v.mp4", fps=8)36print("영상 생성 완료: output_t2v.mp4")

CogVideoX-5B (고품질, 64GB RAM 권장)

1import os2os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"3os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"4 5import torch6from diffusers import CogVideoXPipeline7from diffusers.utils import export_to_video8 9pipe = CogVideoXPipeline.from_pretrained(10    "THUDM/CogVideoX-5b",11    torch_dtype=torch.bfloat16,12)13pipe.to("mps")14pipe.enable_model_cpu_offload()15pipe.enable_vae_slicing()16pipe.enable_vae_tiling()17 18prompt = "A futuristic cityscape at night, neon lights reflecting on wet streets."19 20video = pipe(21    prompt=prompt,22    num_frames=25,23    height=480,24    width=720,25    num_inference_steps=20,26    guidance_scale=6.0,27).frames[0]28 29export_to_video(video, "output_5b.mp4", fps=8)

I2V (이미지→영상) 사용법

이미지를 입력으로 받아 동적인 영상을 생성하는 기능이다. CogVideoXImageToVideoPipeline을 사용하며, 5B-I2V 체크포인트가 필요하다.

1import os2os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"3os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"4 5import torch6from diffusers import CogVideoXImageToVideoPipeline7from diffusers.utils import export_to_video, load_image8 9pipe = CogVideoXImageToVideoPipeline.from_pretrained(10    "THUDM/CogVideoX-5b-I2V",11    torch_dtype=torch.bfloat16,12)13pipe.to("mps")14pipe.enable_model_cpu_offload()15pipe.enable_vae_slicing()16pipe.enable_vae_tiling()17 18# 입력 이미지 로드 (로컬 파일 또는 URL)19image = load_image("input.png")20 21prompt = "The person in the image slowly turns their head and smiles at the camera."22 23video = pipe(24    image=image,25    prompt=prompt,26    num_frames=25,27    height=480,28    width=720,29    num_inference_steps=20,30    guidance_scale=6.0,31).frames[0]32 33export_to_video(video, "output_i2v.mp4", fps=8)34print("I2V 영상 생성 완료: output_i2v.mp4")

이미지 크기 주의: 입력 이미지의 가로 크기는 768~1360px, 세로는 758px이어야 하며, 가로·세로 모두 16의 배수여야 한다. load_image를 사용하면 자동으로 처리된다.

파라미터 조절 가이드

파라미터	설명	Mac 권장값
`num_frames`	생성할 프레임 수	25~30 (최대 30 권장)
`num_inference_steps`	디노이징 스텝 수. 높을수록 품질 향상, 속도 저하	20~30
`guidance_scale`	프롬프트 준수 강도. 높을수록 프롬프트에 충실	6.0~6.5
`height` / `width`	출력 해상도 (16의 배수)	480 × 720 또는 384 × 512
`fps` (export)	영상 재생 속도	8 (2B) / 16 (5B)

생성 시간 예상 (M4 Pro, 64GB): 25프레임, 20스텝 기준 약 15~25분 소요.

메모리 최적화

메모리가 부족한 환경에서는 아래 최적화 옵션을 조합해서 사용한다.

1# 모델 컴포넌트를 추론 시에만 GPU로 이동 (가장 권장)2pipe.enable_model_cpu_offload()3 4# VAE를 슬라이스 단위로 처리 (프레임 수가 많을 때 유효)5pipe.enable_vae_slicing()6 7# VAE를 타일 단위로 처리 (고해상도 시 유효)8pipe.enable_vae_tiling()9 10# 더 적극적인 오프로딩 (속도가 매우 느려지지만 메모리 절약)11pipe.enable_sequential_cpu_offload()

최적화 설정	VRAM 사용량 (5B 기준)	비고
최적화 없음	~33GB	Mac 통합 메모리에서 불가
`enable_model_cpu_offload`	~19GB	권장 기본 설정
+ `enable_vae_tiling`	~11GB	메모리 여유 확보
`enable_sequential_cpu_offload`	~4GB	속도 매우 느림

자주 발생하는 오류 해결

1. `RuntimeError: MPS does not support autocast`

RuntimeError: MPS backend does not support autocast

원인: PyTorch의 torch.autocast()가 MPS를 지원하지 않음.
해결: PYTORCH_ENABLE_MPS_FALLBACK=1 환경 변수를 설정하고 실행한다.

1PYTORCH_ENABLE_MPS_FALLBACK=1 python generate.py

2. 생성된 영상이 흰 화면(white screen)으로 출력됨

원인: 프레임 수 또는 해상도가 너무 높아 VAE 디코딩 중 메모리 초과.
해결:

num_frames를 30 이하로 줄인다.
enable_vae_tiling()을 활성화한다.
해상도를 512×384로 낮춘다.

3. `OutOfMemoryError` 또는 커널 재시작

원인: 통합 메모리 부족.
해결:

다른 애플리케이션을 모두 종료한다.
enable_model_cpu_offload() 및 enable_vae_slicing() 활성화.
num_frames를 20~25로 줄이고, height=384, width=512로 설정한다.
CogVideoX-2B 모델로 전환한다.

4. `ModuleNotFoundError: No module named 'imageio_ffmpeg'`

1pip install imageio[ffmpeg]2# 또는3pip install imageio-ffmpeg

5. 추론 속도가 매우 느림

원인: MPS 폴백으로 일부 연산이 CPU에서 실행됨.
해결: PyTorch 버전을 최신으로 업그레이드하면 MPS 지원 범위가 늘어나 속도가 개선될 수 있다.

1pip install --upgrade torch torchvision torchaudio

참고 링크

THUDM/CogVideo GitHub — 공식 소스코드 및 문서
HuggingFace diffusers — CogVideoX API — 파이프라인 API 레퍼런스
HuggingFace MPS 최적화 가이드 — Apple Silicon MPS 설정 상세
CogVideoX-Mac-Setup (커뮤니티) — Mac M4 Pro 실행 사례 및 패치
THUDM/CogVideoX-2b — 2B 모델 HuggingFace 페이지
THUDM/CogVideoX-5b — 5B 모델 HuggingFace 페이지
THUDM/CogVideoX-5b-I2V — 5B I2V 모델 HuggingFace 페이지

개요

사전 요구사항

설치 방법

1단계: Python 가상 환경 생성

2단계: PyTorch 설치 (MPS 지원 버전)

3단계: diffusers 및 의존 패키지 설치

4단계: 모델 다운로드 (선택 사항 — 자동 캐시)

Apple Silicon MPS 설정

torch.autocast MPS 호환성 패치

T2V (텍스트→영상) 기본 사용법

CogVideoX-2B (경량, Apache 2.0)

CogVideoX-5B (고품질, 64GB RAM 권장)

I2V (이미지→영상) 사용법

파라미터 조절 가이드

메모리 최적화

자주 발생하는 오류 해결

1. `RuntimeError: MPS does not support autocast`

2. 생성된 영상이 흰 화면(white screen)으로 출력됨

3. `OutOfMemoryError` 또는 커널 재시작

4. `ModuleNotFoundError: No module named 'imageio_ffmpeg'`

5. 추론 속도가 매우 느림

참고 링크

관련 페이지

댓글

CogVideoX 설치 및 사용 가이드 (Mac)

개요

사전 요구사항

설치 방법

1단계: Python 가상 환경 생성

2단계: PyTorch 설치 (MPS 지원 버전)

3단계: diffusers 및 의존 패키지 설치

4단계: 모델 다운로드 (선택 사항 — 자동 캐시)

Apple Silicon MPS 설정

torch.autocast MPS 호환성 패치

T2V (텍스트→영상) 기본 사용법

CogVideoX-2B (경량, Apache 2.0)

CogVideoX-5B (고품질, 64GB RAM 권장)

I2V (이미지→영상) 사용법

파라미터 조절 가이드

메모리 최적화

자주 발생하는 오류 해결

1. RuntimeError: MPS does not support autocast

2. 생성된 영상이 흰 화면(white screen)으로 출력됨

3. OutOfMemoryError 또는 커널 재시작

4. ModuleNotFoundError: No module named 'imageio_ffmpeg'

5. 추론 속도가 매우 느림

참고 링크

관련 페이지

댓글

1. `RuntimeError: MPS does not support autocast`

3. `OutOfMemoryError` 또는 커널 재시작

4. `ModuleNotFoundError: No module named 'imageio_ffmpeg'`