Initial commit.

.gitignore

@@ -0,0 +1,288 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
+#  project, it is recommended to include the following files:
+#  .idea/
+#  *.iml
+#  *.ipr
+#  *.iws
+.idea/
+*.iml
+*.ipr
+*.iws
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Windows
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# Linux
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+# Project specific
+# Output directories
+outputs/
+outputs_video/
+states/
+exp_logs/
+my_exps/
+vis/
+
+# Data and model files
+data_tools/
+*.pkl
+*.safetensors
+*.pt
+*.bin
+*.h5
+*.hdf5
+
+# Environment files
+scripts/env.sh
+
+# Keep specific files
+!assets/*.png
+
+# Linting and formatting
+.ruff_cache/
+.black/
+.isort.cfg
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+
+# Logs
+*.log
+logs/
+
+# Cache directories
+.cache/
+cache/

LICENSE

@@ -0,0 +1,77 @@
+TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT
+Tencent HunyuanImage 2.1 Release Date: September 8, 2025
+THIS LICENSE AGREEMENT DOES NOT APPLY IN THE EUROPEAN UNION, UNITED KINGDOM AND SOUTH KOREA AND IS EXPRESSLY LIMITED TO THE TERRITORY, AS DEFINED BELOW.
+By clicking to agree or by using, reproducing, modifying, distributing, performing or displaying any portion or element of the Tencent Hunyuan Works, including via any Hosted Service, You will be deemed to have recognized and accepted the content of this Agreement, which is effective immediately.
+1.	DEFINITIONS.
+a.	“Acceptable Use Policy” shall mean the policy made available by Tencent as set forth in the Exhibit A.
+b.	“Agreement” shall mean the terms and conditions for use, reproduction, distribution, modification, performance and displaying of Tencent Hunyuan Works or any portion or element thereof set forth herein.
+c.	“Documentation” shall mean the specifications, manuals and documentation for Tencent Hunyuan made publicly available by Tencent.
+d.	“Hosted Service” shall mean a hosted service offered via an application programming interface (API), web access, or any other electronic or remote means.
+e.	“Licensee,” “You” or “Your” shall mean a natural person or legal entity exercising the rights granted by this Agreement and/or using the Tencent Hunyuan Works for any purpose and in any field of use.
+f.	“Materials” shall mean, collectively, Tencent’s proprietary Tencent Hunyuan and Documentation (and any portion thereof) as made available by Tencent under this Agreement.
+g.	“Model Derivatives” shall mean all: (i) modifications to Tencent Hunyuan or any Model Derivative of Tencent Hunyuan; (ii) works based on Tencent Hunyuan or any Model Derivative of Tencent Hunyuan; or (iii) any other machine learning model which is created by transfer of patterns of the weights, parameters, operations, or Output of Tencent Hunyuan or any Model Derivative of Tencent Hunyuan, to that model in order to cause that model to perform similarly to Tencent Hunyuan or a Model Derivative of Tencent Hunyuan, including distillation methods, methods that use intermediate data representations, or methods based on the generation of synthetic data Outputs by Tencent Hunyuan or a Model Derivative of Tencent Hunyuan for training that model. For clarity, Outputs by themselves are not deemed Model Derivatives.
+h.	“Output” shall mean the information and/or content output of Tencent Hunyuan or a Model Derivative that results from operating or otherwise using Tencent Hunyuan or a Model Derivative, including via a Hosted Service.
+i.	“Tencent,” “We” or “Us” shall mean the applicable entity or entities in the Tencent corporate family that own(s) intellectual property or other rights embodied in or utilized by the Materials.
+j.	“Tencent Hunyuan” shall mean the large language models, text/image/video/audio/3D generation models, and multimodal large language models and their software and algorithms, including trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code and other elements of the foregoing made publicly available by Us, including, without limitation to, Tencent HunyuanImage 2.1 released at [https://github.com/Tencent-Hunyuan/HunyuanImage-2.1/blob/master/LICENSE；https://huggingface.co/tencent/HunyuanImage-2.1/blob/main/LICENSE].
+k.	“Tencent Hunyuan Works” shall mean: (i) the Materials; (ii) Model Derivatives; and (iii) all derivative works thereof.
+l.	“Territory” shall mean the worldwide territory, excluding the territory of the European Union, United Kingdom and South Korea. 
+m.	“Third Party” or “Third Parties” shall mean individuals or legal entities that are not under common control with Us or You.
+n.	“including” shall mean including but not limited to.
+2.	GRANT OF RIGHTS.
+We grant You, for the Territory only, a non-exclusive, non-transferable and royalty-free limited license under Tencent’s intellectual property or other rights owned by Us embodied in or utilized by the Materials to use, reproduce, distribute, create derivative works of (including Model Derivatives), and make modifications to the Materials, only in accordance with the terms of this Agreement and the Acceptable Use Policy, and You must not violate (or encourage or permit anyone else to violate) any term of this Agreement or the Acceptable Use Policy.
+3.	DISTRIBUTION.
+You may, subject to Your compliance with this Agreement, distribute or make available to Third Parties the Tencent Hunyuan Works, exclusively in the Territory, provided that You meet all of the following conditions:
+a.	You must provide all such Third Party recipients of the Tencent Hunyuan Works or products or services using them a copy of this Agreement;
+b.	You must cause any modified files to carry prominent notices stating that You changed the files;
+c.	You are encouraged to: (i) publish at least one technology introduction blogpost or one public statement expressing Your experience of using the Tencent Hunyuan Works; and (ii) mark the products or services developed by using the Tencent Hunyuan Works to indicate that the product/service is “Powered by Tencent Hunyuan”; and
+d.	All distributions to Third Parties (other than through a Hosted Service) must be accompanied by a “Notice” text file that contains the following notice: “Tencent Hunyuan is licensed under the Tencent Hunyuan Community License Agreement, Copyright © 2025 Tencent. All Rights Reserved. The trademark rights of “Tencent Hunyuan” are owned by Tencent or its affiliate.”
+You may add Your own copyright statement to Your modifications and, except as set forth in this Section and in Section 5, may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Model Derivatives as a whole, provided Your use, reproduction, modification, distribution, performance and display of the work otherwise complies with the terms and conditions of this Agreement (including as regards the Territory). If You receive Tencent Hunyuan Works from a Licensee as part of an integrated end user product, then this Section 3 of this Agreement will not apply to You.
+4.	ADDITIONAL COMMERCIAL TERMS.
+If, on the Tencent Hunyuan version release date, the monthly active users of all products or services made available by or for Licensee is greater than 100 million monthly active users in the preceding calendar month, You must request a license from Tencent, which Tencent may grant to You in its sole discretion, and You are not authorized to exercise any of the rights under this Agreement unless or until Tencent otherwise expressly grants You such rights.
+5.	RULES OF USE.
+a.	Your use of the Tencent Hunyuan Works must comply with applicable laws and regulations (including trade compliance laws and regulations) and adhere to the Acceptable Use Policy for the Tencent Hunyuan Works, which is hereby incorporated by reference into this Agreement. You must include the use restrictions referenced in these Sections 5(a) and 5(b) as an enforceable provision in any agreement (e.g., license agreement, terms of use, etc.) governing the use and/or distribution of Tencent Hunyuan Works and You must provide notice to subsequent users to whom You distribute that Tencent Hunyuan Works are subject to the use restrictions in these Sections 5(a) and 5(b).
+b.	You must not use the Tencent Hunyuan Works or any Output or results of the Tencent Hunyuan Works to improve any other AI model (other than Tencent Hunyuan or Model Derivatives thereof).
+c.	You must not use, reproduce, modify, distribute, or display the Tencent Hunyuan Works, Output or results of the Tencent Hunyuan Works outside the Territory. Any such use outside the Territory is unlicensed and unauthorized under this Agreement.
+6.	INTELLECTUAL PROPERTY.
+a.	Subject to Tencent’s ownership of Tencent Hunyuan Works made by or for Tencent and intellectual property rights therein, conditioned upon Your compliance with the terms and conditions of this Agreement, as between You and Tencent, You will be the owner of any derivative works and modifications of the Materials and any Model Derivatives that are made by or for You.
+b.	No trademark licenses are granted under this Agreement, and in connection with the Tencent Hunyuan Works, Licensee may not use any name or mark owned by or associated with Tencent or any of its affiliates, except as required for reasonable and customary use in describing and distributing the Tencent Hunyuan Works. Tencent hereby grants You a license to use “Tencent Hunyuan” (the “Mark”) in the Territory solely as required to comply with the provisions of Section 3(c), provided that You comply with any applicable laws related to trademark protection. All goodwill arising out of Your use of the Mark will inure to the benefit of Tencent.
+c.	If You commence a lawsuit or other proceedings (including a cross-claim or counterclaim in a lawsuit) against Us or any person or entity alleging that the Materials or any Output, or any portion of any of the foregoing, infringe any intellectual property or other right owned or licensable by You, then all licenses granted to You under this Agreement shall terminate as of the date such lawsuit or other proceeding is filed. You will defend, indemnify and hold harmless Us from and against any claim by any Third Party arising out of or related to Your or the Third Party’s use or distribution of the Tencent Hunyuan Works.
+d.	Tencent claims no rights in Outputs You generate. You and Your users are solely responsible for Outputs and their subsequent uses.
+7.	DISCLAIMERS OF WARRANTY AND LIMITATIONS OF LIABILITY.
+a.	We are not obligated to support, update, provide training for, or develop any further version of the Tencent Hunyuan Works or to grant any license thereto.
+b.	UNLESS AND ONLY TO THE EXTENT REQUIRED BY APPLICABLE LAW, THE TENCENT HUNYUAN WORKS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED “AS IS” WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND INCLUDING ANY WARRANTIES OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, COURSE OF DEALING, USAGE OF TRADE, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING, REPRODUCING, MODIFYING, PERFORMING, DISPLAYING OR DISTRIBUTING ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS AND ASSUME ANY AND ALL RISKS ASSOCIATED WITH YOUR OR A THIRD PARTY’S USE OR DISTRIBUTION OF ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS AND YOUR EXERCISE OF RIGHTS AND PERMISSIONS UNDER THIS AGREEMENT.
+c.	TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL TENCENT OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, FOR ANY DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR LOST PROFITS OF ANY KIND ARISING FROM THIS AGREEMENT OR RELATED TO ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS, EVEN IF TENCENT OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+8.	SURVIVAL AND TERMINATION.
+a.	The term of this Agreement shall commence upon Your acceptance of this Agreement or access to the Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein.
+b.	We may terminate this Agreement if You breach any of the terms or conditions of this Agreement. Upon termination of this Agreement, You must promptly delete and cease use of the Tencent Hunyuan Works. Sections 6(a), 6(c), 7 and 9 shall survive the termination of this Agreement.
+9.	GOVERNING LAW AND JURISDICTION.
+a.	This Agreement and any dispute arising out of or relating to it will be governed by the laws of the Hong Kong Special Administrative Region of the People’s Republic of China, without regard to conflict of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement.
+b.	Exclusive jurisdiction and venue for any dispute arising out of or relating to this Agreement will be a court of competent jurisdiction in the Hong Kong Special Administrative Region of the People’s Republic of China, and Tencent and Licensee consent to the exclusive jurisdiction of such court with respect to any such dispute.
+ 
+EXHIBIT A
+ACCEPTABLE USE POLICY
+
+Tencent reserves the right to update this Acceptable Use Policy from time to time.
+Last modified: November 5, 2024
+
+Tencent endeavors to promote safe and fair use of its tools and features, including Tencent Hunyuan. You agree not to use Tencent Hunyuan or Model Derivatives:
+1.	Outside the Territory;
+2.	In any way that violates any applicable national, federal, state, local, international or any other law or regulation;
+3.	To harm Yourself or others;
+4.	To repurpose or distribute output from Tencent Hunyuan or any Model Derivatives to harm Yourself or others; 
+5.	To override or circumvent the safety guardrails and safeguards We have put in place;
+6.	For the purpose of exploiting, harming or attempting to exploit or harm minors in any way;
+7.	To generate or disseminate verifiably false information and/or content with the purpose of harming others or influencing elections;
+8.	To generate or facilitate false online engagement, including fake reviews and other means of fake online engagement;
+9.	To intentionally defame, disparage or otherwise harass others;
+10.	To generate and/or disseminate malware (including ransomware) or any other content to be used for the purpose of harming electronic systems;
+11.	To generate or disseminate personal identifiable information with the purpose of harming others;
+12.	To generate or disseminate information (including images, code, posts, articles), and place the information in any public context (including –through the use of bot generated tweets), without expressly and conspicuously identifying that the information and/or content is machine generated;
+13.	To impersonate another individual without consent, authorization, or legal right;
+14.	To make high-stakes automated decisions in domains that affect an individual’s safety, rights or wellbeing (e.g., law enforcement, migration, medicine/health, management of critical infrastructure, safety components of products, essential services, credit, employment, housing, education, social scoring, or insurance);
+15.	In a manner that violates or disrespects the social ethics and moral standards of other countries or regions;
+16.	To perform, facilitate, threaten, incite, plan, promote or encourage violent extremism or terrorism;
+17.	For any use intended to discriminate against or harm individuals or groups based on protected characteristics or categories, online or offline social behavior or known or predicted personal or personality characteristics;
+18.	To intentionally exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological harm;
+19.	For military purposes;
+20.	To engage in the unauthorized or unlicensed practice of any profession including, but not limited to, financial, legal, medical/health, or other professional practices.

NOTICE

@@ -0,0 +1,173 @@
+Usage and Legal Notices:
+
+Tencent is pleased to support the open source community by making Tencent HunyuanImage 2.1 available.
+
+Copyright (C) 2025 Tencent. All rights reserved. The below model in this distribution may have been modified by Tencent ("Tencent Modifications"). All Tencent Modifications are Copyright (C) Tencent.
+
+Tencent HunyuanImage 2.1 is licensed under Tencent Hunyuan Community License Agreement, which can be found in this repository called "LICENSE", except for the third-party components listed below. Tencent HunyuanImage 2.1 does not impose any additional limitations beyond what is outlined in the respective licenses of these third-party components. Users must comply with all terms and conditions of original licenses of these third-party components and must ensure that the usage of the third party components adheres to all relevant laws and regulations. 
+
+For avoidance of doubts, Tencent HunyuanImage 2.1 means the large language models and their software and algorithms, including trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code and other elements of the foregoing made publicly available by Tencent in accordance with the Tencent Hunyuan Community License Agreement.
+
+
+
+Other dependencies and licenses:
+
+Open Source Software Licensed under the Apache License Version 2.0:
+The below software in this distribution may have been modified by Tencent.
+--------------------------------------------------------------------
+1. Glyph-ByT5
+Copyright (c) Glyph-ByT5 and its authors.
+Please find the original component at following site: https://github.com/AIGText/Glyph-ByT5
+
+
+Terms of the Apache License Version 2.0:
+--------------------------------------------------------------------
+Apache License 
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and 
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and 
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and 
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. 
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+--------------------------------------------------------------------
+
+Open Source Software Licensed under the TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT and Other Licenses of the Third-Party Components therein:
+The below software in this distribution may have been modified by Tencent ("Tencent Modifications"). All Tencent Modifications are Copyright (C) 2025 Tencent.
+
+--------------------------------------------------------------------
+1. HunyuanVideo
+Copyright (C) 2024 THL A29 Limited, a Tencent company.  All rights reserved.
+
+
+Terms of the TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT:
+--------------------------------------------------------------------
+TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT
+Tencent HunyuanVideo Release Date: December 3, 2024
+THIS LICENSE AGREEMENT DOES NOT APPLY IN THE EUROPEAN UNION, UNITED KINGDOM AND SOUTH KOREA AND IS EXPRESSLY LIMITED TO THE TERRITORY, AS DEFINED BELOW.
+By clicking to agree or by using, reproducing, modifying, distributing, performing or displaying any portion or element of the Tencent Hunyuan Works, including via any Hosted Service, You will be deemed to have recognized and accepted the content of this Agreement, which is effective immediately.
+1.	DEFINITIONS.
+a.	“Acceptable Use Policy” shall mean the policy made available by Tencent as set forth in the Exhibit A.
+b.	“Agreement” shall mean the terms and conditions for use, reproduction, distribution, modification, performance and displaying of Tencent Hunyuan Works or any portion or element thereof set forth herein.
+c.	“Documentation” shall mean the specifications, manuals and documentation for Tencent Hunyuan made publicly available by Tencent.
+d.	“Hosted Service” shall mean a hosted service offered via an application programming interface (API), web access, or any other electronic or remote means.
+e.	“Licensee,” “You” or “Your” shall mean a natural person or legal entity exercising the rights granted by this Agreement and/or using the Tencent Hunyuan Works for any purpose and in any field of use.
+f.	“Materials” shall mean, collectively, Tencent’s proprietary Tencent Hunyuan and Documentation (and any portion thereof) as made available by Tencent under this Agreement.
+g.	“Model Derivatives” shall mean all: (i) modifications to Tencent Hunyuan or any Model Derivative of Tencent Hunyuan; (ii) works based on Tencent Hunyuan or any Model Derivative of Tencent Hunyuan; or (iii) any other machine learning model which is created by transfer of patterns of the weights, parameters, operations, or Output of Tencent Hunyuan or any Model Derivative of Tencent Hunyuan, to that model in order to cause that model to perform similarly to Tencent Hunyuan or a Model Derivative of Tencent Hunyuan, including distillation methods, methods that use intermediate data representations, or methods based on the generation of synthetic data Outputs by Tencent Hunyuan or a Model Derivative of Tencent Hunyuan for training that model. For clarity, Outputs by themselves are not deemed Model Derivatives.
+h.	“Output” shall mean the information and/or content output of Tencent Hunyuan or a Model Derivative that results from operating or otherwise using Tencent Hunyuan or a Model Derivative, including via a Hosted Service.
+i.	“Tencent,” “We” or “Us” shall mean THL A29 Limited.
+j.	“Tencent Hunyuan” shall mean the large language models, text/image/video/audio/3D generation models, and multimodal large language models and their software and algorithms, including trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code and other elements of the foregoing made publicly available by Us, including, without limitation to, Tencent HunyuanVideo released at [https://github.com/Tencent/HunyuanVideo].
+k.	“Tencent Hunyuan Works” shall mean: (i) the Materials; (ii) Model Derivatives; and (iii) all derivative works thereof.
+l.	“Territory” shall mean the worldwide territory, excluding the territory of the European Union, United Kingdom and South Korea. 
+m.	“Third Party” or “Third Parties” shall mean individuals or legal entities that are not under common control with Us or You.
+n.	“including” shall mean including but not limited to.
+2.	GRANT OF RIGHTS.
+We grant You, for the Territory only, a non-exclusive, non-transferable and royalty-free limited license under Tencent’s intellectual property or other rights owned by Us embodied in or utilized by the Materials to use, reproduce, distribute, create derivative works of (including Model Derivatives), and make modifications to the Materials, only in accordance with the terms of this Agreement and the Acceptable Use Policy, and You must not violate (or encourage or permit anyone else to violate) any term of this Agreement or the Acceptable Use Policy.
+3.	DISTRIBUTION.
+You may, subject to Your compliance with this Agreement, distribute or make available to Third Parties the Tencent Hunyuan Works, exclusively in the Territory, provided that You meet all of the following conditions:
+a.	You must provide all such Third Party recipients of the Tencent Hunyuan Works or products or services using them a copy of this Agreement;
+b.	You must cause any modified files to carry prominent notices stating that You changed the files;
+c.	You are encouraged to: (i) publish at least one technology introduction blogpost or one public statement expressing Your experience of using the Tencent Hunyuan Works; and (ii) mark the products or services developed by using the Tencent Hunyuan Works to indicate that the product/service is “Powered by Tencent Hunyuan”; and
+d.	All distributions to Third Parties (other than through a Hosted Service) must be accompanied by a “Notice” text file that contains the following notice: “Tencent Hunyuan is licensed under the Tencent Hunyuan Community License Agreement, Copyright © 2024 Tencent. All Rights Reserved. The trademark rights of “Tencent Hunyuan” are owned by Tencent or its affiliate.”
+You may add Your own copyright statement to Your modifications and, except as set forth in this Section and in Section 5, may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Model Derivatives as a whole, provided Your use, reproduction, modification, distribution, performance and display of the work otherwise complies with the terms and conditions of this Agreement (including as regards the Territory). If You receive Tencent Hunyuan Works from a Licensee as part of an integrated end user product, then this Section 3 of this Agreement will not apply to You.
+4.	ADDITIONAL COMMERCIAL TERMS.
+If, on the Tencent Hunyuan version release date, the monthly active users of all products or services made available by or for Licensee is greater than 100 million monthly active users in the preceding calendar month, You must request a license from Tencent, which Tencent may grant to You in its sole discretion, and You are not authorized to exercise any of the rights under this Agreement unless or until Tencent otherwise expressly grants You such rights.
+5.	RULES OF USE.
+a.	Your use of the Tencent Hunyuan Works must comply with applicable laws and regulations (including trade compliance laws and regulations) and adhere to the Acceptable Use Policy for the Tencent Hunyuan Works, which is hereby incorporated by reference into this Agreement. You must include the use restrictions referenced in these Sections 5(a) and 5(b) as an enforceable provision in any agreement (e.g., license agreement, terms of use, etc.) governing the use and/or distribution of Tencent Hunyuan Works and You must provide notice to subsequent users to whom You distribute that Tencent Hunyuan Works are subject to the use restrictions in these Sections 5(a) and 5(b).
+b.	You must not use the Tencent Hunyuan Works or any Output or results of the Tencent Hunyuan Works to improve any other AI model (other than Tencent Hunyuan or Model Derivatives thereof).
+c.	You must not use, reproduce, modify, distribute, or display the Tencent Hunyuan Works, Output or results of the Tencent Hunyuan Works outside the Territory. Any such use outside the Territory is unlicensed and unauthorized under this Agreement.
+6.	INTELLECTUAL PROPERTY.
+a.	Subject to Tencent’s ownership of Tencent Hunyuan Works made by or for Tencent and intellectual property rights therein, conditioned upon Your compliance with the terms and conditions of this Agreement, as between You and Tencent, You will be the owner of any derivative works and modifications of the Materials and any Model Derivatives that are made by or for You.
+b.	No trademark licenses are granted under this Agreement, and in connection with the Tencent Hunyuan Works, Licensee may not use any name or mark owned by or associated with Tencent or any of its affiliates, except as required for reasonable and customary use in describing and distributing the Tencent Hunyuan Works. Tencent hereby grants You a license to use “Tencent Hunyuan” (the “Mark”) in the Territory solely as required to comply with the provisions of Section 3(c), provided that You comply with any applicable laws related to trademark protection. All goodwill arising out of Your use of the Mark will inure to the benefit of Tencent.
+c.	If You commence a lawsuit or other proceedings (including a cross-claim or counterclaim in a lawsuit) against Us or any person or entity alleging that the Materials or any Output, or any portion of any of the foregoing, infringe any intellectual property or other right owned or licensable by You, then all licenses granted to You under this Agreement shall terminate as of the date such lawsuit or other proceeding is filed. You will defend, indemnify and hold harmless Us from and against any claim by any Third Party arising out of or related to Your or the Third Party’s use or distribution of the Tencent Hunyuan Works.
+d.	Tencent claims no rights in Outputs You generate. You and Your users are solely responsible for Outputs and their subsequent uses.
+7.	DISCLAIMERS OF WARRANTY AND LIMITATIONS OF LIABILITY.
+a.	We are not obligated to support, update, provide training for, or develop any further version of the Tencent Hunyuan Works or to grant any license thereto.
+b.	UNLESS AND ONLY TO THE EXTENT REQUIRED BY APPLICABLE LAW, THE TENCENT HUNYUAN WORKS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED “AS IS” WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND INCLUDING ANY WARRANTIES OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, COURSE OF DEALING, USAGE OF TRADE, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING, REPRODUCING, MODIFYING, PERFORMING, DISPLAYING OR DISTRIBUTING ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS AND ASSUME ANY AND ALL RISKS ASSOCIATED WITH YOUR OR A THIRD PARTY’S USE OR DISTRIBUTION OF ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS AND YOUR EXERCISE OF RIGHTS AND PERMISSIONS UNDER THIS AGREEMENT.
+c.	TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL TENCENT OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, FOR ANY DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR LOST PROFITS OF ANY KIND ARISING FROM THIS AGREEMENT OR RELATED TO ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS, EVEN IF TENCENT OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+8.	SURVIVAL AND TERMINATION.
+a.	The term of this Agreement shall commence upon Your acceptance of this Agreement or access to the Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein.
+b.	We may terminate this Agreement if You breach any of the terms or conditions of this Agreement. Upon termination of this Agreement, You must promptly delete and cease use of the Tencent Hunyuan Works. Sections 6(a), 6(c), 7 and 9 shall survive the termination of this Agreement.
+9.	GOVERNING LAW AND JURISDICTION.
+a.	This Agreement and any dispute arising out of or relating to it will be governed by the laws of the Hong Kong Special Administrative Region of the People’s Republic of China, without regard to conflict of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement.
+b.	Exclusive jurisdiction and venue for any dispute arising out of or relating to this Agreement will be a court of competent jurisdiction in the Hong Kong Special Administrative Region of the People’s Republic of China, and Tencent and Licensee consent to the exclusive jurisdiction of such court with respect to any such dispute.
+ 
+EXHIBIT A
+ACCEPTABLE USE POLICY
+
+Tencent reserves the right to update this Acceptable Use Policy from time to time.
+Last modified: November 5, 2024
+
+Tencent endeavors to promote safe and fair use of its tools and features, including Tencent Hunyuan. You agree not to use Tencent Hunyuan or Model Derivatives:
+1.	Outside the Territory;
+2.	In any way that violates any applicable national, federal, state, local, international or any other law or regulation;
+3.	To harm Yourself or others;
+4.	To repurpose or distribute output from Tencent Hunyuan or any Model Derivatives to harm Yourself or others; 
+5.	To override or circumvent the safety guardrails and safeguards We have put in place;
+6.	For the purpose of exploiting, harming or attempting to exploit or harm minors in any way;
+7.	To generate or disseminate verifiably false information and/or content with the purpose of harming others or influencing elections;
+8.	To generate or facilitate false online engagement, including fake reviews and other means of fake online engagement;
+9.	To intentionally defame, disparage or otherwise harass others;
+10.	To generate and/or disseminate malware (including ransomware) or any other content to be used for the purpose of harming electronic systems;
+11.	To generate or disseminate personal identifiable information with the purpose of harming others;
+12.	To generate or disseminate information (including images, code, posts, articles), and place the information in any public context (including –through the use of bot generated tweets), without expressly and conspicuously identifying that the information and/or content is machine generated;
+13.	To impersonate another individual without consent, authorization, or legal right;
+14.	To make high-stakes automated decisions in domains that affect an individual’s safety, rights or wellbeing (e.g., law enforcement, migration, medicine/health, management of critical infrastructure, safety components of products, essential services, credit, employment, housing, education, social scoring, or insurance);
+15.	In a manner that violates or disrespects the social ethics and moral standards of other countries or regions;
+16.	To perform, facilitate, threaten, incite, plan, promote or encourage violent extremism or terrorism;
+17.	For any use intended to discriminate against or harm individuals or groups based on protected characteristics or categories, online or offline social behavior or known or predicted personal or personality characteristics;
+18.	To intentionally exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological harm;
+19.	For military purposes;
+20.	To engage in the unauthorized or unlicensed practice of any profession including, but not limited to, financial, legal, medical/health, or other professional practices.
+
+For the license of other third party components, please refer to the following URL:
+https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/ff2dd59277b3177785d8279d4170968afa3b1d55/Notice

README.md

@@ -0,0 +1,12 @@
+---
+title: HunyuanImage 2.1
+emoji: 🔥
+colorFrom: gray
+colorTo: green
+sdk: gradio
+sdk_version: 5.44.1
+app_file: app.py
+pinned: false
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,632 @@
+import os
+IS_SPACE = True
+
+if IS_SPACE:
+    import spaces
+
+
+import sys
+import warnings
+import subprocess
+from pathlib import Path
+from typing import Optional, Tuple, Dict
+import torch
+
+def space_context(duration: int):
+    if IS_SPACE:
+        return spaces.GPU(duration=duration)
+    return lambda x: x
+
+@space_context(duration=120)
+def test_env():
+    assert torch.cuda.is_available()
+
+    try:
+        import flash_attn
+    except ImportError:
+        print("Flash-attn not found, installing...")
+        os.system("pip install flash-attn==2.7.3 --no-build-isolation")
+
+    else:
+        print("Flash-attn found, skipping installation...")
+test_env()
+
+warnings.filterwarnings("ignore")
+
+# Add the current directory to Python path
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+try:
+    import gradio as gr
+    from PIL import Image
+    from hyimage.diffusion.pipelines.hunyuanimage_pipeline import HunyuanImagePipeline
+    from huggingface_hub import snapshot_download
+    import modelscope
+except ImportError as e:
+    print(f"Missing required dependencies: {e}")
+    print("Please install with: pip install -r requirements_gradio.txt")
+    print("For checkpoint downloads, also install: pip install -U 'huggingface_hub[cli]' modelscope")
+    sys.exit(1)
+
+class CheckpointDownloader:
+    """Handles downloading of all required checkpoints for HunyuanImage."""
+    
+    def __init__(self, base_dir: str = "./ckpts"):
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(exist_ok=True)
+        
+        # Define all required checkpoints
+        self.checkpoints = {
+            "main_model": {
+                "repo_id": "tencent/HunyuanImage-2.1",
+                "local_dir": self.base_dir,
+            },
+            "mllm_encoder": {
+                "repo_id": "Qwen/Qwen2.5-VL-7B-Instruct", 
+                "local_dir": self.base_dir / "text_encoder" / "llm",
+            },
+            "byt5_encoder": {
+                "repo_id": "google/byt5-small",
+                "local_dir": self.base_dir / "text_encoder" / "byt5-small", 
+            },
+            "glyph_encoder": {
+                "repo_id": "AI-ModelScope/Glyph-SDXL-v2",
+                "local_dir": self.base_dir / "text_encoder" / "Glyph-SDXL-v2",
+                "use_modelscope": True
+            }
+        }
+    
+    def download_checkpoint(self, checkpoint_name: str, progress_callback=None) -> Tuple[bool, str]:
+        """Download a specific checkpoint."""
+        if checkpoint_name not in self.checkpoints:
+            return False, f"Unknown checkpoint: {checkpoint_name}"
+        
+        config = self.checkpoints[checkpoint_name]
+        local_dir = config["local_dir"]
+        local_dir.mkdir(parents=True, exist_ok=True)
+        
+        try:
+            if config.get("use_modelscope", False):
+                # Use modelscope for Chinese models
+                return self._download_with_modelscope(config, progress_callback)
+            else:
+                # Use huggingface_hub for other models
+                return self._download_with_hf(config, progress_callback)
+        except Exception as e:
+            return False, f"Download failed: {str(e)}"
+    
+    def _download_with_hf(self, config: Dict, progress_callback=None) -> Tuple[bool, str]:
+        """Download using huggingface_hub."""
+        repo_id = config["repo_id"]
+        local_dir = config["local_dir"]
+        
+        if progress_callback:
+            progress_callback(f"Downloading {repo_id}...")
+        
+        try:
+            snapshot_download(
+                repo_id=repo_id,
+                local_dir=str(local_dir),
+                local_dir_use_symlinks=False,
+                resume_download=True
+            )
+            return True, f"Successfully downloaded {repo_id}"
+        except Exception as e:
+            return False, f"HF download failed: {str(e)}"
+    
+    def _download_with_modelscope(self, config: Dict, progress_callback=None) -> Tuple[bool, str]:
+        """Download using modelscope."""
+        repo_id = config["repo_id"]
+        local_dir = config["local_dir"]
+        
+        if progress_callback:
+            progress_callback(f"Downloading {repo_id} via ModelScope...")
+        print(f"Downloading {repo_id} via ModelScope...")
+        
+        try:
+            # Use subprocess to call modelscope CLI
+            cmd = [
+                "modelscope", "download", 
+                "--model", repo_id,
+                "--local_dir", str(local_dir)
+            ]
+            
+            subprocess.run(cmd, capture_output=True, text=True, check=True)
+            return True, f"Successfully downloaded {repo_id} via ModelScope"
+        except subprocess.CalledProcessError as e:
+            return False, f"ModelScope download failed: {e.stderr}"
+        except FileNotFoundError:
+            return False, "ModelScope CLI not found. Install with: pip install modelscope"
+    
+    def download_all_checkpoints(self, progress_callback=None) -> Tuple[bool, str, Dict[str, any]]:
+        """Download all checkpoints."""
+        results = {}
+        for name, _ in self.checkpoints.items():
+            if progress_callback:
+                progress_callback(f"Starting download of {name}...")
+            
+            success, message = self.download_checkpoint(name, progress_callback)
+            results[name] = {"success": success, "message": message}
+            
+            if not success:
+                return False, f"Failed to download {name}: {message}", results
+        return True, "All checkpoints downloaded successfully", results
+
+
+@space_context(duration=200)
+def load_pipeline(use_distilled: bool = False, device: str = "cuda"):
+    """Load the HunyuanImage pipeline (only load once, refiner and reprompt are accessed from it)."""
+    try:
+        assert not use_distilled # use_distilled is a placeholder for the future
+
+        print(f"Loading HunyuanImage pipeline (distilled={use_distilled})...")
+        model_name = "hunyuanimage-v2.1-distilled" if use_distilled else "hunyuanimage-v2.1"
+        pipeline = HunyuanImagePipeline.from_pretrained(
+            model_name=model_name,
+            device=device,
+            enable_dit_offloading=True,
+            enable_reprompt_model_offloading=True,
+            enable_refiner_offloading=True
+        )
+        print("✓ Pipeline loaded successfully")
+        return pipeline
+    except Exception as e:
+        error_msg = f"Error loading pipeline: {str(e)}"
+        print(f"✗ {error_msg}")
+        raise
+
+
+if IS_SPACE:
+    downloader = CheckpointDownloader()
+    downloader.download_all_checkpoints()
+
+pipeline = load_pipeline(use_distilled=False, device="cuda")
+class HunyuanImageApp:
+
+    @space_context(duration=290)
+    def __init__(self, auto_load: bool = True, use_distilled: bool = False, device: str = "cuda"):
+        """Initialize the HunyuanImage Gradio app."""
+        global pipeline
+
+        self.pipeline = pipeline
+        self.current_use_distilled = None
+
+
+    def print_peak_memory(self):
+        import torch
+        stats = torch.cuda.memory_stats()
+        peak_bytes_requirement = stats["allocated_bytes.all.peak"]
+        print(f"Before refiner Peak memory requirement: {peak_bytes_requirement / 1024 ** 3:.2f} GB")
+
+    @space_context(duration=300)
+    def generate_image(self, 
+                      prompt: str,
+                      negative_prompt: str,
+                      width: int,
+                      height: int,
+                      num_inference_steps: int,
+                      guidance_scale: float,
+                      seed: int,
+                      use_reprompt: bool,
+                      use_refiner: bool,
+                      # use_distilled: bool
+                      ) -> Tuple[Optional[Image.Image], str]:
+        """Generate an image using the HunyuanImage pipeline."""
+        try:
+
+            if self.pipeline is None:
+                return None, "Pipeline not loaded. Please try again."
+
+
+            if hasattr(self.pipeline, '_refiner_pipeline'):
+                self.pipeline.refiner_pipeline.to('cpu')
+            self.pipeline.to('cuda')
+            
+            # Generate image
+            image = self.pipeline(
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                width=width,
+                height=height,
+                num_inference_steps=num_inference_steps,
+                guidance_scale=guidance_scale,
+                seed=seed,
+                use_reprompt=use_reprompt,
+                use_refiner=use_refiner
+            )
+            self.print_peak_memory()
+            return image, "Image generated successfully!"
+                
+        except Exception as e:
+            error_msg = f"Error generating image: {str(e)}"
+            print(f"✗ {error_msg}")
+            return None, error_msg
+
+    @space_context(duration=300)
+    def enhance_prompt(self, prompt: str, # use_distilled: bool
+                       ) -> Tuple[str, str]:
+        """Enhance a prompt using the reprompt model."""
+        try:
+            # Load pipeline if needed
+            if self.pipeline is None:
+                return prompt, "Pipeline not loaded. Please try again."
+            
+            self.pipeline.to('cpu')
+            if hasattr(self.pipeline, '_refiner_pipeline'):
+                self.pipeline.refiner_pipeline.to('cpu')
+
+            # Use reprompt model from the main pipeline
+            enhanced_prompt = self.pipeline.reprompt_model.predict(prompt)
+            self.print_peak_memory()
+            return enhanced_prompt, "Prompt enhanced successfully!"
+            
+        except Exception as e:
+            error_msg = f"Error enhancing prompt: {str(e)}"
+            print(f"✗ {error_msg}")
+            return prompt, error_msg
+
+    @space_context(duration=300)
+    def refine_image(self, 
+                    image: Image.Image,
+                    prompt: str,
+                    negative_prompt: str,
+                    width: int,
+                    height: int,
+                    num_inference_steps: int,
+                    guidance_scale: float,
+                    seed: int) -> Tuple[Optional[Image.Image], str]:
+        """Refine an image using the refiner pipeline."""
+        try:
+            if image is None:
+                return None, "Please upload an image to refine."
+            
+            # Resize image to target dimensions if needed
+            if image.size != (width, height):
+                image = image.resize((width, height), Image.Resampling.LANCZOS)
+
+            self.pipeline.to('cpu')
+            self.pipeline.refiner_pipeline.to('cuda')
+            
+            # Use refiner from the main pipeline
+            refined_image = self.pipeline.refiner_pipeline(
+                image=image,
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                width=width,
+                height=height,
+                num_inference_steps=num_inference_steps,
+                guidance_scale=guidance_scale,
+                seed=seed
+            )
+            self.print_peak_memory()
+            return refined_image, "Image refined successfully!"
+            
+        except Exception as e:
+            error_msg = f"Error refining image: {str(e)}"
+            print(f"✗ {error_msg}")
+            return None, error_msg
+    
+    
+    def download_single_checkpoint(self, checkpoint_name: str) -> Tuple[bool, str]:
+        """Download a single checkpoint."""
+        try:
+            success, message = self.downloader.download_checkpoint(checkpoint_name)
+            return success, message
+        except Exception as e:
+            return False, f"Download error: {str(e)}"
+    
+    def download_all_checkpoints(self) -> Tuple[bool, str, Dict[str, any]]:
+        """Download all missing checkpoints."""
+        try:
+            success, message, results = self.downloader.download_all_checkpoints()
+            return success, message, results
+        except Exception as e:
+            return False, f"Download error: {str(e)}", {}
+
+def create_interface(auto_load: bool = True, use_distilled: bool = False, device: str = "cuda"):
+    """Create the Gradio interface."""
+    app = HunyuanImageApp(auto_load=auto_load, use_distilled=use_distilled, device=device)
+    
+    # Custom CSS for better styling
+    css = """
+    .gradio-container {
+        max-width: 1200px !important;
+        margin: auto !important;
+    }
+    .tab-nav {
+        background: linear-gradient(90deg, #667eea 0%, #764ba2 100%);
+        border-radius: 10px;
+        padding: 10px;
+        margin-bottom: 20px;
+    }
+    .model-info {
+        background: #f8f9fa;
+        border: 1px solid #dee2e6;
+        border-radius: 8px;
+        padding: 15px;
+        margin-bottom: 20px;
+    }
+    """
+    
+    with gr.Blocks(css=css, title="HunyuanImage Pipeline", theme=gr.themes.Soft()) as demo:
+        gr.Markdown(
+            """
+            # 🎨 HunyuanImage 2.1 Pipeline
+            **HunyuanImage-2.1: An Efficient Diffusion Model for High-Resolution (2K) Text-to-Image Generation​**
+            
+            This app provides three main functionalities:
+            1. **Text-to-Image Generation**: Generate high-quality images from text prompts
+            2. **Prompt Enhancement**: Improve your prompts using MLLM reprompting
+            3. **Image Refinement**: Enhance existing images with the refiner model (Refiner is not supported yet; coming soon.)
+            """,
+            elem_classes="model-info"
+        )
+        
+        with gr.Tabs():
+            # Tab 1: Text-to-Image Generation
+            with gr.Tab("🖼️ Text-to-Image Generation"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        gr.Markdown("### Generation Settings")
+                        gr.Markdown("**Model**: HunyuanImage v2.1 (Non-distilled)")
+                        
+                        # use_distilled = gr.Checkbox(
+                        #     label="Use Distilled Model",
+                        #     value=False,
+                        #     info="Faster generation with slightly lower quality"
+                        # )
+                        use_distilled = False
+                        
+                        prompt = gr.Textbox(
+                            label="Prompt",
+                            placeholder="",
+                            lines=3,
+                            value="A cute, cartoon-style anthropomorphic penguin plush toy with fluffy fur, standing in a painting studio, wearing a red knitted scarf and a red beret with the word “Tencent” on it, holding a paintbrush with a focused expression as it paints an oil painting of the Mona Lisa, rendered in a photorealistic photographic style."
+                        )
+                        
+                        negative_prompt = gr.Textbox(
+                            label="Negative Prompt",
+                            placeholder="",
+                            lines=2,
+                            value=""
+                        )
+                        
+                        with gr.Row():
+                            width = gr.Slider(
+                                minimum=512, maximum=2048, step=64, value=2048,
+                                label="Width", info="Image width in pixels"
+                            )
+                            height = gr.Slider(
+                                minimum=512, maximum=2048, step=64, value=2048,
+                                label="Height", info="Image height in pixels"
+                            )
+                        
+                        with gr.Row():
+                            num_inference_steps = gr.Slider(
+                                minimum=10, maximum=100, step=5, value=50,
+                                label="Inference Steps", info="More steps = better quality, slower generation"
+                            )
+                            guidance_scale = gr.Slider(
+                                minimum=1.0, maximum=10.0, step=0.1, value=3.5,
+                                label="Guidance Scale", info="How closely to follow the prompt"
+                            )
+                        
+                        with gr.Row():
+                            seed = gr.Number(
+                                label="Seed", value=649151, precision=0,
+                                info="Random seed for reproducibility"
+                            )
+                            use_reprompt = gr.Checkbox(
+                                label="Use Reprompt", value=False,
+                                info="Enhance prompt automatically"
+                            )
+                            use_refiner = gr.Checkbox(
+                                label="Use Refiner", value=False,
+                                info="Apply refiner after generation (Refiner is not supported yet; coming soon.)",
+                                interactive=False
+                            )
+                        
+                        generate_btn = gr.Button("🎨 Generate Image", variant="primary", size="lg")
+                    
+                    with gr.Column(scale=1):
+                        gr.Markdown("### Generated Image")
+                        generated_image = gr.Image(
+                            label="Generated Image",
+                            type="pil",
+                            height=600
+                        )
+                        generation_status = gr.Textbox(
+                            label="Status",
+                            interactive=False,
+                            value="Ready to generate"
+                        )
+            
+            # Tab 2: Prompt Enhancement
+            with gr.Tab("✨ Prompt Enhancement"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        gr.Markdown("### Prompt Enhancement Settings")
+                        gr.Markdown("**Model**: HunyuanImage v2.1 Reprompt Model")
+                        
+                        # enhance_use_distilled = gr.Checkbox(
+                        #     label="Use Distilled Model",
+                        #     value=False,
+                        #     info="For loading the reprompt model"
+                        # )
+                        enhance_use_distilled = False
+                        
+                        original_prompt = gr.Textbox(
+                            label="Original Prompt",
+                            placeholder="A cat sitting on a table",
+                            lines=4,
+                            value="A cat sitting on a table"
+                        )
+                        
+                        enhance_btn = gr.Button("✨ Enhance Prompt", variant="primary", size="lg")
+                    
+                    with gr.Column(scale=1):
+                        gr.Markdown("### Enhanced Prompt")
+                        enhanced_prompt = gr.Textbox(
+                            label="Enhanced Prompt",
+                            lines=6,
+                            interactive=False
+                        )
+                        enhancement_status = gr.Textbox(
+                            label="Status",
+                            interactive=False,
+                            value="Ready to enhance"
+                        )
+            
+            # # Tab 3: Image Refinement
+            # with gr.Tab("🔧 Image Refinement"):
+            #     with gr.Row():
+            #         with gr.Column(scale=1):
+            #             gr.Markdown("### Refinement Settings")
+            #             gr.Markdown("**Model**: HunyuanImage v2.1 Refiner")
+                        
+            #             input_image = gr.Image(
+            #                 label="Input Image",
+            #                 type="pil",
+            #                 height=300
+            #             )
+                        
+            #             refine_prompt = gr.Textbox(
+            #                 label="Refinement Prompt",
+            #                 placeholder="Make the image more detailed and high quality",
+            #                 lines=2,
+            #                 value="Make the image more detailed and high quality"
+            #             )
+                        
+            #             refine_negative_prompt = gr.Textbox(
+            #                 label="Negative Prompt",
+            #                 placeholder="",
+            #                 lines=2,
+            #                 value=""
+            #             )
+                        
+            #             with gr.Row():
+            #                 refine_width = gr.Slider(
+            #                     minimum=512, maximum=2048, step=64, value=2048,
+            #                     label="Width", info="Output width"
+            #                 )
+            #                 refine_height = gr.Slider(
+            #                     minimum=512, maximum=2048, step=64, value=2048,
+            #                     label="Height", info="Output height"
+            #                 )
+                        
+            #             with gr.Row():
+            #                 refine_steps = gr.Slider(
+            #                     minimum=1, maximum=20, step=1, value=4,
+            #                     label="Refinement Steps", info="More steps = more refinement"
+            #                 )
+            #                 refine_guidance = gr.Slider(
+            #                     minimum=1.0, maximum=10.0, step=0.1, value=3.5,
+            #                     label="Guidance Scale", info="How strongly to follow the prompt"
+            #                 )
+                        
+            #             refine_seed = gr.Number(
+            #                 label="Seed", value=649151, precision=0,
+            #                 info="Random seed for reproducibility"
+            #             )
+                        
+            #             refine_btn = gr.Button("🔧 Refine Image", variant="primary", size="lg")
+                    
+            #         with gr.Column(scale=1):
+            #             gr.Markdown("### Refined Image")
+            #             refined_image = gr.Image(
+            #                 label="Refined Image",
+            #                 type="pil",
+            #                 height=600
+            #             )
+            #             refinement_status = gr.Textbox(
+            #                 label="Status",
+            #                 interactive=False,
+            #                 value="Ready to refine"
+            #             )
+        
+        # Event handlers
+        generate_btn.click(
+            fn=app.generate_image,
+            inputs=[
+                prompt, negative_prompt, width, height, num_inference_steps,
+                guidance_scale, seed, use_reprompt, use_refiner # , use_distilled
+            ],
+            outputs=[generated_image, generation_status]
+        )
+        
+        enhance_btn.click(
+            fn=app.enhance_prompt,
+            inputs=[original_prompt],
+            outputs=[enhanced_prompt, enhancement_status]
+        )
+        
+        #refine_btn.click(
+        #    fn=app.refine_image,
+        #    inputs=[
+        #        input_image, refine_prompt, refine_negative_prompt,
+        #        refine_width, refine_height, refine_steps, refine_guidance, refine_seed
+        #    ],
+        #    outputs=[refined_image, refinement_status]
+        #)
+        
+        # Additional info
+        gr.Markdown(
+            """
+            ### 📝 Usage Tips
+            
+            **Text-to-Image Generation:**
+            - Use descriptive prompts with specific details
+            - Adjust guidance scale: higher values follow prompts more closely
+            - More inference steps generally produce better quality
+            - Enable reprompt for automatic prompt enhancement
+            - Enable refiner for additional quality improvement
+            
+            **Prompt Enhancement:**
+            - Enter your basic prompt idea
+            - The AI will enhance it with better structure and details
+            - Enhanced prompts often produce better results
+            
+            **Image Refinement:**
+            - Upload any image you want to improve
+            - Describe what improvements you want in the refinement prompt
+            - The refiner will enhance details and quality
+            - Works best with images generated by HunyuanImage
+            """,
+            elem_classes="model-info"
+        )
+    
+    return demo
+
+if __name__ == "__main__":
+    import argparse
+    
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(description="Launch HunyuanImage Gradio App")
+    parser.add_argument("--no-auto-load", action="store_true", help="Disable auto-loading pipeline on startup")
+    parser.add_argument("--use-distilled", action="store_true", help="Use distilled model")
+    parser.add_argument("--device", type=str, default="cuda", help="Device to use (cuda/cpu)")
+    parser.add_argument("--port", type=int, default=8081, help="Port to run the app on")
+    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host to bind to")
+    
+    args = parser.parse_args()
+    
+    # Create and launch the interface
+    auto_load = not args.no_auto_load
+    demo = create_interface(auto_load=auto_load, use_distilled=args.use_distilled, device=args.device)
+    
+    print("🚀 Starting HunyuanImage Gradio App...")
+    print(f"📱 The app will be available at: http://{args.host}:{args.port}")
+    print(f"🔧 Auto-load pipeline: {'Yes' if auto_load else 'No'}")
+    print(f"🎯 Model type: {'Distilled' if args.use_distilled else 'Non-distilled'}")
+    print(f"💻 Device: {args.device}")
+    print("⚠️  Make sure you have the required model checkpoints downloaded!")
+    
+    demo.launch(
+        server_name=args.host,
+        # server_port=args.port,
+        share=False,
+        show_error=True,
+        quiet=False,
+        # max_threads=1,  # Default: sequential processing (recommended for GPU apps)
+        # max_threads=4,  # Enable parallel processing (requires more GPU memory)
+    )

ckpts/checkpoints-download.md

@@ -0,0 +1,74 @@
+
+# Download the pretrained checkpoints:
+
+First, make sure you have installed the huggingface CLI and modelscope CLI.
+
+```bash
+pip install -U "huggingface_hub[cli]"
+pip install modelscope
+```
+
+
+### Download the pretrained DiT and VAE checkpoints:
+```bash
+hf download tencent/HunyuanImage-2.1 --local-dir ./ckpts
+```
+
+### Downloading TextEncoders
+
+HunyuanImage uses an MLLM and a byT5 as text encoders.
+
+* **MLLM**
+
+    HunyuanImage can be integrated with different MLLMs (including HunyuanMLLM and other open-source MLLM models). 
+
+    At this stage, we have not yet released the latest HunyuanMLLM. We recommend the users in community to use an open-source alternative, such as Qwen2.5-VL-7B-Instruct provided by Qwen Team, which can be downloaded by the following command:
+    ```bash
+    hf download Qwen/Qwen2.5-VL-7B-Instruct --local-dir ./ckpts/text_encoder/llm
+    ```
+
+* **ByT5 encoder**
+
+    We use [Glyph-SDXL-v2](https://modelscope.cn/models/AI-ModelScope/Glyph-SDXL-v2) as our [byT5](https://github.com/google-research/byt5) encoder, which can be downloaded by the following command:
+
+    ```bash
+    hf download google/byt5-small --local-dir ./ckpts/text_encoder/byt5-small
+    modelscope download --model AI-ModelScope/Glyph-SDXL-v2 --local_dir ./ckpts/text_encoder/Glyph-SDXL-v2
+    ```
+    You can also manually download the checkpoints from [here](https://modelscope.cn/models/AI-ModelScope/Glyph-SDXL-v2/files) and place them in the text_encoder folder like:
+    ```
+    ckpts
+    ├── text_encoder
+    │   ├── Glyph-SDXL-v2
+    │   │   ├── assets
+    │   │   │   ├── color_idx.json
+    │   │   │   ├── multilingual_10-lang_idx.json
+    │   │   │   └── ...
+    │   │   └── checkpoints
+    │   │       ├── byt5_model.pt
+    │   │       └── ...
+    │   └─  ...
+    └─  ...
+    ```
+
+<details>
+
+<summary>💡Tips for using hf/huggingface-cli (network problem)</summary>
+
+##### 1. Using HF-Mirror
+
+If you encounter slow download speeds in China, you can try a mirror to speed up the download process:
+
+```shell
+HF_ENDPOINT=https://hf-mirror.com hf download tencent/HunyuanImage-2.1 --local-dir ./ckpts
+```
+
+##### 2. Resume Download
+
+`huggingface-cli` supports resuming downloads. If the download is interrupted, you can just rerun the download 
+command to resume the download process.
+
+Note: If an `No such file or directory: 'ckpts/.huggingface/.gitignore.lock'` like error occurs during the download 
+process, you can ignore the error and rerun the download command.
+
+</details>

hyimage/common/config/__init__.py

@@ -0,0 +1,4 @@
+from .lazy import LazyCall, instantiate, locate
+from .base_config import DiTConfig, VAEConfig, TextEncoderConfig, RepromptConfig
+
+__all__ = ["LazyCall", "instantiate", "locate", "DiTConfig", "VAEConfig", "TextEncoderConfig", "RepromptConfig"]

hyimage/common/config/base_config.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from hyimage.common.config.lazy import DictConfig
+
+
+@dataclass
+class DiTConfig:
+    model: DictConfig
+    use_lora: bool = False
+    use_cpu_offload: bool = False
+    gradient_checkpointing: bool = False
+    load_from: Optional[str] = None
+    use_compile: bool = False
+
+
+@dataclass
+class VAEConfig:
+    model: DictConfig
+    load_from: str
+    cpu_offload: bool = False
+    enable_tiling: bool = False
+
+
+@dataclass
+class TextEncoderConfig:
+    model: DictConfig
+    load_from: str
+    prompt_template: Optional[str] = None
+    text_len: Optional[int] = None
+
+
+@dataclass
+class RepromptConfig:
+    model: DictConfig
+    load_from: str

hyimage/common/config/lazy.py

@@ -0,0 +1,69 @@
+import collections.abc as abc
+import copy
+import pydoc
+from typing import Any
+
+
+class DictConfig(dict):
+
+    def __getattr__(self, item):
+        try:
+            return self[item]
+        except KeyError:
+            raise AttributeError(f"'AttrDict' object has no attribute '{item}'")
+
+    def __setattr__(self, key, value):
+        self[key] = value
+
+    def __delattr__(self, item):
+        try:
+            del self[item]
+        except KeyError:
+            raise AttributeError(f"'DictConfig' object has no attribute '{item}'")
+
+
+def locate(name: str) -> Any:
+    """
+    Locate and return an object using a string like {x.__module__}.{x.__qualname__}.
+
+    Args:
+        name:Dotted path to the object
+
+    Returns:
+        The located object
+
+    Raises:
+        ImportError if the object cannot be found
+    """
+    return pydoc.locate(name)
+
+
+
+class LazyObject:
+
+    def __init__(self, target, **kwargs):
+        self._target = target
+        self._kwargs = kwargs
+
+    def instantiate(self, **kwargs):
+        new_kwargs = copy.deepcopy(self._kwargs)
+        new_kwargs.update(kwargs)
+        return self._target(**new_kwargs)
+
+
+class LazyCall:
+
+    def __init__(self, target):
+        if not callable(target):
+            raise ValueError(f"`target` of LazyCall must be a callable, got {target}")
+        self._target = target
+
+    def __call__(self, **kwargs):
+        return LazyObject(self._target, **kwargs)
+
+
+def instantiate(config: LazyObject, **kwargs):
+    if config is None:
+        return None
+    return config.instantiate(**kwargs)
+

hyimage/common/constants.py

@@ -0,0 +1,7 @@
+import torch
+
+PRECISION_TO_TYPE = {
+    "fp32": torch.float32,
+    "fp16": torch.float16,
+    "bf16": torch.bfloat16,
+}

hyimage/common/format_prompt.py

@@ -0,0 +1,70 @@
+import json
+
+
+def closest_color(requested_color):
+    import webcolors
+
+    min_colors = {}
+    for key, name in webcolors.CSS3_HEX_TO_NAMES.items():
+
+        r_c, g_c, b_c = webcolors.hex_to_rgb(key)
+        rd = (r_c - requested_color[0]) ** 2
+        gd = (g_c - requested_color[1]) ** 2
+        bd = (b_c - requested_color[2]) ** 2
+        min_colors[(rd + gd + bd)] = name
+    return min_colors[min(min_colors.keys())]
+
+
+def convert_rgb_to_names(rgb_tuple):
+    try:
+        import webcolors
+
+        color_name = webcolors.rgb_to_name(rgb_tuple)
+    except ValueError:
+        color_name = closest_color(rgb_tuple)
+    return color_name
+
+
+class MultilingualPromptFormat:
+
+    def __init__(
+        self,
+        font_path: str = 'assets/glyph_sdxl_assets/multilingual_10-lang_idx.json',
+        color_path: str = 'assets/glyph_sdxl_assets/color_idx.json',
+    ):
+        with open(font_path, 'r') as f:
+            self.font_dict = json.load(f)
+        with open(color_path, 'r') as f:
+            self.color_dict = json.load(f)
+
+    def format_prompt(self, texts, styles):
+        '''
+        Text "{text}" in {color}, {type}.
+        '''
+
+        prompt = ""
+        for text, style in zip(texts, styles):
+            text_prompt = f'Text "{text}"'
+
+            attr_list = []
+
+            # format color
+            if style["color"] is not None:
+                import webcolors
+
+                hex_color = style["color"]
+                rgb_color = webcolors.hex_to_rgb(hex_color)
+                color_name = convert_rgb_to_names(rgb_color)
+                attr_list.append(f"<color-{self.color_dict[color_name]}>")
+
+            # format font
+            if style["font-family"] is not None:
+                attr_list.append(f"<{style['font-family'][:2]}-font-{self.font_dict[style['font-family']]}>")
+                attr_suffix = ", ".join(attr_list)
+                text_prompt += " in " + attr_suffix
+                text_prompt += ". "
+            else:
+                text_prompt += ". "
+
+            prompt = prompt + text_prompt
+        return prompt

hyimage/diffusion/cfg_utils.py

@@ -0,0 +1,140 @@
+import math
+import torch
+from typing import Dict, List, Optional, Tuple, Union
+
+def rescale_noise_cfg(noise_cfg, noise_pred_text, guidance_rescale=0.0):
+    r"""
+    Rescales `noise_cfg` tensor based on `guidance_rescale` to improve image quality and fix overexposure. Based on
+    Section 3.4 from [Common Diffusion Noise Schedules and Sample Steps are
+    Flawed](https://arxiv.org/pdf/2305.08891.pdf).
+
+    Args:
+        noise_cfg (`torch.Tensor`):
+            The predicted noise tensor for the guided diffusion process.
+        noise_pred_text (`torch.Tensor`):
+            The predicted noise tensor for the text-guided diffusion process.
+        guidance_rescale (`float`, *optional*, defaults to 0.0):
+            A rescale factor applied to the noise predictions.
+    Returns:
+        noise_cfg (`torch.Tensor`): The rescaled noise prediction tensor.
+    """
+    std_text = noise_pred_text.std(dim=list(range(1, noise_pred_text.ndim)), keepdim=True)
+    std_cfg = noise_cfg.std(dim=list(range(1, noise_cfg.ndim)), keepdim=True)
+    # rescale the results from guidance (fixes overexposure)
+    noise_pred_rescaled = noise_cfg * (std_text / std_cfg)
+    # mix with the original results from guidance by factor guidance_rescale to avoid "plain looking" images
+    noise_cfg = guidance_rescale * noise_pred_rescaled + (1 - guidance_rescale) * noise_cfg
+    return noise_cfg
+
+class ClassifierFreeGuidance:
+    def __init__(
+        self,
+        guidance_scale: float = 7.5,
+        guidance_rescale: float = 0.0,
+        use_original_formulation: bool = False,
+        start: float = 0.0,
+        stop: float = 1.0,
+    ):
+        super().__init__()
+
+        self.guidance_scale = guidance_scale
+        self.guidance_rescale = guidance_rescale
+        self.use_original_formulation = use_original_formulation
+
+    def __call__(self, pred_cond: torch.Tensor, pred_uncond: Optional[torch.Tensor] = None) -> torch.Tensor:
+
+        shift = pred_cond - pred_uncond
+        pred = pred_cond if self.use_original_formulation else pred_uncond
+        pred = pred + self.guidance_scale * shift
+
+        if self.guidance_rescale > 0.0:
+            pred = rescale_noise_cfg(pred, pred_cond, self.guidance_rescale)
+
+        return pred
+
+
+class MomentumBuffer:
+    def __init__(self, momentum: float):
+        self.momentum = momentum
+        self.running_average = 0
+
+    def update(self, update_value: torch.Tensor):
+        new_average = self.momentum * self.running_average
+        self.running_average = update_value + new_average
+
+def normalized_guidance_apg(
+    pred_cond: torch.Tensor,
+    pred_uncond: torch.Tensor,
+    guidance_scale: float,
+    momentum_buffer: Optional[MomentumBuffer] = None,
+    eta: float = 1.0,
+    norm_threshold: float = 0.0,
+    use_original_formulation: bool = False,
+):
+    diff = pred_cond - pred_uncond
+    dim = [-i for i in range(1, len(diff.shape))]
+
+    if momentum_buffer is not None:
+        momentum_buffer.update(diff)
+        diff = momentum_buffer.running_average
+
+    if norm_threshold > 0:
+        ones = torch.ones_like(diff)
+        diff_norm = diff.norm(p=2, dim=dim, keepdim=True)
+        scale_factor = torch.minimum(ones, norm_threshold / diff_norm)
+        diff = diff * scale_factor
+
+    v0, v1 = diff.double(), pred_cond.double()
+    v1 = torch.nn.functional.normalize(v1, dim=dim)
+    v0_parallel = (v0 * v1).sum(dim=dim, keepdim=True) * v1
+    v0_orthogonal = v0 - v0_parallel
+    diff_parallel, diff_orthogonal = v0_parallel.type_as(diff), v0_orthogonal.type_as(diff)
+
+    normalized_update = diff_orthogonal + eta * diff_parallel
+    pred = pred_cond if use_original_formulation else pred_uncond
+    pred = pred + guidance_scale * normalized_update
+
+    return pred
+
+class AdaptiveProjectedGuidance:
+    def __init__(
+        self,
+        guidance_scale: float = 7.5,
+        adaptive_projected_guidance_momentum: Optional[float] = None,
+        adaptive_projected_guidance_rescale: float = 15.0,
+        # eta: float = 1.0,
+        eta: float = 0.0,
+        guidance_rescale: float = 0.0,
+        use_original_formulation: bool = False,
+        start: float = 0.0,
+        stop: float = 1.0,
+    ):
+        super().__init__()
+
+        self.guidance_scale = guidance_scale
+        self.adaptive_projected_guidance_momentum = adaptive_projected_guidance_momentum
+        self.adaptive_projected_guidance_rescale = adaptive_projected_guidance_rescale
+        self.eta = eta
+        self.guidance_rescale = guidance_rescale
+        self.use_original_formulation = use_original_formulation
+        self.momentum_buffer = None
+
+    def __call__(self, pred_cond: torch.Tensor, pred_uncond: Optional[torch.Tensor] = None, step=None) -> torch.Tensor:
+
+        if step == 0 and self.adaptive_projected_guidance_momentum is not None:
+            self.momentum_buffer = MomentumBuffer(self.adaptive_projected_guidance_momentum)
+
+        pred = normalized_guidance_apg(
+            pred_cond,
+            pred_uncond,
+            self.guidance_scale,
+            self.momentum_buffer,
+            self.eta,
+            self.adaptive_projected_guidance_rescale,
+            self.use_original_formulation,
+        )
+
+        if self.guidance_rescale > 0.0:
+            pred = rescale_noise_cfg(pred, pred_cond, self.guidance_rescale)
+
+        return pred

hyimage/diffusion/pipelines/hunyuanimage_pipeline.py

@@ -0,0 +1,892 @@
+import re
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+from sympy import N
+from tqdm import tqdm
+import loguru
+import torch
+from hyimage.common.config.lazy import DictConfig
+from PIL import Image
+
+from hyimage.common.config import instantiate
+from hyimage.common.constants import PRECISION_TO_TYPE
+from hyimage.common.format_prompt import MultilingualPromptFormat
+from hyimage.models.text_encoder import PROMPT_TEMPLATE
+from hyimage.models.model_zoo import HUNYUANIMAGE_REPROMPT
+from hyimage.models.text_encoder.byT5 import load_glyph_byT5_v2
+from hyimage.models.hunyuan.modules.hunyuanimage_dit import load_hunyuan_dit_state_dict
+from hyimage.diffusion.cfg_utils import AdaptiveProjectedGuidance, rescale_noise_cfg
+
+
+@dataclass
+class HunyuanImagePipelineConfig:
+    """
+    Configuration class for HunyuanImage diffusion pipeline.
+
+    This dataclass consolidates all configuration parameters for the pipeline,
+    including model configurations (DiT, VAE, text encoder) and pipeline
+    parameters (sampling steps, guidance scale, etc.).
+    """
+
+    # Model configurations
+    dit_config: DictConfig
+    vae_config: DictConfig
+    text_encoder_config: DictConfig
+    reprompt_config: DictConfig
+    refiner_model_name: str = "hunyuanimage-refiner"
+
+    enable_dit_offloading: bool = True
+    enable_reprompt_model_offloading: bool = True
+    enable_refiner_offloading: bool = True
+
+    cfg_mode: str = "MIX_mode_0"
+    guidance_rescale: float = 0.0
+
+    # Pipeline parameters
+    default_sampling_steps: int = 50
+    # Default guidance scale, will be overridden by the guidance_scale parameter in __call__
+    default_guidance_scale: float = 3.5
+    # Inference shift
+    shift: int = 4
+    torch_dtype: str = "bf16"
+    device: str = "cuda"
+    version: str = ""
+
+    @classmethod
+    def create_default(cls, version: str = "v2.1", use_distilled: bool = False, **kwargs):
+        """
+        Create a default configuration for specified HunyuanImage version.
+
+        Args:
+            version: HunyuanImage version, only "v2.1" is supported
+            use_distilled: Whether to use distilled model
+            **kwargs: Additional configuration options
+        """
+        if version == "v2.1":
+            from hyimage.models.model_zoo import (
+                HUNYUANIMAGE_V2_1_DIT,
+                HUNYUANIMAGE_V2_1_DIT_CFG_DISTILL,
+                HUNYUANIMAGE_V2_1_VAE_32x,
+                HUNYUANIMAGE_V2_1_TEXT_ENCODER,
+            )
+            dit_config = HUNYUANIMAGE_V2_1_DIT_CFG_DISTILL() if use_distilled else HUNYUANIMAGE_V2_1_DIT()
+            return cls(
+                dit_config=dit_config,
+                vae_config=HUNYUANIMAGE_V2_1_VAE_32x(),
+                text_encoder_config=HUNYUANIMAGE_V2_1_TEXT_ENCODER(),
+                reprompt_config=HUNYUANIMAGE_REPROMPT(),
+                version=version,
+                **kwargs
+            )
+        else:
+            raise ValueError(f"Unsupported HunyuanImage version: {version}. Only 'v2.1' is supported")
+
+
+class HunyuanImagePipeline:
+    """
+    User-friendly pipeline for HunyuanImage text-to-image generation.
+
+    This pipeline provides a simple interface similar to diffusers library
+    for generating high-quality images from text prompts.
+
+    Supports HunyuanImage 2.1 version with automatic configuration.
+    Both default and distilled (CFG distillation) models are supported.
+    """
+
+    def __init__(
+        self,
+        config: HunyuanImagePipelineConfig,
+        **kwargs
+    ):
+        """
+        Initialize the HunyuanImage diffusion pipeline.
+
+        Args:
+            config: Configuration object containing all model and pipeline settings
+            **kwargs: Additional configuration options
+        """
+        self.config = config
+        self.default_sampling_steps = config.default_sampling_steps
+        self.default_guidance_scale = config.default_guidance_scale
+        self.shift = config.shift
+        self.torch_dtype = PRECISION_TO_TYPE[config.torch_dtype]
+        self.device = config.device
+        self.execution_device = config.device
+
+        self.dit = None
+        self.text_encoder = None
+        self.vae = None
+        self.byt5_kwargs = None
+        self.prompt_format = None
+
+        self.enable_dit_offloading = config.enable_dit_offloading
+        self.enable_reprompt_model_offloading = config.enable_reprompt_model_offloading
+        self.enable_refiner_offloading = config.enable_refiner_offloading
+
+
+        self.cfg_mode = config.cfg_mode
+        self.guidance_rescale = config.guidance_rescale
+
+        if self.cfg_mode == "APG_mode_0":
+            self.cfg_guider = AdaptiveProjectedGuidance(guidance_scale=10.0, eta=0.0,
+                                                        adaptive_projected_guidance_rescale=10.0,
+                                                        adaptive_projected_guidance_momentum=-0.5)
+            self.apg_start_step = 10
+        elif self.cfg_mode == "MIX_mode_0":
+            self.cfg_guider_ocr = AdaptiveProjectedGuidance(guidance_scale=10.0, eta=0.0,
+                                                            adaptive_projected_guidance_rescale=10.0,
+                                                            adaptive_projected_guidance_momentum=-0.5)
+            self.apg_start_step_ocr = 75
+
+            self.cfg_guider_general = AdaptiveProjectedGuidance(guidance_scale=10.0, eta=0.0,
+                                                                adaptive_projected_guidance_rescale=10.0,
+                                                                adaptive_projected_guidance_momentum=-0.5)
+            self.apg_start_step_general = 10
+
+        self.ocr_mask = []
+
+
+        self._load_models()
+
+    def _load_dit(self):
+        try:
+            dit_config = self.config.dit_config
+            self.dit = instantiate(dit_config.model)
+            if dit_config.load_from:
+                load_hunyuan_dit_state_dict(self.dit, dit_config.load_from, strict=True)
+            else:
+                raise ValueError("Must provide checkpoint path for DiT model")
+            self.dit = self.dit.to(self.device, dtype=self.torch_dtype)
+            self.dit.eval()
+            if getattr(dit_config, "use_compile", False):
+                self.dit = torch.compile(self.dit)
+            loguru.logger.info("✓ DiT model loaded")
+        except Exception as e:
+            raise RuntimeError(f"Error loading DiT model: {e}") from e
+
+    def _load_text_encoder(self):
+        try:
+            text_encoder_config = self.config.text_encoder_config
+            if not text_encoder_config.load_from:
+                raise ValueError("Must provide checkpoint path for text encoder")
+
+            if text_encoder_config.prompt_template is not None:
+                prompt_template = PROMPT_TEMPLATE[text_encoder_config.prompt_template]
+                crop_start = prompt_template.get("crop_start", 0)
+            else:
+                crop_start = 0
+                prompt_template = None
+            max_length = text_encoder_config.text_len + crop_start
+
+            self.text_encoder = instantiate(
+                text_encoder_config.model,
+                max_length=max_length,
+                text_encoder_path=os.path.join(text_encoder_config.load_from, "llm"),
+                prompt_template=prompt_template,
+                logger=None,
+                device=self.device,
+            )
+            loguru.logger.info("✓ HunyuanImage text encoder loaded")
+        except Exception as e:
+            raise RuntimeError(f"Error loading text encoder: {e}") from e
+
+    def _load_vae(self):
+        try:
+            vae_config = self.config.vae_config
+            self.vae = instantiate(
+                vae_config.model,
+                vae_path=vae_config.load_from,
+            )
+            self.vae = self.vae.to(self.device)
+            loguru.logger.info("✓ VAE loaded")
+        except Exception as e:
+            raise RuntimeError(f"Error loading VAE: {e}") from e
+
+    def _load_reprompt_model(self):
+        try:
+            reprompt_config = self.config.reprompt_config
+            self._reprompt_model = instantiate(reprompt_config.model, models_root_path=reprompt_config.load_from, enable_offloading=self.enable_reprompt_model_offloading)
+            loguru.logger.info("✓ Reprompt model loaded")
+        except Exception as e:
+            raise RuntimeError(f"Error loading reprompt model: {e}") from e
+
+    @property
+    def refiner_pipeline(self):
+        """
+        As the refiner model is an optional component, we load it on demand.
+        """
+        if hasattr(self, '_refiner_pipeline') and self._refiner_pipeline is not None:
+            return self._refiner_pipeline
+        from hyimage.diffusion.pipelines.hunyuanimage_refiner_pipeline import HunYuanImageRefinerPipeline
+        self._refiner_pipeline = HunYuanImageRefinerPipeline.from_pretrained(self.config.refiner_model_name)
+        return self._refiner_pipeline
+
+    @property
+    def reprompt_model(self):
+        """
+        As the reprompt model is an optional component, we load it on demand.
+        """
+        if hasattr(self, '_reprompt_model') and self._reprompt_model is not None:
+            return self._reprompt_model
+        self._load_reprompt_model()
+        return self._reprompt_model
+
+    def _load_byt5(self):
+
+        assert self.dit is not None, "DiT model must be loaded before byT5"
+
+        if not self.use_byt5:
+            self.byt5_kwargs = None
+            self.prompt_format = None
+            return
+
+        try:
+
+            text_encoder_config = self.config.text_encoder_config
+
+            glyph_root = os.path.join(self.config.text_encoder_config.load_from, "Glyph-SDXL-v2")
+            if not os.path.exists(glyph_root):
+                raise RuntimeError(
+                    f"Glyph checkpoint not found from '{glyph_root}'. \n"
+                    "Please download from https://modelscope.cn/models/AI-ModelScope/Glyph-SDXL-v2/files.\n\n"
+                    "- Required files:\n"
+                    "    Glyph-SDXL-v2\n"
+                    "    ├── assets\n"
+                    "    │   ├── color_idx.json\n"
+                    "    │   └── multilingual_10-lang_idx.json\n"
+                    "    └── checkpoints\n"
+                    "        └── byt5_model.pt\n"
+                )
+                    
+
+            byT5_google_path = os.path.join(text_encoder_config.load_from, "byt5-small")
+            if not os.path.exists(byT5_google_path):
+                loguru.logger.warning(f"ByT5 google path not found from: {byT5_google_path}. Try downloading from https://huggingface.co/google/byt5-small.")
+                byT5_google_path = "google/byt5-small"
+
+
+            multilingual_prompt_format_color_path = os.path.join(glyph_root, "assets/color_idx.json")
+            multilingual_prompt_format_font_path = os.path.join(glyph_root, "assets/multilingual_10-lang_idx.json")
+
+            byt5_args = dict(
+                byT5_google_path=byT5_google_path,
+                byT5_ckpt_path=os.path.join(glyph_root, "checkpoints/byt5_model.pt"),
+                multilingual_prompt_format_color_path=multilingual_prompt_format_color_path,
+                multilingual_prompt_format_font_path=multilingual_prompt_format_font_path,
+                byt5_max_length=128
+            )
+
+            self.byt5_kwargs = load_glyph_byT5_v2(byt5_args, device=self.device)
+            self.prompt_format = MultilingualPromptFormat(
+                font_path=multilingual_prompt_format_font_path,
+                color_path=multilingual_prompt_format_color_path
+            )
+            loguru.logger.info("✓ byT5 glyph processor loaded")
+        except Exception as e:
+            raise RuntimeError("Error loading byT5 glyph processor") from e
+
+    def _load_models(self):
+        """
+        Load all model components.
+        """
+        loguru.logger.info("Loading HunyuanImage models...")
+        self._load_vae()
+        self._load_dit()
+        self._load_byt5()
+        self._load_text_encoder()
+
+
+    def _encode_text(self, prompt: str, data_type: str = "image"):
+        """
+        Encode text prompt to embeddings.
+
+        Args:
+            prompt: The text prompt
+            data_type: The type of data ("image" by default)
+
+        Returns:
+            Tuple of (text_emb, text_mask)
+        """
+        text_inputs = self.text_encoder.text2tokens(prompt)
+        with torch.no_grad():
+            text_outputs = self.text_encoder.encode(
+                text_inputs,
+                data_type=data_type,
+            )
+            text_emb = text_outputs.hidden_state
+            text_mask = text_outputs.attention_mask
+        return text_emb, text_mask
+
+    def _encode_glyph(self, prompt: str):
+        """
+        Encode glyph information using byT5.
+
+        Args:
+            prompt: The text prompt
+
+        Returns:
+            Tuple of (byt5_emb, byt5_mask)
+        """
+        if not self.use_byt5:
+            return None, None
+
+        if not prompt:
+            return (
+                torch.zeros((1, self.byt5_kwargs["byt5_max_length"], 1472), device=self.device),
+                torch.zeros((1, self.byt5_kwargs["byt5_max_length"]), device=self.device, dtype=torch.int64)
+            )
+
+        try:
+            text_prompt_texts = []
+            pattern_quote_single = r'\'(.*?)\''
+            pattern_quote_double = r'\"(.*?)\"'
+            pattern_quote_chinese_single = r'‘(.*?)’'
+            pattern_quote_chinese_double = r'“(.*?)”'
+
+            matches_quote_single = re.findall(pattern_quote_single, prompt)
+            matches_quote_double = re.findall(pattern_quote_double, prompt)
+            matches_quote_chinese_single = re.findall(pattern_quote_chinese_single, prompt)
+            matches_quote_chinese_double = re.findall(pattern_quote_chinese_double, prompt)
+
+            text_prompt_texts.extend(matches_quote_single)
+            text_prompt_texts.extend(matches_quote_double)
+            text_prompt_texts.extend(matches_quote_chinese_single)
+            text_prompt_texts.extend(matches_quote_chinese_double)
+
+            if not text_prompt_texts:
+                self.ocr_mask = [False]
+                return (
+                    torch.zeros((1, self.byt5_kwargs["byt5_max_length"], 1472), device=self.device),
+                    torch.zeros((1, self.byt5_kwargs["byt5_max_length"]), device=self.device, dtype=torch.int64)
+                )
+            self.ocr_mask = [True]
+
+            text_prompt_style_list = [{'color': None, 'font-family': None} for _ in range(len(text_prompt_texts))]
+            glyph_text_formatted = self.prompt_format.format_prompt(text_prompt_texts, text_prompt_style_list)
+
+            byt5_text_ids, byt5_text_mask = self._get_byt5_text_tokens(
+                self.byt5_kwargs["byt5_tokenizer"],
+                self.byt5_kwargs["byt5_max_length"],
+                glyph_text_formatted
+            )
+
+            byt5_text_ids = byt5_text_ids.to(device=self.device)
+            byt5_text_mask = byt5_text_mask.to(device=self.device)
+
+            byt5_prompt_embeds = self.byt5_kwargs["byt5_model"](
+                byt5_text_ids, attention_mask=byt5_text_mask.float()
+            )
+            byt5_emb = byt5_prompt_embeds[0]
+
+            return byt5_emb, byt5_text_mask
+        except Exception as e:
+            loguru.logger.warning(f"Warning: Error in glyph encoding, using fallback: {e}")
+            return (
+                torch.zeros((1, self.byt5_kwargs["byt5_max_length"], 1472), device=self.device),
+                torch.zeros((1, self.byt5_kwargs["byt5_max_length"]), device=self.device, dtype=torch.int64)
+            )
+
+    def _get_byt5_text_tokens(self, tokenizer, max_length, text_list):
+        """
+        Get byT5 text tokens.
+
+        Args:
+            tokenizer: The tokenizer object
+            max_length: Maximum token length
+            text_list: List or string of text
+
+        Returns:
+            Tuple of (byt5_text_ids, byt5_text_mask)
+        """
+        if isinstance(text_list, list):
+            text_prompt = " ".join(text_list)
+        else:
+            text_prompt = text_list
+
+        byt5_text_inputs = tokenizer(
+            text_prompt,
+            padding="max_length",
+            max_length=max_length,
+            truncation=True,
+            add_special_tokens=True,
+            return_tensors="pt",
+        )
+
+        byt5_text_ids = byt5_text_inputs.input_ids
+        byt5_text_mask = byt5_text_inputs.attention_mask
+
+        return byt5_text_ids, byt5_text_mask
+
+    def _prepare_latents(self, width: int, height: int, generator: torch.Generator, batch_size: int = 1):
+        """
+        Prepare initial noise latents.
+
+        Args:
+            width: Image width
+            height: Image height
+            generator: Torch random generator
+            batch_size: Batch size
+
+        Returns:
+            Latent tensor
+        """
+        vae_downsampling_factor = 32
+        assert width % vae_downsampling_factor == 0 and height % vae_downsampling_factor == 0, (
+            f"width and height must be divisible by {vae_downsampling_factor}, but got {width} and {height}"
+        )
+        latent_width = width // vae_downsampling_factor
+        latent_height = height // vae_downsampling_factor
+        latent_channels = 64
+
+        if len(self.dit.patch_size) == 3:
+            latent_shape = (batch_size, latent_channels, 1, latent_height, latent_width)
+        elif len(self.dit.patch_size) == 2:
+            latent_shape = (batch_size, latent_channels, latent_height, latent_width)
+        else:
+            raise ValueError(f"Unsupported patch_size: {self.dit.patch_size}")
+
+        
+        # Generate random noise with shape latent_shape
+        latents = torch.randn(
+            latent_shape,
+            device=generator.device,
+            dtype=self.torch_dtype,
+            generator=generator,
+        ).to(device=self.device)
+
+        return latents
+
+    def _denoise_step(self, latents, timesteps, text_emb, text_mask, byt5_emb, byt5_mask, guidance_scale: float = 1.0, timesteps_r=None):
+        """
+        Perform one denoising step.
+
+        Args:
+            latents: Latent tensor
+            timesteps: Timesteps tensor
+            text_emb: Text embedding
+            text_mask: Text mask
+            byt5_emb: byT5 embedding
+            byt5_mask: byT5 mask
+            guidance_scale: Guidance scale
+            timesteps_r: Optional next timestep
+
+        Returns:
+            Noise prediction tensor
+        """
+        if byt5_emb is not None and byt5_mask is not None:
+            extra_kwargs = {
+                "byt5_text_states": byt5_emb,
+                "byt5_text_mask": byt5_mask,
+            }
+        else:
+            if self.use_byt5:
+                raise ValueError("Must provide byt5_emb and byt5_mask for HunyuanImage 2.1")
+            extra_kwargs = {}
+
+        with torch.no_grad(), torch.autocast(device_type="cuda", dtype=torch.bfloat16, enabled=True):
+            if hasattr(self.dit, 'guidance_embed') and self.dit.guidance_embed:
+                guidance_expand = torch.tensor(
+                    [guidance_scale] * latents.shape[0],
+                    dtype=torch.float32,
+                    device=latents.device
+                ).to(latents.dtype) * 1000
+            else:
+                guidance_expand = None
+
+            noise_pred = self.dit(
+                latents,
+                timesteps,
+                text_states=text_emb,
+                encoder_attention_mask=text_mask,
+                guidance=guidance_expand,
+                return_dict=False,
+                extra_kwargs=extra_kwargs,
+                timesteps_r=timesteps_r,
+            )[0]
+
+        return noise_pred
+
+    def _apply_classifier_free_guidance(self, noise_pred, guidance_scale: float, i: int):
+        """
+        Apply classifier-free guidance.
+
+        Args:
+            noise_pred: Noise prediction tensor
+            guidance_scale: Guidance scale
+
+        Returns:
+            Guided noise prediction tensor
+        """
+        if guidance_scale == 1.0:
+            return noise_pred
+
+        noise_pred_uncond, noise_pred_text = noise_pred.chunk(2)
+
+
+        if self.cfg_mode.startswith("APG_mode_"):
+            if i <= self.apg_start_step:
+                noise_pred = noise_pred_uncond + guidance_scale * (
+                        noise_pred_text - noise_pred_uncond
+                )
+                _ = self.cfg_guider(noise_pred_text, noise_pred_uncond, step=i)
+            else:
+                noise_pred = self.cfg_guider(noise_pred_text, noise_pred_uncond, step=i)
+        elif self.cfg_mode.startswith("MIX_mode_"):
+
+            ocr_mask_bool = torch.tensor(self.ocr_mask, dtype=torch.bool)
+
+            true_idx = torch.where(ocr_mask_bool)[0]
+            false_idx = torch.where(~ocr_mask_bool)[0]
+
+            noise_pred_text_true = noise_pred_text[true_idx] if len(true_idx) > 0 else \
+                torch.empty((0, noise_pred_text.size(1)), dtype=noise_pred_text.dtype, device=noise_pred_text.device)
+            noise_pred_text_false = noise_pred_text[false_idx] if len(false_idx) > 0 else \
+                torch.empty((0, noise_pred_text.size(1)), dtype=noise_pred_text.dtype, device=noise_pred_text.device)
+
+            noise_pred_uncond_true = noise_pred_uncond[true_idx] if len(true_idx) > 0 else \
+                torch.empty((0, noise_pred_uncond.size(1)), dtype=noise_pred_uncond.dtype, device=noise_pred_uncond.device)
+            noise_pred_uncond_false = noise_pred_uncond[false_idx] if len(false_idx) > 0 else \
+                torch.empty((0, noise_pred_uncond.size(1)), dtype=noise_pred_uncond.dtype, device=noise_pred_uncond.device)
+
+            if len(noise_pred_text_true) > 0:
+                if i <= self.apg_start_step_ocr:
+                    noise_pred_true = noise_pred_uncond_true + guidance_scale * (
+                            noise_pred_text_true - noise_pred_uncond_true
+                    )
+                    _ = self.cfg_guider_ocr(noise_pred_text_true, noise_pred_uncond_true, step=i)
+                else:
+                    noise_pred_true = self.cfg_guider_ocr(noise_pred_text_true, noise_pred_uncond_true, step=i)
+            else:
+                noise_pred_true = noise_pred_text_true
+
+            if len(noise_pred_text_false) > 0:
+                if i <= self.apg_start_step_general:
+                    noise_pred_false = noise_pred_uncond_false + guidance_scale * (
+                            noise_pred_text_false - noise_pred_uncond_false
+                    )
+                    _ = self.cfg_guider_general(noise_pred_text_false, noise_pred_uncond_false, step=i)
+                else:
+                    noise_pred_false = self.cfg_guider_general(noise_pred_text_false, noise_pred_uncond_false, step=i)
+            else:
+                noise_pred_false = noise_pred_text_false
+
+            noise_pred = torch.empty_like(noise_pred_text)
+            if len(true_idx) > 0:
+                noise_pred[true_idx] = noise_pred_true
+            if len(false_idx) > 0:
+                noise_pred[false_idx] = noise_pred_false
+
+        else:
+            noise_pred = noise_pred_uncond + guidance_scale * (
+                    noise_pred_text - noise_pred_uncond
+            )
+
+            if self.do_classifier_free_guidance and self.guidance_rescale > 0.0:
+                # Based on 3.4. in https://arxiv.org/pdf/2305.08891.pdf
+                noise_pred = rescale_noise_cfg(
+                    noise_pred,
+                    noise_pred_text,
+                    guidance_rescale=self.guidance_rescale,
+                )
+
+
+        noise_pred = noise_pred_uncond + guidance_scale * (noise_pred_text - noise_pred_uncond)
+        return noise_pred
+
+    def _decode_latents(self, latents):
+        """
+        Decode latents to images using VAE.
+
+        Args:
+            latents: Latent tensor
+
+        Returns:
+            Image tensor
+        """
+        if hasattr(self.vae.config, "shift_factor") and self.vae.config.shift_factor:
+            latents = latents / self.vae.config.scaling_factor + self.vae.config.shift_factor
+        else:
+            latents = latents / self.vae.config.scaling_factor
+
+        if latents.ndim == 5:
+            latents = latents.squeeze(2)
+        if latents.ndim == 4:
+            latents = latents.unsqueeze(2)
+
+        with torch.autocast(device_type="cuda", dtype=torch.float16, enabled=True):
+            image = self.vae.decode(latents, return_dict=False)[0]
+            
+        # Post-process image - remove frame dimension and normalize
+        image = (image / 2 + 0.5).clamp(0, 1)
+        image = image[:, :, 0]  # Remove frame dimension for images
+        image = image.cpu().float()
+        
+        return image
+
+    def get_timesteps_sigmas(self, sampling_steps: int, shift):
+        sigmas = torch.linspace(1, 0, sampling_steps + 1)
+        sigmas = (shift * sigmas) / (1 + (shift - 1) * sigmas)
+        sigmas = sigmas.to(torch.float32)
+        timesteps = (sigmas[:-1] * 1000).to(dtype=torch.float32, device=self.device)
+        return timesteps, sigmas
+
+    def step(self, latents, noise_pred, sigmas, step_i):
+        return latents.float() - (sigmas[step_i] - sigmas[step_i + 1]) * noise_pred.float()
+
+    @torch.no_grad()
+    def __call__(
+        self,
+        prompt: str,
+        shift: int = 4,
+        negative_prompt: str = "",
+        width: int = 2048,
+        height: int = 2048,
+        use_reprompt: bool = False,
+        use_refiner: bool = False,
+        num_inference_steps: Optional[int] = None,
+        guidance_scale: Optional[float] = None,
+        seed: Optional[int] = 42,
+        **kwargs
+    ) -> Image.Image:
+        """
+        Generate an image from a text prompt.
+
+        Args:
+            prompt: Text prompt describing the image
+            negative_prompt: Negative prompt for guidance
+            width: Image width
+            height: Image height
+            use_reprompt: Whether to use reprompt model
+            use_refiner: Whether to use refiner pipeline
+            num_inference_steps: Number of denoising steps (overrides config if provided)
+            guidance_scale: Strength of classifier-free guidance (overrides config if provided)
+            seed: Random seed for reproducibility
+            **kwargs: Additional arguments
+
+        Returns:
+            Generated PIL Image
+        """
+        if seed is not None:
+            generator = torch.Generator(device='cpu').manual_seed(seed)
+        else:
+            generator = None
+
+        sampling_steps = num_inference_steps if num_inference_steps is not None else self.default_sampling_steps
+        guidance_scale = guidance_scale if guidance_scale is not None else self.default_guidance_scale
+        shift = shift if shift is not None else self.shift
+
+        user_prompt = prompt
+        if use_reprompt:
+            if self.enable_dit_offloading:
+                self.to('cpu')
+            prompt = self.reprompt_model.predict(prompt)
+            if self.enable_dit_offloading:
+                self.to(self.execution_device)
+
+        print("=" * 60)
+        print("🖼️  HunyuanImage Generation Task")
+        print("-" * 60)
+        print(f"Prompt:           {user_prompt}")
+        if use_reprompt:
+            print(f"Reprompt:         {prompt}")
+        if not self.cfg_distilled:
+            print(f"Negative Prompt:  {negative_prompt if negative_prompt else '(none)'}")
+        print(f"Guidance Scale:   {guidance_scale}")
+        print(f"CFG Mode:         {self.cfg_mode}")
+        print(f"Guidance Rescale: {self.guidance_rescale}")
+        print(f"Shift:            {self.shift}")
+        print(f"Seed:             {seed}")
+        print(f"Use MeanFlow:     {self.use_meanflow}")
+        print(f"Use byT5:         {self.use_byt5}")
+        print(f"Image Size:       {width} x {height}")
+        print(f"Sampling Steps:   {sampling_steps}")
+        print("=" * 60)
+
+        pos_text_emb, pos_text_mask = self._encode_text(prompt)
+        neg_text_emb, neg_text_mask = self._encode_text(negative_prompt)
+
+        pos_byt5_emb, pos_byt5_mask = self._encode_glyph(prompt)
+        neg_byt5_emb, neg_byt5_mask = self._encode_glyph(negative_prompt)
+
+        latents = self._prepare_latents(width, height, generator=generator)
+
+        do_classifier_free_guidance = (not self.cfg_distilled) and guidance_scale > 1
+        if do_classifier_free_guidance:
+            text_emb = torch.cat([neg_text_emb, pos_text_emb])
+            text_mask = torch.cat([neg_text_mask, pos_text_mask])
+
+            if self.use_byt5 and pos_byt5_emb is not None and neg_byt5_emb is not None:
+                byt5_emb = torch.cat([neg_byt5_emb, pos_byt5_emb])
+                byt5_mask = torch.cat([neg_byt5_mask, pos_byt5_mask])
+            else:
+                byt5_emb = pos_byt5_emb
+                byt5_mask = pos_byt5_mask
+        else:
+            text_emb = pos_text_emb
+            text_mask = pos_text_mask
+            byt5_emb = pos_byt5_emb
+            byt5_mask = pos_byt5_mask
+
+        timesteps, sigmas = self.get_timesteps_sigmas(sampling_steps, shift)
+
+        for i, t in enumerate(tqdm(timesteps, desc="Denoising", total=len(timesteps))):
+            latent_model_input = torch.cat([latents] * 2) if do_classifier_free_guidance else latents
+            t_expand = t.repeat(latent_model_input.shape[0])
+            if self.use_meanflow:
+                if i == len(timesteps) - 1:
+                    timesteps_r = torch.tensor([0.0], device=self.device)
+                else:
+                    timesteps_r = timesteps[i + 1]
+                timesteps_r = timesteps_r.repeat(latent_model_input.shape[0])
+            else:
+                timesteps_r = None
+
+            if self.cfg_distilled:
+                noise_pred = self._denoise_step(
+                    latent_model_input, t_expand, text_emb, text_mask, byt5_emb, byt5_mask, guidance_scale, timesteps_r=timesteps_r,
+                )
+            else:
+                noise_pred = self._denoise_step(
+                    latent_model_input, t_expand, text_emb, text_mask, byt5_emb, byt5_mask, timesteps_r=timesteps_r,
+                )
+
+            if do_classifier_free_guidance:
+                noise_pred = self._apply_classifier_free_guidance(noise_pred, guidance_scale, i)
+
+            latents = self.step(latents, noise_pred, sigmas, i)
+
+
+        image = self._decode_latents(latents)
+        image = (image.squeeze(0).permute(1, 2, 0) * 255).byte().numpy()
+        pil_image = Image.fromarray(image)
+
+        if use_refiner:
+            if self.enable_dit_offloading:
+                self.to('cpu')
+            if self.enable_refiner_offloading:
+                self.refiner_pipeline.to(self.execution_device)
+            pil_image = self.refiner_pipeline(
+                image=pil_image,
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                width=width,
+                height=height,
+                use_reprompt=False,
+                use_refiner=False,
+                num_inference_steps=4,
+                guidance_scale=guidance_scale,
+                generator=generator,
+            )
+            if self.enable_refiner_offloading:
+                self.refiner_pipeline.to('cpu')
+            if self.enable_dit_offloading:
+                self.to(self.execution_device)
+
+        return pil_image
+
+    @property
+    def use_meanflow(self):
+        return getattr(self.dit, 'use_meanflow', False)
+
+    @property
+    def use_byt5(self):
+        return getattr(self.dit, 'glyph_byT5_v2', False)
+
+    @property
+    def cfg_distilled(self):
+        return getattr(self.dit, 'guidance_embed', False)
+
+    def to(self, device: str | torch.device):
+        """
+        Move pipeline to specified device.
+
+        Args:
+            device: Target device string
+
+        Returns:
+            Self
+        """
+        self.device = device
+        if self.dit is not None:
+            self.dit = self.dit.to(device, non_blocking=True)
+        if self.text_encoder is not None:
+            self.text_encoder = self.text_encoder.to(device, non_blocking=True)
+        if self.vae is not None:
+            self.vae = self.vae.to(device, non_blocking=True)
+        return self
+
+    def update_config(self, **kwargs):
+        """
+        Update configuration parameters.
+
+        Args:
+            **kwargs: Key-value pairs to update
+
+        Returns:
+            Self
+        """
+        for key, value in kwargs.items():
+            if hasattr(self.config, key):
+                setattr(self.config, key, value)
+                if hasattr(self, key):
+                    setattr(self, key, value)
+        return self
+
+    @classmethod
+    def from_pretrained(cls, model_name: str = "hunyuanimage-v2.1", use_distilled: bool = False, **kwargs):
+        """
+        Create pipeline from pretrained model.
+
+        Args:
+            model_name: Model name, supports "hunyuanimage-v2.1", "hunyuanimage-v2.1-distilled"
+            use_distilled: Whether to use distilled model (overrides model_name if specified)
+            **kwargs: Additional configuration options
+
+        Returns:
+            HunyuanImagePipeline instance
+        """
+        if model_name == "hunyuanimage-v2.1":
+            version = "v2.1"
+            use_distilled = False
+        elif model_name == "hunyuanimage-v2.1-distilled":
+            version = "v2.1"
+            use_distilled = True
+        else:
+            raise ValueError(
+                f"Unsupported model name: {model_name}. Supported names: 'hunyuanimage-v2.1', 'hunyuanimage-v2.1-distilled'"
+            )
+
+        config = HunyuanImagePipelineConfig.create_default(
+            version=version, use_distilled=use_distilled, **kwargs
+        )
+        return cls(config=config)
+
+    @classmethod
+    def from_config(cls, config: HunyuanImagePipelineConfig):
+        """
+        Create pipeline from configuration object.
+
+        Args:
+            config: HunyuanImagePipelineConfig instance
+
+        Returns:
+            HunyuanImagePipeline instance
+        """
+        return cls(config=config)
+
+
+def DiffusionPipeline(model_name: str = "hunyuanimage-v2.1", use_distilled: bool = False, **kwargs):
+    """
+    Factory function to create HunyuanImagePipeline.
+
+    Args:
+        model_name: Model name, supports "hunyuanimage-v2.1", "hunyuanimage-v2.1-distilled"
+        use_distilled: Whether to use distilled model (overrides model_name if specified)
+        **kwargs: Additional configuration options
+
+    Returns:
+        HunyuanImagePipeline instance
+    """
+    return HunyuanImagePipeline.from_pretrained(model_name, use_distilled=use_distilled, **kwargs)

hyimage/diffusion/pipelines/hunyuanimage_refiner_pipeline.py

@@ -0,0 +1,272 @@
+from dataclasses import dataclass
+from typing import Optional, Union
+
+import torch
+from PIL import Image
+from tqdm import tqdm
+import torchvision.transforms as T
+
+from .hunyuanimage_pipeline import HunyuanImagePipeline, HunyuanImagePipelineConfig
+
+from hyimage.models.model_zoo import (
+    HUNYUANIMAGE_REFINER_DIT,
+    HUNYUANIMAGE_REFINER_VAE_32x,
+    HUNYUANIMAGE_REFINER_TEXT_ENCODER,
+)
+
+
+@dataclass
+class HunYuanImageRefinerPipelineConfig(HunyuanImagePipelineConfig):
+    """
+    Configuration class for HunyuanImage refiner pipeline.
+    
+    Inherits from HunyuanImagePipelineConfig and overrides specific parameters
+    for the refiner functionality.
+    """
+    
+    default_sampling_steps: int = 4
+    shift: int = 1
+    version: str = "v1.0"
+    cfg_mode: str = ""
+
+    @classmethod
+    def create_default(
+        cls,
+        version: str = "v1.0",
+        use_distilled: bool = False,
+        **kwargs,
+    ):
+        dit_config = HUNYUANIMAGE_REFINER_DIT()
+        vae_config = HUNYUANIMAGE_REFINER_VAE_32x()
+        text_encoder_config = HUNYUANIMAGE_REFINER_TEXT_ENCODER()
+
+        return cls(
+            dit_config=dit_config,
+            vae_config=vae_config,
+            text_encoder_config=text_encoder_config,
+            reprompt_config=None,
+            version=version,
+            **kwargs,
+        )
+
+
+class HunYuanImageRefinerPipeline(HunyuanImagePipeline):
+    """A refiner pipeline for HunyuanImage that inherits from the main pipeline.
+    
+    This pipeline refines existing images using the same model architecture
+    but with different default parameters and an image input.
+    """
+    
+    def __init__(self, config: HunYuanImageRefinerPipelineConfig, **kwargs):
+        """Initialize the refiner pipeline.
+        
+        Args:
+            config: Refiner-specific configuration
+            **kwargs: Additional arguments passed to parent class
+        """
+        assert isinstance(config, HunYuanImageRefinerPipelineConfig)
+        super().__init__(config, **kwargs)
+        assert self.cfg_distilled
+        
+    def _condition_aug(self, latents, noise=None, strength=0.3):
+        """Apply conditioning augmentation for refiner.
+        
+        Args:
+            latents: Input latents tensor
+            noise: Optional noise tensor, if None will be generated
+            strength: Augmentation strength factor
+            
+        Returns:
+            Augmented latents tensor
+        """
+        if noise is None:
+            noise = torch.randn_like(latents)
+        return strength * noise + (1 - strength) * latents
+
+    @torch.no_grad()
+    def __call__(
+        self,
+        prompt: str,
+        negative_prompt: str = "",
+        width: int = 2048,
+        height: int = 2048,
+        use_reprompt: bool = False,
+        num_inference_steps: Optional[int] = None,
+        guidance_scale: Optional[float] = None,
+        shift: int = 4,
+        seed: Optional[int] = 42,
+        image: Optional[Image.Image] = None,
+        **kwargs,
+    ) -> Image.Image:
+        """Refine an existing image using text guidance.
+
+        Args:
+            prompt: Text prompt describing the desired refinement
+            negative_prompt: Negative prompt for guidance
+            width: Image width
+            height: Image height
+            use_reprompt: Whether to use reprompt (ignored for refiner)
+            num_inference_steps: Number of denoising steps (overrides config if provided)
+            guidance_scale: Strength of classifier-free guidance (overrides config if provided)
+            seed: Random seed for reproducibility
+            image: Image to be refined (required for refiner)
+            **kwargs: Additional arguments
+
+        Returns:
+            Refined PIL Image
+        """
+        if image is None:
+            raise ValueError("Image parameter is required for refiner pipeline")
+            
+        if seed is not None:
+            generator = torch.Generator(device='cpu').manual_seed(seed)
+        else:
+            generator = None
+
+        sampling_steps = (
+            num_inference_steps
+            if num_inference_steps is not None
+            else self.default_sampling_steps
+        )
+        guidance_scale = (
+            guidance_scale if guidance_scale is not None else self.default_guidance_scale
+        )
+        shift = shift if shift is not None else self.shift
+
+        # Print log about current refinement task
+        print("=" * 60)
+        print("🔧 HunyuanImage Refinement Task")
+        print("-" * 60)
+        print(f"Prompt:           {prompt}")
+        print(f"Guidance Scale:   {guidance_scale}")
+        print(f"Shift:            {self.shift}")
+        print(f"Seed:             {seed}")
+        print(f"Image Size:       {width} x {height}")
+        print(f"Sampling Steps:   {sampling_steps}")
+        print("=" * 60)
+
+        # Encode prompts
+        pos_text_emb, pos_text_mask = self._encode_text(prompt)
+
+        latents = self._prepare_latents(width, height, generator=generator)
+
+        _pil_to_tensor = T.Compose(
+            [
+                T.ToTensor(),  # convert to tensor and normalize to [0, 1]
+                T.Normalize([0.5], [0.5]),  # transform to [-1, 1]
+            ]
+        )
+
+        image_tensor = (
+            _pil_to_tensor(image).unsqueeze(0).to("cuda", dtype=self.vae.dtype)
+        )
+
+        cond_latents = self.vae.encode(
+            image_tensor.to(self.device, dtype=self.vae.dtype)
+        ).latent_dist.sample()
+        
+        if (
+            hasattr(self.vae.config, "shift_factor")
+            and self.vae.config.shift_factor
+        ):
+            cond_latents.sub_(self.vae.config.shift_factor).mul_(
+                self.vae.config.scaling_factor
+            )
+        else:
+            cond_latents.mul_(self.vae.config.scaling_factor)
+        
+        # Add frame dimension for refiner model
+        cond_latents = cond_latents.unsqueeze(2)  # (b c 1 h w)
+        
+        # Apply conditioning augmentation
+        cond_latents = self._condition_aug(cond_latents)
+
+        timesteps, sigmas = self.get_timesteps_sigmas(sampling_steps, shift)
+
+        text_emb = pos_text_emb
+        text_mask = pos_text_mask
+
+        for i, t in enumerate(tqdm(timesteps, desc="Refining", total=len(timesteps))):
+            # Concatenate noise latents with condition latents for refiner input
+            latent_model_input = torch.cat([latents, cond_latents], dim=1)
+            t_expand = t.repeat(latent_model_input.shape[0])
+
+            # Predict noise with guidance
+            noise_pred = self._denoise_step(
+                latent_model_input,
+                t_expand,
+                text_emb,
+                text_mask,
+                None,
+                None,
+                guidance_scale,
+                timesteps_r=None,
+            )
+
+            latents = self.step(latents, noise_pred, sigmas, i)
+
+        refined_image = self._decode_latents(latents)
+
+        # Convert to PIL Image
+        refined_image = (refined_image.squeeze(0).permute(1, 2, 0) * 255).byte().numpy()
+        pil_image = Image.fromarray(refined_image)
+
+        return pil_image
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        model_name: str = "hunyuanimage-refiner",
+        use_distilled: bool = False,
+        **kwargs,
+    ):
+        """Create refiner pipeline from pretrained model.
+        
+        Args:
+            model_name: Model name, currently only supports "hunyuanimage-refiner"
+            use_distilled: Whether to use distilled model (unused for refiner)
+            **kwargs: Additional configuration options
+        """
+        if model_name == "hunyuanimage-refiner":
+            version = "v1.0"
+        else:
+            raise ValueError(
+                f"Unsupported refiner model name: {model_name}. Supported names: 'hunyuanimage-refiner'"
+            )
+
+        config = HunYuanImageRefinerPipelineConfig.create_default(
+            version=version, **kwargs
+        )
+
+        return cls(config=config)
+
+    @classmethod
+    def from_config(cls, config: Union[HunYuanImageRefinerPipelineConfig, HunyuanImagePipelineConfig]):
+        """Create refiner pipeline from configuration object.
+        
+        Args:
+            config: Configuration object for the pipeline
+            
+        Returns:
+            Initialized refiner pipeline instance
+        """
+        return cls(config=config)
+
+
+# Convenience function for easy access
+def RefinerPipeline(
+    model_name: str = "hunyuanimage-refiner",
+    **kwargs,
+):
+    """Factory function to create HunYuanImageRefinerPipeline.
+
+    Args:
+        model_name: Model name, currently only supports "hunyuanimage-refiner"
+        **kwargs: Additional configuration options
+        
+    Returns:
+        Initialized refiner pipeline instance
+    """
+    return HunYuanImageRefinerPipeline.from_pretrained(
+        model_name, **kwargs
+    )

hyimage/models/hunyuan/configs/hunyuanimage_config.py

@@ -0,0 +1,51 @@
+from hyimage.common.config import LazyCall as L
+from hyimage.models.hunyuan.modules.hunyuanimage_dit import HYImageDiffusionTransformer
+
+
+
+
+hunyuanimage_refiner_cfg = L(HYImageDiffusionTransformer)(
+    in_channels=128,
+    out_channels=64,
+    mm_double_blocks_depth=20,
+    mm_single_blocks_depth=40,
+    rope_dim_list=[16, 56, 56],
+    hidden_size=3328,
+    heads_num=26,
+    mlp_width_ratio=4,
+    patch_size=[1, 1, 1],
+    text_states_dim=3584,
+    guidance_embed=True,
+    use_meanflow=True,
+)
+
+hunyuanimage_v2_1_cfg = L(HYImageDiffusionTransformer)(
+    in_channels=64,
+    out_channels=64,
+    mm_double_blocks_depth=20,
+    mm_single_blocks_depth=40,
+    rope_dim_list=[64, 64],
+    hidden_size=3584,
+    heads_num=28,
+    mlp_width_ratio=4,
+    patch_size=[1, 1],
+    text_states_dim=3584,
+    glyph_byT5_v2=True,
+    guidance_embed=False,
+)
+
+hunyuanimage_v2_1_distilled_cfg = L(HYImageDiffusionTransformer)(
+    in_channels=64,
+    out_channels=64,
+    mm_double_blocks_depth=20,
+    mm_single_blocks_depth=40,
+    rope_dim_list=[64, 64],
+    hidden_size=3584,
+    heads_num=28,
+    mlp_width_ratio=4,
+    patch_size=[1, 1],
+    text_states_dim=3584,
+    glyph_byT5_v2=True,
+    guidance_embed=True,
+    use_meanflow=True,
+)

hyimage/models/hunyuan/modules/activation_layers.py

@@ -0,0 +1,23 @@
+import torch.nn as nn
+
+
+def get_activation_layer(act_type):
+    """get activation layer
+
+    Args:
+        act_type (str): the activation type
+
+    Returns:
+        torch.nn.functional: the activation layer
+    """
+    if act_type == "gelu":
+        return lambda: nn.GELU()
+    elif act_type == "gelu_tanh":
+        # Approximate `tanh` requires torch >= 1.13
+        return lambda: nn.GELU(approximate="tanh")
+    elif act_type == "relu":
+        return nn.ReLU
+    elif act_type == "silu":
+        return nn.SiLU
+    else:
+        raise ValueError(f"Unknown activation type: {act_type}")

hyimage/models/hunyuan/modules/embed_layers.py

@@ -0,0 +1,189 @@
+import math
+
+import torch
+import torch.nn as nn
+
+from ..utils.helpers import to_2tuple
+
+
+class PatchEmbed2D(nn.Module):
+
+    def __init__(
+        self,
+        patch_size=16,
+        in_chans=3,
+        embed_dim=768,
+        norm_layer=None,
+        flatten=True,
+        bias=True,
+        dtype=None,
+        device=None,
+    ):
+        super().__init__()
+        patch_size = to_2tuple(patch_size)
+        self.patch_size = patch_size
+        self.flatten = flatten
+
+        self.proj = nn.Conv2d(
+            in_chans, embed_dim, kernel_size=patch_size, stride=patch_size, bias=bias, device=device, dtype=dtype
+        )
+        nn.init.xavier_uniform_(self.proj.weight.view(self.proj.weight.size(0), -1))
+        if bias:
+            nn.init.zeros_(self.proj.bias)
+
+        self.norm = norm_layer(embed_dim) if norm_layer else nn.Identity()
+
+    def forward(self, x):
+        x = self.proj(x)
+        if self.flatten:
+            x = x.flatten(2).transpose(1, 2)
+        x = self.norm(x)
+        return x
+
+
+class PatchEmbed(nn.Module):
+    """2D Image to Patch Embedding
+
+    Image to Patch Embedding using Conv2d
+
+    A convolution based approach to patchifying a 2D image w/ embedding projection.
+
+    Based on the impl in https://github.com/google-research/vision_transformer
+
+    Hacked together by / Copyright 2020 Ross Wightman
+
+    Remove the _assert function in forward function to be compatible with multi-resolution images.
+    """
+
+    def __init__(
+        self,
+        patch_size=16,
+        in_chans=3,
+        embed_dim=768,
+        norm_layer=None,
+        flatten=True,
+        bias=True,
+        dtype=None,
+        device=None,
+    ):
+        factory_kwargs = {"dtype": dtype, "device": device}
+        super().__init__()
+        patch_size = to_2tuple(patch_size)
+        self.patch_size = patch_size
+        self.flatten = flatten
+
+        self.proj = nn.Conv3d(
+            in_chans,
+            embed_dim,
+            kernel_size=patch_size,
+            stride=patch_size,
+            bias=bias,
+            **factory_kwargs
+        )
+        nn.init.xavier_uniform_(self.proj.weight.view(self.proj.weight.size(0), -1))
+        if bias:
+            nn.init.zeros_(self.proj.bias)
+
+        self.norm = norm_layer(embed_dim) if norm_layer else nn.Identity()
+
+    def forward(self, x):
+        x = self.proj(x)
+        if self.flatten:
+            x = x.flatten(2).transpose(1, 2)  # BCHW -> BNC
+        x = self.norm(x)
+        return x
+
+
+class TextProjection(nn.Module):
+    """
+    Projects text embeddings. Also handles dropout for classifier-free guidance.
+
+    Adapted from https://github.com/PixArt-alpha/PixArt-alpha/blob/master/diffusion/model/nets/PixArt_blocks.py
+    """
+
+    def __init__(self, in_channels, hidden_size, act_layer, dtype=None, device=None):
+        factory_kwargs = {"dtype": dtype, "device": device}
+        super().__init__()
+        self.linear_1 = nn.Linear(
+            in_features=in_channels,
+            out_features=hidden_size,
+            bias=True,
+            **factory_kwargs
+        )
+        self.act_1 = act_layer()
+        self.linear_2 = nn.Linear(
+            in_features=hidden_size,
+            out_features=hidden_size,
+            bias=True,
+            **factory_kwargs
+        )
+
+    def forward(self, caption):
+        hidden_states = self.linear_1(caption)
+        hidden_states = self.act_1(hidden_states)
+        hidden_states = self.linear_2(hidden_states)
+        return hidden_states
+
+
+
+def timestep_embedding(t, dim, max_period=10000):
+    """
+    Create sinusoidal timestep embeddings.
+
+    Args:
+        t (torch.Tensor): a 1-D Tensor of N indices, one per batch element. These may be fractional.
+        dim (int): the dimension of the output.
+        max_period (int): controls the minimum frequency of the embeddings.
+
+    Returns:
+        embedding (torch.Tensor): An (N, D) Tensor of positional embeddings.
+
+    .. ref_link: https://github.com/openai/glide-text2im/blob/main/glide_text2im/nn.py
+    """
+    half = dim // 2
+    freqs = torch.exp(
+        -math.log(max_period)
+        * torch.arange(start=0, end=half, dtype=torch.float32)
+        / half
+    ).to(device=t.device)
+    args = t[:, None].float() * freqs[None]
+    embedding = torch.cat([torch.cos(args), torch.sin(args)], dim=-1)
+    if dim % 2:
+        embedding = torch.cat([embedding, torch.zeros_like(embedding[:, :1])], dim=-1)
+    return embedding
+
+
+class TimestepEmbedder(nn.Module):
+    """
+    Embeds scalar timesteps into vector representations.
+    """
+
+    def __init__(
+        self,
+        hidden_size,
+        act_layer,
+        frequency_embedding_size=256,
+        max_period=10000,
+        out_size=None,
+        dtype=None,
+        device=None,
+    ):
+        factory_kwargs = {"dtype": dtype, "device": device}
+        super().__init__()
+        self.frequency_embedding_size = frequency_embedding_size
+        self.max_period = max_period
+        if out_size is None:
+            out_size = hidden_size
+
+        self.mlp = nn.Sequential(
+            nn.Linear(frequency_embedding_size, hidden_size, bias=True, **factory_kwargs),
+            act_layer(),
+            nn.Linear(hidden_size, out_size, bias=True, **factory_kwargs),
+        )
+        nn.init.normal_(self.mlp[0].weight, std=0.02)
+        nn.init.normal_(self.mlp[2].weight, std=0.02)
+
+    def forward(self, t):
+        t_freq = timestep_embedding(t, self.frequency_embedding_size, self.max_period).type(self.mlp[0].weight.dtype)
+        t_emb = self.mlp(t_freq)
+        return t_emb

hyimage/models/hunyuan/modules/flash_attn_no_pad.py

@@ -0,0 +1,125 @@
+import torch
+from einops import rearrange
+
+try:
+    from flash_attn_interface import flash_attn_varlen_func
+
+    print("Using FlashAttention v3.")
+except ImportError:
+    print("FlashAttention v3 not found, falling back to v2.")
+    from flash_attn import flash_attn_varlen_func
+
+from flash_attn import flash_attn_varlen_qkvpacked_func
+from flash_attn.bert_padding import pad_input, unpad_input
+
+
+def get_cu_seqlens(text_mask: torch.Tensor, img_len: int):
+    """
+    Compute cumulative sequence lengths (cu_seqlens) for FlashAttention.
+
+    Args:
+        text_mask (torch.Tensor): Boolean mask of shape (batch_size, text_seq_len).
+        img_len (int): Length of image sequence.
+
+    Returns:
+        cu_seqlens (torch.Tensor): 1D tensor of cumulative sequence lengths for each segment.
+        max_len (int): Maximum sequence length (text + image).
+    """
+    batch_size = text_mask.shape[0]
+    text_len = text_mask.sum(dim=1)
+    max_len = text_mask.shape[1] + img_len
+
+    cu_seqlens = torch.zeros([2 * batch_size + 1], dtype=torch.int32, device=text_mask.device)
+    for i in range(batch_size):
+        s = text_len[i] + img_len
+        s1 = i * max_len + s
+        s2 = (i + 1) * max_len
+        cu_seqlens[2 * i + 1] = s1
+        cu_seqlens[2 * i + 2] = s2
+
+    return cu_seqlens, max_len
+
+
+def flash_attn_v3(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    v: torch.Tensor,
+    cu_seqlens: torch.Tensor,
+    max_s: int,
+    causal: bool = False,
+    deterministic: bool = False,
+):
+    """
+    FlashAttention v3 wrapper.
+
+    Args:
+        q, k, v (torch.Tensor): Query, key, value tensors of shape (batch, seq, nheads, head_dim).
+        cu_seqlens (torch.Tensor): Cumulative sequence lengths.
+        max_s (int): Maximum sequence length.
+        causal (bool): Whether to apply causal masking.
+        deterministic (bool): Deterministic computation.
+
+    Returns:
+        torch.Tensor: Output tensor of shape (batch, seq, nheads, head_dim).
+    """
+    batch_size, seqlen = q.shape[:2]
+    q = q.reshape(-1, *q.shape[2:])
+    k = k.reshape(-1, *k.shape[2:])
+    v = v.reshape(-1, *v.shape[2:])
+    output = flash_attn_varlen_func(
+        q, k, v, cu_seqlens, cu_seqlens, max_s, max_s, causal=causal, deterministic=deterministic
+    )
+    output = output.view(batch_size, seqlen, *output.shape[-2:])
+    return output
+
+
+def flash_attn_no_pad(
+    qkv: torch.Tensor,
+    key_padding_mask: torch.Tensor,
+    causal: bool = False,
+    dropout_p: float = 0.0,
+    softmax_scale=None,
+    deterministic: bool = False,
+):
+    """
+    FlashAttention for packed QKV input without padding.
+
+    Args:
+        qkv (torch.Tensor): Input tensor of shape (batch, seq, 3, nheads, head_dim).
+        key_padding_mask (torch.Tensor): Boolean mask of shape (batch, seq).
+        causal (bool): Whether to apply causal masking.
+        dropout_p (float): Dropout probability.
+        softmax_scale (float, optional): Softmax scaling factor.
+        deterministic (bool): Deterministic computation.
+
+    Returns:
+        torch.Tensor: Output tensor of shape (batch, seq, nheads, head_dim).
+    """
+    batch_size, seqlen, _, nheads, head_dim = qkv.shape
+    x = rearrange(qkv, "b s three h d -> b s (three h d)")
+
+    # Unpad input for FlashAttention, drop `used_seqlens_in_batch` for version compatibility
+    x_unpad, indices, cu_seqlens, max_s = unpad_input(x, key_padding_mask)[:4]
+    x_unpad = rearrange(x_unpad, "nnz (three h d) -> nnz three h d", three=3, h=nheads)
+
+    output_unpad = flash_attn_varlen_qkvpacked_func(
+        x_unpad,
+        cu_seqlens,
+        max_s,
+        dropout_p,
+        softmax_scale=softmax_scale,
+        causal=causal,
+        deterministic=deterministic,
+    )
+    if isinstance(output_unpad, tuple):
+        output_unpad = output_unpad[0]
+
+    # Pad output back to original shape
+    output = pad_input(
+        rearrange(output_unpad, "nnz h d -> nnz (h d)"),
+        indices,
+        batch_size,
+        seqlen,
+    )
+    output = rearrange(output, "b s (h d) -> b s h d", h=nheads)
+    return output

hyimage/models/hunyuan/modules/hunyuanimage_dit.py

@@ -0,0 +1,556 @@
+import os
+from typing import Dict, List, Optional, Union
+
+import torch
+import torch.nn as nn
+from diffusers.configuration_utils import ConfigMixin, register_to_config
+from diffusers.models import ModelMixin
+
+from hyimage.models.hunyuan.modules.posemb_layers import get_nd_rotary_pos_embed
+from hyimage.models.hunyuan.modules.flash_attn_no_pad import get_cu_seqlens
+
+from .activation_layers import get_activation_layer
+from .embed_layers import PatchEmbed, PatchEmbed2D, TextProjection, TimestepEmbedder
+from .mlp_layers import FinalLayer
+from .models import MMDoubleStreamBlock, MMSingleStreamBlock
+from .token_refiner import SingleTokenRefiner
+
+from hyimage.models.text_encoder.byT5 import ByT5Mapper
+
+
+def convert_hunyuan_dict_for_tensor_parallel(state_dict):
+    """
+    Convert a Hunyuan model state dict to be compatible with tensor parallel architectures.
+
+    Args:
+        state_dict: Original state dict
+
+    Returns:
+        new_dict: Converted state dict
+    """
+    new_dict = {}
+    for k, w in state_dict.items():
+        if k.startswith("double_blocks") and "attn_qkv.weight" in k:
+            hidden_size = w.shape[1]
+            k1 = k.replace("attn_qkv.weight", "attn_q.weight")
+            w1 = w[:hidden_size, :]
+            new_dict[k1] = w1
+            k2 = k.replace("attn_qkv.weight", "attn_k.weight")
+            w2 = w[hidden_size : 2 * hidden_size, :]
+            new_dict[k2] = w2
+            k3 = k.replace("attn_qkv.weight", "attn_v.weight")
+            w3 = w[-hidden_size:, :]
+            new_dict[k3] = w3
+        elif k.startswith("double_blocks") and "attn_qkv.bias" in k:
+            hidden_size = w.shape[0] // 3
+            k1 = k.replace("attn_qkv.bias", "attn_q.bias")
+            w1 = w[:hidden_size]
+            new_dict[k1] = w1
+            k2 = k.replace("attn_qkv.bias", "attn_k.bias")
+            w2 = w[hidden_size : 2 * hidden_size]
+            new_dict[k2] = w2
+            k3 = k.replace("attn_qkv.bias", "attn_v.bias")
+            w3 = w[-hidden_size:]
+            new_dict[k3] = w3
+        elif k.startswith("single_blocks") and "linear1" in k:
+            hidden_size = state_dict[k.replace("linear1", "linear2")].shape[0]
+            k1 = k.replace("linear1", "linear1_q")
+            w1 = w[:hidden_size]
+            new_dict[k1] = w1
+            k2 = k.replace("linear1", "linear1_k")
+            w2 = w[hidden_size : 2 * hidden_size]
+            new_dict[k2] = w2
+            k3 = k.replace("linear1", "linear1_v")
+            w3 = w[2 * hidden_size : 3 * hidden_size]
+            new_dict[k3] = w3
+            k4 = k.replace("linear1", "linear1_mlp")
+            w4 = w[3 * hidden_size :]
+            new_dict[k4] = w4
+        elif k.startswith("single_blocks") and "linear2" in k:
+            k1 = k.replace("linear2", "linear2.fc")
+            new_dict[k1] = w
+        else:
+            new_dict[k] = w
+    return new_dict
+
+
+def load_hunyuan_dit_state_dict(model, dit_model_name_or_path, strict=True, assign=False):
+    """
+    Load a state dict for a Hunyuan model, handling both safetensors and torch formats.
+
+    Args:
+        model: Model instance to load weights into
+        dit_model_name_or_path: Path to the checkpoint file
+        strict: Whether to strictly enforce that the keys in state_dict match the model's keys
+        assign: If True, assign weights directly without copying
+
+    Returns:
+        model: The model with loaded weights
+    """
+    from safetensors.torch import load_file as safetensors_load_file
+
+    if not os.path.exists(dit_model_name_or_path):
+        return
+
+    if dit_model_name_or_path.endswith(".safetensors"):
+        state_dict = safetensors_load_file(dit_model_name_or_path)
+    else:
+        state_dict = torch.load(
+            dit_model_name_or_path,
+            map_location="cpu",
+            weights_only=True,
+        )
+    try:
+        state_dict = convert_hunyuan_dict_for_tensor_parallel(state_dict)
+    except Exception:
+        pass
+    model.load_state_dict(state_dict, strict=strict, assign=assign)
+    return model
+
+
+class HYImageDiffusionTransformer(ModelMixin, ConfigMixin):
+
+    @register_to_config
+    def __init__(
+        self,
+        patch_size: list = [1, 2, 2],
+        in_channels: int = 4,
+        out_channels: int = None,
+        hidden_size: int = 3072,
+        heads_num: int = 24,
+        mlp_width_ratio: float = 4.0,
+        mlp_act_type: str = "gelu_tanh",
+        mm_double_blocks_depth: int = 20,
+        mm_single_blocks_depth: int = 40,
+        rope_dim_list: List[int] = [16, 56, 56],
+        qkv_bias: bool = True,
+        qk_norm: bool = True,
+        qk_norm_type: str = "rms",
+        guidance_embed: bool = False,
+        text_projection: str = "single_refiner",
+        use_attention_mask: bool = True,
+        dtype: Optional[torch.dtype] = None,
+        device: Optional[torch.device] = None,
+        text_states_dim: int = 4096,
+        rope_theta: int = 256,
+        glyph_byT5_v2: bool = False,
+        use_meanflow: bool = False,
+    ):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+
+        self.patch_size = patch_size
+        self.in_channels = in_channels
+        self.out_channels = in_channels if out_channels is None else out_channels
+        self.unpatchify_channels = self.out_channels
+        self.guidance_embed = guidance_embed
+        self.rope_dim_list = rope_dim_list
+        self.rope_theta = rope_theta
+        self.use_attention_mask = use_attention_mask
+        self.text_projection = text_projection
+
+        if hidden_size % heads_num != 0:
+            raise ValueError(f"Hidden size {hidden_size} must be divisible by heads_num {heads_num}")
+        pe_dim = hidden_size // heads_num
+        if sum(rope_dim_list) != pe_dim:
+            raise ValueError(f"Got {rope_dim_list} but expected positional dim {pe_dim}")
+        self.hidden_size = hidden_size
+        self.heads_num = heads_num
+
+        self.glyph_byT5_v2 = glyph_byT5_v2
+        if self.glyph_byT5_v2:
+            self.byt5_in = ByT5Mapper(
+                in_dim=1472,
+                out_dim=2048,
+                hidden_dim=2048,
+                out_dim1=hidden_size,
+                use_residual=False
+            )
+
+        # Image projection
+        if len(self.patch_size) == 3:
+            self.img_in = PatchEmbed(self.patch_size, self.in_channels, self.hidden_size, **factory_kwargs)
+        elif len(self.patch_size) == 2:
+            self.img_in = PatchEmbed2D(self.patch_size, self.in_channels, self.hidden_size, **factory_kwargs)
+        else:
+            raise ValueError(f"Unsupported patch_size: {self.patch_size}")
+
+        # Text projection
+        if self.text_projection == "linear":
+            self.txt_in = TextProjection(
+                text_states_dim,
+                self.hidden_size,
+                get_activation_layer("silu"),
+                **factory_kwargs,
+            )
+        elif self.text_projection == "single_refiner":
+            self.txt_in = SingleTokenRefiner(
+                text_states_dim,
+                hidden_size,
+                heads_num,
+                depth=2,
+                **factory_kwargs,
+            )
+        else:
+            raise NotImplementedError(f"Unsupported text_projection: {self.text_projection}")
+
+        # Time modulation
+        self.time_in = TimestepEmbedder(self.hidden_size, get_activation_layer("silu"), **factory_kwargs)
+
+        # MeanFlow support: only create time_r_in when needed
+        self.time_r_in = (
+            TimestepEmbedder(self.hidden_size, get_activation_layer("silu"), **factory_kwargs)
+            if use_meanflow
+            else None
+        )
+        self.use_meanflow = use_meanflow
+
+        # Guidance modulation
+        self.guidance_in = (
+            TimestepEmbedder(self.hidden_size, get_activation_layer("silu"), **factory_kwargs)
+            if guidance_embed
+            else None
+        )
+
+        # Double blocks
+        self.double_blocks = nn.ModuleList(
+            [
+                MMDoubleStreamBlock(
+                    self.hidden_size,
+                    self.heads_num,
+                    mlp_width_ratio=mlp_width_ratio,
+                    mlp_act_type=mlp_act_type,
+                    qk_norm=qk_norm,
+                    qk_norm_type=qk_norm_type,
+                    qkv_bias=qkv_bias,
+                    **factory_kwargs,
+                )
+                for _ in range(mm_double_blocks_depth)
+            ]
+        )
+
+        # Single blocks
+        self.single_blocks = nn.ModuleList(
+            [
+                MMSingleStreamBlock(
+                    self.hidden_size,
+                    self.heads_num,
+                    mlp_width_ratio=mlp_width_ratio,
+                    mlp_act_type=mlp_act_type,
+                    qk_norm=qk_norm,
+                    qk_norm_type=qk_norm_type,
+                    **factory_kwargs,
+                )
+                for _ in range(mm_single_blocks_depth)
+            ]
+        )
+
+        self.final_layer = FinalLayer(
+            self.hidden_size,
+            self.patch_size,
+            self.out_channels,
+            get_activation_layer("silu"),
+            **factory_kwargs,
+        )
+
+    def enable_deterministic(self):
+        """Enable deterministic mode for all transformer blocks."""
+        for block in self.double_blocks:
+            block.enable_deterministic()
+        for block in self.single_blocks:
+            block.enable_deterministic()
+
+    def disable_deterministic(self):
+        """Disable deterministic mode for all transformer blocks."""
+        for block in self.double_blocks:
+            block.disable_deterministic()
+        for block in self.single_blocks:
+            block.disable_deterministic()
+
+    def get_rotary_pos_embed(self, rope_sizes):
+        """
+        Get rotary position embeddings for the given sizes.
+
+        Args:
+            rope_sizes: Sizes for each rotary dimension.
+
+        Returns:
+            freqs_cos, freqs_sin: Cosine and sine frequencies for rotary embedding.
+        """
+        target_ndim = 3
+        head_dim = self.hidden_size // self.heads_num
+        rope_dim_list = self.rope_dim_list
+        if rope_dim_list is None:
+            rope_dim_list = [head_dim // target_ndim for _ in range(target_ndim)]
+        assert sum(rope_dim_list) == head_dim, "sum(rope_dim_list) should equal to head_dim of attention layer"
+        freqs_cos, freqs_sin = get_nd_rotary_pos_embed(
+            rope_dim_list,
+            rope_sizes,
+            theta=self.rope_theta,
+            use_real=True,
+            theta_rescale_factor=1,
+        )
+        return freqs_cos, freqs_sin
+
+    def reorder_txt_token(self, byt5_txt, txt, byt5_text_mask, text_mask):
+        """
+        Reorder text tokens for ByT5 integration.
+
+        Args:
+            byt5_txt: ByT5 text embeddings.
+            txt: Text embeddings.
+            byt5_text_mask: Mask for ByT5 tokens.
+            text_mask: Mask for text tokens.
+
+        Returns:
+            reorder_txt: Reordered text embeddings.
+            reorder_mask: Reordered mask.
+        """
+        reorder_txt = []
+        reorder_mask = []
+
+        for i in range(text_mask.shape[0]):
+            byt5_text_mask_i = byt5_text_mask[i].bool()
+            text_mask_i = text_mask[i].bool()
+            byt5_txt_i = byt5_txt[i]
+            txt_i = txt[i]
+            reorder_txt_i = torch.cat([
+                byt5_txt_i[byt5_text_mask_i],
+                txt_i[text_mask_i],
+                byt5_txt_i[~byt5_text_mask_i],
+                txt_i[~text_mask_i]
+            ], dim=0)
+
+            reorder_mask_i = torch.cat([
+                byt5_text_mask_i[byt5_text_mask_i],
+                text_mask_i[text_mask_i],
+                byt5_text_mask_i[~byt5_text_mask_i],
+                text_mask_i[~text_mask_i]
+            ], dim=0)
+
+            reorder_txt.append(reorder_txt_i)
+            reorder_mask.append(reorder_mask_i)
+
+        reorder_txt = torch.stack(reorder_txt)
+        reorder_mask = torch.stack(reorder_mask).to(dtype=torch.int64)
+
+        return reorder_txt, reorder_mask
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        timestep: torch.LongTensor,
+        text_states: torch.Tensor,
+        encoder_attention_mask: torch.Tensor,
+        output_features: bool = False,
+        output_features_stride: int = 8,
+        freqs_cos: Optional[torch.Tensor] = None,
+        freqs_sin: Optional[torch.Tensor] = None,
+        return_dict: bool = False,
+        guidance=None,
+        extra_kwargs=None,
+        *,
+        timesteps_r: Optional[torch.LongTensor] = None,
+    ) -> Union[torch.Tensor, Dict[str, torch.Tensor]]:
+        """
+        Forward pass for the transformer.
+
+        Parameters
+        ----------
+        hidden_states : torch.Tensor
+            Input image tensor.
+        timestep : torch.LongTensor
+            Timestep tensor.
+        text_states : torch.Tensor
+            Text embeddings.
+        encoder_attention_mask : torch.Tensor
+            Attention mask for text.
+        output_features : bool, optional
+            Whether to output intermediate features.
+        output_features_stride : int, optional
+            Stride for outputting features.
+        freqs_cos, freqs_sin : torch.Tensor, optional
+            Precomputed rotary embeddings.
+        return_dict : bool, optional
+            Not supported.
+        guidance : torch.Tensor, optional
+            Guidance vector for distillation.
+        extra_kwargs : dict, optional
+            Extra arguments for ByT5.
+        timesteps_r : torch.LongTensor, optional
+            Additional timestep for MeanFlow.
+
+        Returns
+        -------
+        tuple
+            (img, features_list, shape)
+        """
+        if guidance is None:
+            guidance = torch.tensor([6016.0], device=hidden_states.device, dtype=torch.bfloat16)
+        img = x = hidden_states
+        text_mask = encoder_attention_mask
+        t = timestep
+        txt = text_states
+        input_shape = x.shape
+
+        # Calculate spatial dimensions and get rotary embeddings
+        if len(input_shape) == 5:
+            _, _, ot, oh, ow = x.shape
+            tt, th, tw = (
+                ot // self.patch_size[0],
+                oh // self.patch_size[1],
+                ow // self.patch_size[2],
+            )
+            if freqs_cos is None or freqs_sin is None:
+                freqs_cos, freqs_sin = self.get_rotary_pos_embed((tt, th, tw))
+        elif len(input_shape) == 4:
+            _, _, oh, ow = x.shape
+            th, tw = (
+                oh // self.patch_size[0],
+                ow // self.patch_size[1],
+            )
+            if freqs_cos is None or freqs_sin is None:
+                assert freqs_cos is None and freqs_sin is None, "freqs_cos and freqs_sin must be both None or both not None"
+                freqs_cos, freqs_sin = self.get_rotary_pos_embed((th, tw))
+        else:
+            raise ValueError(f"Unsupported hidden_states shape: {x.shape}")
+
+        img = self.img_in(img)
+
+        # Prepare modulation vectors
+        vec = self.time_in(t)
+
+        # MeanFlow support: merge timestep and timestep_r if available
+        if self.use_meanflow:
+            assert self.time_r_in is not None, "use_meanflow is True but time_r_in is None"
+        if timesteps_r is not None:
+            assert self.time_r_in is not None, "timesteps_r is not None but time_r_in is None"
+            vec_r = self.time_r_in(timesteps_r)
+            vec = (vec + vec_r) / 2
+
+        # Guidance modulation
+        if self.guidance_embed:
+            if guidance is None:
+                raise ValueError("Didn't get guidance strength for guidance distilled model.")
+            vec = vec + self.guidance_in(guidance)
+
+        # Embed image and text
+        if self.text_projection == "linear":
+            txt = self.txt_in(txt)
+        elif self.text_projection == "single_refiner":
+            txt = self.txt_in(txt, t, text_mask if self.use_attention_mask else None)
+        else:
+            raise NotImplementedError(f"Unsupported text_projection: {self.text_projection}")
+
+        if self.glyph_byT5_v2:
+            byt5_text_states = extra_kwargs["byt5_text_states"]
+            byt5_text_mask = extra_kwargs["byt5_text_mask"]
+            byt5_txt = self.byt5_in(byt5_text_states)
+            txt, text_mask = self.reorder_txt_token(byt5_txt, txt, byt5_text_mask, text_mask)
+
+        txt_seq_len = txt.shape[1]
+        img_seq_len = img.shape[1]
+
+        # Calculate cu_seqlens and max_s for flash attention
+        cu_seqlens, max_s = get_cu_seqlens(text_mask, img_seq_len)
+
+        freqs_cis = (freqs_cos, freqs_sin) if freqs_cos is not None else None
+
+        # Pass through double stream blocks
+        for block in self.double_blocks:
+            double_block_args = [img, txt, vec, freqs_cis, text_mask, cu_seqlens, max_s]
+            img, txt = block(*double_block_args)
+
+        # Merge txt and img to pass through single stream blocks
+        x = torch.cat((img, txt), 1)
+        features_list = [] if output_features else None
+
+        if len(self.single_blocks) > 0:
+            for index, block in enumerate(self.single_blocks):
+                single_block_args = [
+                    x,
+                    vec,
+                    txt_seq_len,
+                    (freqs_cos, freqs_sin),
+                    text_mask,
+                    cu_seqlens,
+                    max_s,
+                ]
+                x = block(*single_block_args)
+                if output_features and index % output_features_stride == 0:
+                    features_list.append(x[:, :img_seq_len, ...])
+
+        img = x[:, :img_seq_len, ...]
+
+        # Final layer
+        img = self.final_layer(img, vec)
+
+        # Unpatchify based on input shape
+        if len(input_shape) == 5:
+            img = self.unpatchify(img, tt, th, tw)
+            shape = (tt, th, tw)
+        elif len(input_shape) == 4:
+            img = self.unpatchify_2d(img, th, tw)
+            shape = (th, tw)
+        else:
+            raise ValueError(f"Unsupported input_shape: {input_shape}")
+
+        assert not return_dict, "return_dict is not supported."
+
+        if output_features:
+            features_list = torch.stack(features_list, dim=0)
+        else:
+            features_list = None
+
+        return (img, features_list, shape)
+
+    def unpatchify(self, x, t, h, w):
+        """
+        Unpatchify 3D tensor.
+
+        Parameters
+        ----------
+        x: torch.Tensor
+            Input tensor of shape (N, T, patch_size**2 * C)
+        t, h, w: int
+            Temporal and spatial dimensions
+
+        Returns
+        -------
+        torch.Tensor
+            Unpatchified tensor of shape (N, C, T*pt, H*ph, W*pw)
+        """
+        c = self.unpatchify_channels
+        pt, ph, pw = self.patch_size
+        assert t * h * w == x.shape[1]
+
+        x = x.reshape(shape=(x.shape[0], t, h, w, c, pt, ph, pw))
+        x = torch.einsum("nthwcopq->nctohpwq", x)
+        imgs = x.reshape(shape=(x.shape[0], c, t * pt, h * ph, w * pw))
+
+        return imgs
+
+    def unpatchify_2d(self, x, h, w):
+        """
+        Unpatchify 2D tensor.
+        
+        Parameters
+        ----------
+        x: torch.Tensor
+            Input tensor of shape (N, T, patch_size**2 * C)
+        h, w: int
+            Spatial dimensions
+
+        Returns
+        -------
+        torch.Tensor
+            Unpatchified tensor of shape (N, C, H*ph, W*pw)
+        """
+        c = self.unpatchify_channels
+        ph, pw = self.patch_size
+        assert h * w == x.shape[1]
+
+        x = x.reshape(shape=(x.shape[0], h, w, c, ph, pw))
+        x = torch.einsum('nhwcpq->nchpwq', x)
+        imgs = x.reshape(shape=(x.shape[0], c, h * ph, w * pw))
+        return imgs

hyimage/models/hunyuan/modules/mlp_layers.py

@@ -0,0 +1,121 @@
+# Modified from timm library:
+# https://github.com/huggingface/pytorch-image-models/blob/648aaa41233ba83eb38faf5ba9d415d574823241/timm/layers/mlp.py#L13
+
+from functools import partial
+
+import torch
+import torch.nn as nn
+
+from ..utils.helpers import to_2tuple
+from .modulate_layers import modulate
+
+
+class MLP(nn.Module):
+    """MLP as used in Vision Transformer, MLP-Mixer and related networks"""
+
+    def __init__(
+        self,
+        in_channels,
+        hidden_channels=None,
+        out_features=None,
+        act_layer=nn.GELU,
+        norm_layer=None,
+        bias=True,
+        drop=0.0,
+        use_conv=False,
+        device=None,
+        dtype=None,
+    ):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+        out_features = out_features or in_channels
+        hidden_channels = hidden_channels or in_channels
+        bias = to_2tuple(bias)
+        drop_probs = to_2tuple(drop)
+        linear_layer = partial(nn.Conv2d, kernel_size=1) if use_conv else nn.Linear
+
+        self.fc1 = linear_layer(in_channels, hidden_channels, bias=bias[0], **factory_kwargs)
+        self.act = act_layer()
+        self.drop1 = nn.Dropout(drop_probs[0])
+        self.norm = norm_layer(hidden_channels, **factory_kwargs) if norm_layer is not None else nn.Identity()
+        self.fc2 = linear_layer(hidden_channels, out_features, bias=bias[1], **factory_kwargs)
+        self.drop2 = nn.Dropout(drop_probs[1])
+
+    def forward(self, x):
+        x = self.fc1(x)
+        x = self.act(x)
+        x = self.drop1(x)
+        x = self.norm(x)
+        x = self.fc2(x)
+        x = self.drop2(x)
+        return x
+
+
+class LinearWarpforSingle(nn.Module):
+    def __init__(self, in_dim: int, out_dim: int, bias=False, device=None, dtype=None):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+        self.fc = nn.Linear(in_dim, out_dim, bias=bias, **factory_kwargs)
+
+    def forward(self, x, y):
+        input = torch.cat([x.contiguous(), y.contiguous()], dim=2).contiguous()
+        return self.fc(input)
+
+
+#
+class MLPEmbedder(nn.Module):
+    """copied from https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/layers.py"""
+
+    def __init__(self, in_dim: int, hidden_dim: int, device=None, dtype=None):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+        self.in_layer = nn.Linear(in_dim, hidden_dim, bias=True, **factory_kwargs)
+        self.silu = nn.SiLU()
+        self.out_layer = nn.Linear(hidden_dim, hidden_dim, bias=True, **factory_kwargs)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.out_layer(self.silu(self.in_layer(x)))
+
+
+class FinalLayer(nn.Module):
+    """The final layer of DiT."""
+
+    def __init__(self, hidden_size, patch_size, out_channels, act_layer, device=None, dtype=None):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+
+        # Just use LayerNorm for the final layer
+        self.norm_final = nn.LayerNorm(hidden_size, elementwise_affine=False, eps=1e-6, **factory_kwargs)
+        if isinstance(patch_size, int):
+            self.linear = nn.Linear(
+                hidden_size,
+                patch_size * patch_size * out_channels,
+                bias=True,
+                **factory_kwargs,
+            )
+        else:
+            out_size = (
+                patch_size[0] * patch_size[1] * patch_size[2] if len(patch_size) == 3 else patch_size[0] * patch_size[1]
+            ) * out_channels
+            self.linear = nn.Linear(
+                hidden_size,
+                out_size,
+                bias=True,
+            )
+        nn.init.zeros_(self.linear.weight)
+        nn.init.zeros_(self.linear.bias)
+
+        # Here we don't distinguish between the modulate types. Just use the simple one.
+        self.adaLN_modulation = nn.Sequential(
+            act_layer(),
+            nn.Linear(hidden_size, 2 * hidden_size, bias=True, **factory_kwargs),
+        )
+        # Zero-initialize the modulation
+        nn.init.zeros_(self.adaLN_modulation[1].weight)
+        nn.init.zeros_(self.adaLN_modulation[1].bias)
+
+    def forward(self, x, c):
+        shift, scale = self.adaLN_modulation(c).chunk(2, dim=1)
+        x = modulate(self.norm_final(x), shift=shift, scale=scale)
+        x = self.linear(x)
+        return x

hyimage/models/hunyuan/modules/models.py

@@ -0,0 +1,367 @@
+from typing import Optional, Tuple
+
+import torch
+import torch.nn as nn
+
+from einops import rearrange
+
+from hyimage.models.hunyuan.modules.flash_attn_no_pad import flash_attn_no_pad
+
+from .activation_layers import get_activation_layer
+from .mlp_layers import MLP, LinearWarpforSingle
+from .modulate_layers import ModulateDiT, apply_gate, modulate
+from .norm_layers import get_norm_layer
+from .posemb_layers import apply_rotary_emb
+
+
+@torch.compiler.disable
+def attention(
+    q,
+    k,
+    v,
+    attn_mode="flash",
+    text_mask=None,
+):
+    """Multi-modal attention function that processes image and text sequences."""
+    query, encoder_query = q
+    key, encoder_key = k
+    value, encoder_value = v
+
+    assert attn_mode == "flash"  # Only flash attention is implemented for now
+    sequence_length = query.size(1)
+    encoder_sequence_length = encoder_query.size(1)
+
+    query = torch.cat([query, encoder_query], dim=1)
+    key = torch.cat([key, encoder_key], dim=1)
+    value = torch.cat([value, encoder_value], dim=1)
+
+    # Stack query, key, value: B, S, 3, H, D
+    qkv = torch.stack([query, key, value], dim=2)
+
+    attn_mask = torch.nn.functional.pad(text_mask, (sequence_length, 0), value=True)
+    hidden_states = flash_attn_no_pad(qkv, attn_mask, causal=False, dropout_p=0.0, softmax_scale=None)
+
+    hidden_states, encoder_hidden_states = hidden_states.split_with_sizes(
+        (sequence_length, encoder_sequence_length), dim=1
+    )
+
+    hidden_states = hidden_states.to(query.dtype)
+    encoder_hidden_states = encoder_hidden_states.to(query.dtype)
+
+    attn = torch.cat([hidden_states, encoder_hidden_states], dim=1)
+
+    b, s, a, d = attn.shape
+    attn = attn.reshape(b, s, -1)
+
+    return attn
+
+
+class MMDoubleStreamBlock(nn.Module):
+    """
+    A multimodal DiT block with separate modulation for text and image/video.
+    """
+
+    def __init__(
+        self,
+        hidden_size: int,
+        heads_num: int,
+        mlp_width_ratio: float,
+        mlp_act_type: str = "gelu_tanh",
+        qk_norm: bool = True,
+        qk_norm_type: str = "rms",
+        qkv_bias: bool = False,
+        dtype: Optional[torch.dtype] = None,
+        device: Optional[torch.device] = None,
+    ):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+
+        self.deterministic = False
+        self.heads_num = heads_num
+        head_dim = hidden_size // heads_num
+        mlp_hidden_dim = int(hidden_size * mlp_width_ratio)
+
+        # Image stream components
+        self.img_mod = ModulateDiT(
+            hidden_size,
+            factor=6,
+            act_layer=get_activation_layer("silu"),
+            **factory_kwargs,
+        )
+        self.img_norm1 = nn.LayerNorm(hidden_size, elementwise_affine=False, eps=1e-6, **factory_kwargs)
+
+        self.img_attn_q = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+        self.img_attn_k = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+        self.img_attn_v = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+
+        qk_norm_layer = get_norm_layer(qk_norm_type)
+        self.img_attn_q_norm = (
+            qk_norm_layer(head_dim, elementwise_affine=True, eps=1e-6, **factory_kwargs) if qk_norm else nn.Identity()
+        )
+        self.img_attn_k_norm = (
+            qk_norm_layer(head_dim, elementwise_affine=True, eps=1e-6, **factory_kwargs) if qk_norm else nn.Identity()
+        )
+        self.img_attn_proj = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+
+        self.img_norm2 = nn.LayerNorm(hidden_size, elementwise_affine=False, eps=1e-6, **factory_kwargs)
+        self.img_mlp = MLP(
+            hidden_size,
+            mlp_hidden_dim,
+            act_layer=get_activation_layer(mlp_act_type),
+            bias=True,
+            **factory_kwargs,
+        )
+
+        # Text stream components
+        self.txt_mod = ModulateDiT(
+            hidden_size,
+            factor=6,
+            act_layer=get_activation_layer("silu"),
+            **factory_kwargs,
+        )
+        self.txt_norm1 = nn.LayerNorm(hidden_size, elementwise_affine=False, eps=1e-6, **factory_kwargs)
+
+        self.txt_attn_q = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+        self.txt_attn_k = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+        self.txt_attn_v = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+        self.txt_attn_q_norm = (
+            qk_norm_layer(head_dim, elementwise_affine=True, eps=1e-6, **factory_kwargs) if qk_norm else nn.Identity()
+        )
+        self.txt_attn_k_norm = (
+            qk_norm_layer(head_dim, elementwise_affine=True, eps=1e-6, **factory_kwargs) if qk_norm else nn.Identity()
+        )
+        self.txt_attn_proj = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+
+        self.txt_norm2 = nn.LayerNorm(hidden_size, elementwise_affine=False, eps=1e-6, **factory_kwargs)
+        self.txt_mlp = MLP(
+            hidden_size,
+            mlp_hidden_dim,
+            act_layer=get_activation_layer(mlp_act_type),
+            bias=True,
+            **factory_kwargs,
+        )
+        self.core_attn = attention
+
+    def enable_deterministic(self):
+        self.deterministic = True
+
+    def disable_deterministic(self):
+        self.deterministic = False
+
+    def forward(
+        self,
+        img: torch.Tensor,
+        txt: torch.Tensor,
+        vec: torch.Tensor,
+        freqs_cis: tuple = None,
+        text_mask: torch.Tensor = None,
+        cu_seqlens=None,
+        max_s=None,
+    ) -> Tuple[torch.Tensor, torch.Tensor]:
+        # Extract modulation parameters for image and text streams
+        (
+            img_mod1_shift,
+            img_mod1_scale,
+            img_mod1_gate,
+            img_mod2_shift,
+            img_mod2_scale,
+            img_mod2_gate,
+        ) = self.img_mod(vec).chunk(6, dim=-1)
+        (
+            txt_mod1_shift,
+            txt_mod1_scale,
+            txt_mod1_gate,
+            txt_mod2_shift,
+            txt_mod2_scale,
+            txt_mod2_gate,
+        ) = self.txt_mod(vec).chunk(6, dim=-1)
+
+        # Process image stream for attention
+        img_modulated = self.img_norm1(img)
+        img_modulated = modulate(img_modulated, shift=img_mod1_shift, scale=img_mod1_scale)
+
+        img_q = self.img_attn_q(img_modulated)
+        img_k = self.img_attn_k(img_modulated)
+        img_v = self.img_attn_v(img_modulated)
+
+        img_q = rearrange(img_q, "B L (H D) -> B L H D", H=self.heads_num)
+        img_k = rearrange(img_k, "B L (H D) -> B L H D", H=self.heads_num)
+        img_v = rearrange(img_v, "B L (H D) -> B L H D", H=self.heads_num)
+
+        # Apply QK-Norm if enabled
+        img_q = self.img_attn_q_norm(img_q).to(img_v)
+        img_k = self.img_attn_k_norm(img_k).to(img_v)
+
+        # Apply RoPE if provided
+        if freqs_cis is not None:
+            img_qq, img_kk = apply_rotary_emb(img_q, img_k, freqs_cis, head_first=False)
+            assert (
+                img_qq.shape == img_q.shape and img_kk.shape == img_k.shape
+            ), f"img_kk: {img_qq.shape}, img_q: {img_q.shape}, img_kk: {img_kk.shape}, img_k: {img_k.shape}"
+            img_q, img_k = img_qq, img_kk
+
+        # Process text stream for attention
+        txt_modulated = self.txt_norm1(txt)
+        txt_modulated = modulate(txt_modulated, shift=txt_mod1_shift, scale=txt_mod1_scale)
+
+        txt_q = self.txt_attn_q(txt_modulated)
+        txt_k = self.txt_attn_k(txt_modulated)
+        txt_v = self.txt_attn_v(txt_modulated)
+
+        txt_q = rearrange(txt_q, "B L (H D) -> B L H D", H=self.heads_num)
+        txt_k = rearrange(txt_k, "B L (H D) -> B L H D", H=self.heads_num)
+        txt_v = rearrange(txt_v, "B L (H D) -> B L H D", H=self.heads_num)
+
+        # Apply QK-Norm if enabled
+        txt_q = self.txt_attn_q_norm(txt_q).to(txt_v)
+        txt_k = self.txt_attn_k_norm(txt_k).to(txt_v)
+
+        # Compute cross-modal attention
+        attn = self.core_attn(
+            (img_q, txt_q),
+            (img_k, txt_k),
+            (img_v, txt_v),
+            text_mask=text_mask,
+        )
+
+        # Split attention outputs for image and text streams
+        img_attn, txt_attn = (
+            attn[:, : img_q.shape[1]].contiguous(),
+            attn[:, img_q.shape[1] :].contiguous(),
+        )
+
+        # Apply attention projection and residual connection for image stream
+        img = img + apply_gate(self.img_attn_proj(img_attn), gate=img_mod1_gate)
+
+        # Apply MLP and residual connection for image stream
+        img = img + apply_gate(
+            self.img_mlp(modulate(self.img_norm2(img), shift=img_mod2_shift, scale=img_mod2_scale)),
+            gate=img_mod2_gate,
+        )
+
+        # Apply attention projection and residual connection for text stream
+        txt = txt + apply_gate(self.txt_attn_proj(txt_attn), gate=txt_mod1_gate)
+
+        # Apply MLP and residual connection for text stream
+        txt = txt + apply_gate(
+            self.txt_mlp(modulate(self.txt_norm2(txt), shift=txt_mod2_shift, scale=txt_mod2_scale)),
+            gate=txt_mod2_gate,
+        )
+
+        return img, txt
+
+
+class MMSingleStreamBlock(nn.Module):
+    """
+    A DiT block with parallel linear layers for multimodal processing.
+    """
+
+    def __init__(
+        self,
+        hidden_size: int,
+        heads_num: int,
+        mlp_width_ratio: float = 4.0,
+        mlp_act_type: str = "gelu_tanh",
+        qk_norm: bool = True,
+        qk_norm_type: str = "rms",
+        qk_scale: float = None,
+        dtype: Optional[torch.dtype] = None,
+        device: Optional[torch.device] = None,
+    ):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+
+        self.deterministic = False
+        self.hidden_size = hidden_size
+        self.heads_num = heads_num
+        head_dim = hidden_size // heads_num
+        mlp_hidden_dim = int(hidden_size * mlp_width_ratio)
+        self.mlp_hidden_dim = mlp_hidden_dim
+        self.scale = qk_scale or head_dim**-0.5
+
+        # Separate linear layers for Q, K, V, and MLP input
+        self.linear1_q = nn.Linear(hidden_size, hidden_size, **factory_kwargs)
+        self.linear1_k = nn.Linear(hidden_size, hidden_size, **factory_kwargs)
+        self.linear1_v = nn.Linear(hidden_size, hidden_size, **factory_kwargs)
+        self.linear1_mlp = nn.Linear(hidden_size, mlp_hidden_dim, **factory_kwargs)
+
+        # Output projection layer
+        self.linear2 = LinearWarpforSingle(hidden_size + mlp_hidden_dim, hidden_size, bias=True, **factory_kwargs)
+
+        # QK normalization layers
+        qk_norm_layer = get_norm_layer(qk_norm_type)
+        self.q_norm = (
+            qk_norm_layer(head_dim, elementwise_affine=True, eps=1e-6, **factory_kwargs) if qk_norm else nn.Identity()
+        )
+        self.k_norm = (
+            qk_norm_layer(head_dim, elementwise_affine=True, eps=1e-6, **factory_kwargs) if qk_norm else nn.Identity()
+        )
+
+        self.pre_norm = nn.LayerNorm(hidden_size, elementwise_affine=False, eps=1e-6, **factory_kwargs)
+
+        self.mlp_act = get_activation_layer(mlp_act_type)()
+        self.modulation = ModulateDiT(
+            hidden_size,
+            factor=3,
+            act_layer=get_activation_layer("silu"),
+            **factory_kwargs,
+        )
+        self.core_attn = attention
+
+    def enable_deterministic(self):
+        self.deterministic = True
+
+    def disable_deterministic(self):
+        self.deterministic = False
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        vec: torch.Tensor,
+        txt_len: int,
+        freqs_cis: Tuple[torch.Tensor, torch.Tensor] = None,
+        text_mask: torch.Tensor = None,
+        cu_seqlens=None,
+        max_s=None,
+    ) -> torch.Tensor:
+        # Extract modulation parameters
+        mod_shift, mod_scale, mod_gate = self.modulation(vec).chunk(3, dim=-1)
+        x_mod = modulate(self.pre_norm(x), shift=mod_shift, scale=mod_scale)
+
+        # Compute Q, K, V, and MLP input
+        q = self.linear1_q(x_mod)
+        k = self.linear1_k(x_mod)
+        v = self.linear1_v(x_mod)
+
+        q = rearrange(q, "B L (H D) -> B L H D", H=self.heads_num)
+        k = rearrange(k, "B L (H D) -> B L H D", H=self.heads_num)
+        v = rearrange(v, "B L (H D) -> B L H D", H=self.heads_num)
+        mlp = self.linear1_mlp(x_mod)
+
+        # Apply QK-Norm if enabled
+        q = self.q_norm(q).to(v)
+        k = self.k_norm(k).to(v)
+
+        # Split into image and text sequences
+        img_q, txt_q = q[:, :-txt_len, :, :], q[:, -txt_len:, :, :]
+        img_k, txt_k = k[:, :-txt_len, :, :], k[:, -txt_len:, :, :]
+        img_v, txt_v = v[:, :-txt_len, :, :], v[:, -txt_len:, :, :]
+
+        # Apply RoPE to image sequence
+        img_qq, img_kk = apply_rotary_emb(img_q, img_k, freqs_cis, head_first=False)
+        assert (
+            img_qq.shape == img_q.shape and img_kk.shape == img_k.shape
+        ), f"img_kk: {img_qq.shape}, img_q: {img_q.shape}, img_kk: {img_kk.shape}, img_k: {img_k.shape}"
+        img_q, img_k = img_qq, img_kk
+
+        # Compute cross-modal attention
+        attn = self.core_attn(
+            (img_q, txt_q),
+            (img_k, txt_k),
+            (img_v, txt_v),
+            text_mask=text_mask,
+        )
+
+        # Combine attention output with MLP activation and apply final projection
+        output = self.linear2(attn, self.mlp_act(mlp))
+        return x + apply_gate(output, gate=mod_gate)

hyimage/models/hunyuan/modules/modulate_layers.py

@@ -0,0 +1,154 @@
+from typing import Callable
+
+import torch
+import torch.nn as nn
+
+
+class ModulateDiT(nn.Module):
+    """Modulation layer for DiT."""
+
+    def __init__(
+        self,
+        hidden_size: int,
+        factor: int,
+        act_layer: Callable,
+        dtype=None,
+        device=None,
+    ):
+        factory_kwargs = {"dtype": dtype, "device": device}
+        super().__init__()
+        self.act = act_layer()
+        self.linear = nn.Linear(hidden_size, factor * hidden_size, bias=True, **factory_kwargs)
+        # Zero-initialize the modulation
+        nn.init.zeros_(self.linear.weight)
+        nn.init.zeros_(self.linear.bias)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.linear(self.act(x))
+
+
+def modulate(x, shift=None, scale=None):
+    """modulate by shift and scale
+
+    Args:
+        x (torch.Tensor): input tensor.
+        shift (torch.Tensor, optional): shift tensor. Defaults to None.
+        scale (torch.Tensor, optional): scale tensor. Defaults to None.
+
+    Returns:
+        torch.Tensor: the output tensor after modulate.
+    """
+    if scale is None and shift is None:
+        return x
+    elif shift is None:
+        return x * (1 + scale.unsqueeze(1))
+    elif scale is None:
+        return x + shift.unsqueeze(1)
+    else:
+        return x * (1 + scale.unsqueeze(1)) + shift.unsqueeze(1)
+
+
+def apply_gate(x, gate=None, tanh=False):
+    """AI is creating summary for apply_gate
+
+    Args:
+        x (torch.Tensor): input tensor.
+        gate (torch.Tensor, optional): gate tensor. Defaults to None.
+        tanh (bool, optional): whether to use tanh function. Defaults to False.
+
+    Returns:
+        torch.Tensor: the output tensor after apply gate.
+    """
+    if gate is None:
+        return x
+    if tanh:
+        return x * gate.unsqueeze(1).tanh()
+    else:
+        return x * gate.unsqueeze(1)
+
+
+def ckpt_wrapper(module):
+    def ckpt_forward(*inputs):
+        outputs = module(*inputs)
+        return outputs
+
+    return ckpt_forward
+
+
+import torch
+import torch.nn as nn
+
+
+class RMSNorm(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        elementwise_affine=True,
+        eps: float = 1e-6,
+        device=None,
+        dtype=None,
+    ):
+        """
+        Initialize the RMSNorm normalization layer.
+
+        Args:
+            dim (int): The dimension of the input tensor.
+            eps (float, optional): A small value added to the denominator for numerical stability. Default is 1e-6.
+
+        Attributes:
+            eps (float): A small value added to the denominator for numerical stability.
+            weight (nn.Parameter): Learnable scaling parameter.
+
+        """
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+        self.eps = eps
+        if elementwise_affine:
+            self.weight = nn.Parameter(torch.ones(dim, **factory_kwargs))
+
+    def _norm(self, x):
+        """
+        Apply the RMSNorm normalization to the input tensor.
+
+        Args:
+            x (torch.Tensor): The input tensor.
+
+        Returns:
+            torch.Tensor: The normalized tensor.
+
+        """
+        return x * torch.rsqrt(x.pow(2).mean(-1, keepdim=True) + self.eps)
+
+    def forward(self, x):
+        """
+        Forward pass through the RMSNorm layer.
+
+        Args:
+            x (torch.Tensor): The input tensor.
+
+        Returns:
+            torch.Tensor: The output tensor after applying RMSNorm.
+
+        """
+        output = self._norm(x.float()).type_as(x)
+        if hasattr(self, "weight"):
+            output = output * self.weight
+        return output
+
+
+def get_norm_layer(norm_layer):
+    """
+    Get the normalization layer.
+
+    Args:
+        norm_layer (str): The type of normalization layer.
+
+    Returns:
+        norm_layer (nn.Module): The normalization layer.
+    """
+    if norm_layer == "layer":
+        return nn.LayerNorm
+    elif norm_layer == "rms":
+        return RMSNorm
+    else:
+        raise NotImplementedError(f"Norm layer {norm_layer} is not implemented")

hyimage/models/hunyuan/modules/norm_layers.py

@@ -0,0 +1,81 @@
+import torch
+import torch.nn as nn
+
+
+class RMSNorm(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        elementwise_affine=True,
+        eps: float = 1e-6,
+        device=None,
+        dtype=None,
+    ):
+        """
+        Initialize the RMSNorm normalization layer.
+
+        Args:
+            dim (int): The dimension of the input tensor.
+            eps (float, optional): A small value added to the denominator for numerical stability. Default is 1e-6.
+
+        Attributes:
+            eps (float): A small value added to the denominator for numerical stability.
+            weight (nn.Parameter): Learnable scaling parameter.
+
+        """
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+        self.eps = eps
+        if elementwise_affine:
+            self.weight = nn.Parameter(torch.ones(dim, **factory_kwargs))
+
+    def _norm(self, x):
+        """
+        Apply the RMSNorm normalization to the input tensor.
+
+        Args:
+            x (torch.Tensor): The input tensor.
+
+        Returns:
+            torch.Tensor: The normalized tensor.
+
+        """
+        return x * torch.rsqrt(x.pow(2).mean(-1, keepdim=True) + self.eps)
+
+    def reset_parameters(self):
+        if hasattr(self, "weight"):
+            self.weight.fill_(1)
+
+    def forward(self, x):
+        """
+        Forward pass through the RMSNorm layer.
+
+        Args:
+            x (torch.Tensor): The input tensor.
+
+        Returns:
+            torch.Tensor: The output tensor after applying RMSNorm.
+
+        """
+        output = self._norm(x.float()).type_as(x)
+        if hasattr(self, "weight"):
+            output = output * self.weight
+        return output
+
+
+def get_norm_layer(norm_layer):
+    """
+    Get the normalization layer.
+
+    Args:
+        norm_layer (str): The type of normalization layer.
+
+    Returns:
+        norm_layer (nn.Module): The normalization layer.
+    """
+    if norm_layer == "layer":
+        return nn.LayerNorm
+    elif norm_layer == "rms":
+        return RMSNorm
+    else:
+        raise NotImplementedError(f"Norm layer {norm_layer} is not implemented")

hyimage/models/hunyuan/modules/posemb_layers.py

@@ -0,0 +1,286 @@
+from typing import List, Tuple, Union
+
+import torch
+
+
+def _to_tuple(x, dim=2):
+    if isinstance(x, int):
+        return (x,) * dim
+    elif len(x) == dim:
+        return x
+    else:
+        raise ValueError(f"Expected length {dim} or int, but got {x}")
+
+
+def get_meshgrid_nd(start, *args, dim=2):
+    """
+    Get n-D meshgrid with start, stop and num.
+
+    Args:
+        start (int or tuple): If len(args) == 0, start is num; If len(args) == 1, start is start, args[0] is stop,
+            step is 1; If len(args) == 2, start is start, args[0] is stop, args[1] is num. For n-dim, start/stop/num
+            should be int or n-tuple. If n-tuple is provided, the meshgrid will be stacked following the dim order in
+            n-tuples.
+        *args: See above.
+        dim (int): Dimension of the meshgrid. Defaults to 2.
+
+    Returns:
+        grid (np.ndarray): [dim, ...]
+    """
+    if len(args) == 0:
+        # start is grid_size
+        num = _to_tuple(start, dim=dim)
+        start = (0,) * dim
+        stop = num
+    elif len(args) == 1:
+        # start is start, args[0] is stop, step is 1
+        start = _to_tuple(start, dim=dim)
+        stop = _to_tuple(args[0], dim=dim)
+        num = [stop[i] - start[i] for i in range(dim)]
+    elif len(args) == 2:
+        # start is start, args[0] is stop, args[1] is num
+        start = _to_tuple(start, dim=dim)  # Left-Top       eg: 12,0
+        stop = _to_tuple(args[0], dim=dim)  # Right-Bottom   eg: 20,32
+        num = _to_tuple(args[1], dim=dim)  # Target Size    eg: 32,124
+    else:
+        raise ValueError(f"len(args) should be 0, 1 or 2, but got {len(args)}")
+
+    # PyTorch implement of np.linspace(start[i], stop[i], num[i], endpoint=False)
+    axis_grid = []
+    for i in range(dim):
+        a, b, n = start[i], stop[i], num[i]
+        g = torch.linspace(a, b, n + 1, dtype=torch.float32)[:n]
+        axis_grid.append(g)
+    grid = torch.meshgrid(*axis_grid, indexing="ij")  # dim x [W, H, D]
+    grid = torch.stack(grid, dim=0)  # [dim, W, H, D]
+
+    return grid
+
+
+#################################################################################
+#                   Rotary Positional Embedding Functions                       #
+#################################################################################
+# https://github.com/meta-llama/llama/blob/be327c427cc5e89cc1d3ab3d3fec4484df771245/llama/model.py#L80
+
+
+def reshape_for_broadcast(
+    freqs_cis: Union[torch.Tensor, Tuple[torch.Tensor]],
+    x: torch.Tensor,
+    head_first=False,
+):
+    """
+    Reshape frequency tensor for broadcasting it with another tensor.
+
+    This function reshapes the frequency tensor to have the same shape as the target tensor 'x'
+    for the purpose of broadcasting the frequency tensor during element-wise operations.
+
+    Notes:
+        When using FlashMHAModified, head_first should be False.
+        When using Attention, head_first should be True.
+
+    Args:
+        freqs_cis (Union[torch.Tensor, Tuple[torch.Tensor]]): Frequency tensor to be reshaped.
+        x (torch.Tensor): Target tensor for broadcasting compatibility.
+        head_first (bool): head dimension first (except batch dim) or not.
+
+    Returns:
+        torch.Tensor: Reshaped frequency tensor.
+
+    Raises:
+        AssertionError: If the frequency tensor doesn't match the expected shape.
+        AssertionError: If the target tensor 'x' doesn't have the expected number of dimensions.
+    """
+    ndim = x.ndim
+    assert 0 <= 1 < ndim
+
+    if isinstance(freqs_cis, tuple):
+        # freqs_cis: (cos, sin) in real space
+        if head_first:
+            assert freqs_cis[0].shape == (
+                x.shape[-2],
+                x.shape[-1],
+            ), f"freqs_cis shape {freqs_cis[0].shape} does not match x shape {x.shape}"
+            shape = [d if i == ndim - 2 or i == ndim - 1 else 1 for i, d in enumerate(x.shape)]
+        else:
+            assert freqs_cis[0].shape == (
+                x.shape[1],
+                x.shape[-1],
+            ), f"freqs_cis shape {freqs_cis[0].shape} does not match x shape {x.shape}"
+            shape = [d if i == 1 or i == ndim - 1 else 1 for i, d in enumerate(x.shape)]
+        return freqs_cis[0].view(*shape), freqs_cis[1].view(*shape)
+    else:
+        # freqs_cis: values in complex space
+        if head_first:
+            assert freqs_cis.shape == (
+                x.shape[-2],
+                x.shape[-1],
+            ), f"freqs_cis shape {freqs_cis.shape} does not match x shape {x.shape}"
+            shape = [d if i == ndim - 2 or i == ndim - 1 else 1 for i, d in enumerate(x.shape)]
+        else:
+            assert freqs_cis.shape == (
+                x.shape[1],
+                x.shape[-1],
+            ), f"freqs_cis shape {freqs_cis.shape} does not match x shape {x.shape}"
+            shape = [d if i == 1 or i == ndim - 1 else 1 for i, d in enumerate(x.shape)]
+        return freqs_cis.view(*shape)
+
+
+def rotate_half(x):
+    x_real, x_imag = x.float().reshape(*x.shape[:-1], -1, 2).unbind(-1)  # [B, S, H, D//2]
+    return torch.stack([-x_imag, x_real], dim=-1).flatten(3)
+
+
+def apply_rotary_emb(
+    xq: torch.Tensor,
+    xk: torch.Tensor,
+    freqs_cis: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]],
+    head_first: bool = False,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """
+    Apply rotary embeddings to input tensors using the given frequency tensor.
+
+    This function applies rotary embeddings to the given query 'xq' and key 'xk' tensors using the provided
+    frequency tensor 'freqs_cis'. The input tensors are reshaped as complex numbers, and the frequency tensor
+    is reshaped for broadcasting compatibility. The resulting tensors contain rotary embeddings and are
+    returned as real tensors.
+
+    Args:
+        xq (torch.Tensor): Query tensor to apply rotary embeddings. [B, S, H, D]
+        xk (torch.Tensor): Key tensor to apply rotary embeddings.   [B, S, H, D]
+        freqs_cis (torch.Tensor or tuple): Precomputed frequency tensor for complex exponential.
+        head_first (bool): head dimension first (except batch dim) or not.
+
+    Returns:
+        Tuple[torch.Tensor, torch.Tensor]: Tuple of modified query tensor and key tensor with rotary embeddings.
+
+    """
+    xk_out = None
+    if isinstance(freqs_cis, tuple):
+        cos, sin = reshape_for_broadcast(freqs_cis, xq, head_first)  # [S, D]
+        cos, sin = cos.to(xq.device), sin.to(xq.device)
+        # real * cos - imag * sin
+        # imag * cos + real * sin
+        xq_out = (xq.float() * cos + rotate_half(xq.float()) * sin).type_as(xq)
+        xk_out = (xk.float() * cos + rotate_half(xk.float()) * sin).type_as(xk)
+    else:
+        # view_as_complex will pack [..., D/2, 2](real) to [..., D/2](complex)
+        xq_ = torch.view_as_complex(xq.float().reshape(*xq.shape[:-1], -1, 2))  # [B, S, H, D//2]
+        freqs_cis = reshape_for_broadcast(freqs_cis, xq_, head_first).to(xq.device)  # [S, D//2] --> [1, S, 1, D//2]
+        # (real, imag) * (cos, sin) = (real * cos - imag * sin, imag * cos + real * sin)
+        # view_as_real will expand [..., D/2](complex) to [..., D/2, 2](real)
+        xq_out = torch.view_as_real(xq_ * freqs_cis).flatten(3).type_as(xq)
+        xk_ = torch.view_as_complex(xk.float().reshape(*xk.shape[:-1], -1, 2))  # [B, S, H, D//2]
+        xk_out = torch.view_as_real(xk_ * freqs_cis).flatten(3).type_as(xk)
+
+    return xq_out, xk_out
+
+
+def get_nd_rotary_pos_embed(
+    rope_dim_list,
+    start,
+    *args,
+    theta=10000.0,
+    use_real=False,
+    theta_rescale_factor: Union[float, List[float]] = 1.0,
+    interpolation_factor: Union[float, List[float]] = 1.0,
+):
+    """
+    This is a n-d version of precompute_freqs_cis, which is a RoPE for tokens with n-d structure.
+
+    Args:
+        rope_dim_list (list of int): Dimension of each rope. len(rope_dim_list) should equal to n.
+            sum(rope_dim_list) should equal to head_dim of attention layer.
+        start (int | tuple of int | list of int): If len(args) == 0, start is num; If len(args) == 1, start is start,
+            args[0] is stop, step is 1; If len(args) == 2, start is start, args[0] is stop, args[1] is num.
+        *args: See above.
+        theta (float): Scaling factor for frequency computation. Defaults to 10000.0.
+        use_real (bool): If True, return real part and imaginary part separately. Otherwise, return complex numbers.
+            Some libraries such as TensorRT does not support complex64 data type. So it is useful to provide a real
+            part and an imaginary part separately.
+        theta_rescale_factor (float): Rescale factor for theta. Defaults to 1.0.
+
+    Returns:
+        pos_embed (torch.Tensor): [HW, D/2]
+    """
+
+    grid = get_meshgrid_nd(start, *args, dim=len(rope_dim_list))  # [3, W, H, D] / [2, W, H]
+
+    if isinstance(theta_rescale_factor, int) or isinstance(theta_rescale_factor, float):
+        theta_rescale_factor = [theta_rescale_factor] * len(rope_dim_list)
+    elif isinstance(theta_rescale_factor, list) and len(theta_rescale_factor) == 1:
+        theta_rescale_factor = [theta_rescale_factor[0]] * len(rope_dim_list)
+    assert len(theta_rescale_factor) == len(rope_dim_list), "len(theta_rescale_factor) should equal to len(rope_dim_list)"
+
+    if isinstance(interpolation_factor, int) or isinstance(interpolation_factor, float):
+        interpolation_factor = [interpolation_factor] * len(rope_dim_list)
+    elif isinstance(interpolation_factor, list) and len(interpolation_factor) == 1:
+        interpolation_factor = [interpolation_factor[0]] * len(rope_dim_list)
+    assert len(interpolation_factor) == len(rope_dim_list), "len(interpolation_factor) should equal to len(rope_dim_list)"
+
+    # use 1/ndim of dimensions to encode grid_axis
+    embs = []
+    for i in range(len(rope_dim_list)):
+        emb = get_1d_rotary_pos_embed(
+            rope_dim_list[i],
+            grid[i].reshape(-1),
+            theta,
+            use_real=use_real,
+            theta_rescale_factor=theta_rescale_factor[i],
+            interpolation_factor=interpolation_factor[i],
+        )  # 2 x [WHD, rope_dim_list[i]]
+        embs.append(emb)
+
+    if use_real:
+        cos = torch.cat([emb[0] for emb in embs], dim=1)  # (WHD, D/2)
+        sin = torch.cat([emb[1] for emb in embs], dim=1)  # (WHD, D/2)
+        return cos, sin
+    else:
+        emb = torch.cat(embs, dim=1)  # (WHD, D/2)
+        return emb
+
+
+def get_1d_rotary_pos_embed(
+    dim: int,
+    pos: Union[torch.FloatTensor, int],
+    theta: float = 10000.0,
+    use_real: bool = False,
+    theta_rescale_factor: float = 1.0,
+    interpolation_factor: float = 1.0,
+) -> Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]:
+    """
+    Precompute the frequency tensor for complex exponential (cis) with given dimensions.
+    (Note: `cis` means `cos + i * sin`, where i is the imaginary unit.)
+
+    This function calculates a frequency tensor with complex exponential using the given dimension 'dim'
+    and the end index 'end'. The 'theta' parameter scales the frequencies.
+    The returned tensor contains complex values in complex64 data type.
+
+    Args:
+        dim (int): Dimension of the frequency tensor.
+        pos (int or torch.FloatTensor): Position indices for the frequency tensor. [S] or scalar
+        theta (float, optional): Scaling factor for frequency computation. Defaults to 10000.0.
+        use_real (bool, optional): If True, return real part and imaginary part separately.
+                                   Otherwise, return complex numbers.
+        theta_rescale_factor (float, optional): Rescale factor for theta. Defaults to 1.0.
+
+    Returns:
+        freqs_cis: Precomputed frequency tensor with complex exponential. [S, D/2]
+        freqs_cos, freqs_sin: Precomputed frequency tensor with real and imaginary parts separately. [S, D]
+    """
+    if isinstance(pos, int):
+        pos = torch.arange(pos).float()
+
+    # proposed by reddit user bloc97, to rescale rotary embeddings to longer sequence length without fine-tuning
+    # has some connection to NTK literature
+    if theta_rescale_factor != 1.0:
+        theta *= theta_rescale_factor ** (dim / (dim - 2))
+
+    freqs = 1.0 / (theta ** (torch.arange(0, dim, 2)[: (dim // 2)].float() / dim))  # [D/2]
+    freqs = torch.outer(pos * interpolation_factor, freqs)  # [S, D/2]
+    if use_real:
+        freqs_cos = freqs.cos().repeat_interleave(2, dim=1)  # [S, D]
+        freqs_sin = freqs.sin().repeat_interleave(2, dim=1)  # [S, D]
+        return freqs_cos, freqs_sin
+    else:
+        freqs_cis = torch.polar(torch.ones_like(freqs), freqs)  # complex64     # [S, D/2]
+        return freqs_cis

hyimage/models/hunyuan/modules/token_refiner.py

@@ -0,0 +1,297 @@
+from typing import Optional
+
+import torch
+import torch.nn as nn
+from einops import rearrange
+
+from hyimage.models.hunyuan.modules.flash_attn_no_pad import flash_attn_no_pad
+from .activation_layers import get_activation_layer
+from .embed_layers import TextProjection, TimestepEmbedder
+from .mlp_layers import MLP
+from .modulate_layers import apply_gate
+from .norm_layers import get_norm_layer
+
+
+@torch.compiler.disable
+def attention(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    v: torch.Tensor,
+    drop_rate: float = 0.0,
+    attn_mask: Optional[torch.Tensor] = None,
+    causal: bool = False,
+) -> torch.Tensor:
+    """
+    Compute attention using flash_attn_no_pad.
+
+    Args:
+        q: Query tensor of shape [B, L, H, D]
+        k: Key tensor of shape [B, L, H, D]
+        v: Value tensor of shape [B, L, H, D]
+        drop_rate: Dropout rate for attention weights.
+        attn_mask: Optional attention mask of shape [B, L].
+        causal: Whether to apply causal masking.
+
+    Returns:
+        Output tensor after attention of shape [B, L, H*D]
+    """
+    qkv = torch.stack([q, k, v], dim=2)
+    if attn_mask is not None and attn_mask.dtype != torch.bool:
+        attn_mask = attn_mask.bool()
+    x = flash_attn_no_pad(qkv, attn_mask, causal=causal, dropout_p=drop_rate, softmax_scale=None)
+    b, s, a, d = x.shape
+    out = x.reshape(b, s, -1)
+    return out
+
+
+class IndividualTokenRefinerBlock(nn.Module):
+    """
+    A single block for token refinement with self-attention and MLP.
+
+    Args:
+        hidden_size: Hidden dimension size.
+        heads_num: Number of attention heads.
+        mlp_width_ratio: Expansion ratio for MLP hidden size.
+        mlp_drop_rate: Dropout rate for MLP.
+        act_type: Activation function type.
+        qk_norm: Whether to use QK normalization.
+        qk_norm_type: Type of QK normalization.
+        qkv_bias: Whether to use bias in QKV projections.
+        dtype: Optional torch dtype.
+        device: Optional torch device.
+    """
+
+    def __init__(
+        self,
+        hidden_size: int,
+        heads_num: int,
+        mlp_width_ratio: float = 4.0,
+        mlp_drop_rate: float = 0.0,
+        act_type: str = "silu",
+        qk_norm: bool = False,
+        qk_norm_type: str = "layer",
+        qkv_bias: bool = True,
+        dtype: Optional[torch.dtype] = None,
+        device: Optional[torch.device] = None,
+    ):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+        self.heads_num = heads_num
+        head_dim = hidden_size // heads_num
+        mlp_hidden_dim = int(hidden_size * mlp_width_ratio)
+
+        self.norm1 = nn.LayerNorm(hidden_size, elementwise_affine=True, eps=1e-6, **factory_kwargs)
+        self.self_attn_qkv = nn.Linear(hidden_size, hidden_size * 3, bias=qkv_bias, **factory_kwargs)
+        qk_norm_layer = get_norm_layer(qk_norm_type)
+        self.self_attn_q_norm = (
+            qk_norm_layer(head_dim, elementwise_affine=True, eps=1e-6, **factory_kwargs) if qk_norm else nn.Identity()
+        )
+        self.self_attn_k_norm = (
+            qk_norm_layer(head_dim, elementwise_affine=True, eps=1e-6, **factory_kwargs) if qk_norm else nn.Identity()
+        )
+        self.self_attn_proj = nn.Linear(hidden_size, hidden_size, bias=qkv_bias, **factory_kwargs)
+
+        self.norm2 = nn.LayerNorm(hidden_size, elementwise_affine=True, eps=1e-6, **factory_kwargs)
+        act_layer = get_activation_layer(act_type)
+        self.mlp = MLP(
+            in_channels=hidden_size,
+            hidden_channels=mlp_hidden_dim,
+            act_layer=act_layer,
+            drop=mlp_drop_rate,
+            **factory_kwargs,
+        )
+
+        self.adaLN_modulation = nn.Sequential(
+            act_layer(),
+            nn.Linear(hidden_size, 2 * hidden_size, bias=True, **factory_kwargs),
+        )
+        # Zero-initialize the modulation
+        nn.init.zeros_(self.adaLN_modulation[1].weight)
+        nn.init.zeros_(self.adaLN_modulation[1].bias)
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        c: torch.Tensor,  # timestep_aware_representations + context_aware_representations
+        attn_mask: Optional[torch.Tensor] = None,
+    ) -> torch.Tensor:
+        """
+        Forward pass for IndividualTokenRefinerBlock.
+
+        Args:
+            x: Input tensor of shape [B, L, C].
+            c: Conditioning tensor of shape [B, C].
+            attn_mask: Optional attention mask of shape [B, L].
+
+        Returns:
+            Refined tensor of shape [B, L, C].
+        """
+        gate_msa, gate_mlp = self.adaLN_modulation(c).chunk(2, dim=1)
+        norm_x = self.norm1(x)
+        qkv = self.self_attn_qkv(norm_x)
+        q, k, v = rearrange(qkv, "B L (K H D) -> K B L H D", K=3, H=self.heads_num)
+        q = self.self_attn_q_norm(q).to(v)
+        k = self.self_attn_k_norm(k).to(v)
+        attn = attention(q, k, v, attn_mask=attn_mask)
+        x = x + apply_gate(self.self_attn_proj(attn), gate_msa)
+        x = x + apply_gate(self.mlp(self.norm2(x)), gate_mlp)
+        return x
+
+
+class IndividualTokenRefiner(nn.Module):
+    """
+    Stacks multiple IndividualTokenRefinerBlock modules.
+
+    Args:
+        hidden_size: Hidden dimension size.
+        heads_num: Number of attention heads.
+        depth: Number of blocks.
+        mlp_width_ratio: Expansion ratio for MLP hidden size.
+        mlp_drop_rate: Dropout rate for MLP.
+        act_type: Activation function type.
+        qk_norm: Whether to use QK normalization.
+        qk_norm_type: Type of QK normalization.
+        qkv_bias: Whether to use bias in QKV projections.
+        dtype: Optional torch dtype.
+        device: Optional torch device.
+    """
+
+    def __init__(
+        self,
+        hidden_size: int,
+        heads_num: int,
+        depth: int,
+        mlp_width_ratio: float = 4.0,
+        mlp_drop_rate: float = 0.0,
+        act_type: str = "silu",
+        qk_norm: bool = False,
+        qk_norm_type: str = "layer",
+        qkv_bias: bool = True,
+        dtype: Optional[torch.dtype] = None,
+        device: Optional[torch.device] = None,
+    ):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+        self.blocks = nn.ModuleList(
+            [
+                IndividualTokenRefinerBlock(
+                    hidden_size=hidden_size,
+                    heads_num=heads_num,
+                    mlp_width_ratio=mlp_width_ratio,
+                    mlp_drop_rate=mlp_drop_rate,
+                    act_type=act_type,
+                    qk_norm=qk_norm,
+                    qk_norm_type=qk_norm_type,
+                    qkv_bias=qkv_bias,
+                    **factory_kwargs,
+                )
+                for _ in range(depth)
+            ]
+        )
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        c: torch.LongTensor,
+        mask: Optional[torch.Tensor] = None,
+    ) -> torch.Tensor:
+        """
+        Forward pass for IndividualTokenRefiner.
+
+        Args:
+            x: Input tensor of shape [B, L, C].
+            c: Conditioning tensor of shape [B, C].
+            mask: Optional mask tensor of shape [B, L].
+
+        Returns:
+            Refined tensor of shape [B, L, C].
+        """
+        if mask is not None:
+            mask = mask.clone().bool()
+            mask[:, 0] = True  # Prevent attention weights from becoming NaN
+        for block in self.blocks:
+            x = block(x, c, mask)
+        return x
+
+
+class SingleTokenRefiner(nn.Module):
+    """
+    Single token refiner block for LLM text embedding refinement.
+
+    Args:
+        in_channels: Input feature dimension.
+        hidden_size: Hidden dimension size.
+        heads_num: Number of attention heads.
+        depth: Number of blocks.
+        mlp_width_ratio: Expansion ratio for MLP hidden size.
+        mlp_drop_rate: Dropout rate for MLP.
+        act_type: Activation function type.
+        qk_norm: Whether to use QK normalization.
+        qk_norm_type: Type of QK normalization.
+        qkv_bias: Whether to use bias in QKV projections.
+        dtype: Optional torch dtype.
+        device: Optional torch device.
+    """
+
+    def __init__(
+        self,
+        in_channels: int,
+        hidden_size: int,
+        heads_num: int,
+        depth: int,
+        mlp_width_ratio: float = 4.0,
+        mlp_drop_rate: float = 0.0,
+        act_type: str = "silu",
+        qk_norm: bool = False,
+        qk_norm_type: str = "layer",
+        qkv_bias: bool = True,
+        dtype: Optional[torch.dtype] = None,
+        device: Optional[torch.device] = None,
+    ):
+        factory_kwargs = {"device": device, "dtype": dtype}
+        super().__init__()
+        self.input_embedder = nn.Linear(in_channels, hidden_size, bias=True, **factory_kwargs)
+        act_layer = get_activation_layer(act_type)
+        self.t_embedder = TimestepEmbedder(hidden_size, act_layer, **factory_kwargs)
+        self.c_embedder = TextProjection(in_channels, hidden_size, act_layer, **factory_kwargs)
+        self.individual_token_refiner = IndividualTokenRefiner(
+            hidden_size=hidden_size,
+            heads_num=heads_num,
+            depth=depth,
+            mlp_width_ratio=mlp_width_ratio,
+            mlp_drop_rate=mlp_drop_rate,
+            act_type=act_type,
+            qk_norm=qk_norm,
+            qk_norm_type=qk_norm_type,
+            qkv_bias=qkv_bias,
+            **factory_kwargs,
+        )
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        t: torch.LongTensor,
+        mask: Optional[torch.LongTensor] = None,
+    ) -> torch.Tensor:
+        """
+        Forward pass for SingleTokenRefiner.
+
+        Args:
+            x: Input tensor of shape [B, L, in_channels].
+            t: Timestep tensor of shape [B].
+            mask: Optional mask tensor of shape [B, L].
+
+        Returns:
+            Refined tensor of shape [B, L, hidden_size].
+        """
+        timestep_aware_representations = self.t_embedder(t)
+        if mask is None:
+            context_aware_representations = x.mean(dim=1)
+        else:
+            mask_float = mask.unsqueeze(-1)  # [B, L, 1]
+            context_aware_representations = (x * mask_float).sum(dim=1) / mask_float.sum(dim=1)
+        context_aware_representations = self.c_embedder(context_aware_representations)
+        c = timestep_aware_representations + context_aware_representations
+        x = self.input_embedder(x)
+        x = self.individual_token_refiner(x, c, mask)
+        return x

hyimage/models/hunyuan/utils/helpers.py

@@ -0,0 +1,23 @@
+import collections.abc
+from itertools import repeat
+
+def _ntuple(n):
+    """
+    Returns a function that converts input to a tuple of length n.
+    If input is an iterable (except str), it is converted to a tuple.
+    If the tuple has length 1, it is repeated n times.
+    Otherwise, the input is repeated n times to form the tuple.
+    """
+    def parse(x):
+        if isinstance(x, collections.abc.Iterable) and not isinstance(x, str):
+            x = tuple(x)
+            if len(x) == 1:
+                x = tuple(repeat(x[0], n))
+            return x
+        return tuple(repeat(x, n))
+    return parse
+
+to_1tuple = _ntuple(1)
+to_2tuple = _ntuple(2)
+to_3tuple = _ntuple(3)
+to_4tuple = _ntuple(4)

hyimage/models/model_zoo.py

@@ -0,0 +1,143 @@
+import os
+import copy
+
+from hyimage.common.config import LazyCall as L
+from hyimage.models.hunyuan.configs.hunyuanimage_config import (
+    hunyuanimage_v2_1_cfg,
+    hunyuanimage_v2_1_distilled_cfg,
+    hunyuanimage_refiner_cfg,
+)
+from hyimage.models.vae import load_vae
+from hyimage.common.config.base_config import (
+    DiTConfig,
+    RepromptConfig,
+    TextEncoderConfig,
+    VAEConfig,
+)
+from hyimage.models.text_encoder import TextEncoder
+
+HUNYUANIMAGE_V2_1_MODEL_ROOT = os.environ.get("HUNYUANIMAGE_V2_1_MODEL_ROOT", "./ckpts")
+
+# =============================================================================
+# MODEL CONFIGURATIONS
+# =============================================================================
+
+# =============================================================================
+# V2.1 MODELS
+# =============================================================================
+
+def HUNYUANIMAGE_V2_1_TEXT_ENCODER(**kwargs):
+    return TextEncoderConfig(
+        model=L(TextEncoder)(
+            text_encoder_type="llm",
+            max_length=1000,
+            text_encoder_precision='fp16',
+            tokenizer_type="llm",
+            text_encoder_path=None,
+            prompt_template=None,
+            prompt_template_video=None,
+            hidden_state_skip_layer=2,
+            apply_final_norm=False,
+            reproduce=False,
+            logger=None,
+            device=None,
+        ),
+        prompt_template="dit-llm-encode-v2",
+        load_from=f"{HUNYUANIMAGE_V2_1_MODEL_ROOT}/text_encoder",
+        text_len=1000,
+    )
+
+
+def HUNYUANIMAGE_V2_1_VAE_32x(**kwargs):
+    return VAEConfig(
+        model=L(load_vae)(
+            vae_path=None,
+            device="cuda",
+        ),
+        load_from=f"{HUNYUANIMAGE_V2_1_MODEL_ROOT}/vae/vae_2_1",
+        cpu_offload=False,
+    )
+
+
+def HUNYUANIMAGE_V2_1_DIT(**kwargs):
+    return DiTConfig(
+        model=copy.deepcopy(hunyuanimage_v2_1_cfg),
+        use_lora=False,
+        use_cpu_offload=False,
+        gradient_checkpointing=True,
+        load_from=f"{HUNYUANIMAGE_V2_1_MODEL_ROOT}/dit/hunyuanimage2.1.safetensors",
+        use_compile=True,
+    )
+
+
+def HUNYUANIMAGE_V2_1_DIT_CFG_DISTILL(**kwargs):
+    return DiTConfig(
+        model=copy.deepcopy(hunyuanimage_v2_1_distilled_cfg),
+        use_lora=False,
+        use_cpu_offload=False,
+        gradient_checkpointing=True,
+        load_from=f"{HUNYUANIMAGE_V2_1_MODEL_ROOT}/dit/hunyuanimage2.1-distilled.safetensors",
+        use_compile=True,
+    )
+
+# =============================================================================
+# REFINER MODELS
+# =============================================================================
+
+def HUNYUANIMAGE_REFINER_DIT(**kwargs):
+    return DiTConfig(
+        model=copy.deepcopy(hunyuanimage_refiner_cfg),
+        use_lora=False,
+        use_cpu_offload=False,
+        gradient_checkpointing=True,
+        load_from=f"{HUNYUANIMAGE_V2_1_MODEL_ROOT}/dit/hunyuanimage-refiner.safetensors",
+        use_compile=True,
+    )
+
+def HUNYUANIMAGE_REFINER_VAE_32x(**kwargs):
+    return VAEConfig(
+        model=L(load_vae)(
+            vae_path=None,
+            device="cuda",
+        ),
+        load_from=f"{HUNYUANIMAGE_V2_1_MODEL_ROOT}/vae/vae_refiner",
+        cpu_offload=False,
+    )
+
+
+def HUNYUANIMAGE_REFINER_TEXT_ENCODER(**kwargs):
+    return TextEncoderConfig(
+        model=L(TextEncoder)(
+            text_encoder_type="llm",
+            max_length=1000,
+            text_encoder_precision='fp16',
+            tokenizer_type="llm",
+            text_encoder_path=None,
+            prompt_template=None,
+            prompt_template_video=None,
+            hidden_state_skip_layer=2,
+            apply_final_norm=False,
+            reproduce=False,
+            logger=None,
+            device=None,
+        ),
+        prompt_template="dit-llm-encode",
+        load_from=f"{HUNYUANIMAGE_V2_1_MODEL_ROOT}/text_encoder",
+        text_len=256,
+    )
+
+
+# =============================================================================
+# SPECIALIZED MODELS
+# =============================================================================
+
+def HUNYUANIMAGE_REPROMPT(**kwargs):
+    from hyimage.models.reprompt import RePrompt
+    
+    return RepromptConfig(
+        model=L(RePrompt)(
+            models_root_path=None,
+            device_map="auto",
+        ),
+        load_from=f"{HUNYUANIMAGE_V2_1_MODEL_ROOT}/reprompt",
+    )

hyimage/models/reprompt/__init__.py

@@ -0,0 +1 @@
+from .reprompt import RePrompt

hyimage/models/reprompt/reprompt.py

@@ -0,0 +1,108 @@
+import re
+import loguru
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from accelerate import cpu_offload_with_hook
+
+"""
+English translation of the System prompt:
+----------------------------------------
+You are an expert in writing image generation prompts. Please rewrite the user's prompt according to the following requirements:
+1. The main subject/action/quantity/style/layout/relationship/attribute/text in the rewritten prompt must be consistent with the original intention;
+2. The rewritten prompt should follow the "overall-detail-conclusion" structure, ensuring the clarity of information hierarchy;
+3. The rewritten prompt should be objective and neutral, avoiding subjective judgment and emotional evaluation;
+4. The rewritten prompt should be from the main to the secondary, always describing the most important elements first, and then the secondary and background elements;
+5. The rewritten prompt should be logically clear, strictly follow the spatial logic or main-secondary logic, allowing the reader to reconstruct the image in the brain;
+6. The rewritten prompt should end with a summary sentence, summarizing the overall style or type of the image.
+"""
+
+SYSTEM_PROMPT = (
+    "你是一位图像生成提示词撰写专家，请根据用户输入的提示词，改写生成新的提示词，改写后的提示词要求："
+    "1 改写后提示词包含的主体/动作/数量/风格/布局/关系/属性/文字等 必须和改写前的意图一致； "
+    "2 在宏观上遵循“总-分-总”的结构，确保信息的层次清晰；"
+    "3 客观中立，避免主观臆断和情感评价；"
+    "4 由主到次，始终先描述最重要的元素，再描述次要和背景元素；"
+    "5 逻辑清晰，严格遵循空间逻辑或主次逻辑，使读者能在大脑中重建画面；"
+    "6 结尾点题，必须用一句话总结图像的整体风格或类型。"
+)
+
+
+def replace_single_quotes(text):
+    """
+    Replace single quotes within words with double quotes, and convert
+    curly single quotes to curly double quotes for consistency.
+    """
+    pattern = r"\B'([^']*)'\B"
+    replaced_text = re.sub(pattern, r'"\1"', text)
+    replaced_text = replaced_text.replace("’", "”")
+    replaced_text = replaced_text.replace("‘", "“")
+    return replaced_text
+
+
+class RePrompt:
+
+    def __init__(self, models_root_path, device_map="auto", enable_offloading=True):
+        """
+        Initialize the RePrompt class with model and processor.
+
+        Args:
+            models_root_path (str): Path to the pretrained model.
+            device_map (str): Device mapping for model loading.
+        """
+        if enable_offloading:
+            device_map = None
+        self.model = AutoModelForCausalLM.from_pretrained(models_root_path, device_map=device_map, trust_remote_code=True)
+        self.tokenizer = AutoTokenizer.from_pretrained(models_root_path, trust_remote_code=True)
+        self.enable_offloading = enable_offloading
+
+        if enable_offloading:
+            _, self.offload_hook = cpu_offload_with_hook(self.model, execution_device=torch.device('cuda'))
+        self.device_map = device_map
+        self.original_device_map = getattr(self.model, 'hf_device_map', None)
+
+    @torch.inference_mode()
+    def predict(
+        self,
+        prompt_cot,
+        sys_prompt=SYSTEM_PROMPT,
+    ):
+        """
+        Generate a rewritten prompt using the model.
+
+        Args:
+            prompt_cot (str): The original prompt to be rewritten.
+            sys_prompt (str): System prompt to guide the rewriting.
+            temperature (float): Sampling temperature.
+            device (str): Device for inference.
+
+        Returns:
+            str: The rewritten prompt, or the original if generation fails.
+        """
+        org_prompt_cot = prompt_cot
+        try:
+            messages = [
+                {"role": "system", "content": sys_prompt},
+                {"role": "user", "content": org_prompt_cot},
+            ]
+            tokenized_chat = self.tokenizer.apply_chat_template(
+                messages, tokenize=True, add_generation_prompt=True, return_tensors="pt", enable_thinking=False  # Toggle thinking mode (default: True)
+            )
+            if self.model.device != torch.device('meta'):
+                tokenized_chat = tokenized_chat.to(self.model.device)
+            outputs = self.model.generate(tokenized_chat, max_new_tokens=2048, temperature=0.0, do_sample=False, top_k=5, top_p=0.9)
+            if self.enable_offloading:
+                self.offload_hook.offload()
+            output_res = self.tokenizer.decode(outputs[0])
+            answer_pattern = r'<answer>(.*?)</answer>'
+            answer_matches = re.findall(answer_pattern, output_res, re.DOTALL)
+            prompt_cot = [match.strip() for match in answer_matches][0]
+            prompt_cot = replace_single_quotes(prompt_cot)
+        except Exception as e:
+            prompt_cot = org_prompt_cot
+            loguru.logger.error(f"✗ Re-prompting failed, fall back to generate prompt. Cause: {e}")
+
+        return prompt_cot
+
+    def to(self, device, *args, **kwargs):
+        self.model = self.model.to(device, *args, **kwargs)
+        return self

hyimage/models/text_encoder/__init__.py

@@ -0,0 +1,469 @@
+from dataclasses import dataclass
+from typing import Optional, Tuple
+from copy import deepcopy
+
+import torch
+import torch.nn as nn
+from transformers import AutoModelForVision2Seq, AutoTokenizer
+
+from transformers.utils import ModelOutput
+
+
+def use_default(value, default):
+    """Utility: return value if not None, else default."""
+    return value if value is not None else default
+
+# Prompt templates for different models and tasks
+PROMPT_TEMPLATE_ENCODE = (
+    "<|start_header_id|>system<|end_header_id|>\n\nDescribe the image by detailing the color, shape, size, texture, "
+    "quantity, text, spatial relationships of the objects and background:<|eot_id|>"
+    "<|start_header_id|>user<|end_header_id|>\n\n{}<|eot_id|>"
+)
+PROMPT_TEMPLATE_ENCODE_V2 = (
+    "<|im_start|>system\nDescribe the image by detailing the color, shape, size, texture, "
+    "quantity, text, spatial relationships of the objects and background:<|im_end|>\n"
+    "<|im_start|>user\n{}<|im_end|>"
+)
+
+NEGATIVE_PROMPT = (
+    "Aerial view, aerial view, overexposed, low quality, deformation, a poor composition, "
+    "bad hands, bad teeth, bad eyes, bad limbs, distortion"
+)
+
+PROMPT_TEMPLATE = {
+    "dit-llm-encode": {
+        "template": PROMPT_TEMPLATE_ENCODE,
+        "crop_start": 36,
+    },
+    "dit-llm-encode-v2": {
+        "template": PROMPT_TEMPLATE_ENCODE_V2,
+        "crop_start": 34,
+    },
+}
+
+def load_text_encoder(
+    text_encoder_type,
+    text_encoder_precision=None,
+    text_encoder_path=None,
+    infer_mode="encoder",
+    logger=None,
+    device=None
+):
+    """
+    Load a text encoder model from pretrained weights.
+
+    Args:
+        text_encoder_type (str): Type of text encoder.
+        text_encoder_precision (str, optional): Precision for model weights.
+        text_encoder_path (str, optional): Path to pretrained weights.
+        infer_mode (str): "encoder" or "decoder".
+        logger (logging.Logger, optional): Logger for info.
+        device (torch.device, optional): Device to move model to.
+
+    Returns:
+        model (nn.Module): Loaded text encoder.
+        model_path (str): Path to model.
+    """
+    if logger is not None:
+        logger.info(f"Loading text encoder model ({text_encoder_type}) from: {text_encoder_path}")
+
+    if text_encoder_type == 'llm':
+        text_encoder = AutoModelForVision2Seq.from_pretrained(
+            text_encoder_path,
+            torch_dtype="auto"
+        )
+    else:
+        raise ValueError(f"Unsupported text encoder type: {text_encoder_type}")
+
+    text_encoder.requires_grad_(False)
+
+    if logger is not None:
+        logger.info(f"Text encoder to dtype: {text_encoder.dtype}")
+
+    if device is not None:
+        text_encoder = text_encoder.to(device)
+
+    return text_encoder, text_encoder_path
+
+def load_tokenizer(
+    tokenizer_type,
+    tokenizer_path=None,
+    padding_side="right",
+    logger=None
+):
+    """
+    Load a tokenizer from pretrained weights.
+
+    Args:
+        tokenizer_type (str): Type of tokenizer.
+        tokenizer_path (str, optional): Path to pretrained tokenizer.
+        padding_side (str): Padding side for tokenizer.
+        logger (logging.Logger, optional): Logger for info.
+
+    Returns:
+        tokenizer: Loaded tokenizer.
+        tokenizer_path (str): Path to tokenizer.
+    """
+    if logger is not None:
+        logger.info(f"Loading tokenizer ({tokenizer_type}) from: {tokenizer_path}")
+
+    if tokenizer_type == "llm":
+        tokenizer = AutoTokenizer.from_pretrained(
+            tokenizer_path, use_fast=False, padding_side=padding_side, trust_remote_code=True)
+    else:
+        raise ValueError(f"Unsupported tokenizer type: {tokenizer_type}")
+
+    return tokenizer, tokenizer_path
+
+@dataclass
+class TextEncoderModelOutput(ModelOutput):
+    """
+    Output for text encoder models.
+
+    Args:
+        hidden_state (torch.FloatTensor): Output hidden states of the last layer.
+        attention_mask (torch.LongTensor, optional): Attention mask for valid tokens.
+        hidden_states_list (tuple(torch.FloatTensor), optional): All hidden states if requested.
+        text_outputs (list, optional): Decoded texts if requested.
+    """
+    hidden_state: torch.FloatTensor = None
+    attention_mask: Optional[torch.LongTensor] = None
+    hidden_states_list: Optional[Tuple[torch.FloatTensor, ...]] = None
+    text_outputs: Optional[list] = None
+
+class TextEncoder(nn.Module):
+    """
+    TextEncoder wraps a pretrained text encoder and tokenizer for flexible text encoding.
+
+    Args:
+        text_encoder_type (str): Type of text encoder.
+        max_length (int): Maximum sequence length.
+        text_encoder_precision (str, optional): Precision for model weights.
+        text_encoder_path (str, optional): Path to pretrained weights.
+        tokenizer_type (str, optional): Type of tokenizer.
+        tokenizer_path (str, optional): Path to pretrained tokenizer.
+        output_key (str, optional): Output key for model output.
+        use_attention_mask (bool): Whether to use attention mask.
+        infer_mode (str): "encoder" or "decoder".
+        input_max_length (int, optional): Max input length.
+        prompt_template (dict, optional): Prompt template for image.
+        prompt_template_video (dict, optional): Prompt template for video.
+        hidden_state_skip_layer (int, optional): Skip layers from last for hidden state.
+        apply_final_norm (bool): Whether to apply final layer norm.
+        reproduce (bool): Deterministic output if True.
+        logger (logging.Logger, optional): Logger for info.
+        device (torch.device, optional): Device to move model to.
+    """
+    def __init__(
+        self,
+        text_encoder_type: str,
+        max_length: int,
+        text_encoder_precision: Optional[str] = None,
+        text_encoder_path: Optional[str] = None,
+        tokenizer_type: Optional[str] = None,
+        tokenizer_path: Optional[str] = None,
+        output_key: Optional[str] = None,
+        use_attention_mask: bool = True,
+        infer_mode: str = "encoder",
+        input_max_length: Optional[int] = None,
+        prompt_template: Optional[dict] = None,
+        prompt_template_video: Optional[dict] = None,
+        hidden_state_skip_layer: Optional[int] = None,
+        apply_final_norm: bool = False,
+        reproduce: bool = False,
+        logger=None,
+        device=None,
+    ):
+        super().__init__()
+        self.text_encoder_type = text_encoder_type
+        self.max_length = max_length
+        self.precision = text_encoder_precision
+        self.model_path = text_encoder_path
+        self.tokenizer_type = tokenizer_type if tokenizer_type is not None else text_encoder_type
+        self.tokenizer_path = tokenizer_path if tokenizer_path is not None else text_encoder_path
+        self.use_attention_mask = use_attention_mask
+        self.input_max_length = input_max_length if input_max_length is not None else max_length
+        self.prompt_template = dict(prompt_template) if prompt_template is not None else None
+        self.prompt_template_video = dict(prompt_template_video) if prompt_template_video is not None else None
+        self.hidden_state_skip_layer = hidden_state_skip_layer
+        self.apply_final_norm = apply_final_norm
+        self.infer_mode = infer_mode
+        self.reproduce = reproduce
+        self.logger = logger
+
+        self.use_template = self.prompt_template is not None
+        if self.use_template:
+            assert isinstance(self.prompt_template, dict) and "template" in self.prompt_template, (
+                f"`prompt_template` must be a dictionary with a key 'template', got {self.prompt_template}"
+            )
+            if self.prompt_template_video is not None:
+                assert isinstance(self.prompt_template_video, dict) and "template" in self.prompt_template_video, (
+                    f"`prompt_template_video` must be a dictionary with a key 'template', got {self.prompt_template_video}"
+                )
+            assert '{}' in str(self.prompt_template["template"]), (
+                "`prompt_template['template']` must contain a placeholder `{}` for the input text, "
+                f"got {self.prompt_template['template']}"
+            )
+
+        if infer_mode == "decoder":
+            assert text_encoder_type in ["llava-llama-3-8b"], (
+                f"Unsupported text encoder type for infer_mode='decoder': {text_encoder_type}"
+            )
+            assert self.prompt_template is not None and hidden_state_skip_layer is not None, (
+                f"`prompt_template` and `hidden_state_skip_layer` must be provided for infer_mode='decoder', "
+                f"got prompt_template={self.prompt_template}, hidden_state_skip_layer={self.hidden_state_skip_layer}"
+            )
+
+        if "t5" in text_encoder_type:
+            self.output_key = output_key or "last_hidden_state"
+        elif "clip" in text_encoder_type:
+            self.output_key = output_key or "pooler_output"
+        elif any(x in text_encoder_type for x in ["llm"]):
+            self.output_key = output_key or ("last_hidden_state" if infer_mode == "encoder" else None)
+        else:
+            raise ValueError(f"Unsupported text encoder type: {text_encoder_type}")
+
+        self.model, self.model_path = load_text_encoder(
+            text_encoder_type=self.text_encoder_type,
+            text_encoder_precision=self.precision,
+            text_encoder_path=self.model_path,
+            infer_mode=self.infer_mode,
+            logger=self.logger,
+            device=device
+        )
+        self.dtype = self.model.dtype
+        self.device = self.model.device
+
+        padding_side = "right" if self.infer_mode == "encoder" else "left"
+        self.tokenizer, self.tokenizer_path = load_tokenizer(
+            tokenizer_type=self.tokenizer_type,
+            tokenizer_path=self.tokenizer_path,
+            padding_side=padding_side,
+            logger=self.logger
+        )
+
+    def __repr__(self):
+        return f"{self.text_encoder_type} ({self.precision} - {self.model_path})"
+
+    @staticmethod
+    def apply_text_to_template(text, template, prevent_empty_text=True):
+        """
+        Apply text to a prompt template.
+
+        Args:
+            text (str): Input text.
+            template (str or list): Template string or list of chat conversation.
+            prevent_empty_text (bool): If True, prevent empty user text by adding a space.
+
+        Returns:
+            str or list: Text with template applied.
+        """
+        if isinstance(template, str):
+            return template.format(text)
+        elif isinstance(template, list):
+            conversation = deepcopy(template)
+            for message in conversation:
+                if '{}' in message.get("content", ""):
+                    filled_text = message["content"].format(text)
+                    if prevent_empty_text and len(filled_text) == 0:
+                        filled_text = ' '
+                    message["content"] = filled_text
+                    break  # Only one placeholder per conversation
+            return conversation
+        else:
+            raise TypeError(f"Unsupported template type: {type(template)}")
+
+    def text2tokens(self, text, data_type='image'):
+        """
+        Tokenize the input text, optionally applying a prompt template.
+
+        Args:
+            text (str or list): Input text.
+            data_type (str): 'image' or 'video'.
+
+        Returns:
+            dict: Tokenized input.
+        """
+        tokenize_input_type = 'str'
+        if self.use_template:
+            if data_type == 'image':
+                prompt_template = self.prompt_template["template"]
+            elif data_type == 'video':
+                prompt_template = self.prompt_template_video["template"]
+            else:
+                raise ValueError(f"Unsupported data type: {data_type}")
+            if isinstance(text, (list, tuple)):
+                text = [self.apply_text_to_template(one_text, prompt_template) for one_text in text]
+                if isinstance(text[0], list):
+                    tokenize_input_type = 'list'
+            elif isinstance(text, str):
+                text = self.apply_text_to_template(text, prompt_template)
+                if isinstance(text, list):
+                    tokenize_input_type = 'list'
+            else:
+                raise TypeError(f"Unsupported text type: {type(text)}")
+        kwargs = dict(truncation=True, max_length=self.max_length, padding="max_length", return_tensors="pt")
+        if tokenize_input_type == 'str':
+            return self.tokenizer(
+                text,
+                return_length=False,
+                return_overflowing_tokens=False,
+                return_attention_mask=True,
+                **kwargs,
+            )
+        elif tokenize_input_type == 'list':
+            return self.tokenizer.apply_chat_template(
+                text,
+                add_generation_prompt=True,
+                tokenize=True,
+                return_dict=True,
+                **kwargs,
+            )
+        else:
+            raise ValueError(f"Unsupported tokenize_input_type: {tokenize_input_type}")
+
+    def encode(
+        self,
+        batch_encoding,
+        use_attention_mask=None,
+        output_hidden_states=False,
+        do_sample=None,
+        hidden_state_skip_layer=None,
+        return_texts=False,
+        data_type='image',
+        device=None
+    ):
+        """
+        Encode tokenized input using the text encoder.
+
+        Args:
+            batch_encoding (dict): Batch encoding from tokenizer.
+            use_attention_mask (bool, optional): Whether to use attention mask.
+            output_hidden_states (bool): Whether to output all hidden states.
+            do_sample (bool, optional): Whether to sample from the model (for decoder-only LLMs).
+            hidden_state_skip_layer (int, optional): Number of layers to skip from last for hidden state.
+            return_texts (bool): Whether to return decoded texts.
+            data_type (str): 'image' or 'video'.
+            device (torch.device, optional): Device to use.
+
+        Returns:
+            TextEncoderModelOutput: Encoded output.
+        """
+        use_attention_mask = use_default(use_attention_mask, self.use_attention_mask)
+        hidden_state_skip_layer = use_default(hidden_state_skip_layer, self.hidden_state_skip_layer)
+        do_sample = use_default(do_sample, not self.reproduce)
+
+        if self.infer_mode == "encoder":
+            attention_mask = batch_encoding["attention_mask"].to(self.model.device) if use_attention_mask else None
+            if 'Gemma2' in self.text_encoder_type:
+                input_ids = batch_encoding["input_ids"].to(self.model.device)
+                _, inputs_embeds, labels, attention_mask = self.model.merge_multimodal(
+                    text_input_ids=input_ids,
+                    text_attention_masks=attention_mask,
+                    text_labels=None,
+                    pixel_values=[None]
+                )
+                outputs = self.model.llm(inputs_embeds=inputs_embeds, labels=labels, attention_mask=attention_mask)
+            else:
+                outputs = self.model(
+                    input_ids=batch_encoding["input_ids"].to(self.model.device),
+                    attention_mask=attention_mask,
+                    output_hidden_states=output_hidden_states or hidden_state_skip_layer is not None,
+                )
+            if hidden_state_skip_layer is not None:
+                last_hidden_state = outputs.hidden_states[-(hidden_state_skip_layer + 1)]
+                # Apply final norm for intermediate layers if requested
+                if hidden_state_skip_layer > 0 and self.apply_final_norm:
+                    last_hidden_state = self.model.final_layer_norm(last_hidden_state)
+            else:
+                last_hidden_state = outputs[self.output_key]
+
+            # Remove hidden states of instruction tokens, only keep prompt tokens.
+            if self.use_template:
+                if data_type == 'image':
+                    crop_start = self.prompt_template.get("crop_start", -1)
+                elif data_type == 'video':
+                    crop_start = self.prompt_template_video.get("crop_start", -1)
+                else:
+                    raise ValueError(f"Unsupported data type: {data_type}")
+                if crop_start > 0:
+                    last_hidden_state = last_hidden_state[:, crop_start:]
+                    attention_mask = attention_mask[:, crop_start:] if use_attention_mask else None
+
+            if output_hidden_states:
+                return TextEncoderModelOutput(last_hidden_state, attention_mask, outputs.hidden_states)
+            return TextEncoderModelOutput(last_hidden_state, attention_mask)
+
+        elif self.infer_mode == "decoder":
+            # Remove leading padding tokens
+            input_max_valid_tokens = batch_encoding["attention_mask"].sum(dim=1).max().item()
+            if input_max_valid_tokens < batch_encoding["attention_mask"].shape[1]:
+                batch_encoding = {
+                    "input_ids": batch_encoding["input_ids"][:, -input_max_valid_tokens:],
+                    "attention_mask": batch_encoding["attention_mask"][:, -input_max_valid_tokens:],
+                }
+
+            # Generate text from the model.
+            outputs = self.model.generate(
+                input_ids=batch_encoding["input_ids"].to(self.model.device),
+                attention_mask=batch_encoding["attention_mask"].to(self.model.device) if use_attention_mask else None,
+                max_new_tokens=self.max_length,
+                do_sample=do_sample,
+                return_dict_in_generate=True,
+                output_hidden_states=True,
+                stop_strings='<|eot_id|>', tokenizer=self.tokenizer,
+                pad_token_id=self.tokenizer.eos_token_id,
+            )
+
+            # Concatenate hidden states from all generated tokens.
+            hidden_states = torch.cat([
+                per_token_hidden_states[-(hidden_state_skip_layer + 1)]
+                for per_token_hidden_states in outputs.hidden_states[1:]
+            ], dim=1)
+            if self.apply_final_norm:
+                hidden_states = self.model.final_layer_norm(hidden_states)
+
+            # Make sequence mask from output sequences
+            output_max_valid_tokens = hidden_states.shape[1]
+            attention_mask = (outputs.sequences[:, -output_max_valid_tokens - 1:-1] != self.tokenizer.eos_token_id).long()
+
+            if return_texts:
+                text_outputs = self.tokenizer.batch_decode(outputs.sequences, skip_special_tokens=False)
+                return TextEncoderModelOutput(hidden_states, attention_mask, None, text_outputs)
+            else:
+                return TextEncoderModelOutput(hidden_states, attention_mask)
+        else:
+            raise ValueError(f"Unsupported text encoder infer mode: {self.infer_mode}")
+
+    def forward(
+        self,
+        text,
+        use_attention_mask=None,
+        output_hidden_states=False,
+        do_sample=False,
+        hidden_state_skip_layer=None,
+        return_texts=False
+    ):
+        """
+        Forward pass: encode text to hidden states.
+
+        Args:
+            text (str or list): Input text.
+            use_attention_mask (bool, optional): Whether to use attention mask.
+            output_hidden_states (bool): Whether to output all hidden states.
+            do_sample (bool): Whether to sample from the model (for decoder-only LLMs).
+            hidden_state_skip_layer (int, optional): Number of layers to skip from last for hidden state.
+            return_texts (bool): Whether to return decoded texts.
+
+        Returns:
+            TextEncoderModelOutput: Encoded output.
+        """
+        batch_encoding = self.text2tokens(text)
+        return self.encode(
+            batch_encoding,
+            use_attention_mask=use_attention_mask,
+            output_hidden_states=output_hidden_states,
+            do_sample=do_sample,
+            hidden_state_skip_layer=hidden_state_skip_layer,
+            return_texts=return_texts
+        )

hyimage/models/text_encoder/byT5/__init__.py

@@ -0,0 +1,213 @@
+import json
+import torch
+import torch.nn as nn
+from transformers import AutoTokenizer, T5ForConditionalGeneration
+
+
+def load_glyph_byT5_v2(args, device):
+    """
+    Loads ByT5 tokenizer and encoder model for glyph encoding.
+
+    Args:
+        args (dict): Configuration dictionary containing paths and settings.
+        device (str or torch.device): Device to load the model onto.
+
+    Returns:
+        dict: Dictionary with keys 'byt5_tokenizer', 'byt5_model', 'byt5_max_length'.
+    """
+    byt5_tokenizer, byt5_model, byt5_max_length = create_byt5(args, device)
+    byt5_model = byt5_model.to(device=device)
+    return {
+        "byt5_tokenizer": byt5_tokenizer,
+        "byt5_model": byt5_model,
+        "byt5_max_length": byt5_max_length,
+    }
+
+
+def create_byt5(args, device):
+    """
+    Create ByT5 tokenizer and encoder, load weights if provided.
+
+    Args:
+        args (dict): Configuration dictionary.
+        device (str or torch.device): Device to load the model onto.
+
+    Returns:
+        tuple: (byt5_tokenizer, byt5_model, byt5_max_length)
+    """
+    byt5_max_length = args['byt5_max_length']
+    byt5_config = dict(
+        byt5_name=args['byT5_google_path'],
+        special_token=True,
+        color_special_token=True,
+        font_special_token=True,
+        color_ann_path=args['multilingual_prompt_format_color_path'],
+        font_ann_path=args['multilingual_prompt_format_font_path'],
+        multilingual=True,
+    )
+    huggingface_cache_dir = None
+    byt5_model, byt5_tokenizer = load_byt5_and_byt5_tokenizer(
+        **byt5_config,
+        huggingface_cache_dir=huggingface_cache_dir,
+        device=device,
+    )
+
+    # Load custom checkpoint if provided
+    if args['byT5_ckpt_path'] is not None:
+        if "cuda" not in str(device):
+            byt5_state_dict = torch.load(args['byT5_ckpt_path'], map_location=f"cuda:{device}")
+        else:
+            byt5_state_dict = torch.load(args['byT5_ckpt_path'], map_location=device)
+        if 'state_dict' in byt5_state_dict:
+            sd = byt5_state_dict["state_dict"]
+            newsd = {}
+            for k, v in sd.items():
+                if k.startswith('module.text_tower.encoder.'):
+                    newsd[k[len('module.text_tower.encoder.'):]] = v
+            byt5_state_dict = newsd
+        byt5_model.load_state_dict(byt5_state_dict)
+    byt5_model.requires_grad_(False)
+    return byt5_tokenizer, byt5_model, byt5_max_length
+
+
+def add_special_token(
+    tokenizer,
+    text_encoder,
+    add_color,
+    add_font,
+    color_ann_path,
+    font_ann_path,
+    multilingual=False,
+):
+    """
+    Add special tokens for color and font to tokenizer and text encoder.
+
+    Args:
+        tokenizer: Huggingface tokenizer.
+        text_encoder: Huggingface T5 encoder.
+        add_color (bool): Whether to add color tokens.
+        add_font (bool): Whether to add font tokens.
+        color_ann_path (str): Path to color annotation JSON.
+        font_ann_path (str): Path to font annotation JSON.
+        multilingual (bool): Whether to use multilingual font tokens.
+    """
+    with open(font_ann_path, 'r') as f:
+        idx_font_dict = json.load(f)
+    with open(color_ann_path, 'r') as f:
+        idx_color_dict = json.load(f)
+
+    if multilingual:
+        font_token = [f'<{font_code[:2]}-font-{idx_font_dict[font_code]}>' for font_code in idx_font_dict]
+    else:
+        font_token = [f'<font-{i}>' for i in range(len(idx_font_dict))]
+    color_token = [f'<color-{i}>' for i in range(len(idx_color_dict))]
+    additional_special_tokens = []
+    if add_color:
+        additional_special_tokens += color_token
+    if add_font:
+        additional_special_tokens += font_token
+
+    tokenizer.add_tokens(additional_special_tokens, special_tokens=True)
+    # Set mean_resizing=False to avoid PyTorch LAPACK dependency
+    text_encoder.resize_token_embeddings(len(tokenizer), mean_resizing=False)
+
+
+def load_byt5_and_byt5_tokenizer(
+    byt5_name='google/byt5-small',
+    special_token=False,
+    color_special_token=False,
+    font_special_token=False,
+    color_ann_path='assets/color_idx.json',
+    font_ann_path='assets/font_idx_512.json',
+    huggingface_cache_dir=None,
+    multilingual=False,
+    device=None,
+):
+    """
+    Load ByT5 encoder and tokenizer from Huggingface, and add special tokens if needed.
+
+    Args:
+        byt5_name (str): Model name or path.
+        special_token (bool): Whether to add special tokens.
+        color_special_token (bool): Whether to add color tokens.
+        font_special_token (bool): Whether to add font tokens.
+        color_ann_path (str): Path to color annotation JSON.
+        font_ann_path (str): Path to font annotation JSON.
+        huggingface_cache_dir (str): Huggingface cache directory.
+        multilingual (bool): Whether to use multilingual font tokens.
+        device (str or torch.device): Device to load the model onto.
+
+    Returns:
+        tuple: (byt5_text_encoder, byt5_tokenizer)
+    """
+    byt5_tokenizer = AutoTokenizer.from_pretrained(
+        byt5_name,
+        cache_dir=huggingface_cache_dir,
+    )
+    byt5_text_encoder = T5ForConditionalGeneration.from_pretrained(
+        byt5_name,
+        cache_dir=huggingface_cache_dir,
+    ).get_encoder()
+
+    if "cuda" not in str(device):
+        device = torch.device(f"cuda:{device}")
+    else:
+        device = torch.device(device)
+    byt5_text_encoder = byt5_text_encoder.to(device)
+
+    if special_token:
+        add_special_token(
+            byt5_tokenizer,
+            byt5_text_encoder,
+            add_color=color_special_token,
+            add_font=font_special_token,
+            color_ann_path=color_ann_path,
+            font_ann_path=font_ann_path,
+            multilingual=multilingual,
+        )
+    return byt5_text_encoder, byt5_tokenizer
+
+
+class ByT5Mapper(nn.Module):
+    """
+    ByT5Mapper: Maps ByT5 encoder outputs to a new space, with optional residual connection.
+
+    Args:
+        in_dim (int): Input dimension (must equal out_dim if use_residual).
+        out_dim (int): Output dimension after second linear layer.
+        hidden_dim (int): Hidden dimension for intermediate layer.
+        out_dim1 (int): Final output dimension.
+        use_residual (bool): Whether to use residual connection (default: True).
+    """
+
+    def __init__(self, in_dim, out_dim, hidden_dim, out_dim1, use_residual=True):
+        super().__init__()
+        if use_residual:
+            assert in_dim == out_dim
+        self.layernorm = nn.LayerNorm(in_dim)
+        self.fc1 = nn.Linear(in_dim, hidden_dim)
+        self.fc2 = nn.Linear(hidden_dim, out_dim)
+        self.fc3 = nn.Linear(out_dim, out_dim1)
+        self.use_residual = use_residual
+        self.act_fn = nn.GELU()
+
+    def forward(self, x):
+        """
+        Forward pass for ByT5Mapper.
+
+        Args:
+            x (Tensor): Input tensor of shape (..., in_dim).
+
+        Returns:
+            Tensor: Output tensor of shape (..., out_dim1).
+        """
+        residual = x
+        x = self.layernorm(x)
+        x = self.fc1(x)
+        x = self.act_fn(x)
+        x = self.fc2(x)
+        x2 = self.act_fn(x)
+        x2 = self.fc3(x2)
+        if self.use_residual:
+            x2 = x2 + residual
+        return x2

hyimage/models/vae/__init__.py

@@ -0,0 +1,29 @@
+import torch
+from pathlib import Path
+from hyimage.common.constants import PRECISION_TO_TYPE
+from .hunyuanimage_vae import HunyuanVAE2D
+
+def load_vae(device, vae_path: str = None, vae_precision: str = None):
+    config = HunyuanVAE2D.load_config(vae_path)
+    vae = HunyuanVAE2D.from_config(config)
+
+    if Path(vae_path).exists():
+        ckpt = torch.load(Path(vae_path) / "pytorch_model.ckpt", map_location='cpu')
+        if "state_dict" in ckpt:
+            ckpt = ckpt["state_dict"]
+        vae_ckpt = {}
+        for k, v in ckpt.items():
+            if k.startswith("vae."):
+                vae_ckpt[k.replace("vae.", "")] = v
+        vae.load_state_dict(vae_ckpt)
+
+    if vae_precision is not None:
+        vae = vae.to(dtype=PRECISION_TO_TYPE[vae_precision])
+
+    vae.requires_grad_(False)
+
+    if device is not None:
+        vae = vae.to(device)
+
+    vae.eval()
+    return vae

hyimage/models/vae/hunyuanimage_vae.py

@@ -0,0 +1,779 @@
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import numpy as np
+import torch
+from diffusers.configuration_utils import ConfigMixin
+from diffusers.configuration_utils import register_to_config
+from diffusers.models.modeling_outputs import AutoencoderKLOutput
+from diffusers.models.modeling_utils import ModelMixin
+from diffusers.utils import BaseOutput
+from diffusers.utils.torch_utils import randn_tensor
+from einops import rearrange
+from torch import Tensor, nn
+from torch.nn import Conv2d
+
+
+class DiagonalGaussianDistribution:
+    def __init__(self, parameters: torch.Tensor, deterministic: bool = False):
+        if parameters.ndim == 3:
+            dim = 2  # (B, L, C)
+        elif parameters.ndim == 5 or parameters.ndim == 4:
+            dim = 1  # (B, C, T, H, W) / (B, C, H, W)
+        else:
+            raise NotImplementedError
+        self.parameters = parameters
+        self.mean, self.logvar = torch.chunk(parameters, 2, dim=dim)
+        self.logvar = torch.clamp(self.logvar, -30.0, 20.0)
+        self.deterministic = deterministic
+        self.std = torch.exp(0.5 * self.logvar)
+        self.var = torch.exp(self.logvar)
+        if self.deterministic:
+            zero_tensor = torch.zeros_like(self.mean, device=self.parameters.device, dtype=self.parameters.dtype)
+            self.var = zero_tensor
+            self.std = zero_tensor
+
+    def sample(self, generator: Optional[torch.Generator] = None) -> torch.FloatTensor:
+        sample = randn_tensor(
+            self.mean.shape,
+            generator=generator,
+            device=self.parameters.device,
+            dtype=self.parameters.dtype,
+        )
+        return self.mean + self.std * sample
+
+    def kl(self, other: Optional["DiagonalGaussianDistribution"] = None) -> torch.Tensor:
+        if self.deterministic:
+            return torch.tensor([0.0], device=self.parameters.device, dtype=self.parameters.dtype)
+        reduce_dim = list(range(1, self.mean.ndim))
+        if other is None:
+            return 0.5 * torch.sum(
+                self.mean.pow(2) + self.var - 1.0 - self.logvar,
+                dim=reduce_dim,
+            )
+        else:
+            return 0.5 * torch.sum(
+                (self.mean - other.mean).pow(2) / other.var
+                + self.var / other.var
+                - 1.0
+                - self.logvar
+                + other.logvar,
+                dim=reduce_dim,
+            )
+
+    def nll(self, sample: torch.Tensor, dims: Tuple[int, ...] = (1, 2, 3)) -> torch.Tensor:
+        if self.deterministic:
+            return torch.tensor([0.0], device=self.parameters.device, dtype=self.parameters.dtype)
+        logtwopi = np.log(2.0 * np.pi)
+        return 0.5 * torch.sum(
+            logtwopi + self.logvar + (sample - self.mean).pow(2) / self.var,
+            dim=dims,
+        )
+
+    def mode(self) -> torch.Tensor:
+        return self.mean
+
+
+@dataclass
+class DecoderOutput(BaseOutput):
+    """Output of the decoder with sample and optional posterior distribution."""
+    sample: torch.FloatTensor
+    posterior: Optional[DiagonalGaussianDistribution] = None
+
+
+def swish(x: Tensor) -> Tensor:
+    """Swish activation function: x * sigmoid(x)."""
+    return x * torch.sigmoid(x)
+
+
+def forward_with_checkpointing(module, *inputs, use_checkpointing=False):
+    """
+    Forward pass with optional gradient checkpointing for memory efficiency.
+
+    Parameters
+    ----------
+    module : nn.Module
+        The module to run.
+    *inputs : Tensor
+        Inputs to the module.
+    use_checkpointing : bool
+        Whether to use gradient checkpointing.
+    """
+    def create_custom_forward(module):
+        def custom_forward(*inputs):
+            return module(*inputs)
+        return custom_forward
+
+    if use_checkpointing:
+        return torch.utils.checkpoint.checkpoint(create_custom_forward(module), *inputs, use_reentrant=False)
+    else:
+        return module(*inputs)
+
+
+class AttnBlock(nn.Module):
+    """Self-attention block for 3D tensors."""
+
+    def __init__(self, in_channels: int):
+        super().__init__()
+        self.in_channels = in_channels
+        self.norm = nn.GroupNorm(num_groups=32, num_channels=in_channels, eps=1e-6, affine=True)
+        self.q = Conv2d(in_channels, in_channels, kernel_size=1)
+        self.k = Conv2d(in_channels, in_channels, kernel_size=1)
+        self.v = Conv2d(in_channels, in_channels, kernel_size=1)
+        self.proj_out = Conv2d(in_channels, in_channels, kernel_size=1)
+
+    def attention(self, x: Tensor) -> Tensor:
+        x = self.norm(x)
+        q = self.q(x)
+        k = self.k(x)
+        v = self.v(x)
+
+        b, c, h, w = q.shape
+        q = rearrange(q, "b c h w -> b (h w) c").contiguous()
+        k = rearrange(k, "b c h w -> b (h w) c").contiguous()
+        v = rearrange(v, "b c h w -> b (h w) c").contiguous()
+
+        x = nn.functional.scaled_dot_product_attention(q, k, v)
+        return rearrange(x, "b (h w) c -> b c h w", h=h, w=w, c=c, b=b)
+
+    def forward(self, x: Tensor) -> Tensor:
+        return x + self.proj_out(self.attention(x))
+
+
+class ResnetBlock(nn.Module):
+    """
+    Residual block with two convolutions and optional channel change.
+
+    Parameters
+    ----------
+    in_channels : int
+        Number of input channels.
+    out_channels : int
+        Number of output channels.
+    """
+
+    def __init__(self, in_channels: int, out_channels: int):
+        super().__init__()
+        self.in_channels = in_channels
+        out_channels = in_channels if out_channels is None else out_channels
+        self.out_channels = out_channels
+
+        self.norm1 = nn.GroupNorm(num_groups=32, num_channels=in_channels, eps=1e-6, affine=True)
+        self.conv1 = Conv2d(in_channels, out_channels, kernel_size=3, stride=1, padding=1)
+        self.norm2 = nn.GroupNorm(num_groups=32, num_channels=out_channels, eps=1e-6, affine=True)
+        self.conv2 = Conv2d(out_channels, out_channels, kernel_size=3, stride=1, padding=1)
+
+        if self.in_channels != self.out_channels:
+            self.nin_shortcut = Conv2d(in_channels, out_channels, kernel_size=1, stride=1, padding=0)
+
+    def forward(self, x: Tensor) -> Tensor:
+        h = x
+        h = self.norm1(h)
+        h = swish(h)
+        h = self.conv1(h)
+        h = self.norm2(h)
+        h = swish(h)
+        h = self.conv2(h)
+
+        if self.in_channels != self.out_channels:
+            x = self.nin_shortcut(x)
+        return x + h
+
+
+class Downsample(nn.Module):
+    """
+    Downsampling block for spatial reduction.
+
+    Parameters
+    ----------
+    in_channels : int
+        Number of input channels.
+    out_channels : int
+        Number of output channels.
+    """
+
+    def __init__(self, in_channels: int, out_channels: int):
+        super().__init__()
+        factor = 4
+        assert out_channels % factor == 0
+
+        self.conv = Conv2d(in_channels, out_channels // factor, kernel_size=3, stride=1, padding=1)
+        self.group_size = factor * in_channels // out_channels
+
+    def forward(self, x: Tensor) -> Tensor:
+        h = self.conv(x)
+        h = rearrange(h, "b c (h r1) (w r2) -> b (r1 r2 c) h w", r1=2, r2=2)
+        shortcut = rearrange(x, "b c (h r1) (w r2) -> b (r1 r2 c) h w", r1=2, r2=2)
+
+        B, C, H, W = shortcut.shape
+        shortcut = shortcut.view(B, h.shape[1], self.group_size, H, W).mean(dim=2)
+        return h + shortcut
+
+
+class Upsample(nn.Module):
+    """
+    Upsampling block for spatial expansion.
+
+    Parameters
+    ----------
+    in_channels : int
+        Number of input channels.
+    out_channels : int
+        Number of output channels.
+    """
+
+    def __init__(self, in_channels: int, out_channels: int):
+        super().__init__()
+        factor = 4
+        self.conv = Conv2d(in_channels, out_channels * factor, kernel_size=3, stride=1, padding=1)
+        self.repeats = factor * out_channels // in_channels
+
+    def forward(self, x: Tensor) -> Tensor:
+        h = self.conv(x)
+        h = rearrange(h, "b (r1 r2 c) h w -> b c (h r1) (w r2)", r1=2, r2=2)
+        shortcut = x.repeat_interleave(repeats=self.repeats, dim=1)
+        shortcut = rearrange(shortcut, "b (r1 r2 c) h w -> b c (h r1) (w r2)", r1=2, r2=2)
+        return h + shortcut
+
+
+class Encoder(nn.Module):
+    """
+    Encoder network that compresses input to latent representation.
+
+    Parameters
+    ----------
+    in_channels : int
+        Number of input channels.
+    z_channels : int
+        Number of latent channels.
+    block_out_channels : Tuple[int, ...]
+        Output channels for each block.
+    num_res_blocks : int
+        Number of residual blocks per block.
+    ffactor_spatial : int
+        Spatial downsampling factor.
+    downsample_match_channel : bool
+        Whether to match channels during downsampling.
+    """
+
+    def __init__(
+        self,
+        in_channels: int,
+        z_channels: int,
+        block_out_channels: Tuple[int, ...],
+        num_res_blocks: int,
+        ffactor_spatial: int,
+        downsample_match_channel: bool = True,
+    ):
+        super().__init__()
+        assert block_out_channels[-1] % (2 * z_channels) == 0
+
+        self.z_channels = z_channels
+        self.block_out_channels = block_out_channels
+        self.num_res_blocks = num_res_blocks
+
+        self.conv_in = Conv2d(in_channels, block_out_channels[0], kernel_size=3, stride=1, padding=1)
+
+        self.down = nn.ModuleList()
+        block_in = block_out_channels[0]
+
+        for i_level, ch in enumerate(block_out_channels):
+            block = nn.ModuleList()
+            block_out = ch
+
+            for _ in range(self.num_res_blocks):
+                block.append(ResnetBlock(in_channels=block_in, out_channels=block_out))
+                block_in = block_out
+
+            down = nn.Module()
+            down.block = block
+
+            add_spatial_downsample = bool(i_level < np.log2(ffactor_spatial))
+
+            if add_spatial_downsample:
+                assert i_level < len(block_out_channels) - 1
+                block_out = block_out_channels[i_level + 1] if downsample_match_channel else block_in
+                down.downsample = Downsample(block_in, block_out)
+                block_in = block_out
+
+            self.down.append(down)
+
+        # Middle blocks with attention
+        self.mid = nn.Module()
+        self.mid.block_1 = ResnetBlock(in_channels=block_in, out_channels=block_in)
+        self.mid.attn_1 = AttnBlock(block_in)
+        self.mid.block_2 = ResnetBlock(in_channels=block_in, out_channels=block_in)
+
+        # Output layers
+        self.norm_out = nn.GroupNorm(num_groups=32, num_channels=block_in, eps=1e-6, affine=True)
+        self.conv_out = Conv2d(block_in, 2 * z_channels, kernel_size=3, stride=1, padding=1)
+
+        self.gradient_checkpointing = False
+
+    def forward(self, x: Tensor) -> Tensor:
+        use_checkpointing = bool(self.training and self.gradient_checkpointing)
+
+        # Downsampling
+        h = self.conv_in(x)
+        for i_level in range(len(self.block_out_channels)):
+            for i_block in range(self.num_res_blocks):
+                h = forward_with_checkpointing(
+                    self.down[i_level].block[i_block], h, use_checkpointing=use_checkpointing
+                )
+            if hasattr(self.down[i_level], "downsample"):
+                h = forward_with_checkpointing(self.down[i_level].downsample, h, use_checkpointing=use_checkpointing)
+
+        # Middle processing
+        h = forward_with_checkpointing(self.mid.block_1, h, use_checkpointing=use_checkpointing)
+        h = forward_with_checkpointing(self.mid.attn_1, h, use_checkpointing=use_checkpointing)
+        h = forward_with_checkpointing(self.mid.block_2, h, use_checkpointing=use_checkpointing)
+
+        # Output with shortcut connection
+        group_size = self.block_out_channels[-1] // (2 * self.z_channels)
+        shortcut = rearrange(h, "b (c r) h w -> b c r h w", r=group_size).mean(dim=2)
+        h = self.norm_out(h)
+        h = swish(h)
+        h = self.conv_out(h)
+        h += shortcut
+        return h
+
+
+class Decoder(nn.Module):
+    """
+    Decoder network that reconstructs output from latent representation.
+
+    Parameters
+    ----------
+    z_channels : int
+        Number of latent channels.
+    out_channels : int
+        Number of output channels.
+    block_out_channels : Tuple[int, ...]
+        Output channels for each block.
+    num_res_blocks : int
+        Number of residual blocks per block.
+    ffactor_spatial : int
+        Spatial upsampling factor.
+    upsample_match_channel : bool
+        Whether to match channels during upsampling.
+    """
+
+    def __init__(
+        self,
+        z_channels: int,
+        out_channels: int,
+        block_out_channels: Tuple[int, ...],
+        num_res_blocks: int,
+        ffactor_spatial: int,
+        upsample_match_channel: bool = True,
+    ):
+        super().__init__()
+        assert block_out_channels[0] % z_channels == 0
+
+        self.z_channels = z_channels
+        self.block_out_channels = block_out_channels
+        self.num_res_blocks = num_res_blocks
+
+        block_in = block_out_channels[0]
+        self.conv_in = Conv2d(z_channels, block_in, kernel_size=3, stride=1, padding=1)
+
+        # Middle blocks with attention
+        self.mid = nn.Module()
+        self.mid.block_1 = ResnetBlock(in_channels=block_in, out_channels=block_in)
+        self.mid.attn_1 = AttnBlock(block_in)
+        self.mid.block_2 = ResnetBlock(in_channels=block_in, out_channels=block_in)
+
+        # Upsampling blocks
+        self.up = nn.ModuleList()
+        for i_level, ch in enumerate(block_out_channels):
+            block = nn.ModuleList()
+            block_out = ch
+
+            for _ in range(self.num_res_blocks + 1):
+                block.append(ResnetBlock(in_channels=block_in, out_channels=block_out))
+                block_in = block_out
+
+            up = nn.Module()
+            up.block = block
+
+            # Determine upsampling strategy
+            add_spatial_upsample = bool(i_level < np.log2(ffactor_spatial))
+
+            if add_spatial_upsample:
+                assert i_level < len(block_out_channels) - 1
+                block_out = block_out_channels[i_level + 1] if upsample_match_channel else block_in
+                up.upsample = Upsample(block_in, block_out)
+                block_in = block_out
+
+            self.up.append(up)
+
+        # Output layers
+        self.norm_out = nn.GroupNorm(num_groups=32, num_channels=block_in, eps=1e-6, affine=True)
+        self.conv_out = Conv2d(block_in, out_channels, kernel_size=3, stride=1, padding=1)
+
+        self.gradient_checkpointing = False
+
+    def forward(self, z: Tensor) -> Tensor:
+        use_checkpointing = bool(self.training and self.gradient_checkpointing)
+
+        repeats = self.block_out_channels[0] // self.z_channels
+        h = self.conv_in(z) + z.repeat_interleave(repeats=repeats, dim=1)
+
+        h = forward_with_checkpointing(self.mid.block_1, h, use_checkpointing=use_checkpointing)
+        h = forward_with_checkpointing(self.mid.attn_1, h, use_checkpointing=use_checkpointing)
+        h = forward_with_checkpointing(self.mid.block_2, h, use_checkpointing=use_checkpointing)
+
+        for i_level in range(len(self.block_out_channels)):
+            for i_block in range(self.num_res_blocks + 1):
+                h = forward_with_checkpointing(self.up[i_level].block[i_block], h, use_checkpointing=use_checkpointing)
+            if hasattr(self.up[i_level], "upsample"):
+                h = forward_with_checkpointing(self.up[i_level].upsample, h, use_checkpointing=use_checkpointing)
+
+        h = self.norm_out(h)
+        h = swish(h)
+        h = self.conv_out(h)
+        return h
+
+
+class HunyuanVAE2D(ModelMixin, ConfigMixin):
+    """
+    HunyuanVAE2D: A 2D image VAE model with spatial tiling support.
+
+    This model implements a variational autoencoder specifically designed for image data,
+    with support for memory-efficient processing through tiling strategies.
+    """
+
+    _supports_gradient_checkpointing = True
+
+    @register_to_config
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        latent_channels: int,
+        block_out_channels: Tuple[int, ...],
+        layers_per_block: int,
+        ffactor_spatial: int,
+        sample_size: int,
+        sample_tsize: int,
+        scaling_factor: float = None,
+        shift_factor: Optional[float] = None,
+        downsample_match_channel: bool = True,
+        upsample_match_channel: bool = True,
+        **kwargs,
+    ):
+        super().__init__()
+        self.ffactor_spatial = ffactor_spatial
+        self.scaling_factor = scaling_factor
+        self.shift_factor = shift_factor
+
+        self.encoder = Encoder(
+            in_channels=in_channels,
+            z_channels=latent_channels,
+            block_out_channels=block_out_channels,
+            num_res_blocks=layers_per_block,
+            ffactor_spatial=ffactor_spatial,
+            downsample_match_channel=downsample_match_channel,
+        )
+
+        self.decoder = Decoder(
+            z_channels=latent_channels,
+            out_channels=out_channels,
+            block_out_channels=list(reversed(block_out_channels)),
+            num_res_blocks=layers_per_block,
+            ffactor_spatial=ffactor_spatial,
+            upsample_match_channel=upsample_match_channel,
+        )
+
+        # Tiling and slicing configuration
+        self.use_slicing = False
+        self.use_spatial_tiling = False
+        self.use_tiling_during_training = False
+
+        # Tiling parameters
+        self.tile_sample_min_size = sample_size
+        self.tile_latent_min_size = sample_size // ffactor_spatial
+        self.tile_overlap_factor = 0.25
+
+    def _set_gradient_checkpointing(self, module, value=False):
+        """
+        Enable or disable gradient checkpointing for memory efficiency.
+
+        Parameters
+        ----------
+        module : nn.Module
+            The module to set.
+        value : bool
+            Whether to enable gradient checkpointing.
+        """
+        if isinstance(module, (Encoder, Decoder)):
+            module.gradient_checkpointing = value
+
+    def enable_spatial_tiling(self, use_tiling: bool = True):
+        """Enable or disable spatial tiling."""
+        self.use_spatial_tiling = use_tiling
+
+    def disable_spatial_tiling(self):
+        """Disable spatial tiling."""
+        self.use_spatial_tiling = False
+
+    def enable_tiling(self, use_tiling: bool = True):
+        """Enable or disable spatial tiling (alias for enable_spatial_tiling)."""
+        self.enable_spatial_tiling(use_tiling)
+
+    def disable_tiling(self):
+        """Disable spatial tiling (alias for disable_spatial_tiling)."""
+        self.disable_spatial_tiling()
+
+    def enable_slicing(self):
+        """Enable slicing for batch processing."""
+        self.use_slicing = True
+
+    def disable_slicing(self):
+        """Disable slicing for batch processing."""
+        self.use_slicing = False
+
+    def blend_h(self, a: torch.Tensor, b: torch.Tensor, blend_extent: int) -> torch.Tensor:
+        """
+        Blend two tensors horizontally with smooth transition.
+
+        Parameters
+        ----------
+        a : torch.Tensor
+            Left tensor.
+        b : torch.Tensor
+            Right tensor.
+        blend_extent : int
+            Number of columns to blend.
+        """
+        blend_extent = min(a.shape[-1], b.shape[-1], blend_extent)
+        for x in range(blend_extent):
+            b[:, :, :, :, x] = a[:, :, :, :, -blend_extent + x] * (1 - x / blend_extent) + b[:, :, :, :, x] * (
+                x / blend_extent
+            )
+        return b
+
+    def blend_v(self, a: torch.Tensor, b: torch.Tensor, blend_extent: int) -> torch.Tensor:
+        """
+        Blend two tensors vertically with smooth transition.
+
+        Parameters
+        ----------
+        a : torch.Tensor
+            Top tensor.
+        b : torch.Tensor
+            Bottom tensor.
+        blend_extent : int
+            Number of rows to blend.
+        """
+        blend_extent = min(a.shape[-2], b.shape[-2], blend_extent)
+        for y in range(blend_extent):
+            b[:, :, :, y, :] = a[:, :, :, -blend_extent + y, :] * (1 - y / blend_extent) + b[:, :, :, y, :] * (
+                y / blend_extent
+            )
+        return b
+
+    def spatial_tiled_encode(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Encode input using spatial tiling strategy.
+
+        Parameters
+        ----------
+        x : torch.Tensor
+            Input tensor of shape (B, C, T, H, W).
+        """
+        B, C, T, H, W = x.shape
+        overlap_size = int(self.tile_sample_min_size * (1 - self.tile_overlap_factor))
+        blend_extent = int(self.tile_latent_min_size * self.tile_overlap_factor)
+        row_limit = self.tile_latent_min_size - blend_extent
+
+        rows = []
+        for i in range(0, H, overlap_size):
+            row = []
+            for j in range(0, W, overlap_size):
+                tile = x[:, :, :, i : i + self.tile_sample_min_size, j : j + self.tile_sample_min_size]
+                tile = self.encoder(tile)
+                row.append(tile)
+            rows.append(row)
+
+        result_rows = []
+        for i, row in enumerate(rows):
+            result_row = []
+            for j, tile in enumerate(row):
+                if i > 0:
+                    tile = self.blend_v(rows[i - 1][j], tile, blend_extent)
+                if j > 0:
+                    tile = self.blend_h(row[j - 1], tile, blend_extent)
+                result_row.append(tile[:, :, :, :row_limit, :row_limit])
+            result_rows.append(torch.cat(result_row, dim=-1))
+
+        moments = torch.cat(result_rows, dim=-2)
+        return moments
+
+    def spatial_tiled_decode(self, z: torch.Tensor) -> torch.Tensor:
+        """
+        Decode latent using spatial tiling strategy.
+
+        Parameters
+        ----------
+        z : torch.Tensor
+            Latent tensor of shape (B, C, H, W).
+        """
+        B, C, H, W = z.shape
+        overlap_size = int(self.tile_latent_min_size * (1 - self.tile_overlap_factor))
+        blend_extent = int(self.tile_sample_min_size * self.tile_overlap_factor)
+        row_limit = self.tile_sample_min_size - blend_extent
+
+        rows = []
+        for i in range(0, H, overlap_size):
+            row = []
+            for j in range(0, W, overlap_size):
+                tile = z[:, :, :, i : i + self.tile_latent_min_size, j : j + self.tile_latent_min_size]
+                decoded = self.decoder(tile)
+                row.append(decoded)
+            rows.append(row)
+
+        result_rows = []
+        for i, row in enumerate(rows):
+            result_row = []
+            for j, tile in enumerate(row):
+                if i > 0:
+                    tile = self.blend_v(rows[i - 1][j], tile, blend_extent)
+                if j > 0:
+                    tile = self.blend_h(row[j - 1], tile, blend_extent)
+                result_row.append(tile[:, :, :, :row_limit, :row_limit])
+            result_rows.append(torch.cat(result_row, dim=-1))
+
+        dec = torch.cat(result_rows, dim=-2)
+        return dec
+
+    def encode(self, x: Tensor, return_dict: bool = True):
+        """
+        Encode input tensor to latent representation.
+
+        Parameters
+        ----------
+        x : Tensor
+            Input tensor.
+        return_dict : bool
+            Whether to return a dict.
+        """
+        original_ndim = x.ndim
+        if original_ndim == 5:
+            x = x.squeeze(2)
+
+        def _encode(x):
+            if self.use_spatial_tiling and (
+                x.shape[-1] > self.tile_sample_min_size or x.shape[-2] > self.tile_sample_min_size
+            ):
+                return self.spatial_tiled_encode(x)
+            return self.encoder(x)
+
+        # Process with or without slicing
+        if self.use_slicing and x.shape[0] > 1:
+            encoded_slices = [_encode(x_slice) for x_slice in x.split(1)]
+            h = torch.cat(encoded_slices)
+        else:
+            h = _encode(x)
+
+        if original_ndim == 5:
+            h = h.unsqueeze(2)
+
+        posterior = DiagonalGaussianDistribution(h)
+
+        if not return_dict:
+            return (posterior,)
+
+        return AutoencoderKLOutput(latent_dist=posterior)
+
+    def decode(self, z: Tensor, return_dict: bool = True, generator=None):
+        """
+        Decode latent representation to output tensor.
+
+        Parameters
+        ----------
+        z : Tensor
+            Latent tensor.
+        return_dict : bool
+            Whether to return a dict.
+        generator : unused
+            For compatibility.
+        """
+        original_ndim = z.ndim
+        if original_ndim == 5:
+            z = z.squeeze(2)
+
+        def _decode(z):
+            if self.use_spatial_tiling and (
+                z.shape[-1] > self.tile_latent_min_size or z.shape[-2] > self.tile_latent_min_size
+            ):
+                return self.spatial_tiled_decode(z)
+            return self.decoder(z)
+
+        if self.use_slicing and z.shape[0] > 1:
+            decoded_slices = [_decode(z_slice) for z_slice in z.split(1)]
+            decoded = torch.cat(decoded_slices)
+        else:
+            decoded = _decode(z)
+
+        if original_ndim == 5:
+            decoded = decoded.unsqueeze(2)
+
+        if not return_dict:
+            return (decoded,)
+
+        return DecoderOutput(sample=decoded)
+
+    def forward(
+        self,
+        sample: torch.Tensor,
+        sample_posterior: bool = False,
+        return_posterior: bool = True,
+        return_dict: bool = True,
+    ):
+        """
+        Forward pass through the VAE (Encode and Decode).
+
+        Parameters
+        ----------
+        sample : torch.Tensor
+            Input tensor.
+        sample_posterior : bool
+            Whether to sample from the posterior.
+        return_posterior : bool
+            Whether to return the posterior.
+        return_dict : bool
+            Whether to return a dict.
+        """
+        posterior = self.encode(sample).latent_dist
+        z = posterior.sample() if sample_posterior else posterior.mode()
+        dec = self.decode(z).sample
+
+        if return_dict:
+            return DecoderOutput(sample=dec, posterior=posterior)
+        else:
+            return (dec, posterior)
+
+    def load_state_dict(self, state_dict, strict=True):
+        """
+        Load state dict, handling possible 5D weight tensors.
+
+        Parameters
+        ----------
+        state_dict : dict
+            State dictionary.
+        strict : bool
+            Whether to strictly enforce that the keys in state_dict match the keys returned by this module's state_dict function.
+        """
+        converted_state_dict = {}
+
+        for key, value in state_dict.items():
+            if 'weight' in key:
+                if len(value.shape) == 5 and value.shape[2] == 1:
+                    converted_state_dict[key] = value.squeeze(2)
+                else:
+                    converted_state_dict[key] = value
+            else:
+                converted_state_dict[key] = value
+
+        return super().load_state_dict(converted_state_dict, strict=strict)

requirements.txt

@@ -0,0 +1,17 @@
+tqdm==4.67.1
+torch>=2.6.0
+einops==0.8.0
+loguru==0.7.3
+numpy==1.26.4
+pillow==11.3.0
+omegaconf>=2.3.0
+torchaudio==2.6.0
+diffusers>=0.32.0
+safetensors==0.4.5
+torchvision==0.21.0
+huggingface-hub==0.34.0
+transformers[accelerate,tiktoken]==4.56.0
+wheel
+setuptools
+modelscope
+huggingface_hub[cli]