开源音乐工具YuE：实时人声伴奏分离与和弦识别的工程实践

去年冬天我一直在折腾一个叫YuE的小项目——名字取自“乐”的拼音也是“Your Engine”的缩写意思是“你的创作引擎”。它是一个开源的音乐创作辅助工具核心功能围绕三件事展开自动伴奏生成、人声与伴奏分离、实时和弦识别。简单说就是给独立音乐人、视频创作者和音频开发者提供一个本地可跑、能流式处理、不依赖在线服务的音频处理底座。当时立项的动机很直接我在做视频配乐时发现找一首歌的纯伴奏要么得靠运气要么得用付费工具临时想给一个旋律配个和弦走向要么翻乐理书要么靠耳朵硬试。于是就想自己动手写一个工具把这几件高频的音频苦力活一次性解决掉。这篇博文就当作项目总结把 YuE 的整体设计、技术拆解、踩坑过程和复现方式都记录下来尤其是那些参数调优和问题排查的细节希望能让想动手做类似工具的朋友少走点弯路。1. YuE 整体设计与思路拆解1.1 为什么动手做 YuE痛点驱动的立项做这个项目之前我先后试用过不少现成的伴奏提取、和弦识别工具。一类是商业闭源产品效果好但价格不低免费版还有音质限制和使用时长限制另一类是开源库比如用 librosa 和音源分离模型做的脚本功能上是能用但基本都是离线离线处理跑完一首歌得等半天而且参数写死了想集成到自己的实时处理链路上还得做大量二次开发。YuE 的定位和它们不一样。它从一开始就强调三件事第一本地优先所有推理都在自己的机器上跑不把音频发到云端第二流式处理可以接麦克风或播放器输出连续不断地把人声分离出来或者实时显示和弦而不是等到整首歌结束再给出结果第三模块化伴奏生成、分离、识别这三大能力是互相独立的模块可以单独跑也能拼在一起当一条音频流水线用。整个项目的技术路线也因此水到渠成。Python 是音频处理和 AI 推理生态最成熟的选项模型训练和部署都用 PyTorch服务层用 FastAPI 加 WebSocket 提供实时接口前端或命令行工具可以随时接入。这套选型可能不是最高性能的组合但胜在开发效率高、替换成本低、社区资料足对一个偏研究和工具型的小项目来说这个取舍很划算。1.2 关键方案选型与放弃的技术路线许多人做音频分离会第一时间想到开源的 Demucs 或 Spleeter说实话它们的分离效果确实好。我也先试过直接封装 Demucs但很快就发现一个不适合 YuE 的地方Demucs 的模型太重了就算是最小版本在 CPU 上推理一首三分钟的歌也要等很久实时流式处理基本不用想。YuE 最后没有走“大模型套壳”的路线而是选择自研一个轻量级 U-Net 结构的分离网络配上多分辨率 STFT 损失函数做训练。它对硬件的需求比 Demucs 低得多效果虽然达不到 SOTA但足够用于视频伴奏提取、人声消除练习这类任务换来的是 CPU 上也能实时处理的能力。和弦识别部分也是反复改过技术方案的。最开始我用的是 librosa 的 chroma 特征加上模板匹配速度倒是很快但一到有复杂伴奏的音乐里准确率就崩尤其低音区和打击乐的干扰很难用规则过滤掉。后来我改成 CQT常 Q 变换特征作为输入再叠加一个简单的前馈网络输出十二个半音的存在概率最后通过时间平滑和和弦词典匹配得到结果准确率明显上了一个台阶推理延迟也维持在几十毫秒级别。1.3 系统架构与模块划分YuE 的代码大概分成 5 个模块相互之间通过标准接口通信不搞隐藏依赖采集层负责从麦克风、音频文件或系统播放流中读取 PCM 数据统一采样率到 22050Hz这是人声频带分析和计算量的一个平衡点。预处理层把波形数据切成固定长度的帧做 STFT 或 CQT 变换并做归一化和缓存管理。推理层加载训练好的模型接收特征输入输出分离掩码或和弦概率。输出层把模型输出的掩码转回波形加入重叠相加和交叉淡化避免拼接处出现爆音或者把和弦概率变成可读的和弦名。服务层提供 WebSocket 接口让客户端可以持续推流、持续拉取结果。这种分层的思路是参考声音处理领域的常见做法单拎出哪一层都可以单独替换测试。比如你不想用自研分离模型可以直接把推理层的入口接到 Demucs 上其他代码不用动。2. 核心细节解析与实操要点2.1 音频预处理采样率、分帧和加窗的选择音频预处理的参数直接决定后面模型看到的“图像”质量。YuE 固定采样率为 22050Hz理由有二人声和绝大多数乐器的基频加上泛音都在 10kHz 以内22050Hz 的奈奎斯特频率已经够用相比 44100Hz计算量和内存占用直接少一半对实时任务非常友好。分帧用的是 n_fft2048hop_length512。2048 个采样点算一次 FFT频率分辨率是 22050/2048 约等于 10.8Hz能区分开相邻半音时间分辨率是 512/22050 约 23ms对大多数音符起始点也都能捕捉到。这个参数组合不会太极端既不会让频谱糊成一团也不至于因为时间窗太短导致频率分辨率不够。加窗我用的 Hanning 窗。没有用 Hamming 或 Blackman是因为 Hanning 在旁瓣抑制和主瓣宽度之间比较均衡对 U-Net 这种需要从频谱中恢复细节的结构来说主瓣太窄反而容易丢失邻近频段的上下文。每次处理一个窗口YuE 额外缓存了前一帧的最后 256 个采样点作为上下文保证帧与帧之间的连续性。2.2 分离模型结构U-Net 与频带注意力YuE 的分离模型主体是 U-Net 的编码器-解码器结构输入是经过对数压缩的 STFT 幅度谱输出是一个软掩码取值范围 0 到 1用这个掩码乘上原始频谱就把目标声音剥离出来了。模型每层编码器由两个卷积块组成卷积核大小是 3x3步长 2 做下采样通道数按 16、32、64、128、256 逐层增加。与标准 U-Net 不同的是我在每个编码器块后加了一个 SESqueeze-and-Excitation模块它能让模型在不同频段上学出注意力权重。比如人声分离时模型会自动把注意力集中到 200Hz 到 4kHz 的人声主要频段把低频贝斯和打击乐的高频瞬态抑制掉。解码器部分用转置卷积逐步恢复分辨率跳跃连接把编码器对应层的特征拼接进来弥补下采样丢失的细节。最后一层是 1x1 卷积加 sigmoid确保输出是在 0 到 1 之间的掩码。整个模型参数量约 240 万权重文件大小不到 10MB在 CPU 上处理 1 秒音频的推理耗时约 0.3 到 0.5 秒完全满足实时流式任务。2.3 和弦识别CQT 特征加概率输出人声分离解决的是客观问题和弦识别就带点主观色彩了。YuE 的和弦识别模块输入用的是 CQT 特征而不是普通 STFT原因是 CQT 在频率轴上是对数分布的更符合人类听感中音高的排列规律。一个八度内的频点数量固定这样模型更容易学到十二平均律的特征模式。特征提取后YuE 用一个小型的全连接网络输出 12 个值分别代表这 1 秒内 C、C#、D 等十二个半音的出现概率。这个概率不是和弦名而是“当前音频里哪些音更活跃”的一个分布。后处理阶段我会对概率做时间中值滤波过滤掉因为打击乐造成的瞬时跳变再用一个定义好的和弦词典去匹配最接近的三和弦或七和弦。匹配的逻辑听起来简单实际写的时候踩了一些坑。直接拿概率最高的三个音组成和弦不现实因为转位和弦和省略和弦会让识别结果非常不稳定。后来处理方式是先把概率低于 0.3 的音符置零然后枚举所有大三、小三、属七、小七和弦计算目标概率分布与每个和弦的余弦相似度取最高者作为输出。这套方案对流行歌曲的主歌副歌段落命中率还不错但遇到爵士里大量色彩和弦还是有明显的局限。2.4 关键参数速查表模块参数项取值选择理由通用采样率22050Hz人声频带内足够计算量减半分离n_fft2048频率分辨率约 10.8Hz兼顾半音音程细节分离hop_length512时间分辨率约 23ms适合人声起始点捕捉分离窗口函数Hanning旁瓣抑制与主瓣宽度均衡分离编码器通道16/32/64/128/256深度适中CPU 推理开销可控和弦识别CQT 每八度频点数24比 12 更能捕捉音高间的微差提高鲁棒性实时流重叠率50%防止分块处理时边缘伪影过重实时流输出拼接方式交叉淡化消除块边界爆音3. 实操过程与核心环节实现3.1 环境搭建与依赖安装YuE 的运行环境不复杂Python 3.10 版本就可以。建议用虚拟环境安装避免把系统 Python 环境搞得乱七八糟。以下是必要的依赖清单torch模型推理建议 2.1 以上版本torchaudio音频格式加载和部分特征变换librosaCQT 特征提取和部分音频处理工具函数numpy数组计算soundfile音频文件读写fastapi uvicornWebSocket 服务层websockets客户端测试用安装命令可以一次性搞定。直接创建新的虚拟环境然后执行pip install torch torchaudio librosa numpy soundfile fastapi uvicorn websockets。如果你的机器有 NVIDIA 显卡建议另装对应 CUDA 版本的 PyTorch实时分离推理速度能快 5 到 10 倍没有显卡也不影响CPU 模式下的推理链路完全可用。3.2 预处理和推理代码实现先看预处理的实现。这里最核心的函数是音频加载和特征转换。我习惯把 22050Hz 重采样、STFT 计算和对数压缩统一封装成一个类方便后续复用。import torch import torchaudio import numpy as np class AudioPreprocessor: def __init__(self, sample_rate22050, n_fft2048, hop_length512): self.sample_rate sample_rate self.n_fft n_fft self.hop_length hop_length self.window torch.hann_window(n_fft) def load_audio(self, path): waveform, sr torchaudio.load(path) if sr ! self.sample_rate: resampler torchaudio.transforms.Resample(sr, self.sample_rate) waveform resampler(waveform) if waveform.shape[0] 1: waveform torch.mean(waveform, dim0, keepdimTrue) return waveform def stft_to_feature(self, waveform): stft torch.stft( waveform, n_fftself.n_fft, hop_lengthself.hop_length, windowself.window, return_complexTrue ) magnitude torch.abs(stft) log_magnitude torch.log1p(magnitude) return log_magnitude这段代码里有两个容易被忽视的细节。第一多声道音频要降成单声道不然后面掩码计算和重组波形都会因为声道数不统一而出错。第二用log1p而不是直接log是为了避免对数变换后出现大量负无穷或极小的数值让模型输入的数值范围稳定保持在 0 到 1 附近训练和推理时收敛都会更顺利。再来看推理主循环的实现。这里模拟的是实时流式处理场景每次从输入流中拿到一小段数据经过预处理、模型预测、掩码应用最终输出分离后的人声或伴奏波形。def process_stream(model, preprocessor, audio_chunk): with torch.no_grad(): feature preprocessor.stft_to_feature(audio_chunk) feature feature.unsqueeze(0) mask model(feature) mask mask.squeeze(0) stft torch.stft( audio_chunk, n_fftpreprocessor.n_fft, hop_lengthpreprocessor.hop_length, windowpreprocessor.window, return_complexTrue ) separated_stft stft * mask * 2.0 separated_wave torch.istft( separated_stft, n_fftpreprocessor.n_fft, hop_lengthpreprocessor.hop_length, windowpreprocessor.window ) return separated_wave掩码乘完后乘以 2.0 这一步非常关键因为训练时使用的窗口是 Hanning 窗istft恢复波形时会有约 2 倍的幅度折损不乘回来音量会明显变小。这是从实验结果里直接得出来的经验值不同窗口函数需要做对应的补偿调整。3.3 完整运行流程与效果评估以“提取一段 30 秒的人声干声”为例完整的运行流程是这样调用load_audio读取音频文件把采样率统一到 22050Hz。调用stft_to_feature得到对数幅度谱。把特征输入分离模型得到人声掩码。将掩码应用到原始 STFT 上再做istft还原波形。写成 wav 文件。我拿一段带钢琴和架子鼓伴奏的人声测试过分离出来的人声清晰度很好副歌部分的高频共鸣没被吃掉缺点是当架子鼓的镲片和人声同时发声时镲片的残响会有一小部分泄漏到人声轨里。伴奏部分整体干净低频贝斯保留得比较完美做消音练习时即使戴耳机听也不会觉得难受。和弦识别的实测效果我用了一首 C 大调的流行歌主歌段落的 C、G、Am、F 四个和弦全部识别正确副歌里出现了一个 Dm7模型输出成了 F 大三和弦因为 Dm7 和 F 的组成音有大量重叠在单靠听感匹配时确实容易搞混。这种错误属于主观听感层面的模糊地带后续可以考虑引入和弦进行上下文来修正。4. 常见问题与排查技巧实录4.1 你大概率会遇到的几个坑这里把 YuE 开发过程中最典型的几个问题整理成一个速查表方便对照排查。每一条背后都有我实打实踩过的坑不是凭空总结的。问题表现根本原因解决方案CPU 推理延迟高实时处理变卡顿模型参数量过大或 batch 设置不当先把模型输入块减小例如每次只处理 30 帧关闭梯度计算使用 torch.no_grad考虑量化到 int8分离后人声有金属感或“罐子声”掩码在频域预测不够准确高频细节丢失损失函数改用多分辨率 STFT loss叠加 L1 loss训练时加入轻微噪声增强鲁棒性和弦识别结果跳变一秒钟换好几个和弦后处理缺乏时间平滑对 12 维半音概率做中值滤波窗口大小取 5 到 7 帧增加最小持续时间限制输出音频有周期性咔哒声分块处理的边界没有做交叉淡化相邻块重叠 50%在重叠区域做线性交叉淡化再输出模型在 CPU 与 GPU 推理结果不一致BatchNorm 层在两种模式下统计方式不同推理时固定 BatchNorm 为 eval 模式如果仍不一致把 BatchNorm 替换成 InstanceNorm内存占用持续上涨WebSocket 消息队列没有限流或积压服务端加队列长度限制超出时丢弃旧数据客户端降低发送频率4.2 排障经验从现象定位到底层原因举一个最典型的例子。第一次跑通完整链路时我发现分离出来的伴奏整体音量很轻不对比原始音频根本听不出来。最开始我以为是模型输出的问题反复调整掩码阈值也没用。排查到最后才发现问题出在istft的幅度还原上。因为训练时网络学到的是对数压缩频谱上的掩码而在推理时我是直接把这个掩码乘到原始线性幅度谱上两者之间的数值尺度根本不匹配。解决思路也很简单推理时先对原始频谱做和训练一致的对数压缩在压缩域里计算掩码乘法然后用指数变换恢复成线性幅度谱。调整完以后输出音量明显恢复到正常水平。类型的问题在音频 AI 项目里特别容易遇到训练和推理链路中任何一个环节哪怕只差一步预处理最终听感就是天壤之别。另一个让人印象深刻的坑出现在 BatchNorm 上。模型在 GPU 上训练离线评测时的分离效果很正常但一上 WebSocket 做流式推理输出的音色就开始飘。原因是流式处理时一个 batch 可能只有一条样本而 BatchNorm 在训练和推理时的行为差异会导致频谱统计特征不稳定。我最后把所有 BatchNorm2d 都换成了 InstanceNorm2d再跑流式推理音色就稳定下来了。4.3 模型训练阶段的避坑心得YuE 的分离模型训练数据集用的是合成混合音频人声轨来自开源语音数据集伴奏来自 MIDI 合成的钢琴、吉他和鼓点音源按照 0 到 6dB 的随机信噪比混合。一开始损失函数用的是 MSE训练到后期发现模型输出的频谱非常“糊”高频细节缺乏锐度。换用 L1 损失后稍微好了一些但人声的瞬态仍然不清晰。最终稳妥的方案是多分辨率 STFT 损失即同时计算 3 种不同参数不同 n_fft 和 hop_length的 STFT 幅值差之和。这个损失函数鼓励模型同时保留时间分辨率和频率分辨率的细节主观听感比单纯 MSE 好了一整个档次。训练中还发现一个规律输入模型的频谱要做随机时间掩码和频率掩码类似 SpecAugment 的做法能让模型对部分缺失的频段或时间段做到更稳定的预测。这一点对实时流式处理尤其重要因为实时流中的数据天然是不完整、有噪声的用这种增强方式训练出来的模型在真实场景里的鲁棒性好很多。5. 后续扩展方向与个人经验沉淀YuE 目前能跑通的主干功能包括伴奏分离和和弦识别自动伴奏生成模块也完成了初版原型但质量还谈不上稳定后续还有很大的调整空间。我个人比较看好的方向是把和弦识别与生成模块串起来识别出和弦走向之后直接调取对应的和弦琶音音色库拼成一段伴奏这样可以从“识别”走向“辅助创作”。最后再分享一个实际开发中沉淀下来的小技巧音频模型的评估不能只看指标比如 SDR 和 SIR 这些数值提升并不代表听感提升。YuE 每次训练完模型我都会额外跑一次 A/B 听感测试用同一段音频分别通过两个版本的模型处理盲听打分。很多时候客观指标涨了几个分贝听感上却变差了而这些问题是任何指标都发现不了的。另外音频项目的日志和中间结果管理务必做得细一点。每次训练时的预处理参数、损失权重、数据集版本都记录下来不然三个月后回来看模型输出你根本不知道当初是怎么训出来的调参效率会特别低。YuE 现在的每个导出模型都会附带一个 JSON 配置说明文件记录训练数据、预处理参数和模型结构版本这个习惯帮我省了大量的复查时间。做这类音乐工具最大的感受是“音频处理没有银弹”。每个任务都要在计算量、实时性和效果之间反复权衡。YuE 的定位不是替代商业级工具而是给大家一个能自由定制、能跑在本地、能集成到工作流里的轻量底座。希望这篇拆解能把项目里的核心思路和一些能直接用的参数方案带给你让你在构建自己的音频处理链路时少试几次错。