HSWQ SAM3 Loader (ConvRot INT8)

What it is, and who actually needs it

SAM3 is Meta's third Segment Anything and the one that mattered: hand it a noun phrase and it returns a mask for every matching instance in one pass. That collapsed the old GroundingDINO-finds-a-box-then-SAM-masks-it pipeline into a single model, which is why SAM3 sits inside most mask editors shipped in 2026.

This node loads a quantized SAM3 - Linear layers stored as ConvRot / TensorWise INT8 rather than fp16 - and keeps them 8-bit in VRAM. SAM3.1 Multiplex lands around 525MB that way, roughly half of fp16. That's the difference between keeping a segmenter resident beside a video model on a 3090 and having it fight for VRAM every run. Worth knowing on its own terms: INT8-ConvRot runs on 20/30/40/50-series cards, including the 30-series, which have no fp8 acceleration at all.

The uncomfortable part, from the changelog

The author removed these SAM3 nodes in v3.4.8 - testing showed the dedicated loader isn't required, because the pack's startup patch already makes stock loaders (CheckpointLoaderSimple, the default Comfy SAM3.1 node) handle ConvRot INT8 SAM3 checkpoints automatically, MixedPrecisionOps attachment and CLIP key remap included. Then v3.5.9 restored the nodes, faithfully, from the v3.4.7 git history.

So: an explicit, discoverable door rather than a necessity. If CheckpointLoaderSimple loads your file cleanly, you don't need this. If a stock load gives you clip missing and then empty or black masks, this node exists to fix exactly that.

Inputs and output

One required input, sam3_name - a dropdown of .safetensors SAM3 checkpoints - and one output, model (MODEL).

That dropdown scans four folders: diffusion_models, sams, detection, checkpoints. A file dumped anywhere else won't appear, which is the number-one "the node is broken" report in waiting. Move it into one of the four and refresh.

Wire model into HSWQ SAM3 Detect or a stock SAM3 node - it's a plain ComfyUI MODEL. For text-prompted detection you also need the CLIP half: the pack's example loads the same checkpoint through CheckpointLoaderSimple and runs CLIPTextEncode("person") into Detect's conditioning.

How it works

It loads the safetensors and walks the state dict for .comfy_quant sidecars declaring format: int8_tensorwise. Find them and it loads with dtype=bfloat16 plus MixedPrecisionOps configured for int8_tensorwise: Linear layers build as QuantizedTensor with TensorWiseINT8Layout, so weights stay 8-bit in VRAM, and the GEMM runs through comfy_kitchen's int8_linear kernel with online activation rotation on ConvRot layers. Don't find them and it's a plain load - a standard fp16 SAM3 checkpoint works through this node fine.

Two safety patches install at load time, both for real failures. An unaligned-GEMM fallback: cuBLAS INT8 GEMM wants K and N in multiples of 4, SAM3 has layers that aren't (boxRPB_embed_x has in_features=2), and those dequantize to float instead of crashing the kernel. And a CLIP key remap: INT8 checkpoints store language_backbone already split into q/k/v where stock ComfyUI conversion expects it fused, so without it you get clip missing, corrupt text embeddings, empty masks.

One expectation to set: the detect node dequantizes these weights back to fp16 at runtime, deliberately, to dodge kernel and DynamicVRAM bugs. INT8 here is a footprint and load-correctness win, not a speed win.

Install

ComfyUI Manager → search ComfyUI-HSWQ-Loader-and-Tools, or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/ussoewwin/ComfyUI-HSWQ-Loader-and-Tools
# restart ComfyUI

Heads up: requirements.txt belongs to the whole pack, not to SAM3 - diffusers, transformers, peft, opencv-python, onnxruntime, plus insightface and facexlib, which nothing here needs and which are the classic Windows install snag. The bundled install.py upgrades pip, setuptools and wheel first, because facexlib pulls filterpy from source and that build dies on Python 3.12 with an old setuptools. Let it.

The pack does not install or toggle Triton - INT8 speed is left to ComfyUI and comfy_kitchen's cuda → triton → eager ladder - so the "SAM3 needs Triton on Windows" complaint that hits some other SAM3 nodes doesn't land here.

And the pack's universal rule: put General Purge VRAM V2 (ComfyUI-DistorchMemoryManager) at the end of the workflow with the HSWQ toggle on. Without it the author reports second runs dying with quantize_nvfp4, PyCapsule or pooled-TC errors, because HSWQ's residual GPU memory survives ComfyUI's normal unload.

Troubleshooting

Empty dropdown. The file isn't in one of the four scanned folders.
clip missing, then black masks. The remap patches didn't install; the pack logs SAM3 process_state_dict patch not installed at startup, usually because another extension shadowed comfy.sd.
Crash inside cublas_gemm_int8. The unaligned-dimension fallback didn't apply.
Where to get the checkpoint. The README publishes SDXL and Z Image quantized models on Hugging Face, not SAM3 - quantize SAM3 yourself with the upstream HSWQ tooling, or run fp16. HSWQ has essentially no Reddit footprint, so the README and the source are the whole paper trail.