YuE2 AI作曲从零跑通：环境权重、五步流程与听感调优

做 AI 作曲这块，模型迭代得快，但真正让人卡住的往往不是“模型行不行”，而是从下载到出声这一段路。YuE2 属于那种“你要是没提前算好显存、没搞明白歌词格式、没对齐采样率，就会在第一步耗掉一整个下午”的东西。我把这次从零跑通 YuE2、生成第一首带人声完整歌曲的全过程拆开写，包括环境怎么备、权重怎么下、五步流程怎么串、参数怎么调、报错怎么查。适合两类人看：一类是手里有张够用的显卡、想自己动手生成歌曲的独立开发者；另一类是已经把模型拉下来了、但一直卡在“跑是跑起来了，出来的是噪音”这一步的朋友。全文都是实操口径，命令、参数、目录结构、踩坑点都能直接对照着改。

1. 先摸清 YuE2 的能力边界，再决定要不要占那几十个G磁盘

很多人拿到一个模型的第一步就是git clone，然后下载权重，然后发现跑不动。YuE2 这类音乐生成模型的资源开销不属于“随便一台笔记本就能玩”的量级，所以动手前先把账算清楚，能省掉很多无谓的折腾。

1.1 它给出的产物是完整歌曲，不是背景音乐素材

这一点必须先说明白，因为它决定了你后面所有参数该怎么设。YuE2 走的是“歌词 + 风格描述 → 带人声的完整歌曲”这条路线，输出里通常包含人声轨和伴奏轨两部分信息，最终混合成一段立体声音频。它不是那种输入一句“轻松的钢琴曲”就吐出一段循环 BGM 的工具，你要给它歌词、要给它段落结构标记（主歌、副歌、桥段），它才会按你给的骨架去“唱”。

我一开始也误判过，拿了一段纯器乐的提示词丢进去，结果模型照样往里塞人声，因为它的训练目标里人声是默认存在的。想让它只出伴奏，通常得靠风格标签里明确排除人声，或者在后期把分离出来的人声轨静音掉。这个认知差会导致你前几次生成的产物完全不是想要的东西。

从技术路线看，YuE2 延续的是“文本与音频离散 token 化 + 自回归生成 + 声码器还原”的组合：先把歌词和风格描述编码成语言模型能吃的 token 序列，自回归地生成音频 token，再由声码器把 token 还原成波形。理解这条链路很重要，因为后面所有的报错和听感问题，几乎都能定位到这条链路的某一环上。

1.2 显存、内存、磁盘三本账，建议提前核算

我在三台不同配置的机器上都试过，差别非常大。下面这张表是实测下来比较有参考价值的档位划分，具体数字会随精度、分段长度、是否量化而变化，但量级是对的：

磁盘这一项特别容易被低估。权重通常是分片存放的，下载完是几个 GB 级的文件，解压或转换格式时还会临时占一份空间。我有一次磁盘只剩 30 GB，权重下到 90% 直接失败，重下了一遍才发现是空间不够，不是网络问题。

显存这块还有个坑：很多人看到“支持量化”就以为 8 GB 也能跑。能加载不代表能推理，长分段推理时 KV cache 会随序列长度线性增长，一段 4 分钟的歌曲对应的 token 数量相当可观，显存峰值往往出现在推理中段而不是加载时。我建议先按最短分段跑通，再逐步加长度，观察峰值。

1.3 三类需求它接不住，别浪费时间

第一类是“给我一段 15 秒的抖音卡点素材”。YuE2 的设计目标是长曲式结构，太短的片段它反而容易生成不完整的乐句，听起来像被硬切断了。

第二类是“精确控制某一个乐器在某秒进”。它是自回归生成，不是 DAW 里的 MIDI 编排，你能控制的是风格、段落、大致情绪，控制不到小节级别。

第三类是“要求人声咬字百分百准确”。中文歌词里生僻字、多音字、连读处理，模型的稳定性一般，同一段词跑两次结果可能不一样。这个要有心理预期，后面我会讲怎么通过歌词排版提高稳定性。

2. 环境与权重落地：三条下载路线，和它们各自会咬人的地方

这一段是整个流程里最枯燥但最容易出事的部分。我见过太多人环境装完了、权重下完了，一跑就报路径找不到，最后发现是目录层级多套了一层。

2.1 依赖安装的顺序问题，比版本号更致命

大部分人装依赖的习惯是“缺什么装什么”，在 YuE2 这种带音频处理链的项目上，这个习惯会带来很麻烦的后果。原因是音频解码、重采样、声码器推理这几块依赖的底层库有版本耦合，先装的包会把某个底层库锁在旧版本，后装的包又要求新版本，最后pip给你一个“依赖冲突已解决”的假象，运行时才炸。

我的做法是先建干净虚拟环境，再一次性按顺序装：先装与计算后端相关的基础包（框架本体、与其匹配的加速库），再装音频 I/O 相关（读写、重采样），最后装项目自身的依赖清单。这样如果出问题，能立刻定位到是哪一层。

# 建环境，Python 版本按项目要求来，别图新 python -m venv yue2-env source yue2-env/bin/activate # 第一步：计算后端。加速库版本必须和框架本体对齐，这一步别偷懒 pip install torch torchaudio --index-url <与你的驱动匹配的源> # 第二步：音频处理链 pip install soundfile librosa numpy scipy # 第三步：项目依赖 pip install -r requirements.txt

装完之后先做一次自检，别急着跑推理：

import torch, soundfile, librosa print("torch:", torch.__version__) print("cuda available:", torch.cuda.is_available()) print("cuda version:", torch.version.cuda) print("device count:", torch.cuda.device_count()) if torch.cuda.is_available(): print("device name:", torch.cuda.get_device_name(0)) free, total = torch.cuda.mem_get_info() print(f"free {free/1024**3:.1f} GB / total {total/1024**3:.1f} GB")

torch.cuda.is_available()返回False是最常见的第一个坑。九成情况是驱动版本和框架编译时的 CUDA 版本对不上，剩下一成是装成了 CPU 版本。看到False别急着改代码，先确认装的是不是带 CUDA 的轮子。

注意：torch.cuda.mem_get_info()拿到的空闲显存比nvidia-smi显示的更贴近实际可用值，因为它排除了驱动预留。判断“能不能跑”时以这个数为准更靠谱。

2.2 权重分片下载：断点续传和校验缺一不可

权重通常是多个分片文件，几十 GB 的量级。这个体量下，一次下完的概率其实不高。我用过的三条路线，各有各的适用场景：

我自己的习惯是路线二，虽然笨但最稳。每个分片下完立刻核对文件大小，全部下完再统一做一次哈希校验。校验这一步千万别省——我遇到过一次分片下载“成功”但文件尾部缺了几 MB，加载时抛的是权重形状不匹配的错，报错信息指向模型结构，查了两小时才想到是文件不完整。

# 目录规划建议：模型、声码器、输出分开，别混在一起 mkdir -p ./models/YuE2 ./models/vocoder ./outputs ./tmp # 分片下载示例（下载工具用你手头有的，占位符替换即可） dl --repo <主模型仓库ID> --local-dir ./models/YuE2 --resume dl --repo <声码器仓库ID> --local-dir ./models/vocoder --resume # 校验：先看文件清单和大小，再算哈希 ls -lh ./models/YuE2 sha256sum ./models/YuE2/*.safetensors > ./tmp/check.txt

2.3 目录层级多套一层，是第一类报错的元凶

--local-dir这类参数的行为在不同工具之间不一致，有的会在目标目录下再建一层以仓库名命名的子目录，有的直接铺平。结果就是你按文档写的路径./models/YuE2/config.json，实际文件在./models/YuE2/<仓库名>/config.json。

我的处理办法很土但有效：下完之后手动ls一遍，确认config.json、权重分片、tokenizer相关文件都在同一层，不在就手动挪平。然后在配置里统一用绝对路径，避免工作目录变化导致的相对路径失效。

import os, json MODEL_DIR = os.path.abspath("./models/YuE2") VOC_DIR = os.path.abspath("./models/vocoder") # 加载前先断言关键文件存在，比等框架抛错快得多 required = ["config.json"] for f in required: p = os.path.join(MODEL_DIR, f) assert os.path.isfile(p), f"missing: {p}" shards = [f for f in os.listdir(MODEL_DIR) if f.endswith(".safetensors")] print("shards:", len(shards)) assert len(shards) > 0, "没有找到权重分片，检查是否多套了一层目录"

这段断言看着简陋，但帮我省掉过好几次来回折腾。加载大模型动辄几分钟，与其等它跑到一半报错，不如在入口处花三秒钟确认。

3. 五步流程串起来：从一句歌词到一段能听的音频

流程本身不复杂，复杂的是每一步之间那些“文档没写但你不知道就过不去”的衔接。我按自己实际跑的顺 sequence 拆成五步，每一步都标出输入、输出和最容易出错的地方。

3.1 第一步：写一份模型读得懂的歌词与风格描述

这是最被低估的一步。很多人以为歌词就是随便贴一段文字，实际上模型对排版极其敏感。段落标记、换行位置、标点使用，都会影响生成结果。

我用的格式是这样的：

[genre] female vocal, mandopop, piano, strings, mid-tempo, emotional [/genre] [verse] 窗外的雨停了又下 桌上的茶凉了半盏 我把没说完的话 折成纸船放进夜里 [chorus] 如果风记得我的名字 就替我去看一眼远方 那些没寄出去的信 还在等一个回音

几条实战规则：

段落标记必须成对出现且单独占一行。[verse]、[chorus]、[bridge]这类标记如果和歌词挤在同一行，模型有可能把它当成正文唱出来。

每行字数尽量控制在相近范围。忽长忽短会让节奏判断失准，听起来像念白和唱段混在一起。我一般控制在 7–12 字一行。

标点越少越好。逗号句号会被当成断句依据，但过多标点会让模型生成很多短的停顿，听感碎。我的习惯是行末不加标点，只在语气需要停顿的地方留一个逗号。

风格标签用逗号分隔的短词，不要写成句子。写成“这是一首带有淡淡忧伤的流行歌曲”这种自然语言描述，模型的响应会变弱；写成female vocal, mandopop, piano, emotional这种标签堆叠，效果明显更稳。

3.2 第二步：把文本切成模型认识的 token 序列

这一步在脚本里通常是一行调用，但它是排查问题的关键观测点。你需要确认的是：歌词有没有被正确切分，段落标记有没有被识别成特殊 token，序列长度有没有超出模型的最大上下文。

from transformers import AutoTokenizer tok = AutoTokenizer.from_pretrained(MODEL_DIR, trust_remote_code=True) prompt = open("./tmp/lyrics.txt", encoding="utf-8").read() ids = tok(prompt, return_tensors="pt").input_ids print("token 数量:", ids.shape[-1]) print("前 40 个 token 解码回文本:") print(repr(tok.decode(ids[0][:40], skip_special_tokens=False)))

重点看两件事。一是总 token 数，它直接决定后面要生成多长的音频；二是解码回来的文本里，段落标记是否还是完整的[verse]形态，如果被拆成了[,verse,]三个 token，说明 tokenizer 没有把这些标记注册为特殊 token，生成的段落结构会很乱，需要检查是否漏了配置文件。

这里有个换算关系值得记住：音频 token 的帧率决定了时长和 token 数量的对应。粗略估算，1 秒音频大约对应 25 个音频 token（每 40 毫秒一个），所以一首 3 分钟的歌大约是 4500 个音频 token。这个数字直接用于设置生成长度上限，设小了歌会被截断，设大了浪费显存和时间。实际帧率以你所用声码器的配置为准，跑之前翻一下配置文件里的采样率与帧率参数。

3.3 第三步：两阶段推理，先出音乐 token 再出声

YuE2 的推理是分两段的。第一段用自回归模型根据文本 token 生成音频 token 序列，第二段用声码器把 token 序列还原成波形。很多人把这两段揉在一起跑，出了噪音根本不知道是哪一段的问题。我的建议是分两次执行，中间把 token 序列存盘，方便复现和对比。

import torch from transformers import AutoModelForCausalLM model = AutoModelForCausalLM.from_pretrained( MODEL_DIR, torch_dtype=torch.float16, device_map="auto", trust_remote_code=True, ) model.eval() gen_cfg = dict( max_new_tokens=3800, # 约 150 秒，按 25 token/秒 估算后留余量 temperature=0.9, top_p=0.92, repetition_penalty=1.15, do_sample=True, ) with torch.inference_mode(): out = model.generate(ids.to(model.device), **gen_cfg) audio_tokens = out[0][ids.shape[-1]:] torch.save(audio_tokens, "./tmp/tokens_stage1.pt") print("生成 token 数:", audio_tokens.shape[-1])

device_map="auto"在显存不够时会自动把部分层丢到内存里，能跑但会慢很多。如果你看到显存占用很低但速度奇慢，八成是触发了这个回退，这时候要考虑降精度或者缩短分段。

第二段解码单独跑：

vocoder = ... wav = vocoder.decode(torch.load("./tmp/tokens_stage1.pt"))

分开跑还有一个好处：调参时只重跑第一段，不用每次都过声码器，迭代速度快一倍以上。

3.4 第四步：解码与采样率对齐，这里最容易出“能播但不对”的问题

声码器输出的采样率和后续处理链的采样率不一致，是一个隐蔽性极强的问题。表现是音频能播放、时长也对，但整体音高偏高或偏低，人声听起来像“快放”或“慢放”。

import soundfile as sf import librosa wav, sr = ... # 声码器输出的 numpy 数组与采样率 print("原始采样率:", sr) TARGET_SR = 44100 if sr != TARGET_SR: wav = librosa.resample(wav, orig_sr=sr, target_sr=TARGET_SR) # 归一化，避免削波 peak = abs(wav).max() if peak > 0: wav = wav / peak * 0.95 sf.write("./outputs/first_take.wav", wav, TARGET_SR, subtype="PCM_24")

归一化那一步在试听阶段特别重要。模型输出的峰值经常超过 1.0，直接写成 PCM_16 会硬削波，听感上是刺耳的破音，很容易被误判成“模型质量差”。存成PCM_24比PCM_16更保险，留出的余量足够后续做母带处理。

3.5 第五步：分段拼接与试听，接缝处理决定成品感

生成的音频超过模型单次能处理的上限时，就要分段生成再拼接。这一步做不好，接缝处会有明显的“咔”声或者节奏断裂。

我的做法是让相邻分段保留一段重叠，然后做交叉淡化：

import numpy as np def crossfade(a, b, sr, fade_ms=120): n = int(sr * fade_ms / 1000) n = min(n, len(a), len(b)) if n <= 0: return np.concatenate([a, b], axis=-1) # 等功率交叉淡化，比线性淡化在接缝处更自然 t = np.linspace(0, np.pi / 2, n) fa, fb = np.cos(t), np.sin(t) if a.ndim == 2: fa, fb = fa[None, :], fb[None, :] merged = a[..., -n:] * fa + b[..., :n] * fb return np.concatenate([a[..., :-n], merged, b[..., n:]], axis=-1)

等功率交叉淡化比线性淡化听起来更自然，原因是线性淡化在两个信号相位接近时会造成功率的凹陷，听感上是接缝处“空了一下”。这个细节在网上很多教程里被忽略了。

提示：重叠区长度建议不少于 200 毫秒，太短的话淡化窗口覆盖不到一个完整的音乐事件，接缝仍然能听出来。

4. 影响听感的参数没几个，但它们之间会互相拉扯

跑通之后你会发现，参数表里密密麻麻几十项，真正对成品质量有决定性影响的不超过六个。剩下的多为性能开关。我把这几个参数按“调了会怎样”整理成实际可操作的口径。

4.1 温度和 top_p 的组合，比单独看某一个值重要

温度控制随机性，top_p 控制候选范围。两个参数单独调的时候，很容易出现“温度升高后跑调变多”或者“top_p 压低了旋律变得呆板”的情况。真正有效的做法是成对调整。

我的经验是先固定在 0.9 / 0.92 跑三条，听差异，如果三条都太相似，就把温度加到 1.0、top_p 留 0.92 再跑两条。注意只动一个参数，动两个就分不清是谁的作用了。这个排查思路和调其他生成模型是一样的，但在音频上特别重要，因为耳朵对差异的判断需要对比，混着改很难建立直觉。

4.2 重复惩罚是双刃剑，超过 1.3 通常就开始伤旋律

repetition_penalty用来抑制模型反复生成相似的片段。设成 1.1–1.2 确实能减少“副歌重复八遍”的情况。但超过 1.3 之后，模型会过度回避重复，连正常的音乐重复（比如动机的再现）都被压掉了，结果是旋律变得支离破碎，缺少支撑。

我踩过的具体坑：在一首需要反复副歌的流行结构里，我把惩罚设到 1.35，结果副歌每次都不一样，本来应该强化的记忆点被拆成了三个相似但不相同的段落，整体听起来很散。改回 1.15 之后立刻就正常了。

4.3 分段长度和重叠区，直接决定显存峰值和接缝质量

分段长度是性能与质量的交叉点。分得越长，模型能看到的上下文越完整，乐句衔接越自然，但显存峰值越高，时间成本也线性增长。分得太短，接缝多，拼接痕迹重。

CONFIG = { "segment_tokens": 2000, # 约 80 秒/段 "overlap_tokens": 250, # 约 10 秒重叠，够淡化窗口 "fade_ms": 150, }

我一般会先按 60–80 秒一段跑，观察显存峰值（用nvidia-smi -l 1或者torch.cuda.max_memory_allocated()记录）。如果峰值离显存上限还有 20% 以上余量，就把段长往上提；如果贴着上限甚至触发回退，就降到 40–50 秒。

torch.cuda.reset_peak_memory_stats() # ... 推理 ... peak = torch.cuda.max_memory_allocated() / 1024**3 print(f"峰值显存: {peak:.2f} GB")

这个峰值数据比任何理论估算都准，跑一次记下来，以后同类长度的任务心里就有数了。

5. 跑不通和跑出来难听，是两类完全不同的问题

这两类问题的排查路径几乎不重叠。混在一起查是最浪费时间的做法。我的原则是先分类，再定位。

5.1 报错类故障：从加载、设备、形状三个方向切

我遇到过的报错按出现频率排一下：

第二条我印象最深。当时报的是形状不匹配，我第一反应是模型版本不对，重下了一遍全精度权重，问题依旧。后来逐个文件比对大小，发现某个分片比其他分片小了整整 2 GB，是下载中断后工具没有正确续传，留了个残文件在那。删掉重下就好了。所以下载完一定要核对每个分片的大小，不能只看总数。

排查顺序我总结成一条链：先确认torch.cuda.is_available()，再确认权重文件齐全且大小一致，再确认模型和声码器的路径没串，最后才怀疑参数。这个顺序覆盖了绝大多数情况，而且每一步都很便宜，花不了几分钟。

5.2 听感类问题：静音、爆音、跑调、人声糊，各有各的对策

这四类问题我全踩过，处理方式完全不同：

静音或无声音：先看生成的 token 数量。如果audio_tokens.shape[-1]是 0 或者只有个位数，说明生成阶段就失败了，通常是max_new_tokens设置问题或者输入 prompt 为空。如果 token 数量正常但解码出来是静音，问题在声码器，检查解码时输入的 token 范围是否包含了特殊标记。

爆音和削波：模型输出的峰值经常超过 1.0，一定要做归一化并留余量。我习惯写到 0.95 峰值，后续再处理。另外PCM_16在高动态段落容易出问题，改PCM_24或float32会好很多。

跑调：多数情况下是温度和重复惩罚设得太激进。温度超过 1.05 之后跑调概率明显上升；重复惩罚超过 1.3 会让旋律失去内在逻辑，听起来像走调但其实是结构散了。先把这两个调回中间值再判断。

人声糊、咬字不清：这是歌词排版和风格标签的问题，不是模型质量问题。我的经验是每行字数压到 8 字左右、去掉多余标点、在风格标签里明确写clear vocal这类提示，改善非常明显。另外，人声和伴奏的比例在生成阶段是固定的，如果觉得人声被压住，可以尝试分离出人声轨单独提升音量再混回去。

5.3 速度优化：从一小时一首到能接受

第一次跑我用的是默认配置，一首 3 分钟的歌花了将近 50 分钟。做了三件事之后降到了十几分钟：

第一，把不必要的日志和中间保存关掉。有些脚本默认每步都存检查点，磁盘 I/O 开销很大。

第二，音频 token 的生成是自回归的，逐 token 出，没有并行空间，所以提速主要靠减少总 token 数。把段长切小、并行跑多段，比单段拉长更快，因为可以批量提交。

第三，确认没有触发device_map="auto"的显存回退。显存回退会让部分层在内存和显存之间来回搬，速度能掉一个量级。用torch.cuda.max_memory_allocated()看峰值，如果远低于物理显存却速度很慢，基本就是这个问题，手动指定device_map={"": 0}强制全上显卡试试。

注意：强制全上显卡前先算一下权重体积，7B 半精度约 14 GB，加上推理时的 KV cache 和声码器，24 GB 卡才比较稳。12 GB 卡上强行这么干只会换来 OOM。

6. 从能出声到能发出去，几个真正拉开差距的细节

跑通只是起点。同一个模型，不同人跑出来的成品差距可以非常大，差距主要在这些地方。

6.1 歌词排版对咬字的影响，比换模型还明显

我做过一组对比：同样的歌词内容，一种是一行十几个字连着写，一种是一行 8 字左右换行，其他参数完全相同。前者听起来含糊、拖音、断句奇怪；后者咬字清楚很多，节奏也自然。原因不难理解，换行给了模型一个天然的乐句边界信号，它不需要自己去猜哪里该停。

几个具体的排版习惯：主歌每行控制在 7–9 字，副歌可以稍长到 10–12 字，因为副歌情绪更高、乐句更长。避免在同一段落里混用极短句和极长句。段落之间的空行保留，它相当于给模型的段落切换提示。

还有一点，生僻字和多音字尽量提前换成常用表达。这不是说模型一定读错，而是稳定性不够，同一段词跑两次可能结果不同，反复重跑不如一开始就规避。

6.2 风格标签的写法：堆词有效，但要堆对维度

风格描述这块，越具体越好，但“具体”指的是维度覆盖，不是形容词数量。我一般覆盖五个维度：

五个维度各给一两个词，基本就能锁定方向。我试过堆十几个形容词，结果反而不如四五个标签稳定，因为互相冲突的标签（比如同时写aggressive和gentle）会让模型摇摆。

6.3 我目前在用的一套可复用流程

固定成脚本之后，每次做新歌只需要改两个文件：歌词文件和风格配置。省下来的时间都在调听感上，而不是重跑流程。

# 目录约定 # ./input/lyrics.txt 歌词与段落标记 # ./input/style.json 风格标签配置 # ./tmp/ 中间 token # ./outputs/ 成品音频 python step1_build_prompt.py # 合并歌词与风格，输出标准 prompt python step2_tokenize.py # 切 token，打印长度与解码校验 python step3_generate.py # 生成音频 token，落盘 python step4_decode.py # 声码器还原 + 重采样 + 归一化 python step5_concat.py # 分段拼接 + 交叉淡化 + 导出

每一步都落盘中间产物，这看起来啰嗦，但排错时价值巨大。哪一步出问题就只重跑那一步，不用从头来。我有一次声码器版本装错，就是因为中间 token 存着，改完声码器直接重跑第四步，两分钟验证完，要是从头跑又是半小时。

另外我在step3里加了个小逻辑，每次跑都记录下当次的参数组合和峰值显存到一个 CSV，跑多了之后回看这份记录，能很快找到“上次那首听着不错的是什么参数”，比凭记忆强太多。

6.4 一个容易被忽略的环节：成品试听要在多套设备上过一遍

耳机上听着平衡的混音，在手机外放上可能人声完全消失。这不是模型的问题，是混音比例和频段分布的问题。我现在固定用三套设备过一遍：头戴耳机、手机外放、一个便宜的蓝牙小音箱。三套都能听清人声、低频不糊，才算过关。如果只在耳机上听，很容易把低频堆得过重，因为耳机能还原，小喇叭还原不了。

如果发现外放时人声被伴奏盖住，处理办法不是整体提音量，而是把伴奏在中频段稍微压一点，或者把人声轨单独提 2–3 dB 再混。这个操作在生成的原始分轨上做，比在混好的成品上做效果好得多。

我自己的体会是，YuE2 这类工具真正的门槛不在“能不能跑起来”，而在“跑起来之后你能不能判断哪里不对”。前者靠一份靠谱的教程加半小时就能解决，后者靠的是一条清晰的排查链路和对参数的手感。上面这套流程我跑了十几首歌之后才慢慢定型，中间浪费的时间大部分都花在“不知道问题出在哪一环”上。所以如果你刚开始，强烈建议先把五步拆开分别跑通、分别验证，别图省事写成一个脚本一把梭。等到每一环的输入输出你都心里有数了，再合并成自动化流程，那时候提速才是真的提速，而不是把问题藏起来。