Hugging Face's logo

Diffusers documentation

Hunyuan-DiT

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Hunyuan-DiT

chinese elements understanding

来自腾讯混元的Hunyuan-DiT：一款具备细粒度中文理解能力的强大多分辨率扩散 Transformer。

该论文的摘要如下：

我们提出了 Hunyuan-DiT，这是一种能够精细理解中英文的文本生成图像扩散 Transformer。为了构建 Hunyuan-DiT，我们精心设计了 Transformer 结构、文本编码器和位置编码。我们还从零开始构建了一套完整的数据流水线，用于更新和评估数据，以支持模型的迭代优化。为了实现精细的语言理解，我们训练了一个多模态大语言模型来优化图像的文本描述。最终，Hunyuan-DiT 能够与用户进行多轮多模态对话，并根据上下文生成和优化图像。通过我们全面的人工评估协议，由 50 多位专业人工评估员参与，Hunyuan-DiT 在中文生成图像方面相较于其他开源模型达到了新的最先进水平。

您可以在 Tencent/HunyuanDiT 找到原始代码库，在 Tencent-Hunyuan 找到所有可用的检查点。

亮点：HunyuanDiT 支持中英文到图像生成，以及多分辨率生成。

HunyuanDiT 包含以下组件：

  • 它使用扩散 Transformer 作为骨干网络
  • 它结合了两种文本编码器：一个双语 CLIP 和一个多语言 T5 编码器

请务必参阅 调度器指南，了解如何探索调度器速度与质量之间的权衡，并查看 跨流水线复用组件 部分，了解如何高效地将相同组件加载到多个流水线中。

您可以通过将 HungyuanDiTPipeline 生成的图像传递给 SDXL refiner 模型，进一步提升生成质量。

优化

您可以使用 torch.compile 和前馈分块来优化流水线的运行时间和内存占用。要了解其他优化方法，请参阅 加速推理 和 减少内存使用 指南。

推理

使用 torch.compile 来降低推理延迟。

首先，加载 pipeline：

from diffusers import HunyuanDiTPipeline
import torch

pipeline = HunyuanDiTPipeline.from_pretrained(
	"Tencent-Hunyuan/HunyuanDiT-Diffusers", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"

然后，将流水线中 transformer 和 vae 组件的内存布局更改为 torch.channels-last：

pipeline.transformer.to(memory_format=torch.channels_last)
pipeline.vae.to(memory_format=torch.channels_last)

最后，编译组件并运行推理：

pipeline.transformer = torch.compile(pipeline.transformer, mode="max-autotune", fullgraph=True)
pipeline.vae.decode = torch.compile(pipeline.vae.decode, mode="max-autotune", fullgraph=True)

image = pipeline(prompt="一个宇航员在骑马").images[0]

在 80GB A100 机器上的 benchmark 结果如下：

With torch.compile(): Average inference time: 12.470 seconds.
Without torch.compile(): Average inference time: 20.570 seconds.

内存优化

通过以 8 位加载 T5 文本编码器，您可以在不到 6 GB 的 GPU 显存中运行该流水线。有关详细信息，请参阅此脚本。

此外，您可以使用 enable_forward_chunking() 方法来降低内存占用。前馈分块（feed-forward chunking）会在循环中依次运行 Transformer 块中的前馈层，而不是一次性全部执行。这让您可以在内存消耗和推理运行时间之间进行权衡。

+ pipeline.transformer.enable_forward_chunking(chunk_size=1, dim=1)

HunyuanDiTPipeline

class diffusers.HunyuanDiTPipeline

< >

( vae: AutoencoderKLtext_encoder: BertModeltokenizer: BertTokenizertransformer: HunyuanDiT2DModelscheduler: DDPMSchedulersafety_checker: StableDiffusionSafetyCheckerfeature_extractor: CLIPImageProcessorPilrequires_safety_checker: bool = Truetext_encoder_2: transformers.models.t5.modeling_t5.T5EncoderModel | None = Nonetokenizer_2: transformers.models.t5.tokenization_t5.T5Tokenizer | None = None )

参数

  • vae (AutoencoderKL) — 变分自编码器（VAE）模型，用于将图像编码为潜在表示，以及从潜在表示解码为图像。我们使用 sdxl-vae-fp16-fix。
  • text_encoder (~transformers.BertModel, ~transformers.CLIPTextModel | None) — 冻结的文本编码器（clip-vit-large-patch14）。 HunyuanDiT 使用经过微调的 [bilingual CLIP]。
  • tokenizer (~transformers.BertTokenizer, ~transformers.CLIPTokenizer | None) — 用于对文本进行分词的 BertTokenizer 或 CLIPTokenizer。
  • transformer (HunyuanDiT2DModel) — 腾讯混元设计的 HunyuanDiT 模型。
  • text_encoder_2 (T5EncoderModel) — mT5 嵌入器。具体而言，它是 ‘t5-v1_1-xxl’。
  • tokenizer_2 (T5Tokenizer) — mT5 嵌入器的分词器。
  • scheduler (DDPMScheduler) — 用于配合 HunyuanDiT 对编码后的图像潜在变量进行去噪的调度器。

用于使用 HunyuanDiT 进行英语/中文到图像生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关该库为所有流水线实现的通用方法（例如下载或保存、在特定设备上运行等），请参阅父类文档。

HunyuanDiT 使用两个文本编码器：mT5 和 [双语 CLIP](由我们自行微调)

__call__

< >

( prompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int | None = 50guidance_scale: float | None = 5.0negative_prompt: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1eta: float | None = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Noneprompt_attention_mask_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask_2: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truecallback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']guidance_rescale: float = 0.0original_size: tuple[int, int] | None = (1024, 1024)target_size: tuple[int, int] | None = Nonecrops_coords_top_left: tuple[int, int] = (0, 0)use_resolution_binning: bool = True ) → StableDiffusionPipelineOutput or tuple

参数

  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则需要传入 prompt_embeds。
  • height (int) — 生成图像的高度（以像素为单位）。
  • width (int) — 生成图像的宽度（以像素为单位）。
  • num_inference_steps (int，可选，默认值为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但推理速度会更慢。此参数受 strength 调节。
  • guidance_scale (float，可选，默认值为 7.5) — 较高的 guidance scale 值会促使模型生成与文本 prompt 紧密相关的图像，但代价是图像质量降低。当 guidance_scale > 1 时，guidance scale 生效。
  • negative_prompt (str 或 list[str]，可选) — 用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 negative_prompt_embeds。在未使用引导（guidance_scale < 1）时将被忽略。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • eta（float，可选，默认值为 0.0）— 对应 DDIM 论文中的参数 eta (η)。仅适用于 DDIMScheduler，在其他调度器中会被忽略。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 用于使生成过程确定性的 torch.Generator。
  • latents (torch.Tensor, 可选) — 预先生成的、从高斯分布中采样的含噪潜变量，用作图像生成的输入。可用于以不同的提示词微调同一生成过程。如果未提供，则使用提供的随机generator进行采样，生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入（提示词加权）。如果未提供，则从 prompt 输入参数生成文本嵌入。
  • prompt_embeds_2 (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入（提示词加权）。如果未提供，则从 prompt 输入参数生成文本嵌入。
  • negative_prompt_embeds (torch.Tensor，可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，negative_prompt_embeds 将根据 negative_prompt 输入参数生成。
  • negative_prompt_embeds_2 (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则根据 negative_prompt 输入参数生成 negative_prompt_embeds。
  • prompt_attention_mask (torch.Tensor, 可选) — 提示词的注意力掩码。当直接传入 prompt_embeds 时，此参数为必填项。
  • prompt_attention_mask_2 (torch.Tensor, 可选) — 提示词的注意力掩码。当直接传入 prompt_embeds_2 时，此项为必填。
  • negative_prompt_attention_mask (torch.Tensor, 可选) — 负面提示词的注意力掩码。当直接传入 negative_prompt_embeds 时，此参数为必填项。
  • negative_prompt_attention_mask_2（torch.Tensor，可选）— 负面提示词的注意力掩码。当直接传入 negative_prompt_embeds_2 时，此参数为必填项。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选 PIL.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 StableDiffusionPipelineOutput 而不是普通元组。
  • callback_on_step_end (Callable[[int, int], None], PipelineCallback, MultiPipelineCallbacks, 可选) — 在每个去噪步骤结束时调用的回调函数或回调函数列表。
  • callback_on_step_end_tensor_inputs (list[str]，可选) — 应传递给回调函数的张量输入列表。如果未定义，则所有张量输入都会被传递。
  • guidance_rescale (float, optional, defaults to 0.0) — Rescale the noise_cfg according to guidance_rescale. Based on findings of Common Diffusion Noise Schedules and Sample Steps are Flawed. See Section 3.4
  • original_size (tuple[int, int]，可选，默认为 (1024, 1024)) — 图像的原始尺寸。用于计算时间 ID。
  • target_size (tuple[int, int]，可选) — 图像的目标尺寸。用于计算时间 ID。
  • crops_coords_top_left (tuple[int, int]，可选，默认为 (0, 0)) — 裁剪区域的左上角坐标。用于计算时间 ID。
  • use_resolution_binning (bool，可选，默认为 True) — 是否使用分辨率分箱。如果为 True，输入分辨率将被映射到最接近的标准分辨率。支持的分辨率包括 1024x1024、1280x1280、1024x768、1152x864、1280x960、768x1024、864x1152、960x1280、1280x768 和 768x1280。建议将此参数设置为 True。

返回值

StableDiffusionPipelineOutput 或 tuple

如果 return_dict 为 True，则返回 StableDiffusionPipelineOutput；否则返回一个 tuple，其中第一个元素是包含生成图像的列表，第二个元素是 bool 列表，用于指示对应的生成图像是否包含“不适合工作场所”（nsfw）内容。

调用 pipeline 的 call 函数，使用 HunyuanDiT 进行生成。

示例：

>>> import torch
>>> from diffusers import HunyuanDiTPipeline

>>> pipe = HunyuanDiTPipeline.from_pretrained(
...     "Tencent-Hunyuan/HunyuanDiT-Diffusers", torch_dtype=torch.float16
... )
>>> pipe.to("cuda")

>>> # You may also use English prompt as HunyuanDiT supports both English and Chinese
>>> # prompt = "An astronaut riding a horse"
>>> prompt = "一个宇航员在骑马"
>>> image = pipe(prompt).images[0]

encode_prompt

< >

( prompt: strdevice: device = Nonedtype: dtype = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | None = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int | None = Nonetext_encoder_index: int = 0 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • device — (torch.device)： torch 设备
  • dtype (torch.dtype) — torch 数据类型
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • do_classifier_free_guidance (bool) — 是否使用 classifier free guidance
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。在未使用引导时会被忽略（即当 guidance_scale 小于 1 时忽略）。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • prompt_attention_mask (torch.Tensor, 可选) — 提示词的注意力掩码。当直接传入 prompt_embeds 时，此参数为必填项。
  • negative_prompt_attention_mask (torch.Tensor, 可选) — 负面提示词的注意力掩码。当直接传入 negative_prompt_embeds 时，此参数为必填项。
  • max_sequence_length (int，可选) — 用于提示词的最大序列长度。
  • text_encoder_index (int, 可选) — 要使用的文本编码器索引。0 表示 clip，1 表示 T5。

将提示词编码为文本编码器的隐藏状态。

Update on GitHub

←HiDream-I1 HunyuanImage2.1→