AudioCraft：开源 MusicGen + AudioGen 框架

为什么需要 AudioCraft：文本生成音乐的工程化难题

在 AudioCraft 出现前，AI 音乐生成存在两条路：一是以 MusicLM 为代表的商业/研究封闭系统，代码与权重不开放，无法二次开发；二是以 Riffusion 为代表的扩散式生成方案，对文本语义的控制弱，时长有限且音质不稳。音频生成的门槛还在于「中间表示」——音频是 32kHz 采样率的高维序列，直接回归波形或频谱几乎不可行，必须先将音频压缩成离散 token 交给语言模型处理。AudioCraft 把这条「音频分词 → Transformer 预测 → 解码还原」的链路完整工程化，研究者拿到手即可推理，不用自己实现 EnCodec 和自回归解码。

AudioCraft 的核心资产是 MusicGen：一个基于 EnCodec tokenizer 的单阶段自回归 Transformer，输入文本描述（如 “upbeat electronic dance music“），输出 32kHz 单声道 WAV。与扩散模型不同，MusicGen 逐 token 预测下一个离散音频编码，天然支持条件控制（文本、旋律引导），且小模型（300M 参数）单张消费级 GPU 即可推理。AudioGen 采用同一架构，只是训练数据换成音效语料，解决”游戏/短视频需要海量音效”的痛点。框架同时提供训练脚本，支持在自定义数据集上继续预训练或微调。

与 Suno、Udio 这类闭源 SaaS 相比，AudioCraft 没有一键出歌的成品体验，需要自己写代码、调参、管理 GPU。但它的价值恰好在于“可自己掌控”——数据、模型、部署全链路开放，适合需要定制音色、接入自有流水线、或做学术研究的团队。它面向的是工程师与研究者，而不是终端用户。

安装与环境配置：4 步就绪

AudioCraft 官方推荐的环境是 Python 3.9 + PyTorch 2.1.0 + CUDA 12.1。核心依赖包括 torch、torchaudio、flashy（Meta 自研训练工具库）、dora（实验管理）。安装方式为源码安装，不推荐直接 pip install audiocraft（PyPI 上的包是构建产物，非官方推荐路径）。

步骤一：创建 Python 3.9 虚拟环境（conda 或 venv 均可）。步骤二：按 CUDA 版本安装 PyTorch 2.1.0，务必保证 torch 与 torchaudio 版本一致，否则解码器会报版本不匹配。步骤三：克隆 AudioCraft 仓库并执行 pip install -e .，该命令会自动安装 flashy、dora、gradio 等全部依赖。步骤四：验证导入是否成功——能正常 import audiocraft 且不报缺少包错误即就绪。

首次推理时会自动从 Hugging Face 下载模型权重（如 facebook/musicgen-small 约 1.9GB），国内网络建议先手动下载或配置 HF 镜像 HF_ENDPOINT=https://hf-mirror.com。安装阶段最常见的失败是 torch/torchaudio 版本错配，务必成套安装。

# 1. 创建环境（Python 3.9）conda create -n audiocraft python=3.9 -yconda activate audiocraft # 2. 安装 PyTorch 2.1.0（CUDA 12.1，按需调整 cu121）pip install torch==2.1.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu121 # 3. 克隆并安装 AudioCraftgit clone https://github.com/facebookresearch/audiocraft.gitcd audiocraftpip install -e . # 4. 验证安装python -c "from audiocraft.models import MusicGen; print('AudioCraft OK')"

快速上手：5 分钟生成第一段音乐

AudioCraft 的最小可用流程只有三步：加载模型 → 设置生成参数 → 调用生成并保存。模型通过 MusicGen.get_pretrained() 加载，支持四个预训练规模——facebook/musicgen-small（300M）、musicgen-medium（1.5B）、musicgen-large（3.3B）、musicgen-melody（1.5B，支持旋律引导）。生成参数中最重要的两个是 duration（生成秒数）和 temperature（采样随机性，值越大越有创造性，官方推荐 1.0）。

以下代码在当前环境直接可运行（需 GPU，CPU 也可跑但极慢）：

运行后当前目录会出现 output_0.wav、output_1.wav，即可直接用播放器试听。进阶技巧：model.generate() 返回的张量需 loudness 响度归一化处理后再写入磁盘，否则音量偏轻；生成 30 秒以上长音频时建议用 sample_rate 保持 32000 不变，避免重采样损失。AudioGen 的用法完全对称，只需把 MusicGen 换成 AudioGen，权重换成 facebook/audiogen-medium。

from audiocraft.models import MusicGenfrom audiocraft.data.audio import audio_write # 1. 加载模型（首次自动下载权重）model = MusicGen.get_pretrained('facebook/musicgen-small') # 2. 设置生成参数：时长 8 秒，采样温度 1.0model.set_generation_params(duration=8, temperature=1.0) # 3. 批量生成（可传多个描述，list 长度即 batch size）descriptions = [    "upbeat electronic dance music with heavy bass drop",    "calm acoustic guitar melody for a rainy day",] # 生成并保存为 WAV（format='wav' 可换 'mp3'/'ogg'）wavs = model.generate(descriptions)for idx, wav in enumerate(wavs):    audio_write(f'output_{idx}', wav.cpu(), model.sample_rate, strategy="loudness", loudness_compressor=True)

核心能力详解：3 大支柱

支柱一：MusicGen 文本生成音乐。MusicGen 是 AudioCraft 的王牌模型，采用 EnCodec 将音频编码为离散 token 序列，再以自回归 Transformer 逐 token 生成。EnCodec 以 32kHz 采样率运行，每 4 秒音频被压缩为 50 个 token 帧，配合文本编码器（T5）将文本描述映射为条件向量。与同期扩散模型相比，MusicGen 的优势在于可控时长——通过 duration 参数可生成任意长度的连贯音频，且支持 batch 批量生成多段音乐。官方预训练数据来自 20,000 小时授权音乐，涵盖流行、摇滚、古典等风格。局限是单声道输出、无歌词能力，长音频（>60 秒）可能出现结构漂移。

支柱二：AudioGen 文本生成音效。AudioGen 与 MusicGen 架构相同，但训练数据是音效语料库（如 AudioSet 的子集），专攻环境音与拟音：雨声、人群嘈杂声、狗吠、汽车引擎轰鸣等。它的典型场景是为游戏、短视频、播客批量生产音效素材。AudioGen.get_pretrained('facebook/audiogen-medium') 即可加载，调用方式与 MusicGen 完全一致。由于音效结构比音乐简单，AudioGen 在相同参数量下对短音频（1-5 秒）的生成质量明显优于 MusicGen 处理音效场景的效果。

支柱三：自定义训练与微调。AudioCraft 附带完整的训练与微调管线：dora 管理实验配置，flashy 提供分布式训练封装。训练音乐模型用 dora run musicgen_train，微调用 musicgen_finetune，训练 AudioGen 用 audiogen_train。数据需整理为包含音频文件与文本描述的 JSON 格式，通过配置文件指定数据路径。对多数团队而言，直接在音乐数据集上微调 musicgen-small 比从头训练更实际——官方提供 facebook/musicgen-small 作为微调起点，单卡 A100 数天内即可完成小规模领域适应。

生产部署与监控：从上线到运维

部署方式一：Gradio 服务化。AudioCraft 自带基于 Gradio 的交互界面，一条命令即可对外提供 Web 服务：python -m audiocraft.serve.musicgen --model facebook/musicgen-medium --listen 0.0.0.0 --port 7860。--listen 参数允许局域网/公网访问，--model 指定加载的权重规模。该方案适合内部演示、小流量产品原型，但 Gradio 并发能力弱，不适合高并发线上场景。

部署方式二：自定义 API 服务。生产环境推荐用 FastAPI 或 BentoML 封装模型：应用启动时把模型加载进显存并常驻，通过 HTTP 接口接收文本描述与时长参数返回音频文件。关键优化点：① 用 torch.compile 或半精度（fp16）降低显存占用，MusicGen-large 在 fp16 下约需 12GB 显存；② 多用户并发时用队列串行化推理，避免 OOM；③ 模型预热——服务启动后先跑一次 1 秒生成，把 CUDA kernel 预编译，否则首个请求延迟会高 3-5 倍。

可观测性。生成类服务的核心监控指标：单次生成耗时（按秒统计）、batch 吞吐量（段/秒）、显存占用曲线、请求失败率。由于 AudioCraft 不提供内置 metrics 接口，需在 API 层自行打点（如 Prometheus 直方图记录 generate_duration_seconds）。另一个隐藏监控点是模型权重下载——首次拉取 musicgen-large 需 11GB+ 流量，务必在容器镜像构建阶段预先下载权重并挂载为本地缓存目录（~/.cache/torch/hub/checkpoints），避免服务启动时动态拉取导致超时。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>坑 1：torch 与 torchaudio 版本必须成套安装，混装会导致运行时 EnCodec 解码报「undefined symbol」类错误——推荐用官方命令整对安装。</li><li>坑 2：MusicGen 权重文件位于 Hugging Face，非大陆网络首次加载极易超时——先手动下载或用 HF_ENDPOINT=https://hf-mirror.com 环境变量加速。</li><li>坑 3：MusicGen.generate() 的入参是字符串列表，传单个字符串会被当作字符列表逐个生成——必须写成 ["描述文本"]。</li><li>坑 4：生成结果写盘前必须做响度归一化（strategy="loudness"），否则输出音量显著低于正常音频。</li><li>坑 5：多人并发调用未做串行化时，显存会瞬时翻倍导致 OOM——在服务层加线程锁或推理队列。</li><li>坑 6：MusicGen 只输出单声道，若业务需要立体声，需在后续用外部工具做 upmix，框架本身不支持。</li></ul>

版本迭代

AudioCraft 于 2023 年 6 月随 MusicGen 论文同步开源，此后一年内经历了 Melody 模型、稳定版强化、参数量与兼容性升级三个主要阶段。v1.2 起加入旋律引导能力，v1.3 修复了采样与生成长音频的稳定性问题。截至当前，官方主要维护分支保持稳定，未再发布大版本。

AI 应用场景

常见误区

面试题