feat(diffusers): add HunyuanImage21 to mindone.diffusers #1400

Cui-yshoho · 2025-10-29T08:20:03Z

What does this PR do?

Fixes # (issue)

Adds # (feature)

Before submitting

This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
Did you read the contributor guideline?
Did you make sure to update the documentation with your changes? E.g. record bug fixes or new features in What's New. Here are the
documentation guidelines
Did you build and run the code without any errors?
Did you report the running environment (NPU type/MS version) and performance in the doc? (better record it for data loading, model inference, or training tasks)
Did you write any new necessary tests?

Who can review?

Anyone in the community is free to review the PR once the tests have passed. Feel free to tag
members/contributors who may be interested in your PR.

@xxx

gemini-code-assist · 2025-10-29T08:21:50Z

Summary of Changes

Hello @Cui-yshoho, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly expands the capabilities of the mindone.diffusers library by integrating the powerful HunyuanImage2.1 text-to-image generation model. It introduces new model architectures and pipelines, alongside a sophisticated guidance system to enhance image generation quality and control. The underlying modular pipeline framework has also received several quality-of-life improvements, making it more robust and user-friendly for future developments.

Highlights

HunyuanImage2.1 Integration: Added comprehensive support for HunyuanImage2.1, including its dedicated VAE models (AutoencoderKLHunyuanImage, AutoencoderKLHunyuanImageRefiner), a new Transformer model (HunyuanImageTransformer2DModel), and two new pipelines (HunyuanImagePipeline, HunyuanImageRefinerPipeline).
Enhanced Guidance Mechanisms: Introduced AdaptiveProjectedMixGuidance for advanced guidance strategies, combining Adaptive Projected Guidance (APG) and Classifier-Free Guidance (CFG). The core BaseGuidance class was also refactored to include an enabled parameter, a new method for easy configuration cloning, and improved state representation for better debugging and control.
Modular Pipeline Refinements: Streamlined the modular pipeline architecture by updating input preparation for guiders, consolidating load_components functionality, and improving how pipeline configurations are loaded, including a fallback mechanism for standard model_index.json files. Typo corrections and clearer docstrings were also applied across various modular pipeline blocks.
MindSpore Compatibility and Utilities: Implemented scaled_dot_product_attention for MindSpore, ensuring better compatibility and performance for attention mechanisms. Minor documentation updates were made to clarify 're-use' vs. 'reuse' terminology.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request adds support for the HunyuanImage2.1 model, including new pipelines, models, and documentation. A significant part of the changes involves a refactoring of the guider classes, which improves their API and consistency. The changes are extensive and well-structured. However, I've found a few critical issues, including incorrect API usage for MindSpore and a potential security vulnerability in the remote code trust logic. There are also some minor issues in the documentation that should be addressed for clarity.

gemini-code-assist · 2025-10-29T08:25:53Z

mindone/diffusers/guiders/adaptive_projected_guidance_mix.py

+            sliced_data = self.running_average[slice_indices]
+
+            # Format the slice for display (convert to float32 for numpy compatibility with bfloat16)
+            slice_str = str(sliced_data.detach().float().cpu().numpy())


This line appears to be copied from a PyTorch implementation. The methods .detach(), .cpu(), and .numpy() are not available on MindSpore tensors and will cause a runtime error. Please use the MindSpore equivalents. For example, .asnumpy() should be used to convert a tensor to a NumPy array, and .to(ms.float32) to cast the dtype.

Suggested change

slice_str = str(sliced_data.detach().float().cpu().numpy())

slice_str = str(sliced_data.to(ms.float32).asnumpy())

gemini-code-assist · 2025-10-29T08:25:53Z

mindone/diffusers/modular_pipelines/modular_pipeline.py

+        if not has_remote_code and trust_remote_code:
            raise ValueError(
                "Selected model repository does not happear to have any custom code or does not have a valid `config.json` file."
            )


The logic for handling trust_remote_code appears to be incorrect. The condition if not has_remote_code and trust_remote_code: will fail to raise an error when has_remote_code is True and trust_remote_code is False. This is a security risk as it could allow untrusted remote code to be executed. The logic should be inverted to raise an error when remote code is present but not trusted.

Suggested change

if not has_remote_code and trust_remote_code:

raise ValueError(

"Selected model repository does not happear to have any custom code or does not have a valid `config.json` file."

)

if has_remote_code and not trust_remote_code:

raise ValueError(

f"Repo {pretrained_model_name_or_path} has custom code which must be trusted to be used. Please set `trust_remote_code=True`."

)

gemini-code-assist · 2025-10-29T08:25:53Z

mindone/diffusers/guiders/adaptive_projected_guidance.py

+            sliced_data = self.running_average[slice_indices]
+
+            # Format the slice for display (convert to float32 for numpy compatibility with bfloat16)
+            slice_str = str(sliced_data.float().numpy())


The method .float() is a PyTorch API. The MindSpore equivalent is .to(ms.float32). Also, while .numpy() is an alias for .asnumpy(), using .asnumpy() is more idiomatic for MindSpore and less prone to confusion.

Suggested change

slice_str = str(sliced_data.float().numpy())

slice_str = str(sliced_data.to(ms.float32).asnumpy())

gemini-code-assist · 2025-10-29T08:25:53Z

docs/diffusers/api/models/autoencoder_kl_hunyuanimage.md

+
+# AutoencoderKLHunyuanImage
+
+The 2D variational autoencoder (VAE) model with KL loss used in [HunyuanImage2.1].


The link for HunyuanImage2.1 is missing. It should point to the model's repository for user reference, similar to other documentation files in this PR.

Suggested change

The 2D variational autoencoder (VAE) model with KL loss used in [HunyuanImage2.1].

The 2D variational autoencoder (VAE) model with KL loss used in [HunyuanImage2.1](https://github.com/Tencent-Hunyuan/HunyuanImage-2.1).

gemini-code-assist · 2025-10-29T08:25:53Z

docs/diffusers/api/pipelines/hunyuanimage21.md

+
+## HunyuanImage-2.1-Distilled
+
+use `distilled_guidance_scale` with the guidance-distilled checkpoint, 


This sentence is incomplete and grammatically incorrect. It should be rephrased to be a complete and clear instruction for the user.

Suggested change

use `distilled_guidance_scale` with the guidance-distilled checkpoint,

Use `distilled_guidance_scale` with the guidance-distilled checkpoint.

gemini-code-assist · 2025-10-29T08:25:53Z

docs/diffusers/api/pipelines/hunyuanimage21.md

+    distilled_guidance_scale=3.25,
+    height=2048,
+    width=2048,
+    generator=generator,


The generator variable is used in this code snippet but is not defined. This will cause a NameError for users who copy and paste this example. Please either define the generator or remove it if it's not essential for the example.

Cui-yshoho requested a review from vigo999 as a code owner October 29, 2025 08:20

gemini-code-assist bot reviewed Oct 29, 2025

View reviewed changes

Cui-yshoho force-pushed the hunyuanimage2_1 branch 11 times, most recently from 1ec8c2e to e07aa90 Compare October 30, 2025 07:04

add hunyuanimage

bdbe81b

Cui-yshoho force-pushed the hunyuanimage2_1 branch from e07aa90 to bdbe81b Compare October 30, 2025 07:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(diffusers): add HunyuanImage21 to mindone.diffusers #1400

feat(diffusers): add HunyuanImage21 to mindone.diffusers #1400

Uh oh!

Cui-yshoho commented Oct 29, 2025

Uh oh!

gemini-code-assist bot commented Oct 29, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Oct 29, 2025

Uh oh!

gemini-code-assist bot Oct 29, 2025

Uh oh!

gemini-code-assist bot Oct 29, 2025

Uh oh!

gemini-code-assist bot Oct 29, 2025

Uh oh!

gemini-code-assist bot Oct 29, 2025

Uh oh!

gemini-code-assist bot Oct 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	slice_str = str(sliced_data.detach().float().cpu().numpy())
	slice_str = str(sliced_data.to(ms.float32).asnumpy())

	slice_str = str(sliced_data.float().numpy())
	slice_str = str(sliced_data.to(ms.float32).asnumpy())


		# AutoencoderKLHunyuanImage

		The 2D variational autoencoder (VAE) model with KL loss used in [HunyuanImage2.1].


		## HunyuanImage-2.1-Distilled

		use `distilled_guidance_scale` with the guidance-distilled checkpoint,

feat(diffusers): add HunyuanImage21 to mindone.diffusers #1400

Are you sure you want to change the base?

feat(diffusers): add HunyuanImage21 to mindone.diffusers #1400

Uh oh!

Conversation

Cui-yshoho commented Oct 29, 2025

What does this PR do?

Before submitting

Who can review?

Uh oh!

gemini-code-assist bot commented Oct 29, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant