Windows、macOS 和 Linux 的完整安装指南——包括最常见错误的排查方法。
最后更新：2026年2月
| Component | Minimum | Recommended |
|---|---|---|
| GPU | NVIDIA RTX 2080 (8GB VRAM) | NVIDIA RTX 3090/4090 (24GB VRAM) |
| CPU | Intel i7-8700 / AMD Ryzen 7 3700X | Intel i9-12900K / AMD Ryzen 9 5900X |
| RAM | 16GB DDR4 | 32GB+ DDR4 |
| Storage | 20GB SSD | 50GB+ NVMe SSD |
| CUDA Version | 11.8 | 12.1 |
| Python | 3.9 | 3.10 or 3.11 |
| OS | Windows 10, macOS 12, Ubuntu 20.04 | Ubuntu 22.04 LTS (best performance) |
从 conda.io 下载并安装 Miniconda。这用于管理你的 Python 环境并防止依赖冲突。
运行：git clone https://github.com/ace-step/ACE-Step.git && cd ACE-Step
git clone https://github.com/ace-step/ACE-Step.git
cd ACE-Step运行：conda env create -f environment.yml && conda activate ace-step
conda env create -f environment.yml
conda activate ace-step对于 CUDA 11.8：pip install torch==2.0.1+cu118 -f https://download.pytorch.org/whl/cu118/torch_stable.html
pip install torch==2.0.1+cu118 torchvision==0.15.2+cu118 torchaudio==2.0.2+cu118 \
-f https://download.pytorch.org/whl/cu118/torch_stable.html运行：python download_models.py，从 HuggingFace 获取约 15GB 的模型检查点。
python download_models.py运行：python app.py，在 http://localhost:7860 启动 Gradio Web 界面。
python app.py为获得更快的生成速度，在支持的 GPU 上使用 FP16 精度（--fp16 标志）。通过安装 xformers 启用 xFormers 注意力机制，可提速 30-40%。对于 12GB 以下显存的 GPU，请始终使用 8 位量化。
pip install xformers
python app.py --fp16如果遇到 CUDA OOM 错误，尝试通过在启动命令中添加 --quantize int8 来启用 8 位量化。或者，使用 --cpu-offload 启用 CPU 卸载，将部分层移至系统内存。
python app.py --quantize int8
# or
python app.py --cpu-offload --fp16ACE-Step 需要特定版本的 PyTorch 和 CUDA。请始终使用提供的 conda 环境文件或 requirements.txt。混合使用 pip 和 conda 安装经常导致冲突。
如果端口 7860 繁忙，在 Gradio 启动命令中添加 --port 7861（或任何可用端口）。
python app.py --port 7861确保磁盘空间充足（模型权重约 15GB）。从项目根目录（而非子目录）运行下载脚本。