diffusers/v0.43.0/zh/api/modular_diffusers/guiders.md

引导者

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

BaseGuidance[[diffusers.BaseGuidance]]

diffusers.BaseGuidance[[diffusers.BaseGuidance]]

diffusers.BaseGuidance(start: float = 0.0, stop: float = 1.0, enabled: bool = True)

源代码

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

cleanup_models[[diffusers.BaseGuidance.cleanup_models]]

cleanup_models(denoiser: torch.nn.Module)

源代码

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

from_pretrained[[diffusers.BaseGuidance.from_pretrained]]

from_pretrained(pretrained_model_name_or_path: str | os.PathLike | None = None, subfolder: str | None = None, return_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 承载者授权令牌。如果为 True，则使用由 diffusers-cli login 生成的令牌（存储在 ~/.huggingface 中）。

revision (str，可选，默认为 "main")：要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID，或 Git 允许的任何标识符。

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

> 若要使用私有或 受限模型，请先登录 使用 hf > auth login。您还可以启用特殊的 > "offline-mode"，以便在防火墙环境中使用此方法。

get_state[[diffusers.BaseGuidance.get_state]]

get_state()

源代码

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

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

新增[[diffusers.BaseGuidance.new]]

new(**kwargs)

源代码

参数：

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

返回值：

具有相同（或已更新）配置的新 guider 实例。

创建此 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[[diffusers.BaseGuidance.prepare_models]]

prepare_models(denoiser: torch.nn.Module)

源代码

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

save_pretrained[[diffusers.BaseGuidance.save_pretrained]]

save_pretrained(save_directory: str | os.PathLike, push_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]]

diffusers.ClassifierFreeGuidance[[diffusers.ClassifierFreeGuidance]]

diffusers.ClassifierFreeGuidance(guidance_scale: float = 7.5, guidance_rescale: float = 0.0, use_original_formulation: bool = False, start: float = 0.0, stop: float = 1.0, enabled: 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)：CFG 停止的去噪步数比例（0.0-1.0）。使用小于 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)
   

   使条件预测与无条件预测之间的差异更大。

2. Diffusers 原生公式（默认，来自 Imagen 论文）：

   x_pred = x_uncond + guidance_scale * (x_cond - x_uncond)
   

   将无条件预测向有条件预测移动，从而有效抑制负面特征（例如“质量差”、“水印”）。理论上等价，但更直观。

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

ClassifierFreeZeroStarGuidance[[diffusers.ClassifierFreeZeroStarGuidance]]

diffusers.ClassifierFreeZeroStarGuidance[[diffusers.ClassifierFreeZeroStarGuidance]]

diffusers.ClassifierFreeZeroStarGuidance(guidance_scale: float = 7.5, zero_init_steps: int = 1, guidance_rescale: float = 0.0, use_original_formulation: bool = False, start: float = 0.0, stop: float = 1.0, enabled: bool = True)

源代码

参数：

guidance_scale (float，默认值为 7.5)：分类器自由引导的 scale 参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。

zero_init_steps (int，默认为 1)：噪声预测被置零的推理步数（参见第 4.2 节）。

guidance_rescale (float，默认为 0.0)：应用于噪声预测的重缩放因子。用于提升图像质量并修复过曝问题。基于 常见的扩散噪声调度和采样步骤存在缺陷 中的第 3.4 节。

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[[diffusers.SkipLayerGuidance]]

diffusers.SkipLayerGuidance[[diffusers.SkipLayerGuidance]]

diffusers.SkipLayerGuidance(guidance_scale: float = 7.5, skip_layer_guidance_scale: float = 2.8, skip_layer_guidance_start: float = 0.01, skip_layer_guidance_stop: float = 0.2, skip_layer_guidance_layers: int | list[int] | None = None, skip_layer_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = None, guidance_rescale: float = 0.0, use_original_formulation: bool = False, start: float = 0.0, stop: float = 1.0, enabled: bool = True)

源代码

参数：

guidance_scale (float，默认值为 7.5)：分类器自由引导的 scale 参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。

skip_layer_guidance_scale (float，默认值为 2.8)：用于跳过层引导的缩放参数。较高的值可能会改善解剖结构和结构连贯性，但也可能导致过度曝光和饱和。

skip_layer_guidance_start (float，默认值为 0.01)：跳层引导开始的时间点，表示总去噪步数中经过的比例。

skip_layer_guidance_stop (float，默认为 0.2)：在总去噪步数中，超过该比例后跳过层引导将停止。

skip_layer_guidance_layers (int 或 list[int]，可选) : 要应用跳过层引导的层索引。可以是单个整数或整数列表。如果未提供，则必须提供 skip_layer_config。对于 Stable Diffusion 3.5 Medium，推荐值为 [7, 8, 9]。

skip_layer_config (LayerSkipConfig 或 list[LayerSkipConfig]，可选)：用于配置跳过层引导。可以是单个 LayerSkipConfig 或 LayerSkipConfig 列表。如果未提供，则必须提供 skip_layer_guidance_layers。

guidance_rescale (float，默认为 0.0)：应用于噪声预测的重缩放因子。用于提升图像质量并修复过曝问题。基于 常见的扩散噪声调度和采样步骤存在缺陷 中的第 3.4 节。

use_original_formulation (bool，默认为 False)：是否使用论文中提出的原始 classifier-free guidance 公式。默认情况下，我们使用 diffusers 原生实现，该实现已在代码库中存在较长时间。有关更多详细信息，请参阅 [~guiders.classifier_free_guidance.ClassifierFreeGuidance]。

start (float，默认为 0.01)：在总去噪步数中，引导开始生效的比例。

stop (float，默认为 0.2)：在总去噪步数中，引导停止所对应的比例。

Skip Layer Guidance (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[[diffusers.SmoothedEnergyGuidance]]

diffusers.SmoothedEnergyGuidance[[diffusers.SmoothedEnergyGuidance]]

diffusers.SmoothedEnergyGuidance(guidance_scale: float = 7.5, seg_guidance_scale: float = 2.8, seg_blur_sigma: float = 9999999.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] | None = None, seg_guidance_config: SmoothedEnergyGuidanceConfig | list[SmoothedEnergyGuidanceConfig] = None, guidance_rescale: float = 0.0, use_original_formulation: bool = False, start: float = 0.0, stop: float = 1.0, enabled: bool = True)

源代码

参数：

guidance_scale (float，默认值为 7.5)：分类器自由引导的 scale 参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。

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，默认为 0.0)：应用于噪声预测的重缩放因子。用于提升图像质量并修复过曝问题。基于 常见的扩散噪声调度和采样步骤存在缺陷 中的第 3.4 节。

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[[diffusers.PerturbedAttentionGuidance]]

diffusers.PerturbedAttentionGuidance[[diffusers.PerturbedAttentionGuidance]]

diffusers.PerturbedAttentionGuidance(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] | None = None, perturbed_guidance_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = None, guidance_rescale: float = 0.0, use_original_formulation: bool = False, start: float = 0.0, stop: float = 1.0, enabled: bool = True)

源代码

参数：

guidance_scale (float，默认值为 7.5)：分类器自由引导的 scale 参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。

perturbed_guidance_scale (float，默认为 2.8)：用于扰动注意力引导的 scale 参数。

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，默认为 0.0)：应用于噪声预测的重缩放因子。用于提升图像质量并修复过曝问题。基于 常见的扩散噪声调度和采样步骤存在缺陷 中的第 3.4 节。

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[[diffusers.AdaptiveProjectedGuidance]]

diffusers.AdaptiveProjectedGuidance[[diffusers.AdaptiveProjectedGuidance]]

diffusers.AdaptiveProjectedGuidance(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, ...] | None = None, eta: float = 1.0, guidance_rescale: float = 0.0, use_original_formulation: bool = False, start: float = 0.0, stop: float = 1.0, enabled: bool = True)

源代码

参数：

guidance_scale (float，默认值为 7.5)：分类器自由引导的 scale 参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。

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，默认为 0.0)：应用于噪声预测的重缩放因子。用于提升图像质量并修复过曝问题。基于 常见的扩散噪声调度和采样步骤存在缺陷 中的第 3.4 节。

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[[diffusers.AutoGuidance]]

diffusers.AutoGuidance[[diffusers.AutoGuidance]]

diffusers.AutoGuidance(guidance_scale: float = 7.5, auto_guidance_layers: int | list[int] | None = None, auto_guidance_config: LayerSkipConfig | list[LayerSkipConfig] | dict[str, Any] = None, dropout: float | None = None, guidance_rescale: float = 0.0, use_original_formulation: bool = False, start: float = 0.0, stop: float = 1.0, enabled: bool = True)

源代码

参数：

guidance_scale (float，默认值为 7.5)：分类器自由引导的 scale 参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。

auto_guidance_layers (int 或 list[int]，可选) : 要应用 skip layer guidance 的层索引。可以是单个整数或整数列表。如果未提供，则必须提供 skip_layer_config。

auto_guidance_config (LayerSkipConfig 或 list[LayerSkipConfig]，可选)：用于配置跳过层引导。可以是单个 LayerSkipConfig 或 LayerSkipConfig 列表。如果未提供，则必须提供 skip_layer_guidance_layers。

dropout (float, 可选) : 在启用的跳过层（通过 auto_guidance_layers 或 auto_guidance_config 指定）上用于自动引导的 dropout 概率。如果未提供，dropout 概率将设置为 1.0。

guidance_rescale (float，默认为 0.0)：应用于噪声预测的重缩放因子。用于提升图像质量并修复过曝问题。基于 常见的扩散噪声调度和采样步骤存在缺陷 中的第 3.4 节。

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[[diffusers.TangentialClassifierFreeGuidance]]

diffusers.TangentialClassifierFreeGuidance[[diffusers.TangentialClassifierFreeGuidance]]

diffusers.TangentialClassifierFreeGuidance(guidance_scale: float = 7.5, guidance_rescale: float = 0.0, use_original_formulation: bool = False, start: float = 0.0, stop: float = 1.0, enabled: bool = True)

源代码

参数：

guidance_scale (float，默认值为 7.5)：分类器自由引导的 scale 参数。较高的值会增强对文本提示的条件约束，而较低的值则允许生成过程拥有更大的自由度。过高的值可能导致饱和并降低图像质量。

guidance_rescale (float，默认为 0.0)：应用于噪声预测的重缩放因子。用于提升图像质量并修复过曝问题。基于 常见的扩散噪声调度和采样步骤存在缺陷 中的第 3.4 节。

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[[diffusers.LTX2Guidance]]

diffusers.LTX2Guidance[[diffusers.LTX2Guidance]]

diffusers.LTX2Guidance(guidance_scale: float = 1.0, stg_scale: float = 0.0, modality_scale: float = 1.0, guidance_rescale: float = 0.0, spatio_temporal_guidance_blocks: list[int] | None = None, start: float = 0.0, stop: float = 1.0, enabled: 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）。负责调用的去噪器块（denoiser block）需为每次前向传播设置这些标识符；使用示例请参见 LTX2LoopDenoiser。