MAGNeT 模型卡与技术解析：AudioCraft 中基于单非自回归 Transformer 的掩码音频生成

• 人工智能
• 深度学习
• 音频
• 媒体生成
• 音乐生成

MAGNeT（Masked Audio Generation using a Single Non-Autoregressive Transformer）是 AudioCraft 库中面向文本到音乐、文本到音效生成的非自回归模型，其模型卡系统记录了模型的架构组成、训练与评估数据、客观指标（FAD/KLD/CLAP）以及已知限制与偏差。本文将围绕该模型卡展开，结合 AudioCraft 仓库中 audiocraft/models/magnet.py、audiocraft/models/lm_magnet.py、audiocraft/solvers/magnet.py 等源码与配置文件，完整解读模型细节、评估结果、使用 API、训练/微调/评估全流程，帮助你既理解模型卡中每一项指标和数据来源，又能直接上手推理与复现。

模型概览（Model details）

模型卡给出的 MAGNeT 核心信息如下：

从源码结构看，MAGNeT 由两个部分拼接而成：EnCodec 负责将音频离散化为 token 序列，非自回归 Transformer（MagnetLMModel）负责在 token 序列上进行掩码生成。在 magnet.py 中，get_pretrained依次调用load_compression_model与load_lm_model_magnet加载这两部分，与模型卡"EnCodec + 非自回归 Transformer"的描述一一对应。

模型卡说明：模型权重以 CC-BY-NC 4.0 发布，意味着权重仅可用于非商业用途；代码本身遵循 MIT 协议。使用前请确认你的应用场景符合许可要求。

技术原理：从模型卡到源码实现

模型卡将 MAGNeT 概括为"一个非自回归 Transformer 进行音乐建模"，而 docs/MAGNET.md 进一步补充：MAGNeT 是在32kHz EnCodec 分词器（4 个码本、50 Hz 帧率）之上训练的掩码生成式非自回归 Transformer。

与 SoundStorm、VampNet 等此前的工作不同，MAGNeT不需要语义 token 条件、模型级联或音频提示（prompting），用一个单一的非自回归 Transformer 直接完成完整的文本到音频生成。这些技术要点可以从源码中得到印证：

• 并行码本模式：训练配置 config/solver/magnet/magnet_32khz.yaml 中codebooks_pattern.modeling: parallel，即各 RVQ 码本并行建模，而非自回归逐码本生成。
• 受限注意力上下文：lm_magnet.py 中restricted_context_attn_mask为码本 > 0 的层构造局部注意力掩码，subcodes_context（默认 5）限定每个时间步能关注到的相邻时间步范围，这也是为什么配置中注明efficient_attention_backend: xformers——受限注意力实现目前仅支持 xformers 后端。
• Span 掩码机制：MagnetLMModel 的span_len（默认 3）定义了训练与推理时连续掩码 token 段的最小长度；solvers/magnet.py 中的_spans_mask通过mean_maskrate_to_u查找表（LUT）将掩码率转换为要放置的 span 起始数量，论文附录 C 给出了平均掩码率的推导。
• 迭代解码：推理阶段对每个码本依次执行若干轮"掩码—预测—重掩码"迭代（decoding_steps，默认[20, 10, 10, 10]），掩码比例按余弦调度mask_p = cos(t * pi / 2)从 1 衰减到 0（见 lm_magnet.py）。

训练损失：单码本掩码交叉熵

训练时每步随机选择一个码本 stage（random.randint(0, K-1)），只在该码本的被掩码位置上计算交叉熵，且所有更高层的码本全部置为掩码 token（见 solvers/magnet.py）。模型卡中提到的"以 50 Hz 采样的 4 码本 EnCodec tokenizer"正是该损失与并行码本模式的数据基础。

预期用途（Intended use）

模型卡明确了 MAGNeT 的定位与研究边界：

• 主要用途：AI 音乐生成研究，包括探测和理解生成模型的局限以推动科学发展；以及由机器学习爱好者通过文本引导生成音乐、理解当前生成式 AI 的能力。
• 主要用户：音频、机器学习和人工智能领域的研究者，以及希望理解这些模型的爱好者。
• 超出范围的使用：未经进一步风险评估与缓解，不应将模型用于下游应用；不得故意创作或传播制造敌对、疏远环境的音乐，包括可能令人感到不安、痛苦或冒犯的内容，以及传播历史或现存的刻板印象的内容。

评估指标（Metrics）

模型卡列出了三类客观指标，均由预训练音频分类器/嵌入模型提取特征后计算：

此外还开展了人类受试者参与的定性研究，评估两个维度：音乐样本的整体质量与相对输入文本的相关性。更详细的口径与人类研究流程见论文。模型卡明确标注"决策阈值（Decision thresholds）：不适用"。

评估数据集与训练数据集

• 评估：MusicCaps 基准（10 秒音频-文本对）以及一个与训练集无艺术家重叠的域内保留集。
• 训练：16K 小时的授权数据，来源包括 Meta Music Initiative Sound Collection、Shutterstock 音乐集和 Pond5 音乐集；预处理细节见论文。

需要特别说明：模型卡中"16K 小时训练数据"这一数据规模描述，与 docs/MAGNET.md 中"内部 10K 首高质量音乐曲目 + ShutterStock 与 Pond5 音乐数据"的描述一致。仓库不提供任何训练数据集，仅附带少量用于演示的 dummy 数据。

评估结果（Evaluation results）

音乐生成模型（MusicCaps）

模型卡给出的公开模型客观指标如下。注意：对公开模型，官方使用 SOTA 音乐源分离方法HT-Demucs（Hybrid Transformer for Music Source Separation）只保留纯乐器音轨，因此与论文中的指标存在差异：

从表中可以看出：同一参数量下 10 秒模型优于 30 秒模型（更短的序列更容易稳定生成）；medium 与 small 的文本一致性（0.28）持平。这些指标可通过 audiocraft/grids/magnet/magnet_pretrained_32khz_eval.py 中的评估网格在 MusicCaps 上复现。

音效生成模型（Audio-MAGNeT，AudioCaps 基准，10 秒样本）

值得注意：在音效任务上 medium 模型（2.32）明显优于 small（3.21），说明参数量对 FAD 的改善在音效域更显著。

Audio-MAGNeT：音效生成模型

模型卡单列了一节介绍音频 MAGNeT 模型：

• 训练数据来源：AudioSet（Gemmeke et al., 2017）的子集、BBC 音效库、AudioCaps（Kim et al., 2019）、Clotho v2（Drossos et al., 2020）、VGG-Sound（Chen et al., 2020）、FSD50K（Fonseca et al., 2021）、Free To Use Sounds、Sonniss Game Effects、WeSoundEffects、Paramount Motion - Odeon Cinematic Sound Effects。
• 评估基准：AudioCaps。
• 模型命名：facebook/audio-magnet-small与facebook/audio-magnet-medium。

从配置看，config/solver/magnet/audio_magnet_16khz.yaml 是 16kHz 单声道音效任务（对应 AudioGen 的训练范式），其 EnCodec 总 stride 为 320、帧率仍为 50 frames/s，并启用了 50% 概率的音频混合增强（aug_p: 0.5、mix_p: 0.5、SNR 范围 -5~5 dB）。对应求解器是 solvers/magnet.py 中的AudioMagnetSolver（DATASET_TYPE = DatasetType.SOUND）。

限制与偏差（Limitations and biases）

模型卡在"数据"、"缓解措施"、"限制"、"偏差"、"风险与危害"五个维度给出了诚实的能力边界：

• 数据：训练数据由音乐专业人士创作并经权利方合法授权；作者认为在更大数据集上扩展可进一步提升性能。
• 缓解措施：使用标签和 HT-Demucs 源分离方法移除了包含人声的音轨。
• 已知限制：
  1. 无法生成逼真的人声（vocals）；
  2. 仅以英文描述训练，其他语言效果较差；
  3. 并非对所有音乐风格和文化表现均衡；
  4. 有时会生成歌曲结尾并坍缩为静音；
  5. 有时难以判断哪些文本描述能产生最佳结果，可能需要 prompt engineering。
• 偏差：数据源多样性不足，各音乐文化并非均衡覆盖；生成样本会反映训练数据的偏差。
• 风险与危害：模型偏差与限制可能导致生成被认为有偏、不当或冒犯的样本；官方认为开源复现代码与训练新模型有助于将应用扩展到更新、更具代表性的数据上。

这些限制在代码层也有对应体现：例如 magnet.py 中self.duration = self.lm.cfg.dataset.segment_duration，说明模型在固定序列长度上工作（10 秒或 30 秒变体），与"有时坍缩为静音"的观测一致。

预训练模型与推理 API

六个预训练模型

仓库提供了 6 个可直接加载的预训练模型（MAGNeT.get_pretrained的 docstring 见 magnet.py）：

快速上手（GPU 必需）

AudioCraft 的推理需要 GPU：medium（约 1.5B 参数）模型建议16GB 显存。按 docs/MAGNET.md 中的示例：

import torchaudio from audiocraft.models import MAGNeT from audiocraft.data.audio import audio_write model = MAGNeT.get_pretrained('facebook/magnet-small-10secs') descriptions = ['disco beat', 'energetic EDM', 'funky groove'] wav = model.generate(descriptions) # 生成 3 个样本 for idx, one_wav in enumerate(wav): # 保存为 {idx}.wav，按 -14 dB LUFS 响度归一化 audio_write(f'{idx}', one_wav.cpu(), model.sample_rate, strategy="loudness", loudness_compressor=True)

也可以启动 Gradio 本地 demo 或 Jupyter Notebook 交互：

# 方式一：Gradio demo（--share 可生成公网分享链接） python -m demos.magnet_app --share # 方式二：本地运行 notebook（需要有 GPU） # 打开 demos/magnet_demo.ipynb

get_pretrained会自动探测设备（有 CUDA 则用cuda，否则回退cpu），见 magnet.py。

生成参数详解：set_generation_params

MAGNeT 提供了独立于 MusicGen 的生成参数接口（magnet.py），默认值如下：

MAGNeT 特有的两个机制值得展开（源码见 lm_magnet.py）：

1. CFG 系数退火：随解码进行，掩码率mask_p从 1 衰减到 0，引导系数按clsfg_coef = mask_p * max_cfg_coef + (1 - mask_p) * min_cfg_coef从max_cfg_coef线性退火到min_cfg_coef（lm_magnet.py）。这也解释了generate接口为何断言cfg_coef is None——MAGNeT 只支持max_cfg_coef, min_cfg_coef的退火形式，不支持固定系数与两阶段 CFG。
2. 温度退火与 span 打分：anneal_temp=True时 softmax 温度在每阶段内线性衰减到零（t = temp * (steps_left / timesteps)）；span_scoring支持 'max'（span 内取最大概率）或 'prod'（对数空间求积）两种 span 置信度打分方式，用于决定下一轮重掩码哪些 span。

推理时 CFG 通过一次前向完成：条件与无条件输入拼接后单次计算，再按引导系数融合（lm_magnet.py），相比两次前向效率更高。

训练、微调与评估

训练配置与网格

MagnetSolver（solvers/magnet.py）实现了 MAGNeT 的训练管线：在预训练 EnCodec 提取的多流离散 token 上定义掩码生成任务。两个官方训练配置：

• 文本到音乐：config/solver/magnet/magnet_32khz.yaml（32kHz、EnCodec 总 stride 640 → 50 frames/s、rvq.n_q=4、rvq.bins=2048）
• 文本到音效：config/solver/magnet/audio_magnet_16khz.yaml（16kHz、总 stride 320 → 50 frames/s）

配置中的关键训练超参与模型卡评估结果直接相关：

• 音乐模型：optim.lr=1（配合 dadam 优化器）、cosine 调度、4000 步 warmup、batch_size: 192（32 卡）；生成阶段配置decoding_steps: [60, 10, 10, 10]。
• 音效模型：optim.lr=5e-4（adamw）、inverse_sqrt 调度、3000 步 warmup、aug_p: 0.5音频混合增强；生成阶段temp: 3.5、top_p: 0.8、max_cfg_coef: 20.0、decoding_steps: [20, 10, 10, 10]。

训练网格位于 audiocraft/grids/magnet/，模型规模通过model/lm/model_scale切换 small（300M）、medium（1.5B）、large（3.3B）：

# 文本到音乐 dora grid magnet.magnet_32khz --dry_run --init # 文本到音效 dora grid magnet.audio_magnet_16khz --dry_run --init # 一切就绪后去掉 --dry_run --init 真正调度任务

从 audiocraft/grids/magnet/magnet_32khz.py 可以看到：small 模型用 32 卡、medium 用 64 卡并开启 FSDP（fsdp.use: True、autocast: False）；10 秒变体通过dataset.segment_duration=10与decoding_steps=[20, 10, 10, 10]区分于 30 秒变体。

数据集格式

MAGNeT 底层是 AudioDataset 并附带元数据（详见 docs/DATASETS.md）：

• 音乐模型：元数据以.json文件形式与音频文件同目录存放；
• 音效模型：同样期望.json元数据，可通过external_metadata_source指定外部文件夹。

微调已有模型（continue_from）

# 用预训练 MAGNeT 初始化 dora run solver=magnet/magnet_32khz model/lm/model_scale=medium continue_from=//pretrained/facebook/magnet-medium-10secs conditioner=text2music # 用自己训练过的 Dora 签名 SIG dora run solver=magnet/magnet_32khz model/lm/model_scale=medium continue_from=//sig/SIG conditioner=text2music # 或直接提供 checkpoint 路径 dora run solver=magnet/magnet_32khz model/lm/model_scale=medium continue_from=/checkpoints/my_other_xp/checkpoint.th

注意两个警告：配置不会自动继承自 continue_from 的模型，需自行保证conditioner、model/lm/model_scale等参数兼容；且暂不支持层结构有差异的微调，若改动模型结构需手工构造 checkpoint 文件，其格式为torch.save的字典{'best_state': {'model': model_state_dict_here}}，并将路径直接传给continue_from（不带//pretrained/前缀）。

评估阶段复现

6 个预训练模型的客观指标可用如下网格复现：

# 文本到音乐 REGEN=1 dora grid magnet.magnet_pretrained_32khz_eval --dry_run --init # 文本到音效 REGEN=1 dora grid magnet.audio_magnet_pretrained_16khz_eval --dry_run --init

评估网格 magnet_pretrained_32khz_eval.py 使用dset: audio/musiccaps_32khz与objective_eval求解器，并需要配置metrics.fad.tf.bin指向本地的 google-research FAD 二进制路径。REGEN=1用于首次运行或网格变更时强制重新生成。

加载自己训练的实验

from audiocraft.solvers.magnet import MagnetSolver solver = MagnetSolver.get_eval_solver_from_sig('SIG', device='cpu', batch_size=8) solver.model solver.dataloaders

导入 / 导出模型

当前不支持从 Hugging Face 实现加载或向其导出。若要将自训练模型导出为与audiocraft.models.MAGNeTAPI 兼容的格式：

from audiocraft.utils import export from audiocraft import train xp = train.main.get_xp_from_sig('SIG_OF_LM') export.export_lm(xp.folder / 'checkpoint.th', '/checkpoints/my_audio_lm/state_dict.bin') # 还需要打包你使用的 EnCodec 模型： ## 情况 1) 自己训练的 xp_encodec = train.main.get_xp_from_sig('SIG_OF_ENCODEC') export.export_encodec(xp_encodec.folder / 'checkpoint.th', '/checkpoints/my_audio_lm/compression_state_dict.bin') ## 情况 2) 使用的预训练模型：只写入指向待下载模型的指针 export.export_pretrained_compression_model('facebook/encodec_32khz', '/checkpoints/my_audio_lm/compression_state_dict.bin')

然后即可用MAGNeT.get_pretrained('/checkpoints/my_audio_lm/')加载自定义模型。

常见问题：FSDP 还是 autocast？

两者互斥（FSDP 内部自带 autocast）。autocast 可用于 1.5B（medium）模型，前提是 GPU 显存足够；FSDP 会通过分片优化器状态释放部分显存给激活值，但复杂度更高。相关配置可在 config/solver/magnet/magnet_32khz.yaml 中看到（默认autocast: true、autocast_dtype: float16），而训练网格在 medium 规模时切换为fsdp.use: True+autocast: False。

引用与进一步阅读

如果你在研究中使用了 MAGNeT，请引用其论文：

@misc{ziv2024masked, title={Masked Audio Generation using a Single Non-Autoregressive Transformer}, author={Alon Ziv and Itai Gat and Gael Le Lan and Tal Remez and Felix Kreuk and Alexandre Défossez and Jade Copet and Gabriel Synnaeve and Yossi Adi}, year={2024}, eprint={2401.04577}, archivePrefix={arXiv}, primaryClass={cs.SD} }

进一步深入可参考仓库中的 MAGNET.md（完整使用与训练指南）、ENCODEC.md（音频分词器训练）、TRAINING.md（训练管线与环境搭建）、DATASETS.md（数据集与元数据规范），以及README.md中的安装说明。理解模型卡的客观指标时，建议结合 magnet_pretrained_32khz_eval.py 与 MusicCaps/AudioCaps 基准口径，并始终留意模型卡中关于人声、多语言、风格均衡性与 prompt engineering 的五条已知限制。

• 人工智能
• 深度学习
• 音频
• 媒体生成
• 音乐生成