Diffusers documentation

HunyuanImage2.1

Diffusers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

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

←Hunyuan-DiT Ideogram 4→

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