docs/ja/LoRA_Training_Tutorial.md

ACE-Step 1.5 LoRA トレーニングチュートリアル

ハードウェア要件

VRAM	説明
16 GB（最低）	通常は使用可能ですが、長い楽曲ではメモリ不足になる場合があります
20 GB 以上（推奨）	フルレングスの楽曲に対応可能。トレーニング中のVRAM使用量は通常17 GB前後です

ヒント： トレーニング前の前処理段階では、VRAMを解放するためにGradioを複数回再起動する必要があります。具体的なタイミングは以降の手順で説明します。

免責事項

本チュートリアルでは、ナユタン星人 (NayutalieN) のアルバム ナユタン星からの物体Y（全13曲）をデモとして使用し、500エポック（バッチサイズ1）でトレーニングを行いました。本チュートリアルはLoRAファインチューニング技術を理解するための教育目的のみに使用されます。ご自身のオリジナル作品でLoRAをトレーニングしてください。

開発者として、私はナユタン星人の楽曲が大好きで、そのアルバムの一つを例として選びました。権利者の方で本チュートリアルが正当な権利を侵害していると思われる場合は、すぐにご連絡ください。有効な通知を受け次第、関連コンテンツを削除いたします。

技術は合理的かつ合法的に使用されるべきです。アーティストの創作を尊重し、オリジナルアーティストの名誉、権利、利益を損害または傷つける行為は行わないでください。

---

データ準備

ヒント： プログラミングに詳しくない方は、本ドキュメントをClaude Code / Codex CLI / Cursor / Copilotなどのコーディングツールに渡して、作業を代行してもらうことができます。

概要

各楽曲のトレーニングデータには以下が含まれます：

1. 音声ファイル — .mp3、.wav、.flac、.ogg、.opus 形式に対応
2. 歌詞 — 音声ファイルと同名の .lyrics.txt ファイル（後方互換のため .txt も対応）
3. アノテーションデータ — caption、bpm、keyscale、timesignature、language などのメタデータ

アノテーションデータ形式

完全なアノテーションデータをお持ちの場合は、JSONファイルを作成し、音声・歌詞と同じディレクトリに配置できます。ファイル構造は以下の通りです：

dataset/
├── song1.mp3               # 音声
├── song1.lyrics.txt        # 歌詞
├── song1.json              # アノテーション（任意）
├── song1.caption.txt       # キャプション（任意、JSONに含めることも可能）
├── song2.mp3
├── song2.lyrics.txt
├── song2.json
└── ...

JSONファイルの構造（すべてのフィールドは任意）：

{
    "caption": "A high-energy J-pop track with synthesizer leads and fast tempo",
    "bpm": 190,
    "keyscale": "D major",
    "timesignature": "4",
    "language": "ja"
}

アノテーションデータがない場合は、後続のセクションで紹介する方法で取得できます。

---

歌詞

歌詞を音声ファイルと同名の .lyrics.txt ファイルとして保存し、同じディレクトリに配置してください。歌詞の正確性を確認してください。

スキャン時の歌詞ファイル検索優先順位：

1. {ファイル名}.lyrics.txt（推奨）
2. {ファイル名}.txt（後方互換）

歌詞の文字起こし

既存の歌詞テキストがない場合は、以下のツールで文字起こしが可能です：

ツール	構造化タグ	精度	使いやすさ	デプロイ方式
acestep-transcriber	なし	誤字の可能性あり	高難度（モデルのデプロイが必要）	セルフホスト
Gemini	あり	誤字の可能性あり	簡単	有料API
Whisper	なし	誤字の可能性あり	普通	セルフホスト / 有料API
ElevenLabs	なし	誤字の可能性あり	普通	有料API（無料枠あり）

本プロジェクトでは scripts/lora_data_prepare/ に対応する文字起こしスクリプトを提供しています：

• whisper_transcription.py — OpenAI Whisper APIによる文字起こし
• elevenlabs_transcription.py — ElevenLabs Scribe APIによる文字起こし

両スクリプトとも process_folder() メソッドによるフォルダ一括処理に対応しています。

確認とクリーニング（必須）

文字起こしされた歌詞には誤字が含まれる可能性があり、手動で確認・修正する必要があります。

LRC形式の歌詞を使用している場合は、タイムスタンプを除去する必要があります。以下は簡単なクリーニング例です：

import re

def clean_lrc_content(lines):
    """LRCファイルの内容をクリーニングし、タイムスタンプを除去"""
    result = []
    for line in lines:
        line = line.strip()
        if not line:
            continue
        # タイムスタンプを除去 [mm:ss.x] [mm:ss.xx] [mm:ss.xxx]
        cleaned = re.sub(r"\[\d{2}:\d{2}\.\d{1,3}\]", "", line)
        result.append(cleaned)

    # 末尾の空行を除去
    while result and not result[-1]:
        result.pop()

    return result

構造化タグ（任意）

歌詞に構造化タグ（[Verse]、[Chorus] など）が含まれていると、モデルが楽曲構造をより効果的に学習できます。構造化タグがなくてもトレーニングは可能です。

ヒント： Gemini を使用して既存の歌詞に構造化タグを追加できます。

例：

[Intro]
La la la...

[Verse 1]
Walking down the empty street
Echoes dancing at my feet

[Chorus]
We are the stars tonight
Shining through the endless sky

[Bridge]
Close your eyes and feel the sound

---

自動アノテーション

1. BPMとKeyの取得

Key-BPM-Finder を使用してBPMとキーのアノテーションをオンラインで取得します：

1. ウェブページを開き、Browse my files をクリックして処理する音声ファイルを選択します（一度に多すぎるとフリーズする場合があります。分割して処理し、CSVを結合することを推奨）。処理はローカルで行われ、サーバーにはアップロードされません。

2. 処理完了後、Export CSV をクリックしてCSVファイルをダウンロードします。

3. CSVファイルの内容例：

   File,Artist,Title,BPM,Key,Camelot
   song1.wav,,,190,D major,10B
   song2.wav,,,128,A minor,8A
   

4. CSVファイルをデータセットフォルダに配置します。キャプションデータを追加する場合は、Camelot 列の後に新しい列を追加してください。

2. Captionの取得

以下の方法で楽曲のキャプションを取得できます：

• acestep-5Hz-lmを使用（0.6B / 1.7B / 4B）— Gradio UIのAuto Label機能から呼び出し（後続の手順を参照）
• Gemini APIを使用 — スクリプト scripts/lora_data_prepare/gemini_caption.py を参照。process_folder() による一括処理に対応し、各音声ファイルに対して以下を生成します：
  • {ファイル名}.lyrics.txt — 歌詞
  • {ファイル名}.caption.txt — キャプション

---

データの前処理

データの準備が完了したら、Gradio UIを使用してデータの確認と前処理を行います。

重要： 起動スクリプトを使用する場合、サービスの事前初期化を無効にするために起動パラメータを変更する必要があります：

• Windows (start_gradio_ui.bat)：if not defined INIT_SERVICE set INIT_SERVICE=--init_service true を if not defined INIT_SERVICE set INIT_SERVICE=--init_service false に変更
• Linux/macOS (start_gradio_ui.sh)：: "${INIT_SERVICE:=--init_service true}" を : "${INIT_SERVICE:=--init_service false}" に変更

Gradio UIを起動します（起動スクリプトまたは acestep/acestep_v15_pipeline.py を直接実行）。

ステップ 1：モデルの読み込み

• LMでキャプションを生成する場合： 初期化時に使用したいLMモデル（acestep-5Hz-lm-0.6B / 1.7B / 4B）を選択します。

• LMを使用しない場合： LMモデルを選択しないでください。

ステップ 2：データの読み込み

LoRA Training タブに切り替え、データセットディレクトリのパスを入力し、Scan をクリックします。

スキャナーは以下のファイルを自動認識します：

ファイル	説明
*.mp3 / *.wav / *.flac / ...	音声ファイル
{ファイル名}.lyrics.txt（または {ファイル名}.txt）	歌詞
{ファイル名}.caption.txt	キャプション
{ファイル名}.json	アノテーションメタデータ（caption / bpm / keyscale / timesignature / language）
*.csv	BPM / Key の一括アノテーション（Key-BPM-Finderからエクスポート）

ステップ 3：データセットのプレビューと調整

• Duration — 音声ファイルから自動的に読み取り
• Lyrics — 対応する .lyrics.txt ファイルが必要（.txt も対応）
• Labeled — キャプションがある場合は ✅、ない場合は ❌ と表示
• BPM / Key / Caption — JSONまたはCSVファイルから読み込み
• データセットがすべてインストゥルメンタルでない場合は、All Instrumental のチェックを外してください
• Format Lyrics と Transcribe Lyrics は現在無効化されています（acestep-transcriber 未接続のため、LMの直接使用はハルシネーションが発生しやすい）
• Custom Trigger Tag を入力してください（現在は効果が限定的です。Replace Caption 以外であれば問題ありません）
• Genre Ratio はキャプションの代わりにジャンルを使用するサンプルの割合を制御します。現在のLMが生成するジャンル記述はキャプションに遠く及ばないため、0のままにして��ださい

ステップ 4：Auto Label Data

• 既にキャプションがある場合は、このステップをスキップできます
• データにキャプションがない場合は、LM推論で生成できます
• BPM / Key の値が不足している場合は、まず Key-BPM-Finder で取得してください。LMによる直接生成はハルシネーションが発生します

ステップ 5：データのプレビューと編集

必要に応じて、データを一件ずつ確認・修正できます。各データの編集後は必ず保存をクリックしてください。

ステップ 6：データセットの保存

保存パスを入力し、データセットをJSONファイルとして保存します。

ステップ 7：前処理によるTensorファイルの生成

注意： 以前にLMでキャプションを生成し、VRAMが不足している場合は、まずGradioを再起動してVRAMを解放してください。再起動時はLMモデルを選択しないでください。再起動後、保存したJSONファイルのパスを入力して読み込みます。

Tensorファイルの保存パスを入力し、前処理を開始して完了を待ちます。

---

トレーニング

注意： Tensorファイル生成後も、VRAMを解放するためにGradioを再起動することを推奨します。

1. Train LoRA タブに切り替え、Tensorファイルのパスを入力してデータセットを読み込みます。
2. トレーニングパラメータに詳しくない場合は、デフォルト値で問題ありません。

パラメータ参考

パラメータ	説明	推奨値
Max Epochs	データセットのサイズに応じて調整	約100曲 → 500エポック、10〜20曲 → 800エポック（参考値）
Batch Size	VRAMに余裕がある場合は増加可能	1（デフォルト）、VRAMが十分であれば 2 または 4
Save Every N Epochs	チェックポイントの保存間隔	Max Epochsが小さい場合は短く、大きい場合は長く設定

上記の数値は参考値です。実際の状況に応じて調整してください。

3. Start Training をクリックし、トレーニングの完了を待ちます。

---

LoRAの使用

1. トレーニング完了後、Gradioを再起動し、モデルを再読み込みします（LMモデルは選択しないでください）。
2. モデルの初期化完了後、トレーニング済みのLoRAウェイトを読み込みます。
3. 音楽生成を開始します。

おめでとうございます！LoRAトレーニングの全プロセスが完了しました。

---

高度なトレーニング：Side-Step

LoRAトレーニングをより細かく制御したい場合——修正されたタイムステップサンプリング、LoKRアダプター、CLIベースのワークフロー、VRAM最適化、勾配感度分析など——コミュニティ開発の Side-Step ツールキットが高度な代替手段を提供します。ドキュメントは本リポジトリの docs/sidestep/ に収録されています。

トピック	説明
Getting Started	インストール、前提条件、初回セットアップ
End-to-End Tutorial	生音声ファイルから生成までの完全ガイド
Dataset Preparation	JSONスキーマ、音声形式、メタデータフィールド、カスタムタグ
Training Guide	LoRA vs LoKR、修正モード vs バニラモード、ハイパーパラメータガイド
Using Your Adapter	出力ディレクトリ構造、Gradioでの読み込み、LoKRの制限
VRAM Optimization Guide	VRAM最適化戦略とGPUティア別設定
Estimation Guide	ターゲットトレーニングのための勾配感度分析
Shift and Timestep Sampling	トレーニングタイムステップの仕組みとSide-Stepの違い
Preset Management	ビルトインプリセット、保存/読み込み/インポート/エクスポート
The Settings Wizard	ウィザード設定の完全リファレンス
Model Management	チェックポイント構造とファインチューンサポート
Windows Notes	Windows固有のセットアップと回避策