online2311/MiniMax-H3-Image-PE-ComfyUI-NVFP4

MiniMax-H3-Image-PE NVFP4 for ComfyUI

这是 MiniMaxAI/MiniMax-H3-Image-PE 的 ComfyUI 文本编码器封装：把官方 modelopt NVFP4 四片权重转换成单文件 minimax_h3_image_pe_nvfp4.safetensors，并对齐 ComfyUI / comfy-kitchen 的 NVFP4 布局（FP4 高低 4 位对调，以及 weight_scale 的 cuBLAS tiled layout）。本仓库是衍生版本，沿用原模型的 MiniMax-H3-Image Community License Agreement，并受适用地域限制。许可全文见 LICENSE。

This repository provides a single-file ComfyUI text-encoder packaging of MiniMaxAI/MiniMax-H3-Image-PE. The source checkpoint is already NVFP4. This conversion does not re-quantize the weights; it only rearranges the official modelopt layout so ComfyUI can load the file with CLIPLoader (type=minimax) and TextGenerateV2.

License

MiniMax-H3-Image-PE is part of MiniMax-H3-Image and is released under the MiniMax-H3-Image Community License Agreement. MiniMax-H3-Image-PE is derived from Qwen3.8-27B, which is licensed under the Apache 2.0 License. The PE model remains subject to the MiniMax-H3-Image Community License Agreement.

This file is a Model Derivative (a layout conversion of the official weights). Redistribution is allowed only within the Applicable Territory, which is worldwide excluding the European Union, the United Kingdom, the Republic of Korea, and the United States of America. A copy of the Agreement and a NOTICE file must accompany distributions. Modified files must carry a prominent notice that they have been modified. You may not impose additional or different license terms on this derivative.

If the annualized revenue of you and/or your affiliates exceeds 1 Million USD, or you provide Hosted Service(s) to any Third Parties, you must obtain a separate, prior written authorization from MiniMax at https://platform.minimax.io/console/license. Commercial products or services that use MiniMax-H3-Image or MiniMax-H3-Image Works must prominently display "MiniMax-H3-Image" on the user interface. The "MiniMax-H3-Image" mark may be used only as reasonably necessary to describe and distribute the works, or as licensed for the encouraged attribution in Section III.3.

Key terms from the official license (quoted):

Solely within the Applicable Territory, we grant you a non-exclusive, non-transferable, royalty-free, limited license to use, reproduce, distribute, create derivative works (including Model Derivatives), and modify the Materials in accordance with the terms of this Agreement and the Acceptable Use Policy

“Excluded Territories” means the European Union, the United Kingdom, the Republic of Korea and the United States of America.

you may distribute or make available the MiniMax-H3-Image Works to Third Parties within the Applicable Territory; provided, that all of the following conditions are met: 1. You must provide a copy of this Agreement to all such Third Parties [...] 2. You must cause any modified files to carry prominent notices stating that you have modified such files; [...] 4. All distributions to Third Parties (other than through Hosted Service) must be accompanied by a “NOTICE” text file containing the following notice: “MiniMax-H3-Image is licensed under the MiniMax-H3-Image Community License Agreement, Copyright © 2026 MiniMax. All Rights Reserved.”

You shall obtain a separate, prior written authorization from MiniMax by sending a request through https://platform.minimax.io/console/license, if the Annualized Revenue of you and/or your affiliates exceeds 1 Million USD, or, you provide Hosted Service(s) to any Third Parties.

You may not use, reproduce, modify, distribute, or display the MiniMax-H3-Image Works or any of their Outputs or results outside the Applicable Territory.

The T2I PE Model is part of MiniMax-H3-Image and is accordingly subject to this Agreement for the avoidance of doubt.

This packaging is a modified file. The conversion changes packed FP4 nibble order and weight_scale layout, drops input_scale, and adds per-layer *.comfy_quant tags. It is not a drop-in replacement for the official Transformers / SGLang shards.

File

File	Size	SHA256
minimax_h3_image_pe_nvfp4.safetensors	17,916,141,691 bytes (16.69 GiB)	92a68898ecfcc95ce71639f3a2e282686089a75602ff3caaa7f354420de74f79

The safetensors file has no __metadata__ block. It contains 2,387 tensors, including 401 NVFP4 quantized layers. Tensor dtype counts:

dtype	tensors
U8	802
BF16	783
F32	401
F8_E4M3	401

Each quantized layer has weight (packed FP4 in U8), weight_scale (F8_E4M3 block scales), weight_scale_2 (F32 scalar), and a comfy_quant U8 tag {"format": "nvfp4", "full_precision_matrix_mult": true}. input_scale tensors from the official modelopt export are omitted, matching other ComfyUI NVFP4 text-encoder files.

This repository contains the converted weight file only. Tokenizer, chat template, and official PE prompts remain in MiniMaxAI/MiniMax-H3-Image-PE. ComfyUI's CLIPLoader with type=minimax uses the built-in MiniMax / Qwen 3.5 tokenizer and chat template.

Use in ComfyUI

1. Place the file in ComfyUI/models/text_encoders/.
2. Load it with CLIPLoader, set type to minimax.
3. Connect the CLIP output to TextGenerateV2 for prompt expansion.

Official PE request defaults, which are also a good starting point in ComfyUI, are temperature 1.0, top_p 0.95, top_k 20, and max_tokens 4096 including thinking and the final answer. Leave thinking enabled. The expected JSON fields are expanded_caption and aspect_ratio.

Measured results

These numbers are from a single expansion run of each prompt on a DGX Spark GB10 machine running ComfyUI v0.45.0, loading minimax_h3_image_pe_nvfp4.safetensors. Do not treat them as a benchmark across machines or ComfyUI versions.

• Chinese and English outputs were valid JSON, with fields expanded_caption and aspect_ratio.
• With thinking enabled: Chinese 376.86 s, English 428.33 s.
• Peak machine memory: 27.09 GiB.
• With thinking disabled, the output was empty. This matches observed model behavior. The official release recommends thinking enabled and max_tokens 4096.

Conversion method

Source: official MiniMaxAI/MiniMax-H3-Image-PE NVFP4 shards, produced with NVIDIA modelopt (quant_algo: NVFP4, group size 16). The four shards were merged into one ComfyUI text-encoder file.

The official packing is not the same as the ComfyUI / comfy-kitchen convention (verified against Comfy-Org/qwen3vl_32b_minimax_h3_nvfp4_awq):

• Packed FP4: modelopt stores the even element in the low nibble; ComfyUI uses high-nibble-first (hi_first=True). The conversion swaps the high and low 4 bits of each packed byte.
• weight_scale (F8_E4M3 block scales): modelopt stores a linear layout; ComfyUI expects the cuBLAS tiled layout produced by comfy.float.to_blocked. The conversion applies that blocked layout.
• weight_scale_2 (F32 scalar) is copied unchanged.
• A per-layer *.comfy_quant U8 tensor is added: {"format": "nvfp4", "full_precision_matrix_mult": true}.
• input_scale is dropped, and no safetensors __metadata__ is written.

This is a layout conversion of already-quantized NVFP4 weights, not a new quantization.

Limitations

• Thinking-off generation produced an empty string in the test above. Use thinking-on and a max_tokens budget of 4096 unless you have measured otherwise.
• The file is for ComfyUI. It is not a drop-in replacement for the official SGLang, Transformers, or Diffusers PE workflows, which expect the original modelopt shard layout.
• License rights are limited to the Applicable Territory. Use, distribution, and display outside that territory are not authorized by the Community License Agreement.
• Hosted services and uses above the revenue threshold require prior written authorization from MiniMax.
• This card reports only the measured runs listed above. Latency and memory will differ on other hardware.

Acknowledgments

Weights, prompts, and the PE task are from MiniMax: MiniMaxAI/MiniMax-H3-Image-PE, part of MiniMax-H3-Image. MiniMax-H3-Image-PE is derived from Qwen3.8-27B. The ComfyUI NVFP4 layout convention follows Comfy-Org's MiniMax H3 text-encoder packaging.