From afd0d7b47b40448341036cea37294fcf3cb2aabd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wenbo=20Ji=E3=80=80=E5=B5=87=E6=96=87=E5=8D=9A?= <36562829+fusheng-ji@users.noreply.github.com> Date: Thu, 22 Oct 2026 15:30:45 +0200 Subject: [PATCH] [Fix] diffusion/flux: use true_cfg_scale as the FLUX CFG weight (#44260) --- docs/cookbook/diffusion/FLUX/FLUX.mdx | 18 +++++++++++++ .../configs/pipeline_configs/flux.py | 6 +++++ .../configs/sample/sampling_params.py | 2 +- .../test/unit/test_flux_true_cfg_scale.py | 27 +++++++++++++++++++ 4 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 python/sglang/multimodal_gen/test/unit/test_flux_true_cfg_scale.py diff --git a/docs/cookbook/diffusion/FLUX/FLUX.mdx b/docs/cookbook/diffusion/FLUX/FLUX.mdx index 15d231228d..4cb69fd80a 100644 --- a/docs/cookbook/diffusion/FLUX/FLUX.mdx +++ b/docs/cookbook/diffusion/FLUX/FLUX.mdx @@ -231,6 +231,24 @@ Use `--lora-path` at startup or the [LoRA management API](/docs/sglang-diffusion - [`XLabs-AI/flux-furry-lora`](https://huggingface.co/XLabs-AI/flux-furry-lora) - [`XLabs-AI/flux-RealismLora`](https://huggingface.co/XLabs-AI/flux-RealismLora) +#### 4.2.4 Negative prompts (true CFG) + +FLUX.1-dev is guidance-distilled: its guidance embedding comes from the server's `--embedded-cfg-scale` (3.5 for FLUX.1), and the requests above run one DiT forward per step. A negative prompt turns on classifier-free guidance, which adds an unconditional forward per step: + +- `--true-cfg-scale` sets the CFG weight, as in diffusers `FluxPipeline`. +- Without `--true-cfg-scale`, the negative prompt uses `--guidance-scale` as the CFG weight. + +```bash +sglang generate \ + --model-path black-forest-labs/FLUX.1-dev \ + --prompt "A red bicycle leaning against a stone wall beside a quiet lake at sunset" \ + --negative-prompt "blurry, distorted, low quality" \ + --true-cfg-scale 2.0 \ + --width 1024 --height 1024 --num-inference-steps 50 --seed 42 +``` + +Keep the weight moderate. On top of the distilled guidance, CFG over-exposes FLUX.1-dev in diffusers as well as in SGLang: at 1024x1024 and 28 steps, about 45% of pixels clip to 0 or 255 at a weight of 4, and 8-15% at 1.5-2. + ## 5. Benchmark ### 5.1 Speedup Benchmark diff --git a/python/sglang/multimodal_gen/configs/pipeline_configs/flux.py b/python/sglang/multimodal_gen/configs/pipeline_configs/flux.py index 6255735d56..ff87a80bca 100644 --- a/python/sglang/multimodal_gen/configs/pipeline_configs/flux.py +++ b/python/sglang/multimodal_gen/configs/pipeline_configs/flux.py @@ -125,6 +125,12 @@ class FluxPipelineConfig(ImagePipelineConfig): def prepare_sigmas(self, sigmas, num_inference_steps): return self._prepare_sigmas(sigmas, num_inference_steps) + def get_classifier_free_guidance_scale(self, batch, guidance_scale: float) -> float: + # true_cfg_scale is the CFG weight when given, as in diffusers FluxPipeline. + if batch.true_cfg_scale is not None: + return batch.true_cfg_scale + return guidance_scale + def prepare_latent_shape(self, batch, batch_size, num_frames): height = 2 * ( batch.height // (self.vae_config.arch_config.vae_scale_factor * 2) diff --git a/python/sglang/multimodal_gen/configs/sample/sampling_params.py b/python/sglang/multimodal_gen/configs/sample/sampling_params.py index c8fa6576cf..78f92976c0 100644 --- a/python/sglang/multimodal_gen/configs/sample/sampling_params.py +++ b/python/sglang/multimodal_gen/configs/sample/sampling_params.py @@ -1411,7 +1411,7 @@ class SamplingParams: "--true-cfg-scale", type=float, dest="true_cfg_scale", - help="True CFG scale for models that distinguish distilled guidance from standard CFG (e.g., Qwen-Image)", + help="True CFG scale for models that distinguish distilled guidance from standard CFG (e.g., Qwen-Image, FLUX.1)", ) add_argument( "--guidance-rescale", diff --git a/python/sglang/multimodal_gen/test/unit/test_flux_true_cfg_scale.py b/python/sglang/multimodal_gen/test/unit/test_flux_true_cfg_scale.py new file mode 100644 index 0000000000..e1430bf4ca --- /dev/null +++ b/python/sglang/multimodal_gen/test/unit/test_flux_true_cfg_scale.py @@ -0,0 +1,27 @@ +import unittest +from types import SimpleNamespace + +from sglang.multimodal_gen.configs.pipeline_configs.flux import ( + Flux2PipelineConfig, + FluxPipelineConfig, +) + + +class TestFluxTrueCFGScale(unittest.TestCase): + def test_true_cfg_scale_is_the_cfg_weight(self): + for config in (FluxPipelineConfig(), Flux2PipelineConfig()): + with self.subTest(config=type(config).__name__): + batch = SimpleNamespace(true_cfg_scale=4.0) + self.assertEqual( + config.get_classifier_free_guidance_scale(batch, 3.5), 4.0 + ) + + def test_guidance_scale_is_the_cfg_weight_without_true_cfg_scale(self): + batch = SimpleNamespace(true_cfg_scale=None) + self.assertEqual( + FluxPipelineConfig().get_classifier_free_guidance_scale(batch, 3.5), 3.5 + ) + + +if __name__ == "__main__": + unittest.main()