ACE-Step-1.5/docs/ja/INSTALL.md

ACE-Step 1.5 インストールガイド

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

---

目次

• 動作要件
• クイックスタート（全プラットフォーム）
• 起動スクリプト
• Windows ポータブルパッケージ
• AMD / ROCm GPU
• Intel GPU
• CPUのみモード
• Linux の注意事項
• 環境変数 (.env)
• コマンドラインオプション
• モデルダウンロード
• どのモデルを選ぶべき？
• 開発

---

動作要件

項目	要件
Python	3.11-3.12（安定版、プレリリース版は不可） 注意： Windows 上の ROCm は Python 3.12 が必要です
GPU	CUDA GPU 推奨。MPS / ROCm / Intel XPU / CPU もサポート
VRAM	DiTのみモード ≥4GB、LLM+DiT ≥6GB
ディスク	コアモデルに約10GB

---

クイックスタート（全プラットフォーム）

1. uv のインストール（パッケージマネージャー）

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. クローン & インストール

git clone https://github.com/ACE-Step/ACE-Step-1.5.git
cd ACE-Step-1.5
uv sync

3. 起動

Gradio Web UI（推奨）：

uv run acestep

REST API サーバー：

uv run acestep-api

Python を直接使用（Conda / venv / システム Python）：

# まず環境をアクティベートしてから：
python acestep/acestep_v15_pipeline.py          # Gradio UI
python acestep/api_server.py                     # REST API

初回実行時にモデルが自動ダウンロードされます。http://localhost:7860（Gradio）または http://localhost:8001（API）を開いてください。

---

🚀 起動スクリプト

全プラットフォーム対応のすぐに使える起動スクリプトです。これらのスクリプトは環境検出、依存関係のインストール、アプリケーションの起動を自動的に処理します。すべてのスクリプトはデフォルトで起動時に更新チェックを行います（設定変更可能）。

利用可能なスクリプト

プラットフォーム	スクリプト	説明
Windows	start_gradio_ui.bat	Gradio Web UI を起動（CUDA）
Windows	start_api_server.bat	REST API サーバーを起動（CUDA）
Windows	start_gradio_ui_rocm.bat	Gradio Web UI を起動（AMD ROCm）
Windows	start_api_server_rocm.bat	REST API サーバーを起動（AMD ROCm）
Linux	start_gradio_ui.sh	Gradio Web UI を起動（CUDA）
Linux	start_api_server.sh	REST API サーバーを起動（CUDA）
macOS	start_gradio_ui_macos.sh	Gradio Web UI を起動（MLX）
macOS	start_api_server_macos.sh	REST API サーバーを起動（MLX）

Windows

# Gradio Web UI を起動（NVIDIA CUDA）
start_gradio_ui.bat

# REST API サーバーを起動（NVIDIA CUDA）
start_api_server.bat

# Gradio Web UI を起動（AMD ROCm）
start_gradio_ui_rocm.bat

# REST API サーバーを起動（AMD ROCm）
start_api_server_rocm.bat

ROCm ユーザー： ROCm スクリプト（start_gradio_ui_rocm.bat、start_api_server_rocm.bat）は HSA_OVERRIDE_GFX_VERSION、ACESTEP_LM_BACKEND=pt、MIOPEN_FIND_MODE=FAST およびその他の ROCm 固有の環境変数を自動設定します。CUDA/ROCm wheel の競合を避けるため、別の venv_rocm 仮想環境を使用します。

Linux

# 実行権限を付与（初回のみ）
chmod +x start_gradio_ui.sh start_api_server.sh

# Gradio Web UI を起動
./start_gradio_ui.sh

# REST API サーバーを起動
./start_api_server.sh

注意： Git はシステムのパッケージマネージャーでインストールする必要があります（sudo apt install git、sudo yum install git、sudo pacman -S git）。

macOS（Apple Silicon / MLX）

macOS スクリプトはネイティブの Apple Silicon アクセラレーション（M1/M2/M3/M4）のために MLX バックエンドを使用します。

# 実行権限を付与（初回のみ）
chmod +x start_gradio_ui_macos.sh start_api_server_macos.sh

# MLX バックエンドで Gradio Web UI を起動
./start_gradio_ui_macos.sh

# MLX バックエンドで REST API サーバーを起動
./start_api_server_macos.sh

macOS スクリプトはネイティブの Apple Silicon アクセラレーションのために ACESTEP_LM_BACKEND=mlx と --backend mlx を自動設定し、非 arm64 マシンでは PyTorch バックエンドにフォールバックします。

注意： Git は xcode-select --install または brew install git でインストールしてください。

スクリプトの機能

• 起動時の更新チェック（デフォルトで有効、設定変更可能）
• 自動環境検出（ポータブル Python または uv）
• 必要に応じて uv を自動インストール
• ダウンロードソースの設定（HuggingFace/ModelScope）
• モデルとパラメータのカスタマイズ

設定の変更方法

すべての設定可能なオプションは、各スクリプトの先頭で変数として定義されています。カスタマイズするには、テキストエディタでスクリプトを開き、変数の値を変更してください。

例：UI 言語を中国語に変更し、1.7B LM モデルを使用する

Windows (.bat)	Linux / macOS (.sh)
start_gradio_ui.bat で以下の行を見つけます： set LANGUAGE=en set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-0.6B 以下のように変更します： set LANGUAGE=zh set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-1.7B	start_gradio_ui.sh で以下の行を見つけます： LANGUAGE="en" LM_MODEL_PATH="--lm_model_path acestep-5Hz-lm-0.6B" 以下のように変更します： LANGUAGE="zh" LM_MODEL_PATH="--lm_model_path acestep-5Hz-lm-1.7B"

例：起動時の更新チェックを無効にする

Windows (.bat)	Linux / macOS (.sh)
REM set CHECK_UPDATE=true set CHECK_UPDATE=false	# CHECK_UPDATE="true" CHECK_UPDATE="false"

例：コメントアウトされたオプションを有効にする — コメントプレフィックス（.bat は REM、.sh は #）を削除します：

Windows (.bat)	Linux / macOS (.sh)
変更前： REM set SHARE=--share 変更後： set SHARE=--share	変更前： # SHARE="--share" 変更後： SHARE="--share"

主な設定可能オプション：

オプション	Gradio UI	API サーバー	説明
LANGUAGE	✅	—	UI 言語：en、zh、he、ja
PORT	✅	✅	サーバーポート（デフォルト：7860 / 8001）
SERVER_NAME / HOST	✅	✅	バインドアドレス（127.0.0.1 または 0.0.0.0）
CHECK_UPDATE	✅	✅	起動時の更新チェック（true / false）
CONFIG_PATH	✅	—	DiT モデル（acestep-v15-turbo など）
LM_MODEL_PATH	✅	✅	LM モデル（acestep-5Hz-lm-0.6B / 1.7B / 4B）
DOWNLOAD_SOURCE	✅	✅	ダウンロードソース（huggingface / modelscope）
SHARE	✅	—	公開 Gradio リンクを作成
INIT_LLM	✅	—	LLM の強制オン/オフ（true / false / auto）
OFFLOAD_TO_CPU	✅	—	低 VRAM GPU 向け CPU オフロード

更新 & メンテナンスツール

スクリプト（Windows）	スクリプト（Linux/macOS）	用途
check_update.bat	check_update.sh	GitHub から更新をチェック
merge_config.bat	merge_config.sh	更新後にバックアップされた設定をマージ
install_uv.bat	install_uv.sh	uv パッケージマネージャーをインストール
quick_test.bat	quick_test.sh	環境セットアップをテスト

更新ワークフロー：

# Windows                          # Linux / macOS
check_update.bat                    ./check_update.sh
merge_config.bat                    ./merge_config.sh

---

🪟 Windows ポータブルパッケージ

Windows ユーザー向けに、依存関係がプリインストールされたポータブルパッケージを提供しています：

1. ダウンロードして解凍：ACE-Step-1.5.7z
2. python_embedded に全依存関係がプリインストール済み
3. 要件： CUDA 12.8

クイックスタートスクリプト

スクリプト	説明
start_gradio_ui.bat	Gradio Web UI を起動
start_api_server.bat	REST API サーバーを起動

両スクリプトは自動環境検出、自動 uv インストール、ダウンロードソース設定、Git 更新チェック（オプション）、モデル・パラメータのカスタマイズに対応しています。

設定

start_gradio_ui.bat：

REM UI言語 (en, zh, he, ja)
set LANGUAGE=ja

REM ダウンロードソース (auto, huggingface, modelscope)
set DOWNLOAD_SOURCE=--download-source huggingface

REM Git更新チェック (true/false)
set CHECK_UPDATE=true

REM モデル設定
set CONFIG_PATH=--config_path acestep-v15-turbo
set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-1.7B

更新 & メンテナンス

スクリプト	用途
check_update.bat	GitHub から更新をチェック
merge_config.bat	更新後にバックアップされた設定をマージ
install_uv.bat	uv パッケージマネージャーをインストール
quick_test.bat	環境セットアップをテスト

---

AMD / ROCm GPU

⚠️ uv run acestep は CUDA PyTorch wheels をインストールするため、既存の ROCm 環境を上書きする可能性があります。

推奨ワークフロー

# 1. 仮想環境を作成してアクティベート
python -m venv .venv
source .venv/bin/activate

# 2. ROCm 対応 PyTorch をインストール
pip install torch --index-url https://download.pytorch.org/whl/rocm6.0

# 3. ACE-Step をインストール
pip install -e .

# 4. サービスを起動
python -m acestep.acestep_v15_pipeline --port 7680

GPU 検出のトラブルシューティング

「No GPU detected, running on CPU」と表示される場合：

1. 診断ツールを実行：python scripts/check_gpu.py
2. RDNA3 GPU の場合、HSA_OVERRIDE_GFX_VERSION を設定：

GPU	値
RX 7900 XT/XTX, RX 9070 XT	export HSA_OVERRIDE_GFX_VERSION=11.0.0
RX 7800 XT, RX 7700 XT	export HSA_OVERRIDE_GFX_VERSION=11.0.1
RX 7600	export HSA_OVERRIDE_GFX_VERSION=11.0.2

3. Windows では start_gradio_ui_rocm.bat / start_api_server_rocm.bat を使用
4. ROCm インストールを確認：rocm-smi

Linux（cachy-os / RDNA4）

詳細は ACE-Step1.5-Rocm-Manual-Linux.md を参照してください。

---

Intel GPU

項目	詳細
テスト済みデバイス	Windows ノートPC、Ultra 9 285H 内蔵グラフィックス
オフロード	デフォルトで無効
コンパイル & 量子化	デフォルトで有効
LLM 推論	サポート（acestep-5Hz-lm-0.6B でテスト済み）
nanovllm アクセラレーション	Intel GPU では未サポート
テスト環境	PyTorch 2.8.0（Intel Extension for PyTorch）

注意：2分以上の音声生成時、LLM 推論速度が低下する場合があります。Intel ディスクリート GPU は動作が期待されますが、まだテストされていません。

---

CPUのみモード

ACE-Step は CPU で推論のみ実行できますが、速度は大幅に遅くなります。

• CPU でのトレーニング（LoRA を含む）は推奨されません。
• 低 VRAM システムでは、DiTのみモード（LLM 無効）がサポートされています。

GPU がない場合：

• クラウド GPU プロバイダーの利用
• 推論のみのワークフロー
• ACESTEP_INIT_LLM=false で DiTのみモードを使用

---

Linux の注意事項

Python 3.11 プレリリース版の問題

一部の Linux ディストリビューション（Ubuntu を含む）には Python 3.11.0rc1 プレリリース版が同梱されており、vLLM バックエンドでセグメンテーションフォルトを引き起こす可能性があります。

推奨： 安定版 Python（≥ 3.11.12）を使用してください。Ubuntu では deadsnakes PPA からインストールできます。

Python のアップグレードができない場合、PyTorch バックエンドを使用：

uv run acestep --backend pt

---

環境変数 (.env)

cp .env.example .env   # コピーして編集

主要な変数

変数	値	説明
ACESTEP_INIT_LLM	auto / true / false	LLM 初期化モード
ACESTEP_CONFIG_PATH	モデル名	DiT モデルパス
ACESTEP_LM_MODEL_PATH	モデル名	LM モデルパス
ACESTEP_DOWNLOAD_SOURCE	auto / huggingface / modelscope	ダウンロードソース
ACESTEP_API_KEY	文字列	API 認証キー

LLM 初期化 (ACESTEP_INIT_LLM)

処理フロー：GPU 検出 → ACESTEP_INIT_LLM オーバーライド → モデル読み込み

値	動作
auto（または空）	GPU 自動検出結果を使用（推奨）
true / 1 / yes	GPU 検出後に LLM を強制有効化（OOM の可能性あり）
false / 0 / no	強制無効化、純粋な DiT モード

シナリオ別 .env の例：

# 自動モード（推奨）
ACESTEP_INIT_LLM=auto

# 低 VRAM GPU で強制有効化
ACESTEP_INIT_LLM=true
ACESTEP_LM_MODEL_PATH=acestep-5Hz-lm-0.6B

# LLM を無効化して高速生成
ACESTEP_INIT_LLM=false

---

コマンドラインオプション

Gradio UI (acestep)

オプション	デフォルト	説明
--port	7860	サーバーポート
--server-name	127.0.0.1	サーバーアドレス（ネットワークアクセスには 0.0.0.0）
--share	false	公開 Gradio リンクを作成
--language	en	UI 言語：en、zh、he、ja
--init_service	false	起動時にモデルを自動初期化
--init_llm	auto	LLM 初期化：true / false / 省略で自動
--config_path	auto	DiT モデル（例：acestep-v15-turbo）
--lm_model_path	auto	LM モデル（例：acestep-5Hz-lm-1.7B）
--offload_to_cpu	auto	CPU オフロード（GPU ティアに基づいて自動設定）
--download-source	auto	モデルソース：auto / huggingface / modelscope
--enable-api	false	Gradio UI と同時に REST API エンドポイントを有効化

例：

# ネットワーク公開 + 日本語 UI
uv run acestep --server-name 0.0.0.0 --share --language ja

# 起動時にモデルを事前初期化
uv run acestep --init_service true --config_path acestep-v15-turbo

# ModelScope からダウンロード
uv run acestep --download-source modelscope

---

📥 モデルダウンロード

初回実行時にモデルが HuggingFace または ModelScope から自動ダウンロードされます。

CLI ダウンロード

uv run acestep-download                              # メインモデルをダウンロード
uv run acestep-download --all                         # 全モデルをダウンロード
uv run acestep-download --download-source modelscope  # ModelScope から
uv run acestep-download --model acestep-v15-sft       # 特定のモデル
uv run acestep-download --list                        # 利用可能な全モデルを一覧表示

手動ダウンロード (huggingface-cli)

# メインモデル（vae, Qwen3-Embedding-0.6B, acestep-v15-turbo, acestep-5Hz-lm-1.7B）
huggingface-cli download ACE-Step/Ace-Step1.5 --local-dir ./checkpoints

# オプションモデル
huggingface-cli download ACE-Step/acestep-5Hz-lm-0.6B --local-dir ./checkpoints/acestep-5Hz-lm-0.6B
huggingface-cli download ACE-Step/acestep-5Hz-lm-4B --local-dir ./checkpoints/acestep-5Hz-lm-4B

共有モデルディレクトリ

複数の ACE-Step インストール（トレーナー、異なるバージョンなど）がある場合、モデルディレクトリを共有して重複ダウンロードを避け、ディスク容量を節約できます：

# シェルプロファイル（~/.bashrc、~/.zshrc など）に追加
export ACESTEP_CHECKPOINTS_DIR=~/ace-step-models

すべてのインストールが同じモデルファイルを使用します。.env ファイルで設定することもできます。

利用可能なモデル

モデル	説明	HuggingFace
Ace-Step1.5（メイン）	コア：vae, Qwen3-Embedding-0.6B, acestep-v15-turbo, acestep-5Hz-lm-1.7B	リンク
acestep-5Hz-lm-0.6B	軽量 LM（0.6B パラメータ）	リンク
acestep-5Hz-lm-4B	大規模 LM（4B パラメータ）	リンク
acestep-v15-base	ベース DiT モデル	リンク
acestep-v15-sft	SFT DiT モデル	リンク
acestep-v15-turbo-shift1	Turbo DiT（shift1）	リンク
acestep-v15-turbo-shift3	Turbo DiT（shift3）	リンク
acestep-v15-turbo-continuous	Turbo DiT（continuous shift 1-5）	リンク

---

💡 どのモデルを選ぶべき？

ACE-Step は GPU の VRAM に自動適応します。UI は検出された GPU ティアに基づいてすべての設定（LM モデル、バックエンド、オフロード、量子化）を事前構成します：

GPU VRAM	推奨 DiT	推奨 LM モデル	バックエンド	備考
≤6GB	2B turbo	なし（DiTのみ）	—	LM はデフォルトで無効；INT8 量子化 + 完全 CPU オフロード
6-8GB	2B turbo	acestep-5Hz-lm-0.6B	pt	軽量 LM、PyTorch バックエンド
8-16GB	2B turbo/sft	0.6B / 1.7B	vllm	8-12GB は 0.6B、12-16GB は 1.7B
16-20GB	2B sft または XL turbo	acestep-5Hz-lm-1.7B	vllm	XL は 20GB 未満で CPU オフロードが必要
20-24GB	XL turbo/sft	acestep-5Hz-lm-1.7B	vllm	XL はオフロード不要；4B LM 利用可能
≥24GB	XL sft（extract/lego/complete には xl-base）	acestep-5Hz-lm-4B	vllm	最高品質、すべてのモデルがオフロードなしで動作

📖 GPU 互換性の詳細（ティアテーブル、時間制限、バッチサイズ、アダプティブ UI デフォルト、メモリ最適化）は GPU 互換性ガイド を参照してください。

---

開発

# 依存関係を追加
uv add package-name
uv add --dev package-name

# 全依存関係を更新
uv sync --upgrade