DiffSynth: ModelConfig

If you're used to ComfyUI, you expect a dropdown. Pick a checkpoint from ComfyUI/models/checkpoints, done. DiffSynth-ComfyUI doesn't work like that, and this little node is the reason why.

The pack is a bridge to DiffSynth-Studio, the ModelScope team's inference framework - the same codebase that shipped the Qwen-Image-i2L single-image LoRA tool people were passing around. That framework carries models ComfyUI core has never had a loader for: LingBot-Video, MOVA, LTX-2, MiniMax H3, Qwen-Image-2.1. Rather than teach ComfyUI about each one, the pack makes you declare the files. That's ModelConfig.

What it actually does

You give it a repository and a filename pattern. It resolves the file, downloads it if it isn't already cached, and hands a model_config object downstream - which is really just a description of one weight file, plus whatever VRAM and quantization settings you attached to it.

One pipeline needs several of these. A Qwen-Image text-to-image graph is three ModelConfig nodes (transformer, text encoder, VAE), then a Merge ModelConfigs node to collect them, then the Loader. The Qwen-Image-Edit graph is the same three plus a fourth for the processor/ folder.

The two required fields are the whole trick:

• model_id - the repo, e.g. Qwen/Qwen-Image-2.1 or MiniMax/MiniMax-H3. DiffSynth resolves these against ModelScope by default.
• origin_file_pattern - the glob inside the repo, e.g. transformer/diffusion_pytorch_model*.safetensors. Note the wildcard: sharded checkpoints are common, and the pattern is how you get all the shards. Leave it blank and you get the whole repo, which is how the pack pulls tokenizer and processor folders.

Everything else is optional and worth knowing:

• download_source - modelscope by default, huggingface if you're pulling something Western. This is per-node, so a graph can mix.
• path - point at a file you already have on disk and skip the download entirely. This is also the only way to use a LoRA that isn't in a repo (see the LoRA Load article).
• vram_config - wire a VRAM Config node in here and the per-stage offload dtypes apply to this file.
• quant_config - wire a Quantization Config here to have this particular file quantized on load.
• register_sidecar - the advanced one. Some models aren't in DiffSynth's built-in registry; flip this on and the pack fetches a .json sidecar sitting next to your .safetensors and registers it for the session. It throws if your pattern doesn't end in .safetensors.

Installing the pack

ComfyUI Manager: search DiffSynth-ComfyUI, install, restart. Manually:

pip install git+https://github.com/modelscope/DiffSynth-Studio.git
cd ComfyUI/custom_nodes
git clone https://github.com/modelscope/DiffSynth-ComfyUI.git

For quantization you need the extras, and they are a genuine extra install, not a flag:

pip install "diffsynth[quant] @ git+https://github.com/modelscope/DiffSynth-Studio.git"

The pack's own requirements.txt is just diffsynth>=2.1.9. That matters more than it looks - see below.

Where people get burned

Nothing downloads until the graph runs. ModelConfig calls download_if_necessary() when the node executes, and ComfyUI only executes nodes that feed an output node. A stray ModelConfig floating on the canvas will happily download nothing, forever.

The first queue is 90% waiting. MiniMax H3 is around 42.5 GB of weights; LTX-2 plus its Gemma text encoder is worse. Queue the graph, go make coffee, watch the terminal.

These files don't go in ComfyUI/models/. The pack fetches from its own repos by pattern. Don't go hunting for a checkpoint dropdown that will never appear.

Your node's fields may not match any tutorial. The Loader and Inference nodes are generated at startup by reflecting on the installed DiffSynth pipeline class - so if a field described in an article isn't on your node, your diffsynth is old. Update it the same way you installed it.

Typos fail late. A wrong origin_file_pattern doesn't error at build time; you find out when the loader can't find the component it expected, usually mid-run after a few minutes of loading.