Diffusers documentation
Hunyuan-DiT
Hunyuan-DiT
来自腾讯混元的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
< source >( 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__
< source >( 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 toguidance_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
< source >( 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。
将提示词编码为文本编码器的隐藏状态。