Install Guide

Como Instalar o ACE-Step Localmente

Guia completo de configuração para Windows, macOS e Linux — incluindo solução dos erros mais comuns.

Última atualização: Fevereiro 2026

Requisitos do Sistema

ComponentMinimumRecommended
GPUNVIDIA RTX 2080 (8GB VRAM)NVIDIA RTX 3090/4090 (24GB VRAM)
CPUIntel i7-8700 / AMD Ryzen 7 3700XIntel i9-12900K / AMD Ryzen 9 5900X
RAM16GB DDR432GB+ DDR4
Storage20GB SSD50GB+ NVMe SSD
CUDA Version11.812.1
Python3.93.10 or 3.11
OSWindows 10, macOS 12, Ubuntu 20.04Ubuntu 22.04 LTS (best performance)

Etapas de Instalação

  1. 1

    Instalar Conda ou Miniconda

    Baixe e instale Miniconda de conda.io. Isso gerencia seu ambiente Python e evita conflitos de dependências.

  2. 2

    Clonar o Repositório

    Execute: 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
  3. 3

    Criar Ambiente Conda

    Execute: conda env create -f environment.yml && conda activate ace-step

    conda env create -f environment.yml
conda activate ace-step
  4. 4

    Instalar PyTorch com CUDA

    Para 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
  5. 5

    Baixar Pesos do Modelo

    Execute: python download_models.py para buscar o checkpoint do modelo (~15GB) do HuggingFace.

    python download_models.py
  6. 6

    Iniciar a Interface Web

    Execute: python app.py para iniciar a interface web Gradio em http://localhost:7860

    python app.py

Otimização de Desempenho

Para geração mais rápida, use precisão FP16 (sinalizador --fp16) em GPUs compatíveis. Instale xformers para habilitar atenção xFormers e obter melhoria de velocidade de 30-40%.

pip install xformers
python app.py --fp16

Problemas Comuns e Soluções

Erro de Memória Insuficiente (OOM)

Se você encontrar erros CUDA OOM, tente habilitar a quantização de 8 bits adicionando --quantize int8 ao seu comando de inicialização. Alternativamente, habilite o descarregamento de CPU com --cpu-offload.

python app.py --quantize int8
# or
python app.py --cpu-offload --fp16

Conflitos de Dependências

ACE-Step requer versões específicas de PyTorch e CUDA. Sempre use o arquivo de ambiente conda fornecido ou requirements.txt.

Porta Já em Uso

Se a porta 7860 estiver ocupada, adicione --port 7861 (ou qualquer porta disponível) ao comando de inicialização do Gradio.

python app.py --port 7861

Caminho do Modelo Não Encontrado

Certifique-se de ter espaço em disco suficiente (~15GB para pesos do modelo). Execute o script de download a partir do diretório raiz do projeto.

FAQ

Pule a Configuração Completamente

Não gosta de comandos de terminal e o inferno das dependências? FM9 oferece geração de música IA compatível com ACE-Step no seu navegador. Sem GPU, sem configuração, sem esperar.

Começar a Criar Gratuitamente

Artigos Relacionados