Open-Sora 설치 및 사용 가이드 (Mac)

개요

이 가이드는 Apple Silicon(M1/M2/M3/M4) Mac에서 Open-Sora를 설치하고 실행하는 방법을 설명한다. Open-Sora는 기본적으로 NVIDIA CUDA GPU를 대상으로 설계되었으나, Apple Silicon Mac에서도 CPU 추론 또는 MPS(Metal Performance Shaders) 백엔드를 활용해 실행할 수 있다. 다만 CUDA 환경 대비 속도가 느리고 일부 제약이 있으므로, 이 점을 감안하고 사용해야 한다.

사전 요구사항

시스템 요구사항

항목	최소 사양	권장 사양
칩셋	Apple M1	Apple M2 Pro 이상
RAM	16GB	32GB 이상
저장 공간	30GB 이상	50GB 이상
macOS	Ventura 13.0 이상	Sonoma 14.0 이상

필수 소프트웨어

Python 3.10 (정확히 3.10 버전 필요)
Conda (Miniforge 또는 Miniconda 권장, Apple Silicon 네이티브 빌드)
Git
Homebrew (패키지 관리 보조)

Miniforge 설치 (미설치 시)

Apple Silicon용 네이티브 conda 환경을 위해 Miniforge를 권장한다.

1brew install miniforge2conda init zsh3source ~/.zshrc

설치 방법

1. conda 가상환경 생성

1conda create -n opensora python=3.102conda activate opensora

2. 저장소 클론

1git clone https://github.com/hpcaitech/Open-Sora2cd Open-Sora

3. PyTorch 설치 (Apple Silicon용)

Mac에서는 CUDA 버전이 아닌 CPU/MPS 지원 PyTorch를 먼저 설치해야 한다.

1pip install torch>=2.4.0 torchvision torchaudio

주의: pip install torch 만 실행하면 자동으로 Apple Silicon 호환 버전이 설치된다. CUDA 전용 인덱스 URL(--index-url https://download.pytorch.org/whl/cu121)은 사용하지 않는다.

4. Open-Sora 코어 패키지 설치

1pip install -v .

5. CUDA 전용 패키지 제외 처리

xformers와 flash-attn은 CUDA 전용 패키지이므로 Mac에서는 설치하지 않는다. 대신 PyTorch 기본 어텐션 구현을 사용한다.

1# xformers, flash-attn은 설치하지 않음2# 아래 명령어로 의존성 충돌 여부 확인3pip check

Apple Silicon 실행 환경 설정

MPS 사용 가능 여부 확인

Python 인터프리터에서 MPS 백엔드가 활성화되어 있는지 확인한다.

1import torch2 3print("MPS 사용 가능:", torch.backends.mps.is_available())4print("MPS 빌드 포함:", torch.backends.mps.is_built())5 6# MPS 사용 시7device = torch.device("mps") if torch.backends.mps.is_available() else torch.device("cpu")8print("사용할 디바이스:", device)

환경 변수 설정

메모리 효율과 안정성을 위해 다음 환경 변수를 설정한다.

1# MPS 메모리 파편화 방지2export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.03 4# 연산 오류 발생 시 CPU 폴백 허용5export PYTORCH_ENABLE_MPS_FALLBACK=1

이를 .zshrc에 영구 등록하려면 아래 명령어를 사용한다.

1echo 'export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0' >> ~/.zshrc2echo 'export PYTORCH_ENABLE_MPS_FALLBACK=1' >> ~/.zshrc3source ~/.zshrc

모델 다운로드

Hugging Face CLI를 사용해 모델 가중치를 다운로드한다.

1pip install huggingface_hub2huggingface-cli download hpcai-tech/Open-Sora-v2 --local-dir ./ckpts

참고: 모델 크기가 크므로(수십 GB) 안정적인 네트워크 환경에서 다운로드하는 것을 권장한다. 다운로드가 중단된 경우 동일 명령어를 재실행하면 이어받기가 가능하다.

기본 T2V(텍스트-투-비디오) 사용법

256px 해상도 텍스트-투-비디오 생성

Mac에서는 단일 프로세스로 실행한다. torchrun 대신 python을 사용하거나, --nproc_per_node 1로 단일 노드 실행을 명시한다.

1torchrun --nproc_per_node 1 --standalone scripts/diffusion/inference.py \2  configs/diffusion/inference/t2i2v_256px.py \3  --save-dir samples \4  --prompt "a cat walking in the rain, cinematic"

이미지-투-비디오(I2V) 생성

1torchrun --nproc_per_node 1 --standalone scripts/diffusion/inference.py \2  configs/diffusion/inference/256px.py \3  --cond_type i2v_head \4  --prompt "a serene lake at sunset" \5  --ref assets/texts/i2v.png \6  --save-dir samples

여러 프롬프트 배치 처리

CSV 파일을 사용해 여러 프롬프트를 한 번에 처리할 수 있다.

1torchrun --nproc_per_node 1 --standalone scripts/diffusion/inference.py \2  configs/diffusion/inference/t2i2v_256px.py \3  --save-dir samples \4  --prompt-path assets/texts/t2v_prompts.csv

해상도 및 길이 설정

종횡비(Aspect Ratio) 설정

1# 16:9 가로 비율 (기본 유튜브 형식)2--aspect_ratio 16:93 4# 9:16 세로 비율 (숏폼 영상)5--aspect_ratio 9:166 7# 1:1 정방형8--aspect_ratio 1:19 10# 시네마틱 와이드스크린11--aspect_ratio 2.39:1

프레임 수(영상 길이) 설정

--num_frames 값은 반드시 4k + 1 형식(1, 5, 9, 17, 33, 65, 129 등)이어야 한다.

1# 약 1초 (25fps 기준)2--num_frames 253 4# 약 4초5--num_frames 976 7# 최대 약 16초8--num_frames 129

모션 강도 설정

1# 정적인 영상 (1~3)2--motion-score 23 4# 기본값5--motion-score 46 7# 역동적인 영상 (5~7)8--motion-score 69 10# 자동 조정11--motion-score dynamic

메모리 최적화

Mac에서 메모리 부족 문제가 발생하는 경우 다음 옵션을 사용한다.

CPU 오프로드 활성화

모델 일부를 RAM으로 오프로드하여 GPU(통합 메모리) 사용량을 줄인다.

1torchrun --nproc_per_node 1 --standalone scripts/diffusion/inference.py \2  configs/diffusion/inference/t2i2v_256px.py \3  --save-dir samples \4  --prompt "sunset over mountains" \5  --offload True

낮은 해상도로 시작하기

메모리가 제한적인 경우 256px 설정으로 시작해 점진적으로 해상도를 높이는 것을 권장한다.

1# 256px 설정 파일 사용 (메모리 최소화)2configs/diffusion/inference/t2i2v_256px.py

시드 고정으로 재현성 확보

1--seed 42

자주 발생하는 오류 해결

오류 1: `xformers` 또는 `flash-attn` 관련 ImportError

ImportError: No module named 'xformers'

원인: Mac에서 xformers는 CUDA 전용이라 설치되지 않는다.

해결: Open-Sora의 설정 파일에서 xformers를 비활성화하거나, 환경 변수로 우회한다.

1export USE_XFORMERS=0

또는 설정 파일(configs/diffusion/inference/*.py)에서 enable_flash_attn = False로 변경한다.

오류 2: MPS 관련 연산 미지원 오류

NotImplementedError: The operator 'aten::...' is not currently supported on the MPS backend.

원인: 일부 PyTorch 연산이 MPS에서 아직 구현되지 않았다.

해결: PYTORCH_ENABLE_MPS_FALLBACK=1 환경 변수를 설정하면 미지원 연산이 자동으로 CPU로 폴백된다.

1PYTORCH_ENABLE_MPS_FALLBACK=1 torchrun --nproc_per_node 1 --standalone \2  scripts/diffusion/inference.py configs/diffusion/inference/t2i2v_256px.py \3  --save-dir samples --prompt "your prompt" --offload True

오류 3: 메모리 부족 (OOM)

RuntimeError: MPS backend out of memory

원인: 통합 메모리 용량이 부족하다.

해결 방법:

--offload True 플래그 추가
더 낮은 해상도 설정 파일 사용 (256px 권장)
다른 메모리 집약적 앱을 종료
PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0 환경 변수 설정

오류 4: `conda activate` 후 pip이 시스템 Python을 사용

1which python  # /usr/bin/python3 이 나오면 문제

해결: conda 환경이 제대로 활성화되었는지 확인한다.

1conda activate opensora2which python  # ~/miniforge3/envs/opensora/bin/python 이어야 함

오류 5: `torchrun`을 찾을 수 없음

zsh: command not found: torchrun

해결: conda 환경이 활성화된 상태에서 torchrun 경로를 확인한다.

1conda activate opensora2which torchrun3# 없다면 직접 실행:4python -m torch.distributed.run --nproc_per_node 1 --standalone \5  scripts/diffusion/inference.py configs/diffusion/inference/t2i2v_256px.py \6  --save-dir samples --prompt "your prompt"

참고 링크

GitHub 공식 저장소: hpcaitech/Open-Sora
Hugging Face 모델: hpcai-tech/Open-Sora-v2
Open-Sora 2.0 논문: arXiv:2503.09642
PyTorch MPS 문서: PyTorch Apple Silicon 지원
Hugging Face Diffusers MPS 가이드: MPS 최적화
Open-Sora 소개 페이지: Open-Sora 소개

개요