Skip to content

GPU_COMPATIBILITY.md

Latest commit

 

History

History
153 lines (108 loc) · 8.78 KB

GPU_COMPATIBILITY.md

File metadata and controls

153 lines (108 loc) · 8.78 KB

GPU 호환성 가이드

ACE-Step 1.5는 GPU의 사용 가능한 VRAM에 자동으로 적응하여 생성 제한, LM 모델 가용성, 오프로드 전략 및 UI 기본 설정을 적절히 조정합니다. 시스템은 시작 시 GPU 메모리를 감지하고 최적의 설정을 구성합니다.

GPU 티어 구성

VRAM 티어 LM 모델 추천 LM 백엔드 최대 길이 (LM 사용 / 미사용) 최대 배치 (LM 사용 / 미사용) 오프로드 양자화
≤4GB 티어 1 없음 — pt 4분 / 6분 1 / 1 CPU + DiT INT8
4-6GB 티어 2 없음 — pt 8분 / 10분 1 / 1 CPU + DiT INT8
6-8GB 티어 3 0.6B 0.6B pt 8분 / 10분 1 / 2 CPU + DiT INT8
8-12GB 티어 4 0.6B 0.6B vllm 8분 / 10분 2 / 4 CPU + DiT INT8
12-16GB 티어 5 0.6B, 1.7B 1.7B vllm 8분 / 10분 2 / 4 CPU INT8
16-20GB 티어 6a 0.6B, 1.7B 1.7B vllm 8분 / 10분 4 / 8 CPU INT8
20-24GB 티어 6b 0.6B, 1.7B, 4B 1.7B vllm 8분 / 8분 4 / 8 없음 없음
≥24GB 제한 없음 전체 (0.6B, 1.7B, 4B) 4B vllm 10분 / 10분 8 / 8 없음 없음

열 설명

  • LM 모델: 해당 티어에서 로드할 수 있는 5Hz 언어 모델 크기
  • 추천 LM: UI에서 해당 티어에 기본 선택되는 LM 모델
  • 백엔드: LM 추론 백엔드 (vllm은 충분한 VRAM을 가진 NVIDIA GPU용, pt는 PyTorch 대체, mlx는 Apple Silicon용)
  • 오프로드:
    • CPU + DiT: 모든 모델(DiT, VAE, 텍스트 인코더)을 미사용 시 CPU로 오프로드; DiT도 단계 간 오프로드
    • CPU: VAE와 텍스트 인코더를 CPU로 오프로드; DiT는 GPU에 유지
    • 없음: 모든 모델을 GPU에 유지
  • 양자화: VRAM 사용량을 줄이기 위해 기본적으로 INT8 가중치 양자화를 활성화할지 여부

적응형 UI 기본 설정

Gradio UI는 감지된 GPU 티어에 따라 자동으로 설정됩니다:

  • LM 초기화 체크박스: LM을 지원하는 티어(티어 3+)에서 기본 체크, 티어 1-2에서는 체크 해제 및 비활성화
  • LM 모델 경로: 티어의 추천 모델이 자동 입력; 드롭다운에는 호환 모델만 표시
  • 백엔드 드롭다운: 티어 1-3에서는 pt/mlx로 제한(vllm KV 캐시가 메모리를 과도하게 사용); 티어 4+에서는 모든 백엔드 사용 가능
  • CPU 오프로드 / DiT 오프로드: 낮은 티어에서 기본 활성화, 높은 티어에서 비활성화
  • 양자화: 티어 1-6a에서 기본 활성화, 티어 6b+에서 비활성화(충분한 VRAM)
  • 모델 컴파일: 모든 티어에서 기본 활성화(양자화에 필요)

호환되지 않는 옵션을 수동으로 선택한 경우(예: 6GB GPU에서 vllm 사용 시도), 시스템이 경고를 표시하고 호환 가능한 설정으로 자동 대체합니다.

런타임 안전 기능

  • VRAM 가드: 각 추론 전에 VRAM 요구 사항을 추정하고 필요 시 배치 크기를 자동 축소
  • 적응형 VAE 디코딩: 3단계 대체: GPU 타일 디코딩 → GPU 디코딩+CPU 오프로드 → 완전 CPU 디코딩
  • 자동 청크 크기: VAE 디코딩 청크 크기가 사용 가능한 여유 VRAM에 적응(64/128/256/512/1024/1536)
  • 길이/배치 클램핑: 티어 제한을 초과하는 값을 요청하면 경고와 함께 자동 조정

참고 사항

  • 기본 설정은 감지된 GPU 메모리에 따라 자동으로 구성됩니다
  • LM 모드는 Chain-of-Thought 생성 및 오디오 이해에 사용되는 언어 모델을 의미합니다
  • Flash Attention은 자동 감지되며 사용 가능할 때 활성화됩니다
  • 제약 디코딩: LM이 초기화되면 LM의 길이 생성도 GPU 티어의 최대 길이 제한으로 제약되어 CoT 생성 중 OOM 에러를 방지합니다
  • VRAM이 6GB 이하인 GPU(티어 1-2)의 경우, DiT 모델의 메모리 확보를 위해 LM 초기화가 기본적으로 비활성화됩니다
  • CLI 인자 또는 Gradio UI를 통해 설정을 수동으로 무시할 수 있습니다

커뮤니티 기여 환영: 위의 GPU 티어 구성은 일반적인 하드웨어에서의 테스트를 바탕으로 합니다. 사용 중인 장치의 실제 성능이 이 파라미터와 다르다면, 더 철저한 테스트를 수행하고 acestep/gpu_config.py에서 구성을 최적화하기 위한 PR을 제출해 주시기 바랍니다.

메모리 최적화 팁

  1. 초저 VRAM (≤6GB): LM 초기화 없이 DiT 전용 모드를 사용. INT8 양자화와 완전 CPU 오프로드가 필수. VAE 디코딩이 자동으로 CPU로 대체될 수 있습니다.
  2. 저 VRAM (6-8GB): pt 백엔드로 0.6B LM 모델 사용 가능. 오프로드를 활성 상태로 유지하세요.
  3. 중간 VRAM (8-16GB): 0.6B 또는 1.7B LM 모델을 사용. 티어 4+에서 vllm 백엔드가 잘 작동합니다.
  4. 높은 VRAM (16-24GB): 더 큰 LM 모델(1.7B 추천)을 활성화. 20GB+에서는 양자화가 선택 사항이 됩니다.
  5. 초고 VRAM (≥24GB): 모든 모델이 오프로드나 양자화 없이 작동. 최고 품질을 위해 4B LM을 사용하세요.

디버그 모드: 다른 GPU 구성 시뮬레이션

테스트 및 개발을 위해 MAX_CUDA_VRAM 환경 변수를 사용하여 다른 GPU 메모리 크기를 시뮬레이션할 수 있습니다:

# 4GB GPU 시뮬레이션 (티어 1)
MAX_CUDA_VRAM=4 uv run acestep

# 6GB GPU 시뮬레이션 (티어 2)
MAX_CUDA_VRAM=6 uv run acestep

# 8GB GPU 시뮬레이션 (티어 4)
MAX_CUDA_VRAM=8 uv run acestep

# 12GB GPU 시뮬레이션 (티어 5)
MAX_CUDA_VRAM=12 uv run acestep

# 16GB GPU 시뮬레이션 (티어 6a)
MAX_CUDA_VRAM=16 uv run acestep

MAX_CUDA_VRAM을 설정하면 시스템은 torch.cuda.set_per_process_memory_fraction()을 호출하여 VRAM 하드 캡을 강제하며, 고사양 GPU에서도 현실적인 시뮬레이션을 제공합니다.

자동 티어 테스트

UI에서 각 티어를 수동으로 테스트하는 대신, profile_inference.py의 tier-test 모드를 사용할 수 있습니다:

# 모든 티어 자동 테스트
python profile_inference.py --mode tier-test

# 특정 티어 테스트
python profile_inference.py --mode tier-test --tiers 6 8 16

# LM 활성화하여 테스트 (지원되는 티어에서)
python profile_inference.py --mode tier-test --tier-with-lm

# 빠른 테스트 (비양자화 티어에서 torch.compile 건너뛰기)
python profile_inference.py --mode tier-test --tier-skip-compile

프로파일링 도구의 전체 문서는 BENCHMARK.md를 참조하세요.

이는 다음과 같은 경우에 유용합니다:

  • 고사양 하드웨어에서 GPU 티어 구성 테스트
  • 각 티어에 대해 경고 및 제한이 올바르게 작동하는지 확인
  • acestep/gpu_config.py 수정 후 자동 회귀 테스트
  • CI/CD VRAM 호환성 검증

경계 테스트 (최소 티어 찾기)

--tier-boundary를 사용하면 INT8 양자화와 CPU 오프로드를 안전하게 비활성화할 수 있는 최소 VRAM 티어를 실험적으로 확인할 수 있습니다. 각 티어에 대해 최대 3가지 구성으로 테스트합니다:

  1. default — 티어의 기본 설정 (양자화 + 오프로드를 구성대로 사용)
  2. no-quant — 오프로드 설정은 유지하되 양자화 비활성화
  3. no-offload — 양자화 없음, CPU 오프로드 없음 (모든 모델을 GPU에 유지)
# 모든 티어에서 경계 테스트 실행
python profile_inference.py --mode tier-test --tier-boundary

# 특정 티어의 경계 테스트
python profile_inference.py --mode tier-test --tier-boundary --tiers 8 12 16 20 24

# LM 활성화된 경계 테스트 (지원되는 티어에서)
python profile_inference.py --mode tier-test --tier-boundary --tier-with-lm

# 결과를 JSON으로 저장
python profile_inference.py --mode tier-test --tier-boundary --benchmark-output boundary_results.json

참고: 경계 테스트 결과는 경험적이며, DiT 모델 변형 (turbo vs base), LM 활성화 여부, 생성 시간, flash attention 가용성에 따라 달라질 수 있습니다.

배치 크기 경계 테스트

--tier-batch-boundary를 사용하여 배치 크기 1, 2, 4, 8을 단계적으로 테스트하여 각 티어의 최대 안전 배치 크기를 찾습니다:

# LM 활성화 상태에서 배치 경계 테스트 실행
python profile_inference.py --mode tier-test --tier-batch-boundary --tier-with-lm

# 특정 티어 테스트
python profile_inference.py --mode tier-test --tier-batch-boundary --tier-with-lm --tiers 8 12 16 24

LM 사용/미사용 두 가지 구성을 모두 테스트하고 각 티어의 최대 성공 배치 크기를 보고합니다.