docs/ko/GRADIO_GUIDE.md

ACE-Step Gradio 데모 사용자 가이드

언어 / Language / 语言 / 言語: English | 한국어 | 中文 | 日本語

---

이 가이드는 ACE-Step Gradio 웹 인터페이스를 사용한 음악 생성에 대한 포괄적인 문서를 제공하며, 모든 기능과 설정을 포함합니다.

목차

• 시작하기
• 서비스 설정
• 생성 모드
• 입력 파라미터
• 고급 설정
• 결과 섹션
• LoRA 학습
• 팁과 모범 사례

---

시작하기

데모 실행

# 기본 실행
python app.py

# 사전 초기화 포함
python app.py --config acestep-v15-turbo --init-llm

# 특정 포트 지정
python app.py --port 7860

인터페이스 개요

Gradio 인터페이스의 레이아웃:

1. 설정 (접이식 아코디언) - 서비스 설정, DiT/LM 파라미터, 출력 옵션
2. 생성 탭 - 메인 작업 공간. 상단에 생성 모드 라디오 선택기:
   • Turbo/SFT 모델: Simple, Custom, Remix, Repaint
   • Base 모델: Simple, Custom, Remix, Repaint, Extract, Lego, Complete
3. 결과 섹션 - 생성된 오디오 재생, 스코어링, 배치 내비게이션
4. 학습 탭 - 데이터셋 빌더 및 LoRA 학습

---

서비스 설정

모델 선택

설정	설명
체크포인트 파일	학습된 모델 체크포인트 선택 (사용 가능한 경우)
메인 모델 경로	DiT 모델 설정 선택 (예: acestep-v15-turbo, acestep-v15-turbo-shift3)
디바이스	처리 디바이스: auto (권장), cuda, 또는 cpu

5Hz LM 설정

설정	설명
5Hz LM 모델 경로	언어 모델 선택. 사용 가능한 모델은 GPU 티어에 따라 자동 필터링 — 예: 6-8GB GPU는 0.6B만, 24GB+ GPU는 모든 크기(0.6B, 1.7B, 4B) 표시.
5Hz LM 백엔드	vllm (더 빠름, VRAM ≥8GB NVIDIA GPU 권장), pt (PyTorch, 범용 폴백), 또는 mlx (Apple Silicon). VRAM <8GB GPU에서는 pt/mlx로 제한 (vllm의 KV 캐시가 메모리를 과도하게 사용하므로).
5Hz LM 초기화	초기화 시 LM을 로드하려면 체크 (thinking 모드에 필요). VRAM ≤6GB GPU(Tier 1-2)에서 기본적으로 체크 해제 및 비활성화.

적응형 기본값: 모든 LM 설정은 GPU의 VRAM 티어에 따라 자동 구성됩니다. 권장 LM 모델, 백엔드, 초기화 상태가 최적 성능을 위해 사전 설정됩니다. 수동으로 변경할 수 있지만, GPU와 호환되지 않는 선택 시 시스템이 경고를 표시합니다.

성능 옵션

설정	설명
Flash Attention 사용	더 빠른 추론을 위해 활성화 (flash_attn 패키지 필요)
CPU로 오프로드	유휴 시 모델을 CPU로 오프로드하여 GPU 메모리 절약. VRAM <20GB GPU에서 자동 활성화.
DiT를 CPU로 오프로드	DiT 모델을 특별히 CPU로 오프로드. VRAM <12GB GPU에서 자동 활성화.
INT8 양자화	INT8 가중치 양자화로 모델 VRAM 사용량 감소. VRAM <20GB GPU에서 자동 활성화.
모델 컴파일	최적화된 추론을 위해 torch.compile 활성화. 모든 티어에서 기본 활성화 (양자화 활성 시 필요).

티어 인식 설정: 오프로드, 양자화, 컴파일 옵션은 GPU 티어에 따라 자동 설정됩니다. 전체 티어 테이블은 GPU_COMPATIBILITY.md를 참조하세요.

LoRA 어댑터

설정	설명
LoRA 경로	학습된 LoRA 어댑터 디렉토리 경로
LoRA 로드	지정된 LoRA 어댑터 로드
언로드	현재 로드된 LoRA 제거
LoRA 사용	추론용 로드된 LoRA 활성화/비활성화

⚠️ 참고: PEFT와 TorchAO 간 호환성 문제로 양자화된 모델에 LoRA 어댑터를 로드할 수 없습니다. LoRA를 사용해야 하는 경우 어댑터를 로드하기 전에 INT8 양자화를 None으로 설정하세요.

초기화

서비스 초기화를 클릭하여 모델을 로드합니다. 상태 박스에 다음을 포함한 진행 상황과 확인이 표시됩니다:

• 감지된 GPU 티어 및 VRAM
• 최대 허용 시간 및 배치 크기 (LM 초기화 여부에 따라 동적 조정)
• 자동 수정된 호환되지 않는 설정에 대한 경고

초기화 후 오디오 시간 및 배치 크기 슬라이더가 티어 제한을 반영하도록 자동 업데이트됩니다.

---

생성 모드

생성 탭 상단의 생성 모드 라디오 선택기가 워크플로를 결정합니다. Turbo 및 SFT 모델은 4가지 모드를 제공하고, Base 모델은 3가지를 추가로 제공합니다.

Simple 모드

빠른 자연어 기반 음악 생성을 위해 설계되었습니다.

사용 방법:

1. 생성 모드에서 Simple 선택
2. "곡 설명" 필드에 자연어 설명 입력
3. 보컬이 필요 없으면 "인스트루멘탈" 옵션 체크
4. 선호하는 보컬 언어 옵션 선택
5. 샘플 생성 클릭하여 caption, 가사, 메타데이터 생성
6. 확장된 섹션에서 생성된 콘텐츠 확인
7. 음악 생성 클릭하여 오디오 생성

설명 예시:

• "조용한 저녁을 위한 부드러운 벵골 러브송"
• "강렬한 베이스 드롭이 있는 업비트 일렉트로닉 댄스 뮤직"
• "어쿠스틱 기타의 멜랑콜리한 인디 포크"
• "연기 자욱한 바에서 연주하는 재즈 트리오"

랜덤 샘플: 🎲 버튼을 클릭하여 랜덤 예시 설명을 로드합니다.

Custom 모드

모든 생성 파라미터를 완전히 제어합니다 (text2music).

사용 방법:

1. 생성 모드에서 Custom 선택
2. Caption과 가사 필드를 수동으로 입력
3. 옵션으로 참조 오디오를 업로드하여 스타일 가이던스
4. 옵션 메타데이터 설정 (BPM, 키, 시간 등)
5. 옵션으로 포맷 클릭하여 LM으로 입력 향상
6. 필요에 따라 고급 설정 구성
7. 음악 생성 클릭하여 오디오 생성

Remix 모드

기존 오디오의 멜로디 구조를 유지하면서 스타일을 변경합니다.

사용 방법:

1. 생성 모드에서 Remix 선택
2. 소스 오디오 업로드 (리믹스할 곡)
3. 타겟 스타일을 설명하는 Caption 작성
4. 옵션으로 가사 수정
5. Remix 강도 (0.0-1.0) 조정: 높을수록 = 원본 구조에 가까움
6. 음악 생성 클릭

용도: 커버 버전 생성, 스타일 전이, 곡 변형 생성.

Repaint 모드

오디오의 특정 시간 구간을 재생성하고 나머지는 유지합니다.

사용 방법:

1. 생성 모드에서 Repaint 선택
2. 소스 오디오 업로드
3. 리페인트 시작과 리페인트 끝 설정 (초; -1은 파일 끝)
4. 리페인트 섹션의 원하는 콘텐츠를 설명하는 Caption 작성
5. 음악 생성 클릭

용도: 문제 있는 섹션 수정, 구간 내 가사 변경, 곡 연장.

Extract 모드 (Base 모델 전용)

믹스된 오디오에서 특정 악기 트랙을 추출/분리합니다.

사용 방법:

1. 생성 모드에서 Extract 선택
2. 소스 오디오 업로드
3. 드롭다운에서 추출할 트랙 이름 선택
4. 음악 생성 클릭

사용 가능한 트랙: vocals, backing_vocals, drums, bass, guitar, keyboard, percussion, strings, synth, fx, brass, woodwinds

Lego 모드 (Base 모델 전용)

기존 오디오에 새로운 악기 트랙을 추가합니다.

사용 방법:

1. 생성 모드에서 Lego 선택
2. 소스 오디오 업로드
3. 드롭다운에서 추가할 트랙 이름 선택
4. 트랙 특성을 설명하는 Caption 작성
5. 음악 생성 클릭

Complete 모드 (Base 모델 전용)

지정된 악기로 부분적인 트랙을 완성합니다 (자동 편곡).

사용 방법:

1. 생성 모드에서 Complete 선택
2. 소스 오디오 업로드
3. 추가할 여러 트랙 이름 선택
4. 원하는 스타일을 설명하는 Caption 작성
5. 음악 생성 클릭

---

입력 파라미터

오디오 입력

필드	설명
참조 오디오	스타일/음색 가이던스를 위한 옵션 오디오 (Custom 모드에서 표시)
소스 오디오	Remix, Repaint, Extract, Lego, Complete 모드에 필수
코드로 변환	소스 오디오에서 5Hz 시맨틱 코드 추출

LM 코드 힌트 (Custom 모드)

사전 계산된 오디오 시맨틱 코드를 여기에 붙여넣어 생성을 가이드할 수 있습니다. 트랜스크라이브 버튼을 사용하여 코드를 분석하고 메타데이터를 추출합니다. 소스 오디오 업로드 없이 멜로디 구조를 제어하기 위한 고급 기능입니다.

음악 Caption

원하는 음악의 텍스트 설명. 다음에 대해 구체적으로 작성:

• 장르와 스타일
• 악기
• 분위기와 느낌
• 템포 느낌 (BPM을 지정하지 않는 경우)

예시: "일렉 기타, 강렬한 드럼, 캐치한 신스 훅이 있는 업비트 팝 록"

🎲를 클릭하여 랜덤 예시 caption을 로드합니다.

가사

구조 태그가 포함된 가사를 입력:

[Verse 1]
오늘 거리를 걸으며
네가 했던 말들을 떠올렸어

[Chorus]
나는 앞으로 나아가, 강하게 서서
여기가 내 자리야

[Verse 2]
...

인스트루멘탈 체크박스: 가사 내용에 관계없이 인스트루멘탈 음악을 생성하려면 체크합니다.

보컬 언어: 보컬 언어를 선택합니다. 자동 감지 또는 인스트루멘탈 트랙에는 "unknown"을 사용합니다.

포맷 버튼: 5Hz LM을 사용하여 caption과 가사를 향상시키려면 클릭합니다.

옵션 파라미터

파라미터	기본값	설명
BPM	자동	분당 비트 수 (30-300)
키 스케일	자동	음악 키 (예: "C Major", "Am", "F# minor")
박자 기호	자동	박자 기호: 2 (2/4), 3 (3/4), 4 (4/4), 6 (6/8)
오디오 시간	자동/-1	목표 길이(초) (10-600). -1은 자동
배치 크기	2	생성할 오디오 변형 수 (1-8)

---

고급 설정

DiT 파라미터

파라미터	기본값	설명
추론 스텝	8	디노이징 스텝. Turbo: 1-20, Base: 1-200
가이던스 스케일	7.0	CFG 강도 (base 모델만). 높을수록 = 프롬프트를 더 따름
시드	-1	랜덤 시드. 배치에는 쉼표로 구분된 값 사용
랜덤 시드	✓	체크 시 랜덤 시드 생성
오디오 형식	mp3	출력 형식: mp3, flac
시프트	3.0	타임스텝 시프트 계수 (1.0-5.0). turbo에 3.0 권장
추론 방법	ode	ode (Euler, 더 빠름) 또는 sde (확률적)
커스텀 타임스텝	-	타임스텝 오버라이드 (예: "0.97,0.76,0.615,0.5,0.395,0.28,0.18,0.085,0")

Base 모델 전용 파라미터

파라미터	기본값	설명
ADG 사용	✗	더 나은 품질을 위해 적응형 듀얼 가이던스 활성화
CFG 구간 시작	0.0	CFG 적용 시작 시점 (0.0-1.0)
CFG 구간 끝	1.0	CFG 적용 종료 시점 (0.0-1.0)

LM 파라미터

파라미터	기본값	설명
LM 온도	0.85	샘플링 온도 (0.0-2.0). 높을수록 = 더 창의적
LM CFG 스케일	2.0	LM 가이던스 강도 (1.0-3.0)
LM Top-K	0	Top-K 샘플링. 0이면 비활성화
LM Top-P	0.9	핵 샘플링 (0.0-1.0)
LM 네거티브 프롬프트	"NO USER INPUT"	CFG용 네거티브 프롬프트

CoT (사고의 연쇄) 옵션

옵션	기본값	설명
CoT Metas	✓	LM 추론을 통해 메타데이터 생성
CoT Language	✓	LM으로 보컬 언어 감지
제약 디코딩 디버그	✗	디버그 로깅 활성화

생성 옵션

옵션	기본값	설명
LM 코드 강도	1.0	LM 코드가 생성에 미치는 영향의 강도 (0.0-1.0)
자동 스코어	✗	품질 스코어 자동 계산
자동 LRC	✗	가사 타임스탬프 자동 생성
LM 배치 청크 크기	8	LM 배치당 최대 항목 수 (GPU 메모리)

메인 생성 컨트롤

컨트롤	설명
Think	코드 생성 및 메타데이터를 위한 5Hz LM 활성화
ParallelThinking	병렬 LM 배치 처리 활성화
CaptionRewrite	LM이 입력 caption을 향상시키도록 함
AutoGen	완료 후 다음 배치 자동 시작

---

결과 섹션

생성된 오디오

배치 크기에 따라 최대 8개의 오디오 샘플이 표시됩니다. 각 샘플에는 다음이 포함됩니다:

• 오디오 플레이어 - 생성된 오디오 재생, 일시 정지, 다운로드
• 소스로 전송 - 이 오디오를 소스 오디오 입력으로 전송하여 추가 처리
• 저장 - 오디오와 메타데이터를 JSON 파일로 저장
• 스코어 - 퍼플렉시티 기반 품질 스코어 계산
• LRC - 가사 타임스탬프 생성 (LRC 형식)

상세 아코디언

"Score & LRC & LM Codes"를 클릭하여 확장하고 다음을 확인:

• LM 코드 - 이 샘플의 5Hz 시맨틱 코드
• 품질 스코어 - 퍼플렉시티 기반 품질 메트릭
• 가사 타임스탬프 - LRC 형식 타이밍 데이터

배치 내비게이션

컨트롤	설명
◀ 이전	이전 배치 보기
배치 인디케이터	현재 배치 위치 표시 (예: "배치 1 / 3")
다음 배치 상태	백그라운드 생성 진행 상황 표시
다음 ▶	다음 배치 보기 (AutoGen이 켜져 있으면 생성 트리거)

파라미터 복원

이 설정을 UI에 적용을 클릭하여 현재 배치의 모든 생성 파라미터를 입력 필드로 복원합니다. 좋은 결과를 반복하는 데 유용합니다.

배치 결과

"배치 결과 및 생성 상세" 아코디언에는 다음이 포함됩니다:

• 모든 생성 파일 - 모든 배치의 모든 파일 다운로드
• 생성 상세 - 생성 과정에 대한 상세 정보

---

LoRA 학습

LoRA 학습 탭은 커스텀 LoRA 어댑터를 만들기 위한 도구를 제공합니다.

📖 전체 단계별 안내 (데이터 준비, 주석, 전처리, 학습, 내보내기)는 LoRA 학습 튜토리얼을 참조하세요.

데이터셋 빌더 탭

1단계: 로드 또는 스캔

옵션 A: 기존 데이터셋 로드

1. 이전에 저장한 데이터셋 JSON 경로 입력
2. 로드 클릭

옵션 B: 새 디렉토리 스캔

1. 오디오 폴더 경로 입력
2. 스캔 클릭하여 오디오 파일 검색 (wav, mp3, flac, ogg, opus)

2단계: 데이터셋 설정

설정	설명
데이터셋 이름	데이터셋 이름
모두 인스트루멘탈	모든 트랙에 보컬이 없는 경우 체크
커스텀 활성화 태그	이 LoRA의 스타일을 활성화하는 고유 태그
태그 위치	태그를 배치할 위치: 앞에 추가, 뒤에 추가, 또는 caption 대체

3단계: 자동 라벨링

모두 자동 라벨링을 클릭하여 모든 오디오 파일의 메타데이터를 생성:

• Caption (음악 설명)
• BPM
• 키
• 박자 기호

메타 건너뛰기 옵션은 LLM 라벨링을 건너뛰고 N/A 값을 사용합니다.

4단계: 미리보기 및 편집

슬라이더를 사용하여 샘플을 선택하고 수동 편집:

• Caption
• 가사
• BPM, 키, 박자 기호
• 언어
• 인스트루멘탈 플래그

변경 저장을 클릭하여 샘플을 업데이트합니다.

5단계: 데이터셋 저장

저장 경로를 입력하고 데이터셋 저장을 클릭하여 JSON으로 내보냅니다.

6단계: 전처리

빠른 학습을 위해 데이터셋을 사전 계산 텐서로 변환:

1. 옵션으로 기존 데이터셋 JSON 로드
2. 텐서 출력 디렉토리 설정
3. 전처리 클릭

이것은 오디오를 VAE 잠재 변수로 인코딩하고, 텍스트를 임베딩으로 인코딩하며, 조건 인코더를 실행합니다.

LoRA 학습 탭

데이터셋 선택

전처리된 텐서 디렉토리 경로를 입력하고 데이터셋 로드를 클릭합니다.

LoRA 설정

설정	기본값	설명
LoRA 랭크 (r)	64	LoRA의 용량. 높을수록 = 더 많은 용량, 더 많은 메모리
LoRA 알파	128	스케일링 계수 (일반적으로 랭크의 2배)
LoRA 드롭아웃	0.1	정규화를 위한 드롭아웃 비율

학습 파라미터

설정	기본값	설명
학습률	1e-4	최적화 학습률
최대 에폭	500	최대 학습 에폭
배치 크기	1	학습 배치 크기
그래디언트 누적	1	유효 배치 = batch_size × accumulation
N 에폭마다 저장	200	체크포인트 저장 빈도
시프트	3.0	turbo 모델의 타임스텝 시프트
시드	42	재현성을 위한 랜덤 시드

학습 컨트롤

• 학습 시작 - 학습 프로세스 시작
• 학습 중지 - 학습 중단
• 학습 진행 - 현재 에폭과 손실 표시
• 학습 로그 - 상세 학습 출력
• 학습 손실 플롯 - 시각적 손실 곡선

LoRA 내보내기

학습 후 최종 어댑터를 내보냅니다:

1. 내보내기 경로 입력
2. LoRA 내보내기 클릭

---

팁과 모범 사례

최고 품질을 위해

1. thinking 모드 사용 - LM 향상 생성을 위해 "Think" 체크박스를 활성화 유지
2. caption을 구체적으로 - 장르, 악기, 분위기, 스타일 세부 사항 포함
3. LM이 메타데이터를 감지하도록 - 자동 감지를 위해 BPM/키/시간을 비워 둠
4. 배치 생성 사용 - 2-4개 변형을 생성하고 최적의 것을 선택

더 빠른 생성을 위해

1. turbo 모델 사용 - acestep-v15-turbo 또는 acestep-v15-turbo-shift3 선택
2. 추론 스텝을 8로 유지 - turbo에 최적인 기본값
3. 배치 크기 줄이기 - 빠른 결과가 필요하면 배치 크기 낮추기
4. AutoGen 비활성화 - 배치 생성의 수동 제어

일관된 결과를 위해

1. 특정 시드 설정 - "랜덤 시드" 체크 해제 후 시드 값 입력
2. 좋은 결과 저장 - 재현을 위해 파라미터를 내보내려면 "저장" 사용
3. "이 설정 적용" 사용 - 좋은 배치에서 파라미터 복원

장시간 음악을 위해

1. 명시적 시간 설정 - 초 단위로 시간 지정
2. Repaint 모드 사용 - 초기 생성 후 문제 있는 섹션 수정
3. 생성 체인 - "소스로 전송"을 사용하여 이전 결과를 기반으로 구축

스타일 일관성을 위해

1. LoRA 학습 - 스타일에 맞는 커스텀 어댑터 생성
2. 참조 오디오 사용 - 오디오 업로드에서 스타일 참조 업로드
3. 일관된 caption 사용 - 유사한 설명적 언어 유지

문제 해결

오디오가 생성되지 않음:

• 모델이 초기화되었는지 확인 (녹색 상태 메시지)
• thinking 모드 사용 시 5Hz LM이 초기화되었는지 확인
• 오류 메시지에 대한 상태 출력 확인

결과 품질이 낮음:

• 추론 스텝 증가 (base 모델의 경우)
• 가이던스 스케일 조정
• 다른 시드 시도
• caption을 더 구체적으로 작성

메모리 부족 (OOM):

• 시스템에 자동 VRAM 관리 (VRAM 가드, 적응형 VAE 디코드, 자동 배치 축소) 포함. 그래도 OOM 발생 시:
• 수동으로 배치 크기 줄이기
• CPU 오프로드 활성화 (VRAM <20GB에서 자동 활성화되어야 함)
• INT8 양자화 활성화 (VRAM <20GB에서 자동 활성화되어야 함)
• LM 배치 청크 크기 줄이기

LM이 작동하지 않음:

• 초기화 시 "5Hz LM 초기화"가 체크되었는지 확인 (VRAM ≤6GB GPU에서 기본 비활성화)
• 유효한 LM 모델 경로가 선택되었는지 확인 (티어 호환 모델만 표시)
• vllm 또는 PyTorch 백엔드가 사용 가능한지 확인 (VRAM <8GB에서 vllm 제한)
• LM 체크박스가 회색이면 GPU 티어가 LM을 지원하지 않음 — DiT 전용 모드 사용

---

키보드 단축키

Gradio 인터페이스는 표준 웹 단축키를 지원합니다:

• Tab - 입력 필드 간 이동
• Enter - 텍스트 입력 제출
• Space - 체크박스 토글

---

언어 지원

인터페이스는 여러 UI 언어를 지원합니다:

• 영어 (en)
• 중국어 (zh)
• 일본어 (ja)
• 한국어 (ko)

서비스 설정 섹션에서 선호하는 언어를 선택하세요.

---

자세한 내용은 다음을 참조하세요:

• 메인 README: ../../README.md
• REST API 문서: ../en/API.md
• Python 추론 API: ../en/INFERENCE.md