ComfyUI 节点式AI图像生成

🔧 Requirements

Install requirements (from same ComfyUI directory)

Prerequisites

Choose the appropriate setup based on your installation:

Option 1: Already Have ComfyUI with SeedVR2 Installed

If you've already installed SeedVR2 as part of ComfyUI (via ComfyUI installation), you can use the CLI directly:

```bash

Install SeedVR2 requirements

uv pip install -r requirements.txt

Streaming mode for long videos (memory-efficient) with 10-bit video output (requires FFMPEG)

📦 Installation

Option 2: Manual Installation

1. Clone the repository into your ComfyUI custom nodes directory:

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

2. Install dependencies using standalone Python: ```bash

Model Installation

Models will be automatically downloaded on first use and saved to ComfyUI/models/SEEDVR2.

You can also manually download models from: - Main models available at numz/SeedVR2_comfyUI and AInVFX/SeedVR2_comfyUI - Additional GGUF models available at cmeka/SeedVR2-GGUF

Node Setup

SeedVR2 uses a modular node architecture with four specialized nodes:

1. SeedVR2 (Down)Load DiT Model

Configure the DiT (Diffusion Transformer) model for video upscaling.

Parameters:

• model: Choose your DiT model
• 3B Models: Faster, lower VRAM requirements
• seedvr2_ema_3b_fp16.safetensors: FP16 (best quality)
• seedvr2_ema_3b_fp8_e4m3fn.safetensors: FP8 8-bit (good quality)
• seedvr2_ema_3b-Q4_K_M.gguf: GGUF 4-bit quantized (acceptable quality)
• seedvr2_ema_3b-Q8_0.gguf: GGUF 8-bit quantized (good quality)
• 7B Models: Higher quality, higher VRAM requirements
• seedvr2_ema_7b_fp16.safetensors: FP16 (best quality)
• seedvr2_ema_7b_fp8_e4m3fn_mixed_block35_fp16.safetensors: FP8 with last block in FP16 to reduce artifacts (good quality)
• seedvr2_ema_7b-Q4_K_M.gguf: GGUF 4-bit quantized (acceptable quality)
• seedvr2_ema_7b_sharp_*: Sharp variants for enhanced detail

• device: GPU device for DiT inference (e.g., cuda:0)

• offload_device: Device to offload DiT model when not actively processing
• none: Keep model on inference device (fastest, highest VRAM)
• cpu: Offload to system RAM (reduces VRAM)
• cuda:X: Offload to another GPU (good balance if available)

• cache_model: Keep DiT model loaded on offload_device between workflow runs
• Useful for batch processing to avoid repeated loading
• Requires offload_device to be set

• blocks_to_swap: BlockSwap memory optimization
• 0: Disabled (default)
• 1-32: Number of transformer blocks to swap for 3B model
• 1-36: Number of transformer blocks to swap for 7B model
• Higher values = more VRAM savings but slower processing
• Requires offload_device to be set and different from device

• swap_io_components: Offload input/output embeddings and normalization layers
• Additional VRAM savings when combined with blocks_to_swap
• Requires offload_device to be set and different from device

• attention_mode: Attention computation backend
• sdpa: PyTorch scaled_dot_product_attention (default, always available)
• flash_attn_2: Flash Attention 2 (Ampere+, requires flash-attn package)
• flash_attn_3: Flash Attention 3 (Hopper+, requires flash-attn with FA3 support)
• sageattn_2: SageAttention 2 (requires sageattention package)
• sageattn_3: SageAttention 3 (Blackwell/RTX 50xx, requires sageattn3 package)

• torch_compile_args: Connect to SeedVR2 Torch Compile Settings node for 20-40% speedup

BlockSwap Explained:

BlockSwap enables running large models on GPUs with limited VRAM by dynamically swapping transformer blocks between GPU and CPU memory during inference.

Note: BlockSwap is not available on macOS. Apple Silicon Macs use unified memory architecture where GPU and CPU share the same memory pool, making BlockSwap meaningless. The option will be automatically disabled with a warning if requested on macOS.

Here's how it works:

- What it does: Keeps only the currently-needed transformer blocks on the GPU, while storing the rest on CPU or another device - When to use it: When you get OOM (Out of Memory) errors during the upscaling phase - How to configure: 1. Set offload_device to cpu or another GPU 2. Start with blocks_to_swap=16 (half the blocks) 3. If still getting OOM, increase to 24 or 32 (3B) / 36 (7B) 4. Enable swap_io_components for maximum VRAM savings 5. If you have plenty of VRAM, decrease or set to 0 for faster processing

Example Configuration for Low 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

Configure the VAE (Variational Autoencoder) model for encoding/decoding video frames.

Parameters:

• model: VAE model selection
• ema_vae_fp16.safetensors: Default and recommended

• device: GPU device for VAE inference (e.g., cuda:0)

• offload_device: Device to offload VAE model when not actively processing
• none: Keep model on inference device (default, fastest)
• cpu: Offload to system RAM (reduces VRAM)
• cuda:X: Offload to another GPU (good balance if available)

• cache_model: Keep VAE model loaded on offload_device between workflow runs
• Requires offload_device to be set

• encode_tiled: Enable tiled encoding to reduce VRAM usage during encoding phase
• Enable if you see OOM errors during the "Encoding" phase in debug logs

• encode_tile_size: Encoding tile size in pixels (default: 1024)
• Applied to both height and width
• Lower values reduce VRAM but may increase processing time

• encode_tile_overlap: Encoding tile overlap in pixels (default: 128)
• Reduces visible seams between tiles

• decode_tiled: Enable tiled decoding to reduce VRAM usage during decoding phase
• Enable if you see OOM errors during the "Decoding" phase in debug logs

• decode_tile_size: Decoding tile size in pixels (default: 1024)

• decode_tile_overlap: Decoding tile overlap in pixels (default: 128)

• torch_compile_args: Connect to SeedVR2 Torch Compile Settings node for 15-25% speedup

VAE Tiling Explained:

VAE tiling processes large resolutions in smaller tiles to reduce VRAM requirements. Here's how to use it:

1. Run without tiling first and monitor the debug logs (enable enable_debug on main node) 2. If OOM during "Encoding" phase: - Enable encode_tiled - If still OOM, reduce encode_tile_size (try 768, 512, etc.) 3. If OOM during "Decoding" phase: - Enable decode_tiled - If still OOM, reduce decode_tile_size 4. Adjust overlap (default 128) if you see visible seams in output (increase it) or processing times are too slow (decrease it).

Example Configuration for High Resolution (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 (Optional)

Configure torch.compile optimization for 20-40% DiT speedup and 15-25% VAE speedup.

Requirements: - PyTorch 2.0+ - Triton (for inductor backend)

Parameters:

• backend: Compilation backend
• inductor: Full optimization with Triton kernel generation and fusion (recommended)
• cudagraphs: Lightweight wrapper using CUDA graphs, no kernel optimization

• mode: Optimization level (compilation time vs runtime performance)
• default: Fast compilation with good speedup (recommended for development)
• reduce-overhead: Lower overhead, optimized for smaller models
• max-autotune: Slowest compilation, best runtime performance (recommended for production)
• max-autotune-no-cudagraphs: Like max-autotune but without CUDA graphs

• fullgraph: Compile entire model as single graph without breaks
• False: Allow graph breaks for better compatibility (default, recommended)
• True: Enforce no breaks for maximum optimization (may fail with dynamic shapes)

• dynamic: Handle varying input shapes without recompilation
• False: Specialize for exact input shapes (default)
• True: Create dynamic kernels that adapt to shape variations (enable when processing different resolutions or batch sizes)

• dynamo_cache_size_limit: Max cached compiled versions per function (default: 64)
• Higher = more memory, lower = more recompilation

• dynamo_recompile_limit: Max recompilation attempts before falling back to eager mode (default: 128)
• Safety limit to prevent compilation loops

Usage: 1. Add this node to your workflow 2. Connect its output to the torch_compile_args input of DiT and/or VAE loader nodes 3. First run will be slow (compilation), subsequent runs will be much faster

When to use: - torch.compile only makes sense when processing multiple batches, long videos, or many tiles - For single images or short clips, the compilation time outweighs the speed improvement - Best suited for batch processing workflows or long videos

Recommended Settings: - For development/testing: mode=default, backend=inductor, fullgraph=False - For production: mode=max-autotune, backend=inductor, fullgraph=False

4. SeedVR2 Video Upscaler (Main Node)

Main upscaling node that processes video frames using DiT and VAE models.

Required Inputs:

• image: Input video frames as image batch (RGB or RGBA format)
• dit: DiT model configuration from SeedVR2 (Down)Load DiT Model node
• vae: VAE model configuration from SeedVR2 (Down)Load VAE Model node

Parameters:

• seed: Random seed for reproducible generation (default: 42)
• Same seed with same inputs produces identical output

• resolution: Target resolution for shortest edge in pixels (default: 1080)
• Maintains aspect ratio automatically

• max_resolution: Maximum resolution for any edge (default: 0 = no limit)
• Automatically scales down if exceeded to prevent OOM

• batch_size: Frames per batch (default: 5)
• CRITICAL REQUIREMENT: Must follow the 4n+1 formula (1, 5, 9, 13, 17, 21, 25, ...)
• Why this matters: The model uses these frames for temporal consistency calculations
• Minimum 5 for temporal consistency: Use 1 only for single images or when temporal consistency isn't needed
• Match shot length ideally: For best results, set batch_size to match your shot length (e.g., batch_size=21 for a 20-frame shot)
• VRAM impact: Higher batch_size = better quality and speed but requires more VRAM
• If you get OOM with batch_size=5: Try optimization techniques first (model offloading, BlockSwap, GGUF models...) before reducing batch_size or input resolution, as these directly impact quality

uniform_batch_size (default: False) - Pads the final batch to match batch_size for uniform processing - Prevents temporal artifacts when the last batch is significantly smaller than others - Example: 45 frames with batch_size=33 creates [33, 33] instead of [33, 12] - Recommended when using large batch sizes and video length is not a multiple of batch_size - Increases VRAM usage slightly but ensures consistent temporal coherence across all batches

• temporal_overlap: Overlapping frames between batches (default: 0)
• Used for blending between batches to reduce temporal artifacts
• Range: 0-16 frames

• prepend_frames: Frames to prepend (default: 0)
• Prepends reversed frames to reduce artifacts at video start
• Automatically removed after processing
• Range: 0-32 frames

• color_correction: Color correction method (default: "wavelet")
• lab: Full perceptual color matching with detail preservation (recommended for highest fidelity to original)
• wavelet: Frequency-based natural colors, preserves details well
• wavelet_adaptive: Wavelet base + targeted saturation correction
• hsv: Hue-conditional saturation matching
• adain: Statistical style transfer
• none: No color correction

• input_noise_scale: Input noise injection scale 0.0-1.0 (default: 0.0)
• Adds noise to input frames to reduce artifacts at very high resolutions
• Try 0.1-0.3 if you see artifacts with high output resolutions

• latent_noise_scale: Latent space noise scale 0.0-1.0 (default: 0.0)
• Adds noise during diffusion process, can soften excessive detail
• Use if input_noise doesn't help, try 0.05-0.15

• offload_device: Device for storing intermediate tensors between processing phases (default: "cpu")
• none: Keep all tensors on inference device (fastest but highest VRAM)
• cpu: Offload to system RAM (recommended for long videos, slower transfers)
• cuda:X: Offload to another GPU (good balance if available, faster than CPU)

• enable_debug: Enable detailed debug logging (default: False)
• Shows memory usage, timing information, and processing details
• Highly recommended for troubleshooting OOM issues

Output: - Upscaled video frames with color correction applied - Format (RGB/RGBA) matches input - Range [0, 1] normalized for ComfyUI compatibility

Typical Workflow Setup

Basic Workflow (High VRAM - 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

Low VRAM Workflow (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

High Performance Workflow (24GB+ with 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

Install PyTorch with CUDA support

📖 Usage

🎬 Video Tutorials

Latest Version Deep Dive (Recommended)

Complete walkthrough of version 2.5 by Adrien from AInVFX, covering the new 4-node architecture, GGUF support, memory optimizations, and production workflows:

This comprehensive tutorial covers: - Installing v2.5 through ComfyUI Manager and troubleshooting conflicts - Understanding the new 4-node modular architecture and why we rebuilt it - Running 7B models on 8GB VRAM with GGUF quantization - Configuring BlockSwap, VAE tiling, and torch.compile for your hardware - Image and video upscaling workflows with alpha channel support - CLI for batch processing and multi-GPU rendering - Memory optimization strategies for different VRAM levels - Real production tips and the critical batch_size formula (4n+1)

Previous Version Tutorial

For reference, here's the original tutorial covering the initial release:

Note: This tutorial covers the previous single-node architecture. While the UI has changed significantly in v2.5, the core concepts about BlockSwap and memory management remain valuable.

Command Line Usage

The CLI provides comprehensive options for single-GPU, multi-GPU, and batch processing workflows.

Basic Usage Examples:

```bash

Option 1: ComfyUI Manager (Recommended)

1. Open ComfyUI Manager in your ComfyUI interface
2. Click "Custom Nodes Manager"
3. Search for "ComfyUI-SeedVR2_VideoUpscaler"
4. Click "Install" and restart ComfyUI

Registry Link: ComfyUI Registry - SeedVR2 Video Upscaler

Create virtual environment with Python 3.13

uv venv --python 3.13

Activate virtual environment

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

🖥️ CLI Enhancements

• Batch Directory Processing: Process entire folders of videos/images with model caching for efficiency
• Single Image Support: Direct image upscaling without video conversion
• Smart Output Detection: Auto-detects output format (MP4/PNG) based on input type
• Enhanced Multi-GPU: Improved workload distribution with temporal overlap blending
• Unified Parameters: CLI and ComfyUI now use identical parameter names for consistency
• Better UX: Auto-display help, validation improvements, progress tracking, and cleaner output

Run the CLI using standalone Python (display help message)

Run the CLI (display help message)