Diffusers documentation

AuraFlow

Diffusers

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

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

AuraFlow

AuraFlow 受 Stable Diffusion 3 的启发，是目前采用 Apache 2.0 许可证的最大文生图生成模型。该模型在 GenEval 基准测试中取得了最先进的结果。

它由 Fal 团队开发，更多详情可参见这篇博客文章。

AuraFlow 在消费级硬件设备上运行成本可能较高。不过，你可以执行一系列优化，使其运行得更快且更节省内存。有关更多详细信息，请参阅本节。

量化

量化通过以较低精度的数据类型存储模型权重，有助于降低超大模型的内存需求。不过，量化对视频质量的影响会因视频模型的不同而有所差异。

请参阅量化概述，以了解支持的量化后端以及如何选择支持您使用场景的量化后端。下面的示例演示了如何使用 bitsandbytes 加载量化的 AuraFlowPipeline 进行推理。

import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, AuraFlowTransformer2DModel, AuraFlowPipeline
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, T5EncoderModel

quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = T5EncoderModel.from_pretrained(
    "fal/AuraFlow",
    subfolder="text_encoder",
    quantization_config=quant_config,
    dtype=torch.float16,
)

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = AuraFlowTransformer2DModel.from_pretrained(
    "fal/AuraFlow",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.float16,
)

pipeline = AuraFlowPipeline.from_pretrained(
    "fal/AuraFlow",
    text_encoder=text_encoder_8bit,
    transformer=transformer_8bit,
    dtype=torch.float16,
    device_map="balanced",
)

prompt = "a tiny astronaut hatching from an egg on the moon"
image = pipeline(prompt).images[0]
image.save("auraflow.png")

也支持加载 GGUF 检查点：

import torch
from diffusers import (
    AuraFlowPipeline,
    GGUFQuantizationConfig,
    AuraFlowTransformer2DModel,
)

transformer = AuraFlowTransformer2DModel.from_single_file(
    "https://huggingface.co/city96/AuraFlow-v0.3-gguf/blob/main/aura_flow_0.3-Q2_K.gguf",
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

pipeline = AuraFlowPipeline.from_pretrained(
    "fal/AuraFlow-v0.3",
    transformer=transformer,
    dtype=torch.bfloat16,
)

prompt = "a cute pony in a field of flowers"
image = pipeline(prompt).images[0]
image.save("auraflow.png")

对 torch.compile() 的支持

AuraFlow 可以通过 torch.compile() 进行编译，以加速推理延迟，即使在不同分辨率下也是如此。首先，请按照此处的说明安装 PyTorch nightly。下面的代码片段展示了启用此功能所需的更改：

+ torch.fx.experimental._config.use_duck_shape = False
+ pipeline.transformer = torch.compile(
    pipeline.transformer, fullgraph=True, dynamic=True
)

将 use_duck_shape 指定为 False 会指示编译器是否应使用相同的符号变量来表示大小相同的输入。有关更多详细信息，请查看此评论。

这带来了从 100%（在低分辨率下）到 30%（在 1536x1536 分辨率下）的速度提升。

感谢 AstraliteHeart 帮助我们重写了 AuraFlowTransformer2DModel 类，使上述功能能够适用于不同的分辨率（PR）。

AuraFlowPipeline

class diffusers.AuraFlowPipeline

< source >

( tokenizer: T5Tokenizertext_encoder: UMT5EncoderModelvae: AutoencoderKLtransformer: AuraFlowTransformer2DModelscheduler: FlowMatchEulerDiscreteScheduler )

参数

tokenizer (T5TokenizerFast) — T5TokenizerFast 类的分词器，属于 T5Tokenizer。
text_encoder (T5EncoderModel) — 冻结的文本编码器。AuraFlow 使用 T5，具体为 EleutherAI/pile-t5-xl 变体。
vae (AutoencoderKL) — 变分自编码器（VAE）模型，用于将图像编码为潜在表示，以及从潜在表示解码回图像。
transformer (AuraFlowTransformer2DModel) — 用于对编码后的图像潜在变量进行去噪的条件 Transformer（MMDiT 和 DiT）架构。
scheduler (FlowMatchEulerDiscreteScheduler) — 用于与 transformer 配合，对编码后的图像潜变量进行去噪的调度器。

call

< source >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonenum_inference_steps: int = 50sigmas: list = Noneguidance_scale: float = 3.5num_images_per_prompt: int | None = 1height: int | None = 1024width: int | None = 1024generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 256output_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: list = ['latents'] ) → ImagePipelineOutput or tuple

参数

prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。在未使用引导时会被忽略（即当 guidance_scale 小于 1 时忽略）。
height (int，可选，默认为 self.transformer.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024 以获得最佳效果。
width (int，可选，默认为 self.transformer.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024 以获得最佳效果。
num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
sigmas (list[float]，可选) — 用于覆盖调度器时间步间隔策略的自定义 sigmas。如果传入了 sigmas，则 num_inference_steps 和 timesteps 必须为 None。
guidance_scale (float，可选，默认值为 5.0) — Classifier-Free Diffusion Guidance 中定义的引导尺度。guidance_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 guidance_scale > 1 来启用引导尺度。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
latents (torch.FloatTensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
prompt_embeds (torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
prompt_attention_mask (torch.Tensor，可选) — 为文本嵌入预生成的注意力掩码。
negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将根据 negative_prompt 输入参数生成。
negative_prompt_attention_mask (torch.Tensor, 可选) — 为负向文本嵌入预生成的注意力掩码。
output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 而不是普通元组。
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 属性中列出的变量。
max_sequence_length (int，默认为 256) — 与 prompt 配合使用的最大序列长度。

返回值

ImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ImagePipelineOutput；否则返回一个 tuple，其中第一个元素是包含生成图像的列表。

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

示例：

>>> import torch
>>> from diffusers import AuraFlowPipeline

>>> pipe = AuraFlowPipeline.from_pretrained("fal/AuraFlow", torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> image = pipe(prompt).images[0]
>>> image.save("aura_flow.png")

encode_prompt

< source >

( prompt: str | list[str]negative_prompt: str | list[str] = Nonedo_classifier_free_guidance: bool = Truenum_images_per_prompt: int = 1device: typing.Optional[torch.device] = 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 = 256lora_scale: float | None = None )

参数

prompt (str 或 list[str]，可选) — 要编码的提示
negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须改为传入 negative_prompt_embeds。在未使用引导时会被忽略（即当 guidance_scale 小于 1 时会被忽略）。
do_classifier_free_guidance (bool，可选，默认为 True) — 是否使用 classifier free guidance
num_images_per_prompt (int，可选，默认为 1) — 每个提示词应生成的图像数量
device — (torch.device，可选)：用于放置生成的嵌入向量的 torch 设备
prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
prompt_attention_mask (torch.Tensor，可选) — 为文本嵌入预生成的注意力掩码。
negative_prompt_embeds (torch.Tensor，可选) — 预生成的负向文本嵌入。
negative_prompt_attention_mask (torch.Tensor, 可选) — 为负向文本嵌入预生成的注意力掩码。
max_sequence_length (int，默认为 256) — 用于提示词的最大序列长度。
lora_scale (float, 可选) — 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。

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

Update on GitHub

←AnimateDiff Bria 3.2→

Diffusers

AuraFlow

量化

对 torch.compile() 的支持

AuraFlowPipeline

class diffusers.AuraFlowPipeline

__call__

encode_prompt

call