Diffusers documentation

UniPCMultistepScheduler

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

UniPCMultistepScheduler

UniPCMultistepScheduler 是一个专为扩散模型快速采样而设计的免训练框架。它由 Wenliang Zhao、Lujia Bai、Yongming Rao、Jie Zhou 和 Jiwen Lu 在 UniPC: A Unified Predictor-Corrector Framework for Fast Sampling of Diffusion Models 中提出。

它由校正器(UniC)和预测器(UniP)组成,二者共享统一的解析形式并支持任意阶数。 UniPC 在设计上是模型无关的,支持像素空间/潜在空间 DPM 的无条件/条件采样。它同样适用于噪声预测模型和数据预测模型。校正器 UniC 也可以应用于任何现成的求解器之后,以提高精度阶数。

该论文的摘要如下:

扩散概率模型(DPMs)在高分辨率图像合成方面展现了极具前景的能力。然而,由于需要对去噪网络进行多次评估,从预训练 DPM 中采样非常耗时,因此加速 DPM 的采样变得越来越重要。尽管在快速采样器设计方面取得了最新进展,但在许多偏好更少步数(例如 <10)的应用场景中,现有方法仍无法生成令人满意的图像。在本文中,我们开发了一种统一校正器(UniC),它可以应用于任何现有的 DPM 采样器之后,在不进行额外模型评估的情况下提高精度阶数,并作为副产品推导出了一个支持任意阶数的统一预测器(UniP)。结合 UniP 和 UniC,我们提出了一个用于 DPM 快速采样的统一预测器-校正器框架,称为 UniPC,它对任意阶数都具有统一的解析形式,并能显著地提高采样质量,尤其是在极少步数的情况下。我们通过大量实验评估了我们的方法,包括使用像素空间和潜在空间 DPM 的无条件采样和有条件采样。我们的 UniPC 仅需 10 次函数评估,即可在 CIFAR10(无条件)上实现 3.87 FID,在 ImageNet 256×256(有条件)上实现 7.51 FID。代码可在 this https URL 获取。

提示

建议将 solver_order 设置为 2 用于引导采样,将 solver_order=3 用于无条件采样。

支持来自 Imagen 的动态阈值处理。对于像素空间扩散模型,您可以同时设置 predict_x0=True 和 thresholding=True 以使用动态阈值处理。此阈值处理方法不适用于 Stable Diffusion 等潜在空间扩散模型。

UniPCMultistepScheduler

class diffusers.UniPCMultistepScheduler

< >

( num_train_timesteps: int = 1000beta_start: float = 0.0001beta_end: float = 0.02beta_schedule: str = 'linear'trained_betas: numpy.ndarray | list[float] | None = Nonesolver_order: int = 2prediction_type: typing.Literal['epsilon', 'sample', 'v_prediction', 'flow_prediction'] = 'epsilon'thresholding: bool = Falsedynamic_thresholding_ratio: float = 0.995sample_max_value: float = 1.0predict_x0: bool = Truesolver_type: typing.Literal['bh1', 'bh2'] = 'bh2'lower_order_final: bool = Truedisable_corrector: list[int] = []solver_p: SchedulerMixin = Noneuse_karras_sigmas: bool = Falseuse_exponential_sigmas: bool = Falseuse_beta_sigmas: bool = Falseuse_flow_sigmas: bool = Falseflow_shift: float = 1.0timestep_spacing: typing.Literal['linspace', 'leading', 'trailing'] = 'linspace'steps_offset: int = 0final_sigmas_type: typing.Literal['zero', 'sigma_min'] = 'zero'rescale_betas_zero_snr: bool = Falseuse_dynamic_shifting: bool = Falsetime_shift_type: typing.Literal['exponential'] = 'exponential'sigma_min: float | None = Nonesigma_max: bool | None = Noneshift_terminal: bool | None = None )

参数

  • num_train_timesteps (int,默认为 1000) — 用于训练模型的扩散步数。
  • beta_start (float,默认为 0.0001) — 推理的起始 beta 值。
  • beta_end (float,默认为 0.02) — 最终的 beta 值。
  • beta_schedule("linear"、"scaled_linear" 或 "squaredcos_cap_v2",默认为 "linear")—— beta 调度,即将 beta 范围映射为用于模型步进的一系列 beta 值。可选 linear、scaled_linear 或 squaredcos_cap_v2。
  • trained_betas (np.ndarray, 可选) — 直接传入 betas 数组到构造函数中,以绕过 beta_start 和 beta_end。
  • solver_order (int,默认为 2) — UniPC 的阶数,可以是任意正整数。由于 UniC 的存在,有效精度阶数为 solver_order + 1。 建议在有引导采样时使用 solver_order=2,在无引导采样时使用 solver_order=3。
  • prediction_type ("epsilon", "sample", "v_prediction", or "flow_prediction", defaults to "epsilon", optional) — Prediction type of the scheduler function; can be epsilon (predicts the noise of the diffusion process), sample (directly predicts the noisy sample), v_prediction(see section 2.4 of [Imagen Video](https://huggingface.co/papers/2210.02303) paper), orflow_prediction`.
  • thresholding (bool,默认为 False) — 是否使用“动态阈值”方法。此方法不适用于 Stable Diffusion 等潜在空间扩散模型。
  • dynamic_thresholding_ratio (float,默认为 0.995) — 动态阈值化方法的比例。仅在 thresholding=True 时有效。
  • sample_max_value (float,默认为 1.0) — 动态阈值化的阈值。仅在 thresholding=True 且 predict_x0=True 时有效。
  • predict_x0 (bool,默认为 True) — 是否对预测的 x0 使用更新算法。
  • solver_type("bh1" 或 "bh2",默认为 "bh2")— UniPC 的求解器类型。当步数 < 10 时,建议对无条件采样使用 bh1,否则使用 bh2。
  • lower_order_final (bool,默认值为 True) — 是否在最后几步使用低阶求解器。仅适用于少于 15 个推理步数的情况。这可以稳定 DPMSolver 在少于 15 步时的采样,尤其是在步数小于等于 10 时。
  • disable_corrector (list,默认值为 []) — 决定在哪些步骤禁用校正器,以缓解 epsilon_theta(x_t, c) 与 epsilon_theta(x_t^c, c) 之间的错位,这种错位可能会影响较大 guidance scale 下的收敛。通常在前几步中禁用校正器。
  • solver_p (SchedulerMixin,默认值为 None) — 如果指定了其他调度器,算法将变为 solver_p + UniC。
  • use_karras_sigmas (bool,可选,默认为 False) — 是否在采样过程的噪声调度中使用 Karras sigmas 来确定步长。如果为 True,则 sigmas 将根据噪声水平序列 {σi} 确定。
  • use_exponential_sigmas (bool,可选,默认为 False) — 在采样过程中,噪声调度的步长是否使用指数 sigmas。
  • use_beta_sigmas (bool, optional, defaults to False) — Whether to use beta sigmas for step sizes in the noise schedule during the sampling process. Refer to Beta Sampling is All You Need for more information.
  • use_flow_sigmas (bool,可选,默认为 False) — 在采样过程中,是否在噪声调度中使用 flow sigmas 作为步长。
  • timestep_spacing("linspace"、"leading" 或 "trailing",默认为 "linspace") — 时间步的缩放方式。更多信息请参阅 常见的扩散噪声调度和采样步骤存在缺陷 中的表 2。
  • steps_offset (int,默认为 0) — 添加到推理步数中的偏移量,某些模型系列需要此参数。
  • final_sigmas_type("zero" 或 "sigma_min",默认为 "zero")— 采样过程中噪声调度的最终 sigma 值。如果为 "sigma_min",则最终 sigma 与训练调度中的最后一个 sigma 相同。如果为 zero,则最终 sigma 设为 0。
  • rescale_betas_zero_snr (bool,默认为 False) — 是否重新缩放 betas 以实现零终端 SNR。这使模型能够生成非常明亮和非常暗的样本,而不是将其限制在中等亮度的样本上。与 --offset_noise 大致相关。

UniPCMultistepScheduler 是一个无需训练的框架,专为扩散模型的高效采样而设计。

该模型继承自 SchedulerMixin 和 ConfigMixin。有关该库为所有调度器实现的通用方法(例如加载和保存),请参阅父类文档。

add_noise

< >

( original_samples: Tensornoise: Tensortimesteps: IntTensor ) → torch.Tensor

参数

  • original_samples (torch.Tensor) — 未添加噪声的原始样本。
  • noise (torch.Tensor) — 要添加到样本中的噪声。
  • timesteps (torch.IntTensor) — 用于向样本添加噪声的时间步。

返回值

torch.Tensor

带噪声的样本。

根据指定时间步的噪声调度,向原始样本添加噪声。

convert_model_output

< >

( model_output: Tensor*argssample: Tensor = None**kwargs ) → torch.Tensor

参数

  • model_output (torch.Tensor) — 学习到的扩散模型的直接输出。
  • timestep (int) — 扩散链中的当前离散时间步。
  • sample (torch.Tensor) — 扩散过程生成的样本的当前实例。

返回值

torch.Tensor

转换后的模型输出。

将模型输出转换为 UniPC 算法所需的对应类型。

index_for_timestep

< >

( timestep: typing.Union[int, torch.Tensor]schedule_timesteps: typing.Optional[torch.Tensor] = None ) → int

参数

  • timestep (int 或 torch.Tensor) — 用于查找索引的时间步。
  • schedule_timesteps (torch.Tensor,可选) — 要搜索的时间步调度。如果为 None,则使用 self.timesteps。

返回值

int

时间步在调度器中的索引。

查找给定时间步在调度器中的索引。

multistep_uni_c_bh_update

< >

( this_model_output: Tensor*argslast_sample: Tensor = Nonethis_sample: Tensor = Noneorder: int = None**kwargs ) → torch.Tensor

参数

  • this_model_output (torch.Tensor) — 模型在 x_t 处的输出。
  • this_timestep (int) — 当前时间步 t。
  • last_sample (torch.Tensor) — 最后一个预测器之前的生成样本 x_{t-1}。
  • this_sample (torch.Tensor) — 最后一个预测器 x_{t} 之后生成的样本。
  • order (int) — 此步骤中 UniC-p 的 p。有效精度阶数应为 order + 1。

返回值

torch.Tensor

当前时间步的修正后样本张量。

UniC (B(h) 版本) 的一步。

multistep_uni_p_bh_update

< >

( model_output: Tensor*argssample: Tensor = Noneorder: int = None**kwargs ) → torch.Tensor

参数

  • model_output (torch.Tensor) — 当前时间步下,学习到的扩散模型的直接输出。
  • prev_timestep (int) — 扩散链中的上一个离散时间步。
  • sample (torch.Tensor) — 扩散过程生成的样本的当前实例。
  • order (int) — 当前时间步的 UniP 阶数(对应于 UniPC-p 中的 p)。

返回值

torch.Tensor

上一步时间步的样本张量。

UniP(B(h) 版本)的单步。或者,如果指定了,则使用 self.solver_p。

scale_model_input

< >

( sample: Tensor*args**kwargs ) → torch.Tensor

参数

  • sample (torch.Tensor) — 输入样本。

返回值

torch.Tensor

经过缩放的输入样本。

确保与那些需要根据当前时间步对去噪模型输入进行缩放的调度器之间的可互换性。

set_begin_index

< >

( begin_index: int = 0 )

参数

  • begin_index (int,默认为 0) — 调度器的起始索引。

设置调度器的起始索引。此函数应在推理之前从流水线中运行。

set_timesteps

< >

( num_inference_steps: int | None = Nonedevice: typing.Union[str, torch.device] = Nonesigmas: list[float] | None = Nonemu: bool | None = None )

参数

  • num_inference_steps (int) — 使用预训练模型生成样本时所用的扩散步数。
  • device (str 或 torch.device,可选) — 时间步应移动到的设备。如果为 None,则不移动时间步。
  • sigmas (List[float], 可选) — 用于每个扩散步骤的自定义 sigmas 值。如果为 None,则 sigmas 会自动计算。
  • mu (float, 可选) — 在使用指数时间偏移类型时,用于动态偏移的可选 mu 参数。

设置扩散链所使用的离散时间步(需在推理之前运行)。

步骤

< >

( model_output: Tensortimestep: typing.Union[int, torch.Tensor]sample: Tensorreturn_dict: bool = True ) → SchedulerOutput or tuple

参数

  • model_output (torch.Tensor) — 学习到的扩散模型的直接输出。
  • timestep (int 或 torch.Tensor) — 扩散链中的当前离散时间步。
  • sample (torch.Tensor) — 扩散过程生成的样本的当前实例。
  • return_dict (bool,默认为 True) — 是否返回 SchedulerOutput 或 tuple。

返回值

SchedulerOutput 或 tuple

If return_dict is True, SchedulerOutput is returned, otherwise a tuple is returned where the first element is the sample tensor.

通过逆转 SDE 来预测上一步时间步的样本。此函数使用多步 UniPC 传播样本。

stretch_shift_to_terminal

< >

( t: Tensor ) → torch.Tensor

参数

  • t (torch.Tensor) — 一个用于拉伸和偏移的时间步张量。

返回值

torch.Tensor

一个经过调整的 timesteps 张量,其最终值等于 self.config.shift_terminal。

拉伸并平移时间步调度,以确保其在配置的 shift_terminal 配置值处终止。

参考:https://github.com/Lightricks/LTX-Video/blob/a01a171f8fe3d99dce2728d60a73fecf4d4238ae/ltx_video/schedulers/rf.py#L51

time_shift

< >

( mu: floatsigma: floatt: Tensor ) → torch.Tensor

参数

  • mu (float) — 用于时间偏移的 mu 参数。
  • sigma (float) — 用于时间偏移的 sigma 参数。
  • t (torch.Tensor) — 输入的时间步。

返回值

torch.Tensor

时间偏移的时间步。

对 sigmas 应用时间偏移。

SchedulerOutput

class diffusers.schedulers.scheduling_utils.SchedulerOutput

< >

( prev_sample: Tensor )

参数

  • prev_sample(对于图像,形状为 (batch_size, num_channels, height, width) 的 torch.Tensor)— 前一时间步的已计算样本 (x_{t-1})。在去噪循环中,应将 prev_sample 用作下一个模型输入。

调度器 step 函数输出的基类。

Update on GitHub