Magenta音乐生成实战：NoteSequence、预训练模型与序列建模

第一次打开 magenta 的命令行帮助文档时，很多人会有一个相似的困惑：明明只是想用几行 Python 让机器写一段旋律，为什么文档里全是 RNN、VAE、NoteSequence、bundle 这些看起来偏研究的词。magenta 就是这样一个有趣的 Python 库，它把音乐与绘画的生成能力打包成了可以直接调用的模型和命令行工具，既能当创意玩具，也能当音乐信息检索、序列生成方向的学习样本。这篇内容适合三类人：想找个能立刻出效果的生成式 AI 练手项目的新手、做音乐科技或互动装置需要批量产出 MIDI 素材的开发者、以及想把预训练序列模型迁移到自己领域的工程师。下面我按实际动手的顺序，把这个库的选型逻辑、核心结构、完整跑通流程和踩坑记录讲清楚。

1. 项目整体设计与思路拆解

1.1 它到底在解决什么问题

生成音乐听起来很玄，落到工程上其实是一个序列预测问题：给定前面的音符，预测下一个音符该是什么。magenta 的所有模型几乎都是围绕这个思路展开的，区别只在于"音符"怎么表示、上下文怎么编码、生成时怎么采样。它没有走"直接生成音频波形"的路线，而是选择了符号音乐（symbolic music），也就是 MIDI 这一层。这个选择非常关键，因为对于刚上手的人来说，符号层的数据量小、可解释性强、出错的成本也低——生成的 MIDI 扔进宿主软件里换个音源，立刻就能听出好坏，而波形生成模型一旦训崩，你只能听到一段噪声。

从工程角度看，magenta 提供的价值集中在三块。第一块是预训练模型加 bundle 文件，下载下来就能生成，不需要你有训练数据。第二块是一套统一的中间数据结构 NoteSequence，所有模型的输入输出都走这个格式，等于把"数据清洗"这件事标准化了。第三块是可复现的训练脚本，从 MIDI 文件夹到 tfrecord 再到训练，链路上每一环都有对应命令。这三块组合起来，让它比"自己拿 PyTorch 写个 LSTM 弹钢琴"要省事得多，也比"直接用商业 AI 作曲工具"要可控得多，因为你能改每一个参数。

1.2 为什么选用 NoteSequence 作为中间表示

刚开始接触的人容易忽略这一点，觉得 MIDI 文件本身就够用了，何必再套一层。实际上 NoteSequence 是这个库设计里最聪明的一环。MIDI 文件是二进制事件流，同一个音高、同一个时值可以用不同的 delta time 编码方式写出来，还存在多轨、控制器事件、音色切换等干扰项。如果每个模型都自己去解析 MIDI，代码会很难维护，模型之间的结果也无法互相串联。NoteSequence 是一个 protobuf 结构，把音乐拆成节奏（tempo）、拍号（time_signatures）、音符（notes）三个主要部分，其中每个 note 明确记录音高 pitch、力度 velocity、开始时间 start_time、结束时间 end_time、乐器编号 instrument 和音色 program。

这样做的好处是时间被统一成了"秒"，而不是 MIDI tick。tick 依赖分辨率和 tempo 的换算，很容易在不同工具之间出现偏差；秒是绝对时间，跨工具链传递时不会打架。代价是精度损失——浮点秒在长时间序列上会有累积误差，所以实际项目里我习惯在最终导出前做一次重新量化。另一个好处是 NoteSequence 天然支持"部分生成"：你可以只生成某个时间段内的音符，前后保留原样，这就是后面做续写、做风格接续的基础。

1.3 为什么模型被拆成这么多个

第一次看模型列表会觉得冗余，光是旋律就有 basic_rnn、lookback_rnn、attention_rnn 三个配置，还有 drums_rnn、improv_rnn、performance_rnn、music_vae 等等。拆这么细的原因是，音乐生成里"上下文应该看多长"和"应该生成什么粒度"这两个问题没有统一答案，不同场景需要不同的取舍。basic_rnn 只看固定长度的前文，速度最快但容易陷入重复；lookback_rnn 在结构上增加了回看机制，能缓解长序列上的记忆衰减；attention_rnn 用注意力机制处理更长依赖，效果更好但显存和时间开销也更大。这三者是"同一任务的不同深度"，不是互相替代的关系。

再往上一层，performance_rnn 换了表示粒度，它生成的不是离散音符，而是"演奏事件"，包含按键按下、松开、力度、时值，输出的演奏更有人味，代价是序列变长、训练更难。improv_rnn 引入了和弦条件，你给它一个和弦进行，它在这个约束下即兴。music_vae 是另一条路线，用变分自编码器学一个隐空间，好处是可以做插值和风格混合，两段旋律之间平滑过渡，这是自回归模型很难做到的。drums_rnn 则专门处理打击乐，因为鼓的"音高"其实对应不同鼓件，语义和其它乐器完全不同。

注意：模型多不代表都要用。实际项目里，旋律用一个 attention_rnn 或 music_vae 就够，鼓可以单独用 drums_rnn 铺底，剩下的按需加。贪多只会让调试链路变长。

2. 核心细节拆解与实操要点

2.1 环境准备：版本矩阵比想象中更重要

这个库最大的门槛不在代码，而在环境。它依赖 TensorFlow，而 TensorFlow 对 Python 版本有硬性要求，magenta 早期版本基于 TF1，后期版本迁移到了 TF2，两套 API 差别很大。如果你在 Python 3.11 或更高版本上直接 pip install，大概率会卡在依赖解析阶段，或者装上了但 import 时报一堆废弃 API 错误。我的建议是直接开一个 Python 3.8 的虚拟环境，这是兼容性最好的区间。

# 创建独立环境，避免污染主环境 conda create -n magenta-env python=3.8 -y conda activate magenta-env # 先装框架，再装库，顺序很重要 pip install tensorflow==2.9.1 pip install magenta==0.4.1 # 补齐音频相关依赖 pip install note-seq pretty_midi mido librosa

装完之后先别急着跑模型，用一段最小代码验证导入是否正常。

import magenta import note_seq from note_seq.protobuf import music_pb2 seq = music_pb2.NoteSequence() seq.notes.add(pitch=60, start_time=0.0, end_time=0.5, velocity=80) seq.total_time = 0.5 print("import ok, notes:", len(seq.notes))

能打印出import ok, notes: 1就算环境通了。这一步看起来废话，但它是后面所有排查的基准线：如果连这行都跑不通，后面报的任何错都先怀疑环境，而不是模型。

参数选择上还有一个容易忽略的细节：protobuf 的版本。magenta 用的 protobuf 生成代码比较老，新版本 protobuf 会直接抛Descriptors cannot be created directly，处理方式是把 protobuf 钉在 3.20 以下。

pip install "protobuf<3.20,>=3.9"

2.2 NoteSequence 的字段含义与量化规则

要把这个库用明白，必须对时间量化有概念。模型不处理任意浮点时间，它把时间切成固定的格子，格子大小由 steps_per_quarter 决定。以旋律模型为例，steps_per_quarter 通常取 4，意味着一个四分音符被切成 4 份，每份是十六分音符。如果 tempo 是 120 BPM，一个四分音符是 0.5 秒，那么一个 step 就是 0.125 秒。要把总时长换算成步数，公式是：

• 每秒的步数 = steps_per_quarter × (qpm / 60)
• 总步数 = 目标秒数 × 每秒步数

举个例子，你想生成 8 小节、4/4 拍、120 BPM 的旋律，总长度是 16 秒，每秒步数 = 4 × 2 = 8，总步数 = 128。这个 128 就是命令行里 num_steps 该填的值。很多人填了 32 却发现只生成了一两秒，就是没做这个换算。

NoteSequence 里还有几个字段值得专门记一下。instrument 是音轨编号，从 0 开始，多轨输出时靠它区分；program 是 MIDI 音色号，0 是钢琴；velocity 是力度，取值 0 到 127，模型生成的力度往往比较平均，想要人味可以后期加抖动。休止在命令行里用 -2 表示，在 NoteSequence 里则直接体现为两个音符之间的时间空隙。这几个约定看起来琐碎，但少了任何一个，导出的 MIDI 要么没声，要么节奏全乱。

2.3 模型与配置对照：怎么选不浪费

选模型的核心依据是"你要生成什么"和"你能接受多长的等待"。下面这张表是我自己在不同项目里实测后整理的，速度是按普通笔记本 CPU 跑的粗略感受，不作为性能承诺。

这里的判断逻辑很直白：如果你只是想看效果，basic_rnn 起手；如果生成的旋律总是两句就原地打转，换 attention_rnn；如果要导出到宿主软件里当钢琴声部用，performance_rnn 的动态更自然；如果要做两段风格的融合，只有 music_vae 能做。别指望一个模型什么都能干，这个库的设计本来就是把任务切开。

2.4 温度参数：唯一需要反复调的旋钮

几乎所有生成模型都有 temperature 这个参数，但很多人只是随便填个 1.0 就不管了。它在数学上的作用是调整采样时的概率分布锐度：温度趋近 0 时，模型永远选概率最高的那个音，输出极其规整但很快就会陷入循环；温度升高，低概率的音也会被选中，创意性上来了，但容易跑调、出现离谱的跳进。

我的经验是把温度当成分档位来用，而不是连续调。0.5 到 0.7 适合需要稳定可用的商业素材；1.0 是默认值，效果中庸；1.2 到 1.5 适合找灵感，批量生成几十条再挑；超过 1.8 基本就是随机游走，偶尔会有惊喜但废片率极高。

# 同一段前置旋律，用三档温度各生成 5 条，横向对比 for t in 0.6 1.0 1.4; do melody_rnn_generate \ --config=attention_rnn \ --bundle_file=./attention_rnn.mag \ --output_dir=./out_temp_$t \ --num_outputs=5 \ --num_steps=128 \ --temperature=$t \ --primer_melody="[60, -2, 62, -2, 64, -2, 65, -2]" done

跑完之后不要只看文件名，直接播一遍。我自己踩过的坑是：温度低的那组听起来"最正确"，但十条几乎一模一样，等于白生成；温度高的那组十条里能挑出一两条有意思的，剩下的删掉就行。所以批量生成时把温度调高、数量拉大，反而更有效率。

3. 完整实操流程与关键环节实现

3.1 五分钟跑通第一个旋律

先下载 bundle 文件。magenta 的惯例是把权重打包成.mag或.ckpt文件，命令行的--bundle_file指向它。文件可以从项目的模型仓库里按模型名找到，下载后放在一个固定目录下，比如./models/。

# 目录约定，后面所有命令都基于这个路径 mkdir -p ./models ./output # 用一段上行音阶做引子，-2 表示休止 melody_rnn_generate \ --config=basic_rnn \ --bundle_file=./models/basic_rnn.mag \ --output_dir=./output \ --num_outputs=3 \ --num_steps=128 \ --temperature=1.0 \ --primer_melody="[60, -2, 62, -2, 64, -2, 65, -2]"

执行完在 output 目录里会出现generated_0.mid之类的文件。这一步的目的是确认整条链路是通的：bundle 能加载、模型能推理、MIDI 能写出。如果这一步就报错，先看错误类型，NotFoundError通常指向路径写错，InvalidArgumentError多半是 bundle 和 config 不匹配——用 attention_rnn 的 config 去加载 basic_rnn 的权重一定会失败。

3.2 用 Python API 接管，做可控生成

命令行够用，但一旦要做条件控制、批量处理、和其它逻辑串起来，就必须走 Python API。核心对象是序列生成器：先读 bundle，再从模型注册表里取生成器类，实例化并初始化，最后构造 GeneratorOptions 调用 generate。

import note_seq from note_seq.protobuf import music_pb2, generator_pb2 from magenta.models.melody_rnn import melody_rnn_sequence_generator from magenta.models.shared import sequence_generator_bundle BUNDLE = "./models/attention_rnn.mag" # 1. 加载权重包 bundle = sequence_generator_bundle.read_bundle_file(BUNDLE) # 2. 取生成器并初始化 generator_map = melody_rnn_sequence_generator.get_generator_map() generator = generator_map["attention_rnn"](checkpoint=None, bundle=bundle) generator.initialize() # 3. 构造前置片段：起手给定两句，后面让模型接 primer = music_pb2.NoteSequence() primer.tempos.add(qpm=100) for i, p in enumerate([60, 62, 64, 65, 67, 65, 64, 62]): primer.notes.add(pitch=p, start_time=i * 0.4, end_time=i * 0.4 + 0.35, velocity=85) primer.total_time = 8 * 0.4 # 4. 计算生成区间的秒数 qpm = 100 steps_per_quarter = generator.steps_per_quarter # 通常为 4 seconds_per_step = 60.0 / qpm / steps_per_quarter generate_steps = 160 start = primer.total_time end = start + generate_steps * seconds_per_step # 5. 配置生成参数，只生成指定区间 options = generator_pb2.GeneratorOptions() options.args["temperature"].float_value = 0.9 options.generate_sections.add(start_time=start, end_time=end) # 6. 生成并导出 result = generator.generate(primer, options) note_seq.sequence_proto_to_midi_file(result, "./output/api_out.mid") print("总时长 %.2f 秒, 音符数 %d" % (result.total_time, len(result.notes)))

这段代码里有几个点值得说开。第一步读 bundle 是有成本的，文件通常几十到上百 MB，如果在服务里高频调用，务必把 bundle 和 generator 缓存在进程级，别每次请求都读一遍。第二步的 initialize 会构建计算图，也是耗时操作，同样应该只做一次。第五步的 generate_sections 决定了"哪些时间段允许模型写音符"，start_time 之前的音符原样保留，这就是续写的实现方式；如果你把 start_time 设成 0，模型会重写整个片段，包括你给的引子。

还有一个细节：primer 里的 tempo 会被带入结果。如果你忘了设，模型会用一个默认节拍，导出的 MIDI 播起来速度不对。另外 velocity 我习惯给 85 左右而不是 127，因为模型倾向于模仿输入的音量水平，输入太满会导致输出也很"硬"。

3.3 换模型做插值：music_vae 的用法

music_vae 的思路和其它模型完全不同，它不是"接着往下写"，而是先编码到隐空间，再在隐空间里采样或插值。做风格过渡时非常有用：给两段风格不同的旋律，让它在中间生成过渡段。

from magenta.models.music_vae import configs from magenta.models.music_vae.trained_model import TrainedModel import note_seq # 选一个两小节旋律配置 config = configs.CONFIG_MAP["cat-mel_2bar_big"] model = TrainedModel( config, batch_size=4, checkpoint_dir_or_path="./models/cat-mel_2bar_big.ckpt" ) # 纯采样：一次出 4 条 samples = model.sample(n=4, length=32, temperature=0.8) for i, s in enumerate(samples): note_seq.sequence_proto_to_midi_file(s, "./output/vae_sample_%d.mid" % i) # 插值：在两段序列的隐向量之间取 5 个中间点 a = [samples[0]] b = [samples[1]] interp = model.interpolate(a, b, num_steps=5) for i, s in enumerate(interp): note_seq.sequence_proto_to_midi_file(s, "./output/vae_interp_%d.mid" % i)

注意 music_vae 的 length 参数是以步为单位的，而且配置决定了它固定生成几小节，cat-mel_2bar_big就是两小节。你不能指望它生成长段，它的定位是"短乐句生成器"，长段落要靠拼接。插值的中间结果有些会非常怪，这是隐空间不被完全约束导致的正常现象，做创意发散可以，做正式作品需要人工筛选。

鼓的生成走另一条命令，思路是给每个鼓件单独指定。

drums_rnn_generate \ --config=drum_kit \ --bundle_file=./models/drum_kit_rnn.mag \ --output_dir=./output/drums \ --num_outputs=3 \ --num_steps=128 \ --temperature=1.1

3.4 批量生成与后处理：让输出能直接用

单条生成只能听个响，真正能用在项目里的方案是批量跑加自动筛选。我一般的做法是：固定引子、扫一组参数网格、全部导出，然后用简单的启发式指标先过滤一轮，比如音域跨度是否过大、音符密度是否合理、有没有长时间空白。过滤掉明显废片，剩下的再人工听。

import os import note_seq from note_seq import midi_io def score_sequence(seq): """一个很粗糙的可用性打分，只做初筛""" notes = seq.notes if len(notes) < 8: return -1 # 太稀疏，直接丢 pitches = [n.pitch for n in notes] span = max(pitches) - min(pitches) if span > 24: return -1 # 跨了两个八度以上，通常很跳 duration = seq.total_time density = len(notes) / max(duration, 0.1) if density < 0.5 or density > 8: return -1 # 太稀或太密 return density # 批量跑完之后遍历目录做初筛 kept = [] for fname in sorted(os.listdir("./output")): if not fname.endswith(".mid"): continue path = os.path.join("./output", fname) seq = midi_io.midi_file_to_note_sequence(path) s = score_sequence(seq) if s > 0: kept.append((s, path)) print("初筛保留 %d 条" % len(kept))

后处理还有两件事值得做。一是重新量化，把浮点时间对齐到网格，避免导出到宿主软件后音符"黏"在一起；二是力度曲线，模型生成的力度往往很平，给一个渐强渐弱的手工包络，听感会立刻不一样。这两步都不复杂，但对最终效果的影响比调温度还大。

4. 常见问题与排查技巧实录

4.1 高频报错速查

下面这张表是我在不同机器、不同 Python 版本上反复踩出来的，按报错信息索引即可。

4.2 几个容易被误判的问题

第一个是"生成的旋律老是重复"。很多人第一反应是模型不行，其实多半是 temperature 太低加上 num_steps 太长。自回归模型在长序列上没有强约束，重复是数学上的必然倾向。我试过的有效办法是缩短单次生成长度，比如一次只生成 32 步，然后拿上一次的输出当前置再生成下一段，靠这种滚动生成打散重复。

第二个是"导出的 MIDI 在软件里听着不对"。这通常不是模型的问题，是量化对不上。magenta 默认的 steps_per_quarter 是 4，也就是十六分音符精度；如果你的工程设的是 480 PPQ 或者别的网格，导入时就会轻微错位。处理方式是在生成后统一用 pretty_midi 重写一遍，显式指定分辨率。

import pretty_midi import note_seq seq = note_seq.midi_file_to_note_sequence("./output/api_out.mid") pm = pretty_midi.PrettyMIDI(initial_tempo=seq.tempos[0].qpm if seq.tempos else 120) for inst_id in set(n.instrument for n in seq.notes): instrument = pretty_midi.Instrument(program=0, is_drum=(inst_id == 9)) for n in seq.notes: if n.instrument != inst_id: continue instrument.notes.append(pretty_midi.Note( velocity=n.velocity, pitch=n.pitch, start=n.start_time, end=n.end_time)) pm.instruments.append(instrument) pm.write("./output/normalized.mid")

第三个是"多轨输出全挤在一个音轨上"。这个问题很隐蔽，因为听感上似乎没问题，但在宿主软件里没法分轨调音色。原因是生成时所有 note 的 instrument 字段都是 0。解决办法是在导出前手动给不同音域或不同声部赋不同的 instrument 编号，代码上就是遍历 notes 按条件改字段值。

注意：magenta 的模型输出是符号层面的"可能性"，它不懂乐理对错，也不懂你的编曲意图。所有输出都必须经过人工筛选和二次编辑，把它当素材生成器而不是成品生成器，心态会好很多。

4.3 环境层面的独家经验

如果条件允许，用容器跑而不是本机裸装。原因很实际：这个库的依赖树比较深，TensorFlow、protobuf、numpy、librosa 之间存在版本牵制，一旦和主环境冲突，回滚成本很高。容器里跑崩了直接删掉重建，几分钟的事。

还有一点，别在机械硬盘上跑批量生成。bundle 文件加载加上频繁写 MIDI，磁盘 IO 会成为瓶颈，尤其是你要一次生成几百条的时候。我实测过同一份代码在固态盘上跑，整体耗时能少三分之一以上。

5. 进阶玩法：从调用现成模型到训练自己的

5.1 训练链路的三步走

预训练模型能出效果，但要让它贴合你的风格，还是得自己训。magenta 的训练链路是标准的三段式：原始 MIDI 转 NoteSequence、NoteSequence 转 tfrecord、tfrecord 喂给训练脚本。

# 第一步：把 MIDI 目录批量转成 NoteSequence 的 tfrecord convert_dir_to_note_sequences \ --input_dir=./my_midi \ --output_file=./data/notesequences.tfrecord \ --recursive # 第二步：转成模型需要的序列样本 melody_rnn_create_dataset \ --config=basic_rnn \ --input=./data/notesequences.tfrecord \ --output_dir=./data/melody_train \ --eval_ratio=0.10 # 第三步：开始训练 melody_rnn_train \ --config=basic_rnn \ --run_dir=./train/basic_rnn_run1 \ --sequence_example_file=./data/melody_train/training_melodies.tfrecord \ --hparams="batch_size=32,rnn_layer_sizes=[128,128],learning_rate=0.002" \ --num_training_steps=5000

第一步之后一定要看一眼日志里统计的序列条数。如果显示 0，说明你的 MIDI 没被识别，常见原因是文件损坏、或者全是没有音符的空轨。第二步的 eval_ratio 是留出的验证比例，0.1 意味着 10% 的数据不进训练，用来看过拟合。第三步的 hparams 是训练的核心旋钮：rnn_layer_sizes 控制容量，两层 128 单元对小型数据集就够，上到 512 会明显过拟合；learning_rate 从 0.002 起，loss 震荡就减半；batch_size 受显存限制，序列越长能塞的越少。

数据来源这里要提醒一句：自用没问题，但如果要公开发布训练产物，务必确认 MIDI 素材的授权情况。自己弹的、买断授权的、明确允许二次使用的，这三类才安全。

5.2 把生成结果接进工作流

真正让这个库产生价值的，是把它嵌进已有的创作流程。我见过两种比较实用的接法。一种是"素材工厂"：写个脚本，每天早上自动生成几十条不同温度、不同引子的片段，导出成 MIDI 放进指定文件夹，创作时打开就能挑。这种做法省掉了"打开工具、调参数、等结果"的重复动作，灵感的命中率靠数量堆。

另一种是"实时交互"：把 generator 常驻在进程里，接收前端传来的几个音高或节奏型，实时返回续写结果。这条路上要注意两点，一是生成耗时，二是并发生成时显存占用。我的做法是限制并发数、把生成长度压短、并且用一个队列削峰，宁可让用户多等半秒，也不要让进程被 OOM 杀掉。

5.3 跳出音乐：这个库的通用启发

magenta 里还有个画简笔画的模型，虽然效果比不上专门的项目，但它说明了一件事：这套"NoteSequence 中间表示 + 序列模型 + bundle 打包"的架构是可以迁移的。任何能离散化成序列的创作行为，都能套同一个框架——把领域对象序列化、定一个 protobuf、选一个自回归或 VAE 模型、打包成可加载文件。我在做别的生成任务时，基本就是照搬这个分层思路：数据层、表示层、模型层、接口层，四层切干净，后面换模型只动模型层。

代价是这套架构对"非序列"的创作形式不友好，比如构图、配色这类强全局约束的任务，硬套序列生成会很难看。所以我的判断是：任务本身有明显的前后依赖、可以切成时间步，就适合；任务需要全局一致性、局部改动牵一发动全身，就别硬套。

如果只给一条建议，我会说：先用预训练 bundle 把整条链路跑通，能听到声音、能导出文件、能进宿主软件编辑，再回头去研究参数和训练。顺序反了，很容易在环境配置和依赖冲突里耗光耐心，最后连模型能干什么都没看到。这个库最有趣的地方不在于它生成得多好，而在于它把"让机器写一段旋律"这件事的门槛压到了几条命令，剩下的探索空间全留给你自己。