Meta 开源的 AudioCraft 系列包含 MusicGen 与 AudioGen 等模型，其中 MusicGen 专门用于根据文本描述生成音乐片段。它基于 Transformer 自回归架构，并引入 EnCodec 音频编码器将连续波形压缩为离散 token，从而让语言模型能够像生成文字一样生成音频。与其他常见方案相比，MusicGen 在旋律连续性、节拍稳定性以及提示词跟随能力上表现突出，适合希望在本地进行音乐原型设计的创作者或研究者。下文将带你完成环境准备、模型安装、命令行与 Python API 调用，以及常见问题排查。
一、环境准备与依赖安装
本地部署 MusicGen 需要一台支持 PyTorch 的机器，如果具备 NVIDIA GPU 会明显加速生成。模型提供 small、medium、large 和 melody 等不同规模权重，small 版本在消费级显卡上也能运行。安装前建议使用 Python 3.9 或 3.10，并创建一个独立的 conda 环境，避免依赖冲突。
创建一个干净的虚拟环境后，需要优先安装与 CUDA 版本匹配的 PyTorch。如果不确定 CUDA 版本，可以先运行 nvidia-smi 查看右上角信息，再到 PyTorch 官网选择对应安装命令。对于没有 GPU 的用户，MusicGen 也支持 CPU 推理，但生成速度会显著下降，通常只适合生成几秒的短片段。
conda create -n audiocraft python=3.10 -y conda activate audiocraft pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 pip install -U audiocraft
安装完成后可以在 Python 中运行 import audiocraft 验证是否成功。如果遇到 ffmpeg 相关错误，还需通过系统包管理器安装 ffmpeg，例如 Ubuntu 下执行 sudo apt install ffmpeg，macOS 下执行 brew install ffmpeg。
二、加载模型与理解生成参数
MusicGen 的模型权重通常从 Hugging Face 拉取，首次运行时需要保持网络畅通。官方提供了多个模型标识，例如 facebook/musicgen-small、facebook/musicgen-medium、facebook/musicgen-large 以及 facebook/musicgen-melody。其中 melody 模型额外支持参考音频的条件生成，可以上传一段旋律并让模型延续或改编。
在生成音乐之前，有四个参数值得关注。首先是 duration，它控制输出音频长度，单位是秒。其次是 temperature，它调节采样随机性，数值越高生成结果越多样但也更容易失去结构。第三是 top_k，限制每一步采样的候选 token 数量，降低随机噪声。第四是 cfg_coef，即无分类器引导系数，适当提高能让模型更贴合文本描述，但过高可能导致音频失真。
如果只是做快速验证，可以选择 small 模型与较短的 duration。例如在显存为 8GB 的显卡上，生成 30 秒音频通常可以完成；若显存紧张，可减少 batch size 或缩短时长。
三、命令行快速生成示例
安装 audiocraft 后，可以通过官方提供的脚本或简单的 Python 命令生成音频。最快捷的方式是进入 Python 交互环境，加载模型后直接调用 generate 方法。下面示例使用文本提示生成一段带有钢琴和鼓点的音乐，并将结果保存为 WAV 文件。
from audiocraft.models import MusicGen
from audiocraft.utils.notebook import display_audio
model = MusicGen.get_pretrained("facebook/musicgen-small")
model.set_generation_params(
duration=20,
temperature=0.9,
top_k=250,
cfg_coef=3.0
)
wav = model.generate([
"acoustic piano and soft drums, relaxing ambient music"
])
model.save_wav(wav, "generated_music.wav")
print("音频已保存至 generated_music.wav")
这里 model.generate 接收一个字符串列表，列表中每个元素对应一条独立的生成任务。生成结果是一个 torch 张量，形状大致为批次、声道、采样点。如果不希望保存文件，也可以直接使用 IPython.display 播放，但本地脚本中保存为 WAV 更直观。
如果希望在终端中直接调用，也可以将上述代码保存为 generate.py 后执行 python generate.py。建议将模型加载放在脚本开头，避免每次生成时重复下载权重。首次运行会从 Hugging Face 下载模型文件，下载时间取决于网络状况。
四、使用参考音频进行旋律生成
MusicGen 的 melody 模型可以在文本提示之外接收参考音频，让生成结果保持参考片段的旋律走向。这个功能适合做风格迁移或动机扩展。使用前需要安装 audiocraft 的完整依赖，并准备一段 WAV 或 MP3 格式的参考音频。
下面示例加载 melody 模型，并将 melody 参数传入 generate。模型会先把参考音频转换为 EnCodec token，再与文本条件联合指导生成。为了获得更好的旋律一致性，建议参考音频长度不要超过 30 秒，并尽量选择干净的单声道或立体声乐器录音。
import torchaudio
from audiocraft.models import MusicGen
model = MusicGen.get_pretrained("facebook/musicgen-melody")
model.set_generation_params(duration=30, temperature=1.0, top_k=300, cfg_coef=4.0)
ref_wav, sr = torchaudio.load("reference.wav")
if sr != 32000:
resampler = torchaudio.transforms.Resample(sr, 32000)
ref_wav = resampler(ref_wav)
wav = model.generate_with_chroma(
["jazz guitar solo over the same chord progression"],
ref_wav,
sr=32000
)
model.save_wav(wav, "melody_output.wav")
print("参考旋律生成完成")
这里使用 generate_with_chroma 方法，它会提取参考音频的 chroma 特征并作为条件。相比于直接拼接音频，chroma 特征对节奏变化更鲁棒，能够保留音高轮廓。若你只想保留风格而不限制旋律，可以使用普通 generate 方法并只传文本。
五、常见问题与性能优化
第一个常见问题是显存不足。MusicGen 默认使用 float32 推理，对于 medium 或 large 模型，8GB 显存可能不够。可以尝试在加载模型时使用 MusicGen.get_pretrained("facebook/musicgen-small", device="cuda") 并设置 torch.set_float32_matmul_precision("high")，或者改用 CPU 推理。对于 24GB 显存，运行 small 和 medium 通常没有压力。
第二个常见问题是生成音频结尾被截断。这是因为部分生成结果在达到 duration 时可能被强制停止，尤其是当 cfg_coef 过高时。可以适当降低 cfg_coef，或把 duration 设置得比实际需要长几秒，再后期裁剪。
第三个问题是下载模型缓慢。如果 Hugging Face 访问不稳定，可以设置镜像环境变量 HF_ENDPOINT，例如在 Linux 或 macOS 下执行 export HF_ENDPOINT=https://hf-mirror.com。也可以手动下载权重文件到本地目录，再通过 MusicGen.get_pretrained("/path/to/local/model") 加载。
最后，为了提升批量生成效率，可以把多个提示词放入列表一次性调用，模型会并行处理并在 GPU 上形成 batch。这样处理 4 到 8 条提示词时，平均每条耗时通常低于逐条生成。若需要长时间生成，建议使用进度条回调或分段生成后拼接，避免单次生成时间过长导致显存峰值过高。
AudioCraft MusicGen本地部署AI音乐生成修改时间：2026-08-28 01:15:40