Skip to content

Latest commit

 

History

History
355 lines (248 loc) · 12.2 KB

INSTALL.md

File metadata and controls

355 lines (248 loc) · 12.2 KB

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

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

目次

動作要件

項目 要件
Python 3.11+（安定版、プレリリース版は不可）
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 ポータブルパッケージ

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

  1. ダウンロードして解凍：ACE-Step-1.5.7z
  2. python_embeded に全依存関係がプリインストール済み
  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
  1. Windows では start_gradio_ui_rocm.bat を使用
  2. 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 オフロード（VRAM < 16GB で自動有効化）
--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

利用可能なモデル

モデル 説明 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 に自動適応します：

GPU VRAM 推奨 LM モデル 備考
≤6GB なし（DiTのみ） メモリ節約のため LM はデフォルトで無効
6-12GB acestep-5Hz-lm-0.6B 軽量、バランスが良い
12-16GB acestep-5Hz-lm-1.7B より高品質
≥16GB acestep-5Hz-lm-4B 最高品質と音声理解能力

📖 GPU 互換性の詳細（時間制限、バッチサイズ、メモリ最適化）は GPU 互換性ガイド を参照してください。

開発

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

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