shaomang/mtnode-aio/minimax-h3-install

MiniMax H3 本地安装

当用户或 MTNode 插件要求在某目录安装 / 自我修复 MiniMax H3（本地 ComfyUI 视频生成） 时使用本 skill。

插件调用时：

• 当前工作区就是 `INSTALL_DIR`，可直接读写并执行命令
• `SCAFFOLD_REF`（或 `.scaffold-ref`）仅作参考：内置脚手架/脚本是示例实现，不是已完成的安装
• 不要假设插件已替你复制好脚手架
• 若任务附带 CONSOLE_LOG，以「最近失败焦点」为准自行分析修复（每人环境不同）
• 先做硬件探测，再决定装什么/怎么装（不同 GPU/驱动/显存差异很大，见下）

目录约定（以 SCAFFOLD_REF 为参考）

• INSTALL_DIR/ComfyUI/ — ComfyUI 根（main.py + venv/ + models/ + custom_nodes/）
• INSTALL_DIR/app/ — 冒烟/健康检查模块（python -m app 打印 JSON 报告，见下）
• INSTALL_DIR/scripts/ — setup_env.ps1 / download_models.ps1 / repair_torch_kitchen.ps1 / patch_*.py / start_backend.cmd
• INSTALL_DIR/output/ — 视频输出（勿删）
• INSTALL_DIR/.cuda-python — 探测到的 CUDA Python 基座路径（setup 后写入）
• 权重位置（ComfyUI 约定）：models/diffusion_models/、models/text_encoders/、models/vae/、models/upscale_models/、custom_nodes/ComfyUI-Frame-Interpolation/ckpts/rife/

国内镜像（必须）

中国大陆网络下，以下镜像必须使用：HuggingFace 无法直连，Python 库必须走清华/中科院镜像。

• 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_H3_PIP_INDEX 覆盖（覆盖的是链的第一级，后面三级兜底仍在）。
• 这条链是随包脚本自己实现的：setup_env.ps1 / repair_torch_kitchen.ps1 里都有一份 $PipIndexChain，每次 pip install 逐级试（每试一级打一行 [h3-setup] pip index=N/4 host=…），上一级失败不再立刻 throw，末级仍失败才报错并点名 No matching distribution found for <包名>。别只调 cn-mirrors.js 的环境变量就以为有回退 —— 宿主注入的 PIP_INDEX_URL 只是第一级。
• 镜像没同步某个包 ≠ 版本写错：ComfyUI 的 requirements.txt 钉了一串子包，任一子包在清华/USTC 缺失，pip 就报 (from versions: none) 并让整步失败。2026-10 实测：comfyui-workflow-templates==0.11.78 依赖的 comfyui-workflow-templates-media-assets-02==0.1.11 在清华与 USTC 都是 404、阿里云与官方 PyPI 都有 —— 症状是安装窗报「隔离 venv 没建起来（venv python 不存在）…多半是驱动与 CUDA 档位不匹配」，而现场其实 venv 在、上一个 step 的 torch 也早就绪。判据一律看那一步日志尾部的 pip 原始报错，别顺着「驱动」往下修。
• 反制机器级 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 次重试。
• torch cu130：SJTU https://mirror.sjtu.edu.cn/pytorch-wheels/cu130 → 阿里云 https://mirrors.aliyun.com/pytorch-wheels/cu130 → 官方 https://download.pytorch.org/whl/cu130（MT_H3_TORCH_INDEX 可覆盖）
• 模型权重（HuggingFace 无法直连）：优先 ModelScope(魔搭) Comfy-Org/MiniMax-H3（国内直连）→ 失败回退 HF_ENDPOINT=https://hf-mirror.com + HF_HUB_DISABLE_XET=1 → 最后一级才是官方 huggingface.co
• GitHub（ComfyUI / KJNodes 克隆 / release 归档）：直连失败用代理回退 https://ghfast.top → https://gh-proxy.com → https://ghproxy.net → 直连（cn-mirrors.js 的 ghProxyUrls()）
• 安装示例：

``powershell .\scripts\setup_env.ps1 # pip 按清华 → 阿里云 → USTC → 官方逐级回退；基座 Python 自动取（3.11 / 3.12），可用 -CudaPython 或 MT_H3_CUDA_PYTHON 显式指定 .\scripts\setup_env.ps1 -SourceOnly # 只保证 ComfyUI 源码在场（clone 缺失时），venv / torch / 依赖 / 节点一律不碰 .\scripts\download_models.ps1 # 权重默认走 ModelScope ``

脚本语言与编码（必须：零中文 + 钉死 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，并按 [h3-setup] / [h3-download] 抓进度）看到的就是正常文本。

• 这条纪律已是硬守卫：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 钉死正确显示。

硬件探测（第一步，必做）

用 nvidia-smi 探测，不要假设是 RTX 4090：

nvidia-smi --query-gpu=name,memory.total,driver_version,compute_cap --format=csv,noheader

判定并记录：

系统内存：(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory → <32GB：权重 offload 到 RAM 会挤，警告并建议优化。

若 GPU 非 NVIDIA 或驱动过老，如实返回失败并写清原因（reason=），不要硬装或给出能用假象。

关键版本事实（实测，务必遵守）

H3 量化算子依赖 CUDA 13 的优化算子；torch 必须是 cu130 或更高。实测：

• torch 2.9.1+cu130（torchvision 0.24.1+cu130、torchaudio 2.9.1+cu130）→ 正常跑通，采样约 5s/it。
• torch 2.6.0+cu124 → ComfyUI 日志 comfy_kitchen backend cuda: {'available': True, 'disabled': True}，第一次 denoise forward 永久卡死（GPU 100%、CPU 0、进度停在 0%，tqdm 计时却在跑）。这是最常见的「能启动但不出片」假象。
• 排查：若启动日志出现 You need pytorch with cu130 or higher to use optimized CUDA operations 或 DynamicVRAM ... PyTorch 2.8+，即 torch 太旧。

配套版本（实测可跑通）：comfy-kitchen 0.2.31、comfy-aimdo 0.4.13、comfyui ~0.33。

驱动与 CUDA 13

torch cu130 wheel 自带 CUDA 13.0 运行时，但要求 NVIDIA 驱动足够新。安装后必须验证：

& "ComfyUI\venv\Scripts\python.exe" -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"

• 打印 True → 继续（CUDA 13 可用）。
• 打印 False → 驱动太旧，H3 无法跑优化的 CUDA 算子。此时：告知用户更新 NVIDIA 驱动（≥ 支持 CUDA 13.0 的版本），并 ok=false reason=driver_too_old，不要退回 cu124 重装（会回到卡死）。
• 顺带核对启动日志中 comfy_kitchen backend cuda ... 'disabled': False（未被禁用）。

基座 Python（setup_env 自动取，也可手动指定）

判据是解释器版本，不是「已经装好 CUDA torch」（历史上那条判据是错的：往隔离 venv 里装 CUDA torch 正是 setup_env.ps1 自己的活，要求用户先备一个带 CUDA torch 的 Python 等于把活推回给用户；2026-11 用户实测报错 Need a Python with CUDA torch. Pass -CudaPython <path> or set MT_H3_CUDA_PYTHON. 就是它）。

setup_env.ps1 走共享获取器 scripts/base_python.ps1（真源 pack-python/base_python.ps1，h3 / music3 / yue2 三包逐字节一致），顺序：

1. -CudaPython / MT_H3_CUDA_PYTHON / MT_H3_PYTHON / 安装目录 .cuda-python 记录的路径（可选覆盖，版本不合格就直接报 h3.python.too_old / h3.python.too_new）；
2. 常见 conda（ProgramData / 用户目录的 miniconda3 / anaconda3 的 envs\seg|torch|pytorch|cuda|base\python.exe）与 PATH 上的 py -3.11/3.12 / python / python3 —— 只要版本是 3.11 或 3.12 就用（不查 torch；老 conda 的 3.10 会因为 cu130 没有 cp310 轮子被跳过）；
3. 都没有 → 自己取一个：有 uv 用 uv python install 3.11/3.12（UV_PYTHON_INSTALL_MIRROR 指向 npmmirror），没有 uv 就直接从 https://registry.npmmirror.com/-/binary/python-build-standalone 下 cpython-3.1x…-x86_64-pc-windows-msvc-install_only(-stripped).tar.gz 解压；缓存目录 %APPDATA%\pipeline-console\python（公共缓存，已下过不重下）。

失败码（安装窗按 steps.json 的 messages 表渲染中文）：h3.python.missing（连下载都失败：网络 / 缓存目录不可写）、h3.python.fetch_failed、h3.python.too_old / h3.python.too_new（是你自己指定的路径不合格）。取到的路径仍写进 INSTALL_DIR\.cuda-python（宿主与 Agent 修复链读它）。

同一条链还带显卡体检（-SkipGpuProbe 模式，只跑 nvidia-smi）：没 N 卡 → h3.gpu.none，驱动主版本 < 580 → h3.gpu.driver_old。install.ps1 在 venv 步之前先跑它，所以「没卡 / 驱动太旧」不会再伪装成 venv 或 Python 失败。

目标

在 INSTALL_DIR 完成可运行后端：

• ComfyUI\venv\Scripts\python.exe 存在且 venv 内 torch.cuda.is_available() 为真（torch ≥ 2.9.1+cu130）
• import comfy_kitchen 成功（torch 必须在 ComfyUI\venv，禁止 --system-site-packages）
• ComfyUI\main.py 存在
• 权重就绪（约 42–65GB；建议预留 ≥70GB）：
• models\diffusion_models\minimax_h3_fl2va_pruned_int8_convrot.safetensors
• models\diffusion_models\minimax_h3_ref2va_pruned_int8_convrot.safetensors（R2V）
• models\text_encoders\qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors
• models\vae\minimax_h3_video_vae_fp16.safetensors + minimax_h3_audio_vae_fp32.safetensors
• 后处理：models\upscale_models\RealESRGAN_x4plus.pth + custom_nodes\ComfyUI-Frame-Interpolation\ckpts\rife\rife47.pth（供独立后处理通道 h3:postProcess 用：视频超分 / 视频补帧节点；生成链不内联）
• 后处理（可选）：models\upscale_models\RealESRGAN_x2plus.pth —— 超分节点选 x2 倍率时优先用它（中间张量只有 x4 的 1/4，峰值系统内存降一档）；缺失不影响安装，缺时用 x4 权重 + 输出端缩到 2 倍
• custom_nodes：ComfyUI-KJNodes（含 Sage / VRAM_Debug / MiniMax LowVRAM / ChunkFFN）、ComfyUI-Frame-Interpolation（4K 补帧）、ComfyUI-MiniMaxH3-TeaCache（脚手架仍克隆但推荐链已移除 TeaCache，保留作可选）
• 不随包附带任何第三方节点包：内置两条链（FL2VA / R2V）只用上面这些节点，装完即可出片；自建工作流若要引用第三方节点（如中文控件的多参生成类节点），由用户在自己的 ComfyUI 里自行安装，MTNode 不做部署、只走 POST /prompt。
• python -m app 健康检查退出码 0（见「冒烟与健康检查」）
• 不要在本 skill 中启动 ComfyUI

显存最佳实践

官方/社区在 24GB 上稳定跑通依赖：量化权重 + 注意力加速 + 步间缓存 + 采样后卸模型再 VAE。整机建议 ≥32GB 系统内存（权重会 offload 到 RAM）。

启动参数（脚手架 scripts\start_backend.cmd 默认，插件可关）

python main.py --listen 127.0.0.1 --port 8188
  --disable-pinned-memory
  --fp16-intermediates
  --reserve-vram 4
  --cache-ram 8 4

环境变量 PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True。插件侧 --disable-pinned-memory/--fp16-intermediates 默认开启、--reserve-vram 档位可配置（关闭/调整后按本表仍应保持 VAE 在 GPU）。

`--cache-ram` 是「系统内存（RAM）被跑满、显存反而空着」那类故障的正解，别省：ComfyUI 默认按

「非活跃阈值 = 100% 内存（最高 128G）」保留节点产物，而超分 / 补帧链的峰值本来就在 RAM——

整段视频的帧张量（外加 float32 副本）攒在系统内存里逐帧过 GPU，峰值 ≈ 源像素 × 16（x4 中间张量）× 帧数。

--cache-ram 8 4 = 活跃 / 非活跃两个保留下限（GB），内存吃紧时才释放缓存产物。插件侧默认开、档位可配置

（【系统内存缓存保留下限】，置 0 = 不加该参数）。超分提交前插件还会按容器里的真实帧数估峰值，

超预算先压目标长边、仍放不下就进超分前预缩放源帧（控制台会写明取舍）——排查这类问题先看那条日志。

`--cpu-vae` 默认关闭，并且不要打开（脚手架 start_backend.cmd 不带它；插件控制台里这个开关已整体移除，宿主启动参数里也永远不会出现它，若发现自己环境手动带了它，去掉再复测）。开启必致 dtype 崩：VideoVAE 解码报 expected m1 and m2 to have the same dtype, but got: float != struct c10::Half —— 采样跑得完、解码阶段挂掉，任何 H3 生成链（内置与自建）都出不了片。所以见到这条 dtype 报错，第一件事是核对插件 Console 的 [launch] flags=… 里有没有 --cpu-vae，而不是去改工作流的 VAE 组合。

显存峰值靠下面的 VRAM_Debug 屏障（先卸 DiT 再解码）压，不靠把 VAE 搬到 CPU。

--disable-pinned-memory 与 --lowvram 同开冲突；不要用 --lowvram。

工作流节点（MTNode 默认启用，节点设置可关）

推荐模型链：UNET → EasyCache → SigmaShift → LowVRAMAttn → ChunkFFN → Sage → Guider（TeaCache 已移除） 采样输出必须经 VRAM_Debug（unload_all_models=true）后再 VAEDecode / VAEDecodeAudio。缺失该屏障 → 解码在 24G 上卡死（DiT 19.9G + VideoVAE 4.9G 超 24G）。

EasyCache 档位口径（H3 不是图像模型，别照抄节点默认值）

• 本 skill 只给结论与判据，数值真源在 `h3/main-h3.js` 的 `EASY_SAFE`（下发前把用户自定义值夹进该区间）。修环境 / 改图时不要把档位改回官方默认，那会把「一开就废」的档放回去。
• 质量安全档：`reuse_threshold=0.08` / `start_percent=0.30` / `end_percent=0.90`（夹取区间 reuse 0.01–0.2、start 0.15–0.6、end 0.6–1.0；三个值都是越小 / 越晚 = 越保真、越不加速）。
• 为什么不用 ComfyUI `EasyCache` 节点自带的 0.2 / 0.15 / 0.95：那套是按几十步的图像模型调的；H3 内置生成链只有 20 步（官方 template 靠 turbo LoRA 压到 4–8 步、根本不用 EasyCache）。起点 0.15 → 第 3 步就进缓存，reuse 额度 0.2 又够大 → 第 3 步起大段步骤直接复用上一版输出，表现为跳步 / 画面漂移。
• 实测判据（864×480 / 20 步 / 同种子，与「关缓存」对比）：官方默认 0.2/0.15/0.95 → 逐帧差异 mean 0.0385、max 0.1323，相邻帧抖动 mean 0.0119（关缓存 0.0092），画面明显跳变；0.08/0.30/0.90 → 差异 mean 0.004、抖动与关缓存基本一致，同时仍实打实跳步（有加速收益）。
• 因此用户报「开了 EasyCache 画质明显下降 / 画面在跳」时：先看节点上三个数有没有落回官方默认（插件 Console / 生成的 workflow JSON 里 EasyCache.inputs），再考虑关缓存或降档；这不是节点开关坏了，也不该为此重装环境。

24G 分辨率红线（超限是自动钳制，不是故障）