HunyuanImage2.1

HunyuanImage-2.1 是一个 17B 参数的文本生成图像模型，能够生成 2K（2048 x 2048）分辨率的图像

HunyuanImage-2.1 提供以下变体：

模型类型	模型 ID
HunyuanImage-2.1	hunyuanvideo-community/HunyuanImage-2.1-Diffusers
HunyuanImage-2.1-Distilled	hunyuanvideo-community/HunyuanImage-2.1-Distilled-Diffusers
HunyuanImage-2.1-Refiner	hunyuanvideo-community/HunyuanImage-2.1-Refiner-Diffusers

缓存还可以通过存储和复用中间输出来加速推理。

HunyuanImage-2.1

HunyuanImage-2.1 在去噪循环中应用了 Adaptive Projected Guidance (APG) 与 Classifier-Free Guidance (CFG) 的组合。HunyuanImagePipeline 包含一个 guider 组件（有关 Guider 的更多信息），并且在运行时不接受 guidance_scale 参数。若要更改与 guider 相关的参数（例如 guidance_scale），可以改为更新 guider 的配置。

import torch
from diffusers import HunyuanImagePipeline

pipe = HunyuanImagePipeline.from_pretrained(
    "hunyuanvideo-community/HunyuanImage-2.1-Diffusers", 
    dtype=torch.bfloat16
)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

您可以检查 guider 对象：

>>> pipe.guider
AdaptiveProjectedMixGuidance {
  "_class_name": "AdaptiveProjectedMixGuidance",
  "_diffusers_version": "0.36.0.dev0",
  "adaptive_projected_guidance_momentum": -0.5,
  "adaptive_projected_guidance_rescale": 10.0,
  "adaptive_projected_guidance_scale": 10.0,
  "adaptive_projected_guidance_start_step": 5,
  "enabled": true,
  "eta": 0.0,
  "guidance_rescale": 0.0,
  "guidance_scale": 3.5,
  "start": 0.0,
  "stop": 1.0,
  "use_original_formulation": false
}

State:
  step: None
  num_inference_steps: None
  timestep: None
  count_prepared: 0
  enabled: True
  num_conditions: 2
  momentum_buffer: None
  is_apg_enabled: False
  is_cfg_enabled: True

若要使用不同的配置更新 guider，请使用 new() 方法。例如，在保持其他所有默认 guidance 参数不变的情况下，生成一张 guidance_scale=5.0 的图像：

import torch
from diffusers import HunyuanImagePipeline

pipe = HunyuanImagePipeline.from_pretrained(
    "hunyuanvideo-community/HunyuanImage-2.1-Diffusers", 
    dtype=torch.bfloat16
)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Update the guider configuration
pipe.guider = pipe.guider.new(guidance_scale=5.0)

prompt = (
    "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."
)

image = pipe(
    prompt=prompt, 
    num_inference_steps=50, 
    height=2048, 
    width=2048,
).images[0]
image.save("image.png")

HunyuanImage-2.1-Distilled

使用蒸馏后的检查点时，请使用 distilled_guidance_scale，

import torch
from diffusers import HunyuanImagePipeline
pipe = HunyuanImagePipeline.from_pretrained("hunyuanvideo-community/HunyuanImage-2.1-Distilled-Diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = (
    "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."
)

out = pipe(
    prompt,
    num_inference_steps=8,
    distilled_guidance_scale=3.25,
    height=2048,
    width=2048,
    generator=generator,
).images[0]

HunyuanImagePipeline

类 diffusers.HunyuanImagePipeline

< source >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLHunyuanImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizertext_encoder_2: T5EncoderModeltokenizer_2: ByT5Tokenizertransformer: HunyuanImageTransformer2DModelguider: AdaptiveProjectedMixGuidance | None = Noneocr_guider: AdaptiveProjectedMixGuidance | None = None )

参数

transformer (HunyuanImageTransformer2DModel) — 用于对编码后的图像潜变量进行去噪的条件 Transformer (MMDiT) 架构。
scheduler (FlowMatchEulerDiscreteScheduler) — 用于与 transformer 配合，对编码后的图像潜变量进行去噪的调度器。
vae (AutoencoderKLHunyuanImage) — 变分自编码器（VAE）模型，用于将图像编码为潜在表示，以及从潜在表示解码为图像。
text_encoder（Qwen2.5-VL-7B-Instruct）—— Qwen2.5-VL-7B-Instruct，具体为 Qwen2.5-VL-7B-Instruct 变体。
tokenizer（Qwen2Tokenizer）— [Qwen2Tokenizer] 类的分词器。
text_encoder_2 (T5EncoderModel) — T5EncoderModel 变体。
tokenizer_2（ByT5Tokenizer）—— [ByT5Tokenizer] 类的分词器
guider (AdaptiveProjectedMixGuidance) — 用于引导图像生成的 [AdaptiveProjectedMixGuidance]。
ocr_guider (AdaptiveProjectedMixGuidance，可选) — 用于在需要文本渲染时引导图像生成的 [AdaptiveProjectedMixGuidance]。

用于文本到图像生成的 HunyuanImage 流水线。

call

< source >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50distilled_guidance_scale: float | None = 3.25sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1generator: torch.Generator | list[torch.Generator] | None = Nonelatents: torch.Tensor | None = Noneprompt_embeds: torch.Tensor | None = Noneprompt_embeds_mask: torch.Tensor | None = Nonenegative_prompt_embeds: torch.Tensor | None = Nonenegative_prompt_embeds_mask: torch.Tensor | None = Noneprompt_embeds_2: torch.Tensor | None = Noneprompt_embeds_mask_2: torch.Tensor | None = Nonenegative_prompt_embeds_2: torch.Tensor | None = Nonenegative_prompt_embeds_mask_2: torch.Tensor | None = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, Any] | None = Nonecallback_on_step_end: Callable[[int, int], None] | None = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents'] ) → ~pipelines.hunyuan_image.HunyuanImagePipelineOutput or tuple

参数

prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义且未提供 negative_prompt_embeds，则使用空的负面提示词。在未使用 guidance 时将被忽略。
height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
distilled_guidance_scale (float, 可选，默认为 None) — 用于 guidance distilled 模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过对噪声预测进行重新缩放来应用 guidance scale，而 guidance distilled 模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 distilled_guidance_scale > 1 来启用 guidance。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。对于 guidance distilled 模型，此参数是必需的。对于非 distilled 模型，此参数将被忽略。
num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
prompt_embeds_mask (torch.Tensor, 可选) — 预生成的文本嵌入掩码。可用于轻松调整文本输入，例如提示词加权。如果未提供，文本嵌入掩码将从 prompt 输入参数生成。
prompt_embeds_2 (torch.Tensor, 可选) — 为 ocr 预生成的文本嵌入。可用于轻松调整文本输入，例如提示词权重。如果未提供，将基于 prompt 输入参数生成 ocr 的文本嵌入。
prompt_embeds_mask_2 (torch.Tensor, 可选) — 为 ocr 预生成的文本嵌入掩码。可用于轻松调整文本输入，例如提示词加权。如果未提供，则会根据 prompt 输入参数生成 ocr 的文本嵌入掩码。
negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
negative_prompt_embeds_mask (torch.Tensor, 可选) — 预生成的负向文本嵌入掩码。可用于轻松调整文本输入，例如提示词加权。如果未提供，负向文本嵌入掩码将从 negative_prompt 输入参数生成。
negative_prompt_embeds_2 (torch.Tensor, 可选) — 为 ocr 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词权重。如果未提供，则会根据 negative_prompt 输入参数生成 ocr 的负向文本嵌入。
negative_prompt_embeds_mask_2 (torch.Tensor, 可选) — 为 ocr 预生成的负向文本嵌入掩码。可用于轻松调整文本输入，例如提示词权重。如果未提供，将基于 negative_prompt 输入参数生成 ocr 的负向文本嵌入掩码。
output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
callback_on_step_end_tensor_inputs (List，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传入。您只能包含流水线类的 ._callback_tensor_inputs 属性中列出的变量。

返回值

~pipelines.hunyuan_image.HunyuanImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.hunyuan_image.HunyuanImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from diffusers import HunyuanImagePipeline

>>> pipe = HunyuanImagePipeline.from_pretrained(
...     "hunyuanvideo-community/HunyuanImage-2.1-Diffusers", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, negative_prompt="", num_inference_steps=50).images[0]
>>> image.save("hunyuanimage.png")

encode_prompt

< source >

参数

prompt (str 或 list[str]，可选) — 要编码的提示
device — (torch.device)： torch 设备
batch_size (int) — 提示词的批处理大小，默认为 1
num_images_per_prompt (int) — 每个提示词应生成的图像数量
prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。如果未提供，将从 prompt 输入参数生成文本嵌入。
prompt_embeds_mask (torch.Tensor, 可选) — 预生成的文本掩码。如果未提供，则会根据 prompt 输入参数生成文本掩码。
prompt_embeds_2 (torch.Tensor, 可选) — 由 ByT5 预生成的字形文本嵌入。如果未提供，将使用 self.tokenizer_2 和 self.text_encoder_2 从 prompt 输入参数生成。
prompt_embeds_mask_2 (torch.Tensor, 可选) — 由 ByT5 预生成的字形文本掩码。如果未提供，将使用 self.tokenizer_2 和 self.text_encoder_2 从 prompt 输入参数生成。

HunyuanImageRefinerPipeline

class diffusers.HunyuanImageRefinerPipeline

< source >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLHunyuanImageRefinertext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: HunyuanImageTransformer2DModelguider: AdaptiveProjectedMixGuidance | None = None )

参数

transformer (HunyuanImageTransformer2DModel) — 用于对编码后的图像潜变量进行去噪的条件 Transformer (MMDiT) 架构。
scheduler (FlowMatchEulerDiscreteScheduler) — 用于与 transformer 配合，对编码后的图像潜变量进行去噪的调度器。
vae (AutoencoderKLHunyuanImageRefiner) — 变分自编码器（VAE）模型，用于将图像编码为潜在表示，以及从潜在表示解码为图像。
text_encoder（Qwen2.5-VL-7B-Instruct）—— Qwen2.5-VL-7B-Instruct，具体为 Qwen2.5-VL-7B-Instruct 变体。
tokenizer（Qwen2Tokenizer）— [Qwen2Tokenizer] 类的分词器。

用于文本到图像生成的 HunyuanImage 流水线。

call

< source >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonedistilled_guidance_scale: float | None = 3.25image: PipelineImageInput | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 4sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1generator: torch.Generator | list[torch.Generator] | None = Nonelatents: torch.Tensor | None = Noneprompt_embeds: torch.Tensor | None = Noneprompt_embeds_mask: torch.Tensor | None = Nonenegative_prompt_embeds: torch.Tensor | None = Nonenegative_prompt_embeds_mask: torch.Tensor | None = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, Any] | None = Nonecallback_on_step_end: Callable[[int, int], None] | None = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents'] ) → ~pipelines.hunyuan_image.HunyuanImagePipelineOutput or tuple

参数

prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词或提示词列表。如果未定义，将使用空的负面提示词。在未使用引导时会被忽略。
distilled_guidance_scale (float, 可选，默认为 None) — 用于 guidance distilled 模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过对噪声预测进行重新缩放来应用 guidance scale，而 guidance distilled 模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 distilled_guidance_scale > 1 来启用 guidance。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。对于 guidance distilled 模型，此参数是必需的。对于非 distilled 模型，此参数将被忽略。
image (PipelineImageInput，可选) — 需要精化的输入图像。
num_images_per_prompt（int，可选，默认为 1）—
height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
callback_on_step_end_tensor_inputs (List，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传入。您只能包含流水线类的 ._callback_tensor_inputs 属性中列出的变量。

返回值

~pipelines.hunyuan_image.HunyuanImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.hunyuan_image.HunyuanImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from diffusers import HunyuanImageRefinerPipeline

>>> pipe = HunyuanImageRefinerPipeline.from_pretrained(
...     "hunyuanvideo-community/HunyuanImage-2.1-Refiner-Diffusers", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> image = load_image("path/to/image.png")
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, image=image, num_inference_steps=4).images[0]
>>> image.save("hunyuanimage.png")

encode_prompt

< source >

参数

prompt (str 或 list[str]，可选) — 要编码的提示
device — (torch.device)： torch 设备
batch_size (int) — 提示词的批处理大小，默认为 1
num_images_per_prompt (int) — 每个提示词应生成的图像数量
prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。如果未提供，将从 prompt 输入参数生成文本嵌入。
prompt_embeds_mask (torch.Tensor, 可选) — 预生成的文本掩码。如果未提供，则会根据 prompt 输入参数生成文本掩码。
prompt_embeds_2 (torch.Tensor, 可选) — 由 ByT5 预生成的字形文本嵌入。如果未提供，将使用 self.tokenizer_2 和 self.text_encoder_2 从 prompt 输入参数生成。
prompt_embeds_mask_2 (torch.Tensor, 可选) — 由 ByT5 预生成的字形文本掩码。如果未提供，将使用 self.tokenizer_2 和 self.text_encoder_2 从 prompt 输入参数生成。

HunyuanImagePipelineOutput

class diffusers.pipelines.hunyuan_image.pipeline_output.HunyuanImagePipelineOutput

< source >

( images: list[PIL.Image.Image, numpy.ndarray] )

参数

images (list[PIL.Image.Image] 或 np.ndarray) — 长度为 batch_size 的去噪 PIL 图像列表，或形状为 (batch_size, height, width, num_channels) 的 numpy 数组。PIL 图像或 numpy 数组表示扩散流水线生成的去噪图像。

HunyuanImage 流水线的输出类。

Update on GitHub

Diffusers

HunyuanImage2.1

HunyuanImage-2.1

HunyuanImage-2.1-Distilled

HunyuanImagePipeline

类 diffusers.HunyuanImagePipeline

__call__

encode_prompt

HunyuanImageRefinerPipeline

class diffusers.HunyuanImageRefinerPipeline

__call__

encode_prompt

HunyuanImagePipelineOutput

class diffusers.pipelines.hunyuan_image.pipeline_output.HunyuanImagePipelineOutput

call

call