凌晨一点，我把一段自己写的中文词塞进 YuE，敲下回车，然后去泡了杯茶。二十多分钟后终端还在滚 token，音箱里传出第一句时我愣了一下——咬字是糊的，但旋律走向、和声色彩和我想的基本一致。那一刻我就知道，这个开源项目值得花时间啃。YuE 是一套开源的**词生歌（lyrics-to-song）**基础模型：你给它一段带结构标签的歌词，再加一行风格描述，它能直接吐出带人声和伴奏的完整歌曲音频，而不是几十秒的循环片段。它解决的是"我脑子里有首歌但不会编曲、不会唱、不会混音"这个老问题——把作词和风格描述当成输入，把成品音频当成输出。这篇东西写给三类人：想本地部署跑通一次音乐生成模型的开发者、想给短视频或独立游戏做原创配乐的内容创作者、以及想拿开源模型做二次开发（微调、分轨、接 DAW）的技术人。不管你是刚装完显卡驱动的新手，还是已经在折腾 LoRA 的老玩家，下面的内容都能直接抄作业。
1. YuE 到底是什么：一个把歌词"唱"出来的双阶段模型
1.1 词生歌这事，难在"对齐"两个字
很多人第一次接触 AI 音乐，是从"文生音乐"开始的：输入 "lo-fi chill beat"，出来一段没有歌词的氛围音频。这类任务本质上是在生成"音色和节奏的纹理"，模型不需要理解语言，只要把音频的统计规律模仿像就行。词生歌完全是另一个难度量级——它要求模型在同一段时间轴上同时处理两件事：歌词的语义与音节，以及音乐的旋律与伴奏。你可以把它类比成给一段旋律填词，或者反过来给一段词谱曲，而且填完之后还得唱出来，音高、时值、换气点都要对得上。
真正的难点在"对齐"。一句"月光落在窗台上"有七个音节，模型必须决定哪几个音节落在强拍上、哪些字要拖长音、哪个字换气。传统做法是把歌词和音频分开建模，中间靠一个对齐模块硬接，结果就是人声像在念经，节奏对不上拍。YuE 的思路是把歌词 token 和音乐 token 塞进同一条序列里，让一个自回归的语言模型去同时预测下一个词和下一帧音乐。这样对齐就不再是外挂模块的事，而是模型在训练中自然学出来的能力，这也是它能"唱清楚"的根基。
理解了这一点，后面很多现象就说得通了：为什么歌词的断行方式会影响成品、为什么结构标签不能乱写、为什么长歌容易在后半段崩掉。这些都不是玄学，是序列建模的必然结果。
1.2 两个阶段的分工：语义 token 和声学 token 的接力
YuE 采用的是两阶段架构，这个设计决定了它的显存占用、生成速度和最终音质上限。
第一阶段是一个音乐语言模型，参数量在 7B 量级，主干沿用 LLaMA 系的结构，输入是"风格标签 + 歌词 + 已生成音频 token"的混合序列。它的任务是预测语义层面的音乐 token——可以粗略理解为"这一段该是什么音高、什么节奏、什么情绪走向"，粒度比较粗，但保留了音乐的结构信息。这一阶段决定了歌好不好听、走向是否合理。
第二阶段是一个声学建模模块，参数小得多（1B 量级），它拿到第一阶段的语义 token，用**残差向量量化（RVQ）**的方式逐层还原成多层级声学 token，最后交给解码器重建波形。RVQ 你可以类比成"先画大色块，再一层层加细节"：第一层定轮廓，后面几层补高频和瞬态。这一阶段决定了音质细不细、人声干不干净。
这种"重语义、轻声学"的分工有明确的工程动机：把大部分算力花在音乐结构上，音质部分用较小的模型配合批量解码来提速。代价是音质上限受第二阶段的容量限制，所以你偶尔会听到类似"隔了一层布"的质感——这不是配置错了，是架构本身的取舍。想要更高音质，现阶段可行的路子是导出分轨后自己在 DAW 里做后期，而不是指望调参数调出来。
1.3 双轨和风格标签：模型能听懂的"谱面语言"
YuE 有个很实用的特性：它在生成时把人声轨和伴奏轨分开建模再交织。这意味着两件事——一是你能拿到相对独立的人声和伴奏，方便后期；二是你可以通过提示词分别影响两边，比如让伴奏偏原声吉他、让人声偏气声。这个设计在开源方案里不算常见，是它比"一整块音频丢给你"的方案更工程化的地方。
另一件事是显式结构标签。模型在训练时见过大量带标签的数据，所以它认识[verse]、[chorus]、[bridge]、[outro]、[inst]这类段落标记，也认识风格、配器、人声类型、BPM、调性这几类全局描述。这些标签不是装饰，而是硬约束——你写了[chorus]，模型才倾向于把情绪推上去；你写了[inst]，它才知道这里该进间奏。很多人第一次跑出来觉得"平淡没高潮"，八成是因为歌词文件从头到尾没有一个结构标签，模型只能按平均概率往前推。
提示：结构标签要写在歌词文件里、单独占一行，且和歌词内容之间留出空行，模型对格式的敏感度比想象中高。
2. 本地跑通前的硬件与环境账：算清楚再动手
2.1 显存、显卡代际与生成时长的换算
YuE 是个吃显存的活。7B 的第一阶段模型在 bf16 下光权重就要十几个 GB，加上 KV 缓存和中间激活，24GB 显存是比较舒服的起点。我整理了一张常见配置的实测体感表，供你判断自己的机器能不能上：
| 显存 | 典型卡 | 可行性 | 需要做的妥协 |
|---|---|---|---|
| 24GB | 3090 / 4090 | 顺畅 | 基本不用调，可开大 batch |
| 16GB | 4080 / 4060Ti 16G | 可行 | 段落数减到 1-2，第二阶段 batch 降到 1 |
| 12GB | 3060 / 4070 | 勉强 | 需要量化或分段跑，速度很慢 |
| 8GB | 多数笔记本卡 | 不建议本地跑 | 用云端实例更划算 |
| 无独显 | Apple Silicon | 可试但慢 | 走 MPS，速度按十几倍打折 |
生成时长也要有心理预期。以我手头 4090、bf16 的环境为例，一首两分钟左右的成品需要十几分钟量级，其中第二阶段（声学还原）占大头。你看到别人说"几秒钟出歌"，那是商业闭源服务，本地开源不是这个数量级。把--stage2_batch_size从 1 提到 4，通常能明显压缩这段时间，代价是显存峰值上升，这是最值得优先调的一个参数。
2.2 环境依赖里最容易翻车的三个点
官方仓库给的步骤看起来很短，但实际坑集中在三处。
第一是flash-attn。这个东西编译时对 PyTorch 版本、CUDA 版本、编译器版本极其挑剔，pip install flash-attn直接编译十有八九半小时起步然后报错。稳妥做法是先锁定torch==2.4.0配对应 CUDA 版本的轮子，再去 flash-attention 的 release 页找预编译 wheel，文件名里的cu12x和torch2.4必须和你的环境完全对上，然后pip install 本地wheel路径装。装不上会直接导致推理脚本 import 失败，而很多人会误以为是模型权重的问题。
第二是Python 版本。建议锁在 3.10，用 conda 建独立环境。3.12 上部分依赖还没有对应轮子，会被迫走源码编译，然后连锁触发第一个坑。
第三是Windows。不是不能跑，但你会在 flash-attn 和 NCCL 相关的报错上耗掉一整天。我自己的选择是直接上 WSL2 或者干脆用 Linux 机器，省下来的时间足够你把歌词写好十遍。
conda create -n yue python=3.10 -y conda activate yue # 按你的 CUDA 版本选择对应的 pytorch 安装命令 conda install pytorch==2.4.0 torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia -y pip install -r requirements.txt # 关键一步：装预编译的 flash-attn，别让它现场编译 pip install /path/to/flash_attn-2.x.x+cu12xxtorch2.4.0-cxx-cp310-cp310-linux_x86_64.whl2.3 权重选择：两个阶段怎么搭
模型权重在 Hugging Face 上分两大类。第一阶段的模型名里通常带s1，后面跟语言范围和推理模式的缩写，常见后缀有cot和icl——前者是常规生成，后者支持用一段参考音频作为提示（这个特性在第五节会细讲）。语言方面会区分英语、中日韩等不同版本，如果你主要写中文歌词，一定要选带中文能力的那个，用纯英文权重跑中文词，结果基本是含混的念白。
第二阶段的模型名里带s2，通常是 1B 的通用版本。这一层基本没什么可选的，跟着第一阶段配就行。下载完注意核对体积和文件完整性，中断过的下载会留下残缺的权重文件，加载时报的错往往是"某个 tensor 尺寸不匹配"，很容易误判成版本冲突。
3. 我的第一次完整生成：从歌词文件到能听的音频
3.1 歌词文件怎么写才不会被"唱糊"
歌词文件是效果的第一决定因素，比任何采样参数都重要。三个原则：
按乐句断行，不按句号断行。模型的换气点主要靠换行来推断。你写成一整段，它会随机找地方断气，听起来像喘不上来。建议每行控制在 8-16 个汉字，和你想听的一个乐句长度对齐。
结构标签给足。一段完整的歌至少要有主歌、副歌、间奏的划分。标签单独占行，前后留空行。标签写错或写成中文全角括号，模型会当普通文字处理，等于白写。
每段旋律提示后面的内容别太长。同一段落连续写二十行歌词，后半段容易跑调或复读，这是长序列自回归的通病。
一个可以直接抄的骨架长这样：
[verse] 走过那条街 灯还亮着 你说的话 我还没忘 [chorus] 如果时间能倒着走 我还会站在那个路口 [inst] [verse] ...3.2 风格提示文本的三行结构与填写策略
风格提示一般写在独立的文本文件里，按行拆分不同维度，常见是三到四行：曲风、配器、人声类型，有些版本还接受 BPM 和调性。写法上有几个我认为影响很大的经验：
- 曲风词不要堆太多，两三个标签足够，堆五个以上模型会钓不出重点，出来的是四不像。
- 配器写具体乐器而不是抽象形容词。"温暖""治愈"这种词对模型几乎没有约束力，写"原声吉他、弦乐、轻鼓"才有用。
- 人声类型越明确越好。"female vocal, breathy, close-mic" 比 "nice voice" 强一百倍。
- BPM 和调性属于"能写就写"。写上去之后，段落之间的节奏一致性会明显好转，尤其是多段落续写时。
注意：风格文件的行数格式不同版本可能有差异。跑通之前先打开仓库里自带的样例文件看一眼，按它的行数来，比你猜格式靠谱得多。
3.3 推理命令逐参数拆解
跑通一次的核心命令大概长这样，我把每个参数为什么这么设讲清楚：
python infer.py \ --cuda_idx 0 \ --stage1_model m-a-p/YuE-s1-xxx \ --stage2_model m-a-p/YuE-s2-1B-general \ --genre_txt genre.txt \ --lyrics_txt lyrics.txt \ --run_n_segments 2 \ --stage2_batch_size 4 \ --max_new_tokens 3000 \ --repetition_penalty 1.1 \ --output_dir ./output--run_n_segments是这次要生成几个段落，是控制总时长最直接的开关。第一次跑建议设 1，先看清楚一个段落对应多少秒音频，再推算整首歌需要几段。这个数字每个版本可能不同，自己实测比查文档快。
--max_new_tokens决定单个段落生成多长，和段落时长基本成正比。设太小会中途截断，设太大容易触发复读。
--repetition_penalty是防复读的关键。1.1 是个安全起点；如果听到某一句旋律反复鬼打墙，往上加到 1.2；如果反而觉得旋律变得杂乱跳脱，就往回降到 1.05。
--stage2_batch_size是速度与显存的平衡杆，显存够就往上加，这是唯一能明显提速的参数。
3.4 输出文件的命名与试听流程
跑完之后输出目录里会出现音频文件，命名一般包含段落序号。别急着一次性听完整首，按这个顺序检查效率最高：
- 先单听第一阶段对应的段落，确认人声旋律走向对不对。如果这一层就不对，别调后面的参数，回去改歌词和风格提示。
- 再听第二阶段还原后的成品，重点听咬字和伴奏清晰度。这一层糊了，是显存不够或者 batch 设置问题导致的中途重试。
- 最后连续播放，听段落接缝处有没有节奏漂移。接缝问题是分段生成的通病，处理办法在下一节。
4. 出片质量不稳定的四类症状与排查链路
4.1 人声含糊、咬字不清
这是最常见的抱怨，但原因至少有四种，得顺着链路排。
第一步先看歌词是不是被当成纯文本念了。如果你听到的是平铺直叙、几乎没有音高起伏的人声，多半是第一阶段的模型语言版本和你的歌词语言不匹配，去换对应的权重。
第二步看是不是段落太长。单个段落里歌词行数超过十五行，前后咬字质量会明显下滑。把长段落拆成两个，分别生成，再接起来。
第三步看第二阶段的还原质量。如果旋律本身没问题，只是听着发闷、齿音缺失，那是声学还原的容量限制或者显存不足导致的降级。调小--stage2_batch_size反而可能改善，因为显存压力小了不会触发异常路径。
第四步才是采样参数。前面三步都排干净了再动 temperature 之类的参数，否则你只是在用一个随机性掩盖另一个问题。
4.2 段落之间的接缝断裂
分段生成的本质是"续写"：后一段以前面已经生成的 token 作为上下文。所以接缝问题的根源通常不是模型不会写，而是信息在传递中丢了。
表现有两种。一种是节奏漂移，第二段的鼓点和第一段对不上；另一种是情绪掉档，副歌接主歌时能量突然塌下去。处理办法我试过三个，按有效性排序：
- 在段落边界处补一个结构标签，明确告诉模型"这里回到主歌"，让它的先验把节奏拉回来。
- 固定风格提示文本，前后两段用完全一样的 genre 文件，包括 BPM 和调性。中途改风格提示是接缝断裂的头号元凶。
- 减少段落切换次数。如果能通过加大
--max_new_tokens把两段合成一段生成，优先这么做。模型的内部连贯性永远好于外部的拼接。
4.3 后半段跑调或复读
这是自回归模型的老毛病：上下文越往后越长，注意力被稀释，模型开始"抄最近的自己"，于是旋律在原地打转，或者调性慢慢往上爬。缓解思路是打断这种自我强化的循环。
提高--repetition_penalty是最直接的一招，但别一次加太狠，1.15 到 1.2 之间试。同时检查歌词是不是在后半段缺乏变化——如果后半段歌词的句式、字数、韵脚和前面高度雷同，模型很难不重复自己。给后半段换韵脚、改句式长度，往往比调参数更有效。
还有一个容易被忽略的原因：总时长超过了模型的有效上下文。一首五分钟的歌硬要一口气生成，后半段必然失控。老老实实分段，接受拼接成本。
4.4 显存溢出与中途被杀
报错形态通常是 CUDA out of memory，或者进程被系统直接 kill 掉（后者在 WSL2 里尤其常见，因为 WSL 有一层内存上限）。
排查按这个顺序走：先把--stage2_batch_size降到 1，这是收益最大的操作；再减--run_n_segments，把一次生成拆成多次；然后确认模型加载用的是 bf16 而不是 fp32，fp32 会让显存直接翻倍；最后检查有没有别的进程在占显存，浏览器开着一堆标签页也会吃掉一两个 GB。
如果是 WSL2 下被 kill，去改.wslconfig里的内存上限，或者干脆在原生 Linux 上跑。
| 症状 | 最先排查 | 其次排查 | 最后手段 |
|---|---|---|---|
| 人声含糊 | 语言版本是否匹配 | 段落是否过长 | 采样参数 |
| 接缝断裂 | 风格提示是否一致 | 是否有边界结构标签 | 合并段落 |
| 后半跑调 | repetition_penalty | 歌词后半段是否雷同 | 分段重生成 |
| 显存溢出 | stage2_batch_size | 精度是否为 bf16 | 换机器或云端 |
5. 把 YuE 用进真实工作流：音色锁定、分轨与二次开发
5.1 用音频提示锁定音色
常规生成模式下，每次跑出来的音色都是随机的，这给系列化创作带来很大麻烦——你想要一套统一的"专辑音色"，结果每首都不一样。带icl后缀的第一阶段模型支持参参考音频作为提示，玩法是喂一段几十秒的干声或成品片段，让模型参考它的音色和演唱风格继续生成。
实操上有几个细节值得注意。参考音频要干净，带混响和伴奏的片段会把伴奏的音色也带进人声里；长度别太短，几秒钟的片段不足以稳定音色；采样率要符合模型预期，不匹配的音频要先重采样，否则会听到奇怪的金属尾音。这一招用来做同一角色的多首歌曲时特别好用，音色一致性比反复调风格词靠谱得多。
5.2 拿分轨进 DAW 做后期
因为模型是双轨生成的，你可以把人声和伴奏分别导出，扔进任何一款 DAW 里做后期。这一步几乎是必须的，原因前面说过——第二阶段的重建质量有上限，但后期的空间很大。
我的常规处理链路是：人声轨先做去齿音和轻度动态压缩，把咬字的毛刺磨掉；然后做轻微的饱和处理，让声音不那么"数字感"；伴奏轨上做宽化和低频收紧，这一步能让整体听起来专业不少。最后加一点点空间效果把人声和伴奏粘在一起，不要两边各加一套混响，那样会散。
5.3 微调与风格标签扩展的可行路径
想让它唱出你自己的风格，微调是最直接的路径。LoRA 是个务实的起点：冻结主干，只训练低秩适配层，24GB 显存能勉强吃下小规模的数据。数据准备有两个坑——一是歌词和音频必须对齐，歌词文本要和音频里实际唱的内容一致，错一个字都会污染对齐；二是数据量不用大但质量要高，几百首干净、风格统一的样本，效果往往好过几千首杂七杂八的。
另一条更轻的路线是扩展风格标签。如果你只是想让模型多认识一种配器或一种唱法，在提示词层面反复强化，配合少量样本做继续训练，比全量微调省事得多。
注意：涉及人声音色的使用，务必确认你拿到的素材有正当来源，别拿真人歌手的声音去模仿复制，这条线不要碰。
6. 它现在的边界，以及和闭源方案对比后我的取舍
拿 YuE 和商业闭源的音乐生成服务放在一起比，结论其实很清晰。闭源方案在成品完成度上领先明显：编曲层次更丰富、混音更干净、副歌的爆点更精准，普通用户点几下就能出一首能直接发的内容。YuE 的优势在另外三个地方：完全本地运行（素材不出本机，适合有保密要求的项目）、可微调可控（能训练自己的风格，商业服务给不了）、分轨输出（后期空间大，能接进现有工作流）。它的短板也很实在——生成慢、音质上限受架构限制、中文咬字的稳定性还在打磨中，而且不同版本的参数命名和行为还在变，昨天能跑通的命令今天可能要改个参数名。
我自己的用法是把它当素材生成器而不是成品机器。用它批量生旋律走向和人声小样，挑出好的那几条，再用 DAW 重新做编曲和混音，最后得到的东西比纯 AI 成品耐听得多。如果只是想快速发一条短视频配乐，我不会用本地跑这一套；但如果是要做一张风格统一、有版权可控性的原创专辑，本地这套目前是少数几个能选的方案之一。跑之前先想清楚你要的是"快"还是"可控"，这两个目标在现阶段的开源模型上还很难同时满足。
