# 扰动注意力引导 [Perturbed-Attention Guidance (PAG)](https://ku-cvlab.github.io/Perturbed-Attention-Guidance/) 是一种新的扩散采样引导方法，它能在无条件和有条件设置下均提升样本质量，且无需额外训练或集成外部模块。 PAG 由 Donghoon Ahn、Hyoungwon Cho、Jaewon Min、Wooseok Jang、Jungwoo Kim、SeonHwa Kim、Hyun Hee Park、Kyong Hwan Jin 和 Seungryong Kim 在 [Self-Rectifying Diffusion Sampling with Perturbed-Attention Guidance](https://huggingface.co/papers/2403.17377) 中提出。 该论文的摘要如下： *近期研究表明，扩散模型能够生成高质量的样本，但其质量在很大程度上依赖于采样引导技术，例如分类器引导（CG）和分类器自由引导（CFG）。这些技术通常不适用于无条件生成，也不适用于图像修复等许多下游任务。在本文中，我们提出了一种新颖的采样引导方法，称为扰动注意力引导（PAG）。该方法能够在无条件和条件设置下均提升扩散样本的质量，且无需额外训练或集成外部模块。PAG 旨在在去噪过程中逐步增强样本的结构。其实现方式是：考虑到自注意力机制捕捉结构信息的能力，将扩散 U-Net 中选定的自注意力图替换为单位矩阵，从而生成结构退化的中间样本，并引导去噪过程远离这些退化样本。在 ADM 和 Stable Diffusion 中，PAG 出人意料地提升了条件场景甚至无条件场景下的样本质量。此外，在现有引导方法（如 CG 或 CFG）无法充分发挥作用的多种下游任务中，PAG 显著提升了基线性能，这些任务包括使用空提示的 ControlNet，以及图像修复（如图像修复和去模糊）。* `pag_applied_layers` 可以作为参数在实例化 PAG 流水线时指定。它可以是一个字符串或一个字符串列表。每个字符串可以是唯一的层标识符，也可以是用于识别一个或多个层的正则表达式。 - 作为普通字符串的完整标识符：`down_blocks.2.attentions.0.transformer_blocks.0.attn1.processor` - 作为 RegEx 的完整标识符：`down_blocks.2.(attentions|motion_modules).0.transformer_blocks.0.attn1.processor` - 作为 RegEx 的部分标识符：`down_blocks.2`，或 `attn1` - 标识符列表（可以是字符串和 ReGex 的组合）：`["blocks.1", "blocks.(14|20)", r"down_blocks\.(2,3)"]` > [!WARNING] > 由于 RegEx 被支持用于匹配层标识符，因此正确使用方法至关重要，否则可能会出现意外行为。推荐通过指定层为 `blocks.{layer_index}` 和 `blocks.({layer_index_1|layer_index_2|...})` 来使用 PAG。以其他方式使用虽然可行，但可能会绕过我们的基本验证检查，从而导致意外结果。 ## 通用任务 您可以将 PAG 应用于 [StableDiffusionXLPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/stable_diffusion_xl#diffusers.StableDiffusionXLPipeline)，以执行文生图、图生图和图像修复等任务。要为特定任务启用 PAG，请使用 [AutoPipeline](./auto_pipeline) API 加载流水线，并设置 `enable_pag=True` 标志以及 `pag_applied_layers` 参数。 > [!TIP] > 🤗 Diffusers 目前仅支持在部分 SDXL 流水线以及 [PixArtSigmaPAGPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/pag#diffusers.PixArtSigmaPAGPipeline) 中使用 PAG。如果您希望为新的流水线添加 PAG 支持，请随时提交一个 [功能请求](https://github.com/huggingface/diffusers/issues/new/choose)！ ```py from diffusers import AutoPipelineForText2Image from diffusers.utils import load_image import torch pipeline = AutoPipelineForText2Image.from_pretrained( "stabilityai/stable-diffusion-xl-base-1.0", enable_pag=True, pag_applied_layers=["mid"], dtype=torch.float16 ) pipeline.enable_model_cpu_offload() ``` > [!TIP] > `pag_applied_layers` 参数允许你指定将 PAG 应用于哪些层。此外，你还可以使用 `set_pag_applied_layers` 方法在创建流水线后更新这些层。有关将 PAG 应用于其他层的更多信息，请参阅 [pag_applied_layers](#pagappliedlayers) 部分。 如果您已经创建并加载了一个 pipeline，可以使用 `from_pipe` API 并设置 `enable_pag` 标志来为其启用 PAG。内部会根据您指定的 pipeline 和任务创建一个 PAG pipeline。在下面的示例中，由于我们使用了 `AutoPipelineForText2Image` 并传入了一个 `StableDiffusionXLPipeline`，因此相应地创建了一个 `StableDiffusionXLPAGPipeline`。请注意，这不需要额外的内存，并且 `StableDiffusionXLPipeline` 和 `StableDiffusionXLPAGPipeline` 都会被加载并处于可用状态。您可以阅读更多关于 `from_pipe` API 以及如何在 diffuser 中复用 pipeline 的内容，详见[此处](https://huggingface.co/docs/diffusers/using-diffusers/loading#reusing-models-in-multiple-pipelines)。 ```py pipeline_sdxl = AutoPipelineForText2Image.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16) pipeline = AutoPipelineForText2Image.from_pipe(pipeline_sdxl, enable_pag=True) ``` 要生成图像，您还需要传入 `pag_scale`。随着 `pag_scale` 增大，图像会呈现出更具语义连贯性的结构，并减少伪影。然而，过大的 guidance scale 会导致图像纹理过于平滑并出现轻微过饱和，这与 CFG 类似。官方演示中使用了 `pag_scale=3.0`，它在大多数使用场景中效果良好，但请根据您的具体需求自由尝试并选择合适的值！当 `pag_scale=0` 时，PAG 将被禁用。 ```py prompt = "an insect robot preparing a delicious meal, anime style" for pag_scale in [0.0, 3.0]: generator = torch.Generator(device="cpu").manual_seed(0) images = pipeline( prompt=prompt, num_inference_steps=25, guidance_scale=7.0, generator=generator, pag_scale=pag_scale, ).images ``` 未使用 PAG 生成的图像 使用 PAG 生成的图像 您可以将 PAG 与图像到图像（image-to-image）流水线配合使用。 ```py from diffusers import AutoPipelineForImage2Image from diffusers.utils import load_image import torch pipeline = AutoPipelineForImage2Image.from_pretrained( "stabilityai/stable-diffusion-xl-base-1.0", enable_pag=True, pag_applied_layers=["mid"], dtype=torch.float16 ) pipeline.enable_model_cpu_offload() ``` 如果您已经拥有一个图像到图像流水线，并希望在其上启用 PAG，可以运行以下代码 ```py pipeline_t2i = AutoPipelineForImage2Image.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16) pipeline = AutoPipelineForImage2Image.from_pipe(pipeline_t2i, enable_pag=True) ``` 从文本到图像流水线直接切换到启用 PAG 的图像到图像流水线也非常简单 ```py pipeline_pag = AutoPipelineForText2Image.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16) pipeline = AutoPipelineForImage2Image.from_pipe(pipeline_t2i, enable_pag=True) ``` 如果您拥有启用了 PAG 的文本生成图像流水线，您可以直接切换到仍启用 PAG 的图像生成图像流水线 ```py pipeline_pag = AutoPipelineForText2Image.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", enable_pag=True, dtype=torch.float16) pipeline = AutoPipelineForImage2Image.from_pipe(pipeline_t2i) ``` 现在让我们生成一张图像！ ```py pag_scales = 4.0 guidance_scales = 7.0 url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/sdxl-text2img.png" init_image = load_image(url) prompt = "a dog catching a frisbee in the jungle" generator = torch.Generator(device="cpu").manual_seed(0) image = pipeline( prompt, image=init_image, strength=0.8, guidance_scale=guidance_scale, pag_scale=pag_scale, generator=generator).images[0] ``` ```py from diffusers import AutoPipelineForInpainting from diffusers.utils import load_image import torch pipeline = AutoPipelineForInpainting.from_pretrained( "stabilityai/stable-diffusion-xl-base-1.0", enable_pag=True, dtype=torch.float16 ) pipeline.enable_model_cpu_offload() ``` 您可以像这样在现有的 inpainting 管道上启用 PAG ```py pipeline_inpaint = AutoPipelineForInpainting.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16) pipeline = AutoPipelineForInpainting.from_pipe(pipeline_inpaint, enable_pag=True) ``` 当您的流水线执行不同的任务时，这仍然有效： ```py pipeline_t2i = AutoPipelineForText2Image.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16) pipeline = AutoPipelineForInpaiting.from_pipe(pipeline_t2i, enable_pag=True) ``` 让我们生成一张图像！ ```py img_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo.png" mask_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo_mask.png" init_image = load_image(img_url).convert("RGB") mask_image = load_image(mask_url).convert("RGB") prompt = "A majestic tiger sitting on a bench" pag_scales = 3.0 guidance_scales = 7.5 generator = torch.Generator(device="cpu").manual_seed(1) images = pipeline( prompt=prompt, image=init_image, mask_image=mask_image, strength=0.8, num_inference_steps=50, guidance_scale=guidance_scale, generator=generator, pag_scale=pag_scale, ).images images[0] ``` ## PAG 与 ControlNet 要将 PAG 与 ControlNet 配合使用，首先创建一个 `controlnet`。然后，将 `controlnet` 以及其他 PAG 参数传递给指定任务的 AutoPipeline 的 `from_pretrained` 方法。 ```py from diffusers import AutoPipelineForText2Image, ControlNetModel import torch controlnet = ControlNetModel.from_pretrained( "diffusers/controlnet-canny-sdxl-1.0", dtype=torch.float16 ) pipeline = AutoPipelineForText2Image.from_pretrained( "stabilityai/stable-diffusion-xl-base-1.0", controlnet=controlnet, enable_pag=True, pag_applied_layers="mid", dtype=torch.float16 ) pipeline.enable_model_cpu_offload() ``` > [!TIP] > 如果您已经拥有 controlnet 流水线并希望启用 PAG，可以使用 `from_pipe` API：`AutoPipelineForText2Image.from_pipe(pipeline_controlnet, enable_pag=True)` 您可以像通常使用 ControlNet 流水线一样使用该流水线，并额外指定 `pag_scale` 参数。请注意，PAG 在无提示生成中表现良好。在本示例中，我们将不输入提示词来生成一张图像。 ```py from diffusers.utils import load_image canny_image = load_image( "https://huggingface.co/datasets/YiYiXu/testing-images/resolve/main/pag_control_input.png" ) for pag_scale in [0.0, 3.0]: generator = torch.Generator(device="cpu").manual_seed(1) images = pipeline( prompt="", controlnet_conditioning_scale=controlnet_conditioning_scale, image=canny_image, num_inference_steps=50, guidance_scale=0, generator=generator, pag_scale=pag_scale, ).images images[0] ``` 未使用 PAG 生成的图像 使用 PAG 生成的图像 ## PAG 与 IP-Adapter [IP-Adapter](https://hf.co/papers/2308.06721) 是一款流行的模型，可以接入扩散模型，从而在不修改底层模型的情况下实现图像提示功能。你可以在加载了 IP-Adapter 的 pipeline 上启用 PAG。 ```py from diffusers import AutoPipelineForText2Image from diffusers.utils import load_image from transformers import CLIPVisionModelWithProjection import torch image_encoder = CLIPVisionModelWithProjection.from_pretrained( "h94/IP-Adapter", subfolder="models/image_encoder", dtype=torch.float16 ) pipeline = AutoPipelineForText2Image.from_pretrained( "stabilityai/stable-diffusion-xl-base-1.0", image_encoder=image_encoder, enable_pag=True, dtype=torch.float16 ).to("cuda") # or "mps", "xpu", "cpu" pipeline.load_ip_adapter("h94/IP-Adapter", subfolder="sdxl_models", weight_name="ip-adapter-plus_sdxl_vit-h.bin") pag_scales = 5.0 ip_adapter_scales = 0.8 image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/ip_adapter_diner.png") pipeline.set_ip_adapter_scale(ip_adapter_scale) generator = torch.Generator(device="cpu").manual_seed(0) images = pipeline( prompt="a polar bear sitting in a chair drinking a milkshake", ip_adapter_image=image, negative_prompt="deformed, ugly, wrong proportion, low res, bad anatomy, worst quality, low quality", num_inference_steps=25, guidance_scale=3.0, generator=generator, pag_scale=pag_scale, ).images images[0] ``` PAG 减少了伪影并提升了整体构图。 未使用 PAG 生成的图像 使用 PAG 生成的图像 ## 配置参数 ### pag_applied_layers `pag_applied_layers` 参数允许你指定将 PAG 应用于哪些层。默认情况下，它仅应用于中间块。更改此设置会对输出产生显著影响。你可以在创建流水线后使用 `set_pag_applied_layers` 方法来调整 PAG 层，从而帮助你找到适合你模型的最佳层。 例如，以下是使用 `pag_layers = ["down.block_2"]` 和 `pag_layers = ["down.block_2", "up.block_1.attentions_0"]` 生成的图像 ```py prompt = "an insect robot preparing a delicious meal, anime style" pipeline.set_pag_applied_layers(pag_layers) generator = torch.Generator(device="cpu").manual_seed(0) images = pipeline( prompt=prompt, num_inference_steps=25, guidance_scale=guidance_scale, generator=generator, pag_scale=pag_scale, ).images images[0] ``` down.block_2 + up.block1.attentions_0 down.block_2 ## AnimateDiffPAGPipeline[[diffusers.AnimateDiffPAGPipeline]] #### diffusers.AnimateDiffPAGPipeline[[diffusers.AnimateDiffPAGPipeline]] ```python diffusers.AnimateDiffPAGPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: diffusers.models.unets.unet_2d_condition.UNet2DConditionModel | diffusers.models.unets.unet_motion_model.UNetMotionModel, motion_adapter: MotionAdapter, scheduler: KarrasDiffusionSchedulers, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None, pag_applied_layers: str | list[str] = 'mid_block.*attn1') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_animatediff.py#L89) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder (`CLIPTextModel`)：冻结的文本编码器（[clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)）。 tokenizer (`CLIPTokenizer`)：一个用于对文本进行分词的 [CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：用于创建 UNetMotionModel 以对编码后的视频潜变量进行去噪的 [UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel)。 motion_adapter (`MotionAdapter`)：一个 `MotionAdapter`，与 `unet` 配合使用，以对编码后的视频潜变量进行去噪。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 使用 [AnimateDiff](https://huggingface.co/docs/diffusers/en/api/pipelines/animatediff) 和 [Perturbed Attention Guidance](https://huggingface.co/docs/diffusers/en/using-diffusers/pag) 进行文本到视频生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.AnimateDiffPAGPipeline.__call__]] ```python __call__(prompt: str | list[str] | None = None, num_frames: int | None = 16, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, guidance_scale: float = 7.5, negative_prompt: str | list[str] | None = None, num_videos_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, clip_skip: int | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], decode_chunk_size: int = 16, pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_animatediff.py#L575) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则需要传入 `prompt_embeds`。 height (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成视频的高度（以像素为单位）。 width (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成视频的像素宽度。 num_frames (`int`，*可选*，默认为 16)：生成的视频帧数。默认为 16 帧，按每秒 8 帧计算，相当于 2 秒的视频。 num_inference_steps (`int`，*可选*，默认值为 50)：去噪步数。更多的去噪步数通常能生成更高质量的视频，但代价是推理速度变慢。 guidance_scale (`float`, *可选*，默认值为 7.5)：较高的 guidance scale 值会促使模型生成与文本 `prompt` 紧密相关的图像，但代价是图像质量降低。当 `guidance_scale > 1` 时，guidance scale 生效。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 `negative_prompt_embeds`。在未使用引导（`guidance_scale < 1`）时将被忽略。 num_videos_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的视频数量。 eta (`float`，*可选*，默认值为 0.0)：对应 [DDIM](https://huggingface.co/papers/2010.02502) 论文中的参数 eta (η)。仅适用于 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，在其他调度器中会被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：用于使生成过程确定性的 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)。 latents (`torch.Tensor`, *可选*) : 从高斯分布中采样的预生成噪声潜变量，用作视频生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，则使用提供的随机`generator`进行采样来生成潜变量张量。潜变量的形状应为`(batch_size, num_channel, num_frames, height, width)`。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成视频的输出格式。可选 `torch.Tensor`、`PIL.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~pipelines.text_to_video_synthesis.TextToVideoSDPipelineOutput` 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为 [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中定义的 `AttentionProcessor` 的参数传递。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 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` 属性中列出的变量。 decode_chunk_size (`int`，*可选*，默认为 16)：调用 `decode_latents` 方法时，每次解码的帧数。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** [AnimateDiffPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/animatediff#diffusers.pipelines.animatediff.AnimateDiffPipelineOutput) 或 `tuple` 如果 `return_dict` 为 `True`，则返回 [AnimateDiffPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/animatediff#diffusers.pipelines.animatediff.AnimateDiffPipelineOutput)；否则返回一个 `tuple`，其中第一个元素是包含生成帧的列表。 用于生成的 pipeline 的调用函数。 示例： ```py >>> import torch >>> from diffusers import AnimateDiffPAGPipeline, MotionAdapter, DDIMScheduler >>> from diffusers.utils import export_to_gif >>> model_id = "SG161222/Realistic_Vision_V5.1_noVAE" >>> motion_adapter_id = "guoyww/animatediff-motion-adapter-v1-5-2" >>> motion_adapter = MotionAdapter.from_pretrained(motion_adapter_id) >>> scheduler = DDIMScheduler.from_pretrained( ... model_id, subfolder="scheduler", beta_schedule="linear", steps_offset=1, clip_sample=False ... ) >>> pipe = AnimateDiffPAGPipeline.from_pretrained( ... model_id, ... motion_adapter=motion_adapter, ... scheduler=scheduler, ... pag_applied_layers=["mid"], ... torch_dtype=torch.float16, ... ).to("cuda") >>> video = pipe( ... prompt="car, futuristic cityscape with neon lights, street, no human", ... negative_prompt="low quality, bad quality", ... num_inference_steps=25, ... guidance_scale=6.0, ... pag_scale=3.0, ... generator=torch.Generator().manual_seed(42), ... ).frames[0] >>> export_to_gif(video, "animatediff_pag.gif") ``` #### encode_prompt[[diffusers.AnimateDiffPAGPipeline.encode_prompt]] ```python encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_animatediff.py#L165) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 ## HunyuanDiTPAGPipeline[[diffusers.HunyuanDiTPAGPipeline]] #### diffusers.HunyuanDiTPAGPipeline[[diffusers.HunyuanDiTPAGPipeline]] ```python diffusers.HunyuanDiTPAGPipeline(vae: AutoencoderKL, text_encoder: BertModel, tokenizer: BertTokenizer, transformer: HunyuanDiT2DModel, scheduler: DDPMScheduler, safety_checker: diffusers.pipelines.stable_diffusion.safety_checker.StableDiffusionSafetyChecker | None = None, feature_extractor: transformers.models.clip.image_processing_pil_clip.CLIPImageProcessorPil | None = None, requires_safety_checker: bool = True, text_encoder_2: transformers.models.t5.modeling_t5.T5EncoderModel | None = None, tokenizer_2: transformers.models.t5.tokenization_t5.T5Tokenizer | None = None, pag_applied_layers: str | list[str] = 'blocks.1') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_hunyuandit.py#L152) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，以及从潜在表示解码为图像。我们使用 `sdxl-vae-fp16-fix`。 text_encoder (`~transformers.BertModel`, `~transformers.CLIPTextModel` | None) : 冻结的文本编码器 ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14))。HunyuanDiT 使用经过微调的 [bilingual CLIP]。 tokenizer (`~transformers.BertTokenizer`、`~transformers.CLIPTokenizer` | None) : 用于对文本进行分词的 `BertTokenizer` 或 `CLIPTokenizer`。 transformer ([HunyuanDiT2DModel](/docs/diffusers/v0.43.0/zh/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel))：由腾讯混元设计的 HunyuanDiT 模型。 text_encoder_2 (`T5EncoderModel`)：mT5 嵌入器。具体而言，它是 't5-v1_1-xxl'。 tokenizer_2 (`T5Tokenizer`)：mT5 嵌入器的分词器。 scheduler ([DDPMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddpm#diffusers.DDPMScheduler))：用于配合 HunyuanDiT 对编码后的图像潜在表示进行去噪的调度器。 使用 HunyuanDiT 和 [Perturbed Attention Guidance](https://huggingface.co/docs/diffusers/en/using-diffusers/pag) 进行英/中到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。请查阅父类文档，了解该库为所有 pipeline 实现的通用方法（例如下载或保存、在特定设备上运行等）。 HunyuanDiT 使用两个文本编码器：[mT5](https://huggingface.co/google/mt5-base) 和 [双语 CLIP](由我们自行微调) #### __调用__[[diffusers.HunyuanDiTPAGPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_2: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_2: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, prompt_attention_mask_2: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask_2: typing.Optional[torch.Tensor] = None, output_type: str = 'pil', return_dict: bool = True, callback_on_step_end: typing.Union[typing.Callable[[int, int, dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], guidance_rescale: float = 0.0, original_size: tuple[int, int] = (1024, 1024), target_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), use_resolution_binning: bool = True, pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_hunyuandit.py#L579) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则需要传入 `prompt_embeds`。 height (`int`) : 生成图像的高度（以像素为单位）。 width (`int`) : 生成图像的宽度（以像素为单位）。 num_inference_steps (`int`，*可选*，默认值为 50)：去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。此参数受 `strength` 调节。 guidance_scale (`float`, *可选*，默认值为 7.5)：较高的 guidance scale 值会促使模型生成与文本 `prompt` 紧密相关的图像，但代价是图像质量降低。当 `guidance_scale > 1` 时，guidance scale 生效。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 `negative_prompt_embeds`。在未使用引导（`guidance_scale < 1`）时将被忽略。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 [DDIM](https://huggingface.co/papers/2010.02502) 论文中的参数 eta (η)。仅适用于 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，在其他调度器中会被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：用于使生成过程确定性的 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)。 latents (`torch.Tensor`, *可选*) : 从高斯分布中采样的预生成噪声潜变量，用作图像生成的输入。可用于以不同的提示词微调同一生成过程。如果未提供，则使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成文本嵌入。 prompt_embeds_2 (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。 negative_prompt_embeds_2 (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。 prompt_attention_mask (`torch.Tensor`, *可选*) : 提示词的注意力掩码。当直接传入 `prompt_embeds` 时，此项为必填。 prompt_attention_mask_2 (`torch.Tensor`，*可选*)：提示词的注意力掩码。当直接传入 `prompt_embeds_2` 时，此项为必填。 negative_prompt_attention_mask (`torch.Tensor`，*可选*)：用于负面提示词的注意力掩码。当直接传入 `negative_prompt_embeds` 时，此参数为必填项。 negative_prompt_attention_mask_2 (`torch.Tensor`, *可选*) : 负面提示词的注意力掩码。当直接传入 `negative_prompt_embeds_2` 时，此参数为必填项。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。在 `PIL.Image` 或 `np.array` 之间选择。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。 callback_on_step_end (`Callable[[int, int], None]`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：在每个去噪步骤结束时调用的回调函数或回调函数列表。 callback_on_step_end_tensor_inputs (`list[str]`，*可选*) : 应传递给回调函数的张量输入列表。如果未定义，则所有张量输入都会被传递。 guidance_rescale (`float`, *optional*, defaults to 0.0) : Rescale the noise_cfg according to `guidance_rescale`. Based on findings of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). See Section 3.4 original_size (`tuple[int, int]`，*可选*，默认为 `(1024, 1024)`)：图像的原始尺寸。用于计算时间 ID。 target_size (`tuple[int, int]`，*可选*)：图像的目标尺寸。用于计算时间 ID。 crops_coords_top_left (`tuple[int, int]`，*可选*，默认为 `(0, 0)`)：裁剪区域的左上角坐标。用于计算时间 ID。 use_resolution_binning (`bool`，*可选*，默认为 `True`)：是否使用分辨率分箱。如果为 `True`，输入分辨率将被映射到最接近的标准分辨率。支持的分辨率为 1024x1024、1280x1280、1024x768、1152x864、1280x960、768x1024、864x1152、960x1280、1280x768 和 768x1280。建议将此值设置为 `True`。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 或 `tuple` 如果 `return_dict` 为 `True`，则返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)；否则返回一个 `tuple`，其中第一个元素是包含生成图像的列表，第二个元素是 `bool` 列表，用于指示对应的生成图像是否包含“不适合工作场所”（nsfw）内容。 调用 pipeline 的 call 函数，使用 HunyuanDiT 进行生成。 示例： ```python >>> import torch >>> from diffusers import AutoPipelineForText2Image >>> pipe = AutoPipelineForText2Image.from_pretrained( ... "Tencent-Hunyuan/HunyuanDiT-v1.2-Diffusers", ... torch_dtype=torch.float16, ... enable_pag=True, ... pag_applied_layers=[14], ... ).to("cuda") >>> # prompt = "an astronaut riding a horse" >>> prompt = "一个宇航员在骑马" >>> image = pipe(prompt, guidance_scale=4, pag_scale=3).images[0] ``` #### encode_prompt[[diffusers.HunyuanDiTPAGPipeline.encode_prompt]] ```python encode_prompt(prompt: str, device: device = None, dtype: dtype = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int | None = None, text_encoder_index: int = 0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_hunyuandit.py#L258) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 device : (`torch.device`): torch 设备 dtype (`torch.dtype`)：torch 数据类型 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 prompt_attention_mask (`torch.Tensor`, *可选*) : 提示词的注意力掩码。当直接传入 `prompt_embeds` 时，此项为必填。 negative_prompt_attention_mask (`torch.Tensor`，*可选*)：用于负面提示词的注意力掩码。当直接传入 `negative_prompt_embeds` 时，此参数为必填项。 max_sequence_length (`int`, *可选*) : 用于提示词的最大序列长度。 text_encoder_index (`int`, *可选*) : 要使用的文本编码器索引。`0` 表示 clip，`1` 表示 T5。 将提示词编码为文本编码器的隐藏状态。 ## KolorsPAGPipeline[[diffusers.KolorsPAGPipeline]] #### diffusers.KolorsPAGPipeline[[diffusers.KolorsPAGPipeline]] ```python diffusers.KolorsPAGPipeline(vae: AutoencoderKL, text_encoder: ChatGLMModel, tokenizer: ChatGLMTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None, force_zeros_for_empty_prompt: bool = False, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_kolors.py#L128) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder (`ChatGLMModel`)：冻结的文本编码器。Kolors 使用 [ChatGLM3-6B](https://huggingface.co/THUDM/chatglm3-6b)。 tokenizer (`ChatGLMTokenizer`)：[ChatGLMTokenizer](https://huggingface.co/THUDM/chatglm3-6b/blob/main/tokenization_chatglm.py) 类的分词器。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：用于对编码后的图像潜变量进行去噪的条件 U-Net 架构。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 force_zeros_for_empty_prompt (`bool`，*可选*，默认为 `"False"`)：是否强制将负提示嵌入始终设置为 0。另请参阅 `Kwai-Kolors/Kolors-diffusers` 的配置。 pag_applied_layers (`str` or `list[str]``, *optional*, defaults to `"mid"`) : Set the transformer attention layers where to apply the perturbed attention guidance. Can be a string or a list of strings with "down", "mid", "up", a whole transformer block or specific transformer block attention layers, e.g.: ["mid"] ["down", "mid"] ["down", "mid", "up.block_1"] ["down", "mid", "up.block_1.attentions_0", "up.block_1.attentions_1"] 使用 Kolors 进行文本到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。请查阅父类文档，了解该库为所有 pipeline 实现的通用方法（例如下载或保存、在特定设备上运行等）。 该 pipeline 还继承了以下加载方法： - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.KolorsPAGPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, denoising_end: float | None = None, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, original_size: tuple[int, int] | None = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] | None = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0, max_sequence_length: int = 256) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_kolors.py#L665) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 `prompt_embeds`。 height (`int`，*可选*，默认为 self.unet.config.sample_size * self.vae_scale_factor)：生成图像的高度（以像素为单位）。默认设置为 1024 以获得最佳效果。对于 [Kwai-Kolors/Kolors-diffusers](https://huggingface.co/Kwai-Kolors/Kolors-diffusers) 以及未在低分辨率上专门微调的检查点，低于 512 像素的效果不佳。 width (`int`，*可选*，默认为 self.unet.config.sample_size * self.vae_scale_factor)：生成图像的宽度（以像素为单位）。默认设置为 1024 以获得最佳效果。对于 [Kwai-Kolors/Kolors-diffusers](https://huggingface.co/Kwai-Kolors/Kolors-diffusers) 以及未在低分辨率上专门微调的检查点，低于 512 像素的宽度效果不佳。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 denoising_end (`float`, *可选*) : 指定时，确定在有意提前终止之前，总去噪过程需要完成的比例（介于 0.0 和 1.0 之间）。因此，返回的样本仍将保留相当多的噪声，具体程度由调度器选择的离散时间步决定。当此管道作为“去噪器混合”多管道设置的一部分时，应理想地使用 denoising_end 参数，如 [**优化图像输出**](https://huggingface.co/docs/diffusers/api/pipelines/stable_diffusion/stable_diffusion_xl#refining-the-image-output) 中所述。 guidance_scale (`float`，*可选*，默认值为 5.0)：如[Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)中定义的引导尺度。`guidance_scale` 定义为[Imagen Paper](https://huggingface.co/papers/2205.11487)中公式 2 的 `w`。通过设置 `guidance_scale > 1` 来启用引导尺度。较高的引导尺度会促使生成与文本 `prompt` 紧密关联的图像，但通常以牺牲图像质量为代价。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 DDIM 论文中的参数 eta (η)：https://huggingface.co/papers/2010.02502。仅适用于 [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，对其他调度器将被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。 latents (`torch.Tensor`, *可选*) : 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 [PIL](https://pillow.readthedocs.io/en/stable/)：`PIL.Image.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~pipelines.kolors.KolorsPipelineOutput` 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。 original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：如果 `original_size` 与 `target_size` 不同，图像将看起来像是被下采样或上采样了。如果未指定，`original_size` 默认为 `(height, width)`。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。 crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：`crops_coords_top_left` 可用于生成一张看似从 `crops_coords_top_left` 位置向下裁剪的图像。通常将 `crops_coords_top_left` 设置为 (0, 0) 即可获得构图良好、居中效果佳的图像。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：在大多数情况下，应将 `target_size` 设置为生成图像所需的宽度和高度。如果未指定，则默认为 `(height, width)`。这是 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述 SDXL 微条件化的一部分。 negative_original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：用于基于特定的图像分辨率对生成过程进行负向条件控制。这是 SDXL 微条件化的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：用于根据特定的裁剪坐标对生成过程施加负向条件。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：用于根据目标图像分辨率对生成过程施加负向条件。在大多数情况下，它应与 `target_size` 相同。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息，请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 max_sequence_length (`int` 默认为 256)：用于 `prompt` 的最大序列长度。 **返回：** `~pipelines.kolors.KolorsPipelineOutput` 或 `tuple` `~pipelines.kolors.KolorsPipelineOutput`（当 `return_dict` 为 True 时），否则为 `tuple`。返回元组时，第一个元素是包含生成图像的列表。 调用生成 pipeline 时调用的函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForText2Image >>> pipe = AutoPipelineForText2Image.from_pretrained( ... "Kwai-Kolors/Kolors-diffusers", ... variant="fp16", ... torch_dtype=torch.float16, ... enable_pag=True, ... pag_applied_layers=["down.block_2.attentions_1", "up.block_0.attentions_1"], ... ) >>> pipe = pipe.to("cuda") >>> prompt = ( ... "A photo of a ladybug, macro, zoom, high quality, film, holding a wooden sign with the text 'KOLORS'" ... ) >>> image = pipe(prompt, guidance_scale=5.5, pag_scale=1.5).images[0] ``` #### encode_prompt[[diffusers.KolorsPAGPipeline.encode_prompt]] ```python encode_prompt(prompt, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 256) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_kolors.py#L216) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，则将从 `prompt` 输入参数生成文本嵌入。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，negative_prompt_embeds 将根据 `negative_prompt` 输入参数生成。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 max_sequence_length (`int` 默认为 256)：用于 `prompt` 的最大序列长度。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.KolorsPAGPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_kolors.py#L608) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionPAGInpaintPipeline[[diffusers.StableDiffusionPAGInpaintPipeline]] #### diffusers.StableDiffusionPAGInpaintPipeline[[diffusers.StableDiffusionPAGInpaintPipeline]] ```python diffusers.StableDiffusionPAGInpaintPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_inpaint.py#L184) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel))：冻结的文本编码器（[clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)）。 tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer))：一个用于对文本进行分词的 `CLIPTokenizer`。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：一个用于对编码后的图像潜变量进行去噪的 `UNet2DConditionModel`。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 safety_checker (`StableDiffusionSafetyChecker`)：分类模块，用于评估生成的图像是否可能被视为冒犯性或有害内容。有关模型潜在危害的更多详细信息，请参阅[模型卡片](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5)。 feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor))：一个 `CLIPImageProcessor`，用于从生成的图像中提取特征；作为 `safety_checker` 的输入。 使用 Stable Diffusion 进行文本到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.StableDiffusionPAGInpaintPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, mask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, masked_image_latents: Tensor = None, height: int | None = None, width: int | None = None, padding_mask_crop: int | None = None, strength: float = 0.9999, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 7.5, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, guidance_rescale: float = 0.0, clip_skip: int | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_inpaint.py#L910) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则需要传入 `prompt_embeds`。 image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]` 或 `list[np.ndarray]`) : `Image`、numpy 数组或张量，表示要执行图像修复的图像批次（即根据 `prompt` 对 `mask_image` 中指定为掩码的图像区域进行重绘）。 mask_image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]` 或 `list[np.ndarray]`) : `Image`、numpy 数组或张量，表示用于对 `image` 进行遮罩处理的图像批次。遮罩中的白色像素将被重绘，而黑色像素将保留。如果 `mask_image` 是 PIL 图像，则在使用前会将其转换为单通道（亮度）。如果它是 numpy 数组或 PyTorch 张量，则应包含一个颜色通道（L）而不是三个，因此 PyTorch 张量的预期形状为 `(B, 1, H, W)`、`(B, H, W)`、`(1, H, W)` 或 `(H, W)`。而 numpy 数组的预期形状为 `(B, H, W, 1)`、`(B, H, W)`、`(H, W, 1)` 或 `(H, W)`。 masked_image_latents (`torch.Tensor`, *可选*) : 掩码图像的预编码潜在表示（用于图像修复）。 height (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成图像的高度（以像素为单位）。 width (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成图像的像素宽度。 padding_mask_crop (`int`, *可选*，默认为 `None`) : 应用于图像和掩码的裁剪边距大小。如果为 `None`，则不对 image 和 mask_image 进行裁剪。如果 `padding_mask_crop` 不为 `None`，则会先找到一个与图像具有相同宽高比且包含所有掩码区域的矩形区域，然后根据 `padding_mask_crop` 扩展该区域。随后，在将图像和 mask_image 调整回原始图像尺寸以进行修复之前，会基于扩展后的区域对它们进行裁剪。当掩码区域较小而图像较大，且包含与修复无关的信息（例如背景）时，此功能非常有用。 strength (`float`, *可选*，默认值为 0.9999)：指示对参考 `image` 进行变换的程度。取值必须在 0 到 1 之间。`image` 用作起始点，`strength` 越高，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 `strength` 为 1 时，添加的噪声达到最大值，去噪过程将运行 `num_inference_steps` 中指定的完整迭代次数。值为 1 时，基本上会忽略 `image`。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 guidance_scale (`float`, *可选*，默认值为 7.5)：较高的 guidance scale 值会促使模型生成与文本 `prompt` 紧密相关的图像，但代价是图像质量降低。当 `guidance_scale > 1` 时，guidance scale 生效。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 `negative_prompt_embeds`。在未使用引导（`guidance_scale < 1`）时将被忽略。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 [DDIM](https://huggingface.co/papers/2010.02502) 论文中的参数 eta (η)。仅适用于 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，在其他调度器中会被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：用于使生成过程确定性的 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)。 latents (`torch.Tensor`, *可选*) : 从高斯分布中采样的预生成噪声潜变量，用作图像生成的输入。可用于以不同的提示词微调同一生成过程。如果未提供，则使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。在 `PIL.Image` 或 `np.array` 之间选择。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为 [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中定义的 `AttentionProcessor` 的参数传递。 guidance_rescale (`float`, *可选*，默认为 0.0) : 来自 [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) 的 guidance rescale 因子。当使用 zero terminal SNR 时，guidance rescale 因子应可修复过度曝光问题。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 或 `tuple` 如果 `return_dict` 为 `True`，则返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)；否则返回一个 `tuple`，其中第一个元素是包含生成图像的列表，第二个元素是 `bool` 列表，用于指示对应的生成图像是否包含“不适合工作场所”（nsfw）内容。 用于生成的 pipeline 的调用函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForInpainting >>> pipe = AutoPipelineForInpainting.from_pretrained( ... "stable-diffusion-v1-5/stable-diffusion-v1-5", torch_dtype=torch.float16, enable_pag=True ... ) >>> pipe = pipe.to("cuda") >>> img_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo.png" >>> mask_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo_mask.png" >>> init_image = load_image(img_url).convert("RGB") >>> mask_image = load_image(mask_url).convert("RGB") >>> prompt = "A majestic tiger sitting on a bench" >>> image = pipe( ... prompt=prompt, ... image=init_image, ... mask_image=mask_image, ... strength=0.8, ... num_inference_steps=50, ... guidance_scale=guidance_scale, ... generator=generator, ... pag_scale=pag_scale, ... ).images[0] ``` #### encode_prompt[[diffusers.StableDiffusionPAGInpaintPipeline.encode_prompt]] ```python encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_inpaint.py#L334) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionPAGInpaintPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_inpaint.py#L849) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionPAGPipeline[[diffusers.StableDiffusionPAGPipeline]] #### diffusers.StableDiffusionPAGPipeline[[diffusers.StableDiffusionPAGPipeline]] ```python diffusers.StableDiffusionPAGPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd.py#L157) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel))：冻结的文本编码器（[clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)）。 tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer))：一个用于对文本进行分词的 `CLIPTokenizer`。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：一个用于对编码后的图像潜变量进行去噪的 `UNet2DConditionModel`。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 safety_checker (`StableDiffusionSafetyChecker`)：分类模块，用于评估生成的图像是否可能被视为冒犯性或有害内容。有关模型潜在危害的更多详细信息，请参阅[模型卡片](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5)。 feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor))：一个 `CLIPImageProcessor`，用于从生成的图像中提取特征；作为 `safety_checker` 的输入。 使用 Stable Diffusion 进行文本到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.StableDiffusionPAGPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 7.5, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, guidance_rescale: float = 0.0, clip_skip: int | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd.py#L745) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则需要传入 `prompt_embeds`。 height (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成图像的高度（以像素为单位）。 width (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成图像的像素宽度。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 guidance_scale (`float`, *可选*，默认值为 7.5)：较高的 guidance scale 值会促使模型生成与文本 `prompt` 紧密相关的图像，但代价是图像质量降低。当 `guidance_scale > 1` 时，guidance scale 生效。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 `negative_prompt_embeds`。在未使用引导（`guidance_scale < 1`）时将被忽略。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 [DDIM](https://huggingface.co/papers/2010.02502) 论文中的参数 eta (η)。仅适用于 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，在其他调度器中会被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：用于使生成过程确定性的 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)。 latents (`torch.Tensor`, *可选*) : 从高斯分布中采样的预生成噪声潜变量，用作图像生成的输入。可用于以不同的提示词微调同一生成过程。如果未提供，则使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。在 `PIL.Image` 或 `np.array` 之间选择。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为 [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中定义的 `AttentionProcessor` 的参数传递。 guidance_rescale (`float`, *可选*，默认为 0.0) : 来自 [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) 的 guidance rescale 因子。当使用 zero terminal SNR 时，guidance rescale 因子应可修复过度曝光问题。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 或 `tuple` 如果 `return_dict` 为 `True`，则返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)；否则返回一个 `tuple`，其中第一个元素是包含生成图像的列表，第二个元素是 `bool` 列表，用于指示对应的生成图像是否包含“不适合工作场所”（nsfw）内容。 用于生成的 pipeline 的调用函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForText2Image >>> pipe = AutoPipelineForText2Image.from_pretrained( ... "stable-diffusion-v1-5/stable-diffusion-v1-5", torch_dtype=torch.float16, enable_pag=True ... ) >>> pipe = pipe.to("cuda") >>> prompt = "a photo of an astronaut riding a horse on mars" >>> image = pipe(prompt, pag_scale=0.3).images[0] ``` #### encode_prompt[[diffusers.StableDiffusionPAGPipeline.encode_prompt]] ```python encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd.py#L304) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionPAGPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd.py#L684) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionPAGImg2ImgPipeline[[diffusers.StableDiffusionPAGImg2ImgPipeline]] #### diffusers.StableDiffusionPAGImg2ImgPipeline[[diffusers.StableDiffusionPAGImg2ImgPipeline]] ```python diffusers.StableDiffusionPAGImg2ImgPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_img2img.py#L152) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel))：冻结的文本编码器（[clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)）。 tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer))：一个用于对文本进行分词的 `CLIPTokenizer`。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：一个用于对编码后的图像潜变量进行去噪的 `UNet2DConditionModel`。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 safety_checker (`StableDiffusionSafetyChecker`)：分类模块，用于评估生成的图像是否可能被视为冒犯性或有害内容。有关模型潜在危害的更多详细信息，请参阅[模型卡片](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5)。 feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor))：一个 `CLIPImageProcessor`，用于从生成的图像中提取特征；作为 `safety_checker` 的输入。 使用 Stable Diffusion 进行文本引导的图像到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.StableDiffusionPAGImg2ImgPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, strength: float = 0.8, num_inference_steps: int | None = 50, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float | None = 7.5, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float | None = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, clip_skip: int = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_img2img.py#L782) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则需要传入 `prompt_embeds`。 image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]` 或 `list[np.ndarray]`) : `Image`、numpy 数组或张量，表示用作起点的图像批次。对于 numpy 数组和 PyTorch 张量，预期的值范围为 `[0, 1]`。如果是张量或张量列表，预期的形状应为 `(B, C, H, W)` 或 `(C, H, W)`。如果是 numpy 数组或数组列表，预期的形状应为 `(B, H, W, C)` 或 `(H, W, C)`。它也可以接受图像潜变量作为 `image`，但如果直接传入潜变量，则不会再次进行编码。 strength (`float`，*可选*，默认值为 0.8)：指示对参考 `image` 进行变换的程度。取值必须在 0 到 1 之间。`image` 用作起始点，`strength` 越高，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 `strength` 为 1 时，添加的噪声达到最大值，去噪过程将运行 `num_inference_steps` 中指定的完整迭代次数。值为 1 时，基本上会忽略 `image`。 num_inference_steps (`int`，*可选*，默认值为 50)：去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。此参数受 `strength` 调节。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 guidance_scale (`float`, *可选*，默认值为 7.5)：较高的 guidance scale 值会促使模型生成与文本 `prompt` 紧密相关的图像，但代价是图像质量降低。当 `guidance_scale > 1` 时，guidance scale 生效。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 `negative_prompt_embeds`。在未使用引导（`guidance_scale < 1`）时将被忽略。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 [DDIM](https://huggingface.co/papers/2010.02502) 论文中的参数 eta (η)。仅适用于 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，在其他调度器中会被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：用于使生成过程确定性的 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。在 `PIL.Image` 或 `np.array` 之间选择。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为 [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中定义的 `AttentionProcessor` 的参数传递。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 或 `tuple` 如果 `return_dict` 为 `True`，则返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)；否则返回一个 `tuple`，其中第一个元素是包含生成图像的列表，第二个元素是 `bool` 列表，用于指示对应的生成图像是否包含“不适合工作场所”（nsfw）内容。 用于生成的 pipeline 的调用函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForImage2Image >>> from diffusers.utils import load_image >>> pipe = AutoPipelineForImage2Image.from_pretrained( ... "stable-diffusion-v1-5/stable-diffusion-v1-5", ... torch_dtype=torch.float16, ... enable_pag=True, ... ) >>> pipe = pipe.to("cuda") >>> url = "https://huggingface.co/datasets/patrickvonplaten/images/resolve/main/aa_xl/000000009.png" >>> init_image = load_image(url).convert("RGB") >>> prompt = "a photo of an astronaut riding a horse on mars" >>> image = pipe(prompt, image=init_image, pag_scale=0.3).images[0] ``` #### encode_prompt[[diffusers.StableDiffusionPAGImg2ImgPipeline.encode_prompt]] ```python encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_img2img.py#L299) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionPAGImg2ImgPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_img2img.py#L725) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionControlNetPAGPipeline[[diffusers.StableDiffusionControlNetPAGPipeline]] #### diffusers.StableDiffusionControlNetPAGPipeline[[diffusers.StableDiffusionControlNetPAGPipeline]] ```python diffusers.StableDiffusionControlNetPAGPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet.ControlNetModel | list[diffusers.models.controlnets.controlnet.ControlNetModel] | tuple[diffusers.models.controlnets.controlnet.ControlNetModel] | diffusers.models.controlnets.multicontrolnet.MultiControlNetModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd.py#L168) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel))：冻结的文本编码器（[clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)）。 tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer))：一个用于对文本进行分词的 `CLIPTokenizer`。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：一个用于对编码后的图像潜变量进行去噪的 `UNet2DConditionModel`。 controlnet ([ControlNetModel](/docs/diffusers/v0.43.0/zh/api/models/controlnet#diffusers.ControlNetModel) 或 `list[ControlNetModel]`)：在去噪过程中为 `unet` 提供额外的条件输入。如果以列表形式设置多个 ControlNet，则会将每个 ControlNet 的输出相加，以生成一个合并的额外条件输入。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 safety_checker (`StableDiffusionSafetyChecker`)：分类模块，用于评估生成的图像是否可能被视为冒犯性或有害内容。有关模型潜在危害的更多详细信息，请参阅[模型卡片](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5)。 feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor))：一个 `CLIPImageProcessor`，用于从生成的图像中提取特征；作为 `safety_checker` 的输入。 使用带有 ControlNet 引导的 Stable Diffusion 进行文本到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### encode_prompt[[diffusers.StableDiffusionControlNetPAGPipeline.encode_prompt]] ```python encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd.py#L275) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionControlNetPAGPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd.py#L810) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionControlNetPAGInpaintPipeline[[diffusers.StableDiffusionControlNetPAGInpaintPipeline]] #### diffusers.StableDiffusionControlNetPAGInpaintPipeline[[diffusers.StableDiffusionControlNetPAGInpaintPipeline]] ```python diffusers.StableDiffusionControlNetPAGInpaintPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet.ControlNetModel | list[diffusers.models.controlnets.controlnet.ControlNetModel] | tuple[diffusers.models.controlnets.controlnet.ControlNetModel] | diffusers.models.controlnets.multicontrolnet.MultiControlNetModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_inpaint.py#L134) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel))：冻结的文本编码器（[clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)）。 tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer))：一个用于对文本进行分词的 `CLIPTokenizer`。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：一个用于对编码后的图像潜变量进行去噪的 `UNet2DConditionModel`。 controlnet ([ControlNetModel](/docs/diffusers/v0.43.0/zh/api/models/controlnet#diffusers.ControlNetModel) 或 `list[ControlNetModel]`)：在去噪过程中为 `unet` 提供额外的条件输入。如果以列表形式设置多个 ControlNet，则会将每个 ControlNet 的输出相加，以生成一个合并的额外条件输入。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 safety_checker (`StableDiffusionSafetyChecker`)：分类模块，用于评估生成的图像是否可能被视为冒犯性或有害内容。有关模型潜在危害的更多详细信息，请参阅[模型卡片](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5)。 feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor))：一个 `CLIPImageProcessor`，用于从生成的图像中提取特征；作为 `safety_checker` 的输入。 使用 Stable Diffusion 并结合 ControlNet 引导进行图像修复的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) > [!TIP] > 此流水线可用于专门针对图像修复（inpainting）进行微调的检查点 > （[stable-diffusion-v1-5/stable-diffusion-inpainting](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-inpainting)）以及 > 默认的文本到图像 Stable Diffusion 检查点 > ([stable-diffusion-v1-5/stable-diffusion-v1-5](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5))。对于在这些检查点上经过微调的 ControlNet，例如 > [lllyasviel/control_v11p_sd15_inpaint](https://huggingface.co/lllyasviel/control_v11p_sd15_inpaint)，使用默认的文本到图像 > Stable Diffusion 检查点可能更为合适。 #### __调用__[[diffusers.StableDiffusionControlNetPAGInpaintPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, mask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, height: int | None = None, width: int | None = None, padding_mask_crop: int | None = None, strength: float = 1.0, num_inference_steps: int = 50, guidance_scale: float = 7.5, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 0.5, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_inpaint.py#L972) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则需要传入 `prompt_embeds`。 image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]` 或 `list[np.ndarray]`)：用作起始点的 `Image`、NumPy 数组或张量，表示一个图像批次。对于 NumPy 数组和 PyTorch 张量，预期的取值范围为 `[0, 1]`。如果它是张量或张量列表，预期的形状应为 `(B, C, H, W)` 或 `(C, H, W)`。如果它是 NumPy 数组或数组列表，预期的形状应为 `(B, H, W, C)` 或 `(H, W, C)`。它也可以接受图像潜变量作为 `image`，但如果直接传入潜变量，则不会再次进行编码。 mask_image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]` 或 `list[np.ndarray]`)：用于对 `image` 进行遮罩的 `Image`、NumPy 数组或张量，表示一个图像批次。遮罩中的白色像素将被重绘，而黑色像素将保留。如果 `mask_image` 是 PIL 图像，则在使用前会将其转换为单通道（亮度）。如果它是 NumPy 数组或 PyTorch 张量，则应包含一个颜色通道（L）而不是三个，因此 PyTorch 张量的预期形状为 `(B, 1, H, W)`、`(B, H, W)`、`(1, H, W)` 或 `(H, W)`。对于 NumPy 数组，其形状应为 `(B, H, W, 1)`、`(B, H, W)`、`(H, W, 1)` 或 `(H, W)`。 control_image (`torch.Tensor`、`PIL.Image.Image`、`list[torch.Tensor]`、`list[PIL.Image.Image]`、`list[list[torch.Tensor]]` 或 `list[list[PIL.Image.Image]]`)：用于为 `unet` 提供生成引导的 ControlNet 输入条件。如果类型指定为 `torch.Tensor`，则会按原样传递给 ControlNet。也可以接受 `PIL.Image.Image` 作为图像。输出图像的默认尺寸与 `image` 的尺寸相同。如果传入了高度和/或宽度，`image` 将相应地调整大小。如果在 `init` 中指定了多个 ControlNet，则必须以列表形式传入图像，以便列表中的每个元素都能被正确批处理，作为单个 ControlNet 的输入。 height (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成图像的高度（以像素为单位）。 width (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成图像的像素宽度。 padding_mask_crop (`int`, *可选*，默认为 `None`) : 应用于图像和掩码的裁剪边距大小。如果为 `None`，则不对 image 和 mask_image 进行裁剪。如果 `padding_mask_crop` 不为 `None`，则会先找到一个与图像具有相同宽高比且包含所有掩码区域的矩形区域，然后根据 `padding_mask_crop` 扩展该区域。随后，在将图像和 mask_image 调整回原始图像尺寸以进行修复之前，会基于扩展后的区域对它们进行裁剪。当掩码区域较小而图像较大，且包含与修复无关的信息（例如背景）时，此功能非常有用。 strength (`float`, *可选*，默认为 1.0)：指示对参考 `image` 进行变换的程度。取值必须在 0 到 1 之间。`image` 用作起始点，`strength` 越高，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 `strength` 为 1 时，添加的噪声达到最大值，去噪过程将运行 `num_inference_steps` 中指定的完整迭代次数。值为 1 时，基本上会忽略 `image`。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 guidance_scale (`float`, *可选*，默认值为 7.5)：较高的 guidance scale 值会促使模型生成与文本 `prompt` 紧密相关的图像，但代价是图像质量降低。当 `guidance_scale > 1` 时，guidance scale 生效。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 `negative_prompt_embeds`。在未使用引导（`guidance_scale < 1`）时将被忽略。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 [DDIM](https://huggingface.co/papers/2010.02502) 论文中的参数 eta (η)。仅适用于 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，在其他调度器中会被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：用于使生成过程确定性的 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)。 latents (`torch.Tensor`, *可选*) : 从高斯分布中采样的预生成噪声潜变量，用作图像生成的输入。可用于以不同的提示词微调同一生成过程。如果未提供，则使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。在 `PIL.Image` 或 `np.array` 之间选择。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为 [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中定义的 `AttentionProcessor` 的参数传递。 controlnet_conditioning_scale (`float` 或 `list[float]`，*可选*，默认为 0.5) : ControlNet 的输出在加到原始 `unet` 的残差之前，会先乘以 `controlnet_conditioning_scale`。如果在 `init` 中指定了多个 ControlNet，可以将对应的 scale 设置为列表。 control_guidance_start (`float` 或 `list[float]`，*可选*，默认为 0.0)：ControlNet 开始生效的总步数百分比。 control_guidance_end (`float` 或 `list[float]`，*可选*，默认为 1.0)：ControlNet 停止应用时的总步数百分比。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 或 `tuple` 如果 `return_dict` 为 `True`，则返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)；否则返回一个 `tuple`，其中第一个元素是包含生成图像的列表，第二个元素是 `bool` 列表，用于指示对应的生成图像是否包含“不适合工作场所”（nsfw）内容。 用于生成的 pipeline 的调用函数。 示例： ```py >>> # !pip install transformers accelerate >>> import cv2 >>> from diffusers import AutoPipelineForInpainting, ControlNetModel, DDIMScheduler >>> from diffusers.utils import load_image >>> import numpy as np >>> from PIL import Image >>> import torch >>> init_image = load_image( ... "https://huggingface.co/datasets/diffusers/test-arrays/resolve/main/stable_diffusion_inpaint/boy.png" ... ) >>> init_image = init_image.resize((512, 512)) >>> generator = torch.Generator(device="cpu").manual_seed(1) >>> mask_image = load_image( ... "https://huggingface.co/datasets/diffusers/test-arrays/resolve/main/stable_diffusion_inpaint/boy_mask.png" ... ) >>> mask_image = mask_image.resize((512, 512)) >>> def make_canny_condition(image): ... image = np.array(image) ... image = cv2.Canny(image, 100, 200) ... image = image[:, :, None] ... image = np.concatenate([image, image, image], axis=2) ... image = Image.fromarray(image) ... return image >>> control_image = make_canny_condition(init_image) >>> controlnet = ControlNetModel.from_pretrained( ... "lllyasviel/control_v11p_sd15_inpaint", torch_dtype=torch.float16 ... ) >>> pipe = AutoPipelineForInpainting.from_pretrained( ... "stable-diffusion-v1-5/stable-diffusion-v1-5", ... controlnet=controlnet, ... torch_dtype=torch.float16, ... enable_pag=True, ... ) >>> pipe.scheduler = DDIMScheduler.from_config(pipe.scheduler.config) >>> pipe.enable_model_cpu_offload() >>> # generate image >>> image = pipe( ... "a handsome man with ray-ban sunglasses", ... num_inference_steps=20, ... generator=generator, ... eta=1.0, ... image=init_image, ... mask_image=mask_image, ... control_image=control_image, ... pag_scale=0.3, ... ).images[0] ``` #### encode_prompt[[diffusers.StableDiffusionControlNetPAGInpaintPipeline.encode_prompt]] ```python encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_inpaint.py#L251) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionControlNetPAGInpaintPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_inpaint.py#L919) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionXLPAGPipeline[[diffusers.StableDiffusionXLPAGPipeline]] #### diffusers.StableDiffusionXLPAGPipeline[[diffusers.StableDiffusionXLPAGPipeline]] ```python diffusers.StableDiffusionXLPAGPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl.py#L172) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder (`CLIPTextModel`)：冻结的文本编码器。Stable Diffusion XL 使用 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel) 的文本部分，具体为 [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14) 变体。 text_encoder_2 (` CLIPTextModelWithProjection`)：第二个冻结的文本编码器。Stable Diffusion XL 使用 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection) 的文本和池化部分，具体为 [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k) 变体。 tokenizer (`CLIPTokenizer`)：[CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的分词器。 tokenizer_2 (`CLIPTokenizer`)：第二个 [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的 Tokenizer。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：用于对编码后的图像潜变量进行去噪的条件 U-Net 架构。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 force_zeros_for_empty_prompt (`bool`，*可选*，默认为 `"True"`)：是否强制将负提示嵌入始终设置为 0。另请参阅 `stabilityai/stable-diffusion-xl-base-1-0` 的配置。 add_watermarker (`bool`，*可选*)：是否使用 [invisible_watermark 库](https://github.com/ShieldMnt/invisible-watermark/) 为输出图像添加水印。如果未定义，则当该包已安装时默认为 True，否则不使用水印。 使用 Stable Diffusion XL 进行文本到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。请查阅父类文档，了解该库为所有 pipeline 实现的通用方法（例如下载或保存、在特定设备上运行等）。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.StableDiffusionXLPAGPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, denoising_end: float | None = None, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, guidance_rescale: float = 0.0, original_size: tuple[int, int] | None = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] | None = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, clip_skip: int | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl.py#L836) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 `prompt_embeds`。 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 height (`int`，*可选*，默认为 self.unet.config.sample_size * self.vae_scale_factor)：生成图像的高度（以像素为单位）。默认设置为 1024 以获得最佳效果。对于 [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) 以及未在低分辨率上专门微调的检查点，低于 512 像素的效果不佳。 width (`int`，*可选*，默认为 self.unet.config.sample_size * self.vae_scale_factor)：生成图像的像素宽度。默认设置为 1024 以获得最佳效果。对于 [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) 以及未在低分辨率上专门微调的检查点，低于 512 像素的宽度效果不佳。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 denoising_end (`float`, *可选*) : 指定时，确定在有意提前终止之前，总去噪过程需要完成的比例（介于 0.0 和 1.0 之间）。因此，返回的样本仍将保留相当多的噪声，具体程度由调度器选择的离散时间步决定。当此管道作为“去噪器混合”多管道设置的一部分时，应理想地使用 denoising_end 参数，如 [**优化图像输出**](https://huggingface.co/docs/diffusers/api/pipelines/stable_diffusion/stable_diffusion_xl#refining-the-image-output) 中所述。 guidance_scale (`float`，*可选*，默认值为 5.0)：如[Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)中定义的引导尺度。`guidance_scale` 定义为[Imagen Paper](https://huggingface.co/papers/2205.11487)中公式 2 的 `w`。通过设置 `guidance_scale > 1` 来启用引导尺度。较高的引导尺度会促使生成与文本 `prompt` 紧密关联的图像，但通常以牺牲图像质量为代价。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 DDIM 论文中的参数 eta (η)：https://huggingface.co/papers/2010.02502。仅适用于 [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，对其他调度器将被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。 latents (`torch.Tensor`, *可选*) : 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 [PIL](https://pillow.readthedocs.io/en/stable/)：`PIL.Image.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。 guidance_rescale (`float`, *optional*, defaults to 0.0) : Guidance rescale factor proposed by [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) `guidance_scale` is defined as `φ` in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Guidance rescale factor should fix overexposure when using zero terminal SNR. original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：如果 `original_size` 与 `target_size` 不同，图像将看起来像是被下采样或上采样了。如果未指定，`original_size` 默认为 `(height, width)`。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。 crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：`crops_coords_top_left` 可用于生成一张看似从 `crops_coords_top_left` 位置向下裁剪的图像。通常将 `crops_coords_top_left` 设置为 (0, 0) 即可获得构图良好、居中效果佳的图像。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：在大多数情况下，应将 `target_size` 设置为生成图像所需的宽度和高度。如果未指定，则默认为 `(height, width)`。这是 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述 SDXL 微条件化的一部分。 negative_original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：用于基于特定的图像分辨率对生成过程进行负向条件控制。这是 SDXL 微条件化的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：用于根据特定的裁剪坐标对生成过程施加负向条件。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：用于根据目标图像分辨率对生成过程施加负向条件。在大多数情况下，它应与 `target_size` 相同。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息，请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` 或 `tuple` 如果 `return_dict` 为 True，则返回 `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput`，否则返回 `tuple`。当返回元组时，第一个元素是一个包含生成图像的列表。 调用生成 pipeline 时调用的函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForText2Image >>> pipe = AutoPipelineForText2Image.from_pretrained( ... "stabilityai/stable-diffusion-xl-base-1.0", ... torch_dtype=torch.float16, ... enable_pag=True, ... ) >>> pipe = pipe.to("cuda") >>> prompt = "a photo of an astronaut riding a horse on mars" >>> image = pipe(prompt, pag_scale=0.3).images[0] ``` #### encode_prompt[[diffusers.StableDiffusionXLPAGPipeline.encode_prompt]] ```python encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl.py#L293) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionXLPAGPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl.py#L771) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionXLPAGImg2ImgPipeline[[diffusers.StableDiffusionXLPAGImg2ImgPipeline]] #### diffusers.StableDiffusionXLPAGImg2ImgPipeline[[diffusers.StableDiffusionXLPAGImg2ImgPipeline]] ```python diffusers.StableDiffusionXLPAGImg2ImgPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None, requires_aesthetics_score: bool = False, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl_img2img.py#L191) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder (`CLIPTextModel`)：冻结的文本编码器。Stable Diffusion XL 使用 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel) 的文本部分，具体为 [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14) 变体。 text_encoder_2 (` CLIPTextModelWithProjection`)：第二个冻结的文本编码器。Stable Diffusion XL 使用 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection) 的文本和池化部分，具体为 [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k) 变体。 tokenizer (`CLIPTokenizer`)：[CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的分词器。 tokenizer_2 (`CLIPTokenizer`)：第二个 [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的 Tokenizer。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：用于对编码后的图像潜变量进行去噪的条件 U-Net 架构。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 requires_aesthetics_score (`bool`，*可选*，默认为 `"False"`)：指示 `unet` 在推理时是否需要传入 `aesthetic_score` 条件。另请参阅 `stabilityai/stable-diffusion-xl-refiner-1-0` 的配置。 force_zeros_for_empty_prompt (`bool`，*可选*，默认为 `"True"`)：是否强制将负提示嵌入始终设置为 0。另请参阅 `stabilityai/stable-diffusion-xl-base-1-0` 的配置。 add_watermarker (`bool`，*可选*)：是否使用 [invisible_watermark 库](https://github.com/ShieldMnt/invisible-watermark/) 为输出图像添加水印。如果未定义，则当该包已安装时默认为 True，否则不使用水印。 使用 Stable Diffusion XL 进行文本到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。请查阅父类文档，了解该库为所有 pipeline 实现的通用方法（例如下载或保存、在特定设备上运行等）。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.StableDiffusionXLPAGImg2ImgPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, strength: float = 0.3, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, denoising_start: float | None = None, denoising_end: float | None = None, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, guidance_rescale: float = 0.0, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, aesthetic_score: float = 6.0, negative_aesthetic_score: float = 2.5, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl_img2img.py#L989) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 `prompt_embeds`。 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 image (`torch.Tensor` 或 `PIL.Image.Image` 或 `np.ndarray` 或 `list[torch.Tensor]` 或 `list[PIL.Image.Image]` 或 `list[np.ndarray]`)：要使用 pipeline 修改的图像。 strength (`float`, *可选*，默认为 0.3)：从概念上讲，表示对参考 `image` 进行多大程度的变换。取值必须在 0 到 1 之间。`image` 将作为起点，`strength` 越大，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 `strength` 为 1 时，添加的噪声达到最大值，去噪过程将运行 `num_inference_steps` 中指定的完整迭代次数。因此，值为 1 时实际上会忽略 `image`。请注意，如果 `denoising_start` 被声明为整数，则 `strength` 的值将被忽略。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 denoising_start (`float`, *可选*) : 指定时，表示在去噪过程启动前需要跳过的总去噪过程的比例（介于 0.0 和 1.0 之间）。因此，去噪过程的初始部分将被跳过，并假定传入的 `image` 是一张部分去噪的图像。请注意，当指定此参数时，strength 将被忽略。`denoising_start` 参数在将此管道集成到“去噪器混合”多管道设置中时特别有用，详见 [**提升图像质量**](https://huggingface.co/docs/diffusers/using-diffusers/sdxl#refine-image-quality)。 denoising_end (`float`, *可选*) : 指定后，用于确定在有意提前终止之前，总去噪过程需要完成的比例（介于 0.0 和 1.0 之间）。因此，返回的样本仍将保留大量噪声（大约还需要最后 20% 的时间步），并且应由一个将 `denoising_start` 设置为 0.8 的后续流水线进行去噪，使其仅对调度器的最后 20% 进行去噪。理想情况下，当此流水线作为“去噪器混合”多流水线设置的一部分时，应使用 denoising_end 参数，如 [**提升图像质量**](https://huggingface.co/docs/diffusers/using-diffusers/sdxl#refine-image-quality) 中所述。 guidance_scale (`float`，*可选*，默认值为 7.5)：如[Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)中定义的引导尺度。`guidance_scale` 定义为[Imagen Paper](https://huggingface.co/papers/2205.11487)中公式 2 的 `w`。通过设置 `guidance_scale > 1` 来启用引导尺度。较高的引导尺度会促使生成与文本 `prompt` 紧密关联的图像，但通常以牺牲图像质量为代价。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 DDIM 论文中的参数 eta (η)：https://huggingface.co/papers/2010.02502。仅适用于 [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，对其他调度器将被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。 latents (`torch.Tensor`, *可选*) : 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 [PIL](https://pillow.readthedocs.io/en/stable/)：`PIL.Image.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput` 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。 guidance_rescale (`float`, *optional*, defaults to 0.0) : Guidance rescale factor proposed by [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) `guidance_scale` is defined as `φ` in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Guidance rescale factor should fix overexposure when using zero terminal SNR. original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：如果 `original_size` 与 `target_size` 不同，图像将看起来像是被下采样或上采样了。如果未指定，`original_size` 默认为 `(height, width)`。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。 crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：`crops_coords_top_left` 可用于生成一张看似从 `crops_coords_top_left` 位置向下裁剪的图像。通常将 `crops_coords_top_left` 设置为 (0, 0) 即可获得构图良好、居中效果佳的图像。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：在大多数情况下，应将 `target_size` 设置为生成图像所需的宽度和高度。如果未指定，则默认为 `(height, width)`。这是 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述 SDXL 微条件化的一部分。 negative_original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：用于基于特定的图像分辨率对生成过程进行负向条件控制。这是 SDXL 微条件化的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：用于根据特定的裁剪坐标对生成过程施加负向条件。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：用于根据目标图像分辨率对生成过程施加负向条件。在大多数情况下，它应与 `target_size` 相同。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息，请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 aesthetic_score (`float`，*可选*，默认值为 6.0)：用于通过影响正向文本条件来模拟生成图像的美学评分。这是 SDXL 微条件化的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 negative_aesthetic_score (`float`，*可选*，默认值为 2.5)：[https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述的 SDXL 微条件（micro-conditioning）的一部分。可通过影响负向文本条件来模拟生成图像的美学评分。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** `~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput` 或 `tuple` 如果 `return_dict` 为 True，则返回 `~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput`，否则返回一个 `tuple。当返回元组时，第一个元素是一个包含生成图像的列表。 调用生成 pipeline 时调用的函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForImage2Image >>> from diffusers.utils import load_image >>> pipe = AutoPipelineForImage2Image.from_pretrained( ... "stabilityai/stable-diffusion-xl-refiner-1.0", ... torch_dtype=torch.float16, ... enable_pag=True, ... ) >>> pipe = pipe.to("cuda") >>> url = "https://huggingface.co/datasets/patrickvonplaten/images/resolve/main/aa_xl/000000009.png" >>> init_image = load_image(url).convert("RGB") >>> prompt = "a photo of an astronaut riding a horse on mars" >>> image = pipe(prompt, image=init_image, pag_scale=0.3).images[0] ``` #### encode_prompt[[diffusers.StableDiffusionXLPAGImg2ImgPipeline.encode_prompt]] ```python encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl_img2img.py#L311) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionXLPAGImg2ImgPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl_img2img.py#L920) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionXLPAGInpaintPipeline[[diffusers.StableDiffusionXLPAGInpaintPipeline]] #### diffusers.StableDiffusionXLPAGInpaintPipeline[[diffusers.StableDiffusionXLPAGInpaintPipeline]] ```python diffusers.StableDiffusionXLPAGInpaintPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None, requires_aesthetics_score: bool = False, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl_inpaint.py#L204) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder (`CLIPTextModel`)：冻结的文本编码器。Stable Diffusion XL 使用 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel) 的文本部分，具体为 [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14) 变体。 text_encoder_2 (` CLIPTextModelWithProjection`)：第二个冻结的文本编码器。Stable Diffusion XL 使用 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection) 的文本和池化部分，具体为 [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k) 变体。 tokenizer (`CLIPTokenizer`)：[CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的分词器。 tokenizer_2 (`CLIPTokenizer`)：第二个 [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的 Tokenizer。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：用于对编码后的图像潜变量进行去噪的条件 U-Net 架构。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 requires_aesthetics_score (`bool`，*可选*，默认为 `"False"`)：指示在推理期间是否要求向 `unet` 传递 aesthetic_score 条件。另请参阅 `stabilityai/stable-diffusion-xl-refiner-1-0` 的配置。 force_zeros_for_empty_prompt (`bool`，*可选*，默认为 `"True"`)：是否强制将负提示嵌入始终设置为 0。另请参阅 `stabilityai/stable-diffusion-xl-base-1-0` 的配置。 add_watermarker (`bool`，*可选*)：是否使用 [invisible_watermark 库](https://github.com/ShieldMnt/invisible-watermark/) 为输出图像添加水印。如果未定义，则当该包已安装时默认为 True，否则不使用水印。 使用 Stable Diffusion XL 进行文本到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。请查阅父类文档，了解该库为所有 pipeline 实现的通用方法（例如下载或保存、在特定设备上运行等）。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.StableDiffusionXLPAGInpaintPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, mask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, masked_image_latents: Tensor = None, height: int | None = None, width: int | None = None, padding_mask_crop: int | None = None, strength: float = 0.9999, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, denoising_start: float | None = None, denoising_end: float | None = None, guidance_scale: float = 7.5, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, guidance_rescale: float = 0.0, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, aesthetic_score: float = 6.0, negative_aesthetic_score: float = 2.5, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl_inpaint.py#L1080) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 `prompt_embeds`。 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 image (`PIL.Image.Image`) : `Image`，或表示将进行修复的图像批次的张量，*即*图像的部分区域将被 `mask_image` 掩码，并根据 `prompt` 重新绘制。 mask_image (`PIL.Image.Image`) : `Image`，或表示图像批次的张量，用于对 `image` 进行遮罩。遮罩中的白色像素将被重绘，而黑色像素将保留。如果 `mask_image` 是 PIL 图像，在使用前会先转换为单通道（亮度）。如果它是张量，则应包含一个颜色通道（L）而不是三个，因此预期的形状为 `(B, H, W, 1)`。 masked_image_latents (`torch.Tensor`, *可选*) : 掩码图像的预编码潜在表示（用于图像修复）。 height (`int`，*可选*，默认为 self.unet.config.sample_size * self.vae_scale_factor)：生成图像的高度（以像素为单位）。默认设置为 1024 以获得最佳效果。对于 [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) 以及未在低分辨率上专门微调的检查点，低于 512 像素的效果不佳。 width (`int`，*可选*，默认为 self.unet.config.sample_size * self.vae_scale_factor)：生成图像的像素宽度。默认设置为 1024 以获得最佳效果。对于 [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) 以及未在低分辨率上专门微调的检查点，低于 512 像素的宽度效果不佳。 padding_mask_crop (`int`, *可选*，默认为 `None`) : 应用于图像和掩码的裁剪边距大小。如果为 `None`，则不对 image 和 mask_image 进行裁剪。如果 `padding_mask_crop` 不为 `None`，则会先找到一个与图像具有相同宽高比且包含所有掩码区域的矩形区域，然后根据 `padding_mask_crop` 扩展该区域。随后，在将图像和 mask_image 调整回原始图像尺寸以进行修复之前，会基于扩展后的区域对它们进行裁剪。当掩码区域较小而图像较大，且包含与修复无关的信息（例如背景）时，此功能非常有用。 strength (`float`, *可选*，默认为 0.9999)：从概念上讲，表示对参考`image`中被掩码部分进行多大程度的变换。取值必须在 0 到 1 之间。`image`将作为起点，`strength`越大，添加的噪声越多。去噪步数取决于初始添加的噪声量。当`strength`为 1 时，添加的噪声达到最大值，去噪过程将运行`num_inference_steps`中指定的完整迭代次数。因此，值为 1 时，基本上会忽略参考`image`中被掩码的部分。请注意，如果`denoising_start`被声明为整数，则`strength`的值将被忽略。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 denoising_start (`float`, *可选*) : 指定时，表示在去噪过程启动前需要跳过的总去噪过程的比例（介于 0.0 和 1.0 之间）。因此，去噪过程的初始部分将被跳过，并假定传入的 `image` 是一张部分去噪的图像。请注意，当指定此参数时，strength 将被忽略。`denoising_start` 参数在将此管道集成到“去噪器混合”多管道配置中时特别有用，详见 [**优化图像输出**](https://huggingface.co/docs/diffusers/api/pipelines/stable_diffusion/stable_diffusion_xl#refining-the-image-output)。 denoising_end (`float`, *可选*) : 指定时，确定在有意提前终止之前，总去噪过程需要完成的比例（介于 0.0 和 1.0 之间）。因此，返回的样本仍将保留大量噪声（大约还需要最后 20% 的时间步），并且应该由一个将 `denoising_start` 设置为 0.8 的后续流水线进行去噪，使其仅对调度器的最后 20% 进行去噪。理想情况下，当此流水线作为“去噪器混合”多流水线设置的一部分时，应使用 denoising_end 参数，如 [**优化图像输出**](https://huggingface.co/docs/diffusers/api/pipelines/stable_diffusion/stable_diffusion_xl#refining-the-image-output) 中所述。 guidance_scale (`float`，*可选*，默认值为 7.5)：如[Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)中定义的引导尺度。`guidance_scale` 定义为[Imagen Paper](https://huggingface.co/papers/2205.11487)中公式 2 的 `w`。通过设置 `guidance_scale > 1` 来启用引导尺度。较高的引导尺度会促使生成与文本 `prompt` 紧密关联的图像，但通常以牺牲图像质量为代价。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 DDIM 论文中的参数 eta (η)：https://huggingface.co/papers/2010.02502。仅适用于 [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，对其他调度器将被忽略。 generator (`torch.Generator`, *可选*) : 一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。 latents (`torch.Tensor`, *可选*) : 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机`generator`进行采样来生成潜变量张量。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 [PIL](https://pillow.readthedocs.io/en/stable/)：`PIL.Image.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。 original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：如果 `original_size` 与 `target_size` 不同，图像将看起来像是被下采样或上采样了。如果未指定，`original_size` 默认为 `(height, width)`。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。 crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：`crops_coords_top_left` 可用于生成一张看似从 `crops_coords_top_left` 位置向下裁剪的图像。通常将 `crops_coords_top_left` 设置为 (0, 0) 即可获得构图良好、居中效果佳的图像。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：在大多数情况下，应将 `target_size` 设置为生成图像所需的宽度和高度。如果未指定，则默认为 `(height, width)`。这是 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述 SDXL 微条件化的一部分。 negative_original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：用于基于特定的图像分辨率对生成过程进行负向条件控制。这是 SDXL 微条件化的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：用于根据特定的裁剪坐标对生成过程施加负向条件。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：用于根据目标图像分辨率对生成过程施加负向条件。在大多数情况下，它应与 `target_size` 相同。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息，请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 aesthetic_score (`float`，*可选*，默认值为 6.0)：用于通过影响正向文本条件来模拟生成图像的美学评分。这是 SDXL 微条件化的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 negative_aesthetic_score (`float`，*可选*，默认值为 2.5)：[https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述的 SDXL 微条件（micro-conditioning）的一部分。可通过影响负向文本条件来模拟生成图像的美学评分。 guidance_rescale (`float`, *可选*，默认为 0.0) : [常见的扩散噪声调度和采样步骤存在缺陷](https://arxiv.org/pdf/2305.08891.pdf) 中的 guidance rescale 因子。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** `~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput` 或 `tuple` 如果 `return_dict` 为 True，则返回 `~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput`，否则返回 `tuple. `tuple。当返回元组时，第一个元素是一个包含生成图像的列表。 调用生成 pipeline 时调用的函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForInpainting >>> from diffusers.utils import load_image >>> pipe = AutoPipelineForInpainting.from_pretrained( ... "stabilityai/stable-diffusion-xl-base-1.0", ... torch_dtype=torch.float16, ... variant="fp16", ... enable_pag=True, ... ) >>> pipe.to("cuda") >>> img_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo.png" >>> mask_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo_mask.png" >>> init_image = load_image(img_url).convert("RGB") >>> mask_image = load_image(mask_url).convert("RGB") >>> prompt = "A majestic tiger sitting on a bench" >>> image = pipe( ... prompt=prompt, ... image=init_image, ... mask_image=mask_image, ... num_inference_steps=50, ... strength=0.80, ... pag_scale=0.3, ... ).images[0] ``` #### encode_prompt[[diffusers.StableDiffusionXLPAGInpaintPipeline.encode_prompt]] ```python encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl_inpaint.py#L401) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionXLPAGInpaintPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_xl_inpaint.py#L1011) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionXLControlNetPAGPipeline[[diffusers.StableDiffusionXLControlNetPAGPipeline]] #### diffusers.StableDiffusionXLControlNetPAGPipeline[[diffusers.StableDiffusionXLControlNetPAGPipeline]] ```python diffusers.StableDiffusionXLControlNetPAGPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet.ControlNetModel | list[diffusers.models.controlnets.controlnet.ControlNetModel] | tuple[diffusers.models.controlnets.controlnet.ControlNetModel] | diffusers.models.controlnets.multicontrolnet.MultiControlNetModel, scheduler: KarrasDiffusionSchedulers, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_xl.py#L185) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel))：冻结的文本编码器（[clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)）。 text_encoder_2 ([CLIPTextModelWithProjection](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModelWithProjection))：第二个冻结的文本编码器（[laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k)）。 tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer))：一个用于对文本进行分词的 `CLIPTokenizer`。 tokenizer_2 ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer))：一个用于对文本进行分词的 `CLIPTokenizer`。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：一个用于对编码后的图像潜变量进行去噪的 `UNet2DConditionModel`。 controlnet ([ControlNetModel](/docs/diffusers/v0.43.0/zh/api/models/controlnet#diffusers.ControlNetModel) 或 `list[ControlNetModel]`)：在去噪过程中为 `unet` 提供额外的条件输入。如果以列表形式设置多个 ControlNet，则会将每个 ControlNet 的输出相加，以生成一个合并的额外条件输入。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 force_zeros_for_empty_prompt (`bool`，*可选*，默认为 `"True"`)：是否始终将负提示嵌入设置为 0。另请参阅 `stabilityai/stable-diffusion-xl-base-1-0` 的配置。 add_watermarker (`bool`，*可选*)：是否使用 [invisible_watermark](https://github.com/ShieldMnt/invisible-watermark/) 库为输出图像添加水印。如果未定义，且该包已安装，则默认值为 `True`；否则不使用水印。 使用 Stable Diffusion XL 和 ControlNet 引导进行文本到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) - 用于加载 `.ckpt` 文件的 [from_single_file()](/docs/diffusers/v0.43.0/zh/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.StableDiffusionXLControlNetPAGPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, denoising_end: float | None = None, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 1.0, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_xl.py#L1003) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则需要传入 `prompt_embeds`。 prompt_2 (`str` 或 `list[str]`，*可选*) : 要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]`、`list[np.ndarray]`、`list[list[torch.Tensor]]`、`list[list[np.ndarray]]` 或 `list[list[PIL.Image.Image]]`)：用于为 `unet` 提供生成引导的 ControlNet 输入条件。如果类型指定为 `torch.Tensor`，则会原样传递给 ControlNet。也可以接受 `PIL.Image.Image` 作为图像。输出图像的默认尺寸与 `image` 的尺寸相同。如果传入了高度和/或宽度，`image` 将相应地调整大小。如果在 `init` 中指定了多个 ControlNet，则必须以列表形式传入图像，以便列表中的每个元素都能被正确批处理，作为单个 ControlNet 的输入。 height (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成图像的高度（以像素为单位）。对于 [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) 以及未在低分辨率上专门微调的检查点，低于 512 像素的效果不佳。 width (`int`，*可选*，默认为 `self.unet.config.sample_size * self.vae_scale_factor`)：生成图像的像素宽度。对于 [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) 以及未在低分辨率上专门微调的检查点，低于 512 像素的宽度效果不佳。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 denoising_end (`float`, *可选*) : 指定时，确定在有意提前终止之前，总去噪过程需要完成的比例（介于 0.0 和 1.0 之间）。因此，返回的样本仍将保留相当多的噪声，具体程度由调度器选择的离散时间步决定。当此管道作为“去噪器混合”多管道设置的一部分时，应理想地使用 denoising_end 参数，如 [**优化图像输出**](https://huggingface.co/docs/diffusers/api/pipelines/stable_diffusion/stable_diffusion_xl#refining-the-image-output) 中所述。 guidance_scale (`float`, *可选*，默认值为 5.0)：较高的 guidance scale 值会促使模型生成与文本 `prompt` 紧密相关的图像，但代价是图像质量降低。当 `guidance_scale > 1` 时，guidance scale 生效。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 `negative_prompt_embeds`。在未使用引导（`guidance_scale < 1`）时将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：用于指导图像生成中不应包含的内容的提示词或提示词列表。该内容会发送给 `tokenizer_2` 和 `text_encoder_2`。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 [DDIM](https://huggingface.co/papers/2010.02502) 论文中的参数 eta (η)。仅适用于 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，在其他调度器中会被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：用于使生成过程确定性的 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)。 latents (`torch.Tensor`, *可选*) : 从高斯分布中采样的预生成噪声潜变量，用作图像生成的输入。可用于以不同的提示词微调同一生成过程。如果未提供，则使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入（提示词权重）。如果未提供，则从 `negative_prompt` 输入参数生成池化的 `negative_prompt_embeds`。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。在 `PIL.Image` 或 `np.array` 之间选择。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为 [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中定义的 `AttentionProcessor` 的参数传递。 controlnet_conditioning_scale (`float` 或 `list[float]`，*可选*，默认为 1.0) : ControlNet 的输出在加到原始 `unet` 的残差之前，会先乘以 `controlnet_conditioning_scale`。如果在 `init` 中指定了多个 ControlNet，可以将对应的 scale 设置为列表。 control_guidance_start (`float` 或 `list[float]`，*可选*，默认为 0.0)：ControlNet 开始生效的总步数百分比。 control_guidance_end (`float` 或 `list[float]`，*可选*，默认为 1.0)：ControlNet 停止应用时的总步数百分比。 original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：如果 `original_size` 与 `target_size` 不同，图像将看起来像是被下采样或上采样了。如果未指定，`original_size` 默认为 `(height, width)`。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。 crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：`crops_coords_top_left` 可用于生成一张看似从 `crops_coords_top_left` 位置向下裁剪的图像。通常将 `crops_coords_top_left` 设置为 (0, 0) 即可获得构图良好、居中效果佳的图像。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：在大多数情况下，应将 `target_size` 设置为生成图像所需的宽度和高度。如果未指定，则默认为 `(height, width)`。这是 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述 SDXL 微条件化的一部分。 negative_original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：用于基于特定的图像分辨率对生成过程进行负向条件控制。这是 SDXL 微条件化的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：用于根据特定的裁剪坐标对生成过程施加负向条件。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：用于根据目标图像分辨率对生成过程施加负向条件。在大多数情况下，它应与 `target_size` 相同。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息，请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 或 `tuple` 如果 `return_dict` 为 `True`，则返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)，否则返回一个包含输出图像的 `tuple`。 用于生成的 pipeline 的调用函数。 示例： ```py >>> # !pip install opencv-python transformers accelerate >>> from diffusers import AutoPipelineForText2Image, ControlNetModel, AutoencoderKL >>> from diffusers.utils import load_image >>> import numpy as np >>> import torch >>> import cv2 >>> from PIL import Image >>> prompt = "aerial view, a futuristic research complex in a bright foggy jungle, hard lighting" >>> negative_prompt = "low quality, bad quality, sketches" >>> # download an image >>> image = load_image( ... "https://hf.co/datasets/hf-internal-testing/diffusers-images/resolve/main/sd_controlnet/hf-logo.png" ... ) >>> # initialize the models and pipeline >>> controlnet_conditioning_scale = 0.5 # recommended for good generalization >>> controlnet = ControlNetModel.from_pretrained( ... "diffusers/controlnet-canny-sdxl-1.0", torch_dtype=torch.float16 ... ) >>> vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16) >>> pipe = AutoPipelineForText2Image.from_pretrained( ... "stabilityai/stable-diffusion-xl-base-1.0", ... controlnet=controlnet, ... vae=vae, ... torch_dtype=torch.float16, ... enable_pag=True, ... ) >>> pipe.enable_model_cpu_offload() >>> # get canny image >>> image = np.array(image) >>> image = cv2.Canny(image, 100, 200) >>> image = image[:, :, None] >>> image = np.concatenate([image, image, image], axis=2) >>> canny_image = Image.fromarray(image) >>> # generate image >>> image = pipe( ... prompt, controlnet_conditioning_scale=controlnet_conditioning_scale, image=canny_image, pag_scale=0.3 ... ).images[0] ``` #### encode_prompt[[diffusers.StableDiffusionXLControlNetPAGPipeline.encode_prompt]] ```python encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_xl.py#L306) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 #### get_guidance_scale_embedding[[diffusers.StableDiffusionXLControlNetPAGPipeline.get_guidance_scale_embedding]] ```python get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_xl.py#L946) **参数：** w (`torch.Tensor`) : 生成具有指定 guidance scale 的嵌入向量，以用于后续丰富时间步嵌入。 embedding_dim (`int`，*可选*，默认值为 512)：要生成的嵌入的维度。 dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：生成嵌入的数据类型。 **返回：** `torch.Tensor` 形状为 `(len(w), embedding_dim)` 的嵌入向量。 参见 https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 ## StableDiffusionXLControlNetPAGImg2ImgPipeline[[diffusers.StableDiffusionXLControlNetPAGImg2ImgPipeline]] #### diffusers.StableDiffusionXLControlNetPAGImg2ImgPipeline[[diffusers.StableDiffusionXLControlNetPAGImg2ImgPipeline]] ```python diffusers.StableDiffusionXLControlNetPAGImg2ImgPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet.ControlNetModel | list[diffusers.models.controlnets.controlnet.ControlNetModel] | tuple[diffusers.models.controlnets.controlnet.ControlNetModel] | diffusers.models.controlnets.multicontrolnet.MultiControlNetModel, scheduler: KarrasDiffusionSchedulers, requires_aesthetics_score: bool = False, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None, pag_applied_layers: str | list[str] = 'mid') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_xl_img2img.py#L163) **参数：** vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder (`CLIPTextModel`)：冻结的文本编码器。Stable Diffusion 使用的是 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel) 的文本部分，具体为 [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14) 变体。 text_encoder_2 (` CLIPTextModelWithProjection`)：第二个冻结的文本编码器。Stable Diffusion XL 使用 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection) 的文本和池化部分，具体为 [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k) 变体。 tokenizer (`CLIPTokenizer`)：[CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的分词器。 tokenizer_2 (`CLIPTokenizer`)：第二个 [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的 Tokenizer。 unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/zh/api/models/unet2d-cond#diffusers.UNet2DConditionModel))：用于对编码后的图像潜变量进行去噪的条件 U-Net 架构。 controlnet ([ControlNetModel](/docs/diffusers/v0.43.0/zh/api/models/controlnet#diffusers.ControlNetModel) 或 `list[ControlNetModel]`)：在去噪过程中为 unet 提供额外的条件。如果以列表形式设置多个 ControlNet，则会将每个 ControlNet 的输出相加，以生成一个合并的额外条件。 scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin))：用于与 `unet` 配合以去除编码后的图像潜变量噪声的调度器。可以是 [DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)、[LMSDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) 或 [PNDMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/pndm#diffusers.PNDMScheduler) 之一。 requires_aesthetics_score (`bool`，*可选*，默认为 `"False"`)：指示 `unet` 在推理时是否需要传入 `aesthetic_score` 条件。另请参阅 `stabilityai/stable-diffusion-xl-refiner-1-0` 的配置。 force_zeros_for_empty_prompt (`bool`，*可选*，默认为 `"True"`)：是否强制将负提示嵌入始终设置为 0。另请参阅 `stabilityai/stable-diffusion-xl-base-1-0` 的配置。 add_watermarker (`bool`，*可选*)：是否使用 [invisible_watermark 库](https://github.com/ShieldMnt/invisible-watermark/) 为输出图像添加水印。如果未定义，则当该包已安装时默认为 True，否则不使用水印。 feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor))：一个 `CLIPImageProcessor`，用于从生成的图像中提取特征；作为 `safety_checker` 的输入。 使用 Stable Diffusion XL 并结合 ControlNet 引导进行图像到图像生成的 Pipeline。 该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。请查阅父类文档，了解该库为所有 pipeline 实现的通用方法（例如下载或保存、在特定设备上运行等）。 该 pipeline 还继承了以下加载方法： - 用于加载文本反转嵌入的 [load_textual_inversion()](/docs/diffusers/v0.43.0/zh/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) - 用于加载 LoRA 权重的 [load_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) - 用于保存 LoRA 权重的 [save_lora_weights()](/docs/diffusers/v0.43.0/zh/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) - 用于加载 IP Adapter 的 [load_ip_adapter()](/docs/diffusers/v0.43.0/zh/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) #### __调用__[[diffusers.StableDiffusionXLControlNetPAGImg2ImgPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, height: int | None = None, width: int | None = None, strength: float = 0.8, num_inference_steps: int = 50, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 0.8, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, aesthetic_score: float = 6.0, negative_aesthetic_score: float = 2.5, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_xl_img2img.py#L1079) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 `prompt_embeds`。 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]`、`list[np.ndarray]`、`list[list[torch.Tensor]]`、`list[list[np.ndarray]]` 或 `list[list[PIL.Image.Image]]`)：初始图像将作为图像生成过程的起点。也可以接受图像潜变量作为 `image`，如果直接传入潜变量，则不会再次进行编码。 control_image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]`、`list[np.ndarray]`、`list[list[torch.Tensor]]`、`list[list[np.ndarray]]` 或 `list[list[PIL.Image.Image]]`)：ControlNet 的输入条件。ControlNet 使用该输入条件生成对 Unet 的引导。如果类型指定为 `torch.Tensor`，则按原样传递给 ControlNet。也可以接受 `PIL.Image.Image` 作为图像。输出图像的默认尺寸与 `image` 的尺寸相同。如果传入了高度和/或宽度，`image` 将根据它们进行缩放。如果在初始化中指定了多个 ControlNet，必须以列表形式传入图像，以便列表中的每个元素都能被正确批处理，作为单个 controlnet 的输入。 height (`int`，*可选*，默认为 control_image 的尺寸)：生成图像的高度（以像素为单位）。低于 512 像素的值在 [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) 以及未在低分辨率上专门微调的检查点上效果不佳。 width (`int`，*可选*，默认为 control_image 的尺寸)：生成图像的像素宽度。低于 512 像素的宽度在 [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) 以及未在低分辨率上专门微调的检查点上效果不佳。 strength (`float`，*可选*，默认值为 0.8)：指示对参考 `image` 进行变换的程度。取值必须在 0 到 1 之间。`image` 用作起始点，`strength` 越高，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 `strength` 为 1 时，添加的噪声达到最大值，去噪过程将运行 `num_inference_steps` 中指定的完整迭代次数。值为 1 时，基本上会忽略 `image`。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 guidance_scale (`float`，*可选*，默认值为 7.5)：如[Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)中定义的引导尺度。`guidance_scale` 定义为[Imagen Paper](https://huggingface.co/papers/2205.11487)中公式 2 的 `w`。通过设置 `guidance_scale > 1` 来启用引导尺度。较高的引导尺度会促使生成与文本 `prompt` 紧密关联的图像，但通常以牺牲图像质量为代价。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 eta (`float`，*可选*，默认值为 0.0)：对应 DDIM 论文中的参数 eta (η)：https://huggingface.co/papers/2010.02502。仅适用于 [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，对其他调度器将被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。 latents (`torch.Tensor`, *可选*) : 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 ip_adapter_image : (`PipelineImageInput`，*可选*)：用于配合 IP Adapter 使用的可选图像输入。 ip_adapter_image_embeds (`list[torch.Tensor]`，*可选*)：用于 IP-Adapter 的预生成图像嵌入。它应是一个列表，长度与 IP-Adapter 的数量相同。每个元素应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负向图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算得出。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 [PIL](https://pillow.readthedocs.io/en/stable/)：`PIL.Image.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。 cross_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。 controlnet_conditioning_scale (`float` 或 `list[float]`，*可选*，默认为 1.0) : ControlNet 的输出在加到原始 unet 的残差之前，会先乘以 `controlnet_conditioning_scale`。如果在初始化时指定了多个 ControlNet，可以将对应的 scale 设置为列表。 guess_mode (`bool`，*可选*，默认为 `False`)：在此模式下，即使您移除了所有提示词，ControlNet 编码器也会尽力识别输入图像的内容。建议将 `guidance_scale` 设置在 3.0 到 5.0 之间。 control_guidance_start (`float` 或 `list[float]`，*可选*，默认为 0.0)：ControlNet 开始应用时占总步数的百分比。 control_guidance_end (`float` 或 `list[float]`，*可选*，默认为 1.0)：控制网络停止应用时的总步数百分比。 original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：如果 `original_size` 与 `target_size` 不同，图像将看起来像是被下采样或上采样了。如果未指定，`original_size` 默认为 `(height, width)`。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。 crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：`crops_coords_top_left` 可用于生成一张看似从 `crops_coords_top_left` 位置向下裁剪的图像。通常将 `crops_coords_top_left` 设置为 (0, 0) 即可获得构图良好、居中效果佳的图像。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：在大多数情况下，应将 `target_size` 设置为生成图像所需的宽度和高度。如果未指定，则默认为 `(height, width)`。这是 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述 SDXL 微条件化的一部分。 negative_original_size (`tuple[int]`，*可选*，默认为 (1024, 1024))：用于基于特定的图像分辨率对生成过程进行负向条件控制。这是 SDXL 微条件化的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_crops_coords_top_left (`tuple[int]`，*可选*，默认值为 (0, 0))：用于根据特定的裁剪坐标对生成过程施加负向条件。这是 SDXL 微条件的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。更多信息请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 negative_target_size (`tuple[int]`，*可选*，默认值为 (1024, 1024))：用于根据目标图像分辨率对生成过程施加负向条件。在大多数情况下，它应与 `target_size` 相同。这是 SDXL 微条件的一部分，如 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节所述。更多信息，请参阅此 issue 讨论：https://github.com/huggingface/diffusers/issues/4208。 aesthetic_score (`float`，*可选*，默认值为 6.0)：用于通过影响正向文本条件来模拟生成图像的美学评分。这是 SDXL 微条件化的一部分，详见 [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 中的第 2.2 节。 negative_aesthetic_score (`float`，*可选*，默认值为 2.5)：[https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952) 第 2.2 节中所述的 SDXL 微条件（micro-conditioning）的一部分。可通过影响负向文本条件来模拟生成图像的美学评分。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 callback_on_step_end (`Callable`、`PipelineCallback`、`MultiPipelineCallbacks`、*可选*)：一个函数，或 `PipelineCallback` 或 `MultiPipelineCallbacks` 的子类，在推理过程中每个去噪步骤结束时被调用，其参数为：`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` 属性中列出的变量。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** `~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput` 或 `tuple` 如果 `return_dict` 为 True，则返回 `~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput`，否则返回一个包含输出图像的 `tuple`。 调用生成 pipeline 时调用的函数。 示例： ```py >>> # pip install accelerate transformers safetensors diffusers >>> import torch >>> import numpy as np >>> from PIL import Image >>> from transformers import DPTFeatureExtractor, DPTForDepthEstimation >>> from diffusers import ControlNetModel, StableDiffusionXLControlNetPAGImg2ImgPipeline, AutoencoderKL >>> from diffusers.utils import load_image >>> depth_estimator = DPTForDepthEstimation.from_pretrained("Intel/dpt-hybrid-midas").to("cuda") >>> feature_extractor = DPTFeatureExtractor.from_pretrained("Intel/dpt-hybrid-midas") >>> controlnet = ControlNetModel.from_pretrained( ... "diffusers/controlnet-depth-sdxl-1.0-small", ... variant="fp16", ... use_safetensors="True", ... torch_dtype=torch.float16, ... ) >>> vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16) >>> pipe = StableDiffusionXLControlNetPAGImg2ImgPipeline.from_pretrained( ... "stabilityai/stable-diffusion-xl-base-1.0", ... controlnet=controlnet, ... vae=vae, ... variant="fp16", ... use_safetensors=True, ... torch_dtype=torch.float16, ... enable_pag=True, ... ) >>> pipe.enable_model_cpu_offload() >>> def get_depth_map(image): ... image = feature_extractor(images=image, return_tensors="pt").pixel_values.to("cuda") ... with torch.no_grad(), torch.autocast("cuda"): ... depth_map = depth_estimator(image).predicted_depth ... depth_map = torch.nn.functional.interpolate( ... depth_map.unsqueeze(1), ... size=(1024, 1024), ... mode="bicubic", ... align_corners=False, ... ) ... depth_min = torch.amin(depth_map, dim=[1, 2, 3], keepdim=True) ... depth_max = torch.amax(depth_map, dim=[1, 2, 3], keepdim=True) ... depth_map = (depth_map - depth_min) / (depth_max - depth_min) ... image = torch.cat([depth_map] * 3, dim=1) ... image = image.permute(0, 2, 3, 1).cpu().numpy()[0] ... image = Image.fromarray((image * 255.0).clip(0, 255).astype(np.uint8)) ... return image >>> prompt = "A robot, 4k photo" >>> image = load_image( ... "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky/cat.png" ... ).resize((1024, 1024)) >>> controlnet_conditioning_scale = 0.5 # recommended for good generalization >>> depth_image = get_depth_map(image) >>> images = pipe( ... prompt, ... image=image, ... control_image=depth_image, ... strength=0.99, ... num_inference_steps=50, ... controlnet_conditioning_scale=controlnet_conditioning_scale, ... ).images >>> images[0].save(f"robot_cat.png") ``` #### encode_prompt[[diffusers.StableDiffusionXLControlNetPAGImg2ImgPipeline.encode_prompt]] ```python encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_controlnet_sd_xl_img2img.py#L296) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则两个文本编码器均使用 `prompt`。 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表，用于引导图像生成。如果未定义，则两个文本编码器都会使用 `negative_prompt`。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，negative_prompt_embeds 将从 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如* 提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 将提示词编码为文本编码器的隐藏状态。 ## StableDiffusion3PAGPipeline[[diffusers.StableDiffusion3PAGPipeline]] #### diffusers.StableDiffusion3PAGPipeline[[diffusers.StableDiffusion3PAGPipeline]] ```python diffusers.StableDiffusion3PAGPipeline(transformer: SD3Transformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, text_encoder_2: CLIPTextModelWithProjection, tokenizer_2: CLIPTokenizer, text_encoder_3: T5EncoderModel, tokenizer_3: T5Tokenizer, pag_applied_layers: str | list[str] = 'blocks.1') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_3.py#L136) **参数：** transformer ([SD3Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel))：用于对编码后的图像潜变量进行去噪的条件 Transformer (MMDiT) 架构。 scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler))：用于与 `transformer` 配合，对编码后的图像潜变量进行去噪的调度器。 vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder (`CLIPTextModelWithProjection`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection)，具体为 [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14) 变体，额外增加了一个投影层，该层使用维度为 `hidden_size` 的对角矩阵进行初始化。 text_encoder_2 (`CLIPTextModelWithProjection`)：即 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection)，具体为 [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k) 变体。 text_encoder_3 (`T5EncoderModel`)：冻结的文本编码器。Stable Diffusion 3 使用 [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel)，具体为 [t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl) 变体。 tokenizer (`CLIPTokenizer`)：[CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的分词器。 tokenizer_2 (`CLIPTokenizer`)：第二个 [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的 Tokenizer。 tokenizer_3 (`T5TokenizerFast`)：[T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer) 类的分词器。 用于使用 Stable Diffusion 3 进行文本到图像生成的 [PAG 流水线](https://huggingface.co/docs/diffusers/main/en/using-diffusers/pag)。 #### __调用__[[diffusers.StableDiffusion3PAGPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, prompt_3: str | list[str] | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 28, sigmas: list[float] | None = None, guidance_scale: float = 7.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, negative_prompt_3: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, clip_skip: int | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 256, pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_3.py#L684) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 `prompt_embeds`。 prompt_2 (`str` 或 `list[str]`，*可选*) : 要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则使用 `prompt` 代替 prompt_3 (`str` 或 `list[str]`，*可选*) : 要发送给 `tokenizer_3` 和 `text_encoder_3` 的提示词或提示词列表。如果未定义，将使用 `prompt` 作为替代 height (`int`，*可选*，默认为 self.unet.config.sample_size * self.vae_scale_factor)：生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。 width (`int`，*可选*，默认为 self.unet.config.sample_size * self.vae_scale_factor)：生成图像的像素宽度。默认设置为 1024 以获得最佳效果。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 guidance_scale (`float`，*可选*，默认值为 7.0)：[Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598) 中定义的引导尺度。`guidance_scale` 定义为 [Imagen Paper](https://huggingface.co/papers/2205.11487) 中公式 2 的 `w`。通过设置 `guidance_scale > 1` 来启用引导尺度。较高的引导尺度会促使生成与文本 `prompt` 紧密关联的图像，但通常以牺牲图像质量为代价。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的、用于引导图像生成的提示词或提示词列表。如果未定义，则使用 `negative_prompt` 代替 negative_prompt_3 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_3` 和 `text_encoder_3` 的提示词或提示词列表，用于引导图像生成。如果未定义，则使用 `negative_prompt` 代替 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。 latents (`torch.FloatTensor`, *可选*) : 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于以不同的提示词微调同一生成过程。如果未提供，将通过使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，则将从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，negative_prompt_embeds 将根据 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的池化文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 [PIL](https://pillow.readthedocs.io/en/stable/)：`PIL.Image.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` 而不是普通元组。 joint_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 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` 的最大序列长度。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** `~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput` 或 `tuple` 如果 `return_dict` 为 True，则返回 `~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput`，否则返回 `tuple`。当返回元组时，第一个元素是一个包含生成图像的列表。 调用生成 pipeline 时调用的函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForText2Image >>> pipe = AutoPipelineForText2Image.from_pretrained( ... "stabilityai/stable-diffusion-3-medium-diffusers", ... torch_dtype=torch.float16, ... enable_pag=True, ... pag_applied_layers=["blocks.13"], ... ) >>> pipe.to("cuda") >>> prompt = "A cat holding a sign that says hello world" >>> image = pipe(prompt, guidance_scale=5.0, pag_scale=0.7).images[0] >>> image.save("sd3_pag.png") ``` #### encode_prompt[[diffusers.StableDiffusion3PAGPipeline.encode_prompt]] ```python encode_prompt(prompt: str | list[str], prompt_2: str | list[str], prompt_3: str | list[str], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, negative_prompt_3: str | list[str] | None = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, clip_skip: int | None = None, max_sequence_length: int = 256, lora_scale: float | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_3.py#L335) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则所有文本编码器均使用 `prompt`。 prompt_3 (`str` 或 `list[str]`，*可选*) : 要发送给 `tokenizer_3` 和 `text_encoder_3` 的提示词或提示词列表。如果未定义，则所有文本编码器均使用 `prompt`。 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的、用于引导图像生成的提示词或提示词列表。如果未定义，则所有文本编码器都会使用 `negative_prompt`。 negative_prompt_3 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_3` 和 `text_encoder_3` 的、用于引导图像生成的提示词或提示词列表。如果未定义，则所有文本编码器都会使用 `negative_prompt`。 prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，则将从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，negative_prompt_embeds 将根据 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的池化文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 ## StableDiffusion3PAGImg2ImgPipeline[[diffusers.StableDiffusion3PAGImg2ImgPipeline]] #### diffusers.StableDiffusion3PAGImg2ImgPipeline[[diffusers.StableDiffusion3PAGImg2ImgPipeline]] ```python diffusers.StableDiffusion3PAGImg2ImgPipeline(transformer: SD3Transformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, text_encoder_2: CLIPTextModelWithProjection, tokenizer_2: CLIPTokenizer, text_encoder_3: T5EncoderModel, tokenizer_3: T5Tokenizer, pag_applied_layers: str | list[str] = 'blocks.1') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_3_img2img.py#L152) **参数：** transformer ([SD3Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel))：用于对编码后的图像潜变量进行去噪的条件 Transformer (MMDiT) 架构。 scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler))：用于与 `transformer` 配合，对编码后的图像潜变量进行去噪的调度器。 vae ([AutoencoderKL](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl#diffusers.AutoencoderKL))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。 text_encoder (`CLIPTextModelWithProjection`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection)，具体为 [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14) 变体，额外增加了一个投影层，该层使用维度为 `hidden_size` 的对角矩阵进行初始化。 text_encoder_2 (`CLIPTextModelWithProjection`)：即 [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection)，具体为 [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k) 变体。 text_encoder_3 (`T5EncoderModel`)：冻结的文本编码器。Stable Diffusion 3 使用 [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel)，具体为 [t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl) 变体。 tokenizer (`CLIPTokenizer`)：[CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的分词器。 tokenizer_2 (`CLIPTokenizer`)：第二个 [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer) 类的 Tokenizer。 tokenizer_3 (`T5TokenizerFast`)：[T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer) 类的分词器。 用于使用 Stable Diffusion 3 进行图像到图像生成的 [PAG 流水线](https://huggingface.co/docs/diffusers/main/en/using-diffusers/pag)。 #### __调用__[[diffusers.StableDiffusion3PAGImg2ImgPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, prompt_3: str | list[str] | None = None, height: int | None = None, width: int | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, strength: float = 0.6, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 7.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, negative_prompt_3: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, clip_skip: int | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 256, pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_3_img2img.py#L735) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 `prompt_embeds`。 prompt_2 (`str` 或 `list[str]`，*可选*) : 要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则使用 `prompt` 代替 prompt_3 (`str` 或 `list[str]`，*可选*) : 要发送给 `tokenizer_3` 和 `text_encoder_3` 的提示词或提示词列表。如果未定义，将使用 `prompt` 作为替代 height (`int`，*可选*，默认为 `self.default_sample_size * self.vae_scale_factor`)：生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。 width (`int`，*可选*，默认为 `self.default_sample_size * self.vae_scale_factor`)：生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。 image (`torch.Tensor`、`PIL.Image.Image`、`np.ndarray`、`list[torch.Tensor]`、`list[PIL.Image.Image]` 或 `list[np.ndarray]`) : `Image`、numpy 数组或张量，表示用作起点的图像批次。对于 numpy 数组和 PyTorch 张量，预期的值范围为 `[0, 1]`。如果是张量或张量列表，预期的形状应为 `(B, C, H, W)` 或 `(C, H, W)`。如果是 numpy 数组或数组列表，预期的形状应为 `(B, H, W, C)` 或 `(H, W, C)`。它也可以接受图像潜变量作为 `image`，但如果直接传入潜变量，则不会再次进行编码。 strength (`float`，*可选*，默认值为 0.8)：指示对参考 `image` 进行变换的程度。取值必须在 0 到 1 之间。`image` 用作起始点，`strength` 越高，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 `strength` 为 1 时，添加的噪声达到最大值，去噪过程将运行 `num_inference_steps` 中指定的完整迭代次数。值为 1 时，基本上会忽略 `image`。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 guidance_scale (`float`，*可选*，默认值为 7.0)：[Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598) 中定义的引导尺度。`guidance_scale` 定义为 [Imagen Paper](https://huggingface.co/papers/2205.11487) 中公式 2 的 `w`。通过设置 `guidance_scale > 1` 来启用引导尺度。较高的引导尺度会促使生成与文本 `prompt` 紧密关联的图像，但通常以牺牲图像质量为代价。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的、用于引导图像生成的提示词或提示词列表。如果未定义，则使用 `negative_prompt` 代替 negative_prompt_3 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_3` 和 `text_encoder_3` 的提示词或提示词列表，用于引导图像生成。如果未定义，则使用 `negative_prompt` 代替 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。 latents (`torch.FloatTensor`, *可选*) : 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于以不同的提示词微调同一生成过程。如果未提供，将通过使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，则将从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，negative_prompt_embeds 将根据 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的池化文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 [PIL](https://pillow.readthedocs.io/en/stable/)：`PIL.Image.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` 而不是普通元组。 joint_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 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` 的最大序列长度。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** `~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput` 或 `tuple` 如果 `return_dict` 为 True，则返回 `~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput`，否则返回 `tuple`。当返回元组时，第一个元素是一个包含生成图像的列表。 调用生成 pipeline 时调用的函数。 示例： ```py >>> import torch >>> from diffusers import StableDiffusion3PAGImg2ImgPipeline >>> from diffusers.utils import load_image >>> pipe = StableDiffusion3PAGImg2ImgPipeline.from_pretrained( ... "stabilityai/stable-diffusion-3-medium-diffusers", ... torch_dtype=torch.float16, ... pag_applied_layers=["blocks.13"], ... ) >>> pipe.to("cuda") >>> prompt = "a photo of an astronaut riding a horse on mars" >>> url = "https://huggingface.co/datasets/patrickvonplaten/images/resolve/main/aa_xl/000000009.png" >>> init_image = load_image(url).convert("RGB") >>> image = pipe(prompt, image=init_image, guidance_scale=5.0, pag_scale=0.7).images[0] ``` #### encode_prompt[[diffusers.StableDiffusion3PAGImg2ImgPipeline.encode_prompt]] ```python encode_prompt(prompt: str | list[str], prompt_2: str | list[str], prompt_3: str | list[str], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, negative_prompt_3: str | list[str] | None = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, clip_skip: int | None = None, max_sequence_length: int = 256, lora_scale: float | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_sd_3_img2img.py#L351) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的提示词或提示词列表。如果未定义，则所有文本编码器均使用 `prompt`。 prompt_3 (`str` 或 `list[str]`，*可选*) : 要发送给 `tokenizer_3` 和 `text_encoder_3` 的提示词或提示词列表。如果未定义，则所有文本编码器均使用 `prompt`。 device : (`torch.device`): torch 设备 num_images_per_prompt (`int`) : 每个提示词应生成的图像数量 do_classifier_free_guidance (`bool`) : 是否使用 classifier free guidance negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 negative_prompt_2 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_2` 和 `text_encoder_2` 的、用于引导图像生成的提示词或提示词列表。如果未定义，则所有文本编码器都会使用 `negative_prompt`。 negative_prompt_3 (`str` 或 `list[str]`，*可选*)：要发送给 `tokenizer_3` 和 `text_encoder_3` 的、用于引导图像生成的提示词或提示词列表。如果未定义，则所有文本编码器都会使用 `negative_prompt`。 prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，则将从 `prompt` 输入参数生成文本嵌入。 negative_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，negative_prompt_embeds 将根据 `negative_prompt` 输入参数生成。 pooled_prompt_embeds (`torch.FloatTensor`，*可选*)：预生成的池化文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，将从 `prompt` 输入参数生成池化文本嵌入。 negative_pooled_prompt_embeds (`torch.FloatTensor`, *可选*) : 预生成的负向池化文本嵌入。可用于轻松调整文本输入，*例如*提示词权重。如果未提供，将从 `negative_prompt` 输入参数生成 pooled negative_prompt_embeds。 clip_skip (`int`, *可选*) : 在计算提示嵌入时，从 CLIP 中跳过的层数。值为 1 表示将使用倒数第二层的输出来计算提示嵌入。 lora_scale (`float`, *可选*) : 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。 ## PixArtSigmaPAGPipeline[[diffusers.PixArtSigmaPAGPipeline]] #### diffusers.PixArtSigmaPAGPipeline[[diffusers.PixArtSigmaPAGPipeline]] ```python diffusers.PixArtSigmaPAGPipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, vae: AutoencoderKL, transformer: PixArtTransformer2DModel, scheduler: KarrasDiffusionSchedulers, pag_applied_layers: str | list[str] = 'blocks.1') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_pixart_sigma.py#L144) 使用 PixArt-Sigma 进行文本到图像生成的 [PAG 流水线](https://huggingface.co/docs/diffusers/main/en/using-diffusers/pag)。 #### __调用__[[diffusers.PixArtSigmaPAGPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, negative_prompt: str = '', num_inference_steps: int = 20, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 4.5, num_images_per_prompt: int | None = 1, height: int | None = None, width: int | None = None, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: int = 1, clean_caption: bool = True, use_resolution_binning: bool = True, max_sequence_length: int = 300, pag_scale: float = 3.0, pag_adaptive_scale: float = 0.0) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_pixart_sigma.py#L574) **参数：** prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 `prompt_embeds`。 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。当不使用引导时（即 `guidance_scale` 小于 `1` 时），此参数将被忽略。 num_inference_steps (`int`，*可选*，默认值为 100)：去噪步数。更多的去噪步数通常能带来更高质量的图像，但代价是推理速度变慢。 timesteps (`list[int]`，*可选*)：用于在支持 `set_timesteps` 方法中 `timesteps` 参数的调度器中，指定去噪过程所使用的自定义时间步。如果未定义，则使用传入 `num_inference_steps` 时的默认行为。必须按降序排列。 sigmas (`list[float]`, *可选*) : 用于支持在 `set_timesteps` 方法中接受 `sigmas` 参数的调度器的去噪过程的自定义 sigmas。如果未定义，将使用传入 `num_inference_steps` 时的默认行为。 guidance_scale (`float`, *可选*，默认值为 4.5) : 如 [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598) 中定义的引导尺度。`guidance_scale` 定义为 [Imagen Paper](https://huggingface.co/papers/2205.11487) 中公式 2 的 `w`。通过设置 `guidance_scale > 1` 来启用引导尺度。较高的引导尺度会促使生成与文本 `prompt` 紧密关联的图像，通常以牺牲图像质量为代价。 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。 height (`int`，*可选*，默认为 self.unet.config.sample_size)：生成图像的高度（以像素为单位）。 width (`int`，*可选*，默认为 self.unet.config.sample_size)：生成图像的像素宽度。 eta (`float`，*可选*，默认值为 0.0)：对应 DDIM 论文中的参数 eta (η)：https://huggingface.co/papers/2010.02502。仅适用于 [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，对其他调度器将被忽略。 generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。 latents (`torch.Tensor`, *可选*) : 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机`generator`进行采样来生成潜变量张量。 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 prompt_attention_mask (`torch.Tensor`, *可选*) : 为文本嵌入预生成的注意力掩码。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负向文本嵌入。对于 PixArt-Sigma，此负向提示应为 ""。如果未提供，negative_prompt_embeds 将根据 `negative_prompt` 输入参数生成。 negative_prompt_attention_mask (`torch.Tensor`, *可选*) : 为负文本嵌入预生成的注意力掩码。 output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 [PIL](https://pillow.readthedocs.io/en/stable/)：`PIL.Image.Image` 或 `np.array`。 return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~pipelines.stable_diffusion.IFPipelineOutput` 而不是普通元组。 callback (`Callable`，*可选*)：一个在推理过程中每 `callback_steps` 步被调用一次的可调用对象。该函数将以以下参数被调用：`callback(step: int, timestep: int, latents: torch.Tensor)`。 callback_steps (`int`，*可选*，默认为 1)：`callback` 函数的调用频率。如果未指定，则回调将在每个步骤被调用。 clean_caption (`bool`，*可选*，默认为 `True`)：是否在创建嵌入之前清理字幕。需要安装 `beautifulsoup4` 和 `ftfy`。如果未安装这些依赖项，嵌入将直接从原始提示创建。 use_resolution_binning (`bool`，默认为 `True`)：如果设置为 `True`，则请求的高度和宽度会先通过 `ASPECT_RATIO_1024_BIN` 映射到最接近的分辨率。在生成的潜在变量被解码为图像后，它们会被重新调整回请求的分辨率。适用于生成非正方形图像。 max_sequence_length (`int` 默认为 300)：用于 `prompt` 的最大序列长度。 pag_scale (`float`，*可选*，默认值为 3.0)：用于扰动注意力引导的缩放因子。如果设置为 0.0，则不会使用扰动注意力引导。 pag_adaptive_scale (`float`，*可选*，默认值为 0.0)：用于扰动注意力引导的自适应缩放因子。如果设置为 0.0，则使用 `pag_scale`。 **返回：** [ImagePipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/consistency_models#diffusers.ImagePipelineOutput) 或 `tuple` 如果 `return_dict` 为 `True`，则返回 [ImagePipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/consistency_models#diffusers.ImagePipelineOutput)，否则返回一个 `tuple`，其中第一个元素是包含生成图像的列表 调用生成 pipeline 时调用的函数。 示例： ```py >>> import torch >>> from diffusers import AutoPipelineForText2Image >>> pipe = AutoPipelineForText2Image.from_pretrained( ... "PixArt-alpha/PixArt-Sigma-XL-2-1024-MS", ... torch_dtype=torch.float16, ... pag_applied_layers=["blocks.14"], ... enable_pag=True, ... ) >>> pipe = pipe.to("cuda") >>> prompt = "A small cactus with a happy face in the Sahara desert" >>> image = pipe(prompt, pag_scale=4.0, guidance_scale=1.0).images[0] ``` #### encode_prompt[[diffusers.PixArtSigmaPAGPipeline.encode_prompt]] ```python encode_prompt(prompt: str | list[str], do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_images_per_prompt: int = 1, device: typing.Optional[torch.device] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, clean_caption: bool = False, max_sequence_length: int = 300, **kwargs) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pag/pipeline_pag_pixart_sigma.py#L190) **参数：** prompt (`str` 或 `list[str]`，*可选*)：要编码的提示 negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则必须传入 `negative_prompt_embeds`。在未使用引导时会被忽略（即当 `guidance_scale` 小于 `1` 时会被忽略）。对于 PixArt-Alpha，此值应为 ""。 do_classifier_free_guidance (`bool`，*可选*，默认为 `True`)：是否使用无分类器引导 num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词应生成的图像数量 device : (`torch.device`, *可选*): 用于放置生成的嵌入的 torch 设备 prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，文本嵌入将从 `prompt` 输入参数生成。 negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负文本嵌入。对于 PixArt-Alpha，它应该是空字符串 "" 的嵌入。 clean_caption (`bool`，默认为 `False`)：如果 `True`，该函数将在编码之前对提供的字幕进行预处理和清理。 max_sequence_length (`int`，默认值为 300)：用于提示词的最大序列长度。 将提示词编码为文本编码器的隐藏状态。