ComfyUI-WanVideoWrapper开发者指南：节点架构与API设计详解

ComfyUI-WanVideoWrapper开发者指南：节点架构与API设计详解

【免费下载链接】ComfyUI-WanVideoWrapper 项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper

一、核心节点架构解析

ComfyUI-WanVideoWrapper采用模块化节点设计，通过INPUT_TYPES方法定义节点输入参数，实现视频生成流程的灵活组合。以下是关键节点类型及其实现：

1.1 模型管理节点

• WanVideoSetBlockSwap：控制模型块交换逻辑，定义于nodes.py

  @classmethod
  def INPUT_TYPES(s):
      return {
          "required": {"model": ("WANVIDEOMODEL",)},
          "optional": {"block_swap_args": ("BLOCKSWAPARGS",)}
      }
  

• WanVideoLoadModel：加载不同精度模型，支持量化配置，定义于nodes_model_loading.py

1.2 文本编码节点

• WanVideoTextEncodeCached：带缓存机制的文本编码器，支持提示词扩展与权重解析，定义于nodes.py

  @classmethod
  def INPUT_TYPES(s):
      return {
          "required": {
              "model_name": (folder_paths.get_filename_list("text_encoders"),),
              "positive_prompt": ("STRING", {"multiline": True}),
              "negative_prompt": ("STRING", {"multiline": True}),
              # 量化与设备配置参数
          }
      }
  

1.3 采样器节点

• WanVideoSampler：实现视频扩散采样，支持多种调度器与注意力模式，定义于nodes_sampler.py

  def process(self, model, image_embeds, shift, steps, cfg, seed, scheduler, ...):
      # 实现带CFG的扩散采样逻辑
      for i in range(steps):
          noise_pred = model.apply_model(...)
          sample = scheduler.step(noise_pred, timestep, sample)
  

二、API设计模式

2.1 节点通信协议

节点间通过类型化数据传输，核心数据类型包括：

• WANVIDEOMODEL：封装视频生成模型及其配置
• WANVIDEOTEXTEMBEDS：文本嵌入容器，包含正负提示词编码
• FETAARGS：增强视频参数，定义于nodes.py

2.2 内存管理接口

• set_module_tensor_to_device：安全迁移模型参数至指定设备，定义于utils.py

  def set_module_tensor_to_device(module, tensor_name, device, value=None, dtype=None):
      # 递归解析参数路径并迁移设备
      if "." in tensor_name:
          splits = tensor_name.split(".")
          module = getattr(module, splits[0])
          tensor_name = ".".join(splits[1:])
      # 设置参数或缓冲区
      if tensor_name in module._parameters:
          module._parameters[tensor_name] = new_param
  

• apply_lora：低内存LoRA应用实现，支持权重缩放与设备调度，定义于utils.py

三、关键技术实现

3.1 径向注意力机制

通过MaskMap实现时空注意力掩码，优化长视频生成性能：

# [wanvideo/radial_attention/attn_mask.py](https://link.gitcode.com/i/8fe8cd6bf98cf2695169069132bb28ad)
def __init__(self, video_token_num=25440, num_frame=16, block_size=128):
    self.mask_map = self.queryLogMask(video_token_num, "radial", block_size)

在utils.py中通过setup_radial_attention完成注意力配置。

3.2 提示词权重解析

支持(text:weight)格式的提示词加权，实现于nodes.py：

def parse_prompt_weights(self, prompt):
    # 解析带权重的提示词
    pattern = r'\((.*?):([\d\.]+)\)'
    matches = re.findall(pattern, prompt)
    for text, weight in matches:
        cleaned_prompt = prompt.replace(f"({text}:{weight})", text)
        weights[text] = float(weight)

四、工作流组合示例

4.1 基础视频生成流程

4.2 关键节点配置代码

# 文本编码节点配置
text_embeds = WanVideoTextEncodeCached().process(
    model_name="t5-xxl",
    positive_prompt="a cat running in the grass",
    use_disk_cache=True
)

# 采样器参数配置
sampler_args = {
    "steps": 20,
    "cfg": 7.0,
    "scheduler": "flowmatch",
    "rope_function": "riflex"
}

五、性能优化策略

5.1 内存优化

• 实现块级量化加载：gguf/gguf.py
• 动态设备调度：utils.py的set_module_tensor_to_device

5.2 计算效率

• 选择性编译：utils.py的compile_model支持模块级编译
• 注意力分块：nodes_sampler.py实现块级交叉注意力

六、扩展开发指南

6.1 自定义节点开发

1. 继承基础节点类并实现INPUT_TYPES和process方法
2. 注册节点类别：CATEGORY = "WanVideoWrapper/Extensions"
3. 示例：ATI/nodes.py的动作捕捉节点

6.2 模型适配接口

• 实现apply_lora兼容的权重注入：custom_linear.py
• 扩展注意力模式：参考radial_attention/sparse_int8_attn.py

七、API参考文档

核心模块路径

• 节点定义：nodes.py、nodes_sampler.py
• 工具函数：utils.py
• 模型架构：wanvideo/model.py
• 调度器：wanvideo/schedulers/

数据类型参考

类型标识	描述	关联节点
WANVIDEOMODEL	视频模型容器	模型加载/配置节点
WANVIDEOTEXTEMBEDS	文本嵌入数据	文本编码节点
FETAARGS	增强视频参数	WanVideoEnhanceAVideo

八、常见问题解决

8.1 尺寸兼容性

径向注意力要求特定分辨率，可通过utils.py的find_closest_valid_dim计算兼容尺寸：

# 查找最近的有效分辨率
valid_width = find_closest_valid_dim(fixed_dim=height, var_dim=width, block_size=128)

8.2 内存溢出

• 降低block_size参数（最小64）
• 启用FP8量化：fp8_optimization.py
• 增加dense_blocks数量减少注意力计算量

九、版本迁移指南

9.0→9.1版本变更

• WANVideoClipVisionEncode节点参数重命名：image→image_1
• 注意力掩码配置迁移至MaskMap类：wanvideo/radial_attention/attn_mask.py

十、开发资源

• 示例工作流：example_workflows/
• 测试素材：example_workflows/example_inputs/
• 性能基准：utils.py的print_memory工具

通过以上架构解析与API指南，开发者可快速掌握WanVideoWrapper的扩展开发与性能优化方法，构建定制化视频生成工作流。

【免费下载链接】ComfyUI-WanVideoWrapper 项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-WanVideoWrapper