Nodes/ComfyUI-Sigmax/Qwen Image 2.1 Sigma Scheduler
ComfyUI Node

Qwen Image 2.1 Sigma Scheduler

Qwen Image 2.1's Shift Depends on Your Resolution — This Node Does the Math

By rookiestar28·Created 4 months ago·Updated 20 days ago· 12
Qwen Image 2.1 Sigma Scheduler
    • sigmas
    • schedule_info
    ◄mode▾►
    ◄steps25►
    ◄target_source▾►
    ◄width0►
    ◄height0►
    ◄image_seq_len0►
    ◄strict_officialtrue►
    ◄start_step0►
    ◄end_step-1►

    The problem this solves

    On every flow-matching model, shift is roughly what replaced the old scheduler dropdown - it decides how sampling effort splits between "what is this thing" and "how does it look." It's model-specific too: Z-Image Turbo wants 7 where ComfyUI's default is 3. Get it wrong and you're not running a slightly worse version of the model, you're running a different curve.

    Qwen Image 2.1 is annoying because there isn't one correct value. In the Diffusers lane the shift is derived from how many latent tokens your image is worth: small canvas, small shift; big canvas, bigger shift. So the schedule that gives you clean 1024×1024 won't necessarily give you clean 1536×864.

    Sigmax.QwenImage21SigmaScheduler builds that SIGMAS tensor for you from the reference implementations, with the resolution math done. It's a schedule builder and nothing else - no weights, no model patching, no sampler choice.

    Two lanes, and you should know which one you're in

    mode has exactly two options, and they are not interchangeable.

    Comfy Native reproduces ComfyUI's own Qwen 2.1 sampling: the 10,000-entry simple flow table, an exponential mu shift at a fixed mu = 0.69, then the terminal zero. Because mu is fixed, this lane is resolution-independent - that's the point of it.

    Diffusers Dynamic is the Hugging Face lane: a reciprocal step grid with mu computed from your target size:

    mu = 0.5 + (tokens - 256) * (0.9 - 0.5) / (8192 - 256)
    

    That's 0.5 at 256 tokens, 0.9 at 8192, unclamped past either end. Tokens are (width / 16) * (height / 16) - one per 16×16 latent pixel, deliberately without the packing or reference-image prefix tokens original Qwen Image uses, because those would compute the wrong shift for 2.1. Then the tail is stretched so the last nonzero sigma lands at 0.02 before the appended zero.

    Inputs you'll actually set

    Most of these fields exist to stop you feeding the node contradictory instructions, so the rules matter more than the widgets:

    • target_source - None (Native), Dimensions, or Target Tokens. Native mode requires None (Native) and zeroes everywhere else. Dynamic mode requires exactly one live source: Dimensions with positive width/height divisible by 32 and image_seq_len at 0, or Target Tokens with a positive image_seq_len and dimensions at 0. Mix them and you get an error, by design - zero means "inactive", not "infer it".
    • steps - default 25 native / 40 dynamic. See strict_official below.
    • strict_official (default on) - refuses any step count that isn't the lane's baseline. It's a guardrail that stops you quietly running an unvalidated recipe, and it does not re-count steps when you flip mode. Turn it off deliberately if you want a custom count.
    • start_step / end_step - slices the schedule; end_step = -1 means "to the end". Handy for splitting a hires or refiner pass and taking only part of the curve.

    Outputs are sigmas (SIGMAS) and schedule_info (a JSON string carrying source revision, mu, effective dimensions, token count, slicing, license and warnings).

    Wiring it up

    sigmas goes into a custom-sampling path that accepts external sigmas - the SamplerCustomAdvanced family - alongside your sampler and guider. schedule_info is a plain string; park a text display node on it and you get a receipt of which curve you actually ran, which is worth having when an output changes and you can't remember what you touched.

    Then leave it alone. This is the one that bites people: no BasicScheduler, no second scheduler, no ModelSamplingAuraFlow after it. The curve already contains the shift. Run it through another scheduler and you've shifted twice - and nothing will error, it'll just look bad.

    Install

    Manager: search ComfyUI-Sigmax, install, restart. Git:

    cd ComfyUI/custom_nodes
    git clone https://github.com/rookiestar28/ComfyUI-Sigmax comfyui-sigmax
    

    Note the folder name - the pack expects custom_nodes/comfyui-sigmax. Then restart and look for nodes under Sigmax. in the menu.

    The good news: zero runtime dependencies. pyproject.toml declares an empty dependencies list, so there's no pip step - and no model downloads either, since this node never fetches weights. You need Python 3.10+ and ComfyUI 0.29.0+.

    Where people get burned

    The errors are almost all contract violations, and they're readable: native mode with a nonzero width, dynamic mode with both tokens and dimensions, Target Tokens with 0 tokens, a dimension that isn't a multiple of 32. Fix the input the error names rather than flipping modes to dodge it. And changing mode does not change steps - Dynamic with 25 steps and strict_official on just errors out.

    Second thing worth knowing: the license. Qwen Image 2.1's model materials sit under the Qwen Research License, noncommercial research and evaluation only, with separate authorization for commercial use. Different regime from the Apache-2.0 Qwen Image 1.x line, and worth knowing before you build a product on it.

    One last expectation-setter: the author validates the schedule math and model-free execution, and explicitly does not claim image-quality parity. What you get is the reference curve, computed correctly for your resolution, with a receipt - which is what you want when you're chasing why one aspect ratio keeps going soft.

    CategorySigmax/scheduling

    Inputs (9)

    NameTypeDefaultDescription
    modeCOMBO2 options: Comfy Native, Diffusers Dynamic
    stepsINT251–10000Native baseline 25; dynamic baseline 40; strict rejects other counts.
    target_sourceCOMBO3 options: None (Native), Dimensions, Target Tokens
    widthINT00–1000000Dimensions only: positive multiple of 32. Otherwise keep zero.
    heightINT00–1000000Dimensions only: positive multiple of 32. Otherwise keep zero.
    image_seq_lenINT00–1000000Target Tokens only: target latent tokens without packing or reference images. Otherwise zero.
    strict_officialBOOLEANtrue—
    start_stepINT00–9999—
    end_stepINT-1-1–10000—

    Outputs (2)

    NameTypeDescription
    sigmasSIGMAS—
    schedule_infoSTRING—