TeaCache (Ray)

Diffusion sampling wastes time: a lot of consecutive denoising steps produce predictions that barely change, and you're paying full transformer cost for each one. TeaCache's whole idea is to detect those "nothing happened" steps and reuse the previous step's prediction instead of running the model again. It's a free speedup in the sense that it trades a small quality risk for a large wall-clock win - typically 30–50% faster on video models with barely visible differences. RayTeaCache is the Raylight port, and it's distributed-aware, which is the interesting part.

The mechanism: at each step it computes a cheap feature (a subsampled representation of the input), compares it against the previous step's, and if the change rate is below threshold, it carries the prior prediction forward instead of recomputing. warmup_percent is the portion of sampling where it always computes (building up the reference state), and retention_interval caps how many consecutive steps can be skipped before it's forced to run again - the guardrail that keeps errors from compounding.

The controls, in the order you'll tune them:

• threshold (default 0.25) - the skip sensitivity. Higher = more skipping = faster but riskier. This is your main speed/quality tradeoff knob.
• warmup_percent (default 0.1) - first 10% of steps always compute. Raise it if the early trajectory is where your quality dies.
• retention_interval (default 8) - max consecutive skipped steps. Lower it for safety, raise it for speed.
• start_percent / end_percent (defaults 0.15 / 0.95) - the denoising window where caching is active. The defaults keep caching off at the very start and very end, where changes are large.

The optional inputs are where the distributed part shows: subsample_factor (default 8) controls how aggressively the comparison feature is downsampled, verbose logs the skip decisions, and distributed_sync - on by default - synchronizes the cache decision across Ray workers. That last one matters: on a sequence-parallel run, the workers are denoising different slices, and if they disagree about whether to skip, the all-gathered result corrupts. Distributed sync makes them decide together. It's the difference between a port that "works on paper" and one that works on actual multi-GPU runs.

Where it fits

Any Raylight workflow where speed matters more than pixel-perfect fidelity - the Wan video runs the pack is famous for are the natural habitat. It's a ray_actors-in/ray_actors-out patch after Ray Init Actor, and it composes with everything else in the graph. The KB's Wan guide notes TeaCache as standard kit in the Wan ecosystem, and this is that same tool for Raylight.

Install

Part of raylight:

cd ComfyUI/custom_nodes
git clone https://github.com/komikndr/raylight
cd raylight
pip install -r requirements.txt

Restart, or install "raylight" via ComfyUI Manager.

Gotchas

• Threshold is the whole ballgame. At 0.25 you get the classic "looks identical" speedup; push toward 0.4–0.5 and motion can get jittery or details smear, especially on fast-moving video.
• If you're in USP (sequence-parallel) mode, leave distributed_sync on. Turning it off to "save a sync" is how you get corrupt frames that are miserable to debug.
• TeaCache is a quality-risk accelerator, not a free lunch - validate on your actual content. For a single high-value generation, the honest call is often "just run it without caching."