[Model] Add Hunyuan Image3 AR Support

[usberkeley]

Purpose

This PR adds support for the Hunyuan Image3 model to vLLM-Omni. Hunyuan Image3 is a multimodal image generation model developed by Tencent, supporting text-to-image generation tasks.

Test Plan

1. Text input test

• GPU: 8 x L40S (48GB)
• TP: 8

Note: The default configuration in hunyuan_image_3_moe.yaml is tensor_parallel_size: 8.

from vllm_omni.entrypoints.omni import Omni

if __name__ == "__main__":
    omni = Omni(model="tencent/HunyuanImage-3.0")
    prompts = [
    {
        "prompt": "<|im_start|>system\nYou are Qwen.<|im_end|>\n<|im_start|>user\nExplain the system architecture for a scalable audio generation pipeline. Answer in 15 words.<|im_end|>\n<|im_start|>assistant\n",
        "modalities": ["text"]
    }
    ]
    omni_outputs = omni.generate(prompts)
    print(omni_outputs[0].request_output[0].outputs[0].text)

2. Multimodal input test
   TODO

Test Result

TODO

---

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.
• (Optional) Release notes update. If your change is user facing, please update the release notes draft.

BEFORE SUBMITTING, PLEASE READ https://github.com/vllm-project/vllm-omni/blob/main/CONTRIBUTING.md (anything written below this line will be removed by GitHub Actions)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bb011f27c7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[hsliuustc0106]

please paste your test example command

[usberkeley]

please paste your test example command

Hi @hsliuustc0106

1. Text input test

• GPU: 8 x L40S (48GB)
• TP: 8

Note: The default configuration in hunyuan_image_3_moe.yaml is tensor_parallel_size: 8.

from vllm_omni.entrypoints.omni import Omni

if __name__ == "__main__":
    omni = Omni(model="tencent/HunyuanImage-3.0")
    prompts = [
    {
        "prompt": "<|im_start|>system\nYou are Qwen.<|im_end|>\n<|im_start|>user\nExplain the system architecture for a scalable audio generation pipeline. Answer in 15 words.<|im_end|>\n<|im_start|>assistant\n",
        "modalities": ["text"]
    }
    ]
    omni_outputs = omni.generate(prompts)
    print(omni_outputs[0].request_output[0].outputs[0].text)

[Copilot]

Pull request overview

Adds initial vLLM-Omni autoregressive (AR) integration for Tencent’s Hunyuan Image3 model, including model registration and a default stage config.

Changes:

• Updates AR GPU runner postprocessing to use a shared multimodal-output extraction helper.
• Registers HunyuanImage3ForCausalMM in the Omni model registry.
• Introduces a new Hunyuan Image3 model implementation + utilities and a new stage config YAML.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
vllm_omni/worker/gpu_ar_model_runner.py	Switches to extract_multimodal_outputs for postprocessing model outputs.
vllm_omni/model_executor/stage_configs/hunyuan_image_3_moe.yaml	Adds a default stage config for running Hunyuan Image3 with the AR worker/scheduler.
vllm_omni/model_executor/models/registry.py	Registers the Hunyuan Image3 model architecture for lazy loading.
vllm_omni/model_executor/models/hunyuan_image3_0/hunyuan_image3_0_utils.py	Adds Hunyuan-specific RoPE2D + image KV cache helper utilities.
vllm_omni/model_executor/models/hunyuan_image3_0/hunyuan_image3_0.py	Adds the main Hunyuan Image3 model implementation (decoder, attention, MoE, weight loading).
vllm_omni/model_executor/models/hunyuan_image3_0/__init__.py	Exposes the new model class for import.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[david6666666]

any updated? Tencent has just released https://huggingface.co/tencent/HunyuanImage-3.0-Instruct https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil

[usberkeley]

any updated? Tencent has just released https://huggingface.co/tencent/HunyuanImage-3.0-Instruct https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil

Got it. we are working on image encoder and will follow up the update of new release

[usberkeley]

Hi @princepride

When you have a moment, please review this code. thanks!

[princepride]

@usberkeley Can you rebase your code first, we have changed some code in ar_model_runner.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b8d58b560e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[princepride]

@usberkeley pre-commit failed, PTAL

[princepride]

@usberkeley good job! just a little advice.

[princepride]

@usberkeley I think as for AR model, it should have text as the output

[princepride]

@usberkeley I used transformers execute your prompt

[hsliuustc0106]

This PR adds 3057 lines of new model code with ZERO test coverage. Add tests to verify: (1) model loads correctly, (2) forward pass produces expected output shapes, (3) memory usage is reasonable, (4) integration with vllm-omni pipeline works. Without tests, we cannot validate correctness or prevent regressions.

[hsliuustc0106]

This config file has no schema validation or documentation. Add comments explaining each parameter's purpose, valid ranges, and default values. Consider adding a schema validator to catch configuration errors early.

[princepride]

@vllm-omni-reviewer

[usberkeley]

@vllm-omni-reviewer

[lishunyang12]

Left a couple more comments on the latest revision. The mRoPE addition looks solid. Main remaining concern is the load_weights indentation bug and dead code.

[hsliuustc0106]

@vllm-omni-reviewer

这个哥们好像不干活了，我明天看看为啥

[princepride]

Please remove it, we don't need.