AudioCraft 保姆级部署教程：Meta 开源音频生成库，本地一键跑通 MusicGen / AudioGen / MAGNeT

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

一、项目介绍

AudioCraft 是 Meta AI（FAIR）开源的 PyTorch 音频深度学习研究库（官方 README 原文："AudioCraft is a PyTorch library for deep learning research on audio generation"）。它把 Meta 此前发表的一系列 SOTA 音频生成模型——MusicGen（文本生成音乐）、AudioGen（文本生成音效）、EnCodec（神经音频编解码器）、Multi Band Diffusion、MAGNeT（非自回归文本到音乐/音效）、AudioSeal（音频水印）、MusicGen Style、JASCO（和弦+旋律+鼓条件文本到音乐）——统一到同一套代码框架下，同时提供推理代码与训练代码。

项目在 GitHub（facebookresearch/audiocraft）持续活跃维护（核验日期 2026-11-01），官方明确要求 Python 3.9 与 PyTorch 2.1.0。仓库不提供 Docker 镜像，也不提供后台常驻/开机自启的官方方式，本教程完全按官方 README 原生命令给出。

二、功能拆解

按官方 README「Models」一节，AudioCraft 当前包含的模型与训练代码：

模型	说明	训练代码
MusicGen	SOTA 可控文本到音乐	✅
AudioGen	SOTA 文本到音效	❌（仅推理）
EnCodec	SOTA 高保真神经音频编解码器	✅
Multi Band Diffusion	EnCodec 兼容的扩散解码器	✅
MAGNeT	SOTA 非自回归文本到音乐/音效	❌（仅推理）
AudioSeal	SOTA 音频水印	✅（需 `[wm]` extra）
MusicGen Style	文本+风格到音乐	❌（仅推理）
JASCO	和弦+旋律+鼓条件的高质量文本到音乐	✅

其他能力：官方 API 文档（https://facebookresearch.github.io/audiocraft/api_docs/audiocraft/index.html ）、训练总览文档 docs/TRAINING.md。

三、官方/GitHub 链接

GitHub 仓库：https://github.com/facebookresearch/audiocraft
官方 API 文档：https://facebookresearch.github.io/audiocraft/api_docs/audiocraft/index.html
MusicGen 文档：https://github.com/facebookresearch/audiocraft/blob/main/docs/MUSICGEN.md
AudioGen 文档：https://github.com/facebookresearch/audiocraft/blob/main/docs/AUDIOGEN.md
EnCodec 文档：https://github.com/facebookresearch/audiocraft/blob/main/docs/ENCODEC.md
MAGNeT 文档：https://github.com/facebookresearch/audiocraft/blob/main/docs/MAGNET.md
AudioSeal 文档：https://github.com/facebookresearch/audiocraft/blob/main/docs/WATERMARKING.md
JASCO 文档：https://github.com/facebookresearch/audiocraft/blob/main/docs/JASCO.md
训练总览：https://github.com/facebookresearch/audiocraft/blob/main/docs/TRAINING.md

四、环境要求

官方 README「Installation」一节明确：

Python：3.9（官方原文："AudioCraft requires Python 3.9"）
PyTorch：2.1.0（官方原文："PyTorch 2.1.0"；并特别提示"Best to make sure you have torch installed first, in particular before installing xformers"）
ffmpeg： 官方推荐安装，可用 apt 或 conda（conda install "ffmpeg<5" -c conda-forge）
操作系统： 官方未限定；Linux 是最常见训练/推理环境
GPU： 官方未给出最低显存；MusicGen/MAGNeT 等扩散模型实际推理建议 GPU（CPU 可跑但慢，官方未写明）
可选： xformers（README 注释中提到"before installing xformers"，未列入主安装命令）

五、部署步骤

步骤 1：先安装 PyTorch 2.1.0（官方原命令）

# Best to make sure you have torch installed first, in particular before installing xformers.
# Don't run this if you already have PyTorch installed.
python -m pip install 'torch==2.1.0'

逐段解释：python -m pip 用当前 Python 解释器对应的 pip 执行；'torch==2.1.0' 锁定 PyTorch 2.1.0 版本（AudioCraft 官方要求版本，不要用更新版本）；官方注释明确"如果你已经装了 PyTorch 就别跑这条"。

预期输出参考： pip 下载 torch 及依赖，结束时输出 Successfully installed torch-2.1.0 ...。

步骤 2：安装 setuptools 与 wheel（官方原命令）

# You might need the following before trying to install the packages
python -m pip install setuptools wheel

逐段解释：setuptools 与 wheel 是从源码构建 Python 包所需的打包工具，官方注明"安装包之前可能需要先装"。

预期输出参考： Requirement already satisfied 或 Successfully installed setuptools-xx wheel-xx。

步骤 3：按用途选择下列任一安装方式（官方原命令四选一）

python -m pip install -U audiocraft  # stable release
python -m pip install -U git+https://git@github.com/facebookresearch/audiocraft#egg=audiocraft  # bleeding edge
python -m pip install -e .  # or if you cloned the repo locally (mandatory if you want to train).
python -m pip install -e '.[wm]'  # if you want to train a watermarking model

逐段解释：
- python -m pip install -U audiocraft：从 PyPI 安装稳定版，最简单，仅推理够用。
- python -m pip install -U git+https://...#egg=audiocraft：直接从 GitHub main 分支安装最新 bleeding edge 版。
- python -m pip install -e .：先 git clone 本仓库后在仓库根目录执行；官方明确标注"想训练就必须用这条"（editable 模式，改源码立即生效）。
- python -m pip install -e '.[wm]'：在 editable 基础上额外装 watermarking（AudioSeal 训练）依赖。

预期输出参考： pip 解析并安装 audiocraft 及其依赖，结束时输出 Successfully installed audiocraft-xxx ...。

步骤 4：安装 ffmpeg（官方推荐）

sudo apt-get install ffmpeg
# Or if you are using Anaconda or Miniconda
conda install "ffmpeg<5" -c conda-forge

逐段解释：AudioCraft 处理音频文件时需要 ffmpeg 解码；系统包管理器用 apt，Anaconda 用户用 conda 并锁定 <5 版本。

预期输出参考： apt/conda 下载并安装 ffmpeg 包，结束时无报错。

六、配置参数详解

1. 环境变量（官方 FAQ「Where are the models stored?」原文）

变量	说明
`AUDIOCRAFT_CACHE_DIR`	AudioCraft 模型权重的本地缓存目录；官方原文："Hugging Face stored the model in a specific location, which can be overridden by setting the `AUDIOCRAFT_CACHE_DIR` environment variable"

官方同时指出：
- 其他 Hugging Face 模型的缓存位置请参考 Hugging Face Transformers 文档（https://huggingface.co/docs/transformers/installation#cache-setup ）。
- 若使用依赖 Demucs 的模型（如 musicgen-melody），Demucs 下载位置参考 Torch Hub 文档（https://pytorch.org/docs/stable/hub.html#where-are-my-downloaded-models-saved ）。

2. 模型权重缓存机制

官方 FAQ 明确：模型权重首次推理时自动从 Hugging Face 下载到本地缓存目录，下次推理直接读本地文件。

3. 各模型专属配置

每个模型的 config、example grids、FAQ 在仓库 docs/ 下对应文档（见第三节链接），官方 README 未在顶层罗列配置参数表，使用时按具体模型文档查阅。

七、启动与运维

AudioCraft 是一个 Python 库而非独立服务，没有传统意义上的"启动命令"。官方 README 给出的入口是 Python API：

推理： 在 Python 脚本中 from audiocraft.models import MusicGen 等（详见各模型 docs/xxx.md）。
训练： 用官方训练管线脚本（详见 docs/TRAINING.md 与各模型文档）。
后台常驻 / 开机自启： 官方 README 未提供任何 systemd、Docker、supervisor 方案。AudioCraft 不是服务型软件，是库；若需将其包装为 HTTP 服务，须自行开发（不属官方范畴）。
修改端口： 官方不涉及 Web 端口。
数据持久化： 模型权重按 AUDIOCRAFT_CACHE_DIR 或默认 Hugging Face 缓存目录持久化。
查看日志： 训练日志由各模型训练脚本决定（见 docs/TRAINING.md）；推理脚本默认输出到 stdout。

八、实操验证

完成上述步骤 1–4 的安装后，启动 Python：

python

按官方 MusicGen 文档的最小示例（首次运行会自动下载权重到缓存）：

import torchaudio
from audiocraft.models import MusicGen
from audiocraft.data.audio import audio_write

model = MusicGen.get_pretrained('facebook/musicgen-small')
model.set_generation_params(duration=8)  # generate 8 seconds.
wav = model.generate_unconditional(4)    # generates 4 unconditional audio samples

逐段解释：MusicGen.get_pretrained('facebook/musicgen-small') 从 Hugging Face 加载预训练 MusicGen-small；set_generation_params(duration=8) 设置生成长度 8 秒；generate_unconditional(4) 生成 4 段无条件音频。

预期输出参考： 首次运行会显示 Hugging Face 权重下载进度条；随后 Python 进程不报错，wav 为形状正确的张量。官方 README 未给出具体 stdout 文本，故不虚构。

文本到音乐（按 MusicGen 文档标准用法）：

descriptions = ['happy rock', 'energetic EDM', 'sad jazz']
wav = model.generate(descriptions)  # generates 3 samples.

for idx, one_wav in enumerate(wav):
    # Will save under {idx}.wav, with loudness normalization at -14 db LUFS.
    audio_write(f'{idx}', one_wav.cpu(), model.sample_rate, strategy="loudness", loudness_compressor=True)

逐段解释：generate(descriptions) 按文本描述生成；audio_write 保存 wav 文件，官方注释明确"Will save under {idx}.wav, with loudness normalization at -14 db LUFS"。

预期看到： 当前目录生成 0.wav、1.wav、2.wav 三个音频文件，可用播放器打开聆听。

九、故障排查

案例 1：ModuleNotFoundError: No module named 'audiocraft'

报错原文（常见形式）：ModuleNotFoundError: No module named 'audiocraft'
报错原因：未按官方步骤 3 安装，或在另一个 Python 环境中执行。
分步解决：① python -c "import sys; print(sys.executable)" 确认当前 Python 路径；② 在同一 Python 环境执行 python -m pip install -U audiocraft（或在仓库根目录 python -m pip install -e .）；③ 重新 import audiocraft。

案例 2：Torch not compiled with CUDA enabled 或 CUDA 版本不匹配

报错原文（常见形式）：AssertionError: Torch not compiled with CUDA enabled 或 CUDA error: no kernel image is available for execution on the device
报错原因：官方要求 torch==2.1.0，若 pip 默认安装了 CPU 版本或 CUDA 版本与系统驱动不符，GPU 推理会失败。
分步解决：① 先 pip uninstall torch；② 按 https://pytorch.org/get-started/previous-versions/ 选择与本机 CUDA 匹配的 PyTorch 2.1.0 安装命令；③ 验证 python -c "import torch; print(torch.cuda.is_available())" 应输出 True。

案例 3：ffmpeg not found 或音频文件加载失败

报错原文（常见形式）：RuntimeError: ffmpeg not found 或 torchaudio 解码报错
报错原因：未执行官方步骤 4 安装 ffmpeg。
分步解决：① sudo apt-get install ffmpeg（Debian/Ubuntu）或 conda install "ffmpeg<5" -c conda-forge（Anaconda）；② ffmpeg -version 验证；③ 重新运行推理脚本。

案例 4：Hugging Face 模型下载慢 / 中断

报错原因：官方 FAQ 指出模型权重首次从 Hugging Face 下载，国内网络可能中断。
分步解决：① 设置 AUDIOCRAFT_CACHE_DIR=/your/cache 指定缓存位置；② 设置 Hugging Face 镜像环境变量（属 Hugging Face 库通用机制，非 AudioCraft 官方文档内容）；③ 重新运行脚本，已下载部分会断点续传。

十、升级、回滚与卸载

升级：

python -m pip install -U audiocraft

逐段解释：官方步骤 3 中 stable release 命令自带 -U（upgrade），再次执行即升级到最新 PyPI 版本；bleeding edge 用户用同一条 git+ 命令；editable 用户在仓库内 git pull 即可（源码即最新）。

回滚： 官方未提供一键回滚命令；可 python -m pip install audiocraft==<旧版本号> 锁定到指定 PyPI 版本（具体可用版本见 https://pypi.org/project/audiocraft/#history ）。

卸载：

python -m pip uninstall audiocraft

模型权重缓存位于 AUDIOCRAFT_CACHE_DIR 或默认 ~/.cache/huggingface/，可单独删除以释放磁盘（官方未提供清理命令，此为通用清理）。

十一、商用许可合规说明

代码许可证：MIT License（官方 README「License」一节原文："The code in this repository is released under the MIT license as found in the LICENSE file"；LICENSE 文件首行确认 MIT，Copyright Meta Platforms, Inc. and affiliates）。
模型权重许可证：CC-BY-NC 4.0（官方 README 原文："The models weights in this repository are released under the CC-BY-NC 4.0 license as found in the LICENSE_weights file"）。
商用注意： 代码 MIT 可商用，但模型权重采用 CC-BY-NC 4.0，禁止商用——即 MusicGen/AudioGen/MAGNeT/AudioSeal 等预训练权重不得用于商业产品，仅可研究/评估；商用需自行训练或换用商用许可的替代模型。
MIT 代码部分分发时须保留版权声明与许可文本。