docs: sync KB — ace-step-local-network.md

development/ace-step-local-network.md

@@ -0,0 +1,95 @@
+---
+title: "ACE-Step 1.5 — Local Network Setup Guide"
+description: "How to run ACE-Step AI music generator on the local network via Gradio UI or REST API, including .env configuration and startup notes."
+type: guide
+domain: development
+tags: [ace-step, ai, music-generation, gradio, gpu, cuda]
+---
+
+# ACE-Step 1.5 — Local Network Setup
+
+ACE-Step is an open-source AI music generation model. This guide covers running it on the workstation and serving the Gradio web UI to the local network.
+
+## Location
+
+```
+/mnt/NV2/Development/ACE-Step-1.5/
+```
+
+Cloned from GitHub. Uses `uv` for dependency management — the `.venv` is created automatically on first run.
+
+## Quick Start (Gradio UI)
+
+```bash
+cd /mnt/NV2/Development/ACE-Step-1.5
+./start_gradio_ui.sh
+```
+
+Accessible from any device on the network at **http://10.10.0.41:7860** (or whatever the workstation IP is).
+
+## .env Configuration
+
+The `.env` file in the project root persists settings across git updates. Current config:
+
+```env
+SERVER_NAME=0.0.0.0
+PORT=7860
+LANGUAGE=en
+```
+
+### Key Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SERVER_NAME` | `127.0.0.1` | Set to `0.0.0.0` for LAN access |
+| `PORT` | `7860` | Gradio UI port |
+| `LANGUAGE` | `en` | UI language (`en`, `zh`, `he`, `ja`). **Must be set** — empty value causes `unbound variable` error with the launcher's `set -u` |
+| `ACESTEP_CONFIG_PATH` | `acestep-v15-turbo` | DiT model variant |
+| `ACESTEP_LM_MODEL_PATH` | `acestep-5Hz-lm-0.6B` | Language model for lyrics/prompts |
+| `ACESTEP_INIT_LLM` | `auto` | `auto` / `true` / `false` — auto detects based on VRAM |
+| `CHECK_UPDATE` | `true` | Set to `false` to skip interactive update prompt (useful for background/automated starts) |
+
+See `.env.example` for the full list.
+
+## REST API Server (Alternative)
+
+For programmatic access instead of the web UI:
+
+```bash
+cd /mnt/NV2/Development/ACE-Step-1.5
+./start_api_server.sh
+```
+
+Default: `http://127.0.0.1:8001`. To serve on LAN, edit `start_api_server.sh` line 12:
+
+```bash
+HOST="0.0.0.0"
+```
+
+API docs available at `http://<ip>:8001/docs`.
+
+## Hardware Profile (Workstation)
+
+- **GPU**: NVIDIA RTX 4080 SUPER (16 GB VRAM)
+- **Tier**: 16GB class — auto-enables CPU offload, INT8 quantization, LLM
+- **Max batch (with LM)**: 4
+- **Max batch (without LM)**: 8
+- **Max duration (with LM)**: 480s (8 min)
+- **Max duration (without LM)**: 600s (10 min)
+
+## Startup Behavior
+
+1. Loads `.env` configuration
+2. Checks for git updates (interactive prompt — set `CHECK_UPDATE=false` to skip)
+3. Creates `.venv` via `uv sync` if missing (slow on first run)
+4. Runs legacy NVIDIA torch compatibility check
+5. Loads DiT model → quantizes to INT8 → loads LM → allocates KV cache
+6. Launches Gradio with queue for multi-user support
+
+Full startup takes ~30-40 seconds after first run.
+
+## Gotchas
+
+- **LANGUAGE must be set in `.env`**: The system `$LANGUAGE` locale variable can be empty, causing the launcher to crash with `unbound variable` due to `set -u`. Always include `LANGUAGE=en` in `.env`.
+- **Update prompt blocks background execution**: If running headlessly or from a script, set `CHECK_UPDATE=false` to avoid the interactive Y/N prompt.
+- **Model downloads**: First run downloads ~4-5 GB of model weights from HuggingFace. Subsequent runs use cached checkpoints in `./checkpoints/`.