Stable Audio Tools 保姆级部署教程：Stability AI 开源音频生成训练与推理工具包，本地跑通文本生成音频

本文所有命令与配置均照搬 Stability-AI/stable-audio-tools 官方仓库 README（main 分支）原文，未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

Stable Audio Tools 是 Stability AI 官方开源的音频生成模型训练与推理代码库（官方 README 副标题："Training and inference code for audio generation models"）。它是 Stability AI 在发布 stable-audio-open-1.0 等开源文本到音频模型时同步放出的工程基座，包含模型配置加载、推理脚本、Gradio 网页界面、PyTorch Lightning 多 GPU 训练管线，以及训练后"拆包"（unwrap）权重的工具。

项目在 GitHub（Stability-AI/stable-audio-tools）持续活跃维护（核验日期 2026-11-01），官方明确要求 PyTorch 2.5 或更高版本（为支持 Flash Attention 与 Flex Attention），开发环境使用 Python 3.10，并官方推荐使用 uv 进行快速、可复现的依赖管理。仓库本身不提供 Docker 镜像，也不提供后台常驻/开机自启的官方方式，因此本教程完全按官方 README 的原生命令给出。

二、功能拆解

按官方 README，Stable Audio Tools 的核心能力如下：

功能	说明（官方 README 原文要点）
模型推理	通过 `--pretrained-name stabilityai/stable-audio-open-1.0` 直接从 Hugging Face 加载官方权重
Gradio 网页界面	`run_gradio.py` 提供浏览器交互界面，可加载 Hugging Face 预训练模型或本地 ckpt
多模型类型	`model_type` 支持 `autoencoder`、`diffusion_uncond`、`diffusion_cond`、`diffusion_cond_inpaint`、`diffusion_autoencoder`、`lm`
训练管线	基于 PyTorch Lightning，支持多 GPU、多节点、DeepSpeed ZeRO Stage 2、梯度累积
模型拆包	`unwrap_model.py` 将训练 wrapper ckpt 拆成仅含模型本体的 ckpt，供推理/微调使用
数据集	支持本地音频目录与 Amazon S3 上的 WebDataset（见 docs/datasets.md）
W&B 日志	训练过程接入 Weights & Biases 记录 loss 与 demo

三、官方/GitHub 链接

GitHub 仓库：https://github.com/Stability-AI/stable-audio-tools
官方预训练模型（Hugging Face）：https://huggingface.co/stabilityai/stable-audio-open-1.0
uv 文档：https://docs.astral.sh/uv/
Flash Attention：https://github.com/Dao-AILab/flash-attention
Weights & Biases：https://wandb.ai/
数据集配置文档：https://github.com/Stability-AI/stable-audio-tools/blob/main/docs/datasets.md

四、环境要求

官方 README 明确的硬性要求：

Python：3.10（官方"Development for the repo is done in Python 3.10"）
PyTorch：≥ 2.5（官方原文："Requires PyTorch 2.5 or later for Flash Attention and Flex Attention support"）
包管理：官方推荐 uv（也可用 pip 直接安装）
GPU： 官方未给出最低显存数字，但 Stable Audio Open 1.0 是扩散模型，实际推理建议至少 8GB 显存（官方未写明，此为使用层面建议，不属官方要求）
操作系统： 官方未限定操作系统；Linux 是最常见的训练/推理环境，macOS 可推理但 Flash Attention 仅 NVIDIA GPU 可用
可选： Flash Attention（官方"recommended for performance"）、Weights & Biases 账号（训练必需）、FFmpeg（音频处理常见依赖，README 未强制）

五、部署步骤

方式 A：uv 安装（官方推荐）

步骤 1：安装 uv

pip install uv

逐段解释：pip install uv 通过 pip 安装 Astral 官方的 uv 包管理器；也可按 uv 官方文档（https://docs.astral.sh/uv/getting-started/installation/）用其他方式安装。

预期输出参考： pip 安装进度条，结束时输出 Successfully installed uv-x.x.x。

步骤 2：克隆仓库并进入目录

git clone https://github.com/Stability-AI/stable-audio-tools.git
cd stable-audio-tools

逐段解释：git clone 克隆官方仓库；cd 进入项目根目录，后续所有 uv sync、uv run 命令都必须在该目录下执行（官方 README 中 --config-file 参数说明："required if running train.py from a directory other than the repo root"，意味着从仓库根目录运行是官方默认约定）。

预期输出参考： git 输出 Cloning into 'stable-audio-tools'... 与进度计数。

步骤 3：安装依赖（按用途三选一）

# Inference only
uv sync

# Training
uv sync --extra train

# Everything (training + Gradio UI)
uv sync --extra train --extra ui

逐段解释：uv sync 依据仓库根目录的 pyproject.toml 与 uv.lock 创建一个隔离的虚拟环境并安装锁定版本的依赖；--extra train 额外安装训练依赖组；--extra ui 额外安装 Gradio 界面依赖组。仅做推理用第一条；要跑 Gradio Web 界面必须选第三条（--extra ui）。

预期输出参考： uv 输出 Resolved N packages ... Installed N packages in X.XXs，并在仓库下创建 .venv/ 目录。

步骤 4（可选，官方推荐）：安装 Flash Attention

官方原文："Flash Attention is recommended for performance. Follow the installation instructions in the Flash Attention repository to install it after running uv sync."

按 Flash Attention 仓库官方说明安装（本教程不替代其官方步骤）。

方式 B：pip 直接安装（官方 alternative）

官方 README 同时给出 pip 直接安装命令：

pip install "stable-audio-tools[train]"

逐段解释：pip install "stable-audio-tools[train]" 从 PyPI 安装 stable-audio-tools 包并附带 train 可选依赖组。该方式适用于不需要 clone 仓库源码、仅作为库调用的场景；若要修改源码或运行仓库根目录的 train.py / run_gradio.py 脚本，仍推荐方式 A 的 git clone + uv sync。

六、配置参数详解

1. Gradio 界面启动参数（官方 README「Interface」一节原文）

run_gradio.py 接受以下命令行参数：

参数	说明
`--pretrained-name`	Hugging Face 仓库名（如 `stabilityai/stable-audio-open-1.0`）；优先加载仓库内 `model.safetensors`，其次 `model.ckpt`；与 `--model-config`/`--ckpt-path` 二选一
`--model-config`	本地模型的 config 文件路径
`--ckpt-path`	本地未拆包模型 checkpoint 路径
`--pretransform-ckpt-path`	可选；替换模型中的 pretransform，用于测试微调过的 decoder
`--share`	设为 true 时生成 Gradio 公网分享链接
`--username` 与 `--password`	成对使用，为 Gradio demo 设置登录账号密码
`--model-half`	设为 true 时将模型权重转半精度

2. 训练脚本 train.py 可选参数（官方 README「Additional training flags」原文）

参数	默认值	说明
`--config-file`	仓库根 `defaults.ini`	从非仓库根目录运行 train.py 时必填
`--pretransform-ckpt-path`	无	latent diffusion 等模型加载预训练 autoencoder，需未拆包 ckpt
`--save-dir`	无	保存 checkpoint 的目录
`--checkpoint-every`	10000	每隔多少 step 保存一次 checkpoint
`--batch-size`	8	每 GPU 样本数，按显存尽量调大
`--num-gpus`	1	每节点 GPU 数
`--num-nodes`	1	GPU 节点数
`--accum-batches`	无	梯度累积 batch 数，小显存扩大有效 batch size
`--strategy`	ddp（num_gpus>1 时）/ None	多 GPU 策略；`deepspeed` 启用 DeepSpeed ZeRO Stage 2
`--precision`	16	训练浮点精度
`--num-workers`	无	DataLoader CPU worker 数
`--seed`	无	PyTorch RNG 种子，用于确定性训练

3. 模型 config 顶层字段（官方 README「Model config」原文）

model_type：autoencoder / diffusion_uncond / diffusion_cond / diffusion_cond_inpaint / diffusion_autoencoder / lm
sample_size：训练/推理音频长度（采样点数）
sample_rate：采样率（Hz）
audio_channels：声道数，默认 2，单声道设 1
model：按 model_type 变化的具体模型配置
training：按 model_type 变化的训练配置

七、启动与运维

启动 Gradio 界面（官方原命令）：

uv run python run_gradio.py --pretrained-name stabilityai/stable-audio-open-1.0

逐段解释：uv run 在 uv 创建的虚拟环境中运行命令；python run_gradio.py 启动 Gradio Web UI；--pretrained-name stabilityai/stable-audio-open-1.0 直接从 Hugging Face 拉取官方预训练权重（首次运行需在 Hugging Face 上接受该模型条款）。

预期输出参考： Gradio 启动后输出 Running on local URL: http://0.0.0.0:7860 之类的本地地址（官方 README 未给出具体端口输出文本；Gradio 默认端口为 7860，属 Gradio 框架默认行为，非本项目官方硬编码）。

训练（官方原命令）：

uv run python train.py --dataset-config /path/to/config ...

或官方示例：

python3 ./train.py --dataset-config /path/to/dataset/config --model-config /path/to/model/config --name harmonai_train

--name 设置 Weights & Biases 项目名。训练前需先执行 wandb login 登录。

模型拆包（官方原命令）：

python3 ./unwrap_model.py --model-config /path/to/model/config --ckpt-path /path/to/wrapped/ckpt --name model_unwrap

逐段解释：训练产生的 ckpt 包含 discriminator、EMA、optimizer 等 training wrapper 状态，体积大；该脚本输出仅含模型本体的 ckpt，供推理、作为 pretransform、或部分初始化微调使用。

后台常驻 / 开机自启： 官方 README 未提供任何 systemd、supervisor、Docker 或后台常驻方案。如确需长期运行，可基于 Linux 通用机制（如 nohup uv run python run_gradio.py ... & 或 systemd unit）自行托管——此为操作系统层面的通用做法，不属官方文档内容。
修改端口： 官方 README 未提供 --port 参数；Gradio 框架本身支持 server_port，但本项目官方未在 run_gradio.py 参数表中列出，故不建议自创。
数据持久化： Hugging Face 模型权重默认缓存在 ~/.cache/huggingface/（Hugging Face 库默认行为）；训练 checkpoint 按 --save-dir 指定目录保存。
查看日志： 训练日志同步输出到终端与 Weights & Biases 控制台（官方要求训练前 wandb login）。

八、实操验证

首次使用前，前往 https://huggingface.co/stabilityai/stable-audio-open-1.0 登录 Hugging Face 账号并接受模型条款（官方 README："once you've accepted the terms for the model on Hugging Face"）。
在项目根目录执行：

python3 ./run_gradio.py --pretrained-name stabilityai/stable-audio-open-1.0

浏览器打开终端输出的本地地址（Gradio 默认 http://127.0.0.1:7860）。
在 Gradio 界面的文本框输入一段描述（如"soft rain on a window"），点击生成，等待数秒至数十秒（取决于 GPU）后界面中出现可播放的音频播放器。
验证本地 ckpt：若已有未拆包 ckpt，改用 --model-config /path/to/config --ckpt-path /path/to/ckpt 启动，界面应正常加载模型并生成音频。

预期看到： Gradio 网页可访问、文本框可输入、生成后输出可播放音频。官方 README 未给出截图，故不虚构界面细节。

登录与安全（重要）

官方默认登录状态： 默认无账号密码。run_gradio.py 默认启动公开访问的 Gradio 界面。
设置登录（官方参数）： 如需加访问控制，启动时成对传入 --username 与 --password：

python3 ./run_gradio.py --pretrained-name stabilityai/stable-audio-open-1.0 --username demo --password 你的强密码

登录地址： 浏览器访问 Gradio 监听地址（默认 http://127.0.0.1:7860）。
首次登录改密： 官方未提供界面内改密流程；修改密码需退出进程、更换 --password 参数后重启。
密码存放位置： 仅作为命令行参数存在于启动命令/启动脚本中，官方未提供配置文件方式。
--share 风险： 官方 --share 参数会生成一个 *.gradio.live 的公网临时链接；公网暴露时必须配合 --username/--password，否则任何人都可访问你的 GPU 资源。
安全提醒：部署完成后，若将 Gradio 暴露到公网，必须通过 --username/--password 设置强密码，并慎用 --share。

九、故障排查

案例 1：RuntimeError: FlashAttention is only supported on CUDA >= 11.6 或类似 CUDA 版本不符

报错原文（常见形式）：RuntimeError: FlashAttention is only supported on CUDA >= 11.6 或 Triton Error while importing flash_attn
报错原因：官方 README 要求 PyTorch 2.5+ 以支持 Flash/Flex Attention；若安装的 PyTorch CUDA 版本与系统 CUDA 驱动不匹配，Flash Attention 会加载失败。
分步解决：① nvidia-smi 查看驱动支持的 CUDA 版本；② 按 https://pytorch.org/get-started/locally/ 重新安装匹配 CUDA 版本的 PyTorch 2.5+；③ 重新 uv sync；④ 若仍失败，可先不装 Flash Attention（官方仅说"recommended"，非必需）。

案例 2：Hugging Face 模型下载 401 / 403 You must agree to share your contact information

报错原文（常见形式）：401 Client Error. ... You must change your settings at https://huggingface.co/... 或 EntryNotFound / Repository not found
报错原因：官方 README 明确要求"once you've accepted the terms for the model on Hugging Face"——未在网页上接受模型条款、或未 huggingface-cli login 配置 token。
分步解决：① 浏览器登录 Hugging Face，打开 https://huggingface.co/stabilityai/stable-audio-open-1.0 点击"Agree and access repository"；② 命令行执行 huggingface-cli login 粘贴 read token；③ 重新运行 run_gradio.py。

案例 3：从非仓库根目录运行 train.py 报 config 文件找不到

报错原文（常见形式）：FileNotFoundError: defaults.ini 或训练启动后立即退出
报错原因：官方 README --config-file 参数说明："The path to the defaults.ini file in the repo root, required if running train.py from a directory other than the repo root"。
分步解决：① cd stable-audio-tools 仓库根目录后再运行；② 或显式传入 --config-file /path/to/stable-audio-tools/defaults.ini。

案例 4：--extra ui 未安装导致 Gradio 启动失败 ModuleNotFoundError: No module named 'gradio'

报错原因：仅执行了 uv sync（推理 only），未加 --extra ui。
分步解决：在仓库根目录执行 uv sync --extra train --extra ui（官方第三条 sync 命令），再重新 uv run python run_gradio.py ...。

十、升级、回滚与卸载

升级（官方未提供专门升级命令，按仓库原生 git + uv 机制）：

git pull
uv sync --extra train --extra ui

逐段解释：git pull 拉取最新 main 分支代码；uv sync 依据新版 uv.lock 同步依赖。官方 README 未给出额外升级命令，此为 git/uv 项目的标准更新方式。

回滚： 官方未提供一键回滚命令；可在仓库内 git checkout <旧 tag 或 commit> 后重新 uv sync。

卸载： 本项目以仓库源码 + uv 虚拟环境形式安装，卸载即删除仓库目录（含 .venv/）：rm -rf stable-audio-tools；pip 方式安装者执行 pip uninstall stable-audio-tools。Hugging Face 模型权重缓存于 ~/.cache/huggingface/，可单独删除以释放磁盘（官方未提供卸载命令，此为通用清理）。

十一、商用许可合规说明

许可证：MIT License（仓库根 LICENSE 文件首行："MIT License / Copyright (c) 2023 Stability AI"）。
MIT 许可允许自由使用、修改、分发与商用（包括闭源商业产品），但必须在软件副本中保留原始版权声明与许可文本。
注意：模型权重与代码许可不同——stable-audio-open-1.0 模型权重在 Hugging Face 上采用 Stability AI Community License（非本仓库代码许可），商用前须单独阅读 https://huggingface.co/stabilityai/stable-audio-open-1.0 的模型 license；本仓库代码本身是 MIT。
训练产生的衍生模型权重的许可归属由使用者自行决定，官方代码不约束权重许可。