SDMatte 加载器

RuiSDMatteLoader is the weight-loading half of RUI-Nodes' SDMatte matting system. It loads the SDMatte model into memory once and hands the loaded model to the RuiSDMatte matting node, so you're not re-reading a multi-gigabyte checkpoint on every single run. If you've used any other loader/matcher pair in ComfyUI, the pattern is familiar: loader holds the weights, the processing node does the work.

For background on why this family of models exists - and how matting differs from ordinary background removal - the KB's background-removal essay is the best starting point. The short version: plain segmentation models predict a hard foreground/background label and fall apart on hair, glass, and smoke. Matting models predict fractional alpha. SDMatte (vivo Camera Research, ICCV 2025) is built on a Stable Diffusion 2.1 backbone and is one of the strongest options for those hard edges - but unlike BiRefNet, which ComfyUI now ships in core, SDMatte needs a manual setup, and that's what this node streamlines.

How it works

The loader's only output is sdmatte_model, a custom model object that the RuiSDMatte node consumes directly. It keeps the model resident so repeated runs don't pay the load cost. The settings:

• ckpt_name - the weights file, pulled from models/SDMatte/ inside your ComfyUI models directory. Two files work and are bit-identical in model weights: the official SDMatte_plus.pth (12.1GB, from LongfeiHuang/SDMatte) and the community SDMatte_plus.safetensors (5.19GB, from 1038lab/SDMatte). The pth's extra ~7GB is optimizer/trainer state that inference never touches. Don't agonize over which to download - pick the safetensors and save the bandwidth. And notably: you do not need Stable Diffusion 2.1 weights. SDMatte is built on SD 2.1's architecture, but the network is constructed from config files that ship with this node, and every weight comes from the SDMatte checkpoint itself.
• precision - fp32 (default, matches the official test config) or fp16. FP16 saves VRAM but the SD 2.1 VAE tends to overflow in half precision, which can produce black or noisy output. Leave it on fp32 unless you're desperate.
• device - auto or cpu. You almost certainly want auto.
• attention_slicing - default on, and here the numbers are worth respecting: at 1024 resolution the author measured VRAM peak dropping from ~15.5GB to ~9.1GB, with output differences around 1e-6 (invisible) and, if anything, slightly faster. 12GB cards should keep it on. Turn it off only if you're chasing bit-exact parity with the official config.

Installing it

This is the heavier sibling in the RUI-Nodes pack. The base install is the same - ComfyUI Manager (search "RUI-Nodes") or:

cd ComfyUI/custom_nodes
git clone https://github.com/rui40000/RUI-Nodes
cd RUI-Nodes
pip install -r requirements.txt

But the matting nodes also need diffusers>=0.30.0, transformers>=4.40.0, safetensors, scipy, and opencv-python. The pack wraps them in a try/except, so if those are missing the rest of the pack still loads and this node simply won't appear. Then drop a checkpoint into ComfyUI/models/SDMatte/ (create the folder) and restart.

Where people get burned

The #1 community complaint across all SDMatte nodes is "it can't detect the models I downloaded" - it's a recurring theme in r/comfyui threads, and it almost always means one of two things: the weights aren't in models/SDMatte/, or the diffusers/transformers deps aren't installed so the nodes never registered. Check both before anything else. Also: if you installed a fresh transformers 5.x, older SDMatte implementations silently lose the text encoder's weights due to a key-prefix change - this node handles that automatically, which is one of the reasons to prefer it. And keep attention slicing on; on 12GB cards the ~9GB peak with it on is comfortable, off is not.