TeaCache for Ruyi

Ruyi is slow. Not "sit back and sip your coffee" slow - community reports from launch measured around ten minutes for a single 512×72-frame clip on a 3090. So when the pack ships a node literally called TeaCache, it's not a nicety; it's the first thing you should reach for. If the model is the engine, this is the fuel-saver that skips the boring parts of the drive.

What it is

TeaCache is a caching/skipping acceleration technique from Alibaba's ali-vilab lab - the same team behind Wan's speed tricks - and it became a staple of the local video scene because it works on big diffusion transformers without retraining. The Ruyi pack wraps it as a RUYI_MODEL pass-through node: you slot it between Load Model and the sampler, and the sampler turns it on during denoising.

How it works

During the denoising loop, many consecutive timesteps produce near-identical feature states - the model is computing essentially the same thing twice. TeaCache watches those states, and when the change from the previous step falls below a threshold, it skips the expensive transformer forward pass entirely and reuses the cached result. That's free steps saved.

The node's own tooltips tell you what to expect:

• threshold (default 0.10, range 0–0.5) - 0.10 caches about 6–8 steps out of your run; 0.15 caches 10–12. Higher threshold = more skips = faster, but eventually you're reusing results that were never that close.
• skip_start_steps (default 3) and skip_end_steps (default 1) - the safety rails. The first few steps set the overall structure of the video and the last ones lock in fine detail, so TeaCache deliberately leaves them alone. Don't zero these out chasing speed; that's where the quality loss lives.
• offload_cpu (default true) - pushes the cached tensors to system RAM to save VRAM. On a 24GB card you can probably leave it on; on a tight card, definitely.

Inputs and output

Inputs: ruyi_model, enable (default on), threshold, skip_start_steps, skip_end_steps, offload_cpu. Output: ruyi_model again, so you can keep chaining nodes after it.

One thing that trips people up: this node doesn't do anything by itself. It records settings into the ruyi_model object, and the sampler reads them when it initializes the pipeline. If you delete this node or wire around it, the sampler silently disables TeaCache - no error, no warning, it just runs un-cached. When it is active, the sampler prints something like TeaCache cached steps: 8 to the console, which is a handy sanity check that it's actually doing work.

Installation

No extra install beyond the pack itself - TeaCache ships as part of ComfyUI-Ruyi:

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

Then just add the node in the chain: Ruyi_LoadModel → Ruyi_TeaCache → Ruyi_I2VSampler.

Where people get burned

The honest trade is that TeaCache trades a little fidelity for speed - you're literally skipping computed steps. That's why the default threshold is a modest 0.10 with the start/end steps protected. If you crank threshold to 0.5 to squeeze out maximum speed, expect visible motion artifacts and a video that feels less alive. The KB's distillation docs make the same point about every speed technique: the gain is real, the quality cost is real, and the sensible setup is the one where you don't notice either. Start at the defaults, check the console for how many steps got cached, and only push the threshold if the video still looks fine.