NoizAI/YuE2-Turbo
NoizAI/YuE2-Turbo has 137 GitHub stars and 25 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-18 07:49 UTC. Last push 2026-09-22.
实测星标增长
- 24小时
- 0
- 7天
- 正在收集历史
- 15天
- 正在收集历史
- 1个月
- 正在收集历史
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Fast, concurrent inference for YuE2. Same model and recipe: 1.68× faster per song, 3.31× more songs per GPU.
机器学习README_zh.md
原文
English | 中文
YuE2-Turbo: YuE2 高性能并发推理服务
同样的 YuE2 模型。单曲生成提速 1.68×,单卡吞吐提升 3.31×。
🧰 环境要求 · 🚀 部署服务 · ⚙️ 配置说明 · 🎵 关于 YuE2 · 🤗 权重下载
YuE2-Turbo 是面向 YuE2 的推理加速与生产服务化方案。 在保持官方发布的 YuE2-3B 权重与标准生成规格(BF16、32 步 flow-matching 采样)完全一致的前提下,重构了底层执行架构:自回归(AR)阶段采用 vLLM 加速,全流程权重 常驻 GPU 显存,非自回归声学阶段(NAR)支持 跨请求批处理,并提供开箱即用的 HTTP 异步任务 API + 网页版 Studio Web UI,单张 GPU 即可高效承载多用户并发生成。
| 场景 | 原版 YuE2 | YuE2-Turbo | 加速比 |
|---|---|---|---|
| 单请求 (RTF,越低越好) | 0.290 | 0.173 | 1.68× |
| 4 并发请求 (系统 RTF) | 0.317 | 0.096 | 3.31× |
测试环境:单卡 NVIDIA RTX 5090 (32 GB),PyTorch 2.10.0 + CUDA 12.8,vLLM 0.19.0,BF16,32 步 ODE,充分预热后测得。RTF = 生成每秒音频所需的计算时间(秒):RTF 0.17 意味着生成一段 60 秒歌曲仅需约 10 秒。单请求指标基于 3 首歌曲 × 3 次重复取平均;并发指标基于每波 4 个请求 × 3 波测得,系统 RTF = 单波耗时 ÷ 生成的总音频时长。可使用 yue2-benchmark 完整复现。
加速路径在 WildSongBench 标准协议上没有掉点。192 题各生成 2 首,取得分更低的 PER 候选,对照公布的 YuE2 标准分数:
| 指标 | 原版 YuE2 | YuE2-Turbo |
|---|---|---|
| SongBench Avg ↑ | 6.7316 | 6.7623 |
| MuLan ↑ | 0.5068 | 0.5069 |
| AllMusicCaps ↑ | 0.4054 | 0.4087 |
| PER ↓ | 8.44% | 8.18% |
单卡 RTX 5090,vLLM 4 路并发,BF16、32 步 ODE,与官方同一套权重和生成规格。
环境要求
| 依赖项 | 测试验证 / 推荐配置 |
|---|---|
| 操作系统 | Linux x86_64 |
| GPU | 支持 BF16 的 NVIDIA 显卡。默认参数针对 32 GB RTX 5090 优化;在 24 GB 显卡上建议调小 YUE2_AR_CONCURRENCY / YUE2_VLLM_MAX_NUM_SEQS 或设置 YUE2_RESIDENT_MODELS=false |
| 驱动 | 支持 CUDA 12.8 |
| Python | 3.11 或 3.12 |
| PyTorch | 2.10.0 (cu128 wheels) |
| vLLM / Triton | 0.19.0 / 3.6.0(包含在 server 依赖中) |
| 磁盘空间 | YuE2-3B + YuE2-Vae 约需 8 GB,另需数 GB 存放 vLLM 转换后的 AR 权重缓存 |
默认配置下服务静默显存占用约 18 GB(PyTorch MoT + VAE 约 8 GB,vLLM 引擎约 10 GB);在 32 GB 显卡上应对 4 路并发时,峰值显存保持在 25 GB 以内。
部署加速服务
1. 安装
git clone <this repository> YuE2-Turbo
cd YuE2-Turbo
uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cu128
uv pip install '.[server]'
server 依赖包含了 FastAPI、Uvicorn、vLLM 与 Triton。初次启动会自动从 Hugging Face 下载权重;如需离线运行,可设置 YUE2_MODEL / YUE2_VAE 指向本地目录并指定 YUE2_LOCAL_FILES_ONLY=true。
2. 配置环境变量
export YUE2_API_KEY="$(openssl rand -hex 32)" # 必填,API 密钥(不少于 16 字符)
export YUE2_DATA_DIR="$PWD/outputs/service" # SQLite 任务库与音频/乐谱产物存储目录
export CUDA_VISIBLE_DEVICES=0 # 每个服务进程独占一张卡;使用卡号索引,勿用 UUID
默认设置已经全量开启加速特性(YUE2_BACKEND=vllm、YUE2_RESIDENT_MODELS=true、YUE2_AR_CONCURRENCY=4、YUE2_NAR_BATCH_SIZE=2、YUE2_AR_NAR_OVERLAP=true)。如需微调,请参考 配置说明。
3. 启动 API 服务
yue2-serve # 默认监听 127.0.0.1:8000(可通过 YUE2_HOST / YUE2_PORT 修改)
服务启动时会依次加载 vLLM 引擎、PyTorch MoT 与 VAE,并自动执行一段预热生成,确保后续真实请求直接达到最优速度。检查就绪状态:
curl -i http://127.0.0.1:8000/health/ready # 加载阶段返回 503,就绪后返回 200
可访问 http://127.0.0.1:8000/docs 查看交互式 OpenAPI 接口文档(点击 Authorize 输入配置的 API Key 即可调试)。
4. Web UI 启动!
YUE2_UPSTREAM=http://127.0.0.1:8000 yue2-web # 默认监听 http://0.0.0.0:8016
Studio 提供了可视化的单页音乐创作工作台:支持歌词与风格输入、作曲模式切换、ABC 乐谱预览、可选的原曲上传翻唱、实时生成进度反馈、音频播放与结果下载。浏览器在请求时携带用户填入的 Bearer Token,网关本身不硬编码或持久化密钥。若在非受信网络暴露,建议在前端配置 HTTPS。
5. 调用 API
curl -X POST http://127.0.0.1:8000/v1/jobs \
-H "Authorization: Bearer $YUE2_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-0001' \
-d '{"style":"Mandarin, piano pop, warm vocal","lyrics":"[Verse]\n晨光落在窗边\n[Chorus]\n让歌声陪伴你","cot":"full","seed":42}'
接口返回 202 Accepted 以及任务 id,轮询任务并下载产物:
JOB=<id>
curl -H "Authorization: Bearer $YUE2_API_KEY" http://127.0.0.1:8000/v1/jobs/$JOB
curl -H "Authorization: Bearer $YUE2_API_KEY" http://127.0.0.1:8000/v1/jobs/$JOB/audio -o song.flac
curl -H "Authorization: Bearer $YUE2_API_KEY" http://127.0.0.1:8000/v1/jobs/$JOB/score -o score.abc
curl -X POST -H "Authorization: Bearer $YUE2_API_KEY" http://127.0.0.1:8000/v1/jobs/$JOB/cancel
| 接口 | 用途 |
|---|---|
GET /health/live, GET /health/ready |
存活探针 / 就绪探针(无需鉴权) |
POST /v1/jobs |
提交生成任务(支持 n=2 同时生成多个随机 seed);相同 Idempotency-Key + 相同请求体自动幂等返回原任务 |
GET /v1/jobs/{id} |
查询任务详情:状态(queued → running → succeeded / truncated / failed / cancelled)、阶段、Token 统计、各阶段耗时 |
POST /v1/jobs/{id}/cancel |
取消任务(在下一个 Token / ODE 步 / VAE 分块边界处快速退出) |
GET /v1/jobs/{id}/audio, /score |
下载 FLAC 音频或 ABC 乐谱 |
POST /v1/covers |
翻唱:把上传的歌曲转成旋律后再生成(YUE2_SHEETSAGE_DEVICE 不能为 off) |
队列已满时返回 429(附带 Retry-After 头);服务未就绪时返回 503。生成产物默认按每个数据目录保留 24 小时或最多 5 GiB。若请求需要 CFG(cfg_scale ≠ 1)或关闭思维链(cot="off"),服务会自动平滑回退至原版 PyTorch 分支执行,无需人工干预。
翻唱
翻唱默认开启。YUE2_SHEETSAGE_DEVICE 默认是 auto。SheetSage2 只在第一次翻唱时加载,普通生成不会占用它的显存。它把上传的歌曲转成不含和弦的旋律 ABC,YuE2 再用 cot=melody 按给定风格和歌词生成。它不克隆原唱音色。
auto 会在 YuE2 已经常驻之后看剩余显存:至少还有 YUE2_SHEETSAGE_MIN_FREE_GIB(默认 8 GiB)才把转谱放在 GPU 上并以 BF16 运行,否则留在 CPU 上用 FP32。24 GB 卡在生成服务常驻后通常走 CPU。CPU 转一首完整歌曲可能要数分钟,这段时间同样计入 YUE2_TASK_TIMEOUT_SECONDS。系统 PATH 里需要有 ffmpeg。server 附加依赖已经包含 SheetSage2 导入所需的 Python 包(mir_eval、pretty_midi、mido、scipy)。显式设为 off 可关闭翻唱。
curl -X POST http://127.0.0.1:8000/v1/covers \
-H "Authorization: Bearer $YUE2_API_KEY" \
-F "[email protected]" \
-F "style=Mandarin, piano pop, warm vocal" \
-F "lyrics=[Verse]
晨光落在窗边
[Chorus]
让歌声陪伴你" \
-F "seed=42"
之后仍用原来的任务接口下载 FLAC 和旋律谱。Studio 里的入口是「上传歌曲翻唱」。网关只对 POST /v1/covers 放宽到 40 MB,其它请求仍是 256 KB。YUE2_SHEETSAGE_DEVICE=off 时该接口返回 503,并且不会保存音频。
命令行会先转谱,再释放 SheetSage2 的权重,然后才加载 YuE2,避免两个模型同时留在显卡上:
yue2 cover --audio song.mp3 --request cover-request.json --sheetsage-device auto --output outputs/cover
配置说明
所有配置均通过 YUE2_ 前缀的环境变量读取:
| 环境变量 | 默认值 | 说明 |
|---|---|---|
YUE2_BACKEND |
vllm |
推理后端:vllm(加速路径)、torch(原版 CUDA Graph 路径)、torch-eager |
YUE2_RESIDENT_MODELS |
true |
MoT 与 VAE 模型常驻显存,避免任务间反复卸载加载 |
YUE2_AR_CONCURRENCY |
4 |
同时提交给 vLLM 并行调度的请求数(需 ≤ YUE2_VLLM_MAX_NUM_SEQS) |
YUE2_VLLM_MAX_NUM_SEQS |
4 |
vLLM 调度器最大并发序列数 |
YUE2_VLLM_MAX_NUM_BATCHED_TOKENS |
8192 |
vLLM 单次调度最大 Token 数(chunked prefill) |
YUE2_VLLM_GPU_MEMORY_UTILIZATION |
0.30 |
预留给 vLLM 引擎(权重 + KV Cache)的显存比例 |
YUE2_NAR_BATCH_SIZE |
2 |
NAR 声学合成批处理请求数(最大为 2) |
YUE2_AR_NAR_OVERLAP |
true |
重叠调度:当上一批请求在执行 NAR/VAE 时,提前调度下一批 AR 生成 |
YUE2_AR_BATCH_WAIT_MS |
50 |
批量接收并发请求的微等待窗口(毫秒) |
YUE2_MEMORY_BUDGET_GIB |
30 |
PyTorch 显存分配配额预算 |
YUE2_ODE_STEPS |
32 |
Flow-matching 采样步数;减小可进一步提升 NAR 速度,但对音质略有折损 |
YUE2_MAX_PENDING |
16 |
任务排队最大深度,超出返回 429 |
YUE2_TASK_TIMEOUT_SECONDS |
1200 |
单任务执行超时时间(秒,不计排队时间) |
YUE2_ARTIFACT_RETENTION_SECONDS / YUE2_ARTIFACT_MAX_GIB |
86400 / 5 |
产物自动清理策略(保留时长 / 空间上限) |
YUE2_WARMUP |
true |
服务启动时自动运行预热任务 |
YUE2_MODEL / YUE2_VAE / YUE2_LOCAL_FILES_ONLY |
HF 仓库 ID / false |
模型来源与离线加载模式 |
YUE2_SHEETSAGE_DEVICE |
auto |
翻唱转谱:auto(空闲显存够则 GPU,否则 CPU)、cpu、cuda,或 off(关闭) |
YUE2_SHEETSAGE_MIN_FREE_GIB |
8 |
auto 把 SheetSage2 放到 GPU 前要求的空闲显存(GiB) |
YUE2_SHEETSAGE / YUE2_SHEETSAGE_REVISION |
m-a-p/SheetSage2 / 未设置 |
启用翻唱时加载的 SheetSage2 快照 |
设置 YUE2_BACKEND=torch YUE2_RESIDENT_MODELS=false YUE2_AR_CONCURRENCY=1 YUE2_NAR_BATCH_SIZE=1 YUE2_AR_NAR_OVERLAP=false 可在相同 API 接口下完全还原原版执行行为(即上表中“原版 YuE2”基准)。
多卡部署
建议每张物理 GPU 单独启动一个 yue2-serve 进程,分别配置不同的 CUDA_VISIBLE_DEVICES、YUE2_PORT 与 YUE2_DATA_DIR,并在前端使用 Nginx 或网关做负载均衡。请勿使用多个 Uvicorn worker 或多进程同时操作同一个数据目录(服务会对数据目录加进程锁)。
复现性能评测
export CUDA_VISIBLE_DEVICES=0 # 指定一张无其他负载的测试 GPU
yue2-benchmark --check
yue2-benchmark --requests examples/benchmark-requests.jsonl \
--profiles reference vllm --warmup 1 --repeats 3 \
--output outputs/benchmark-rtx5090
reference 代表原版路径,vllm 代表加速路径。测试完成后生成的 report.json 会详细记录每次运行的各阶段耗时、RTF、Token 吞吐率、峰值显存与模型哈希。并发测试可通过向运行中的 yue2-serve 提交相同请求批次(并发度 1、2、4),并统计整波任务墙钟耗时与生成总音频时长的比值测得。
关于 YuE2
YuE2-Turbo 基于 M-A-P 社区发布的 YuE2 构建。模型权重、演示试听、评估评测、翻唱/编辑模式与 Agent Skill 等详细介绍,请参阅原仓库:
github.com/multimodal-art-projection/YuE · 🤗 YuE2-3B · 🤗 YuE2-Vae · Demo 页面
开源许可
本项目代码遵循 Apache 2.0 协议开源。YuE2 模型权重独立遵循 CC BY-NC 4.0 非商业许可协议;第三方组件保留其原始开源许可。
致谢
感谢 Linux.Do