docs/ja/GRADIO_GUIDE.md

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

Language / 语言 / 言語: English | 中文 | 日本語

---

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

目次

• はじめに
• サービス設定
• 生成モード
• 入力パラメータ
• 高度な設定
• 結果セクション
• 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、キー、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 トレーニングチュートリアルを参照してください。

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

ステップ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 を参照

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
• REST APIドキュメント：API.md
• Python推論API：INFERENCE.md