Nucleus-Image Block Swap

Nucleus-Image is a sparse MoE: 17B params, but only ~2B active per forward pass. The catch is that all the experts still need to live somewhere. Nucleus-Image Block Swap is the one setting that decides whether "somewhere" is your VRAM or your CPU. One integer, 0 to 29. That's the entire node.

How it works

The transformer has 32 layers; the first three are dense, leaving 29 that use routed MoE with 64 experts each. On load, the Transformer Loader counts those 29 MoE blocks and keeps num_moe − blocks_to_swap of them on the GPU, shipping the rest to the CPU offload device. The node's own docstring gives you the extremes:

0 (default) - every expert on the GPU. About 18.5GB of model resident in VRAM. Fastest.
29 - every expert on CPU. Roughly 3.2GB of GPU footprint. Slowest, but it runs on cards that otherwise can't.

The swap happens at load time, per expert block. Raising the number doesn't change the output one bit - it's purely a memory-versus-speed trade. Same seed, same image, slower wall clock.

The input and where it goes

One input, blocks_to_swap (INT, 0–29, step 1). It produces a BLOCKSWAPARGS object which feeds the Transformer Loader's optional block_swap_args input. Don't wire it, and you get the default 0 - all experts on GPU. The node is just a structured way to hand a number to the loader.

When to reach for it

The README's verified setup runs FP8 on 24GB with blocks_to_swap = 0 and never touches this node. If you're on a smaller card, or you're trying to run the bf16 transformer, or ComfyUI throws an OOM at the Sampler, this is your first knob. The README's OOM answer is literally "increase blocks_to_swap." Start with a small number and creep up until it fits - every expert you move to CPU buys you headroom at the cost of slower generation, and 24GB users generally don't need any.

Installing

Same as every node in the pack - ComfyUI Manager (search "Nucleus-Image") or:

cd ComfyUI/custom_nodes
git clone https://github.com/a180265/Nucleus-Image-comfyui-beta

restart. It needs no model files of its own; it only produces arguments for the loader.

The honest caveat

This is a beta, and the author says so plainly: Block Swap "passed code review" but was not runtime-tested. The mechanism is straightforward and the docstring's memory figures are precise, but if you're on an unusual card, verify with a short run before you trust a big swap count for a long job. Also worth knowing: the swap is a one-time placement decision, not adaptive. If your VRAM is tight because other things are loaded, the loader won't rebalance on its own - you set the dial, and you get what you set.