AI工具

Wan 2.2 本地部署教程：ComfyUI、显存选择与视频生成排错

Wan 2.2 本地部署指南，说明模型家族、ComfyUI 与 Diffusers 路线、CUDA 环境、显存预算、模型下载、生成参数、性能验证和常见错误。

Wan 2.2 是阿里 Wan-Video 团队发布的开源视频生成模型系列。 Google Trends 美国区的 “AI video” 上升查询中出现 wan 2.2，但本地部署最容易踩坑的并不是启动命令，而是下载了不适合显存和工作流的模型变体。 本文先解释模型家族，再分别给出 ComfyUI 和 Python 路线，所有显存数字都应以具体模型卡、分辨率和 offload 设置重新验证。

下载前先识别模型名称

Wan 2.2 仓库可能同时列出文本生成视频、图片生成视频、TI2V、Animate、S2V 等不同任务。 同一任务还可能存在不同参数规模、MoE 或量化版本。 模型文件名相似，不代表可以放进同一个工作流节点。 先在官方 README 记录四项信息：

  • 任务类型。
  • 参数规模与架构。
  • 推荐分辨率。
  • 官方推理入口。

不要先下载几十 GB 文件，再根据报错猜模型用途。

显存规划按峰值而不是模型文件大小

模型权重只是显存的一部分。 推理还需要文本编码器、VAE、激活、注意力缓存和输出张量。 分辨率、帧数、batch size 与采样步骤都会改变峰值。 CPU offload 能降低显存，但会增加系统内存和 PCIe 传输。 量化能减少权重占用，但不一定同比降低所有激活。 不要用“模型文件 14 GB，所以 16 GB 显卡一定够”做预算。

三种硬件路线怎么选

24 GB 以上 NVIDIA 显卡适合从官方较完整工作流开始。 12–16 GB 显卡需要选择较小模型、量化、低分辨率或 CPU offload。 8 GB 显卡更适合短片、低分辨率实验，不适合作为稳定生产基线。 多卡只有在推理框架明确支持时才有效，不能靠设置 CUDA_VISIBLE_DEVICES=0,1 自动合并显存。 纯 CPU 可以验证环境与节点，但生成速度通常不可实用。 AMD、Intel 和 Apple Silicon 支持情况以官方仓库与框架版本为准。

检查 NVIDIA 驱动和 CUDA 可见性 

1

nvidia-smi

记录驱动版本、显卡型号、总显存和当前占用。 Python 环境中再检查 PyTorch：

1

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.version.cuda); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU')"

nvidia-smi 正常而 torch.cuda.is_available() 为 false，通常是 PyTorch 安装了 CPU 版本或环境选错。 不要反复重装显卡驱动掩盖 Python 虚拟环境问题。

为 Wan 2.2 创建独立 Python 环境 

1
2
3

python -m venv .venv-wan22
.\.venv-wan22\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel

Linux：

1
2
3

python3 -m venv .venv-wan22
source .venv-wan22/bin/activate
python -m pip install --upgrade pip setuptools wheel

不要把 ComfyUI、自定义节点和独立 Diffusers 项目塞进同一个全局 Python。 依赖冲突时，独立环境比强制降级整个系统更容易恢复。

克隆官方仓库并锁定 commit 

1
2
3

git clone https://github.com/Wan-Video/Wan2.2.git
cd Wan2.2
git rev-parse HEAD

先阅读当前 README 的安装命令和模型表。

1
2

git status --short
git log -1 --oneline

教程与仓库更新不同步时，commit SHA 能说明你实际使用的版本。 不要在第一次成功前追踪未经验证的 PR 分支。

安装 PyTorch 时匹配官方支持组合

先到 PyTorch 官方安装页选择操作系统、包管理器和 CUDA 版本。 示例命令不能脱离当前驱动照抄：

1

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

cu128 只是示例，执行前确认 Wan 2.2 与依赖支持。 安装后再次运行 CUDA 可见性检查。 再按仓库要求安装依赖：

1

pip install -r requirements.txt

模型下载目录要有足够空间

权重、文本编码器、VAE 和缓存可能占用数十 GB。 下载前检查：

1
2

df -h
du -sh ~/.cache/huggingface 2>/dev/null || true

Windows：

1

Get-PSDrive -PSProvider FileSystem

把 Hugging Face 缓存放到大容量磁盘：

1

$env:HF_HOME = "D:\hf-cache"

环境变量只对当前终端生效时，打开新窗口会重新下载到默认位置。

使用 Hugging Face CLI 下载指定仓库 

1
2

pip install -U "huggingface_hub[cli]"
huggingface-cli login

只下载官方模型卡列出的仓库，不使用名称相似的未知镜像。

1
2

huggingface-cli download <official-model-repository> \
  --local-dir ./models/wan22

将占位符替换为官方 README 当前给出的模型 ID。 下载后保存文件清单和大小：

1

find ./models/wan22 -type f -printf '%P %s\n' | sort > wan22-files.txt

ComfyUI 路线先更新核心再装节点

备份现有 ComfyUI：

1
2

git -C ComfyUI status --short
git -C ComfyUI rev-parse HEAD

有用户修改时不要直接 pull。 在新目录测试更新版本，或先保存补丁。

1
2
3

git clone https://github.com/comfyanonymous/ComfyUI.git ComfyUI-Wan22
cd ComfyUI-Wan22
python -m pip install -r requirements.txt

Wan 2.2 原生节点支持情况以 ComfyUI 当前版本和官方工作流为准。

模型文件必须放进节点实际读取的目录

ComfyUI 常见目录包括：

1
2
3
4

ComfyUI/models/diffusion_models/
ComfyUI/models/text_encoders/
ComfyUI/models/vae/
ComfyUI/models/clip_vision/

不同工作流对目录和文件类型要求不同。 不要把所有文件都放进 checkpoints。 打开工作流后，节点下拉框没有模型，先查看 ComfyUI 启动日志中的扫描路径。 重启 ComfyUI，再刷新浏览器。

用额外模型路径避免重复占用磁盘

可以在 extra_model_paths.yaml 指向统一模型库。

1
2
3
4
5
6

wan22:
  base_path: D:/ai-models/wan22
  diffusion_models: diffusion_models
  text_encoders: text_encoders
  vae: vae
  clip_vision: clip_vision

Windows 路径推荐使用正斜杠，减少 YAML 转义问题。 修改后从启动日志确认新路径被加载。 共享目录设为只读时，自定义节点不能在里面自动下载或改名。

导入官方工作流后先检查缺失节点

工作流 JSON 可能依赖特定 ComfyUI 版本或自定义节点。 看到红色节点时，先记录节点类名。 只从可信仓库安装对应节点，不要让 Manager 批量安装所有搜索结果。 安装后记录仓库 URL 和 commit：

1
2

git -C custom_nodes/<node-directory> remote -v
git -C custom_nodes/<node-directory> rev-parse HEAD

自定义节点拥有执行本机 Python 的权限，应像普通软件一样审查。

第一段视频用低成本参数

先选择模型推荐的较低分辨率。 帧数控制在官方示例范围。 batch size 设为 1。 采样步骤先用示例值，不追求最大。 固定 seed，方便比较配置变化。 提示词描述一个主体、一个动作和简单镜头。 第一轮目标是验证数据流，不是生成最终作品。

文本生成视频的提示词结构 

1
2
3
4

A red bicycle parked beside a quiet lake at sunrise.
Light fog moves slowly above the water.
The camera performs a gentle left-to-right pan.
Natural colors, realistic motion, no text, no watermark.

主体过多会增加一致性难度。 动作、镜头和环境分别说明，比堆叠风格词更容易复现。 如果模型支持负面提示词，把变形、文字和低质量等约束放在对应输入，不要混进主提示词末尾猜语法。

图片生成视频先处理输入画布

输入图片应与目标宽高比接近。 主体不要贴边，给运动留出空间。 透明 PNG 的 alpha 处理取决于工作流，必要时先合成背景。 EXIF 旋转可能让实际像素方向与预览不同。

1
2
3
4
5
6

from PIL import Image, ImageOps

image = Image.open("input.jpg")
image = ImageOps.exif_transpose(image).convert("RGB")
image.save("input-normalized.png")
print(image.size)

规范化后再放进工作流。

显存不足先看峰值发生在哪个阶段

文本编码器阶段 OOM、扩散阶段 OOM 和 VAE 解码阶段 OOM 的处理不同。 查看日志最后一个加载组件。

1

nvidia-smi -l 1

降低分辨率和帧数对激活显存最有效。 启用模型或文本编码器 CPU offload 会增加内存占用。 VAE tiled decode 可以缓解解码峰值，但可能增加接缝或耗时。 不要一遇到 OOM 就同时改五个设置。

Windows 页面文件与系统内存

CPU offload 可能消耗大量 RAM。 系统内存不足时，Windows 会使用页面文件，生成速度可能骤降。 检查任务管理器中的 Commit 和磁盘活动。 页面文件放在空间充足的 SSD，并设置合理上限。 不要在系统盘只剩几 GB 时启动大模型下载和 offload。

CUDA out of memory 后要彻底释放进程

某些失败工作流会保留显存。 停止 ComfyUI 队列不一定释放 Python 进程。

1
2

nvidia-smi
Get-Process python -ErrorAction SilentlyContinue

确认 PID 属于本次 ComfyUI 后再结束进程。 不要杀死其他用户或训练任务的 Python。 重新启动后只改一个参数验证。

No module named 通常是启动环境不一致

确认 ComfyUI 使用的 Python：

1
2

import sys
print(sys.executable)

便携版 ComfyUI 可能带独立 Python。 把依赖安装到系统 Python 不会自动进入便携环境。 使用该环境的 python -m pip install ...，而不是裸 pip。

shape mismatch 多半是模型组件混用

检查 diffusion model、VAE、text encoder 和工作流是否来自同一模型族。 Wan 2.1 的组件不应根据文件名猜测与 Wan 2.2 完全兼容。 量化权重还需要对应 loader 节点。 回到官方工作流与完整精度组件做最小验证，再逐项替换。 不要通过忽略 state dict 错误强行加载视频模型。

黑色视频先排除编码器问题

确认生成的帧是否正常，再判断 MP4 编码。 把帧导出为 PNG 检查。 FFmpeg 不存在或编码器失败时，预览可能为空但推理结果仍在。

1
2

ffmpeg -version
ffprobe -v error -show_streams output.mp4

若 PNG 同样全黑，再检查 VAE、精度和输入范围。

生成速度要按有效帧计算

记录 warm-up 后的第二次运行。 保存模型、分辨率、帧数、步骤、seed、GPU、峰值显存和总耗时。

1

seconds_per_generated_frame = total_seconds / output_frames

首轮包含模型加载，不能直接与已缓存的第二轮比较。 开启 offload 后 GPU 利用率降低并不一定是错误，可能在等待内存传输。

用 ffprobe 验收输出 

1
2
3
4

ffprobe -v error \
  -show_entries stream=codec_name,width,height,r_frame_rate,nb_frames \
  -show_entries format=duration,size \
  -of json output.mp4

确认分辨率、帧率、帧数和时长符合工作流。 浏览器能播放不代表编码参数适合剪辑软件。 需要后期处理时转成明确的 H.264 或中间编码格式。

批量队列要防止磁盘写满

每个视频可能产生预览、临时帧和最终 MP4。 为输出目录设置空间告警。 任务开始前估算最大产物数量。 失败任务的临时目录设置过期清理，但不要在 Python 进程仍使用时删除。 文件名包含 job ID、模型和 seed，避免覆盖。

自定义节点升级采用可回退方式 

1
2
3

git -C custom_nodes/example status --short
git -C custom_nodes/example rev-parse HEAD
git -C custom_nodes/example pull --ff-only

升级前保存工作流 JSON。 新版本失败时回到记录的 commit，而不是随机安装另一个 fork。 ComfyUI 核心、节点和模型三者不要在同一天全部升级。

远程开放 ComfyUI 的风险

ComfyUI 和自定义节点通常不是为无认证公网设计。 默认只监听回环地址。 远程访问使用 VPN 或 SSH 隧道：

1

ssh -L 8188:127.0.0.1:8188 user@gpu-server

不要把 8188 端口直接映射到公网。 上传素材可能含人脸、客户视频和版权内容，远端存储需要访问控制与清理策略。

发布工作流时带上依赖清单

只分享 JSON 不足以复现。 同时记录：

  • ComfyUI commit。
  • 自定义节点仓库与 commit。
  • 模型仓库与文件名。
  • Python、PyTorch 和 CUDA 版本。
  • 分辨率、帧数、步骤和 seed。
  • 是否使用量化与 offload。

不要分享模型文件本身来绕过许可证或访问限制。

更新 Wan 2.2 前保留一次基准

准备固定图片、提示词、seed 和工作流。 升级后生成同样任务，比较峰值显存、耗时、输出尺寸和关键帧。 模型随机性意味着画面不会像像素测试一样完全相同。 重点检查是否能完成、是否出现异常闪烁和动作崩坏。 性能退步时分别回退模型、节点和 PyTorch，定位是哪一层变化。

本地部署完成标准

  • CUDA 在目标虚拟环境可见。
  • 模型任务与工作流类型一致。
  • ComfyUI 能发现所有组件。
  • 第一段低分辨率视频能完成。
  • OOM 阶段和峰值显存有记录。
  • ffprobe 输出参数正确。
  • 自定义节点来源和 commit 可追溯。
  • 远程端口没有直接暴露公网。
  • 固定基准可用于以后升级。

Wan 2.2 的本地部署不是把权重放进一个目录就结束。把模型组件、工作流、显存和媒体输出分别验证，才能区分下载错误、节点不兼容、CUDA 问题与真正的模型能力限制。

项目入口