Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /zh /using-diffusers /guiders.md

mishig

2 days ago

preview code

download

raw

7.22 kB

# 引导者

[Classifier-free guidance](https://huggingface.co/papers/2207.12598) 用于引导模型生成更贴合提示词的内容，常用于提升生成质量、可控性以及对提示词的遵循度。存在多种不同的引导方法，在 Diffusers 中它们被称为 *guiders*。与 blocks 类似，你可以轻松切换并使用不同的 guiders 来适配不同的使用场景，而无需重写 pipeline。

本指南将向您展示如何切换 guider、调整 guider 参数，以及如何将其加载并共享到 Hub。

## 切换引导器

[ClassifierFreeGuidance](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/guiders#diffusers.ClassifierFreeGuidance) 是默认的 guider，在通过 [init_pipeline()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks.init_pipeline) 初始化 pipeline 时创建。它由 `from_config` 创建，因此无需从模块化仓库加载规范。guider 不会列在 `modular_model_index.json` 中。

使用 [get_component_spec()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.get_component_spec) 来检查 guider。

```py
t2i_pipeline.get_component_spec("guider")
ComponentSpec(name='guider', type_hint=<class 'diffusers.guiders.classifier_free_guidance.ClassifierFreeGuidance'>, description=None, config=FrozenDict([('guidance_scale', 7.5), ('guidance_rescale', 0.0), ('use_original_formulation', False), ('start', 0.0), ('stop', 1.0), ('_use_default_values', ['start', 'guidance_rescale', 'stop', 'use_original_formulation'])]), repo=None, subfolder=None, variant=None, revision=None, default_creation_method='from_config')
```

通过向 [update_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.update_components) 传入新的 guider 来切换到不同的 guider。

> [!TIP]
> 更改 guider 会返回一段文本，提示您正在更改 guider 类型。
> ```bash
> ModularPipeline.update_components: adding guider with new type: PerturbedAttentionGuidance, previous type: ClassifierFreeGuidance
> ```
```py
from diffusers import LayerSkipConfig, PerturbedAttentionGuidance
config = LayerSkipConfig(indices=[2, 9], fqn="mid_block.attentions.0.transformer_blocks", skip_attention=False, skip_attention_scores=True, skip_ff=False)
guider = PerturbedAttentionGuidance(
    guidance_scale=5.0, perturbed_guidance_scale=2.5, perturbed_guidance_config=config
)
t2i_pipeline.update_components(guider=guider)
```
再次使用 [get_component_spec()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.get_component_spec) 以验证 guider 类型已有所不同。
```py
t2i_pipeline.get_component_spec("guider")
ComponentSpec(name='guider', type_hint=<class 'diffusers.guiders.perturbed_attention_guidance.PerturbedAttentionGuidance'>, description=None, config=FrozenDict([('guidance_scale', 5.0), ('perturbed_guidance_scale', 2.5), ('perturbed_guidance_start', 0.01), ('perturbed_guidance_stop', 0.2), ('perturbed_guidance_layers', None), ('perturbed_guidance_config', LayerSkipConfig(indices=[2, 9], fqn='mid_block.attentions.0.transformer_blocks', skip_attention=False, skip_attention_scores=True, skip_ff=False, dropout=1.0)), ('guidance_rescale', 0.0), ('use_original_formulation', False), ('start', 0.0), ('stop', 1.0), ('_use_default_values', ['perturbed_guidance_start', 'use_original_formulation', 'perturbed_guidance_layers', 'stop', 'start', 'guidance_rescale', 'perturbed_guidance_stop']), ('_class_name', 'PerturbedAttentionGuidance'), ('_diffusers_version', '0.35.0.dev0')]), repo=None, subfolder=None, variant=None, revision=None, default_creation_method='from_config')
```
## 加载自定义引导器
Hub 上已保存且包含 `modular_model_index.json` 文件的 Guider，现在被视为 `from_pretrained` 组件，而非 `from_config` 组件。
```json
{
  "guider": [
    null,
    null,
    {
      "repo": "YiYiXu/modular-loader-t2i-guider",
      "revision": null,
      "subfolder": "pag_guider",
      "type_hint": [
        "diffusers",
        "PerturbedAttentionGuidance"
      ],
      "variant": null
    }
  ]
}
```
[load_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.load_components) 调用完成后，才会根据 `modular_model_index.json` 中的加载规范创建 guider。

```py
t2i_pipeline = t2i_blocks.init_pipeline("YiYiXu/modular-doc-guider")
# not created during init
assert t2i_pipeline.guider is None
t2i_pipeline.load_components()
# loaded as PAG guider
t2i_pipeline.guider
```

## 更改 guider 参数

[create()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline_components#diffusers.ComponentSpec.create) 方法和 [update_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.update_components) 可用于调整 guider 参数。下面的示例修改了 `guidance_scale` 的值。

```py
guider_spec = t2i_pipeline.get_component_spec("guider")
guider = guider_spec.create(guidance_scale=10)
t2i_pipeline.update_components(guider=guider)
```

## 上传自定义 guider

在自定义 guider 上调用 [push_to_hub()](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.utils.PushToHubMixin.push_to_hub) 方法，将其共享到 Hub。

```py
guider.push_to_hub("YiYiXu/modular-loader-t2i-guider", subfolder="pag_guider")
```

要让此 guider 在 pipeline 中可用，请修改 `modular_model_index.json` 文件，或使用 [update_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.update_components) 方法。

编辑 `modular_model_index.json` 文件，并添加 guider 的加载规范，使其指向包含 guider 配置的文件夹。

```json
{
  "guider": [
    "diffusers",
    "PerturbedAttentionGuidance",
    {
      "repo": "YiYiXu/modular-loader-t2i-guider",
      "revision": null,
      "subfolder": "pag_guider",
      "type_hint": [
        "diffusers",
        "PerturbedAttentionGuidance"
      ],
      "variant": null
    }
  ],
```

将 `default_creation_method()` 更改为 `from_pretrained`，并使用 [update_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.update_components) 来更新 guider 和组件规范以及流水线配置。

> [!TIP]
> 更改创建方法将返回一段文本，提示您正在将创建类型更改为 `from_pretrained`。
> ```bash
> ModularPipeline.update_components: changing the default_creation_method of guider from from_config to from_pretrained.
> ```

```py
guider_spec = t2i_pipeline.get_component_spec("guider")
guider_spec.default_creation_method="from_pretrained"
guider_spec.pretrained_model_name_or_path="YiYiXu/modular-loader-t2i-guider"
guider_spec.subfolder="pag_guider"
pag_guider = guider_spec.load()
t2i_pipeline.update_components(guider=pag_guider)
```

要将其设置为管道的默认 guider，请调用 [push_to_hub()](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.utils.PushToHubMixin.push_to_hub)。这是一个可选步骤，如果您仅在本地进行实验，则无需执行此操作。

```py
t2i_pipeline.push_to_hub("YiYiXu/modular-doc-guider")
```

Xet Storage Details

Size:: 7.22 kB
Xet hash:: 98624f47b8389e49834f930c1469aa00fe1ec30d7c5a9188b25e3afbea3a255e

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# 引导者

	[Classifier-free guidance](https://huggingface.co/papers/2207.12598) 用于引导模型生成更贴合提示词的内容，常用于提升生成质量、可控性以及对提示词的遵循度。存在多种不同的引导方法，在 Diffusers 中它们被称为 guiders。与 blocks 类似，你可以轻松切换并使用不同的 guiders 来适配不同的使用场景，而无需重写 pipeline。

	本指南将向您展示如何切换 guider、调整 guider 参数，以及如何将其加载并共享到 Hub。

	## 切换引导器

	[ClassifierFreeGuidance](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/guiders#diffusers.ClassifierFreeGuidance) 是默认的 guider，在通过 [init_pipeline()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks.init_pipeline) 初始化 pipeline 时创建。它由 `from_config` 创建，因此无需从模块化仓库加载规范。guider 不会列在 `modular_model_index.json` 中。

	使用 [get_component_spec()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.get_component_spec) 来检查 guider。

	```py
	t2i_pipeline.get_component_spec("guider")
	ComponentSpec(name='guider', type_hint=<class 'diffusers.guiders.classifier_free_guidance.ClassifierFreeGuidance'>, description=None, config=FrozenDict([('guidance_scale', 7.5), ('guidance_rescale', 0.0), ('use_original_formulation', False), ('start', 0.0), ('stop', 1.0), ('_use_default_values', ['start', 'guidance_rescale', 'stop', 'use_original_formulation'])]), repo=None, subfolder=None, variant=None, revision=None, default_creation_method='from_config')
	```

	通过向 [update_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.update_components) 传入新的 guider 来切换到不同的 guider。

	> [!TIP]
	> 更改 guider 会返回一段文本，提示您正在更改 guider 类型。
	> ```bash
	> ModularPipeline.update_components: adding guider with new type: PerturbedAttentionGuidance, previous type: ClassifierFreeGuidance
	> ```

	```py
	from diffusers import LayerSkipConfig, PerturbedAttentionGuidance

	config = LayerSkipConfig(indices=[2, 9], fqn="mid_block.attentions.0.transformer_blocks", skip_attention=False, skip_attention_scores=True, skip_ff=False)
	guider = PerturbedAttentionGuidance(
	guidance_scale=5.0, perturbed_guidance_scale=2.5, perturbed_guidance_config=config
	)
	t2i_pipeline.update_components(guider=guider)
	```

	再次使用 [get_component_spec()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.get_component_spec) 以验证 guider 类型已有所不同。

	```py
	t2i_pipeline.get_component_spec("guider")
	ComponentSpec(name='guider', type_hint=<class 'diffusers.guiders.perturbed_attention_guidance.PerturbedAttentionGuidance'>, description=None, config=FrozenDict([('guidance_scale', 5.0), ('perturbed_guidance_scale', 2.5), ('perturbed_guidance_start', 0.01), ('perturbed_guidance_stop', 0.2), ('perturbed_guidance_layers', None), ('perturbed_guidance_config', LayerSkipConfig(indices=[2, 9], fqn='mid_block.attentions.0.transformer_blocks', skip_attention=False, skip_attention_scores=True, skip_ff=False, dropout=1.0)), ('guidance_rescale', 0.0), ('use_original_formulation', False), ('start', 0.0), ('stop', 1.0), ('_use_default_values', ['perturbed_guidance_start', 'use_original_formulation', 'perturbed_guidance_layers', 'stop', 'start', 'guidance_rescale', 'perturbed_guidance_stop']), ('_class_name', 'PerturbedAttentionGuidance'), ('_diffusers_version', '0.35.0.dev0')]), repo=None, subfolder=None, variant=None, revision=None, default_creation_method='from_config')
	```

	## 加载自定义引导器

	Hub 上已保存且包含 `modular_model_index.json` 文件的 Guider，现在被视为 `from_pretrained` 组件，而非 `from_config` 组件。

	```json
	{
	"guider": [
	null,
	null,
	{
	"repo": "YiYiXu/modular-loader-t2i-guider",
	"revision": null,
	"subfolder": "pag_guider",
	"type_hint": [
	"diffusers",
	"PerturbedAttentionGuidance"
	],
	"variant": null
	}
	]
	}
	```

	[load_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.load_components) 调用完成后，才会根据 `modular_model_index.json` 中的加载规范创建 guider。

	```py
	t2i_pipeline = t2i_blocks.init_pipeline("YiYiXu/modular-doc-guider")
	# not created during init
	assert t2i_pipeline.guider is None
	t2i_pipeline.load_components()
	# loaded as PAG guider
	t2i_pipeline.guider
	```

	## 更改 guider 参数

	[create()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline_components#diffusers.ComponentSpec.create) 方法和 [update_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.update_components) 可用于调整 guider 参数。下面的示例修改了 `guidance_scale` 的值。

	```py
	guider_spec = t2i_pipeline.get_component_spec("guider")
	guider = guider_spec.create(guidance_scale=10)
	t2i_pipeline.update_components(guider=guider)
	```

	## 上传自定义 guider

	在自定义 guider 上调用 [push_to_hub()](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.utils.PushToHubMixin.push_to_hub) 方法，将其共享到 Hub。

	```py
	guider.push_to_hub("YiYiXu/modular-loader-t2i-guider", subfolder="pag_guider")
	```

	要让此 guider 在 pipeline 中可用，请修改 `modular_model_index.json` 文件，或使用 [update_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.update_components) 方法。

	编辑 `modular_model_index.json` 文件，并添加 guider 的加载规范，使其指向包含 guider 配置的文件夹。

	```json
	{
	"guider": [
	"diffusers",
	"PerturbedAttentionGuidance",
	{
	"repo": "YiYiXu/modular-loader-t2i-guider",
	"revision": null,
	"subfolder": "pag_guider",
	"type_hint": [
	"diffusers",
	"PerturbedAttentionGuidance"
	],
	"variant": null
	}
	],
	```

	将 `default_creation_method()` 更改为 `from_pretrained`，并使用 [update_components()](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.update_components) 来更新 guider 和组件规范以及流水线配置。

	> [!TIP]
	> 更改创建方法将返回一段文本，提示您正在将创建类型更改为 `from_pretrained`。
	> ```bash
	> ModularPipeline.update_components: changing the default_creation_method of guider from from_config to from_pretrained.
	> ```

	```py
	guider_spec = t2i_pipeline.get_component_spec("guider")
	guider_spec.default_creation_method="from_pretrained"
	guider_spec.pretrained_model_name_or_path="YiYiXu/modular-loader-t2i-guider"
	guider_spec.subfolder="pag_guider"
	pag_guider = guider_spec.load()
	t2i_pipeline.update_components(guider=pag_guider)
	```

	要将其设置为管道的默认 guider，请调用 [push_to_hub()](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.utils.PushToHubMixin.push_to_hub)。这是一个可选步骤，如果您仅在本地进行实验，则无需执行此操作。

	```py
	t2i_pipeline.push_to_hub("YiYiXu/modular-doc-guider")
	```