PixArt-Σ 설치 및 사용 가이드 (Mac)

개요

이 가이드는 Apple Silicon Mac(M1/M2/M3/M4 시리즈)에서 PixArt-Σ를 HuggingFace diffusers 라이브러리를 통해 설치하고 이미지를 생성하는 방법을 설명한다. PyTorch의 MPS(Metal Performance Shaders) 백엔드를 활용하여 Mac의 GPU를 사용하므로 CPU 대비 훨씬 빠른 속도로 실행할 수 있다.

사전 요구사항

• macOS: 12.3 Ventura 이상 (MPS 지원)
• 하드웨어: Apple Silicon (M1 이상) — Intel Mac은 MPS 미지원, CPU로만 실행 가능
• RAM: 최소 16GB 권장 (1024px 기준), 4K 생성 시 32GB 이상 권장
• Python: 3.9 이상
• 디스크 공간: 모델 다운로드에 약 20GB 여유 공간 필요 (T5 텍스트 인코더 + 트랜스포머 + VAE)

설치 방법 (diffusers)

1. 가상 환경 생성

python3 -m venv pixart-env
source pixart-env/bin/activate

2. PyTorch 및 diffusers 설치

Apple Silicon에서 MPS를 사용하려면 PyTorch 2.0 이상이 필요하다.

# PyTorch 설치 (MPS 지원 포함, macOS 기본)
pip install torch torchvision

# diffusers 및 필수 라이브러리 설치
pip install diffusers transformers accelerate

# 선택 사항: 캡션 정제 기능 사용 시
pip install beautifulsoup4 ftfy

최신 diffusers를 사용하려면 GitHub에서 직접 설치할 수 있다.

pip install git+https://github.com/huggingface/diffusers

3. 설치 확인

import torch
import diffusers

print(f"PyTorch 버전: {torch.__version__}")
print(f"MPS 사용 가능: {torch.backends.mps.is_available()}")
print(f"diffusers 버전: {diffusers.__version__}")

MPS 사용 가능: True가 출력되면 정상이다.

Apple Silicon MPS 설정

MPS 디바이스를 설정하는 기본 패턴은 다음과 같다.

import torch

# MPS 사용 가능 여부 확인 후 디바이스 선택
if torch.backends.mps.is_available():
    device = "mps"
elif torch.cuda.is_available():
    device = "cuda"
else:
    device = "cpu"

print(f"사용 디바이스: {device}")

주의: MPS에서는 torch.float16 대신 torch.float32를 사용하는 것이 안정적이다. float16은 일부 연산에서 오류가 발생할 수 있다.

기본 이미지 생성

import torch
from diffusers import PixArtSigmaPipeline

# 파이프라인 로드 (최초 실행 시 모델 자동 다운로드, 약 20GB)
pipe = PixArtSigmaPipeline.from_pretrained(
    "PixArt-alpha/PixArt-Sigma-XL-2-1024-MS",
    torch_dtype=torch.float32,  # MPS에서는 float32 권장
)
pipe = pipe.to("mps")

# 이미지 생성
prompt = "A majestic mountain landscape at sunset, ultra detailed, 4K"
image = pipe(prompt).images[0]

# 저장
image.save("output.png")
print("이미지 저장 완료: output.png")

해상도 설정

PixArt-Σ는 다양한 해상도와 종횡비를 지원한다. use_resolution_binning=True(기본값)를 사용하면 요청한 해상도에 가장 가까운 최적 해상도로 자동 조정된다.

# 정사각형 1024px
image = pipe(prompt, height=1024, width=1024).images[0]

# 세로형 (포트레이트)
image = pipe(prompt, height=1280, width=768).images[0]

# 가로형 (랜드스케이프)
image = pipe(prompt, height=768, width=1280).images[0]

# 2K 해상도 (RAM 여유 시)
image = pipe(prompt, height=2048, width=2048).images[0]

추론 단계(num_inference_steps)와 가이던스 스케일(guidance_scale)로 품질과 속도를 조절할 수 있다.

image = pipe(
    prompt,
    height=1024,
    width=1024,
    num_inference_steps=20,   # 기본값 20, 높을수록 품질↑ 속도↓
    guidance_scale=4.5,        # 기본값 4.5, 높을수록 프롬프트 충실도↑
    negative_prompt="blurry, low quality, distorted",
).images[0]

메모리 최적화

Mac의 통합 메모리(Unified Memory)는 CPU와 GPU가 공유하므로 메모리 관리가 중요하다.

Attention Slicing (권장)

범용 메모리가 없는 환경에서 약 20% 성능 향상. 64GB 미만 Mac에서는 활성화를 권장한다.

pipe.enable_attention_slicing()

CPU Offloading

메모리가 부족할 때 모델 일부를 CPU로 오프로드한다.

pipe.enable_model_cpu_offload()
# pipe.to("mps") 대신 사용 — 자동으로 필요한 시점에 GPU로 이동

순차적 CPU Offloading (최소 메모리)

더 적극적인 오프로딩으로 메모리 사용량을 최소화한다.

pipe.enable_sequential_cpu_offload()

16GB RAM 환경의 권장 설정

import torch
from diffusers import PixArtSigmaPipeline

pipe = PixArtSigmaPipeline.from_pretrained(
    "PixArt-alpha/PixArt-Sigma-XL-2-1024-MS",
    torch_dtype=torch.float32,
)
pipe.enable_attention_slicing()
pipe.enable_model_cpu_offload()

image = pipe(
    "A serene Japanese garden with cherry blossoms",
    height=1024,
    width=1024,
    num_inference_steps=20,
).images[0]
image.save("garden.png")

자주 발생하는 오류 해결

오류 1: MPS 디바이스에서 float16 관련 오류

RuntimeError: MPS does not support float16 for this operation

해결: torch_dtype=torch.float32로 변경한다.

pipe = PixArtSigmaPipeline.from_pretrained(
    "PixArt-alpha/PixArt-Sigma-XL-2-1024-MS",
    torch_dtype=torch.float32,  # float16 → float32
)

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

RuntimeError: MPS backend out of memory

해결: 다음을 순서대로 시도한다.

# 1. Attention Slicing 활성화
pipe.enable_attention_slicing()

# 2. CPU Offloading 활성화
pipe.enable_model_cpu_offload()

# 3. 해상도 낮추기
image = pipe(prompt, height=512, width=512).images[0]

# 4. 파이썬 가비지 컬렉션 실행
import gc
gc.collect()
torch.mps.empty_cache()

오류 3: 모델 다운로드 실패

OSError: We couldn't connect to 'https://huggingface.co'

해결: HuggingFace 접속이 원활하지 않은 경우 미러를 사용하거나, 토큰 인증이 필요한지 확인한다.

huggingface-cli login

오류 4: accelerate 관련 경고

UserWarning: `enable_model_cpu_offload` requires accelerate

해결:

pip install accelerate

오류 5: T5 인코더 로드 속도 느림

T5 텍스트 인코더는 약 10GB로 크기가 크다. 최초 로드 시 시간이 걸리는 것은 정상이다. 반복 실행 시에는 캐시된 모델을 사용하므로 빠르게 로드된다. 모델 캐시 위치는 ~/.cache/huggingface/hub/이다.

참고 링크

• PixArt-Σ 소개 — 이 위키의 소개 페이지
• GitHub — PixArt-alpha/PixArt-sigma
• HuggingFace diffusers — PixArtSigmaPipeline API 문서
• HuggingFace — MPS (Metal Performance Shaders) 최적화 가이드
• HuggingFace — PixArt-alpha/PixArt-Sigma-XL-2-1024-MS 모델
• arXiv 논문 — 2403.04692