shaomang/mtnode-aio/yue2-local-install

YuE2 本地音乐生成 — 安装 / 修复

当用户或 MTNode 插件要求在某目录安装 / 自我修复 YuE2（本地全曲音乐生成，含人声） 后端时使用本 skill。

上游参考：YuE2 官方仓库、m-a-p/YuE2-3B 模型卡。 官方文档与安装脚本以 Linux 为准，本 skill 是本机（Windows）移植口径，两者冲突时以本 skill 为准（见「Windows 与官方 Linux 的差异」）。

插件调用时：

• 当前工作区就是 `INSTALL_DIR`，可直接读写并执行命令
• `SCAFFOLD_REF`（或 `.scaffold-ref`）仅作参考：内置 yue-pack/ 脚手架是示例实现，不是已完成的安装。请按下方目标自行准备目录；可按需从参考路径复制或改写，也可等价实现
• 不要假设插件已替你复制好脚手架
• 若任务附带 CONSOLE_LOG（插件 console 最近日志），以「最近失败焦点」为准定位根因并修复，不要盲目重装全部模型

目标

在 INSTALL_DIR 完成可运行的 YuE2 后端，使：

• INSTALL_DIR\.venv\Scripts\python.exe 存在，且 .venv\Scripts\python.exe -c "import yue2" 成功
• venv 内只装 CUDA 版 torch（不许 --system-site-packages，与 Music3 的 system-site-packages 口径相反），torch.cuda.is_available() 为真
• INSTALL_DIR\models\m-a-p__YuE2-3B\ 与 INSTALL_DIR\models\m-a-p__YuE2-Vae\ 权重就绪（含 config.json 且权重文件非空）
• INSTALL_DIR\models\.ok 与 INSTALL_DIR\.install-ok 存在
• 冒烟通过后不要保留常驻服务：启停由插件负责（冒烟用的一次性启停必须结束就关）

输入参数

脚本参数（scripts\install.ps1）：-InstallDir、-PythonExe（显式指定 Python 3.12）、-TorchIndex（显式指定 cu 档位）、 -ModelDir（离线复用已有权重，建目录联接不复制）、-SkipModels、-AllowOtherPython（非 3.12 后门）。

目录约定（以 SCAFFOLD_REF 为参考）

• INSTALL_DIR/app/ — yue-pack 服务（python -m app <port>；server.py / engine.py / audio.py / __main__.py）
• INSTALL_DIR/.venv/ — 隔离虚拟环境（Python 3.12）
• INSTALL_DIR/models/ — m-a-p__YuE2-3B/、m-a-p__YuE2-Vae/（+ .ok 标记）
• INSTALL_DIR/output/ — 音频输出（勿删）
• INSTALL_DIR/scripts/ — install.ps1 / start_backend.cmd（幂等，可重复执行）
• INSTALL_DIR/.cuda-python — 探测到的 Python 3.12 基座路径（install 后写入）
• INSTALL_DIR/.install-ok、INSTALL_DIR/.yue2-agent-result — 成功 / 结论标记（见「marker 约定」）

硬件探测（第一步，必做，不合格直接拒绝）

nvidia-smi --query-gpu=name,memory.total,driver_version,compute_cap --format=csv,noheader
(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory
py -3.12 -c "import sys; print(sys.version)"

判定（硬门槛，不要硬装）：

替代方案（拒绝时必须一并告诉用户）：

1. 用云端 / 第三方 API 或 MTNode 的 Music 3 / 云端音乐节点出歌（本机不用装）；
2. 显存不足但想本机跑：走 ComfyUI 量化 YuE2 分支（FP8/int8 量化权重，显存占用低一档）——

如 t8star/YuE2-Comfy、 ComfyUI-FL-YuE2、 ComfyUI-Olm-YuE2、 ComfyUI-YuE2，按 H3 技能口径建 ComfyUI 环境；

1. 只有 CPU：官方链路在 CPU 上慢到不可用（且部分算子在 CPU 上不可用），不提供 CPU 兜底，如实说明。

拒绝不是失败报告：要写清实测 gpu= / vram= / driver= 与上面 1–3 条替代方案，让用户能自己选下一手。

基座 Python（3.12 优先 / 3.11 可用，install.ps1 自动取）

YuE2 本机移植口径：Python 3.12 优先，3.11 也可（cu130 轮子是 cp311+）。install.ps1 不再要求你先装 Python，走共享获取器 scripts/base_python.ps1（真源 pack-python/base_python.ps1，与 h3 / music3 逐字节一致）：

1. MT_YUE2_PYTHON / MT_YUE2_CUDA_PYTHON / .cuda-python 记录的路径（可选覆盖）
2. py -3.12 / py -3.11（Windows 启动器）、常见 conda（envs\py312|seg|torch|base）、PATH 中的 python / python3（必须核对版本，3.10 / 3.13 不算命中）
3. 都没有 → 自己取：有 uv 用 uv python install 3.12，否则从 https://registry.npmmirror.com/-/binary/python-build-standalone 下 cpython-3.12…x86_64-pc-windows-msvc-install_only 解压；缓存 %APPDATA%\pipeline-console\python

命中后写入 INSTALL_DIR\.cuda-python（单行绝对路径），venv 一律用它的 -m venv 创建。失败码：yue2.python.missing（连下载都失败）、yue2.python.fetch_failed、yue2.python.too_old / yue2.python.too_new（你自己指定的路径版本不合格）——文案在 yue-pack/steps.json 的 messages 表。

国内镜像（必须）

中国大陆网络下必须走镜像：HuggingFace 无法直连。

1. pip：清华 https://pypi.tuna.tsinghua.edu.cn/simple（--trusted-host pypi.tuna.tsinghua.edu.cn）

→ 失败回退阿里云 https://mirrors.aliyun.com/pypi/simple/ → USTC https://mirrors.ustc.edu.cn/pypi/simple/ → 官方 https://pypi.org/simple（官方只做最后一级兜底）；可用 MT_YUE2_PIP_INDEX 覆盖。 反制机器级 pip.ini：用 PIP_INDEX_URL / PIP_EXTRA_INDEX_URL / PIP_TRUSTED_HOST 环境变量在安装子进程内覆盖 （宿主 cn-mirrors.js 的 installEnv() 已统一注入），绝不改用户机器上的 pip.ini。 不要用 `pip --isolated`：它忽略环境变量与用户级 config，机器级 extra-index-url = https://pypi.ngc.nvidia.com （NVIDIA PyIndex 常塞，国内 DNS 直接失败）照样生效，每个包白等 5 次重试。

1. torch（按驱动选 cu 档位，见下节）：SJTU https://mirror.sjtu.edu.cn/pytorch-wheels/<cuXXX>

→ 阿里云 https://mirrors.aliyun.com/pytorch-wheels/<cuXXX> → 官方 https://download.pytorch.org/whl/<cuXXX> （MT_YUE2_TORCH_INDEX 可覆盖）。 不要把 torch 写进 `requirements.txt`（清华镜像上的 torch 只有 CPU 轮子，会静默装成 CPU 版）。

1. 模型权重：优先 ModelScope（魔搭） modelscope.snapshot_download("m-a-p/YuE2-3B") /

"m-a-p/YuE2-Vae"（国内直连）→ 失败回退 HF_ENDPOINT=https://hf-mirror.com + HF_HUB_DISABLE_XET=1 的 huggingface_hub.snapshot_download → 最后一级才是官方 huggingface.co。

• 仓库 id 以实际可达为准：ModelScope 上若不存在同名仓库，先用 modelscope 的仓库查询 / HF 镜像确认真实 id 再下，

不要假设魔搭 id 与 HF id 一定同名；把最终使用的 id 写进日志与结论文本。

• 下载中断可重跑续传；已存在且非空的权重自动跳过，不重下。

1. GitHub（如需克隆官方仓库 / 自定义算子、下载 release 归档）：直连失败用代理回退

https://ghfast.top → https://gh-proxy.com → https://ghproxy.net → 直连（cn-mirrors.js 的 ghProxyUrls()）。

脚本语言与编码（必须：零中文 + 钉死 UTF-8）

宿主用 powershell.exe（Windows PowerShell 5.1）跑 scripts\*.ps1。而 UTF-8 无 BOM 的 `.ps1` 在中文 Windows 上会被按 GBK(cp936) 解码 —— 中文变成乱码字节，还会吞掉紧跟的 } / ' / "，脚本直接语法崩（本轮改前实测：breeze 10 处、sensenova 113 处、yue 42 处、tts 15 处、llama 3 处、h3 download_models 6 处 + repair_torch_kitchen 1 处语法错），控制台同时一片乱码。

• scripts\*.ps1 / scripts\*.cmd 与安装期辅助 *.py（如 download_weights.py / probe_attention.py）一律纯 ASCII 英文：注释、消息、异常文本全英文；不许有中文、全角标点、——、制表线 ─、emoji。
• .ps1 开头（param 块之后）必须钉死编码三行，.cmd 在 setlocal 后加两行：

``powershell try { [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false) } catch { } $OutputEncoding = New-Object System.Text.UTF8Encoding($false) $env:PYTHONIOENCODING = 'utf-8' ``

``bat chcp 65001 >nul set "PYTHONIOENCODING=utf-8" ``

这样脚本自身与 pip / git / python 的输出都按 UTF-8 出去，宿主（用 UTF-8 解码 stdout，并按 [yue2-install] progress: 抓进度）看到的就是正常文本。

• 这条纪律已是硬守卫：AGENTS.md 的「协作约定」钉了它，test/smoke-install-scripts.js 会自动扫描全部 *-pack 的 .ps1 / .cmd / .bat、*-pack/scripts/**/*.py、共享真源 pack-steps/ 与 pack-python/、以及项目 scripts/ 下的 .ps1 / .cmd / .bat —— 任一字节 > 0x7F（中文、全角标点、emoji、→、制表线）或带 BOM 即硬失败。改脚本后必须跑 node test/smoke-install-scripts.js（同时还钉 GBK(cp936) 与 UTF-8 双解码解析零错、进度前缀与 reason= 等 ASCII 契约仍在）；后端运行时 Python（*-pack/app/**、*-pack/shims/**）豁免，仍是中文。
• Python 后端（app/*.py 的启动横幅与日志）本轮不做零中文，仍是中文，靠上面的 UTF-8 钉死正确显示。

torch 与驱动档位（按 driver_version 自动匹配）

nvidia-smi --query-gpu=driver_version --format=csv,noheader 取主版本，按下表优先高档、失败逐档降级：

• 每档装完必须验证：& ".venv\Scripts\python.exe" -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"；

打印 True 才算该档成功。

• 三档全失败 → reason=torch_install_failed。
• torchvision / torchaudio 与 torch 同档同大版本（同一次 pip 命令一起装）。
• 装成 CPU 版（torch.version.cuda 为 None 或版本号不带 +cu）→ 视为该档失败，用 -TorchIndex 重装，

不要让服务以 CPU 版启动。

安装步骤（按序）

1. 硬件 / Python 探测（见上）。不合格 → 按拒绝口径写结论并中止，给出替代方案。
2. 准备工程文件

若缺 app\server.py / app\engine.py / app\ui.py / app\audio.py / app\__main__.py / scripts\install.ps1 / scripts\start_backend.cmd / requirements.txt / manifest.json： 从 SCAFFOLD_REF 复制或按参考自行生成。保留用户已有的 .venv / models / output。 入口口径：宿主（插件）只跑 .venv\Scripts\python.exe -m app.ui <port>（Gradio UI 入口）； -m app <port> 是标准库 HTTP 服务入口，仅用于自查 / 契约冒烟，不要拿它当宿主启动命令。

1. 建 venv（隔离，禁 --system-site-packages）

``powershell cd INSTALL_DIR & "<Python312>" -m venv .venv .\.venv\Scripts\python.exe -m pip install -U pip setuptools wheel -i https://pypi.tuna.tsinghua.edu.cn/simple ``

1. 按驱动装 CUDA torch（见上节），装完立即验证 torch.cuda.is_available()。
2. pip 安装 yue2 与依赖

``powershell .\.venv\Scripts\python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple ``

• requirements.txt 至少包含 yue2、modelscope、huggingface_hub、soundfile、numpy、transformers、

accelerate、safetensors、sentencepiece、gradio；torch 不在其中（gradio 是 app\ui.py 的必需依赖， 脚手架 install.ps1 在 requirements.txt 之外显式补装并做 import gradio 自检）。

• pip 的源不靠命令行参数，靠 `PIP_INDEX_URL` / `PIP_EXTRA_INDEX_URL` / `PIP_TRUSTED_HOST` 环境变量

（宿主注入；手工跑时先设好），不要加 `--isolated` —— 它忽略环境变量，机器级 pip.ini 的不可达 extra-index 会照旧生效。

• 若 yue2 在 PyPI 不可达：改从官方仓库以可编辑方式装（pip install -e <仓库路径> 或 pip install git+<镜像前缀>https://github.com/multimodal-art-projection/YuE.git），

并把实际安装来源写进日志与结论。

• 注意力档位在 Windows 上是明确故障点，不是「慢一点」：本机 torch 常常有 flash-attn 的 schema、没有对应 kernel，

yue2 默认 auto 会选到 flash，真实生成跑到 Planning score 阶段才报 USE_FLASH_ATTENTION was not enabled for build.；本移植因此把档位默认定成 `cudnn` （app\windows_patch.py 的 resolve_backend()：显式覆盖 → 默认 cudnn，不再三档探针选档）， 安装脚本只把这份默认记一份 JSON 记录到 <INSTALL_DIR>\.attention-backend。 真跑一次的确认由宿主在启动服务前做：scripts\probe_attention.py --only <生效档> --json （只验一档；跑不了直接报 attention_backend_unsupported，不自动降级）。 要换档只能显式：YUE2_ATTENTION_BACKEND=sdpa，或在 .attention-backend 里写单行纯文本。

• 不要装 `flash-attn`（Windows 无官方轮子，源码编译基本失败）：换档靠显式指定，不靠装 flash-attn。
• 装完自检：.\.venv\Scripts\python.exe -c "import yue2, soundfile, torch; print('deps ok')"。

1. 下载模型权重（ModelScope 优先，hf-mirror 回退；可参考 SCAFFOLD_REF\scripts\install.ps1）

目标：models\m-a-p__YuE2-3B\、models\m-a-p__YuE2-Vae\ 均含 config.json 且权重文件非空； 全部就位后写 models\.ok。已有非空权重则跳过。

1. 冒烟（必须做，判定安装是否成功）
2. 契约层：起服务 → GET /health → 字段齐全；若脚手架支持 MTNODE_YUE2_MOCK=1，可先跑一遍 mock（不加载 3B 权重，秒级）。
3. 一次极短真实生成（判定口径，mock 不能替代）：短歌词 / 极短时长 / 少步数，请求生成接口，

确认返回音频路径存在且文件非空（> 几 KB，且能被 soundfile 读出的时长 > 0）。

1. POST /api/shutdown 关掉服务（不要留下常驻进程），把音频路径与时长写进结论。
2. 标记完成：创建 .install-ok；写 .yue2-agent-result（ok=true）；失败写 ok=false + reason=。

yue-pack 服务契约（插件依赖，实现 app/ 时勿缺）

以 SCAFFOLD_REF 的 app/ 与插件 yue2/main-yue2.js 为权威实现；字段名不要改。