ACE-Step 1.5 Windows 11 초보자 설치·테스트 매뉴얼 (RTX 4060 노트북용)

대상: AI를 처음 접하는 사용자

목표: Windows 11에서 ACE-Step 1.5를 설치하고, 첫 곡 생성 테스트까지 완료

방식: 1안(공식 Gradio/WebUI) 기준

0) 먼저 이해하고 시작하기 (초보자용 핵심 개념)

ACE-Step 1.5가 무엇인가요?

ACE-Step 1.5는 텍스트(장르, 분위기, 가사 등)를 입력하면 음악을 생성해주는 오픈소스 AI 모델입니다.

Gradio/WebUI가 무엇인가요?

  • WebUI: 웹 브라우저에서 조작하는 화면(버튼, 입력칸)
  • Gradio: 파이썬 프로그램을 웹 화면으로 쉽게 띄워주는 도구

즉, 설치 후에는 코드를 계속 만지는 것이 아니라, 브라우저 UI에서 생성 버튼을 눌러 사용하게 됩니다.

왜 가상환경(venv/conda)을 쓰나요?

AI 설치는 라이브러리(패키지) 버전 충돌이 자주 납니다.

  • 가상환경 = 이 프로젝트 전용 독립 상자
  • 장점: 다른 프로젝트를 망치지 않고, 문제 발생 시 재설치가 쉽습니다.

RTX 4060 노트북에 맞춘 핵심 전략

RTX 4060 노트북은 보통 VRAM 8GB이므로 다음이 중요합니다.

  1. 처음엔 짧은 길이/낮은 스텝으로 테스트
  2. 필요하면 CPU 오프로딩 옵션 사용
  3. 배치 크기(동시 생성량) 1 유지

1) 준비물 체크리스트

아래 5가지를 먼저 설치합니다.

  1. Windows 11 최신 업데이트
  2. NVIDIA 드라이버 최신 버전 (Game Ready 또는 Studio)
  3. Git for Windows
  4. Python 3.10.x (권장)
  5. **FFMpeg full-shared 버전 설치 :ffmpeg-release-full-shared.zip **
    : https://www.gyan.dev/ffmpeg/builds/
  6. Visual C++ Redistributable (런타임 오류 예방)

팁: Python은 3.11/3.12에서도 동작할 수 있으나, 초보자는 호환성이 좋은 3.10을 권장합니다.

2) 설치 전 사전 점검 (아주 중요)

2-1. PowerShell 열기

  • 시작 메뉴 → PowerShell 검색 → 실행

2-2. Git 확인

git --version

정상 예시: git version 2.xx.x

2-3. Python 확인

python --version

정상 예시: Python 3.10.x

2-4. NVIDIA GPU 확인

nvidia-smi

정상이라면 GPU 정보와 드라이버 버전이 표시됩니다.

만약 nvidia-smi가 안 되면 드라이버부터 다시 설치하세요.

3) 프로젝트 폴더 만들기

아래는 예시 경로입니다.

cd $HOME
mkdir ai-music -ErrorAction SilentlyContinue
cd ai-music

4) ACE-Step 소스 받기

git clone https://github.com/ace-step/ACE-Step.git
cd ACE-Step

5) 가상환경 만들기 (venv 방식)

5-1. 가상환경 생성

python -m venv .venv

5-2. 가상환경 활성화

.\.venv\Scripts\Activate.ps1

활성화되면 프롬프트 앞에 (.venv)가 보입니다.

실행 정책 오류가 나면 1회성으로 아래 실행:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

그 후 다시 활성화 명령 실행

6) PyTorch(CUDA) 설치

ACE-Step README 기준으로 Windows + NVIDIA GPU 권장 명령은 아래입니다.

pip install --upgrade pip
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

용어 설명

  • PyTorch: AI 모델을 실행하는 핵심 엔진
  • CUDA: NVIDIA GPU 가속 기술
  • cu126: CUDA 12.6 계열 빌드

7) ACE-Step 설치

pip install -e .

-e 뜻

editable 설치로, 현재 폴더 코드와 연결되어 개발/수정에 유리합니다. 현재 폴더의 파이썬 프로젝트를 "개발 모드(editable mode)"로 설치하라는 뜻
현재 폴더의 파이썬 프로젝트를 개발 모드로 설치해서 수정 즉시 반영되게 해라

pip install 차이점에 대한 설명

❌ 일반 설치

pip install .

코드가 site-packages에 복사된다.
소스 코드 수정하면 → 다시 설치해야 반영됨

✅ Editable 설치

pip install -e .

소스를 복사하지 않는다.
현재 폴더를 링크해서 사용한다.
코드 수정하면 → 바로 반영된다.

👉 그래서 개발할 때 무조건 Editable 을 사용

8) (선택) Windows 최적화 패키지

공식 권장 고급 옵션(--torch_compile)을 쓸 때 Windows는 아래가 필요할 수 있습니다.

pip install triton-windows

처음에는 생략해도 됩니다. 문제가 없으면 나중에 성능 최적화 단계에서 적용하세요.

9) 첫 실행 (가장 안전한 시작 명령)

처음은 안정성 우선으로 아래처럼 실행합니다.

acestep --port 7865 --cpu_offload true --overlapped_decode true

옵션 설명 (초보자 버전)

  • --port 7865: 브라우저 접속 포트 번호
  • --cpu_offload true: VRAM 부족 시 일부를 RAM으로 넘겨 실행 안정성 확보
  • --overlapped_decode true: 디코딩 성능 개선 옵션

실행 후 터미널에 로컬 주소(예: http://127.0.0.1:7865)가 뜨면 브라우저로 열면 됩니다.

에러 발생시 가상환경 (.venv) 에서

# 설치된 gradio 및 gradio-client , gradio_client 를 삭제

pip uninstall -y gradio gradio-client gradio_client

# gradio 와 gradio-client 호환 버전을 설지 한다.
# gradio 5.50.0은 gradio-client == 1.14.0을 강제함

 pip install "gradio==5.50.0" "gradio-client==1.14.0"

10) 첫 테스트 생성 (3~5분짜리 따라하기)

UI에서 Text2Music 탭 기준으로 진행합니다.

10-1. 입력값 예시

  • Tags(태그):
    k-pop, bright, energetic, female vocal, modern pop, clean mix
  • Lyrics(가사):
[verse]
새로운 하루가 시작돼
작은 아이디어가 빛나네

[chorus]
한 걸음 더, 오늘도 가보자
우리의 리듬으로 채워가
  • Audio Duration(길이): 20~30초(처음엔 짧게)

10-2. 설정값(초보 안정 프리셋)

  • Inference Steps: 20~28
  • Guidance Scale: 기본값 또는 중간값
  • Seed: 고정값(예: 12345)으로 재현성 확보

10-3. 생성

  • Generate 클릭
  • 첫 실행은 모델 다운로드 때문에 시간이 더 걸릴 수 있음

(Wav) 파일 생성 오류 일 때

FFmpeg 버전을 확인하고 full shared 를 설치해야 함
5. **FFMpeg full-shared 버전 설치 :ffmpeg-release-full-shared.zip **
: https://www.gyan.dev/ffmpeg/builds/

11) 결과 확인과 품질 올리는 법

처음 결과가 별로일 때

  1. 태그를 구체화 (장르 + 분위기 + 악기 + 보컬 성별)
  2. 길이 짧게 유지한 채 seed만 바꿔 여러 번 시도
  3. 스텝을 20→28→35 순으로 점진 증가

품질과 속도의 트레이드오프

  • 스텝↑: 품질/안정성↑, 속도↓
  • 길이↑: 시간↑, VRAM 부담↑

RTX 4060 노트북은 짧게 탐색 후 최종 길이 확장이 효율적입니다.

12) 자주 발생하는 문제와 해결

문제 A: CUDA out of memory

원인: VRAM 부족

해결 순서

  1. 길이 20~30초로 축소
  2. 스텝 낮추기
  3. --cpu_offload true 유지
  4. 백그라운드 앱(브라우저 게임 탭 등) 종료

문제 B: ModuleNotFoundError / 패키지 오류

원인: 가상환경 미활성화 또는 설치 누락

해결

  1. (.venv) 표시 확인
  2. pip install -e . 재실행
  3. 필요시 .venv 삭제 후 다시 생성

문제 C: 실행은 되는데 브라우저 접속 불가

해결

  1. 주소를 정확히 http://127.0.0.1:7865 입력
  2. 포트 충돌 시 --port 7866으로 변경

문제 D: 너무 느림

해결

  1. 길이·스텝 줄이기
  2. 탐색 단계에서 instrumental로 먼저 테스트
  3. 필요 시 --torch_compile true + triton-windows 적용(고급)

13) 초보자를 위한 운영 루틴 (실전 권장)

  1. 짧은 20~30초 프리뷰 3개 생성
  2. 가장 좋은 결과의 seed 기록
  3. 같은 seed로 태그/가사만 미세 수정
  4. 만족하면 길이 확장

이 방식이 실패 비용을 크게 줄입니다.

14) 테스트 완료 기준 (체크리스트)

  • acestep 명령으로 UI 실행됨
  • 브라우저에서 UI 접속 성공
  • 20~30초 곡 1개 이상 생성 성공
  • 생성 파일 재생 확인
  • 프롬프트/seed/설정값 기록 완료

15) 완전 초보용 한 줄 요약

  • 설치 핵심은 Python 가상환경 + CUDA용 PyTorch + pip install -e .
  • 사용 핵심은 짧게 먼저 생성해서 빠르게 반복
  • RTX 4060 노트북은 --cpu_offload true 기반 안정 운용이 가장 안전합니다.

부록 A) 복붙용 최소 명령 모음

cd $HOME
mkdir ai-music -ErrorAction SilentlyContinue
cd ai-music
git clone https://github.com/ace-step/ACE-Step.git
cd ACE-Step
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
pip install -e .
acestep --port 7865 --cpu_offload true --overlapped_decode true

부록 B) 안전/저작권 기본 원칙

AI 생성 음악은 상업 사용 전 반드시 아래를 확인하세요.

  1. 저작권/이용약관 확인
  2. 특정 아티스트 스타일 과도 모방 지양
  3. 배포 전 원본성 검토

작성 목적: 스카이님의 요청에 따른 초보자 교육용 설치·테스트 매뉴얼

16) 오류 메시지별 즉시 대응표 (현장용)

아래 표는 실제 초보자가 자주 만나는 에러를 바로 조치할 수 있게 정리한 빠른 대응표입니다.

16-1. 설치/실행 오류

  1. python: command not found 또는 python is not recognized
  • 의미: Python 경로가 시스템에 등록되지 않았거나 설치가 누락됨
  • 즉시 조치:
    • Python 재설치 시 Add Python to PATH 체크
    • 새 PowerShell 창에서 python --version 재확인
  1. No module named ...
  • 의미: 필요한 패키지가 현재 가상환경에 없음
  • 즉시 조치:
    • (.venv) 활성 상태인지 확인
    • pip install -e . 재실행
  1. acestep is not recognized
  • 의미: 콘솔 명령이 가상환경 경로를 못 찾음
  • 즉시 조치:
    • \.venv\Scripts\Activate.ps1 다시 실행
    • 여전히 안 되면 pip install -e . 재실행

16-2. GPU/메모리 오류

  1. CUDA out of memory
  • 의미: GPU VRAM이 부족함
  • 즉시 조치 (순서대로):
    1. 길이 20~30초로 줄이기
    2. 스텝 20~24로 낮추기
    3. --cpu_offload true 유지
    4. 브라우저/게임/영상 편집 툴 종료 후 재시도
  1. Torch not compiled with CUDA enabled
  • 의미: CPU 버전 PyTorch가 설치됨
  • 즉시 조치:
    • 기존 torch 제거 후 CUDA 버전 재설치
pip uninstall -y torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
  1. nvidia-smi는 되는데 생성이 비정상적으로 느림
  • 의미: GPU 대신 CPU로 돌고 있을 가능성
  • 즉시 조치:
    • 가상환경 재활성화 후 재실행
    • 백그라운드 점유 앱 종료
    • 짧은 프롬프트/짧은 길이로 GPU 사용 여부 체감 테스트

16-3. 접속/UI 오류

  1. 브라우저에서 127.0.0.1:7865 접속 실패
  • 의미: 서버 미기동 또는 포트 충돌
  • 즉시 조치:
    • 터미널에서 에러 유무 확인
    • 포트 변경: acestep --port 7866 --cpu_offload true --overlapped_decode true
    • 방화벽 팝업이 나오면 로컬 접근 허용
  1. 첫 실행에서 오래 멈춘 것처럼 보임
  • 의미: 모델 다운로드/초기 캐시 생성 중일 수 있음
  • 즉시 조치:
    • 3~10분 여유를 두고 기다림
    • 네트워크 상태 확인
    • 중단했다면 재실행 후 동일 단계 재시도

16-4. 품질/결과 오류

  1. 보컬이 깨지거나 가사가 이상함
  • 의미: 프롬프트/가사 구조·스텝·길이 조합이 불안정
  • 즉시 조치:
    • 가사 길이를 줄이고 섹션 태그([verse], [chorus])를 단순화
    • 스텝을 약간 올려 재시도
    • seed 고정 후 한 변수씩만 변경
  1. 결과 편차가 너무 큼
  • 의미: 시드/설정 고정 없이 반복한 경우
  • 즉시 조치:
    • seed 고정 (예: 12345)
    • 태그·가이드·스텝 중 하나만 바꿔 비교

17) 5분 복구 프로토콜 (완전 초보용)

문제가 복잡해졌을 때는 아래 5분 복구 절차로 초기화하면 대부분 해결됩니다.

  1. PowerShell 종료 후 새로 열기
  2. 프로젝트 폴더로 이동
  3. 가상환경 활성화
cd $HOME\ai-music\ACE-Step
.\.venv\Scripts\Activate.ps1
  1. 핵심 패키지 재정렬
pip install --upgrade pip
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
pip install -e .
  1. 안전 실행 옵션으로 재기동
acestep --port 7865 --cpu_offload true --overlapped_decode true

이 프로토콜 이후에도 실패하면, 오류 메시지 원문을 복사해 원인 분석을 진행합니다.