MD: APG Guider

The standard way to force a model to follow your prompt is CFG, and the standard problem with CFG is that cranking it burns the image - oversaturated, blown-out, "overcooked" results. APG (Adaptive Projected Gradient) is a family of guidance techniques that tries to have it both ways: project the guidance vector onto a cleaner direction so the model follows the prompt hard without the artifacts. This node is MD's fork of that idea, and the pack credits blepping with the original concept.

It's a GUIDER node: feed it model, positive, and negative conditioning, and it returns a guider object you connect to a KSampler's guider input, replacing the built-in CFG guider. If you've ever run a distilled/turbo model and gotten CFG burn at low scale, this is aimed at exactly that failure mode.

How it works

Under the hood it's the classic CFG formula - uncond + (cond - uncond) * scale - but with three corrections on top:

• Orthogonal projection - the guidance correction is projected onto a direction orthogonal to the current prediction, which is the "adaptive projected gradient" trick that stops oversteering. The mode dropdown picks the variant: pure_apg (standard projection) is the recommended default, pre_cfg applies it before CFG scaling, and alt1/alt2 are alternative momentum blends.
• Momentum (momentum, default 0.75) - a running average across steps that smooths the guidance vectors. Positive values stabilize; the source warns negative values oscillate.
• Norm thresholding (norm_threshold, default 2.5) - caps the guidance vector's magnitude so it can't blow out. Lower = safer, weaker.
• Sigma scheduling - start_sigma / end_sigma control when APG is active. The neat part: it's a two-stage CFG. cfg_before applies during the high-sigma active phase (4.0–7.0 recommended), then when APG deactivates at end_sigma, cfg_after takes over (2.0–3.5) so the low-noise detail phase runs gentler. That handoff is the whole "steer hard early, refine softly late" philosophy.

apg_scale (default 4.5) is the strength of the orthogonal correction - 3.0–6.0 is the band; higher enforces adherence but risks burning, same trade as CFG, just wider. predict_image (default True) targets the x0/v-prediction domain rather than epsilon, which the tooltip says works better for modern models. disable_apg turns the whole thing into a plain CFG guider for A/B testing without rewiring - genuinely useful.

The eta input is explicitly marked DEPRECATED - leave it at 0, this fork doesn't use it.

Outputs

apg_guider (wire into KSampler), plus two debug outputs: guidance_plot (a rendered image showing the guidance schedule - you can see where APG is active and where it hands off) and config_summary (a string). There's also an optional yaml_parameters_opt input for advanced multi-stage schedules - a list of dicts with start_sigma/cfg/apg_scale - which overrides the sliders if valid.

The honest take

APG-style guidance is real research (the projection idea is well established), and the sigma-scheduled two-CFG structure is a thoughtful design. But it's a fiddly node from a niche pack - you'll be tuning apg_scale, momentum, and thresholds against your specific model, and the community footprint is small enough that you're mostly on your own. Start with defaults, watch guidance_plot to see the schedule, and only reach for it if plain CFG burn is a problem you actually have.

Installing

It's part of MD Nodes:

cd path/to/ComfyUI/custom_nodes
git clone https://github.com/MDMAchine/ComfyUI_MD_Nodes.git
cd ComfyUI_MD_Nodes && pip install -r requirements.txt

Or via ComfyUI Manager (search MD Nodes), then restart. Heavy requirements (audio libs, matplotlib, client SDKs) come with the pack.