🎵 音乐工作台 YuE2

• 模型下载默认走 https://hf-mirror.com（大陆直连，无需科学上网）
• 镜像不可用时自动回退 huggingface.co
• 想手动指定镜像：设置环境变量 HF_ENDPOINT=https://hf-mirror.com
• 想手动下载 / 换量化版本（q8 更高质量约 4GB）：

py312\python.exe scripts\download_models.py          :: q4_k_m（默认，约2.7GB）
py312\python.exe scripts\download_models.py --q8     :: q8_0（约4GB，质量更佳）

所有服务端口集中在仓库根的 ports.json，改完重启生效：

{
  "gateway": 7863,    // FastAPI 网关
  "dsh": 3081,        // 工作台 UI
  "audiocpp": 8080    // 推理引擎
}

也可用环境变量临时覆盖（优先级更高，便于排障/并行实例）： YUE2_GATEWAY_PORT / YUE2_DSH_PORT / YUE2_AUDIOCPP_PORT

文件缺失或写坏时自动回退默认端口——配置问题绝不会导致服务起不来。

能。显存不足或无独显时自动切换 CPU 后端，生成完成后自动切回。16GB 内存 + 现代多核 CPU 即可出歌，只是等待时间更长。诚实的限制：CPU 慢多少没有本机基准数据，社区经验值约 5-10 倍，请以你自己的实测为准（同一歌词多次生成波动可达 ±40%，单点数字本来就不可信，页面因此显示区间而非精确 ETA）。

full 模式（可编辑旋律 + 和声）+ 32 步 + 长歌词，6GB+ 显存约 60-90 分钟；melody / off 模式更快。支持批量排队挂机。

不会。除首次模型下载走镜像站外，写词、生成、换声、训练、歌词对齐全部在本机完成，无任何遥测。

老方案用语音识别（ASR）反推时间轴，但歌声上 ASR 漏识率高达 20-30%（实测错得离谱），误差逐级累积。新方案走强制对齐路线：歌词文本是已知的，直接把已知歌词"压"到音频上——中文走 FunASR 字级时间戳，英文走 wav2vec2 CTC 对齐，最后用 VAD 人声起音点做锚点吸附消除集体漂移。字/词级误差在百毫秒量级，同时产出行级 .lrc 与逐字 .elrc（卡拉OK逐字高亮）。诚实的边界：逐字高亮由支持 eLRC 的外部播放器渲染，工作台自己的页面只放音频 + 提供两种下载，不在页面内做逐字滚动。

乐谱框里有谱 = 按谱生成，这已经不需要你手动配合「规划 CoT」下拉框了：工作台会在提交前双向核对口径——只有旋律声部的谱走 melody（伴奏自由），带和弦记号的谱走 full（旋律+和声都按谱），档位选反了会被纠正（引擎不会替你改写谱面：melody 不会自动删掉谱里的 "C"、"Am7"，full 也不会替你补和声），选了 off 同样会被纠正回按谱路线（off 带谱会被引擎直接判 400）。之所以要分这两条：外部 ABC 是绕过符号规划器当条件喂进去的，但 melody/full 是两套不同的原生指令，路线和谱的形态不符就属于口径不符，谱面条件就会走偏——听起来像"没按我的谱唱"。乐谱框下面会实时显示这份谱有没有和弦、将走哪条路线；提交后 toast 提示本次实际路线，历史存档里记的也是实际路线。

「🎸 从参考歌曲提取乐谱」默认给纯旋律谱（配 melody，翻唱最常用）；勾选旁边的「提取时带和弦」就得到旋律+和弦完整谱（配 full，和声也一起锚住）。和弦在两种模式下都会被识别，勾选几乎不多花时间。诚实的限制：完整谱的和弦记号要过 SheetSage2 的记号表，遇到它不认的和弦性质会整份 ABC 导出失败（不会静默给你一份旧谱，报错里写明原因）——遇到这种情况取消勾选重提一次即可。

注意：按谱生成只锚定旋律走向（full 还锚和声），不会保留原曲歌手的音色与原编曲。

每个任务都有一个全局唯一 ID（形如 20260926_183413_64c31a01：创建时刻 + 32 位随机），任务名可以随便重复，ID 不会。它同时就是落盘文件名（runtime/output/<ID>.wav/.json/.lrc、换声与音色训练目录、乐谱存档），所以报障、删除、重跑都能精确定位到一次任务，不会误伤同名兄弟。历史页/换声列表/音色训练卡片/生成进度条上都直接显示 ID，点一下即复制。

批量队列另有一层队列 ID，代表"一次提交"：投 2 首就是这 2 首的队列，面板只显示这一批的 完成/总数，之前跑过的条目单独计为"历史队列记录"，不再混进当前总数。往还在跑的队列里追加时，新任务沿用那支队列的名字和 ID（追加本来就是同一支队列的延伸）。

不用。音色制作支持断点续跑，中断后从上次进度继续；训练前有模型体检（提前发现权重损坏/不匹配），训练过程支持试听，多音色还能融合。体检要真的把 .pth 用 torch 加载一遍（几十秒起步），所以结果按"文件指纹（修改时间 + 大小）"缓存：同一个没动过的模型重复点不会反复重载，重训覆盖了模型则自动失效，需要强制重测就带 ?force=1；加载失败（损坏、内存不够）不缓存，下次仍会重测。

不能。YuE2 模型权重遵循 CC-BY-NC 4.0（非商用），本项目扩展代码同样随上游许可分发，生成的音频也不建议商用。详见根目录 LICENSE 与下方许可说明。

上限分别是：曲风描述 2,000 字符、歌词 20,000 字符、ABC 乐谱 20,000 字符。超限直接报错并写明长度与上限，不再静默截断——以前超长会被砍尾，产出的音频与歌词尾部对不上，强制对齐就会错位，而且你从界面上看不出来被砍过。批量队列按同一口径逐条校验，一条超限只拒那一条。

按任务 ID 精确清：runtime/output/<ID> 的 .wav/.json/.txt/.lrc/.lrcjob/.elrc 全套产物、换声任务的工作目录 runtime/rvc/jobs/<ID>/（用户上传的原曲与分离出的干声/伴奏，以前只删成品 wav，这些目录会攒成几个 GB 的孤儿）。队列记录与历史存档同步删除。只认这张白名单后缀，绝不按通配匹配——把 * 当 ID 传进来清不掉任何东西。文件被播放器占用时删不掉就保留，不会假装删除成功。

不建议，而且默认会被拒。网关只监听 127.0.0.1，并有一道本机接口守卫：Host 不是回环地址直接 403（DNS 重绑定拿到的 Host: evil.com 就是这一条挡的）；变更类请求（POST/PUT/PATCH/DELETE）带的 Origin/Referer 不是本机来源也 403（浏览器 CORS 只挡"读回包"，挡不住"发请求"，任意外部网页都能对 127.0.0.1 发无 body 的 POST 停任务、杀引擎）。响应还会带上 CSP frame-ancestors 只允许本机来源内嵌，防点击劫持。

如果你把 settings.app_host 改成 0.0.0.0（或任何非回环地址）想开放局域网，网关会直接拒绝启动并说明原因。两个原因：一是 Host 检查不改的话，局域网请求会被全部 403，"以为开放了其实锁死"比启动即失败更难查；二是放宽后的判定必须还能把"你自己的设备"和"被 DNS 重绑定指到你内网 IP 的网页"区分开——只比较 Origin 与 Host 这两个都由攻击者域名决定的字符串，等于没判。所以开放要两个变量一起给：YUE2_ALLOW_LAN=1（表明你知情）+ YUE2_LAN_HOSTS=192.168.1.7（逗号分隔的主机名白名单，就是你实际访问用的那个 IP 或主机名）。只给前者仍然拒绝启动。开放后：Host 必须命中白名单或为本机回环（dsh 代理的内部跳变恒发 Host: 127.0.0.1:7863），变更类请求的 Origin 必须命中白名单且端口是网关或工作台服务端口，CSP frame-ancestors 与 CORS 也只放行这批主机。局域网模式下没有任何账号隔离，且报错详情会带本机绝对路径与账号名，前面必须自己加一道反代鉴权——本工作台不为公网多用户设计。

⚠️ 一个 TCP 层的坑（评审复查实测确认）：app_host 要填 0.0.0.0，不要填某个具体 LAN IP（如 192.168.1.7）。本机 dsh 工作台的内部代理硬编码连 127.0.0.1:7863，网关只绑具体 IP 时回环上没人监听，工作台会直接连不上（ECONNREFUSED），HTTP 守卫修得再对也到不了那一层。绑 0.0.0.0 才能同时服务回环与局域网；网关启动时会检测到这种配法并打 ⚠️ 警告。

顺带一条同类收口：切换模型（POST /api/models/switch）以前"校验用一个变量、写进 server.json 用另一个未校验的变量"，../ 能把路径带出引擎工作目录；现在只接受 model/ 下的纯文件名，带目录的一律 400。

收——现在才叫真的收。早期版本首启用 WMI Win32_Process.Create 拉起网关（为了不弹黑窗口），而 WMI 派生的进程继承的是 WMI 服务的环境、不是那个 cmd 的环境，于是 HF_ENDPOINT/HF_HOME/TORCH_HOME/FFMPEG_PATH/NO_PROXY 和 secrets\local_env.bat 里的密钥对首启进程全部无效；偏偏看门狗重启那条路是带着环境传的，造成"第一次跑的和重启后跑的不是同一套配置"。现在两条路统一为 Start-Process -WindowStyle Hidden：同样不弹窗口，但逐层继承父进程环境（实测对照：同一段探针子进程，WMI 读不到变量、Start-Process 读得到）。密钥依旧只走环境继承，绝不出现在命令行字符串里（命令行全局可读）。

这条链路依赖本机的 GPT-SoVITS 安装（含 RoFormer/HPs 两个分离模型）。默认路径是作者机位置，别的机器请设环境变量 YUE2_GSV_ROOT 指向自己的 GPT-SoVITS 根目录；没配置时相关功能会在页面上给出明确提示，其他功能不受影响。GPU/CPU 也由后端模式统一决定，不再硬写 cuda。

py312\python.exe -m unittest discover -s tests -v

实测约 50 秒跑完 238 个用例。测试只操作临时目录和只读端点，不提交任何计算任务，因此 CPU/GPU 正在跑歌时可以并行执行（换声队列那组把真实 worker 换成假任务，同样不碰 GPU）。用例覆盖任务 ID 唯一性、删除清理白名单、输入长度上限（含历史记录与模板这两个存储入口）、和弦识别与 melody/full 配对、引号内英文单词不当成和弦、旧队列迁移、队列状态文件原子写、并发追加与崩溃复活上限、中断标注的诚实性（在算条目不被代写"服务重启"、只有早于本进程启动的才有资格这么说）、本机接口守卫（含 LAN 主机名白名单与端口，以及按 dsh 代理真实发出的请求头复现的"走代理"路径）、开放绑定拒绝启动、模型切换路径校验、上传总量与磁盘剩余闸门、体检结果缓存、看门狗"启动即死"熔断（刚拉起几秒就退出=配置错，不是假死，连击三次不再空转刷日志）、换声静音门（静音参考必须被压掉、有人声参考一律不动，两个方向都锁）与混音不得把立体声伴奏压成单声道，以及换声串行队列（三条一起提交时并发峰值必须是 1、执行顺序=提交顺序、位次随队列前移实时重算、只有没开跑的能取消、上传入口必须入队而不是起线程、排队条目要能在 /rvc/active 与 /history/active 里看见，以及把真实 _GPU_SEM 掐住时 worker 必须还待在 pending、不许提前起推理进程）。音色训练这一侧还锁住了：显存档位（6GB→3、16GB→8、CPU 与显存未知→4 且必须写明理由）、每轮耗时只能用实测节奏（没有真实节奏时不许假装知道，报错的作业不许写节奏）、数据集体检报出时长/静音占比/爆音，且体检过的素材训练时直接复用不重传、轮数档位能低于旧的地板值、检查点按分位留「最终 + 约 25% + 约 50% + 约 75%」四档且 G/D 成对（练过头要听中段，只留最近两个恰好把中段删掉；25% 那档是 10-03 重训实测「越练越脏」之后当场补的）、一个目录只用一种存盘制式（目录里只剩旧 G_2333333.pth 的音色继续按 -l 1 走，混了自动续跑会读错档）、重训先归档而不是删除（ckpt_archive/ 里连 train.log/tfevents 一起搬走，卡片不会拿上一轮的进度冒充本轮）、成品与索引覆盖前各备份一份到 before_rerun/、档位标签报「第 N 轮」而不是步数、逐点试听各自缓存互不覆盖、过期成品不许冒充检查点、选点定稿的 400/404/500 三条岔路（400 直接把本音色现有档位列出来，不拿一个已经不存在的写死档名当例子）、试听素材优先取训练侧的干净切片、loss 首尾用中位数并跳过第 1 轮冷启动尖峰，以及重训开始前把上一轮的结论清空（自检/损失/检查点列表/样片，样片挪进 before_rerun/ 而不是删）、看门狗只在端口仍有人监听时才免死、只体检未开练的任务在列表里可见且能一键删掉素材目录，以及高频噪声化（电音）那 4 例：数字静音段不许被算成毛刺（平谱会骗人，这是踩过的坑）、同样旋律更噪的那一份必须在每一项指标上都更差、_rvc_quality_report 要把锅判给正确那一层、素材量得出而产物量不出＝最坏结论，不许留成一片静默空白、辅音音头那 1 例：谐波堆上每秒一次硬起音 vs 同样高频能量但 0.35 秒慢攻击，前者必须数得出音头、后者必须掉一半以上并判 muffled，同一条音频自己比不许报警（齿音是清音，筛帧时只按响度、不能再要求"有声"，否则要量的东西被筛掉了）。看门狗侧另有 7 例锁住**"训练在推进时不许误杀"：端口有人监听 + 长任务刚写过文件才免死，端口空了照样拉起（02:56 那个洞——免死之后什么都不做，页面一直连不上）。换声侧真实 worker 必须把 --index 指向自己的那份索引**（串台那次的回归锁）。换声参数新三件的闸门（偶数平滑半径必须被钳成奇数、缺 fcpe 能力或依赖时提交即 400 且给出路、runtime 缺 --filter-radius 时 worker 不传该参数并在任务上留痕）、能力探测的解析与缓存（探坏按缺能力降级，不许崩提交）。素材净化（评审 A1）这一侧 13 例：净化两阶段必须真按 -m pymss.cli 调用（包名别名是 VR 模型的真机拦路虎）、干净声部只认精确名单（"No Noise" 含 "Noise" 这类子串陷阱各有用例）、缺输出逐文件回退并计数、整批失败先重试、全部失败必须在挪动任何文件之前终止且文案给出路、续跑已净化即跳过、前缀撞名（s 不许抢走 s0_Dry.wav）、档位模型必须真实存在于 vendored 目录、提交闸门只认 off/light/medium、档位随续跑继承、体检底噪 -38.8/-46/很干净三档分别荐「中」「轻」「不净化」且文案如实交代"混响机器判不准"。音域建档与清理（评审 J1 + 自查 K1 + J3）：下载音色传一段该歌手本人的参考音频即解锁变调建议、且来源必须标成"参考音频实测"而不冒充训练实测；2a_f0 空目录才回落到建档档（训练集是这个音色的第一手证据，参考音频盖不过它）；不存在的音色 404、纯静音 422 且不留假档案。删一条换声记录必须把它登记的三个多产物（<id>_full_song.wav 等）一起带走，而 meta 里被塞进穿越名或别人任务的文件名时那些文件必须原地不动。净化子进程退出码 0 却零产出不许算成功。每个用例都标了对应的评审编号。

发版前自检：py312\python.exe -m unittest discover -s tests 必须全绿，并且改动过的行为要按下方「版本与发版」里那条冒烟清单在本机实测一遍再打 tag —— 评审里"代码已改"和"线上生效"是两件事，网关是常驻进程，不重启就看不到新逻辑。