Load Model

"Load Model" sounds like the boring first step, but in this pack it's doing real work: the first time you run it, it pulls down the entire Ruyi-Mini-7B model - about 17GB - straight from Hugging Face, no manual downloading required. It's the gate everything else in the ComfyUI-Ruyi pack passes through, so getting it right fixes half your problems before they start.

What it loads

Ruyi is CreateAI's image-to-video model, Apache 2.0, released December 2024: 7 billion parameters, up to 768 resolution at 24fps and 120 frames (five seconds), with the camera and motion controls that made it interesting. It's a 2D-to-3D diffusion transformer that shares architectural DNA with Tencent's Hunyuan Video - same 3D-transformer family - plus a MAGVIT-style VAE and a CLIP image encoder. All of that gets assembled into one inference pipeline when this node runs.

The model dropdown has exactly one entry, Ruyi-Mini-7B. Don't hunt for a bigger one; this is the whole catalog.

The inputs that actually matter

• auto_download (default yes) - if the model is missing or incomplete in ComfyUI/models/Ruyi, this node downloads it via snapshot_download. Set to no if you want to manage the 17GB yourself and symlink it in instead.
• auto_update (default yes) - checks for model updates on every load. This matters more than it sounds: the original weights had a bug that drew black lines on 3:4 and 4:5 videos, fixed by a Dec 24, 2024 update. Leave this on. One gotcha: the update check relies on huggingface_hub's cache, so don't delete the .cache folder inside the model directory or updates silently stop working.
• fp8_quant_mode (default none) - the VRAM dial. none is bf16 at full memory; then lite, strong, and extreme in descending memory order. This is where you make a 17GB model fit smaller cards. The KB's general fp8 advice - "if it fits, just use it" - applies, but here it's a ladder, not a switch, so start at lite and step down only as far as you need.
• fp8_data_type (default auto) - fp8_e4m3fn (the usual choice) or fp8_e5m2. The tooltip on the node says it plainly: don't combine fp8_e5m2 with extreme mode. Trust it.

Output

One output: ruyi_model (type RUYI_MODEL). It carries the whole pipeline - weights, scheduler, embeddings, and a running list of any LoRAs and plugin settings you attach. Wire it to Ruyi_LoadLora, Ruyi_TeaCache, Ruyi_EnhanceAVideo, or straight into the sampler. The RUYI_MODEL type is specific to this pack; you can't feed it anything else, and nothing else accepts it.

Installation

# ComfyUI Manager: search "Ruyi", install ComfyUI-Ruyi (plus ComfyUI-VideoHelperSuite)
# or:
cd ComfyUI/custom_nodes
git clone https://github.com/IamCreateAI/Ruyi-Models.git
pip install -r Ruyi-Models/requirements.txt

The requirements are the heavy end of a video-model stack: diffusers, transformers, accelerate, decord, imageio with both ffmpeg and pyav backends, opencv, scikit-image. On Windows portable, run pip through the embedded interpreter (..\..\python_embeded\python.exe -m pip install ...). Then add VideoHelperSuite so the sampler's output has somewhere to go.

Common issues

• LoadModel: ConnectionError (MaxRetryError) - this is the README's own FAQ entry: huggingface_hub failed to reach the model server, usually a network hiccup. If your connection is fine, just rerun the node. If it persists, your network can't reach HF and auto_download won't save you - grab the weights another way and point auto_download at no.
• Model won't load with auto_download off - you get a FileNotFoundError telling you exactly where it wants the files (ComfyUI/models/Ruyi/Ruyi-Mini-7B). Put them there, or flip auto_download back to yes.
• Slow model load - normal. A 3090 owner measured about a minute just to load the weights before the first generation. That's the price of 7B parameters with CPU offload enabled.
• PyTorch too old - the README calls out PyTorch 2.2+ specifically for FlashAttention-2, which is a big chunk of this model's generation speed. If your Ruyi runs feel glacial, check the torch version before blaming the node.

One honest note: the model is a bit of a dinosaur by mid-2026 - Wan took over the local I2V conversation months later. But Load Model is well-built for its job, and for anyone running Ruyi, it's the piece that makes everything else possible.