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. サービス設定 - モデルの読み込みと初期化
2. 必須入力 - タスクタイプ、オーディオアップロード、生成モード
3. 音楽キャプションと歌詞 - 生成用のテキスト入力
4. オプションパラメータ - BPM、キー、durationなどのメタデータ
5. 高度な設定 - 生成の細かい制御
6. 結果 - 生成されたオーディオの再生と管理

---

サービス設定

モデル選択

設定	説明
チェックポイントファイル	トレーニング済みモデルチェックポイントを選択（利用可能な場合）
メインモデルパス	DiTモデル設定を選択（例：acestep-v15-turbo、acestep-v15-turbo-shift3）
デバイス	処理デバイス：auto（推奨）、cuda、または cpu

5Hz LM設定

設定	説明
5Hz LMモデルパス	言語モデルを選択（例：acestep-5Hz-lm-0.6B、acestep-5Hz-lm-1.7B）
5Hz LMバックエンド	vllm（より高速、推奨）または pt（PyTorch、互換性が高い）
5Hz LMを初期化	初期化時にLMを読み込むためにチェック（thinkingモードに必要）

パフォーマンスオプション

設定	説明
Flash Attentionを使用	より高速な推論のために有効化（flash_attnパッケージが必要）
CPUにオフロード	アイドル時にモデルをCPUにオフロードしてGPUメモリを節約
DiTをCPUにオフロード	DiTモデルを特にCPUにオフロード

LoRAアダプター

設定	説明
LoRAパス	トレーニング済みLoRAアダプターディレクトリへのパス
LoRAを読み込み	指定されたLoRAアダプターを読み込み
アンロード	現在読み込まれているLoRAを削除
LoRAを使用	推論用の読み込まれたLoRAを有効化/無効化

初期化

サービスを初期化 をクリックしてモデルを読み込みます。ステータスボックスに進捗と確認が表示されます。

---

生成モード

シンプルモード

シンプルモードは、迅速な自然言語ベースの音楽生成用に設計されています。

使用方法：

1. 生成モードラジオボタンで「シンプル」を選択
2. 「曲の説明」フィールドに自然言語の説明を入力
3. ボーカルが不要な場合は「インストゥルメンタル」をオプションでチェック
4. オプションで希望するボーカル言語を選択
5. サンプルを作成 をクリックしてcaption、歌詞、メタデータを生成
6. 展開されたセクションで生成されたコンテンツを確認
7. 音楽を生成 をクリックしてオーディオを作成

説明の例：

• 「静かな夜のための柔らかいベンガルのラブソング」
• 「重いベースドロップのアップビートなエレクトロニックダンスミュージック」
• 「アコースティックギターのメランコリックなインディーフォーク」
• 「煙たいバーで演奏するジャズトリオ」

ランダムサンプル： 🎲 ボタンをクリックしてランダムな例の説明を読み込みます。

カスタムモード

カスタムモードはすべての生成パラメータの完全な制御を提供します。

使用方法：

1. 生成モードラジオボタンで「カスタム」を選択
2. Captionと歌詞フィールドを手動で入力
3. オプションのメタデータを設定（BPM、キー、Durationなど）
4. オプションで フォーマット をクリックしてLMを使用して入力を強化
5. 必要に応じて高度な設定を構成
6. 音楽を生成 をクリックしてオーディオを作成

---

タスクタイプ

text2music（デフォルト）

テキスト説明および/または歌詞から音楽を生成。

ユースケース： プロンプトに基づいて新しい音楽をゼロから作成。

必須入力： Captionまたは歌詞（少なくとも1つ）

cover

既存のオーディオを構造を維持しながらスタイルを変更して変換。

ユースケース： 異なるスタイルのカバーバージョンを作成。

必須入力：

• ソースオーディオ（オーディオアップロードセクションでアップロード）
• ターゲットスタイルを説明するCaption

重要なパラメータ： オーディオカバー強度（0.0-1.0）

• 高い値は元の構造をより多く維持
• 低い値はより創造的な自由を許可

repaint

オーディオの特定の時間セグメントを再生成。

ユースケース： 生成された音楽の特定のセクションを修正または変更。

必須入力：

• ソースオーディオ
• リペイント開始（秒）
• リペイント終了（秒、ファイル終端には-1）
• 希望するコンテンツを説明するCaption

lego（Baseモデルのみ）

既存のオーディオのコンテキストで特定の楽器トラックを生成。

ユースケース： バッキングトラックに楽器レイヤーを追加。

必須入力：

• ソースオーディオ
• トラック名（ドロップダウンから選択）
• トラック特性を説明するCaption

利用可能なトラック： vocals、backing_vocals、drums、bass、guitar、keyboard、percussion、strings、synth、fx、brass、woodwinds

extract（Baseモデルのみ）

ミックスオーディオから特定の楽器トラックを抽出/分離。

ユースケース： ステム分離、楽器の分離。

必須入力：

• ソースオーディオ
• 抽出するトラック名

complete（Baseモデルのみ）

指定された楽器で部分的なトラックを完成。

ユースケース： 不完全な作品の自動アレンジ。

必須入力：

• ソースオーディオ
• トラック名（複数選択）
• 希望するスタイルを説明するCaption

---

入力パラメータ

必須入力

タスクタイプ

ドロップダウンから生成タスクを選択。選択されたタスクに基づいて指示フィールドが自動的に更新されます。

オーディオアップロード

フィールド	説明
参照オーディオ	スタイル参照用のオプションオーディオ
ソースオーディオ	cover、repaint、lego、extract、completeタスクに必須
コードに変換	ソースオーディオから5Hzセマンティックコードを抽出

LMコードヒント

事前計算されたオーディオセマンティックコードをここに貼り付けて生成をガイドできます。トランスクライブ ボタンを使用してコードを分析しメタデータを抽出します。

音楽キャプション

希望する音楽のテキスト説明。以下について具体的に：

• ジャンルとスタイル
• 楽器
• ムードと雰囲気
• テンポ感（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アダプターを作成するためのツールを提供します。

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

ステップ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をより具体的にする

メモリ不足：

• バッチサイズを減らす
• CPUオフロードを有効化
• LMバッチチャンクサイズを減らす

LMが機能しない：

• 初期化時に「5Hz LMを初期化」がチェックされていたことを確認
• 有効なLMモデルパスが選択されていることを確認
• vllmまたはPyTorchバックエンドが利用可能であることを確認

---

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

Gradioインターフェースは標準的なWebショートカットをサポート：

• Tab - 入力フィールド間を移動
• Enter - テキスト入力を送信
• Space - チェックボックスを切り替え

---

言語サポート

インターフェースは複数のUI言語をサポート：

• 英語 (en)
• 中国語 (zh)
• 日本語 (ja)

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

---

詳細については以下を参照：

• メインREADME：../../README.md
• REST APIドキュメント：API.md
• Python推論API：INFERENCE.md