ComfyUI-SeedVR2_VideoUpscaler

SeedVR2 的官方 ComfyUI 版本，可实现高质量视频和图像 upscale。

也可作为多 GPU 独立 CLI 运行，详见🖥️ 作为独立程序运行部分。

📋 快速访问

• 🆙 未来版本
• 🚀 更新日志
• 🎯 功能特点
• 🔧 系统要求
• 📦 安装步骤
• 📖 使用指南
• 🖥️ 作为独立程序运行
• ⚠️ 局限性
• 🤝 贡献指南
• 🙏 致谢
• 📜 许可证

🆙 未来版本

我们正在积极开发改进和新功能。如需了解最新动态：

• 📌 跟踪开发进度：访问 Issues 查看活跃开发内容、报告错误并请求新功能
• 💬 加入社区：在 Discussions 中向他人学习、分享工作流程并获取帮助
• 🔮 下一代模型调查：我们正在征求社区对下一代开源超强通用修复模型的意见。请在 Issue #164 中分享您的建议

🚀 更新日志

2025.11.09 - 版本 2.5.5

• 💾 内存：修复长视频的内存泄漏问题 - 通过轻量级批次索引实现按需重建，而非存储完整的转换视频；修复 release_tensor_memory 以一致处理 CPU/CUDA/MPS；重构批次处理辅助工具

2025.11.08 - 版本 2.5.4

• 🎨 修复：AdaIN 色彩校正 - 将 .view() 替换为 .reshape()，以处理空间填充后非连续的张量，解决"视图大小与输入张量的大小和步幅不兼容"错误
• 🔴 修复：AMD ROCm 兼容性 - 在 Conv3d workaround 中添加 cuDNN 可用性检查，防止 ROCm 系统（Windows/Linux 上的 AMD GPU）出现"ATen 未使用 cuDNN 支持编译"错误

2025.11.08 - 版本 2.5.3

• 🍎 修复：Apple Silicon MPS 设备处理 - 修正 MPS 设备枚举，使用 "mps" 而非 "mps:0"，解决 M 系列 Mac 上的无效设备错误
• 🪟 修复：Windows 上的 torch.mps 属性错误 - 添加对 torch.mps.is_available() 的防御性检查，以处理非 Mac 平台上 PyTorch 版本中该方法不存在的情况

2025.11.07 - 版本 2.5.0 🎉

⚠️ 重大变更：这是一个需要重新创建工作流程的重大更新。所有节点和 CLI 参数都经过重新设计，以提高可用性和一致性。观看 AInVFX 的最新视频深入了解，并查看使用指南部分。

📦 正式发布：现已在主分支上提供，支持 ComfyUI Manager，便于安装和自动版本跟踪。更新的依赖项和本地导入可防止与其他 ComfyUI 自定义节点发生冲突。

🎨 ComfyUI 改进

• 四节点模块化架构：拆分为 DiT 模型、VAE 模型、torch.compile 设置和主 upscale 器专用节点，实现精细化控制
• 全局模型缓存：模型现在可跨多个 upscale 器实例共享，并自动更新配置 - 不再需要重复加载
• ComfyUI V3 迁移：完全兼容 ComfyUI V3 无状态节点设计
• RGBA 支持：原生 alpha 通道处理，结合边缘引导 upscale 技术，实现清晰透明效果
• 改进的内存管理：流式架构可防止 VRAM 峰值，不受视频长度影响
• 灵活的分辨率支持：采用无损填充方法（替代限制性裁剪），可 upscale 至任何能被 2 整除的分辨率
• 增强的参数设置：新增 uniform_batch_size、temporal_overlap、prepend_frames 和 max_resolution，提供更好的控制能力

🖥️ CLI 增强功能

• 批量目录处理：处理整个文件夹的视频/图像，并通过模型缓存提高效率
• 单图像支持：直接进行图像 upscale，无需视频转换
• 智能输出检测：根据输入类型自动检测输出格式（MP4/PNG）
• 增强的多 GPU 支持：改进工作负载分配，采用时间重叠混合技术
• 统一参数：CLI 和 ComfyUI 现在使用完全相同的参数名称，确保一致性
• 更优用户体验：自动显示帮助信息、改进验证机制、进度跟踪和更清晰的输出

⚡ 性能与优化

• torch.compile 支持：通过全图编译实现 DiT 速度提升 20-40%，VAE 速度提升 15-25%
• 优化的 BlockSwap：自适应内存清理（5% 阈值）、独立 I/O 组件处理、降低开销
• 增强的 VAE 分块处理：支持累积缓冲区的张量卸载，独立的编码/解码配置
• 原生数据类型管道：消除不必要的转换，全程保持 bfloat16 精度，兼顾速度与质量
• 优化的张量操作：用原生 PyTorch 操作替代 einops rearrange，实现 2-5 倍更快的转换

🎯 质量改进

• LAB 色彩校正：全新感知色彩迁移方法，色彩准确度更高（现已设为默认）
• 更多色彩处理方式：HSV 饱和度匹配、小波自适应及混合方法
• 确定性生成：基于种子的可复现性，采用特定阶段种子策略
• 更佳时间一致性：Hann 窗口融合技术，实现批次间平滑过渡

💾 内存管理

• 智能卸载：DiT、VAE 和张量可独立配置设备（CPU/GPU/无）
• 四阶段流水线：完成所有批次的每个阶段（编码→ upscale→解码→后处理）后再进入下一阶段，最大限度减少模型切换
• 优化清理机制：特定阶段资源管理，确保张量内存正确释放
• 峰值 VRAM 跟踪：分阶段内存监控并显示摘要

🔧 技术改进

• GGUF 量化支持：全面支持 GGUF，实现低 VRAM 系统上的 4 位/8 位推理
• 改进 GGUF 处理：修复 VRAM 泄漏问题，支持 torch.compile，优化非持久缓冲区
• Apple Silicon 支持：全面支持 Apple Silicon Mac 的 MPS（Metal 性能着色器）
• AMD ROCm 兼容性：为 PyTorch ROCm 7+ 支持添加条件性 FSDP 导入
• Conv3d 内存问题解决：修复 PyTorch 2.9+ cuDNN 内存 bug（减少 3 倍内存占用）
• 可选 Flash Attention：当 flash-attn 不可用时，可平稳回退至 SDPA

📚 代码质量

• 模块化架构：将单体文件拆分为专注的模块（generation_phases、model_configuration 等）
• 全面文档：所有模块均配有详细的文档字符串和类型提示
• 优化错误处理：早期验证、清晰错误消息及安装说明
• 统一日志记录：统一缩进格式，优化分类，消息简洁明了

2025.08.07

• 🎯 统一调试系统：全新结构化日志，包含分类、计时器和内存跟踪功能。主节点现已支持 enable_debug
• ⚡ 智能 FP8 优化：FP8 模型现在保持原生 FP8 存储，仅在进行算术运算时转换为 BFloat16——比 FP16 更快、内存效率更高
• 📦 模型注册表：多仓库支持（numz/ 及 AInVFX/），用户模型自动发现，添加混合 FP8 变体以修复 7B 模型的伪影问题
• 💾 模型缓存：cache_model 已移至主节点，通过优化 RoPE/包装器清理修复内存泄漏
• 🧹 代码清理：全新模块化结构（constants.py、model_registry.py、debug.py），移除遗留代码

2025.07.17

• 🛠️ 添加 7B 锐化模型：新增 2 个 7B 模型，输出效果更清晰

2025.07.11

• 🎬 完整教程发布：来自 AInVFX 的 Adrien 制作了一份深入的 ComfyUI SeedVR2 指南，涵盖从基本设置到在消费级 GPU 上运行的高级 BlockSwap 技术的所有内容。非常适合理解内存优化和带 alpha 通道的图像序列 upscale！观看教程

2025.09.07

• 🛠️ Blockswap 集成：特别感谢来自 AInVFX 的 Adrien Toupet！此功能对低 VRAM 用户非常有用（参见 使用方法 部分）

2025.07.03

• 🛠️ 可以 独立模式 运行，并支持 多 GPU，参见 🖥️ 独立运行

2025.06.30

• 🚀 加快处理速度，减少 VRAM 占用
• 🛠️ 修复 3B 模型的内存泄漏问题
• ❌ 现在可在需要时中断进程
• ✅ 重构代码以便更好地与社区共享，欢迎提交拉取请求
• 🛠️ 移除 flash attention 依赖（感谢 luke2642！！）

2025.06.24

• 🚀 处理速度提升最高达 4 倍

2025.06.22

• 💪 支持 FP8 兼容性！
• 🚀 加快所有处理流程
• 🚀 减少 VRAM 消耗（RTX4090 最多仍建议 batch_size=1，正在努力优化）
• 🛠️ 更完善的基准测试即将推出

2025.06.20

• 🛠️ 初始提交

🎯 功能特点

核心能力

• 高质量扩散型超分辨率：单步扩散模型，用于视频和图像增强
• 时间一致性：通过可配置的批量处理，保持视频帧间的连贯性
• 多格式支持：处理视频和图像的RGB及RGBA（alpha通道）格式
• 任意视频长度：适用于任何长度的视频

模型支持

• 多种模型变体：3B和7B参数模型，提供不同精度选项
• FP16、FP8和GGUF量化：根据不同显存需求，可选择全精度（FP16）、混合精度（FP8）或高度量化的GGUF模型
• 模型自动下载：首次使用时从HuggingFace自动下载模型

内存优化

• BlockSwap技术：动态在GPU和CPU内存之间交换 transformer 块，使大模型能在有限显存上运行
• VAE分块处理：通过分块编码/解码处理大分辨率，降低显存占用
• 智能卸载：在处理阶段之间将模型和中间张量卸载到CPU或辅助GPU
• GGUF量化支持：采用4位或8位量化运行模型，实现极致显存节省

性能特性

• torch.compile集成：使用PyTorch 2.0+编译，可选择性提升DiT速度20-40%、VAE速度15-25%
• 多GPU命令行界面：跨多个GPU分配工作负载，并带有自动时间重叠融合
• 模型缓存：将模型保持加载在内存中，以加快批量处理速度
• 灵活的注意力后端：可选择PyTorch SDPA（稳定，始终可用）或Flash Attention 2（在支持的硬件上速度更快）

质量控制

• 高级色彩校正：五种方法，包括LAB（推荐用于最高保真度）、小波、自适应小波、HSV和AdaIN
• 噪声注入控制：微调输入和潜在噪声尺度，以减少高分辨率下的伪影
• 可配置的分辨率限制：设置目标分辨率和最大分辨率，并自动保持宽高比

工作流特性

• ComfyUI 集成：四个专用节点，可完全控制 upscale 处理流程
• 独立 CLI：命令行界面，支持批量处理和自动化操作
• 调试日志：全面的调试模式，包含内存跟踪、计时信息和处理详情
• 进度报告：处理过程中的实时进度更新

🔧 系统要求

硬件

借助当前的优化（分块处理、BlockSwap、GGUF 量化），SeedVR2 可在多种硬件上运行：

• 最低显存（8GB 及以下）：使用 GGUF Q4_K_M 模型，并启用 BlockSwap 和 VAE 分块处理
• 中等显存（12-16GB）：使用 FP8 模型，根据需要启用 BlockSwap 或 VAE 分块处理
• 高显存（24GB+）：使用 FP16 模型，可获得最佳质量和速度，无需内存优化

软件

• ComfyUI：建议使用最新版本
• Python：3.12+（已测试并推荐 Python 3.12 和 3.13）
• PyTorch：2.0+（支持 torch.compile，可选但推荐）
• Triton：使用 inductor 后端进行 torch.compile 时必需（可选）
• Flash Attention 2：在支持的硬件上提供更快的注意力计算（可选，默认回退到 PyTorch SDPA）

📦 安装方法

选项 1：ComfyUI Manager（推荐）

1. 在 ComfyUI 界面中打开 ComfyUI Manager
2. 点击“Custom Nodes Manager”
3. 搜索“ComfyUI-SeedVR2_VideoUpscaler”
4. 点击“Install”并重启 ComfyUI

注册表链接：ComfyUI Registry - SeedVR2 Video Upscaler

选项 2：手动安装

1. 克隆仓库到您的 ComfyUI 自定义节点目录：

cd ComfyUI
git clone https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler.git custom_nodes/seedvr2_videoupscaler

1. 使用独立 Python 安装依赖项：

# Install requirements (from same ComfyUI directory)
# Windows:
.venv\Scripts\python.exe -m pip install -r custom_nodes\seedvr2_videoupscaler\requirements.txt
# Linux/macOS:
.venv/bin/python -m pip install -r custom_nodes/seedvr2_videoupscaler/requirements.txt

1. 重启 ComfyUI

模型安装

首次使用时，模型将自动下载并保存至 ComfyUI/models/SEEDVR2。

您也可以手动下载模型：

• 主模型可在 numz/SeedVR2_comfyUI 和 AInVFX/SeedVR2_comfyUI 获取
• 额外的 GGUF 模型可在 cmeka/SeedVR2-GGUF 获取

📖 使用指南

🎬 视频教程

最新版本深度解析（推荐）

AInVFX 的 Adrien 制作的 2.5 版本完整教程，涵盖全新的 4 节点架构、GGUF 支持、内存优化及生产工作流：

本综合教程内容包括：

• 通过 ComfyUI Manager 安装 v2.5 及冲突排查
• 理解全新的 4 节点模块化架构及其重构原因
• 使用 GGUF 量化技术在 8GB VRAM 上运行 7B 模型
• 针对硬件配置 BlockSwap、VAE 分块处理和 torch.compile
• 支持 alpha 通道的图像与视频放大工作流
• 用于批量处理和多 GPU 渲染的 CLI
• 不同 VRAM 水平的内存优化策略
• 实际生产技巧及关键的 batch_size 公式（4n+1）

旧版本教程

作为参考，以下是涵盖初始版本的原始教程：

注：本教程介绍的是旧版单节点架构。尽管 v2.5 的界面发生了显著变化，但关于 BlockSwap 和内存管理的核心概念仍然具有参考价值。

节点设置

SeedVR2 采用模块化节点架构，包含四个专用节点：

1. SeedVR2 (Down)Load DiT Model

配置用于视频放大的 DiT（扩散Transformer）模型。

参数：

• model：选择 DiT 模型

  • 3B 模型：速度更快，VRAM 需求更低
    • seedvr2_ema_3b_fp16.safetensors：FP16（最佳质量）
    • seedvr2_ema_3b_fp8_e4m3fn.safetensors：FP8 8 位（良好质量）
    • seedvr2_ema_3b-Q4_K_M.gguf：GGUF 4 位量化（可接受质量）
    • seedvr2_ema_3b-Q8_0.gguf：GGUF 8 位量化（良好质量）
  • 7B 模型：质量更高，VRAM 需求更高
    • seedvr2_ema_7b_fp16.safetensors：FP16（最佳质量）
    • seedvr2_ema_7b_fp8_e4m3fn_mixed_block35_fp16.safetensors：FP8 格式，最后一个块采用 FP16 以减少伪影（良好质量）
    • seedvr2_ema_7b-Q4_K_M.gguf：GGUF 4 位量化（可接受质量）
    • seedvr2_ema_7b_sharp_*：Sharp 变体，增强细节表现

• device：DiT 推理使用的 GPU 设备（例如 cuda:0）

• offload_device：非活动处理时模型卸载的目标设备

  • none：保持模型在推理设备上（速度最快，VRAM 占用最高）
  • cpu：卸载到系统内存（减少 VRAM 占用）
  • cuda:X：卸载到另一块 GPU（如有可用，平衡效果好）

• cache_model：在工作流运行期间保持 DiT 模型加载在 offload_device 上

  • 对批量处理有用，避免重复加载
  • 需要设置 offload_device

• blocks_to_swap：BlockSwap 内存优化

  • 0：禁用（默认）
  • 1-32：3B 模型可交换的 Transformer 块数量
  • 1-36：7B 模型可交换的 Transformer 块数量
  • 值越高 = VRAM 节省越多但处理速度越慢
  • 需要设置 offload_device 且与 device 不同

• swap_io_components：卸载输入/输出嵌入和归一化层

  • 与 blocks_to_swap 结合使用可额外节省 VRAM
  • 需要设置 offload_device 且与 device 不同

• attention_mode：注意力计算后端

  • sdpa：PyTorch scaled_dot_product_attention（默认，稳定，始终可用）
  • flash_attn：Flash Attention 2（在支持的硬件上更快，需要安装 flash-attn 包）

• torch_compile_args：连接到 SeedVR2 Torch Compile Settings 节点可提升 20-40% 速度

BlockSwap 详解：

BlockSwap 通过在推理过程中动态地在 GPU 和 CPU 内存之间交换 Transformer 块，使大型模型能够在 VRAM 有限的 GPU 上运行。其工作原理如下：

• 功能：只在 GPU 上保留当前需要的 Transformer 块，其余块存储在 CPU 或其他设备上
• 使用场景：放大阶段出现 OOM（内存不足）错误时
• 配置方法：
  1. 将 offload_device 设置为 cpu 或另一块 GPU
  2. 初始设置 blocks_to_swap=16（一半的块）
  3. 如果仍出现 OOM，增加至 24 或 32（3B 模型）/ 36（7B 模型）
  4. 启用 swap_io_components 以获得最大 VRAM 节省
  5. 如果 VRAM 充足，减少或设为 0 以加快处理速度

低 VRAM（8GB）示例配置：

• model: seedvr2_ema_3b-Q8_0.gguf
• device: cuda:0
• offload_device: cpu
• blocks_to_swap: 32
• swap_io_components: True

2. SeedVR2 (Down)Load VAE Model

配置用于视频帧编码/解码的 VAE（变分自编码器）模型。

参数：

• model：VAE 模型选择

  • ema_vae_fp16.safetensors：默认且推荐

• device：VAE 推理使用的 GPU 设备（例如 cuda:0）

• offload_device：非活动处理时模型卸载的目标设备

  • none：保持模型在推理设备上（默认，速度最快）
  • cpu：卸载到系统内存（减少 VRAM 占用）
  • cuda:X：卸载到另一块 GPU（如有可用，平衡效果好）

• cache_model：在工作流运行期间保持 VAE 模型加载在 offload_device 上

  • 需要设置 offload_device

• encode_tiled：启用分块编码以减少编码阶段的 VRAM 使用

  • 如果在调试日志的"Encoding"阶段看到 OOM 错误，启用此项

• encode_tile_size：编码分块大小（像素）（默认：1024）

  • 同时应用于高度和宽度
  • 值越低 VRAM 占用越少，但可能增加处理时间

• encode_tile_overlap：编码分块重叠区域（像素）（默认：128）

  • 减少分块之间的可见接缝

• decode_tiled：启用分块解码以减少解码阶段的 VRAM 使用

  • 如果在调试日志的"Decoding"阶段看到 OOM 错误，启用此项

• decode_tile_size：解码分块大小（像素）（默认：1024）

• decode_tile_overlap：解码分块重叠区域（像素）（默认：128）

• torch_compile_args：连接到 SeedVR2 Torch Compile Settings 节点可提升 15-25% 速度

VAE 分块处理详解：

VAE 分块处理将高分辨率图像分割为较小的分块进行处理，以降低 VRAM 需求。使用方法如下：

1. 先禁用分块运行，并监控调试日志（在主节点启用 enable_debug）
2. 如果在"Encoding"阶段 OOM：
   • 启用 encode_tiled
   • 如果仍然 OOM，减小 encode_tile_size（尝试 768、512 等）
3. 如果在"Decoding"阶段 OOM：
   • 启用 decode_tiled
   • 如果仍然 OOM，减小 decode_tile_size
4. 调整重叠区域（默认 128）：
   • 如分块间出现可见接缝，增加重叠值
   • 如处理时间过长，减少重叠值

高分辨率（4K）示例配置：

• encode_tiled: True
• encode_tile_size: 1024
• encode_tile_overlap: 128
• decode_tiled: True
• decode_tile_size: 1024
• decode_tile_overlap: 128

3. SeedVR2 Torch Compile Settings（可选）

配置 torch.compile 优化，可提升 DiT 20-40% 速度和 VAE 15-25% 速度。

要求：

• PyTorch 2.0+
• Triton（用于 inductor 后端）

参数：

• backend：编译后端

  • inductor：使用 Triton 内核生成和融合的全面优化（推荐）
  • cudagraphs：使用 CUDA 图的轻量级包装，无内核优化

• mode：优化级别（编译时间 vs 运行时性能）

  • default：编译速度快，加速效果好（推荐用于开发）
  • reduce-overhead：低开销，针对小型模型优化
  • max-autotune：编译最慢，运行时性能最佳（推荐用于生产）
  • max-autotune-no-cudagraphs：类似 max-autotune，但不使用 CUDA 图

• fullgraph：将整个模型编译为单个无中断图

  • False：允许图中断以获得更好的兼容性（默认，推荐）
  • True：强制无中断以获得最大优化（可能在动态形状下失败）

• dynamic：处理变化的输入形状而无需重新编译

  • False：针对精确输入形状优化（默认）
  • True：创建适应形状变化的动态内核（处理不同分辨率或批量大小时启用）

• dynamo_cache_size_limit：每个函数的最大缓存编译版本数（默认：64）

  • 越高 = 内存占用越多，越低 = 重新编译越多

• dynamo_recompile_limit：回退到 eager 模式前的最大重新编译尝试次数（默认：128）

  • 防止编译循环的安全限制

使用方法：

1. 将此节点添加到工作流
2. 将其输出连接到 DiT 和/或 VAE 加载器节点的 torch_compile_args 输入
3. 首次运行会较慢（编译过程），后续运行将显著加快

适用场景：

• torch.compile 仅在处理多个批次、长视频或大量分块时才有意义
• 对于单张图像或短视频，编译时间会超过加速收益
• 最适合批量处理工作流或长视频

推荐设置：

• 开发/测试：mode=default，backend=inductor，fullgraph=False
• 生产环境：mode=max-autotune，backend=inductor，fullgraph=False

4. SeedVR2 Video Upscaler（主节点）

使用 DiT 和 VAE 模型处理视频帧的主放大节点。

必需输入：

• image：输入视频帧，格式为图像批次（RGB 或 RGBA）
• dit：来自 SeedVR2 (Down)Load DiT Model 节点的 DiT 模型配置
• vae：来自 SeedVR2 (Down)Load VAE Model 节点的 VAE 模型配置

参数：

• seed：用于可重现生成的随机种子（默认：42）

  • 相同种子和相同输入将产生完全相同的输出

• resolution：目标分辨率，指最短边的像素数（默认：1080）

  • 自动保持宽高比

• max_resolution：任意边的最大分辨率（默认：0 = 无限制）

  • 如超过限制将自动缩小，防止 OOM

• batch_size：每批处理的帧数（默认：5）

  • 关键要求：必须遵循4n+1 公式（1、5、9、13、17、21、25...）
  • 重要性：模型使用这些帧进行时间一致性计算
  • 至少 5 帧以保证时间一致性：仅在处理单张图像或不需要时间一致性时使用 1
  • 理想匹配镜头长度：为获得最佳效果，将 batch_size 设置为与镜头长度匹配（例如 20 帧镜头使用 batch_size=21）
  • VRAM 影响：batch_size 越大 = 质量和速度越好，但需要更多 VRAM
  • 如果 batch_size=5 时出现 OOM：首先尝试优化技术（模型卸载、BlockSwap、GGUF 模型...），再考虑减小 batch_size 或输入分辨率，因为这些会直接影响质量

uniform_batch_size（默认：False）

• 将最后一个批次填充至 batch_size 以实现统一处理

  • 当最后一个批次远小于其他批次时，防止时间伪影
  • 示例：45 帧，batch_size=33 时，处理为 [33, 33] 而非 [33, 12]
  • 当使用大 batch_size 且视频长度不是 batch_size 的倍数时推荐启用
  • 略微增加 VRAM 占用，但确保所有批次间时间一致性

• temporal_overlap：批次间的重叠帧数（默认：0）

  • 用于批次间混合，减少时间伪影
  • 范围：0-16 帧

• prepend_frames：前置帧数（默认：0）

  • 前置反转帧以减少视频开头的伪影
  • 处理后自动移除
  • 范围：0-32 帧

• color_correction：色彩校正方法（默认："wavelet"）

  • lab：完全感知色彩匹配，保留细节（推荐用于最高保真度）
  • wavelet：基于频率的自然色彩，良好保留细节
  • wavelet_adaptive：小波基础 + 目标饱和度校正
  • hsv：基于色调的饱和度匹配
  • adain：统计风格迁移
  • none：无色彩校正

• input_noise_scale：输入噪声注入强度 0.0-1.0（默认：0.0）

  • 向输入帧添加噪声以减少超高分辨率下的伪影
  • 如在高输出分辨率下看到伪影，尝试 0.1-0.3

• latent_noise_scale： latent 空间噪声强度 0.0-1.0（默认：0.0）

  • 在扩散过程中添加噪声，可柔化过度细节
  • 如 input_noise 无效，尝试 0.05-0.15

• offload_device：处理阶段之间存储中间张量的设备（默认："cpu"）

  • none：所有张量保持在推理设备上（最快但 VRAM 占用最高）
  • cpu：卸载到系统内存（推荐用于长视频，传输较慢）
  • cuda:X：卸载到另一块 GPU（如有可用，平衡效果好，比 CPU 快）

• enable_debug：启用详细调试日志（默认：False）

  • 显示内存使用、时间信息和处理详情
  • 强烈推荐用于排查 OOM 问题

输出：

• 应用色彩校正后的放大视频帧
• 格式（RGB/RGBA）与输入匹配
• 范围 [0, 1] 归一化，兼容 ComfyUI

典型工作流程设置

基础工作流程（高显存 - 24GB+）：

Load Video Frames
    ↓
SeedVR2 Load DiT Model
  ├─ model: seedvr2_ema_3b_fp16.safetensors
  └─ device: cuda:0
    ↓
SeedVR2 Load VAE Model
  ├─ model: ema_vae_fp16.safetensors
  └─ device: cuda:0
    ↓
SeedVR2 Video Upscaler
  ├─ batch_size: 21
  └─ resolution: 1080
    ↓
Save Video/Frames

低显存工作流（8-12GB）：

Load Video Frames
    ↓
SeedVR2 Load DiT Model
  ├─ model: seedvr2_ema_3b-Q8_0.gguf
  ├─ device: cuda:0
  ├─ offload_device: cpu
  ├─ blocks_to_swap: 32
  └─ swap_io_components: True
    ↓
SeedVR2 Load VAE Model
  ├─ model: ema_vae_fp16.safetensors
  ├─ device: cuda:0
  ├─ encode_tiled: True
  └─ decode_tiled: True
    ↓
SeedVR2 Video Upscaler
  ├─ batch_size: 5
  └─ resolution: 720
    ↓
Save Video/Frames

高性能工作流（24GB+ 显存支持 torch.compile）：

Load Video Frames
    ↓
SeedVR2 Torch Compile Settings
  ├─ mode: max-autotune
  └─ backend: inductor
    ↓
SeedVR2 Load DiT Model
  ├─ model: seedvr2_ema_7b_sharp_fp16.safetensors
  ├─ device: cuda:0
  └─ torch_compile_args: connected
    ↓
SeedVR2 Load VAE Model
  ├─ model: ema_vae_fp16.safetensors
  ├─ device: cuda:0
  └─ torch_compile_args: connected
    ↓
SeedVR2 Video Upscaler
  ├─ batch_size: 81
  └─ resolution: 1080
    ↓
Save Video/Frames

🖥️ 独立运行（CLI）

独立 CLI 提供强大的批处理功能，支持多 GPU 并具备复杂的优化选项。

前提条件

根据您的安装情况选择合适的设置：

选项 1：已安装带有 SeedVR2 的 ComfyUI

如果您已通过 ComfyUI 安装 将 SeedVR2 作为 ComfyUI 的一部分安装，可直接使用 CLI：

# Navigate to your ComfyUI directory
cd ComfyUI

# Run the CLI using standalone Python (display help message)
# Windows:
.venv\Scripts\python.exe custom_nodes\seedvr2_videoupscaler\inference_cli.py --help
# Linux/macOS:
.venv/bin/python custom_nodes/seedvr2_videoupscaler/inference_cli.py --help

跳至下方的命令行用法。

选项 2：独立安装（无需 ComfyUI）

如果您希望在不安装 ComfyUI 的情况下使用 CLI，请按照以下步骤操作：

1. 安装 uv（现代 Python 包管理器）：

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

1. 克隆仓库：

git clone https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler.git seedvr2_videoupscaler
cd seedvr2_videoupscaler

1. 创建虚拟环境并安装依赖项：

# Create virtual environment with Python 3.13
uv venv --python 3.13

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# Install PyTorch with CUDA support
# Check command line based on your environment: https://pytorch.org/get-started/locally/
uv pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu130

# Install SeedVR2 requirements
uv pip install -r requirements.txt

# Run the CLI (display help message)
# Windows:
.venv\Scripts\python.exe inference_cli.py --help
# Linux/macOS:
.venv/bin/python inference_cli.py --help

命令行使用方法

命令行界面（CLI）为单GPU、多GPU和批量处理工作流提供了全面的选项。

基本使用示例：

# Basic image upscaling
python inference_cli.py image.jpg

# Basic video video upscaling with temporal consistency
python inference_cli.py video.mp4 --resolution 720 --batch_size 33

# Multi-GPU processing with temporal overlap
python inference_cli.py video.mp4 \
    --cuda_device 0,1 \
    --resolution 1080 \
    --batch_size 81 \
    --uniform_batch_size \
    --temporal_overlap 3 \
    --prepend_frames 4

# Memory-optimized for low VRAM (8GB)
python inference_cli.py image.png \
    --dit_model seedvr2_ema_3b-Q8_0.gguf \
    --resolution 1080 \
    --blocks_to_swap 32 \
    --swap_io_components \
    --dit_offload_device cpu \
    --vae_offload_device cpu

# High resolution with VAE tiling
python inference_cli.py video.mp4 \
    --resolution 1440 \
    --batch_size 31 \
    --uniform_batch_size \
    --temporal_overlap 3 \
    --vae_encode_tiled \
    --vae_decode_tiled

# Batch directory processing with model caching
python inference_cli.py media_folder/ \
    --output processed/ \
    --cuda_device 0 \
    --cache_dit \
    --cache_vae \
    --dit_offload_device cpu \
    --vae_offload_device cpu \
    --resolution 1080 \
    --max_resolution 1920

命令行参数

输入/输出：

• <input>：输入文件（.mp4、.avi、.png、.jpg 等）或目录
• --output：输出路径（默认：在 'output/' 目录中自动生成）
• --output_format：输出格式：'mp4'（视频）或 'png'（图像序列）。默认：根据输入类型自动检测
• --model_dir：模型目录（默认：./models/SEEDVR2）

模型选择：

• --dit_model：要使用的 DiT 模型。选项：3B/7B 及 fp16/fp8/GGUF 变体（默认：3B FP8）

处理参数：

• --resolution：目标短边分辨率（像素）（默认：1080）
• --max_resolution：任意边的最大分辨率。如果超过则缩小。0 = 无限制（默认：0）
• --batch_size：每批处理的帧数（必须遵循 4n+1：1、5、9、13、17、21...）。理想情况下应与镜头长度匹配，以获得最佳时间一致性（默认：5）
• --seed：用于可复现性的随机种子（默认：42）
• --skip_first_frames：跳过初始 N 帧（默认：0）
• --load_cap：从视频加载最多 N 帧。0 = 加载所有（默认：0）
• --prepend_frames：在开始处添加 N 个反转帧以减少起始伪影（会自动移除）（默认：0）
• --temporal_overlap：批次/GPU 之间重叠的帧数，用于平滑融合（默认：0）

质量控制：

• --color_correction：色彩校正方法：'lab'（感知型，推荐）、'wavelet'、'wavelet_adaptive'、'hsv'、'adain' 或 'none'（默认：lab）
• --input_noise_scale：输入噪声注入比例（0.0-1.0）。在高分辨率下减少伪影（默认：0.0）
• --latent_noise_scale：潜在空间噪声比例（0.0-1.0）。必要时可柔化细节（默认：0.0）

内存管理：

• --dit_offload_device：用于卸载 DiT 模型的设备：'none'（保持在 GPU 上）、'cpu' 或 'cuda:X'（默认：none）
• --vae_offload_device：用于卸载 VAE 模型的设备：'none'、'cpu' 或 'cuda:X'（默认：none）
• --blocks_to_swap：要交换的 transformer 块数量（0=禁用，3B：0-32，7B：0-36）。需要 dit_offload_device（默认：0）
• --swap_io_components：卸载 I/O 组件以节省更多 VRAM。需要 dit_offload_device
• --use_non_blocking：对 BlockSwap 使用非阻塞内存传输（推荐）

VAE 分块处理：

• --vae_encode_tiled：启用 VAE 编码分块处理以减少编码期间的 VRAM 使用
• --vae_encode_tile_size：VAE 编码分块大小（像素）（默认：1024）
• --vae_encode_tile_overlap：VAE 编码分块重叠（像素）（默认：128）
• --vae_decode_tiled：启用 VAE 解码分块处理以减少解码期间的 VRAM 使用
• --vae_decode_tile_size：VAE 解码分块大小（像素）（默认：1024）
• --vae_decode_tile_overlap：VAE 解码分块重叠（像素）（默认：128）
• --tile_debug：可视化分块：'false'（默认）、'encode' 或 'decode'

性能优化：

• --attention_mode：注意力后端：'sdpa'（默认，稳定）或 'flash_attn'（更快，需要安装相应包）
• --compile_dit：为 DiT 模型启用 torch.compile（提速 20-40%，需要 PyTorch 2.0+ 和 Triton）
• --compile_vae：为 VAE 模型启用 torch.compile（提速 15-25%，需要 PyTorch 2.0+ 和 Triton）
• --compile_backend：编译后端：'inductor'（完全优化）或 'cudagraphs'（轻量级）（默认：inductor）
• --compile_mode：优化级别：'default'、'reduce-overhead'、'max-autotune'、'max-autotune-no-cudagraphs'（默认：default）
• --compile_fullgraph：将整个模型编译为单个图（更快但灵活性较低）（默认：False）
• --compile_dynamic：处理变化的输入形状而无需重新编译（默认：False）
• --compile_dynamo_cache_size_limit：每个函数的最大缓存编译版本数（默认：64）
• --compile_dynamo_recompile_limit：回退前的最大重新编译尝试次数（默认：128）

模型缓存（批处理）：

• --cache_dit：在文件之间缓存 DiT 模型（仅限单 GPU，加快目录处理速度）
• --cache_vae：在文件之间缓存 VAE 模型（仅限单 GPU，加快目录处理速度）

多 GPU：

• --cuda_device：CUDA 设备 ID。单个 ID（例如 '0'）或逗号分隔的列表 '0,1' 用于多 GPU

调试：

• --debug：启用详细调试日志

多GPU处理原理说明

命令行界面（CLI）的多GPU模式会自动在多个GPU之间分配工作负载，并进行智能的时间重叠处理：

工作原理：

1. 视频被分割成多个块，每个GPU分配一个块
2. 每个GPU独立处理其分配的块
3. 块之间通过--temporal_overlap参数指定的帧数进行重叠
4. 利用重叠区域将结果无缝融合在一起

2个GPU且temporal_overlap=4的示例：

GPU 0: Frames 0-50 (includes 4 overlap frames at end)
GPU 1: Frames 46-100 (includes 4 overlap frames at beginning)
Result: Frames 0-100 with smooth transition at frame 48

最佳实践：

• 将 --temporal_overlap 设置为 2-8 帧以实现平滑混合
• 重叠度越高 = 过渡越平滑，但冗余处理越多
• 使用 --prepend_frames 减少视频开头的伪影
• 为获得最佳结果，batch_size 应能整除分块大小

⚠️ 局限性

模型局限性

批处理大小限制：由于时间一致性架构，模型要求 batch_size 遵循 4n+1 公式（1、5、9、13、17、21、25……）。批次中的所有帧会一起处理以保证时间连贯性，然后可以使用 temporal_overlap 对批次进行混合。理想情况下，将 batch_size 设置为与你的镜头长度相匹配，以获得最佳质量。

性能考量

VAE 瓶颈：即使采用优化的 DiT upscale（BlockSwap、GGUF、torch.compile），VAE 编码/解码阶段也可能成为瓶颈，尤其是在高分辨率下。VAE 速度较慢。使用大的 batch_size 可以缓解此问题。

显存（VRAM）使用：尽管目前的集成已支持低显存系统（8GB 或更少，配合适当优化），但显存使用情况取决于以下因素：

• 输入/输出分辨率（分辨率越高 = 显存占用越多）
• 批处理大小（batch_size 越大 = 显存占用越多，但时间一致性和速度越好）
• 模型选择（显存占用：FP16 > FP8 > GGUF）
• 优化设置（BlockSwap、VAE 分块可显著减少显存占用）

速度：处理速度取决于：

• GPU 性能（计算性能、显存带宽和架构代次）
• 模型大小（3B 比 7B 快）
• 批处理大小（更大的 batch_size 由于能更好地利用 GPU，每帧处理速度更快）
• 优化设置（torch.compile 可显著提升速度）
• 分辨率（分辨率越高，速度越慢）

最佳实践

1. 启用调试模式开始，以了解显存的使用位置
2. 编码时出现内存不足（OOM）错误：启用 VAE 编码分块并减小分块大小
3. ** upscale 时出现 OOM 错误**：启用 BlockSwap 并增加 blocks_to_swap
4. 解码时出现 OOM 错误：启用 VAE 解码分块并减小分块大小
   • 如果尝试上述所有方法后仍然 OOM：减小 batch_size 或分辨率
5. 追求最佳质量：使用与镜头长度匹配的更大 batch_size、FP16 模型以及 LAB 颜色校正
6. 追求速度：使用 FP8/GGUF 模型，启用 torch.compile，如果可用则使用 Flash Attention
7. 先使用短视频片段测试设置，再处理长视频

🤝 贡献指南

欢迎大家贡献力量！我们十分重视社区的意见和改进建议。

详细的贡献指南，请参见 CONTRIBUTING.md。

快速入门步骤：

1. Fork 本仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送分支到远程（git push origin feature/AmazingFeature）
5. 提交 Pull Request 到 main 分支（适用于稳定功能）或 nightly 分支（适用于实验性功能）

获取帮助：

• YouTube：AInVFX Channel
• GitHub Issues：用于提交错误报告和功能请求
• GitHub Discussions：用于提问和社区支持
• Discord：adrientoupet & NumZ#7184

🙏 致谢

本 ComfyUI 实现是 NumZ 与 AInVFX（Adrien Toupet）合作的项目，基于 ByteDance Seed 团队的原始 SeedVR2 开发。

特别感谢社区贡献者，包括 benjaminherb、cmeka、FurkanGozukara、JohnAlcatraz、lihaoyun6、Luchuanzhao、Luke2642、naxci1、q5sys 以及其他众多贡献者，感谢他们的改进、错误修复和测试工作。

📜 许可证

本仓库中的代码根据 LICENSE 文件中的 MIT 许可证发布。