From 7f441defccdd2e88f0978e225798691f74b324a6 Mon Sep 17 00:00:00 2001 From: Leonid Pershin Date: Tue, 8 Sep 2026 20:31:18 +0300 Subject: [PATCH] feat: add start.sh for Linux/macOS, harden both launchers start.sh mirrors start.bat: finds Python 3.10+, creates the venv, installs PyTorch (CUDA index on Linux, the MPS build on macOS, or the CPU index with --cpu), installs ACE-Step, reports the device and launches the UI. Same flags, and the defaults can also come from the environment (PORT=7870 ./start.sh). On macOS it passes --bf16 false, which the README already calls for. Dropped start.sh from .gitignore, where it sat among the upstream author's local scratch files. Both launchers also gain two fixes found while testing on WSL: - A venv is only accepted if pip works in it, not merely if the interpreter exists. A directory left by an interrupted install looked ready and then failed several steps later with a misleading "check your internet connection". Such a venv is now recreated, and if creation fails on Debian/Ubuntu the error points at python3-venv, which is the actual cause there. - The launch banner announced the URL as if the server were already up, while model loading still had a minute to go. It now says the interface will be available once "Running on local URL" appears. Co-Authored-By: Claude Opus 5 --- .gitignore | 1 - README.md | 37 ++++++-- README_RU.md | 38 +++++++-- start.bat | 34 +++++--- start.sh | 233 +++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 321 insertions(+), 22 deletions(-) create mode 100755 start.sh 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[@]}"