ComfyUI-WanVideoWrapper 的 WanVideo 视频生成完整指南：从装到出片一次解决 6 个卡点

ComfyUI-WanVideoWrapper 的 WanVideo 视频生成完整指南从装到出片一次解决 6 个卡点【免费下载链接】ComfyUI-WanVideoWrapper项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapperComfyUI-WanVideoWrapper 是 ComfyUI 上的 WanVideo 视频生成节点包覆盖模型加载、采样、显存管理、上下文窗口长视频四类节点内置 HuMo、VACE、ControlNet 等数十种扩展。本文按先跑通、卡住自救的路径走一遍最短路径出片、显存三开关、报错原文速查和两个最小案例。先验证你的显卡带不带得动基线对照表所有数据均取自仓库 readme.md 与 requirements.txt 原文没有实测数据的地方以仓库 README 为准。指标最低要求推荐值依据GPU 显存8GB1.3B 模型 block swap16GB14B 模型README 实测1.3B T2V 生成 1025 帧窗口视频显存低于 5GB14B 跑 512x512x81、offload 20/40 blocks 约 16GBPyTorch任意 CUDA 版 2.7.0nodes_model_loading.py 中WanVideoTorchCompileSettings的 DESCRIPTION 写明 Requires Triton and torch 2.7.0 is recommendedPython 环境跟随 ComfyUI 运行时ComfyUI 自带环境README Installation 一节依赖直接装进 ComfyUI 的 Pythonportable 版用python_embededattention 后端sdpa无需额外安装按需选 flash_attn_2 / sageattnnodes_model_loading.py 第 39-40 行attention_modes列表WanVideoModelLoader默认sdpa依赖版本下限requirements.txt 原文依赖包版本下限用途diffusers0.33.0调度器基础设施accelerate1.2.1显存 offload 机制peft0.17.0LoRA 加载gguf0.17.1GGUF 量化模型支持sentencepiece0.2.0T5 分词ftfy / einops / protobuf / pyloudnorm / opencv-python / scipy无下限文本、音频、图像处理⚠️ 依赖必须装进 ComfyUI 的 Python。装进系统全局 Python 后重启 ComfyUI 仍会报ModuleNotFoundError这是第一高频问题。跑通最短路径从 clone 到第一个 mp4第一步装插件和依赖cd ComfyUI/custom_nodes git clone https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper pip install -r ComfyUI/custom_nodes/ComfyUI-WanVideoWrapper/requirements.txtportableWindows 免安装版用内置 Python路径见 readme.md Installation 一节python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-WanVideoWrapper\requirements.txt应该看到什么clone 后custom_nodes/下多出ComfyUI-WanVideoWrapper目录pip 末尾打印Successfully installed ...。判定标准装完后pip list中上述 5 个带下限的包版本号不低于下限即通过低于下限用pip install --upgrade 包名补齐。入口init.py 的加载规则值得知道nodes、nodes_sampler、nodes_model_loading、nodes_utility、cache_methods五个必需模块任何一个导入失败都会直接抛异常阻断启动其余几十个扩展模块HuMo、FlashVSR、ATI 等失败只打印WanVideoWrapper WARNING: {模块名} nodes not available警告不阻断核心流程。所以某个扩展节点不见了通常是该模块缺依赖不是插件坏掉。第二步四个模型文件放进对应目录目录由 ComfyUI 的folder_paths机制固定readme.md Models 一节放错目录下拉框里选不到模型放置目录备注UMT5 文本编码器ComfyUI/models/text_encodersnodes_model_loading.py 第 1967 行get_filename_list(text_encoders)CLIP visionComfyUI/models/clip_visionI2V 必需nodes_model_loading.py 第 2080 行同时兼容旧式放在 text_encoders 的布局Wan 主模型TransformerComfyUI/models/diffusion_models.safetensors与.gguf均支持VAEComfyUI/models/vae视频解码关于 GGUFnodes_model_loading.py 第 53 行把unet_gguf键挂到diffusion_models目录扫描README 也写明 GGUF models can now be loaded in the main model loader as well。也就是说.gguf量化文件直接放进diffusion_models/WanVideoModelLoader就能选中小显存卡靠量化版省显存。验证文件完整性ls -lh ComfyUI/models/diffusion_models ComfyUI/models/text_encoders应该看到什么主模型 GB 量级、文本编码器数 GB 量级。判定标准0 字节或几十 KB 的文件就是下载中断重下即可别指望运行时才发现问题。README 中作者个人推荐 fp8 scaled 版模型显存占用更低对应仓库地址在 README Models 一节。第三步导入官方示例工作流出第一个视频仓库自带 40 多份可导入工作流按模型规模从小到大起步ls example_workflows | grep 1_3B应该看到什么wanvideo_1_3B_EchoShot_example.json、wanvideo_1_3B_FlashVSR_upscale_example.json等文件名。判定标准把选中的 JSON 拖进画布后每个 loader 节点的下拉框都能选到模型、连线完整无红框即可以 Queue Prompt。预期输出ComfyUI 日志滚动采样进度条结束后ComfyUI/output/出现 mp4。核心节点的默认参数源码可查出问题先对照节点关键参数默认值出处WanVideoModelLoaderbase_precisionbf16、load_deviceoffload_device、attention_modesdpanodes_model_loading.py 第 1084-1090 行WanVideoSamplersteps30、cfg6.0、shift5.0、schedulerunipc、force_offloadTruenodes_sampler.py 第 42-47 行WanVideoImageToVideoEncodewidth832、height480、num_frames81nodes.py 第 989-991 行WanVideoEmptyEmbedsT2Vwidth832、height480、num_frames81nodes.py 第 1415-1417 行load_device的 tooltip 明确提示大模型不要选main_device除非你有 48GB 显存num_frames的步长为 4即帧数必须满足 4n1。显存爆掉时三个 offload 开关和实测数字WanVideoWrapper 提供两种互斥的 offload 机制loadmodel里有 assert两者同时接入会直接报错 Cant use both block_swap_args and vram_management_args at the same time外加一个弥补速度的预取开关开关位置与取值源码/README 依据blocks_to_swapWanVideoBlockSwap默认 20范围 0-4814B 共 40 blocks1.3B/5B 共 30 blocksLongCat 为 48nodes_model_loading.py 第 299 行 tooltipprefetch_blocks默认 0官方建议 1第 306 行 tooltip1 is usually enough to offset speed loss from block swappingoffload_percentWanVideoVRAMManagement默认 1.0范围 0.0-1.0比 block swap 更省显存但更慢第 324-331 行调参流程跑一次用nvidia-smi记录显存峰值再决定 swap 多少 blocks。nvidia-smi应该看到什么采样期间Memory-Usage的占用数字。判定标准峰值距离显卡总显存留出 1-2GB 余量即安全OOM 就调大blocks_to_swap每加 1 个 block 观察一次。两个容易忽略的显存来源未合并的 LoRA。README Update notification 一节说明新版 LoRA 权重以 buffer 形式挂到对应 block 上遵循 block swap但如果你没用 block swapLoRA 会全部常驻显存比旧版更吃显存。README 给了具体算例1GB 未合并 LoRA 14B 模型 swap 20 blocks 时单 block 增大约 25MB总占用多 500MB补偿方法是多 swap 2 个 blocks。GGUF 模型的两个硬限制quantization必须为disabled否则报 Quantization should be disabled when loading GGUF models.且不支持 LoRA merge否则报 GGUF models do not support LoRA merging, please disable merge_loras in the LoRA select node.这两条在 nodes_model_loading.py 第 1132-1137 行可直接查。报错时先查这三处报错原文速查⚠️ 判定优先级先看日志有没有红色 Traceback → 没有再看下拉框缺不缺模型 → 都没有再看是不是运行时 OOM。三处都排查完多数问题就能定位。报错现象或关键字可能原因处理动作WanVideoWrapper WARNING: HuMo nodes not available: No module named xxx模块名随警告变化该可选扩展模块的依赖缺失导入被跳过按警告里的模块名补装对应依赖核心 T2V/I2V 工作流不受影响见init.py 第 62-66 行WARNING: Found 1 other WanVideoWrapper directoriescustom_nodes下存在多份插件拷贝节点可能冲突只保留一份目录删掉其余拷贝后重启 ComfyUI警告来源init.py 第 5 行Cant import SageAttention: ...选了 sageattn 系 attention 模式但没装 sageattention 库改回attention_modesdpa或补装 sageattention来源 nodes_model_loading.py 第 1124-1128 行VAE is required for image encoding./T5 encoder is required for text encoding.I2V/T2V 节点没接 VAE 或 T5 输入在WanVideoImageToVideoEncode/WanVideoTextEncode的 optional 端口接上对应 loader来源 nodes.py 第 310、1023 行start_step must be less than end_step采样起止步数填反或相等交换或重设start_step/end_step来源 wanvideo/schedulers/init.py 第 178 行更新插件后新尺寸首跑显存异常飙高重跑一次就正常旧 triton 编译缓存README 指出主要在 Windows 出现删除C:\Users\username\.triton与C:\Users\username\AppData\Local\Temp\torchinductor_username两个目录内容后重跑README Unrelated other VRAM issue 一节模型代码更新后旧工作流显存变大未合并 LoRA 改为 buffer 挂载不用 block swap 时显存上升接入 WanVideoBlockSwapREADME 给出 500MB 算例见上文两个最小案例说话视频与长视频分段案例一一张图 一段音频出说话人视频输入一张人物图可用仓库自带 example_workflows/example_inputs/human.png和一段音频。关键步骤导入官方示例 example_workflows/wanvideo_2_1_14B_HuMo_example_01.json节点实现在 HuMo/nodes.py确认 HuMo 节点的图像、音频输入已连接音频编码由 HuMo/audio_proj.py 完成工作流内已接好Queue Prompt预期结果输出与音频时长一致的 mp4口型与发音对齐。判定标准视频时长 ≈ 音频时长若口型不同步先查音频采样率与帧率设置不要怀疑模型。案例二1025 帧长视频用上下文窗口分段生成输入1.3B T2V 模型 长 prompt。关键步骤在 nodes.py 的WanVideoContextOptions第 1894 行节点设置分段默认context_frames81、context_stride4、context_overlap16注意 tooltip 提示 latent 空间 4 帧合 1填的是像素帧数把context_options接入WanVideoSampler的context_options端口num_frames直接填 1025分段与融合逻辑在 context_windows/context.py预期结果README Context window test 一节的实测口径——1.3B T2V 模型、窗口 81 帧、重叠 16 帧生成 1025 帧显存低于 5GBRTX 5090 上耗时 10 分钟。判定标准总帧数为 1025 且分段融合处无明显跳变。三条反直觉经验以及下一步往哪走1. 多数人的假设显存不够就降分辨率、减帧数。实际做法先保持完整参数调大blocks_to_swap并把prefetch_blocks设为 1速度损失基本被预取抵消。仓库内的依据README 实测 14B 模型 512x512x81、offload 20/40 blocks 约 16GBnodes_model_loading.py 第 306 行 prefetch 的官方 tooltip。2. 多数人的假设长视频就该把num_frames拉大硬跑。实际做法用上下文窗口分段生成帧数直接填 1025 也不爆显存。仓库内的依据README Context window test 实测 1025 帧 5GBcontext_windows/context.py 的滑动窗口与融合实现。3. 多数人的假设TeaCache 阈值越小跳步越少、结果越稳。实际做法新版阈值是旧版的 10 倍经验区间 0.25-0.30阈值过低反而会跳过早期步、破坏运动连贯性。仓库内的依据README TeaCache 一节明确写 with the new version the threshold values should be 10x higher 和 Range of 0.25-0.30 seems good。至此装环境、放模型、出片、显存调参、报错定位的主干路径已经走完速查表建议留在手边。下一步两个深入方向控制类玩法看 example_workflows/ 里的 VACE、Fun-Control、ReCamMaster 系列工作流想改采样与 VRAM 逻辑读 wanvideo/schedulers/ 与 wanvideo/modules/model.py 的调度器和模型实现。【免费下载链接】ComfyUI-WanVideoWrapper项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考