# ACE-Step Gradio デモユーザーガイド

**Language / 语言 / 言語:** [English](../en/GRADIO_GUIDE.md) | [中文](../zh/GRADIO_GUIDE.md) | [日本語](GRADIO_GUIDE.md)

---

本ガイドはACE-Step Gradio Webインターフェースを使用した音楽生成の包括的なドキュメントを提供し、すべての機能と設定を含みます。

## 目次

- [はじめに](#はじめに)
- [サービス設定](#サービス設定)
- [生成モード](#生成モード)
- [入力パラメータ](#入力パラメータ)
- [高度な設定](#高度な設定)
- [結果セクション](#結果セクション)
- [LoRAトレーニング](#loraトレーニング)
- [ヒントとベストプラクティス](#ヒントとベストプラクティス)

---

## はじめに

### デモの起動

```bash
# 基本的な起動
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](../ja/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、キー、Durationなど）
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モード）

事前計算されたオーディオセマンティックコードをここに貼り付けて生成をガイドできます。**トランスクライブ** ボタンを使用してコードを分析しメタデータを抽出します。これはソースオーディオをアップロードせずにメロディ構造を制御するための高度な機能です。

### 音楽キャプション

希望する音楽のテキスト説明。以下について具体的に：
- ジャンルとスタイル
- 楽器
- ムードと雰囲気
- テンポ感（BPMを指定しない場合）

**例：** 「エレキギター、力強いドラム、キャッチーなシンセフックのアップビートなポップロック」

🎲 をクリックしてランダムな例のcaptionを読み込みます。

### 歌詞

構造タグ付きの歌詞を入力：

```
[Verse 1]
今日街を歩いていて
君が言っていた言葉を思い出していた

[Chorus]
前に進んでいく、強くいる
ここが僕の居場所

[Verse 2]
...
```

**インストゥルメンタルチェックボックス：** これをチェックすると、歌詞の内容に関係なくインストゥルメンタル音楽を生成します。

**ボーカル言語：** ボーカルの言語を選択。自動検出またはインストゥルメンタルトラックには「unknown」を使用。

**フォーマットボタン：** クリックして5Hz LMを使用してcaptionと歌詞を強化。

### オプションパラメータ

| パラメータ | デフォルト | 説明 |
|-----------|---------|-------------|
| **BPM** | 自動 | 1分あたりのビート数（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形式）

### 詳細アコーディオン

「スコア & LRC & LMコード」をクリックして展開し、以下を表示：
- **LMコード** - このサンプルの5Hzセマンティックコード
- **品質スコア** - パープレキシティベースの品質メトリック
- **歌詞タイムスタンプ** - LRC形式のタイミングデータ

### バッチナビゲーション

| コントロール | 説明 |
|---------|-------------|
| **◀ 前へ** | 前のバッチを表示 |
| **バッチインジケーター** | 現在のバッチ位置を表示（例：「バッチ 1 / 3」）|
| **次バッチステータス** | バックグラウンド生成の進捗を表示 |
| **次へ ▶** | 次のバッチを表示（AutoGenがオンの場合は生成をトリガー）|

### パラメータの復元

**これらの設定をUIに適用** をクリックして、現在のバッチからすべての生成パラメータを入力フィールドに復元。良い結果を反復するのに便利。

### バッチ結果

「バッチ結果と生成詳細」アコーディオンには以下が含まれます：
- **すべての生成ファイル** - すべてのバッチからすべてのファイルをダウンロード
- **生成詳細** - 生成プロセスに関する詳細情報

---

## LoRAトレーニング

LoRAトレーニングタブはカスタムLoRAアダプターを作成するためのツールを提供します。

> 📖 **包括的なステップバイステップガイド**（データ準備、アノテーション、前処理、訓練、エクスポート）については、[LoRA トレーニングチュートリアル](./LoRA_Training_Tutorial.md)を参照してください。

### データセットビルダータブ

#### ステップ1：読み込みまたはスキャン

**オプションA：既存のデータセットを読み込み**
1. 以前保存したデータセットJSONへのパスを入力
2. **読み込み** をクリック

**オプションB：新しいディレクトリをスキャン**
1. オーディオフォルダへのパスを入力
2. **スキャン** をクリックしてオーディオファイルを検索（wav、mp3、flac、ogg、opus）

#### ステップ2：データセットの設定

| 設定 | 説明 |
|---------|-------------|
| **データセット名** | データセットの名前 |
| **すべてインストゥルメンタル** | すべてのトラックにボーカルがない場合にチェック |
| **カスタムアクティベーションタグ** | このLoRAのスタイルをアクティブにするユニークなタグ |
| **タグ位置** | タグを配置する場所：前に追加、後に追加、またはcaptionを置換 |

#### ステップ3：自動ラベル

**すべて自動ラベル** をクリックしてすべてのオーディオファイルのメタデータを生成：
- Caption（音楽の説明）
- BPM
- キー
- 拍子記号

**Metasをスキップ** オプションはLLMラベリングをスキップしてN/A値を使用します。

#### ステップ4：プレビューと編集

スライダーを使用してサンプルを選択し、手動で編集：
- Caption
- 歌詞
- BPM、キー、拍子記号
- 言語
- インストゥルメンタルフラグ

**変更を保存** をクリックしてサンプルを更新。

#### ステップ5：データセットを保存

保存パスを入力し、**データセットを保存** をクリックしてJSONとしてエクスポート。

#### ステップ6：前処理

高速トレーニングのためにデータセットを事前計算テンソルに変換：
1. オプションで既存のデータセットJSONを読み込み
2. テンソル出力ディレクトリを設定
3. **前処理** をクリック

これによりオーディオがVAE潜在変数にエンコードされ、テキストが埋め込みにエンコードされ、条件エンコーダーが実行されます。

### LoRAトレーニングタブ

#### データセット選択

前処理されたテンソルディレクトリへのパスを入力し、**データセットを読み込み** をクリック。

#### LoRA設定

| 設定 | デフォルト | 説明 |
|---------|---------|-------------|
| **LoRAランク (r)** | 64 | LoRAの容量。高い = より多くの容量、より多くのメモリ |
| **LoRA Alpha** | 128 | スケーリング係数（通常はランクの2倍）|
| **LoRA Dropout** | 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/キー/Durationを空のままにする
4. **バッチ生成を使用** - 2-4のバリエーションを生成し、最良のものを選ぶ

### より高速な生成のために

1. **turboモデルを使用** - `acestep-v15-turbo` または `acestep-v15-turbo-shift3` を選択
2. **推論ステップを8に保つ** - turboに最適なデフォルト
3. **バッチサイズを減らす** - 迅速な結果が必要な場合はバッチサイズを下げる
4. **AutoGenを無効化** - バッチ生成の手動制御

### 一貫した結果のために

1. **特定のシードを設定** - 「ランダムシード」のチェックを外してシード値を入力
2. **良い結果を保存** - 再現のためにパラメータをエクスポートするために「保存」を使用
3. **「これらの設定を適用」を使用** - 良いバッチからパラメータを復元

### 長尺音楽のために

1. **明示的なdurationを設定** - 秒単位でdurationを指定
2. **repaintタスクを使用** - 初期生成後に問題のあるセクションを修正
3. **生成をチェーン** - 以前の結果の上に構築するために「ソースに送信」を使用

### スタイルの一貫性のために

1. **LoRAをトレーニング** - あなたのスタイル用のカスタムアダプターを作成
2. **参照オーディオを使用** - オーディオアップロードでスタイル参照をアップロード
3. **一貫したcaptionを使用** - 類似の説明的な言語を維持

### トラブルシューティング

**オーディオが生成されない：**
- モデルが初期化されていることを確認（緑のステータスメッセージ）
- thinkingモードを使用している場合は5Hz LMが初期化されていることを確認
- エラーメッセージのステータス出力を確認

**結果の品質が悪い：**
- 推論ステップを増やす（baseモデルの場合）
- ガイダンススケールを調整
- 異なるシードを試す
- captionをより具体的にする

**メモリ不足（OOM）：**
- システムは自動VRAMガード（バッチ自動削減）とアダプティブVAEデコード（CPUフォールバック）を含みます。それでもOOMが発生する場合：
- 手動でバッチサイズを減らす
- CPUオフロードを有効化（VRAM <20GBでは自動有効のはず）
- INT8量子化を有効化（VRAM <20GBでは自動有効のはず）
- LMバッチチャンクサイズを減らす
- 各ティアの推奨設定は [GPU_COMPATIBILITY.md](../ja/GPU_COMPATIBILITY.md) を参照

**LMが機能しない：**
- 初期化時に「5Hz LMを初期化」がチェックされていたことを確認（VRAM ≤6GBのGPUではデフォルト無効）
- 有効なLMモデルパスが選択されていることを確認（ティア互換モデルのみ表示）
- vllmまたはPyTorchバックエンドが利用可能であることを確認（VRAM <8GBではvllm制限）
- LMチェックボックスがグレーアウトしている場合、GPUティアがLMをサポートしていません — DiTのみモードを使用

---

## キーボードショートカット

Gradioインターフェースは標準的なWebショートカットをサポート：
- **Tab** - 入力フィールド間を移動
- **Enter** - テキスト入力を送信
- **Space** - チェックボックスを切り替え

---

## 言語サポート

インターフェースは複数のUI言語をサポート：
- **英語** (en)
- **中国語** (zh)
- **日本語** (ja)

サービス設定セクションで好みの言語を選択してください。

---

詳細については以下を参照：
- メインREADME：[`../../README.md`](../../README.md)
- REST APIドキュメント：[`API.md`](API.md)
- Python推論API：[`INFERENCE.md`](INFERENCE.md)