hf-doc-build/doc / diffusers /main /ja /api /pipelines /pag.md

|

361 kB

Perturbed-Attention Guidance

Perturbed-Attention Guidance (PAG)は、無条件設定および条件付き設定の両方でサンプル品質を向上させる新しい拡散サンプリングガイダンスです。追加の学習や外部モジュールの統合を必要とせずに、この品質向上を実現します。

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 で紹介されました。

論文の抄録は以下の通りです：

最近の研究により、拡散モデルは高品質なサンプルを生成できることが示されていますが、その品質は、Classifier Guidance (CG) や Classifier-Free Guidance (CFG) などのサンプリングガイダンス手法に大きく依存しています。これらの手法は、無条件生成や画像復元などのさまざまな下流タスクでは、しばしば適用できません。本論文では、無条件設定と条件付き設定の両方で拡散サンプルの品質を向上させる新しいサンプリングガイダンス、Perturbed-Attention Guidance (PAG) を提案します。PAG は、追加の学習や外部モジュールの統合を必要とせずにこの向上を実現します。PAG は、デノイジングプロセス全体を通じてサンプルの構造を段階的に強化するように設計されています。具体的には、自己注意機構が構造情報を捕捉する能力を考慮し、拡散 U-Net の選択された自己注意マップを単位行列に置き換えることで構造が劣化した中間サンプルを生成し、デノイジングプロセスをこれらの劣化したサンプルから遠ざけるように誘導します。ADM と Stable Diffusion の両方において、PAG は条件付きシナリオだけでなく、無条件シナリオでも驚くほどサンプルの品質を向上させます。さらに、PAG は、CG や CFG などの既存のガイダンスを十分に活用できないさまざまな下流タスクにおけるベースライン性能を大幅に向上させます。これには、空のプロンプトを用いた ControlNet や、インペインティングやデブラーリングなどの画像復元が含まれます。

PAGは、PAGパイプラインをインスタンス化する際にpag_applied_layersをパラメータとして指定することで使用できます。単一の文字列または文字列のリストを指定できます。各文字列は、一意のレイヤー識別子、または1つ以上のレイヤーを特定するための正規表現を指定できます。

通常の文字列としての完全な識別子: 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)"]

RegEx はレイヤー識別子のマッチング手段としてサポートされているため、正しく使用することが極めて重要です。正しく使用しないと、予期しない動作が発生する可能性があります。PAG を使用する推奨方法は、レイヤーを blocks.{layer_index} および blocks.({layer_index_1|layer_index_2|...}) の形式で指定することです。これ以外の方法で使用する場合は、実行は可能ですが、基本的な検証チェックを回避してしまい、予期しない結果につながる可能性があります。

一般的なタスク

PAGは、テキストから画像への変換、画像から画像への変換、インペインティングなどのタスクにおいて、StableDiffusionXLPipelineに適用できます。特定のタスクでPAGを有効にするには、enable_pag=Trueフラグとpag_applied_layers引数を指定して、AutoPipeline APIを使用してパイプラインを読み込みます。

🤗 Diffusers は現在、PAG を一部の SDXL パイプラインおよび PixArtSigmaPAGPipeline で使用することのみサポートしています。新しいパイプラインに PAG のサポートを追加したい場合は、機能リクエストをお気軽に作成してください。

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()

pag_applied_layers 引数により、PAG を適用するレイヤーを指定できます。また、パイプラインの作成後に set_pag_applied_layers メソッドを使用して、これらのレイヤーを更新することも可能です。他のレイヤーへの PAG の適用方法については、pag_applied_layers セクションを参照してください。

すでに作成および読み込み済みのパイプラインがある場合、enable_pag フラグを指定して from_pipe API を使用することで、そのパイプライン上で PAG を有効にできます。内部では、指定したパイプラインとタスクに基づいて PAG パイプラインが作成されます。以下の例では、AutoPipelineForText2Image を使用し StableDiffusionXLPipeline を渡したため、StableDiffusionXLPAGPipeline がそれに応じて作成されます。なお、これには追加のメモリは必要なく、StableDiffusionXLPipeline と StableDiffusionXLPAGPipeline の両方が読み込まれて使用可能な状態になります。from_pipe API と diffuser におけるパイプラインの再利用方法については、こちらをご覧ください。

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 を大きくすると、画像はより意味的に一貫性のある構造を持ち、アーティファクトが少なくなります。ただし、ガイドスケールが大きすぎると、CFG と同様に、テクスチャが滑らかになり、画像がわずかに飽和する可能性があります。公式デモでは pag_scale=3.0 が使用されており、ほとんどのユースケースで良好に動作しますが、必要に応じて実験し、適切な値を選択してください。pag_scale=0 の場合、PAG は無効になります。

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パイプラインで使用できます。

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を有効にしたい場合は、これを実行できます

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対応の画像から画像へのパイプラインへ直接切り替えることも非常に簡単です

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を有効にしたまま、画像から画像へのパイプラインに直接切り替えることができます。

pipeline_pag = AutoPipelineForText2Image.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", enable_pag=True, dtype=torch.float16)
pipeline = AutoPipelineForImage2Image.from_pipe(pipeline_t2i)

では、画像を生成してみましょう!

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]

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()

既存のインペインティングパイプラインでPAGを有効にするには、次のようにします。

pipeline_inpaint = AutoPipelineForInpainting.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16)
pipeline = AutoPipelineForInpainting.from_pipe(pipeline_inpaint, enable_pag=True)

パイプラインのタスクが異なる場合でも、この方法は引き続き機能します。

pipeline_t2i = AutoPipelineForText2Image.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16)
pipeline = AutoPipelineForInpaiting.from_pipe(pipeline_t2i, enable_pag=True)

画像を生成してみましょう！

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]

ControlNet を使用した PAG

PAGをControlNetと併用するには、まずcontrolnetを作成します。次に、指定したタスクのAutoPipelineのfrom_pretrainedメソッドに、controlnetとその他のPAG引数を渡します。

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()

すでに ControlNet パイプラインがあり、PAG を有効にしたい場合は、from_pipe API を使用できます: AutoPipelineForText2Image.from_pipe(pipeline_controlnet, enable_pag=True)

は通常のControlNetパイプラインと同様に使用でき、pag_scaleパラメータを指定するオプションが追加されています。なお、PAGは条件なし生成で良好に動作します。この例では、プロンプトなしで画像を生成します。

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で生成された画像

IP-Adapter を使用した PAG

IP-Adapterは、基盤モデルを変更することなく画像プロンプトを可能にするため、拡散モデルに組み込むことができる人気のあるモデルです。IP-Adapterが読み込まれたパイプラインでPAGを有効にできます。

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 を適用するレイヤーを指定できます。デフォルトでは、mid blocks にのみ適用されます。この設定を変更すると、出力に大きな影響を与えます。パイプラインの作成後、set_pag_applied_layers メソッドを使用して PAG の適用レイヤーを調整することで、モデルに最適なレイヤーを見つけることができます。

例として、pag_layers = ["down.block_2"]とpag_layers = ["down.block_2", "up.block_1.attentions_0"]で生成された画像を示します。

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]]

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')

ソース

パラメータ:

vae (AutoencoderKL) : 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ（VAE）モデル。

text_encoder (CLIPTextModel) : 凍結されたテキストエンコーダー (clip-vit-large-patch14)。

tokenizer (CLIPTokenizer) : テキストをトークン化するためのCLIPTokenizer。

unet (UNet2DConditionModel) : エンコードされた動画の潜在変数をノイズ除去するために、UNetMotionModel を作成するために使用される UNet2DConditionModel。

motion_adapter (MotionAdapter) : unet と組み合わせて、エンコードされた動画の潜在変数をデノイズするために使用する MotionAdapter。

scheduler (SchedulerMixin) : unet と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラ。DDIMScheduler、LMSDiscreteScheduler、または PNDMScheduler のいずれかです。

AnimateDiffとPerturbed Attention Guidanceを用いたテキストから動画への生成パイプライン。

このモデルは DiffusionPipeline を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

パイプラインは、以下の読み込みメソッドも継承します:

テキストインバージョンの埋め込みを読み込むためのload_textual_inversion()
LoRA重みの読み込みにload_lora_weights()
LoRA重みの保存にはsave_lora_weights()を使用します
IP Adapterの読み込みにload_ip_adapter()

call[[diffusers.AnimateDiffPAGPipeline.call]]

__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)

ソース

パラメータ:

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、optional、デフォルトは 16) : 生成される動画フレームの数です。デフォルトは 16 フレームで、1 秒あたり 8 フレームの場合、2 秒の動画になります。

num_inference_steps (int、optional、デフォルト値は 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、optional、デフォルトは 1) : プロンプトごとに生成する動画の数を指定します。

eta (float、任意、デフォルト値は 0.0) : DDIM論文のパラメータ eta (η) に対応します。DDIMSchedulerでのみ適用され、他のスケジューラーでは無視されます。

generator (torch.Generator または list[torch.Generator]、任意) : 生成を決定論的にするための torch.Generator。

latents (torch.Tensor, 任意) : 高斯分布からサンプリングされた事前生成されたノイジーな潜在変数（latents）で、動画生成の入力として使用されます。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムな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, 任意) : 指定された場合、self.processor で定義されている AttentionProcessor に渡される kwargs の辞書です。

clip_skip (int, optional) : プロンプト埋め込みを計算する際に、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、optional、デフォルト値は 3.0) : 乱数化されたアテンションガイダンスのスケール係数です。0.0 に設定すると、乱数化されたアテンションガイダンスは使用されません。

pag_adaptive_scale (float、任意、デフォルト値は 0.0) : 乱数付きアテンションガイダンスの適応スケール係数です。0.0 に設定されている場合、pag_scale が使用されます。

戻り値: AnimateDiffPipelineOutput または tuple

return_dict が True の場合、AnimateDiffPipelineOutput が返され、それ以外の場合は、最初の要素が生成されたフレームのリストである tuple が返されます。

生成用の pipeline への呼び出し関数。

例:

>>> 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]]

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)

ソース

パラメータ:

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 入力引数から negative_prompt_embeds が生成されます。

lora_scale (float、任意) : LoRAレイヤーが読み込まれている場合、テキストエンコーダーのすべてのLoRAレイヤーに適用されるLoRAスケールです。

clip_skip (int, optional) : プロンプト埋め込みを計算する際に、CLIPからスキップするレイヤー数。値が1の場合、プロンプト埋め込みの計算に最終レイヤーの直前のレイヤーの出力が使用されます。

プロンプトをテキストエンコーダーの隠れ状態にエンコードします。

HunyuanDiTPAGPipeline[[diffusers.HunyuanDiTPAGPipeline]]

diffusers.HunyuanDiTPAGPipeline[[diffusers.HunyuanDiTPAGPipeline]]

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')

ソース

パラメータ:

vae (AutoencoderKL) : 画像を潜在表現にエンコードし、潜在表現からデコードするための Variational Auto-Encoder (VAE) モデルです。sdxl-vae-fp16-fix を使用します。

text_encoder (~transformers.BertModel、~transformers.CLIPTextModel | None) : 凍結されたテキストエンコーダー(clip-vit-large-patch14)。HunyuanDiT は、ファインチューニングされた [bilingual CLIP] を使用しています。

tokenizer (~transformers.BertTokenizer、~transformers.CLIPTokenizer | None) : テキストをトークン化するためのBertTokenizerまたはCLIPTokenizer。

transformer (HunyuanDiT2DModel) : Tencent Hunyuan によって設計された HunyuanDiT モデルです。

text_encoder_2 (T5EncoderModel) : mT5エンベッダーです。具体的には、't5-v1_1-xxl'です。

tokenizer_2 (T5Tokenizer) : mT5エンベッダー用のトークナイザー。

scheduler (DDPMScheduler) : HunyuanDiT と組み合わせて使用し、エンコードされた画像の潜在変数をデノイズするためのスケジューラ。

HunyuanDiT と Perturbed Attention Guidance を使用した英語/中国語から画像生成を行う Pipeline。

このモデルは DiffusionPipeline を継承しています。ライブラリがすべてのパイプラインに対して実装している汎用的なメソッド（ダウンロードや保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

HunyuanDiTは2つのテキストエンコーダーを使用しています:mT5とbilingual CLIP

call[[diffusers.HunyuanDiTPAGPipeline.call]]

__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)

ソース

パラメータ:

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論文のパラメータ eta (η) に対応します。DDIMSchedulerでのみ適用され、他のスケジューラーでは無視されます。

generator (torch.Generator または list[torch.Generator]、任意) : 生成を決定論的にするための torch.Generator。

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を返すかどうか。

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. See Section 3.4

original_size (tuple[int, int]、任意、デフォルトは(1024, 1024)) : 画像の元のサイズ。time ids の計算に使用されます。

target_size (tuple[int, int]、optional) : 画像のターゲットサイズ。time ids の計算に使用されます。

crops_coords_top_left (tuple[int, int]、optional、デフォルトは(0, 0)) : クロップの左上座標。time ids の計算に使用されます。

use_resolution_binning (bool、任意、デフォルトはTrue) : 解像度バインニングを使用するかどうかを指定します。Trueの場合、入力解像度は最も近い標準解像度に変換されます。サポートされている解像度は、1024x1024、1280x1280、1024x768、1152x864、1280x960、768x1024、864x1152、960x1280、1280x768、768x1280です。この値をTrueに設定することを推奨します。

pag_scale (float、optional、デフォルト値は 3.0) : 乱数化されたアテンションガイダンスのスケール係数です。0.0 に設定すると、乱数化されたアテンションガイダンスは使用されません。

pag_adaptive_scale (float、任意、デフォルト値は 0.0) : 乱数付きアテンションガイダンスの適応スケール係数です。0.0 に設定されている場合、pag_scale が使用されます。

戻り値: StableDiffusionPipelineOutput または tuple

If return_dict is True, StableDiffusionPipelineOutput is returned, otherwise a tuple is returned where the first element is a list with the generated images and the second element is a list of bools indicating whether the corresponding generated image contains "not-safe-for-work" (nsfw) content.

HunyuanDiT による生成用の pipeline への呼び出し関数。

例:

>>> 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]]

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)

ソース

パラメータ:

prompt (str または list[str]、省略可能) : エンコードするプロンプト

device : (torch.device): torch デバイス

dtype (torch.dtype) : torch dtype

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 入力引数から negative_prompt_embeds が生成されます。

prompt_attention_mask (torch.Tensor, 任意) : プロンプト用のアテンションマスク。prompt_embeds を直接渡す場合に必要です。

negative_prompt_attention_mask (torch.Tensor, 任意) : 負のプロンプト用のアテンションマスク。negative_prompt_embedsが直接渡される場合に必要です。

max_sequence_length (int, 任意) : プロンプトに使用する最大シーケンス長。

text_encoder_index (int, optional) : 使用するテキストエンコーダーのインデックス。clip は 0、T5 は 1 です。

プロンプトをテキストエンコーダーの隠れ状態にエンコードします。

KolorsPAGPipeline[[diffusers.KolorsPAGPipeline]]

diffusers.KolorsPAGPipeline[[diffusers.KolorsPAGPipeline]]

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')

ソース

パラメータ:

vae (AutoencoderKL) : 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ（VAE）モデル。

text_encoder (ChatGLMModel) : 凍結されたテキストエンコーダー。Kolors は ChatGLM3-6B を使用しています。

tokenizer (ChatGLMTokenizer) : クラス ChatGLMTokenizer の Tokenizer。

unet (UNet2DConditionModel) : エンコードされた画像の潜在変数をノイズ除去するための条件付き U-Net アーキテクチャ。

scheduler (SchedulerMixin) : unet と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラ。DDIMScheduler、LMSDiscreteScheduler、または 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 を継承しています。ライブラリがすべてのパイプラインに対して実装している汎用的なメソッド（ダウンロードや保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

パイプラインは、以下の読み込みメソッドも継承します:

LoRA重みの読み込みにload_lora_weights()
LoRA重みの保存にはsave_lora_weights()を使用します
IP Adapterの読み込みにload_ip_adapter()

call[[diffusers.KolorsPAGPipeline.call]]

__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)

ソース

パラメータ:

prompt (str または list[str]、省略可) : 画像生成をガイドするためのプロンプトです。未定義の場合、代わりに prompt_embeds を渡す必要があります。

height (int、optional、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) : 生成される画像のピクセル単位の縦幅です。最適な結果を得るため、デフォルトでは 1024 に設定されています。Kwai-Kolors/Kolors-diffusers および低解像度で特にファインチューニングされていないチェックポイントでは、512 ピクセル未満ではうまく動作しません。

width (int、optional、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) : 生成される画像の幅（ピクセル単位）です。最適な結果を得るため、デフォルトでは 1024 に設定されています。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 引数をサポートするスケジューラーにおいて、デノイジングプロセスに使用するカスタムシグマ。num_inference_steps が渡された場合のデフォルトの動作が使用されます。

denoising_end (float, 任意) : 指定すると、デノイジング全体のどの割合（0.0 から 1.0 の間）で処理を意図的に早期終了させるかを決定します。その結果、スケジューラによって選択された離散タイムステップによって決定されるように、返されるサンプルには依然としてかなりの量のノイズが残ります。画像出力の洗練 に詳述されているように、このパラメータは、このパイプラインが「Mixture of Denoisers」マルチパイプライン構成の一部を形成する場合に、理想的には利用されるべきです。

guidance_scale (float、任意、デフォルト値は 5.0) : Classifier-Free Diffusion Guidanceで定義されているガイダンススケールです。guidance_scale は、Imagen Paperの式 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/main/ja/api/schedulers/ddim#diffusers.DDIMScheduler) にのみ適用され、それ以外のスケジューラーでは無視されます。

generator (torch.Generator または list[torch.Generator]、任意) : 生成を決定論的にするための torch ジェネレーター 1 つまたはそのリスト。

latents (torch.Tensor, 任意) : イメージ生成の入力として使用される、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムなgeneratorを使用してサンプリングを行い、ラテンツのテンソルが生成されます。

prompt_embeds (torch.Tensor, 任意) : 事前生成されたテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。

pooled_prompt_embeds (torch.Tensor, 任意) : 事前に生成されたプーリング済みテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からプーリング済みテキスト埋め込みが生成されます。

negative_prompt_embeds (torch.Tensor, 任意) : 事前に生成されたネガティブなテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が生成されます。

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（PIL.Image.Image）または np.array から選択します。

return_dict (bool、任意、デフォルトはTrue) : プレーンなタプルではなく~pipelines.kolors.KolorsPipelineOutputを返すかどうかを指定します。

cross_attention_kwargs (dict, 任意) : 指定された場合、diffusers.models.attention_processor の self.processor で定義されている AttentionProcessor に渡される kwargs の辞書です。

original_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : original_size が target_size と異なる場合、画像はダウンサンプリングまたはアップサンプリングされたように見えます。original_size は、指定されていない場合、デフォルトで (height, width) になります。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロコンディショニングの一部です。

crops_coords_top_left (tuple[int]、optional、デフォルト値は (0, 0)) : crops_coords_top_left を使用すると、crops_coords_top_left の位置から下方向に「切り抜かれた」ように見える画像を生成できます。crops_coords_top_left を (0, 0) に設定することで、通常は良好で中央が整った画像が得られます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。

target_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : ほとんどの場合、target_size は生成される画像の希望する高さおよび幅に設定する必要があります。指定されない場合、デフォルトで (height, width) が使用されます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。

negative_original_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : 特定の画像解像度に基づいて、生成プロセスをネガティブに条件付けます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。

negative_crops_coords_top_left (tuple[int]、optional、デフォルト値は (0, 0)) : 特定のクロップ座標に基づいて、生成プロセスを負の条件として設定します。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。

negative_target_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : 目標画像の解像度に基づいて、生成プロセスをネガティブに条件付けます。ほとんどの場合、target_size と同じである必要があります。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この 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、optional、デフォルト値は 3.0) : 乱数化されたアテンションガイダンスのスケール係数です。0.0 に設定すると、乱数化されたアテンションガイダンスは使用されません。

pag_adaptive_scale (float、任意、デフォルト値は 0.0) : 乱数付きアテンションガイダンスの適応スケール係数です。0.0 に設定されている場合、pag_scale が使用されます。

max_sequence_length (int、デフォルトは 256) : prompt に使用する最大シーケンス長。

戻り値: ~pipelines.kolors.KolorsPipelineOutput または tuple

return_dict が True の場合は ~pipelines.kolors.KolorsPipelineOutput、それ以外の場合は tuple を返します。tuple を返す場合、最初の要素は生成された画像のリストです。

生成用のパイプラインを呼び出したときに実行される関数。

例:

>>> 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]]

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)

ソース

パラメータ:

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 入力引数から negative_prompt_embeds が生成されます。

negative_pooled_prompt_embeds (torch.Tensor, 任意) : 事前に生成されたネガティブなプールのテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、negative_prompt 入力引数からプールの negative_prompt_embeds が生成されます。

max_sequence_length (int、デフォルトは 256) : prompt に使用する最大シーケンス長。

プロンプトをテキストエンコーダーの隠れ状態にエンコードします。

get_guidance_scale_embedding[[diffusers.KolorsPAGPipeline.get_guidance_scale_embedding]]

get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32)

ソース

パラメータ:

w (torch.Tensor) : 指定されたガイダンススケールで埋め込みベクトルを生成し、タイムステップ埋め込みを後で強化します。

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]]

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')

ソース

パラメータ:

vae (AutoencoderKL) : 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ（VAE）モデル。

text_encoder (CLIPTextModel) : 凍結されたテキストエンコーダー (clip-vit-large-patch14)。

tokenizer (CLIPTokenizer) : テキストをトークン化するためのCLIPTokenizer。

unet (UNet2DConditionModel) : エンコードされた画像の潜在変数をノイズ除去するための UNet2DConditionModel。

scheduler (SchedulerMixin) : unet と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラ。DDIMScheduler、LMSDiscreteScheduler、または PNDMScheduler のいずれかです。

safety_checker (StableDiffusionSafetyChecker) : 生成された画像が攻撃的または有害とみなされる可能性を推定する分類モジュールです。モデルの潜在的な害に関する詳細については、モデルカードを参照してください。

feature_extractor (CLIPImageProcessor) : 生成された画像から特徴量を抽出するためのCLIPImageProcessor。safety_checkerの入力として使用されます。

Stable Diffusion を使用したテキストから画像への生成を行う Pipeline。

このモデルは DiffusionPipeline を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

パイプラインは、以下の読み込みメソッドも継承します:

テキストインバージョンの埋め込みを読み込むためのload_textual_inversion()
LoRA重みの読み込みにload_lora_weights()
LoRA重みの保存にはsave_lora_weights()を使用します
.ckptファイルを読み込むためのfrom_single_file()
IP Adapterの読み込みにload_ip_adapter()

call[[diffusers.StableDiffusionPAGInpaintPipeline.call]]

__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)

ソース

パラメータ:

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 配列、またはテンソル。インペイントする画像のバッチを表します（mask_image でマスクする部分と、prompt に従って再描画する部分）。

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 テンソルの場合は、3 チャネルではなく 1 つの色チャネル（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 の場合、画像および 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は実質的に無視されます。