SCAIL-2 (ComfyUI 版) 部署实战

> 2026-09-03 老张 & 新艳 在 AutoDL RTX PRO 6000 96G 上完整跑通后沉淀。
> 目标：任意云端（AutoDL 等）或本地（Linux / Windows 双平台）+ NVIDIA GPU，从零部署到能跑 SCAIL-2 角色动画。
> v1.1.0 新增 Windows 原生 + WSL2 双路径与显存档位说明。

一、架构认知（先懂再装）

> 💡 三分钟决定要不要继续：SCAIL-2 是 31GB 级模型（Wan2.1-14B），低于 12G 显存的机器装不了也别装；只想"看看效果"建议直接用智谱官网或官方 API 试玩，省得搭环境烧时间。本技能面向：真要在自己机器/云端部署的人。

• SCAIL-2 = 智谱 AI 基于 Wan2.1-14B 的改装版（加动作控制头），不是独立底模
• 依赖 Wan2.1 全套生态：VAE(wan_2.1_vae)、文本编码器(umt5_xxl)、CLIP Vision、采样器
• ComfyUI 0.33.0+ 内核原生支持 SCAIL-2 + SAM3 节点，不用装任何自定义节点
• SAM3.0 与 SAM3.1 是两个不同模型类（见第五节），推荐用 SAM3.0 原版

二、前置条件

2.1 🔑 先看显存档位（决定你的卡能干什么）

> 💡 显存不足时的降档组合：fp8 或 int8 量化主模型 + turbo LoRA 减步 + 512×896 低分辨率 + 短片段（≤81 帧）。
> Windows 12G 卡实测定位：验证节点链路、SAM3 mask、提示词效果——真批量出片建议云端。

⏱️ 动手前 60 秒自检（回答三个问题再决定路线）：
1. 我的卡 ≥24G？ → 否：看降档组合 or 直接租云（AutoDL 等 96G ≈¥6/时）
2. 我要跑长视频/批量？ → 是：直接上云端，本地 12G 别硬扛
3. 我只是试玩？ → 是：先试官方 API 再决定要不要部署

2.2 🪟 Windows 部署（原生 或 WSL2，二选一）

路径 A：Windows 原生（推荐给只是想试跑的）

# A1 装 Python 3.10-3.13（python.org 官方安装包，勾选 Add to PATH）
# A2 装 CUDA 版 PyTorch（先看显卡驱动支持的 CUDA: nvidia-smi 右上角）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
#   ↑ 或 cu121/cu128，取决于驱动；3060 用 cu126/cu121 均可
# A3 拿 ComfyUI（官方 Windows 便携包最省事）
#   下载 ComfyUI_windows_portable_nvidia.7z 解压即可，自带 python+torch
#   （或 git clone https://github.com/comfyanonymous/ComfyUI + pip install -r requirements.txt）
# A4 启动（双击 run_nvidia_gpu.bat 或命令行）
python main.py --listen 127.0.0.1 --port 8188
# A5 浏览器开 http://127.0.0.1:8188 就是 GUI

路径 B：WSL2（推荐给要"跟 Linux 文档一字不差"的）

# B1 PowerShell(管理员): wsl --install -d Ubuntu-22.04   # 装完重启
# B2 Windows 侧装好 NVIDIA 驱动（WSL 内 nvidia-smi 能见卡即 OK）
# B3 进 WSL 后照 Linux 部署步骤走（conda h3 + torch cu130 + ComfyUI 0.33）
#   唯一差异: CUDA 驱动由 Windows 宿主提供，无需在 WSL 里装驱动
# B4 启动 ComfyUI 后，Windows 浏览器直接访问 http://127.0.0.1:8188
#    （WSL2 localhost 自动转发，无需额外配置）

Windows 专属注意

> 🔑 通用部分（模型下载 / SAM3.0 权重 / 节点补丁 / 工作流 / 排坑）三章起全平台共用，Windows 用户从「三、模型下载」继续即可。

三、模型下载清单（总 ~50G）

3.1 模型清单与放置目录

3.2 🔑 SAM3.0 权重获取（绕过 Meta gated）

Meta 原版 facebook/sam3 在 HF 是 gated（需申请授权，等几天）。
但 ModelScope 镜像同名仓库不设限，国内直连秒下：

pip install modelscope
# 只下 sam3.pt 到 ComfyUI checkpoints 目录
python -c "
from modelscope.hub.file_download import model_file_download
p = model_file_download('facebook/sam3', 'sam3.pt',
    local_dir='<ComfyUI>/models/checkpoints/', revision='master')
print('DONE:', p)
"

⚠️ 关键区别（血的教训）：
- sam3.pt（3.45G，PyTorch 原版）= ComfyUI 要的 SAM3.0 格式 ✅
- model.safetensors（3.44G，transformers 版，key 带 detector_model. 前缀）= ComfyUI 不认 ❌
- 判别：ComfyUI 检测逻辑认 detector.* / tracker.* 顶层 key

四、环境排坑（⚠️ 全部实测踩过）

4.1 torch cu130 环境混装 cu12+cu13 nvidia 包 → cuDNN frontend 崩

症状：SAM3_Detect 报 cuDNN Frontend error ... major version mismatch between cudart and nvrtc 或
RuntimeError: cuDNN version incompatibility: PyTorch was compiled against (9,13,0) but found runtime (9,8,0)

修复（卸载 cu12 残留，对齐 torch cu130）：

# 1) 卸载 14 个 -cu12 包
pip uninstall -y nvidia-cublas-cu12 nvidia-cuda-cupti-cu12 nvidia-cuda-nvrtc-cu12 \
  nvidia-cuda-runtime-cu12 nvidia-cudnn-cu12 nvidia-cufft-cu12 nvidia-cufile-cu12 \
  nvidia-curand-cu12 nvidia-cusolver-cu12 nvidia-cusparse-cu12 nvidia-cusparselt-cu12 \
  nvidia-nccl-cu12 nvidia-nvjitlink-cu12 nvidia-nvtx-cu12

# 2) 补装 cu13 套（必须 --force-reinstall，否则文件缺失）
pip install --force-reinstall --no-deps nvidia-cusparselt-cu13==0.8.0
pip install --force-reinstall --no-deps nvidia-nccl-cu13==2.27.7
pip install --force-reinstall --no-deps nvidia-cudnn-cu13==9.13.0.50

验证：python -c "import torch; print(torch.cuda.is_available(), torch.backends.cudnn.version())" → 期望 True 91300

4.2 GPU 设备节点缺失 / nvidia-smi 是 0 字节

症状：torch.cuda.is_available() == False，但 /proc/driver/nvidia/gpus/ 有卡
场景：云端实例切换 GPU 后设备节点没重建，或之前误装驱动留下 0 字节假文件

修复（root 下重建节点）：

grep nvidia /proc/devices  # 看主设备号，通常 195 nvidia / 503 uvm
mknod /dev/nvidiactl c 195 255
for i in 0 1 2 3 4 5 6 7; do mknod /dev/nvidia$i c 195 $i; done
mknod /dev/nvidia-uvm c 503 0
mknod /dev/nvidia-modeset c 195 254
chmod 666 /dev/nvidia*

终极解法：云端实例去控制台「重启/开卡」，环境自动恢复干净（最省事）。

五、SAM3.0 vs SAM3.1 工作流差异（🔴 最容易错）

5.1 节点补丁（ComfyUI 0.33.0 必须打！）

症状：SAM3_VideoTrack 报 can't assign a tuple to a torch.HalfTensor
根因：节点 execute() 只适配 SAM3.1 字典返回，SAM3.0 的 track_video 返回纯张量
补丁：改 comfy_extras/nodes_sam3.py（改前 cp nodes_sam3.py nodes_sam3.py.bak）：

# 原代码:
result = sam3_model.forward_video(...)
result["orig_size"] = (H, W)   # ← SAM3.0 时 result 是 tensor，这行炸

# 改为:
result = sam3_model.forward_video(...)
if isinstance(result, dict):
    result["orig_size"] = (H, W)
    return io.NodeOutput(result)
# SAM3.0: tensor -> pack 成字典
from comfy.ldm.sam3.tracker import pack_masks
logits = result.to(device=device)
N, N_obj = logits.shape[0], logits.shape[1]
bin_masks = logits > 0
if bin_masks.shape[-1] % 8 != 0:
    bin_masks = torch.nn.functional.pad(bin_masks, (0, 8 - bin_masks.shape[-1] % 8))
result = {"packed_masks": pack_masks(bin_masks), "n_frames": N, "scores": []}
result["orig_size"] = (H, W)
return io.NodeOutput(result)

5.2 文本编码器别用错（报 mat shape 错误）

症状：mat1 and mat2 shapes cannot be multiplied (512x4096 and 1024x256) at detector.py resizer
根因：给 SAM3 的 CLIPTextEncode 用了 Wan 的 umt5_xxl（4096 维）≠ SAM3 自带 language_backbone（1024 维）
修复：SAM3 的文本编码必须用 CheckpointLoaderSimple(sam3.pt) 的 CLIP 输出（["58", 1]），不能用 umt5

{"class_type": "CLIPTextEncode", "inputs": {"clip": ["58", 1], "text": "human"}}
//       58 = CheckpointLoaderSimple(sam3.pt)   ↑[1]=它自带的 CLIP

六、启动 & 端到端验证

6.1 启动 ComfyUI

cd <ComfyUI>
python main.py --listen 0.0.0.0 --port 8188
curl http://127.0.0.1:8188/system_stats   # 验证 API

6.2 最小验证图（SAM3.0 全链路）

LoadVideo(驱动视频) → GetVideoComponents → ImageScale(640x1152)
LoadImage(人物参考图) → ImageScale(640x1152)
CheckpointLoaderSimple(sam3.pt)
  ├─ [0] model → SAM3_Detect / SAM3_VideoTrack
  └─ [1] CLIP → CLIPTextEncode("human")
ImageFromBatch(取首帧) → SAM3_Detect → 首帧mask
SAM3_VideoTrack(images=驱动帧, initial_mask=首帧mask) → driving_track
SAM3_VideoTrack(images=参考帧, initial_mask=参考mask) → ref_track
SCAIL2ColoredMask(driving_track, ref_track) → 彩色mask
WanSCAILToVideo(pose_video=驱动帧, pose_video_mask=彩色mask,
                reference_image=参考图, reference_image_mask=colored[1],
                clip_vision_output=CLIPVisionEncode(clip_vision_h, 参考图),
                width=640, height=1152, length=81)
→ SamplerCustom(euler/simple, 30步, cfg=1.0) → VAEDecode → VHS_VideoCombine

质量参数（治虚影/手部）：30 步（≥20）、负向加 ghosting, motion blur, double exposure, extra fingers, malformed hands, fused fingers、SAM3 refine_iterations=4、提示词加 sharp details, natural hands and fingers。

6.3 长视频分段（>81 帧）

单段上限 ~81 帧。全片 292 帧示例：[81, 76, 76, 59] 四段链式——
每段 WanSCAILToVideo 接上一段 VAEDecode 输出作 previous_frames（节点内自动只取尾部 5 帧锚定），
video_frame_offset 用上一段节点输出 [wv_id, 3] 链式传递。
实测 4 段输出帧数为 81+73+73+57=284（Extend 段自动去重叠帧）。

6.4 合入原视频音乐

# 抽音轨 + 拼接 + 合轨
ffmpeg -y -i drive.mp4 -vn -acodec copy drive_audio.m4a
ffmpeg -y -f concat -safe 0 -i list.txt -c copy combined.mp4   # list.txt 写绝对路径
ffmpeg -y -i combined.mp4 -i drive_audio.m4a -c:v copy -c:a aac -shortest final.mp4

七、分辨率上限（Wan2.1 骨架决定）

八、常用排坑速查

九、验证完成标准

1. import torch: cuda True, cudnn 91300
2. ComfyUI /system_stats 正常
3. 单节点 SAM3_Detect(首帧) 出 mask 无报错
4. SAM3_VideoTrack 带 initial_mask 跑通 100 帧
5. 81 帧单段 SCAIL-2 出片成功
6. （可选）多段链式全时长 + 合音乐