MERT-v2-FullSong

MERT-v2-FullSong

一个音乐编码器，把 30 到 360 秒的整首歌转成帧级或整段级的数值特征。适合处理冻结嵌入的音乐 AI 研究者和开发者。

由 m-a-p 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：MERT-v2-FullSong 是 m-a-p 推出的双向音乐编码器，能处理 30 到 360 秒的整首歌曲。它把音频转成通用的音乐表示，可以按帧，也可以按整段录音。它在 MERT-v2-30s 的基础上继续预训练，并保持相同的特征接口。它有 632 million 参数、24 层、1,024 维，读取 24 kHz 单声道音频，频率为 25 Hz。

适合谁：适合想用现成歌曲特征、而不是从零训练音频模型的音乐 AI 研究者和开发者。模型卡报告的是冻结编码器的结果，所以适合在它上面训练小模型的工作。

Title: 谁会用它
Industry | Who uses it | How they use it | Example
音乐研究 | 音乐信息检索研究者 | 提取特征并在上面训练小模型 | 在冻结的歌曲嵌入上搭一个分类器
音频软件 | 开发者 | 把一首曲子变成一个嵌入向量 | 用整段录音级的嵌入比较歌曲
学术 | 音频机器学习的学生 | 逐层研究编码器学到了什么 | 读取 24 个块各自的隐藏状态

如果你需要商用许可，可以跳过它。记录上的许可是非商用的。

用在哪里：它通过 Python 里标准的 Hugging Face transformers 库加载，流程与早期的 MERT 模型相同。

• Python 加 transformers、torch 和 torchaudio
• 有 GPU 就用 GPU，否则用 CPU
• Windows、macOS 或 Linux 加 Python

Title: 它能做的事
Use case | Who | What they get back
帧级特征 | 研究者 | 每个 25 Hz 帧对应一个 1,024 个数的向量
整段级嵌入 | 开发者 | 一段音频或一首歌对应一个 1,024 个数的向量
逐层检查 | 学生 | 24 个块各自独立的隐藏状态

如何设置：你需要带 pip 的 Python。模型卡固定了 torch、torchaudio 和 transformers 的版本，所以请安装匹配的一套。

• 带 pip 的 Python
• 固定版本的 torch、torchaudio 和 transformers 包
• 用来读取音频文件的 soundfile 包
• 一个音频文件，例如 music.wav

1. 用模型卡里的命令安装匹配的 PyTorch 包。
2. 可选：用 Hugging Face 工具取回模型文件。
3. 把一个名为 music.wav 的音乐文件放在你的脚本旁边。

python -m pip install torch==2.6.0 torchaudio==2.6.0 transformers==4.53.2 huggingface-hub safetensors soundfile

pip install -U huggingface_hub
hf download m-a-p/MERT-v2-FullSong

如何使用：运行下面的脚本。它读取你文件的前 30 秒，混成单声道，重采样，然后在开启隐藏状态输出的情况下运行模型。想处理整首歌，就删掉切片这一步。

import soundfile as sf
import torch
import torchaudio.functional as AF
from transformers import AutoFeatureExtractor, AutoModel
repo = "m-a-p/MERT-v2-FullSong"
device = "cuda" if torch.cuda.is_available() else "cpu"
processor = AutoFeatureExtractor.from_pretrained(repo, trust_remote_code=True)
model = AutoModel.from_pretrained(repo, trust_remote_code=True).eval().to(device)
audio, sr = sf.read("music.wav", dtype="float32", always_2d=True)
audio = audio[:30 * sr].mean(axis=1)  # First 30 seconds, mixed to mono.
waveform = AF.resample(torch.from_numpy(audio), sr, processor.sampling_rate)
inputs = processor(
    waveform.numpy(), sampling_rate=processor.sampling_rate, return_tensors="pt",
).to(device)
with torch.inference_mode():
    output = model(**inputs, output_hidden_states=True)
frames = output.last_hidden_state         # [batch, frames, 1024], 25 Hz
layers = output.hidden_states             # 24 tensors, one per block
mask = output.feature_attention_mask[..., None]
embedding = (frames * mask).sum(1) / mask.sum(1).clamp_min(1)  # [batch, 1024]

Title: 脚本返回什么
Tool | What it does
last_hidden_state | 25 Hz、1,024 维的帧特征
hidden_states | 24 个张量，每个块一个
embedding | 每段录音一个平均后的向量
AutoFeatureExtractor | 把音频处理成模型期望的采样率

示例：你把脚本指向一个名为 music.wav 的歌曲文件。模型返回前 30 秒的一组帧特征、每个块各一个隐藏状态，以及一个 1,024 个数的嵌入，你可以保存它或交给分类器。

新手与专家：如果你是新手，编码器把声音变成描述它的一串数字。第一件小事，是在一个短音乐文件上运行上面的脚本，然后打印嵌入的形状。

如果你熟悉这个领域，这是一个从 30 秒版本继续预训练的双向编码器，所以在保持相同特征接口的同时带来了整首歌的上下文。第 1 块对应第一个隐藏状态，第 24 块对应最后一个。模型卡的 MARBLE 对比用的是冻结编码器。

读取音乐文件并转成单声道
重采样到模型的采样率
编码器生成帧特征
把帧平均成一个嵌入

注意事项：模型卡统计了每个 MERT2 编码器在 MARBLE 上胜过最强外部基线的指标数。那里所有分数都乘以 100，越高越好。

Title: MARBLE 上领先的指标数，共 15 个
MERT2-30s: 14 metrics
MERT2-FS full-song: 13 metrics

• License: CC BY-NC 4.0，非商用
• Cost to run: 未提及
• Data it reaches: 你的音频文件，以及来自 Hugging Face 的模型文件
• Not for: 在这个许可下的商业用途

Hugging Face 上的数据（2026年11月13日）

• 任务：feature extraction
• 框架：transformers
• 参数量：632M
• Weights: about 2.5 GB in F32; about 316 MB at 4-bit (estimate)
• Formats: Safetensors
• 最近 30 天下载：13,790
• 点赞：57
• 许可证：cc-by-nc-4.0
• Quantized versions: 2
• Fine-tunes: 3
• 标签：transformers, safetensors, mert2, feature-extraction, audio, music, music-understanding, representation-learning

链接

• 模型：https://huggingface.co/m-a-p/MERT-v2-FullSong
• 文件：https://huggingface.co/m-a-p/MERT-v2-FullSong/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download m-a-p/MERT-v2-FullSong

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。