Hugging Face's logo

Diffusers documentation

引导者

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

引导者

Guiders 是 Modular Diffusers 中的组件，用于控制生成过程中扩散过程的引导方式。它们实现了各种引导技术，以提升生成质量和可控性。

BaseGuidance

class diffusers.BaseGuidance

< >

( start: float = 0.0stop: float = 1.0enabled: bool = True )

提供实现引导技术骨架的基类。

cleanup_models

< >

( denoiser: torch.nn.Module )

在给定批次的数据处理完成后，清理用于 guidance 技术的模型。子类应重写此方法以实现特定的模型清理逻辑。它适用于移除在 prepare_models 期间添加的任何钩子或其他有状态修改。

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike | None = Nonesubfolder: str | None = Nonereturn_unused_kwargs = False**kwargs )

参数

  • pretrained_model_name_or_path (str 或 os.PathLike, 可选) — 可以是以下之一：
    • 一个字符串，即托管在 Hub 上的预训练模型的 model id（例如 google/ddpm-celebahq-256）。
    • 指向一个 目录（例如 ./my_model_directory）的路径，该目录包含使用 save_pretrained() 保存的 guider 配置。
  • subfolder (str, 可选) — 模型文件在 Hub 或本地更大的模型仓库中的子文件夹位置。
  • return_unused_kwargs (bool，可选，默认为 False) — 是否返回未被 Python 类使用的 kwargs。
  • cache_dir (str | os.PathLike, 可选) — 如果未使用标准缓存，则下载的预训练模型配置将被缓存到的目录路径。
  • force_download (bool，可选，默认为 False) — 是否强制（重新）下载模型权重和配置文件，如果存在缓存版本则覆盖它们。
  • proxies (dict[str, str]，可选) — 按协议或端点使用的代理服务器字典，例如 {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。每次请求都会使用这些代理。
  • output_loading_info(bool, 可选，默认为 False) — 是否同时返回一个包含缺失键、意外键和错误消息的字典。
  • local_files_only(bool, 可选，默认为 False) — 是否仅加载本地的模型权重和配置文件。如果设置为 True，则不会从 Hub 下载模型。
  • token (str 或 bool，可选) — 用于远程文件的 HTTP bearer 授权令牌。如果为 True，则使用由 diffusers-cli login 生成的令牌（存储在 ~/.huggingface 中）。
  • revision (str, 可选, 默认为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 id，或 Git 允许的任何标识符。

从本地目录或 Hub 仓库中预定义的 JSON 配置文件实例化一个 guider。

> 若要使用私有或 受控模型，请先通过 hf > auth login 登录。您还可以启用特殊的 > “离线模式”，以便在防火墙环境中使用此方法。

get_state

< >

( )

以字典形式返回引导技术的当前状态。状态变量将包含在 repr 方法中。返回值：dict[str, Any]：一个包含当前状态变量的字典，其中包括：

  • step：当前推理步骤
  • num_inference_steps: 推理总步数
  • timestep: 当前时间步张量
  • count_prepared: prepare_models 被调用的次数
  • enabled: 是否启用引导
  • num_conditions: 条件数量

新增

< >

( **kwargs )

参数

  • **kwargs — 用于在新实例中覆盖的配置参数。如果未提供 kwargs，则返回具有相同配置的精确副本。

创建此 guider 实例的副本，可选择修改配置参数。

示例：

# Create a CFG guider
guider = ClassifierFreeGuidance(guidance_scale=3.5)

# Create an exact copy
same_guider = guider.new()

# Create a copy with different start step, keeping other config the same
new_guider = guider.new(guidance_scale=5)

prepare_models

< >

( denoiser: torch.nn.Module )

为给定数据批次准备模型，以应用引导技术。子类应重写此方法，以实现特定的模型准备逻辑。

save_pretrained

< >

( save_directory: str | os.PathLikepush_to_hub: bool = False**kwargs )

参数

  • save_directory (str 或 os.PathLike) — 用于保存配置 JSON 文件的目录（如果该目录不存在，则会自动创建）。
  • push_to_hub (bool，可选，默认为 False) — 是否在保存模型后将其推送到 Hugging Face Hub。您可以使用 repo_id 指定要推送到的仓库（默认使用您命名空间中 save_directory 的名称）。
  • kwargs (dict[str, Any]，可选) — 传递给 push_to_hub() 方法的额外关键字参数。

将 guider 配置对象保存到目录中，以便使用 from_pretrained() 类方法重新加载。

ClassifierFreeGuidance

类 diffusers.ClassifierFreeGuidance

< >

( guidance_scale: float = 7.5guidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale (float，默认为 7.5) — 此 guider 在后处理阶段应用的 CFG 缩放值。值越高，提示词的条件约束越强，但可能会降低生成质量。典型取值范围：1.0-20.0。
  • guidance_rescale (float, defaults to 0.0) — Rescaling factor to prevent overexposure from high guidance scales. Based on Common Diffusion Noise Schedules and Sample Steps are Flawed. Range: 0.0 (no rescaling) to 1.0 (full rescaling).
  • use_original_formulation (bool，默认为 False) — 如果为 True，则使用论文中的原始 CFG 公式。如果为 False（默认值），则使用 Imagen 论文中的 diffusers 原生公式。
  • start (float，默认为 0.0) — CFG 开始生效的去噪步骤比例（0.0-1.0）。使用 > 0.0 可在早期去噪步骤中禁用 CFG。
  • stop (float，默认为 1.0) — 去噪步骤的比例（0.0-1.0），在此之后 CFG 停止。使用 < 1.0 可在后期去噪步骤中禁用 CFG。
  • enabled（bool，默认为 True）— 是否启用 CFG。设置为 False 可完全禁用 CFG（仅使用条件预测）。

为扩散模型实现无分类器引导（CFG）。

参考：https://huggingface.co/papers/2207.12598

CFG 通过在条件数据和无条件数据上联合训练模型，并在推理时结合两者的预测，从而提升生成质量和对提示词的遵循度。这使得我们可以在质量（高引导）和多样性（低引导）之间进行权衡。

两种 CFG 公式：

  1. 原始公式（来自论文）：
x_pred = x_cond + guidance_scale * (x_cond - x_uncond)
Moves conditional predictions further from unconditional ones.
  1. Diffusers 原生公式（默认，来自 Imagen 论文）：
x_pred = x_uncond + guidance_scale * (x_cond - x_uncond)
Moves unconditional predictions toward conditional ones, effectively suppressing negative features (e.g., "bad quality", "watermarks"). Equivalent in theory but more intuitive.

使用 use_original_formulation=True 切换到原始公式。

ClassifierFreeZeroStarGuidance

class diffusers.ClassifierFreeZeroStarGuidance

< >

( guidance_scale: float = 7.5zero_init_steps: int = 1guidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale (float，默认为 7.5) — 无分类器引导的缩放参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。
  • zero_init_steps (int，默认为 1) — 噪声预测被置零的推理步数（参见第 4.2 节）。
  • guidance_rescale (float, defaults to 0.0) — The rescale factor applied to the noise predictions. This is used to improve image quality and fix overexposure. Based on Section 3.4 from Common Diffusion Noise Schedules and Sample Steps are Flawed.
  • use_original_formulation (bool，默认为 False) — 是否使用论文中提出的 classifier-free guidance 的原始公式。默认情况下，我们使用 diffusers 原生实现，该实现已在代码库中存在较长时间。有关更多详细信息，请参阅 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]。
  • start (float，默认为 0.01) — 在总去噪步数中，引导开始生效的比例。
  • stop (float，默认为 0.2) — 在总去噪步数中，超过该比例后停止引导。

Classifier-free Zero（CFG-Zero）：https://huggingface.co/papers/2503.18886

这是 Classifier-Free Zero* 引导技术的实现，它是 classifier-free guidance 的一种变体。该技术提出在扩散过程的前几步中对噪声预测进行零初始化，并引入了用于噪声预测的最优重缩放因子，有助于提升生成图像的质量。

该论文的作者在推理步骤的前 4% 中建议设置零初始化。

SkipLayerGuidance

class diffusers.SkipLayerGuidance

< >

( guidance_scale: float = 7.5skip_layer_guidance_scale: float = 2.8skip_layer_guidance_start: float = 0.01skip_layer_guidance_stop: float = 0.2skip_layer_guidance_layers: int | list[int] | None = Noneskip_layer_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = Noneguidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale (float，默认为 7.5) — 无分类器引导的缩放参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。
  • skip_layer_guidance_scale (float，默认为 2.8) — skip layer guidance 的 scale 参数。较高的值可能会改善解剖结构和结构连贯性，但也可能导致过曝和饱和。
  • skip_layer_guidance_start (float，默认为 0.01) — 跳层引导开始的时间点，表示总去噪步数中经过的比例。
  • skip_layer_guidance_stop (float，默认值为 0.2) — 在总去噪步数中，经过该比例后停止 skip layer guidance 的阈值。
  • skip_layer_guidance_layers (int 或 list[int]，可选) — 应用 skip layer guidance 的层索引。可以是单个整数或整数列表。如果未提供，则必须提供 skip_layer_config。对于 Stable Diffusion 3.5 Medium，推荐值为 [7, 8, 9]。
  • skip_layer_config (LayerSkipConfig 或 list[LayerSkipConfig]，可选) — 用于 skip layer guidance 的配置。可以是单个 LayerSkipConfig，也可以是 LayerSkipConfig 的列表。如果未提供，则必须提供 skip_layer_guidance_layers。
  • guidance_rescale (float, defaults to 0.0) — The rescale factor applied to the noise predictions. This is used to improve image quality and fix overexposure. Based on Section 3.4 from Common Diffusion Noise Schedules and Sample Steps are Flawed.
  • use_original_formulation (bool，默认为 False) — 是否使用论文中提出的 classifier-free guidance 的原始公式。默认情况下，我们使用 diffusers 原生实现，该实现已在代码库中存在较长时间。有关更多详细信息，请参阅 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]。
  • start (float，默认为 0.01) — 在总去噪步数中，引导开始生效的比例。
  • stop (float，默认为 0.2) — 在总去噪步数中，超过该比例后停止引导。

跳过层引导（SLG）：https://github.com/Stability-AI/sd3.5

时空引导（STG）：https://huggingface.co/papers/2411.18664

SLG 由 StabilityAI 提出，用于提升生成图像的结构和解剖学一致性。其工作原理是：在去噪过程中，除了 CFG（[~guiders.classifier_free_guidance.ClassifierFreeGuidance]）中已使用的条件批次和无条件批次外，额外引入一个条件数据批次，并跳过其中指定 transformer 块的前向传播，然后根据“未跳过的条件预测”与“跳过的条件预测”之间的差异，对 CFG 预测进行缩放和平移。

SLG 背后的直觉可以理解为：将 CFG 预测的分布估计进一步推离条件分布估计的较差版本（因为跳过层相当于在条件预测中使用了一个较差版本的模型）。

STG 是一项改进和后续工作，它结合了 SLG、PAG 以及类似技术中用于提升视频扩散模型生成质量的思路。

延伸阅读：

skip_layer_guidance_scale、skip_layer_guidance_start 和 skip_layer_guidance_stop 的默认值采用 StabilityAI 针对 Stable Diffusion 3.5 Medium 给出的推荐值。

SmoothedEnergyGuidance

class diffusers.SmoothedEnergyGuidance

< >

( guidance_scale: float = 7.5seg_guidance_scale: float = 2.8seg_blur_sigma: float = 9999999.0seg_blur_threshold_inf: float = 9999.0seg_guidance_start: float = 0.0seg_guidance_stop: float = 1.0seg_guidance_layers: int | list[int] | None = Noneseg_guidance_config: SmoothedEnergyGuidanceConfig | list[SmoothedEnergyGuidanceConfig] = Noneguidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale (float，默认为 7.5) — 无分类器引导的缩放参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。
  • seg_guidance_scale (float，默认为 3.0) — 平滑能量引导的缩放参数。较高的值可能会改善解剖结构和结构的一致性，但也可能导致过曝和饱和。
  • seg_blur_sigma (float，默认值为 9999999.0) — 用于模糊注意力权重的程度。将该值设置为大于 9999.0 会导致无限模糊，即查询变为均匀分布。经验上，以指数方式控制该值效果良好。
  • seg_blur_threshold_inf (float，默认值为 9999.0) — 超过该阈值时，模糊被视为无限。
  • seg_guidance_start (float，默认为 0.0) — 在总去噪步数中，平滑能量引导开始生效的比例。
  • seg_guidance_stop (float，默认值为 1.0) — 在总去噪步数中，平滑能量引导停止所对应的比例。
  • seg_guidance_layers (int 或 list[int]，可选) — 要应用平滑能量引导的层索引。可以是单个整数或整数列表。如果未提供，则必须提供 seg_guidance_config。对于 Stable Diffusion 3.5 Medium，推荐值为 [7, 8, 9]。
  • seg_guidance_config (SmoothedEnergyGuidanceConfig 或 list[SmoothedEnergyGuidanceConfig]，可选) — 平滑能量层引导的配置。可以是单个 SmoothedEnergyGuidanceConfig，也可以是 SmoothedEnergyGuidanceConfig 的列表。如果未提供，则必须提供 seg_guidance_layers。
  • guidance_rescale (float, defaults to 0.0) — The rescale factor applied to the noise predictions. This is used to improve image quality and fix overexposure. Based on Section 3.4 from Common Diffusion Noise Schedules and Sample Steps are Flawed.
  • use_original_formulation (bool，默认为 False) — 是否使用论文中提出的 classifier-free guidance 的原始公式。默认情况下，我们使用 diffusers 原生实现，该实现已在代码库中存在较长时间。有关更多详细信息，请参阅 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]。
  • start (float，默认为 0.01) — 在总去噪步数中，引导开始生效的比例。
  • stop (float，默认为 0.2) — 在总去噪步数中，超过该比例后停止引导。

平滑能量引导（SEG）：https://huggingface.co/papers/2408.00760

目前，SEG 仅作为实验性原型功能提供支持，因此其实现方式可能会在未来被修改，且不会提前通知，也不保证可复现性。此实现基于以下假设：

  • 生成的图像为正方形（高度 == 宽度）
  • 该模型不会将不同的模态组合在一起（例如，文本和图像的潜在流不会像 Flux 那样被组合在一起）

PerturbedAttentionGuidance

class diffusers.PerturbedAttentionGuidance

< >

( guidance_scale: float = 7.5perturbed_guidance_scale: float = 2.8perturbed_guidance_start: float = 0.01perturbed_guidance_stop: float = 0.2perturbed_guidance_layers: int | list[int] | None = Noneperturbed_guidance_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = Noneguidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale (float，默认为 7.5) — 无分类器引导的缩放参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。
  • perturbed_guidance_scale（float，默认为 2.8）— 用于扰动注意力引导的缩放参数。
  • perturbed_guidance_start (float，默认为 0.01) — 在总去噪步数中，扰动注意力引导开始生效的比例。
  • perturbed_guidance_stop (float，默认为 0.2) — 在总去噪步数中，超过该比例后停止使用扰动注意力引导。
  • perturbed_guidance_layers（int 或 list[int]，可选）— 应用扰动注意力引导的层索引。可以是单个整数或整数列表。 如果未提供，则必须提供 perturbed_guidance_config。
  • perturbed_guidance_config (LayerSkipConfig 或 list[LayerSkipConfig]，可选) — 用于扰动注意力引导的配置。可以是单个 LayerSkipConfig 或 LayerSkipConfig 列表。如果未提供，则必须提供 perturbed_guidance_layers。
  • guidance_rescale (float, defaults to 0.0) — The rescale factor applied to the noise predictions. This is used to improve image quality and fix overexposure. Based on Section 3.4 from Common Diffusion Noise Schedules and Sample Steps are Flawed.
  • use_original_formulation (bool，默认为 False) — 是否使用论文中提出的 classifier-free guidance 的原始公式。默认情况下，我们使用 diffusers 原生实现，该实现已在代码库中存在较长时间。有关更多详细信息，请参阅 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]。
  • start (float，默认为 0.01) — 在总去噪步数中，引导开始生效的比例。
  • stop (float，默认为 0.2) — 在总去噪步数中，超过该比例后停止引导。

扰动注意力引导（PAG）：https://huggingface.co/papers/2403.17377

PAG 背后的直觉可以理解为：将 CFG 预测的分布估计进一步推离条件分布估计的较差版本。PAG 是最早引入“利用训练模型的较差版本来更好地引导自身去噪过程”这一思想的技巧之一。它通过为特定选定的层将分数矩阵替换为单位矩阵，来扰动潜在流的注意力分数。

延伸阅读：

PAG 的实现与 SkipLayerGuidance 类似，因为两者在配置参数和实现细节上存在重叠。

AdaptiveProjectedGuidance

class diffusers.AdaptiveProjectedGuidance

< >

( guidance_scale: float = 7.5adaptive_projected_guidance_momentum: float | None = Noneadaptive_projected_guidance_rescale: float = 15.0adaptive_projected_guidance_norm_dim: int | tuple[int, ...] | None = Noneeta: float = 1.0guidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale (float，默认为 7.5) — 无分类器引导的缩放参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。
  • adaptive_projected_guidance_momentum (float，默认为 None) — 自适应投影引导的动量参数。如果设置为 None，则禁用该功能。
  • adaptive_projected_guidance_rescale (float，默认值为 15.0) — 应用于噪声预测的重缩放因子。用于提升图像质量并修复
  • adaptive_projected_guidance_norm_dim (int 或 tuple[int]，可选) — 用于计算 APG 范数和投影的维度。如果省略，则使用所有非批次维度，以保持原始行为。
  • guidance_rescale (float, defaults to 0.0) — The rescale factor applied to the noise predictions. This is used to improve image quality and fix overexposure. Based on Section 3.4 from Common Diffusion Noise Schedules and Sample Steps are Flawed.
  • use_original_formulation (bool，默认为 False) — 是否使用论文中提出的 classifier-free guidance 的原始公式。默认情况下，我们使用 diffusers 原生实现，该实现已在代码库中存在较长时间。有关更多详细信息，请参阅 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]。
  • start (float，默认为 0.0) — 去噪总步数中，引导开始生效的比例。
  • stop (float，默认为 1.0) — 在总去噪步数中，超过该比例后停止引导。

自适应投影引导（APG）：https://huggingface.co/papers/2410.02416

AutoGuidance

class diffusers.AutoGuidance

< >

( guidance_scale: float = 7.5auto_guidance_layers: int | list[int] | None = Noneauto_guidance_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = Nonedropout: float | None = Noneguidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale (float，默认为 7.5) — 无分类器引导的缩放参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。
  • auto_guidance_layers (int 或 list[int]，可选) — 应用 skip layer guidance 的层索引。可以是单个整数或整数列表。如果未提供，则必须提供 skip_layer_config。
  • auto_guidance_config (LayerSkipConfig 或 list[LayerSkipConfig]，可选) — 用于 skip layer guidance 的配置。可以是单个 LayerSkipConfig，也可以是 LayerSkipConfig 的列表。如果未提供，则必须提供 skip_layer_guidance_layers。
  • dropout (float, 可选) — 在启用的跳过层上用于自动引导的 dropout 概率（通过 auto_guidance_layers 或 auto_guidance_config 指定）。如果未提供，dropout 概率将设置为 1.0。
  • guidance_rescale (float, defaults to 0.0) — The rescale factor applied to the noise predictions. This is used to improve image quality and fix overexposure. Based on Section 3.4 from Common Diffusion Noise Schedules and Sample Steps are Flawed.
  • use_original_formulation (bool，默认为 False) — 是否使用论文中提出的 classifier-free guidance 的原始公式。默认情况下，我们使用 diffusers 原生实现，该实现已在代码库中存在较长时间。有关更多详细信息，请参阅 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]。
  • start (float，默认为 0.0) — 去噪总步数中，引导开始生效的比例。
  • stop (float，默认为 1.0) — 在总去噪步数中，超过该比例后停止引导。

AutoGuidance：https://huggingface.co/papers/2406.02507

TangentialClassifierFreeGuidance

class diffusers.TangentialClassifierFreeGuidance

< >

( guidance_scale: float = 7.5guidance_rescale: float = 0.0use_original_formulation: bool = Falsestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale (float，默认为 7.5) — 无分类器引导的缩放参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。
  • guidance_rescale (float, defaults to 0.0) — The rescale factor applied to the noise predictions. This is used to improve image quality and fix overexposure. Based on Section 3.4 from Common Diffusion Noise Schedules and Sample Steps are Flawed.
  • use_original_formulation (bool，默认为 False) — 是否使用论文中提出的 classifier-free guidance 的原始公式。默认情况下，我们使用 diffusers 原生实现，该实现已在代码库中存在较长时间。有关更多详细信息，请参阅 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]。
  • start (float，默认为 0.0) — 去噪总步数中，引导开始生效的比例。
  • stop (float，默认为 1.0) — 在总去噪步数中，超过该比例后停止引导。

切向分类器自由引导（TCFG）：https://huggingface.co/papers/2503.18137

LTX2Guidance

class diffusers.LTX2Guidance

< >

( guidance_scale: float = 1.0stg_scale: float = 0.0modality_scale: float = 1.0guidance_rescale: float = 0.0spatio_temporal_guidance_blocks: list[int] | None = Nonestart: float = 0.0stop: float = 1.0enabled: bool = True )

参数

  • guidance_scale（float，默认为 1.0）— 该模态的 CFG 缩放系数。当值为 1.0 时，将完全跳过 CFG 处理。
  • stg_scale (float，默认为 0.0) — 该模态的时空引导尺度。当值为 0.0 时，将完全跳过 STG 处理。
  • modality_scale (float，默认为 1.0) — 该模态的模态隔离引导比例。当值为 1.0 时，将完全跳过该步骤。
  • guidance_rescale (float, defaults to 0.0) — Rescaling factor to prevent overexposure from high guidance scales. Based on Common Diffusion Noise Schedules and Sample Steps are Flawed. Range: 0.0 (no rescaling) to 1.0 (full rescaling).
  • spatio_temporal_guidance_blocks (list[int], 可选) — 在 STG 过程中需要扰动的 Transformer 块。该值的具体使用方式取决于去噪器块： LTX-2 在单次前向传播中扰动整个块，该前向传播为所有模态提供输入，因此它仅从视频引导器读取此值——在音频引导器上设置该值不会产生任何效果，而该音频引导器会通过其自身的 stg_scale 加入相同的 STG 前向传播。
  • start (float，默认为 0.0) — 去噪步骤（0.0-1.0）中开始应用引导的比例。
  • stop (float，默认为 1.0) — 去噪步骤的比例（0.0-1.0），在此之后停止引导。
  • enabled（bool，默认为 True） — 是否启用该 guider 的引导功能。当设置为 False 时，仅执行条件路径。

LTX-2.X 的单模态引导器。通过 delta 公式组合最多三个术语：

  • 无分类器引导（CFG），
  • 时空引导（STG），即额外执行一次前向传播，其中一组 transformer 块受到扰动，
  • 模态隔离引导，即额外执行一次禁用 A2V/V2A 交叉注意力的过程。

一个实例驱动一种模态，因此多模态检查点包含多个实例：LTX-2.X 将视频 guider 与 audio_guider 配对，每个实例各自持有其对应的 scales。最终的 guidance 估计值在调用方提供的空间中计算——LTX-2 去噪器在调用此函数前将 velocity->x0 进行转换，调用后再转换回来，因此 forward 基于 x0 预测进行操作。

与通过钩子（hooks）应用扰动的 SkipLayerGuidance 不同，LTX2Guidance 要求其非 CFG 扰动可通过模型的前向传播参数进行配置（即 LTX2VideoTransformer3DModel 中的 spatio_temporal_guidance_blocks 和 isolate_modalities）。调用去噪器块负责为每次前向传播设置这些标识符；使用示例请参见 LTX2LoopDenoiser。

Update on GitHub

←组件和配置 IP-Adapter→