shaomang/mtnode-aio/sensenova-local-install

SenseNova 本地图像生成 — 安装 / 修复

当用户或 MTNode 插件要求在某目录安装 / 自我修复 SenseNova（SenseNova-U1.5-8B-MoT 本地文生图） 后端时使用本 skill。

上游参考：OpenSenseNova/SenseNova-U1（安装文档 docs/installation_CN.md）、 权重 ModelScope SenseNova/SenseNova-U1.5-8B-MoT · HuggingFace sensenova/SenseNova-U1.5-8B-MoT。 官方文档与示例脚本以 Linux 为准，本 skill 是本机（Windows）移植口径，两者冲突时以本 skill 为准（见「Windows 与官方 Linux 的差异」）。

对接面核对基准：tag `comfyui-v0.3.0` 的 examples/t2i/inference.py（t2i_generate 的入参、SUPPORTED_RESOLUTIONS 11 个训练桶、_denorm 反归一化）、examples/editing/inference.py（参考图 / 图像编辑：it2i_generate(tokenizer, prompt, images, image_size=…, cfg_scale=…, img_cfg_scale=…, …)，images 是 PIL 列表）与 apps/comfyui/local_pipeline.py（进度钩子）。升级 `-Ref` 到新 tag 前必须重核这几处，接口一变本包的 app/engine.py 就要跟着改。

插件调用时：

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

目标

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

• INSTALL_DIR\.venv\Scripts\python.exe 存在；-c "from app import server"、-c "import sensenova_u1"、-c "import torch" 三条都成功
• venv 内 只装 CUDA 版 torch（禁 --system-site-packages），torch.cuda.is_available() 为真且版本串带 +cu1xx（不带 +cu 就是 CPU 版，判失败）
• transformers >= 4.57.1：低于此版本 AutoConfig 认不出 model_type: "neo_chat"，加载必失败
• INSTALL_DIR\models\SenseNova__SenseNova-U1.5-8B-MoT\ 权重就绪：config.json + model.safetensors.index.json + 8 片 model-*-of-00008.safetensors，分片合计 ≥30GB（应约 32.66GB）
• INSTALL_DIR\models\.ok、INSTALL_DIR\.attn-backend（flash 或 sdpa）、INSTALL_DIR\.install-ok、INSTALL_DIR\.sensenova-agent-result 存在
• 冒烟通过后不要保留常驻服务：启停由插件负责（冒烟用的一次性启停必须结束就关）

输入参数

固定口径（不要改）：模型 SenseNova/SenseNova-U1.5-8B-MoT（ModelScope id，HF id 为小写 sensenova/...）、推理包 sensenova_u1（GitHub tag comfyui-v0.3.0）、服务端口 8774、默认 vram_mode=fast、默认 dtype=bfloat16、默认 attn_backend=sdpa。

脚本参数（scripts\install.ps1，幂等可重跑）：

目录约定（以 SCAFFOLD_REF 为参考）

• INSTALL_DIR/app/ — 只用标准库的 HTTP 服务（python -m app <port>；server.py / engine.py / __init__.py / __main__.py）
• INSTALL_DIR/.venv/ — 隔离虚拟环境（Python 3.11）
• INSTALL_DIR/models/SenseNova__SenseNova-U1.5-8B-MoT/ — 权重（+ 同级 .ok 标记）
• INSTALL_DIR/outputs/ — 默认产物目录（勿删；节点给了 outputDir 时写别处）
• INSTALL_DIR/src/ — sensenova_u1 源码解包目录（安装期产物，可留存）
• INSTALL_DIR/scripts/ — install.ps1（幂等）；根目录 start_backend.cmd（手动起服用）
• INSTALL_DIR/.attn-backend — 单行注意力档位（flash / sdpa），由安装期探针写出
• INSTALL_DIR/.install-ok、INSTALL_DIR\.sensenova-agent-result — 成功 / 结论标记（见「marker 约定」）

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

nvidia-smi --query-gpu=name,memory.total,driver_version,compute_cap --format=csv,noheader
(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory
(Get-PSDrive <安装目录所在盘>).Free

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

拒绝时必须一并给出的替代方案：

1. 改用 MTNode 的云端文生图节点 `proc_image`（不占本机显存、无安装成本），要本地化再谈；
2. 换 / 升级到 24GB 级以上的 NVIDIA 卡（4090 / 3090 / A5000 / A6000），或 48GB 卡上走 vram_mode=full；
3. 内存不足 → 加内存到 ≥40GB（权重 bf16 无法在内存里再压）；
4. 只有 CPU：官方链路在 CPU 上慢到不可用（且部分算子不可用），不提供 CPU 兜底，-Cpu 只能验流程不能出图。

拒绝不是失败报告：要写清实测 gpu= / vram= / ram= / driver= / 磁盘剩余，与上面 1–4 条，让用户能自己选下一手。

为什么必须分层卸载（别在文档里自创说法）

实测基准（RTX 4090 24GB · 驱动 610.88 · 63.8GB 内存 · bf16 · sdpa · E: NVMe）

首图含权重加载（懒加载），冷启动第一发比后续慢；同进程后续请求不必再加载。下表 elapsedSec 是 /generate 全程：

读法：fast 的显存是预算封顶的（约 16GiB，换更大的桶也只涨一点），所以 24GB 卡上 fast 就是默认档；low 把显存压到 3GiB 但慢约 2.4×。权重加载 28–32s（NVMe、8 片）；low/balanced 因逐层同步会更慢。冷启动第一发明显更慢（第一次进 offload 上下文、pinned cache 与 cudnn 预热）：12 步那次前一两步就吃掉几分钟，/progress 会一段时间停在 sample 15% 不动 —— 那是正常的，看 step/totalSteps 而不是只看 percent。

Python 选择（优先 uv 托管 3.11，全程不翻墙）

上游 requires-python >=3.10,<3.14，官方参考环境是 3.11。依次：

1. 显式 -Python <路径>
2. `uv python find 3.11` → 没有就 `uv python install 3.11`（约 30–60 秒）。必须先设镜像，否则卡在 GitHub release：

``powershell $env:UV_PYTHON_INSTALL_MIRROR = "https://registry.npmmirror.com/-/binary/python-build-standalone" ``

1. 本机 py -3.11 → -3.12 → -3.13 → -3.10（py -<ver> -c "import sys;print(sys.executable)" 取真实路径）
2. PATH 里的 python（必须核对版本在 3.10–3.13）
3. 都没有 → reason=python_not_found，指引：装 uv（pip install uv）或 python.org / Microsoft Store 装 3.11，或用 -Python 指路后重跑

命中后 venv 一律用它的 -m venv 创建（缺 pip 用 ensurepip 兜底，再退 uv venv --seed .venv）。

国内镜像（必须）与回退顺序

中国大陆网络下必须走镜像：HuggingFace 无法直连、download.pytorch.org 与 GitHub 极易超时。

• 权重下载可续传：已存在且非空的分片自动跳过；中断就重跑脚本。
• ModelScope 与 HF 的 id 大小写不同（SenseNova/… vs sensenova/…），结论文本里写清最终实际用到的源与 id。
• Windows PowerShell 5.1 下载前必须开 TLS1.2：[Net.ServicePointManager]::SecurityProtocol = … -bor [Net.SecurityProtocolType]::Tls12，否则 pip 装得上、tarball 下不动。
• 全程 UTF-8：PYTHONIOENCODING=utf-8 + install.ps1 / start_backend.cmd 里的 chcp 65001（GBK 控制台打进度会崩）；脚本自身是纯 ASCII 英文，中文只来自 Python 后端与原生工具（见「脚本语言与编码」）。

脚本语言与编码（必须：零中文 + 钉死 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，并按 [sensenova-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 钉死正确显示。

安装步骤（按序；括号内是脚本打印的 progress: 值）