[Fix] HunyuanImage-3.0: unify naming hunyuan_image_3 → hunyuan_image3 (#2712)

docs/design/feature/expert_parallel.md

@@ -207,9 +207,9 @@ Complete examples in the codebase:
 
 | Model | Path | Pattern | Notes |
 |-------|------|---------|-------|
-| **HunyuanImage3.0** | `vllm_omni/diffusion/models/hunyuan_image_3/hunyuan_image_3_transformer.py` | Standard EP | Full implementation with validation |
+| **HunyuanImage3.0** | `vllm_omni/diffusion/models/hunyuan_image3/hunyuan_image3_transformer.py` | Standard EP | Full implementation with validation |
 | **EP Tests** | `vllm-omni/tests/e2e/offline_inference/test_expert_parallel.py` | E2E testing | EP correctness and performance |
-| **Constraint Tests** | `vllm-omni/tests/diffusion/models/hunyuan_image_3/test_hunyuan_fused_moe.py` | Unit testing | Validation logic |
+| **Constraint Tests** | `vllm-omni/tests/diffusion/models/hunyuan_image3/test_hunyuan_fused_moe.py` | Unit testing | Validation logic |
 
 ---
 ## Summary

tests/diffusion/models/hunyuan_image3/test_hunyuan_fused_moe.py

@@ -12,7 +12,7 @@ class TestSetForwardContextNumTokens:
 
     def test_sets_num_tokens_when_context_available(self, mocker):
         """num_tokens should be set on ForwardContext when available."""
-        import vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe as hunyuan_moe
+        import vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe as hunyuan_moe
 
         mock_ctx = mocker.MagicMock()
         del mock_ctx.in_profile_run  # simulate missing attr
@@ -26,7 +26,7 @@ class TestSetForwardContextNumTokens:
 
     def test_sets_in_profile_run_only_if_missing(self, mocker):
         """in_profile_run should not be overwritten if already set."""
-        import vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe as hunyuan_moe
+        import vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe as hunyuan_moe
 
         mock_ctx = mocker.MagicMock()
         mock_ctx.in_profile_run = True  # already set
@@ -40,7 +40,7 @@ class TestSetForwardContextNumTokens:
 
     def test_noop_when_context_unavailable(self, mocker):
         """Should do nothing when ForwardContext is not available."""
-        import vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe as hunyuan_moe
+        import vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe as hunyuan_moe
 
         mocker.patch.object(hunyuan_moe._vllm_fc, "is_forward_context_available", return_value=False)
         mock_get = mocker.patch.object(hunyuan_moe._vllm_fc, "get_forward_context")
@@ -55,11 +55,11 @@ class TestHunyuanFusedMoEPlatformDispatch:
 
     def test_default_platform_uses_default_impl_qualname(self, mocker):
         """HunyuanFusedMoE should resolve the impl class from the platform hook."""
-        import vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe as hunyuan_moe
+        import vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe as hunyuan_moe
 
         mock_platform = mocker.MagicMock()
         mock_platform.get_diffusion_model_impl_qualname.return_value = (
-            "vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe.HunyuanFusedMoEDefault"
+            "vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe.HunyuanFusedMoEDefault"
         )
 
         mocker.patch.object(
@@ -71,7 +71,7 @@ class TestHunyuanFusedMoEPlatformDispatch:
         mock_impl = mocker.MagicMock()
         mock_resolve.return_value = mock_impl
 
-        from vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe import (
+        from vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe import (
             HunyuanFusedMoE,
         )
 
@@ -80,7 +80,7 @@ class TestHunyuanFusedMoEPlatformDispatch:
         mock_platform.prepare_diffusion_op_runtime.assert_called_once_with("hunyuan_fused_moe")
         mock_platform.get_diffusion_model_impl_qualname.assert_called_once_with("hunyuan_fused_moe")
         mock_resolve.assert_called_once_with(
-            "vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe.HunyuanFusedMoEDefault"
+            "vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe.HunyuanFusedMoEDefault"
         )
         mock_impl.assert_called_once_with(prefix="")
 
@@ -90,7 +90,7 @@ class TestHunyuanFusedMoEFactory:
 
     def test_new_delegates_to_impl_class(self, mocker):
         """HunyuanFusedMoE(prefix=..., **kwargs) should instantiate and return impl instance."""
-        import vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe as hunyuan_moe
+        import vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe as hunyuan_moe
 
         class MockImpl:
             def __init__(self, *, prefix: str = "", **kwargs):
@@ -104,7 +104,7 @@ class TestHunyuanFusedMoEFactory:
         mock_impl_class = mocker.MagicMock(return_value=MockImpl(prefix="test", a=1))
         mocker.patch.object(hunyuan_moe, "resolve_obj_by_qualname", return_value=mock_impl_class)
 
-        from vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe import (
+        from vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe import (
             HunyuanFusedMoE,
         )
 
@@ -119,7 +119,7 @@ class TestHunyuanFusedMoEFactory:
 
     def test_make_expert_params_mapping_delegates_to_impl(self, mocker):
         """make_expert_params_mapping should delegate to impl class method."""
-        import vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe as hunyuan_moe
+        import vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe as hunyuan_moe
 
         expected_mapping = [("a", "b", 0, "c")]
         mock_platform = mocker.MagicMock()
@@ -130,7 +130,7 @@ class TestHunyuanFusedMoEFactory:
         mock_impl_class.make_expert_params_mapping = mocker.MagicMock(return_value=expected_mapping)
         mocker.patch.object(hunyuan_moe, "resolve_obj_by_qualname", return_value=mock_impl_class)
 
-        from vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe import (
+        from vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe import (
             HunyuanFusedMoE,
         )
 

tests/e2e/offline_inference/test_hunyuanimage3_text2img.py

@@ -17,7 +17,7 @@ PROMPT = "A brown and white dog is running on the grass"
 MODEL_NAME = "tencent/HunyuanImage-3.0"
 LOCAL_CLIP_PATH = "openai/clip-vit-base-patch32"
 REPO_ROOT = Path(__file__).resolve().parents[3]
-STAGE_CONFIG_PATH = REPO_ROOT / "vllm_omni" / "model_executor" / "stage_configs" / "hunyuan_image_3_moe.yaml"
+STAGE_CONFIG_PATH = REPO_ROOT / "vllm_omni" / "model_executor" / "stage_configs" / "hunyuan_image3_moe.yaml"
 
 pytestmark = [pytest.mark.advanced_model, pytest.mark.diffusion]
 

vllm_omni/diffusion/models/hunyuan_image3/__init__.py

@@ -2,12 +2,12 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 """Hunyuan Image 3 diffusion model components."""
 
-from vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe import HunyuanFusedMoE
-from vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_image_3_transformer import (
+from vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe import HunyuanFusedMoE
+from vllm_omni.diffusion.models.hunyuan_image3.hunyuan_image3_transformer import (
     HunyuanImage3Model,
     HunyuanImage3Text2ImagePipeline,
 )
-from vllm_omni.diffusion.models.hunyuan_image_3.pipeline_hunyuan_image_3 import (
+from vllm_omni.diffusion.models.hunyuan_image3.pipeline_hunyuan_image3 import (
     HunyuanImage3Pipeline,
 )
 

vllm_omni/diffusion/models/hunyuan_image3/hunyuan_image3_tokenizer.py

@@ -13,7 +13,7 @@ from diffusers.utils.outputs import BaseOutput
 from transformers import AutoTokenizer
 from vllm.logger import init_logger
 
-from .hunyuan_image_3_transformer import ImageInfo, JointImageInfo, default
+from .hunyuan_image3_transformer import ImageInfo, JointImageInfo, default
 
 logger = init_logger(__name__)
 

vllm_omni/diffusion/models/hunyuan_image3/hunyuan_image3_transformer.py

@@ -74,7 +74,7 @@ from vllm_omni.diffusion.distributed.sp_plan import (
 )
 from vllm_omni.diffusion.distributed.utils import get_local_device
 from vllm_omni.diffusion.layers.rope import RotaryEmbedding
-from vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe import HunyuanFusedMoE
+from vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe import HunyuanFusedMoE
 
 logger = logging.getLogger(__name__)
 

vllm_omni/diffusion/models/hunyuan_image3/pipeline_hunyuan_image3.py

@@ -25,8 +25,8 @@ from vllm_omni.diffusion.profiler.diffusion_pipeline_profiler import DiffusionPi
 from vllm_omni.diffusion.request import OmniDiffusionRequest
 
 from .autoencoder import AutoencoderKLConv3D
-from .hunyuan_image_3_tokenizer import TokenizerWrapper
-from .hunyuan_image_3_transformer import (
+from .hunyuan_image3_tokenizer import TokenizerWrapper
+from .hunyuan_image3_transformer import (
     CausalMMOutputWithPast,
     HunyuanImage3ImageProcessor,
     HunyuanImage3Model,

vllm_omni/diffusion/registry.py

@@ -119,8 +119,8 @@ _DIFFUSION_MODELS = {
         "FluxKontextPipeline",
     ),
     "HunyuanImage3ForCausalMM": (
-        "hunyuan_image_3",
-        "pipeline_hunyuan_image_3",
+        "hunyuan_image3",
+        "pipeline_hunyuan_image3",
         "HunyuanImage3Pipeline",
     ),
     "Flux2KleinPipeline": (

vllm_omni/platforms/interface.py

@@ -64,7 +64,7 @@ class OmniPlatform(Platform):
     @classmethod
     def get_diffusion_model_impl_qualname(cls, op_name: str) -> str:
         if op_name == "hunyuan_fused_moe":
-            return "vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe.HunyuanFusedMoEDefault"
+            return "vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe.HunyuanFusedMoEDefault"
         raise NotImplementedError(f"Unsupported diffusion model op: {op_name}")
 
     @classmethod

vllm_omni/platforms/musa/platform.py

@@ -39,7 +39,7 @@ class MUSAOmniPlatform(OmniPlatform, MUSAPlatformBase):
     def get_diffusion_model_impl_qualname(cls, op_name: str) -> str:
         # MUSA uses default implementations for diffusion ops
         if op_name == "hunyuan_fused_moe":
-            return "vllm_omni.diffusion.models.hunyuan_image_3.hunyuan_fused_moe.HunyuanFusedMoEDefault"
+            return "vllm_omni.diffusion.models.hunyuan_image3.hunyuan_fused_moe.HunyuanFusedMoEDefault"
         return super().get_diffusion_model_impl_qualname(op_name)
 
     @classmethod