[Feature] HunyuanImage3 allow guidance_scale<=1 in DiT stage

[Fishermanykx]

Purpose

This PR is intended to adjust HunyuanImage3's default behavior that always generated the negative/unconditional branch, so generation can run in single-branch mode when guidance is not enabled.

What This PR Changes

1. Guidance behavior

   • Allows guidance_scale <= 1.0 without forcing it to 1.0 + epsilon.
   • This enables true non-CFG behavior for low-guidance requests.

2. CFG factor control

   • Changes cfg_factor for gen_image from a fixed value to dynamic gating
   • CFG duplication is now enabled only when guidance is actually greater than 1.

3. Tensor layout robustness

   • Replaces view(...) with reshape(...) in the HunyuanImage3 attention output path to avoid runtime errors when tensors are non-contiguous.

Test Plan

Tested on 4x Ascend NPU with v0.18.0.post1 vllm omni

Online

vllm serve "/data/HunyuanImage-3.0/" --omni --port "8091" \
    --tensor_parallel_size 4  \
    --log-stats \
    --stage-configs-path "vllm_omni/platforms/npu/stage_configs/hunyuan_image3_moe_dit.yaml"

client

curl -X POST http://localhost:8091/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": 
        "A cinematic medium shot captures a single Asian woman seated on a chair within a dimly lit room, creating an intimate and theatrical atmosphere. The composition is focused on the subject, rendered with rich colors and intricate textures that evoke a nostalgic and moody feeling.\n\nThe primary subject is a young Asian woman with a thoughtful and expressive countenance, her gaze directed slightly away from the camera. She is seated in a relaxed yet elegant posture on an ornate, vintage armchair. The chair is upholstered in a deep red velvet, its fabric showing detailed, intricate textures and slight signs of wear. She wears a simple, elegant dress in a dark teal hue, the material catching the light in a way that reveals its fine-woven texture. Her skin has a soft, matte quality, and the light delicately models the contours of her face and arms.\n\nThe surrounding room is characterized by its vintage decor, which contributes to the historic and evocative mood. In the immediate background, partially blurred due to a shallow depth of field consistent with a f/2.8 aperture, the wall is covered with wallpaper featuring a subtle, damask pattern. The overall color palette is a carefully balanced interplay of deep teal and rich red hues, creating a visually compelling and cohesive environment. The entire scene is detailed, from the fibers of the upholstery to the subtle patterns on the wall.\n\nThe lighting is highly dramatic and artistic, defined by high contrast and pronounced shadow play. A single key light source, positioned off-camera, projects gobo lighting patterns onto the scene, casting intricate shapes of light and shadow across the woman and the back wall. These dramatic shadows create a strong scense of depth and a theatrical quality. While some shadows are deep and defined, others remain soft, gently wrapping around the subject and preventing the loss of detail in darker areas. The soft focus on the background enhances the intimate feeling, drawing all attention to the expressive subject. The overall image presents a cinematic, photorealistic photography style.",
    "num_inference_steps": 50,
    "guidance_scale": "1.0",
    "n": 1,
    "size": "1024x1024",
    "seed": 42
  }' | jq -r '.data[0].b64_json' | base64 -d > output.png

test plan without vllm omni

torchrun --master_port=10086 --nproc_per_node 4 run_image_gen.py --reproduce --model-id $model  --verbose 0 --image-size 1024x1024 --diff-infer-steps 50 --prompt $prompt 2>&1 | tee "./logs/$(date +%Y%m%d_%H%M%S).log"

Test Result

guidance scale	E2E
5.0	27.256s
1.0	15.895s

guidance scale = 1.0 with vllm omni

guidance scale = 1.0 without vllm omni

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[Fishermanykx]

@gcanlin @Bounty-hunter PTAL

[gcanlin]

Why do we think that hunyuan-image doesn't support guidance_scale <= 1 before?

[Fishermanykx]

Why do we think that hunyuan-image doesn't support guidance_scale <= 1 before?

In line 1013 of vllm_omni/diffusion/models/hunyuan_image_3/pipeline_hunyuan_image_3.py, if guidance_scale <= 1, it will be set to 1.0 + np.finfo(float).eps

[gcanlin]

Is this line equivalent to the official line below?
https://github.com/Tencent-Hunyuan/HunyuanImage-3.0/blob/d280425cf453a153e5846c725af58de39c10b09f/hunyuan_image_3/hunyuan_image_3_pipeline.py#L776

[Fishermanykx]

I think it is

[gcanlin]

LGTM