diff --git a/.gitignore b/.gitignore index baf43aa..81a461b 100644 --- a/.gitignore +++ b/.gitignore @@ -200,5 +200,4 @@ ui/components_demo.py data_sampler_demo.py pipeline_ace_step_demo.py *.wav -start.sh exps/* \ No newline at end of file diff --git a/README.md b/README.md index 3240b4d..4533350 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ - [✨ Features](#-features) - [📦 Installation](#-installation) -- [⚡ Quick Start (Windows)](#-quick-start-windows) +- [⚡ Quick Start](#-quick-start) - [🚀 Usage](#-usage) - [📱 User Interface Guide](#-user-interface-guide) - [🔨 Train](#-train) @@ -260,19 +260,30 @@ pip3 install torch torchvision torchaudio --index-url https://download.pytorch.o pip install -e . ``` +If you also intend to train or fine-tune, install the training extras as well (they are not needed for inference): +```bash +pip install -e ".[train]" +``` + The ACE-Step application is now installed. The GUI works on Windows, macOS, and Linux. For instructions on how to run it, please see the [Usage](#-usage) section. -## ⚡ Quick Start (Windows) +## ⚡ Quick Start -This repository ships with [`start.bat`](./start.bat), which does everything for you: checks Python, creates the virtual environment, installs PyTorch with CUDA support, installs ACE-Step, and launches the web UI. +This repository ships with launcher scripts that do everything for you: check Python, create the virtual environment, install PyTorch with the right backend, install ACE-Step, and launch the web UI. -Just double-click `start.bat`, or run it from a command prompt: +**Windows** — double-click [`start.bat`](./start.bat), or run it from a command prompt: ```bat start.bat ``` +**Linux / macOS** — run [`start.sh`](./start.sh): + +```bash +./start.sh +``` + The first run takes a few minutes (roughly 3 GB of packages are downloaded). Model weights (~8 GB) are fetched automatically on the first generation. Later runs start immediately. ### Script flags @@ -296,7 +307,7 @@ Flags can be combined, for example: start.bat --lowvram --listen --port 7870 ``` -Defaults (port, GPU index, checkpoint path) live in the settings block at the top of `start.bat`. +Defaults (port, GPU index, checkpoint path) live in the settings block at the top of each script. In `start.sh` they can also be overridden with environment variables (`PORT=7870 ./start.sh`). On macOS the scripts install the MPS build of PyTorch and pass `--bf16 false` automatically. ## 🚀 Usage @@ -321,6 +332,22 @@ acestep --checkpoint_path /path/to/checkpoint --port 7865 --device_id 0 --share If you are using macOS, please use `--bf16 false` to avoid errors. +#### 🖥️ Command Line Generation + +To generate without the web UI, use `infer.py`: + +```bash +python infer.py \ + --prompt "synth-pop, female vocal, warm analog synths, 110 bpm" \ + --lyrics_file my_song.txt \ + --duration 120 --steps 60 --seed 7 \ + --format mp3 --output_path outputs/my_song.mp3 +``` + +Run `python infer.py --help` for the full list. The main options are `--prompt`, `--lyrics` / `--lyrics_file`, `--duration`, `--steps`, `--guidance_scale`, `--scheduler`, `--cfg_type`, `--omega_scale`, `--seed`, `--format` and `--output_path`; the runtime flags (`--bf16`, `--cpu_offload`, `--overlapped_decode`, `--torch_compile`, `--device_id`) match the ones the GUI takes. + +With no `--prompt`, the script keeps its original behaviour and generates from a random example in `examples/input_params`. + #### 🔍 API Usage If you intend to integrate ACE-Step as a library into your own Python projects, you can install the latest version directly from GitHub using the following pip command. diff --git a/README_RU.md b/README_RU.md index 6cdf67d..965c2a2 100644 --- a/README_RU.md +++ b/README_RU.md @@ -22,7 +22,7 @@ - [✨ Возможности](#-возможности) - [📦 Установка](#-установка) -- [⚡ Быстрый старт на Windows](#-быстрый-старт-на-windows) +- [⚡ Быстрый старт](#-быстрый-старт) - [🚀 Использование](#-использование) - [📱 Описание интерфейса](#-описание-интерфейса) - [🔨 Обучение](#-обучение) @@ -261,19 +261,30 @@ pip3 install torch torchvision torchaudio --index-url https://download.pytorch.o pip install -e . ``` +Если планируете обучать или дообучать модель, поставьте дополнительно зависимости для обучения — для инференса они не нужны: +```bash +pip install -e ".[train]" +``` + На этом установка завершена. Графический интерфейс работает на Windows, macOS и Linux. Как запускать — см. раздел [Использование](#-использование). -## ⚡ Быстрый старт на Windows +## ⚡ Быстрый старт -В репозитории есть скрипт [`start.bat`](./start.bat), который делает всё сам: проверяет Python, создаёт виртуальное окружение, ставит PyTorch с поддержкой CUDA, устанавливает ACE-Step и запускает веб-интерфейс. +В репозитории есть скрипты запуска, которые делают всё сами: проверяют Python, создают виртуальное окружение, ставят PyTorch с нужным бэкендом, устанавливают ACE-Step и запускают веб-интерфейс. -Достаточно дважды кликнуть по `start.bat` — или запустить из командной строки: +**Windows** — достаточно дважды кликнуть по [`start.bat`](./start.bat) или запустить из командной строки: ```bat start.bat ``` +**Linux / macOS** — запустите [`start.sh`](./start.sh): + +```bash +./start.sh +``` + При первом запуске установка займёт несколько минут (скачивается около 3 ГБ пакетов). Веса модели (~8 ГБ) докачаются автоматически при первой генерации. Последующие запуски стартуют сразу. ### Флаги скрипта @@ -284,6 +295,7 @@ start.bat | `--cpu` | Запуск на процессоре, без CUDA (очень медленно, но работает без видеокарты NVIDIA) | | `--share` | Публичная ссылка Gradio для доступа снаружи | | `--port ` | Порт веб-интерфейса (по умолчанию 7865) | +| `--device ` | Номер видеокарты (по умолчанию 0) | | `--listen` | Слушать `0.0.0.0`, чтобы зайти с других устройств в локальной сети | | `--reinstall` | Полностью пересоздать виртуальное окружение с нуля | | `--update` | Обновить зависимости в существующем окружении | @@ -296,7 +308,7 @@ start.bat start.bat --lowvram --listen --port 7870 ``` -Настройки по умолчанию (порт, номер GPU, путь к весам модели) задаются в блоке `==== НАСТРОЙКИ ====` в начале файла `start.bat`. +Настройки по умолчанию (порт, номер GPU, путь к весам модели) задаются в блоке `==== НАСТРОЙКИ ====` в начале каждого скрипта. В `start.sh` их можно переопределить переменными окружения (`PORT=7870 ./start.sh`). На macOS скрипт сам ставит сборку PyTorch с MPS и передаёт `--bf16 false`. ## 🚀 Использование @@ -321,6 +333,22 @@ acestep --checkpoint_path /path/to/checkpoint --port 7865 --device_id 0 --share На macOS используйте `--bf16 false`, чтобы избежать ошибок. +#### 🖥️ Генерация из командной строки + +Чтобы генерировать без веб-интерфейса, используйте `infer.py`: + +```bash +python infer.py \ + --prompt "synth-pop, female vocal, warm analog synths, 110 bpm" \ + --lyrics_file my_song.txt \ + --duration 120 --steps 60 --seed 7 \ + --format mp3 --output_path outputs/my_song.mp3 +``` + +Полный список — `python infer.py --help`. Основные опции: `--prompt`, `--lyrics` / `--lyrics_file`, `--duration`, `--steps`, `--guidance_scale`, `--scheduler`, `--cfg_type`, `--omega_scale`, `--seed`, `--format`, `--output_path`. Флаги режима работы (`--bf16`, `--cpu_offload`, `--overlapped_decode`, `--torch_compile`, `--device_id`) те же, что у графического интерфейса. + +Без `--prompt` скрипт ведёт себя как раньше и генерирует по случайному примеру из `examples/input_params`. + #### 🔍 Использование как библиотеки Если вы хотите встроить ACE-Step как библиотеку в собственный Python-проект, можно поставить последнюю версию прямо из GitHub. diff --git a/start.bat b/start.bat index a789ca9..b45f32c 100644 --- a/start.bat +++ b/start.bat @@ -68,8 +68,15 @@ if "%DO_REINSTALL%"=="1" ( ) REM ------------------------- поиск Python ------------------------- -if exist "%VENV_PY%" goto venv_ready +REM Рабочим считаем окружение, в котором есть и python, и pip: каталог от +REM прерванной установки выглядит как готовый, но валится дальше с невнятной +REM ошибкой про интернет. +if not exist "%VENV_PY%" goto venv_create +"%VENV_PY%" -m pip --version >nul 2>&1 && goto venv_ready +echo [1/4] Окружение "%VENV_DIR%" неработоспособно, пересоздаю... +rmdir /s /q "%VENV_DIR%" +:venv_create echo [1/4] Ищу подходящий Python... set "SYS_PY=" for %%V in (3.12 3.11 3.10 3.13) do ( @@ -92,14 +99,9 @@ echo Найден Python %PYVER% (%SYS_PY%) echo [1/4] Создаю виртуальное окружение в "%VENV_DIR%"... %SYS_PY% -m venv "%VENV_DIR%" -if errorlevel 1 ( - echo [ОШИБКА] Не удалось создать виртуальное окружение. - goto fail -) -if not exist "%VENV_PY%" ( - echo [ОШИБКА] Виртуальное окружение создано некорректно: нет "%VENV_PY%". - goto fail -) +if errorlevel 1 goto venv_failed +if not exist "%VENV_PY%" goto venv_failed +"%VENV_PY%" -m pip --version >nul 2>&1 || goto venv_failed set "FRESH_VENV=1" :venv_ready @@ -205,9 +207,12 @@ if "%OPT_LOWVRAM%"=="1" set "ARGS=%ARGS% --cpu_offload true --overlapped_decode echo [4/4] Запускаю веб-интерфейс... echo. -echo Адрес: http://%SERVER_NAME%:%PORT% if "%OPT_LOWVRAM%"=="1" echo Режим: экономия видеопамяти -echo Первый запуск скачивает веса модели (~8 ГБ) - наберитесь терпения. +echo Идёт загрузка моделей, это занимает время. +echo При первом запуске дополнительно скачиваются веса (~8 ГБ). +echo. +echo Интерфейс будет доступен на http://%SERVER_NAME%:%PORT% +echo когда ниже появится строка "Running on local URL". echo Остановить: Ctrl+C в этом окне. echo. @@ -240,6 +245,13 @@ echo. goto success REM ------------------------- завершение ------------------------- +:venv_failed +echo. +echo [ОШИБКА] Не удалось создать рабочее виртуальное окружение в "%VENV_DIR%". +echo Переустановите Python с https://www.python.org/downloads/, +echo отметив "Add Python to PATH", и запустите "%SCRIPT_NAME% --reinstall". +goto fail + :fail echo. pause diff --git a/start.sh b/start.sh new file mode 100755 index 0000000..d174700 --- /dev/null +++ b/start.sh @@ -0,0 +1,233 @@ +#!/usr/bin/env bash +# ACE-Step: настройка окружения и запуск веб-интерфейса на Linux / macOS. +# Windows-аналог — start.bat. +set -uo pipefail + +cd "$(dirname "$0")" + +# ============================ НАСТРОЙКИ ============================ +VENV_DIR="${VENV_DIR:-venv}" # каталог виртуального окружения +PORT="${PORT:-7865}" # порт веб-интерфейса +SERVER_NAME="${SERVER_NAME:-127.0.0.1}" # 0.0.0.0 — доступ из локальной сети +DEVICE_ID="${DEVICE_ID:-0}" # номер видеокарты +CHECKPOINT_PATH="${CHECKPOINT_PATH:-}" # пусто — скачать в ~/.cache/ace-step +# Сборка PyTorch под CUDA (cu126 / cu124 / cu121). Только для Linux. +TORCH_INDEX="${TORCH_INDEX:-https://download.pytorch.org/whl/cu126}" +# ================================================================== + +SCRIPT_NAME="$(basename "$0")" +OPT_LOWVRAM=0 +OPT_CPU=0 +OPT_SHARE=0 +DO_SETUP_ONLY=0 +DO_REINSTALL=0 +DO_UPDATE=0 + +usage() { + cat < Порт веб-интерфейса (по умолчанию $PORT) + --device Номер видеокарты (по умолчанию $DEVICE_ID) + --listen Слушать 0.0.0.0 (доступ из локальной сети) + --reinstall Пересоздать виртуальное окружение с нуля + --update Обновить зависимости + --setup Только установка, без запуска + --help Эта справка + +Настройки по умолчанию — в блоке НАСТРОЙКИ в начале файла, +их можно переопределить переменными окружения (PORT=7870 ./$SCRIPT_NAME). + +EOF +} + +die() { + echo + echo "[ОШИБКА] $*" >&2 + exit 1 +} + +while [ $# -gt 0 ]; do + case "$1" in + --help|-h) usage; exit 0 ;; + --lowvram) OPT_LOWVRAM=1; shift ;; + --cpu) OPT_CPU=1; shift ;; + --share) OPT_SHARE=1; shift ;; + --setup) DO_SETUP_ONLY=1; shift ;; + --reinstall) DO_REINSTALL=1; shift ;; + --update) DO_UPDATE=1; shift ;; + --listen) SERVER_NAME="0.0.0.0"; shift ;; + --port) PORT="${2:?--port требует значение}"; shift 2 ;; + --device) DEVICE_ID="${2:?--device требует значение}"; shift 2 ;; + *) + echo "[ОШИБКА] Неизвестный аргумент: $1" >&2 + echo "Запустите ./$SCRIPT_NAME --help для справки." >&2 + exit 1 ;; + esac +done + +echo +echo "==========================================" +echo " ACE-Step - генерация музыки" +echo "==========================================" +echo + +case "$(uname -s)" in + Darwin) IS_MAC=1 ;; + *) IS_MAC=0 ;; +esac + +VENV_PY="$PWD/$VENV_DIR/bin/python" + +# Рабочим считаем окружение, в котором есть и python, и pip: каталог от +# прерванной установки (или venv без ensurepip) выглядит как готовый, но валится +# дальше с невнятной ошибкой. +venv_ok() { + [ -x "$VENV_PY" ] && "$VENV_PY" -m pip --version >/dev/null 2>&1 +} + +venv_failed() { + echo >&2 + echo "[ОШИБКА] Не удалось создать рабочее виртуальное окружение в \"$VENV_DIR\"." >&2 + if [ "$IS_MAC" = 0 ] && command -v apt >/dev/null 2>&1; then + echo "На Debian/Ubuntu для этого нужен отдельный пакет:" >&2 + echo " sudo apt install python3-venv" >&2 + fi + exit 1 +} + +if [ "$DO_REINSTALL" = 1 ] && [ -d "$VENV_DIR" ]; then + echo "[1/4] Удаляю старое окружение \"$VENV_DIR\"..." + rm -rf "$VENV_DIR" +fi + +# ------------------------- поиск Python ------------------------- +if venv_ok; then + echo "[1/4] Виртуальное окружение найдено: $VENV_DIR" +else + if [ -d "$VENV_DIR" ]; then + echo "[1/4] Окружение \"$VENV_DIR\" неработоспособно, пересоздаю..." + rm -rf "$VENV_DIR" + fi + echo "[1/4] Ищу подходящий Python..." + SYS_PY="" + for candidate in python3.12 python3.11 python3.10 python3.13 python3; do + if command -v "$candidate" >/dev/null 2>&1 && + "$candidate" -c 'import sys; sys.exit(0 if sys.version_info >= (3,10) else 1)' 2>/dev/null; then + SYS_PY="$candidate" + break + fi + done + [ -n "$SYS_PY" ] || die "Не найден Python 3.10 или новее. Установите его и повторите." + + echo " Найден Python $("$SYS_PY" -c 'import sys; print(sys.version.split()[0])') ($SYS_PY)" + echo "[1/4] Создаю виртуальное окружение в \"$VENV_DIR\"..." + "$SYS_PY" -m venv "$VENV_DIR" || venv_failed + venv_ok || venv_failed +fi + +# ------------------------- зависимости ------------------------- +echo "[2/4] Проверяю зависимости..." + +NEED_TORCH=0 +"$VENV_PY" -c "import importlib.util,sys; sys.exit(0 if importlib.util.find_spec('torch') else 1)" 2>/dev/null || NEED_TORCH=1 + +# Проверяем именно установку пакета: каталог acestep лежит рядом со скриптом, +# поэтому find_spec('acestep') сработал бы и без установленных зависимостей. +NEED_ACESTEP=0 +"$VENV_PY" -c "import importlib.metadata as md, importlib.util as u, sys; md.version('ace_step'); sys.exit(0 if u.find_spec('click') and u.find_spec('gradio') else 1)" 2>/dev/null || NEED_ACESTEP=1 + +if [ "$DO_UPDATE" = 1 ]; then + NEED_TORCH=1 + NEED_ACESTEP=1 +fi + +if [ "$NEED_TORCH" = 1 ] || [ "$NEED_ACESTEP" = 1 ]; then + echo " Обновляю pip..." + "$VENV_PY" -m pip install --upgrade pip setuptools wheel --quiet || + die "Не удалось обновить pip. Проверьте подключение к интернету." +fi + +if [ "$NEED_TORCH" = 1 ]; then + if [ "$IS_MAC" = 1 ]; then + # На macOS колёса с PyPI уже собраны с поддержкой MPS. + echo " Устанавливаю PyTorch (macOS/MPS). Это займёт несколько минут..." + "$VENV_PY" -m pip install --upgrade torch torchvision torchaudio + elif [ "$OPT_CPU" = 1 ]; then + echo " Устанавливаю PyTorch для CPU. Это займёт несколько минут..." + "$VENV_PY" -m pip install --upgrade torch torchvision torchaudio \ + --index-url https://download.pytorch.org/whl/cpu + else + echo " Устанавливаю PyTorch с поддержкой CUDA. Это займёт несколько минут..." + "$VENV_PY" -m pip install --upgrade torch torchvision torchaudio --index-url "$TORCH_INDEX" + fi || die "Не удалось установить PyTorch. Если у вас другая версия CUDA, поменяйте TORCH_INDEX." +fi + +if [ "$NEED_ACESTEP" = 1 ]; then + echo " Устанавливаю ACE-Step и зависимости..." + "$VENV_PY" -m pip install -e . || die "Не удалось установить ACE-Step." +fi + +if [ "$OPT_LOWVRAM" = 1 ] && [ "$IS_MAC" = 0 ]; then + if ! "$VENV_PY" -c "import importlib.util,sys; sys.exit(0 if importlib.util.find_spec('triton') else 1)" 2>/dev/null; then + echo " Режим экономии VRAM: устанавливаю triton..." + "$VENV_PY" -m pip install triton --quiet || + echo "[ВНИМАНИЕ] triton не установился, --torch_compile может не заработать." + fi +fi + +# ------------------------- проверка устройства ------------------------- +echo "[3/4] Проверяю устройство..." +BF16=true +if [ "$OPT_CPU" = 1 ]; then + echo " Принудительный режим CPU. Генерация будет очень медленной." + DEVICE_ID=-1 + BF16=false +elif [ "$IS_MAC" = 1 ]; then + # На MPS bfloat16 приводит к ошибкам, см. README. + echo " macOS: используется MPS, bf16 отключён." + BF16=false +else + GPUINFO="$("$VENV_PY" -c "import torch; print((torch.cuda.get_device_name(0) + ' - ' + str(round(torch.cuda.get_device_properties(0).total_memory/1073741824, 1)) + ' GB VRAM') if torch.cuda.is_available() else 'NO_CUDA')" 2>/dev/null || echo NO_CUDA)" + if [ "$GPUINFO" = "NO_CUDA" ]; then + echo + echo "[ВНИМАНИЕ] CUDA недоступна - модель будет работать на процессоре (очень медленно)." + echo "Если у вас есть видеокарта NVIDIA, обновите драйвер и переустановите PyTorch:" + echo " ./$SCRIPT_NAME --update" + echo + else + echo " $GPUINFO" + fi +fi + +if [ "$DO_SETUP_ONLY" = 1 ]; then + echo + echo "Установка завершена. Для запуска выполните ./$SCRIPT_NAME" + exit 0 +fi + +# ------------------------- запуск ------------------------- +ARGS=(--port "$PORT" --server_name "$SERVER_NAME" "--device_id=$DEVICE_ID" --bf16 "$BF16") +[ -n "$CHECKPOINT_PATH" ] && ARGS+=(--checkpoint_path "$CHECKPOINT_PATH") +[ "$OPT_SHARE" = 1 ] && ARGS+=(--share true) +if [ "$OPT_LOWVRAM" = 1 ]; then + ARGS+=(--cpu_offload true --overlapped_decode true) + [ "$IS_MAC" = 0 ] && ARGS+=(--torch_compile true) +fi + +echo "[4/4] Запускаю веб-интерфейс..." +echo +[ "$OPT_LOWVRAM" = 1 ] && echo " Режим: экономия видеопамяти" +echo " Идёт загрузка моделей, это занимает время." +echo " При первом запуске дополнительно скачиваются веса (~8 ГБ)." +echo +echo " Интерфейс будет доступен на http://$SERVER_NAME:$PORT" +echo " когда ниже появится строка \"Running on local URL\"." +echo " Остановить: Ctrl+C в этом окне." +echo + +exec "$VENV_PY" -m acestep.gui "${ARGS[@]}"