Comfy-WaveSpeed: reading one transformer block to decide whether to run the other fifty

Two nodes, and a status note that ranks them against each other

The readme opens with the usual claims of being an all in one optimisation solution, and then does something rarer: it tells you which of the two things it does is dependable.

The status note says the caching and compilation nodes are stable and widely used, but that active development on the repository is intermittent, and that the one unimplemented item in the feature checklist should be treated as an idea rather than a roadmap. That last clause matters. A checkbox list in a readme is normally a promise, and projects that are busy often leave aspirational items in one. This one labels its own aspirational item explicitly, which tells you the author knows the difference between the two and expects you to as well.

The unimplemented item is multi-GPU inference, described as a context parallelism technique adapted from the author's other project. So the two implemented features are algorithmic caching and compilation, and the third would have been distribution. Everything in the readme is organised around that: one node that makes each step cheaper, one node that makes the model start faster, and an admission that neither of them makes a 70 billion parameter video model fit on the card you have.

The two nodes are also not independent. The documentation is explicit about ordering, with the cache node placed after the model loader and the compile node placed after either of those. The natural reading is that caching changes what the compiler is compiling, and compiling first then caching would fuse or specialise against work you are about to throw away. A node pack that documents its own stacking order has usually been through the failure.

The fallback advice deserves attention because it tells you the author's own ranking. If the compilation node causes trouble, the documented remedy is to remove it from the workflow and keep only the cache node, and the readme adds that the cache node on its own still delivers a significant speedup. That is a maintainer saying the second feature is the fragile one.

How the cache decides to skip forty-nine transformer blocks

The mechanism is a change detector, and it is a good one to understand before you tune anything.

Diffusion sampling in these models is an iterative denoising loop. At each step the whole transformer stack runs, and early in the process the output changes a lot while later in the process it changes very little. The expensive observation is that most of the compute in a step produces a result that is nearly identical to the previous step's.

This project uses the first transformer block as a probe. The residual output of that block is read at the current step and compared against the same value at the previous step. If the difference is small enough, the previous step's final residual output is reused and every remaining block is skipped. One block's worth of computation is spent to decide whether to spend forty-nine.

The inspiration is named, pointing at an existing denoising cache project and other caching algorithms in the same family. What makes the first block a good probe is that it is early enough to reflect the current step's input and cheap enough to always run. Using a later block as the indicator would give a better signal and cost more; using the output of the whole stack as the indicator would be circular, since deciding whether to run the stack requires having run it.

The stated result is a speedup of up to two times while maintaining accuracy, and the expected range in practice is quoted more conservatively as one and a half to three times with acceptable accuracy loss. Both numbers appear, and the gap between the headline and the expectation is the honest part: two times is the ceiling, three times is the optimistic end of the range, and the word used for the quality cost is loss rather than nothing. This is a trade, and the parameter that controls it is described next.

The threshold table, and a parameter name that has a typo baked into the API

Tuning this cache is a single number, and the readme gives a table of starting points rather than a default, which is the right call and also the main practical obstacle.

The parameter is named with a misspelling, reading as a residual difference threshold with the vowels transposed. That typo is part of the public interface now, appearing in the workflow JSON files and in every saved graph, and it will not be fixed without breaking existing workflows. It is worth knowing before you go looking for the correctly spelled name and conclude the setting does not exist.

The table gives a value per model, and the values are not interchangeable. The suggested figure for one image model at twenty-eight steps with a specific eight-bit quantisation is a little over a tenth, two video models at twenty and thirty steps both take a tenth, a second image model at thirty steps takes a little over a tenth again, and the oldest model in the list at twenty-five steps takes double that. The pattern is legible: a smaller number means a stricter test, and the models that need a looser test are the ones where the residual settles earlier in the denoising loop.

Read the table as recipes rather than constants. Each row is bound to a step count, and the step count is part of the recipe, because the number of times the cache is allowed to fire depends on how many opportunities it has. Change the steps and the threshold is no longer the value that was tested. The quantisation in the row is bound in as well, and the fact that every image model row names an eight-bit variant is a hint that this was tuned on a setup most people do not have.

The practical procedure the documentation implies is therefore: start from the row matching your model and step count, generate the same prompt with and without the node, and look at the images. There is no automated quality metric in the readme, and the comparison linked in the documentation is a visual one. That is a real limitation of a threshold that trades compute for fidelity, and the author has not pretended otherwise.

Model coverage is a list, and one entry is exclusive with another node pack

The supported model list is worth reading for what it implies about the implementation. The coverage is a flagship image model, a video model in both native and non-native form, a video model in native form only, a mid-sized image model and an older image model. The parenthetical qualifications are the interesting part: they say the same family is handled differently depending on which pipeline variant you are running, which means the node has to be patching more than one graph rather than one.

That is visible in the repository layout. The implementation is not one file. There is a module for the cache nodes, a separate module holding the caching logic itself, a module named for patching, a utility module, a miscellaneous nodes module, and a module whose name does not appear anywhere in the readme. Six demo workflows ship as JSON, one per supported configuration, including a controlnet variant, which is the case most likely to break a patch that assumes a single sampling path.

The compatibility note is the other half of this section, and it is a genuine exclusion rather than a caveat. Applying the cache on the oldest model in the list is incompatible with a separately maintained node pack that changes the sampling schedule, and the note says it will not function properly if that pack is installed and enabled. Two node packs both reaching into the same step loop is a genuine conflict, and a project that documents it as a hard exclusion rather than leaving you to discover an image that looks wrong is being straight with the reader.

The undocumented module is worth a sentence. Its presence in the repository with no mention in the readme means either an unreleased node type or a leftover from an experiment. Neither is a problem for a user, and both are reasons to read the source before assuming the readme is the complete surface.

The compile node has four documented failure modes and one real advantage

The second feature wraps the framework's ahead-of-time compiler, and its documentation is organised as a list of things that will go wrong. All four are stated without hedging.

First, the compilation happens on the first run of a workflow and takes a long time, after which it is cached. That is a cost paid once, but it means the first generation after you change anything can stall, and a user who does not know that will assume the node is broken.

Second, and more subtly, compilation is invalidated by changing the resolution or the text prompt, which is a frequency problem rather than a correctness one. The documented remedies are two: enable a dynamic option on the node, or start the application with a recompilation logging environment variable to find out why it is recompiling. Offering a diagnostic switch next to the fix is good practice and is a fair signal about how often this comes up.

Third, the compiler and the model's offloading mechanism do not get along, and the documented fix is to launch the application in a mode that disables offloading. The command is one flag:

comfy launch -- --gpu-only

Fourth, and the two hard limits, the compiler does not work on Windows officially, with a note telling the reader to look elsewhere if they hit this, and compiling a model with eight-bit quantisation does not work on cards older than a particular architecture generation, with a specific older consumer card named. Both are phrased as do not use rather than works partially, which is the correct characterisation for a compiler.

Against four failure modes there is one advantage, and the readme leads with it: this node works with low-rank adapters where the framework's own compile node does not. For anyone generating with a fine-tuned model, that single capability is the reason to use this node instead of the built-in one, and it is a much more common situation than the documentation's tone suggests. A cache that skips work is model agnostic; a compiler that refuses to compile an adapted model is a hard stop, so the two features have different audiences and different reasons to exist.

Installation is a clone, and the register entry has no icon

The installation is two commands, which is the standard for this kind of node pack because ComfyUI loads custom nodes from a directory rather than from a package index:

cd custom_nodes
git clone https://github.com/chengzeyi/Comfy-WaveSpeed.git

There is a registry entry in the readme as well, so the nodes are also discoverable through the ecosystem's own catalogue. The packaging metadata is where the details are. The project version is a one point one point eight, the licence is declared by file reference rather than by an identifier, and the registry section carries a publisher identifier and a display name, with the icon field present and empty. An empty icon field is a small unfinished detail, and it is the kind of thing that tells you the registry submission was done quickly and will be revisited or not.

The demo workflow folder is the part of the repository that makes this project usable rather than merely interesting. Six saved graphs, one per supported model, one with a controlnet attached. For a feature whose only configuration surface is a hand-tuned number, a saved workflow with that number already filled in is worth more than any amount of documentation, and shipping them is the difference between a fifteen minute evaluation and an afternoon of setup.

The readme also carries a pointer to the author's hosted generation platform for readers who do not have a GPU at all, framed as a fallback for the same model families. That is a commercial relationship and it belongs in an assessment, because it tells you who maintains the node and what they do for a living. It is also worth separating from the technical question: a hosted endpoint charges per generation, whereas this cache makes a fixed local cost lower, and the two are substitutes only for someone who was not going to buy hardware anyway.

Editorial conclusion

Comfy-WaveSpeed is worth installing if you run diffusion models locally on a supported card and generate enough images that a two to three times speedup pays for the tuning, and you are willing to spend an afternoon finding a threshold that suits your model and step count rather than copying a table. It is a poor fit on Windows or on a pre-Ada card if you plan to use the compile node, since both limitations are documented as unsupported rather than degraded, and a poor fit if you need multi-GPU inference, which is listed as an idea rather than a plan. Install the cache node first and treat the compiler as the optional half, exactly as the documentation suggests, because the cache works alone and the compiler does not. If you have no local GPU at all, the same model families are available on a hosted platform the author runs, which is a different cost model rather than a substitute for the speedup.

Frequently asked questions

Official sources

1. chengzeyi/Comfy-WaveSpeed on GitHub
2. Issues
3. License: MIT
4. README