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

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

目次

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

動作要件

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

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

# 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 モデルを使用する

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

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"

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

REM set CHECK_UPDATE=true
set CHECK_UPDATE=false

# CHECK_UPDATE="true"
CHECK_UPDATE="false"

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

REM set SHARE=--share

set SHARE=--share

# SHARE="--share"

SHARE="--share"

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

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

更新ワークフロー：

# 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

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

両スクリプトは自動環境検出、自動 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

更新 & メンテナンス

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 を設定：

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

注意：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   # コピーして編集

主要な変数

LLM 初期化 (ACESTEP_INIT_LLM)

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

シナリオ別 .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)

例：

# ネットワーク公開 + 日本語 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 ファイルで設定することもできます。

利用可能なモデル

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

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

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

開発

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

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