# ControlNet với Stable Diffusion 3

  

StableDiffusion3ControlNetPipeline là một triển khai của ControlNet cho Stable Diffusion 3.

ControlNet được giới thiệu trong [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) bởi Lvmin Zhang, Anyi Rao và Maneesh Agrawala.

Với một mô hình ControlNet, bạn có thể cung cấp một hình ảnh điều khiển bổ sung để điều kiện hóa và kiểm soát quá trình tạo hình ảnh của Stable Diffusion. Ví dụ, nếu bạn cung cấp một bản đồ độ sâu, mô hình ControlNet sẽ tạo ra một hình ảnh giữ lại thông tin không gian từ bản đồ độ sâu. Đây là một cách linh hoạt và chính xác hơn để kiểm soát quá trình tạo hình ảnh.

Tóm tắt từ bài báo là:

*Chúng tôi giới thiệu ControlNet, một kiến trúc mạng nơ-ron để thêm các điều khiển điều kiện không gian vào các mô hình khuếch tán từ văn bản sang ảnh lớn, được huấn luyện trước. ControlNet khóa các mô hình khuếch tán lớn sẵn sàng cho sản xuất, và tái sử dụng các lớp mã hóa sâu và mạnh mẽ của chúng, được huấn luyện trước với hàng tỷ hình ảnh, làm xương sống vững chắc để học một tập hợp đa dạng các điều khiển có điều kiện. Kiến trúc mạng nơ-ron được kết nối bằng các "cuộn không" (các lớp tích chập khởi tạo bằng không) giúp tăng dần số tham số từ không và đảm bảo rằng không có nhiễu có hại nào có thể ảnh hưởng đến quá trình tinh chỉnh. Chúng tôi kiểm tra các điều khiển điều kiện khác nhau, ví dụ như cạnh, độ sâu, phân đoạn, tư thế con người, v.v., với Stable Diffusion, sử dụng một hoặc nhiều điều kiện, có hoặc không có lời nhắc. Chúng tôi cho thấy rằng việc huấn luyện ControlNet là mạnh mẽ với các bộ dữ liệu nhỏ (<50k) và lớn (>1m). Các kết quả mở rộng cho thấy ControlNet có thể thúc đẩy các ứng dụng rộng hơn để kiểm soát các mô hình khuếch tán ảnh.*

Mã controlnet này chủ yếu được triển khai bởi [The InstantX Team](https://huggingface.co/InstantX). Mã liên quan đến inpainting được phát triển bởi [The Alimama Creative Team](https://huggingface.co/alimama-creative). Bạn có thể tìm thấy các checkpoint được huấn luyện trước cho SD3-ControlNet trong bảng dưới đây:

| Loại ControlNet | Nhà phát triển | Liên kết |
| -------- | ---------- | ---- |
| Canny | [Đội ngũ InstantX](https://huggingface.co/InstantX) | [Liên kết](https://huggingface.co/InstantX/SD3-Controlnet-Canny) |
| Độ sâu | [Đội ngũ InstantX](https://huggingface.co/InstantX) | [Liên kết](https://huggingface.co/InstantX/SD3-Controlnet-Depth) |
| Tư thế | [Đội ngũ InstantX](https://huggingface.co/InstantX) | [Liên kết](https://huggingface.co/InstantX/SD3-Controlnet-Pose) |
| Gạch | [Đội ngũ InstantX](https://huggingface.co/InstantX) | [Liên kết](https://huggingface.co/InstantX/SD3-Controlnet-Tile) |
| Inpainting | [Đội ngũ AlimamaCreative](https://huggingface.co/alimama-creative) | [liên kết](https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting) |

> [!TIP]
> Hãy chắc chắn xem qua [hướng dẫn](../../using-diffusers/schedulers) về Schedulers để tìm hiểu cách khám phá sự đánh đổi giữa tốc độ và chất lượng của scheduler, và xem phần [tái sử dụng các thành phần giữa các pipeline](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) để tìm hiểu cách nạp các thành phần giống nhau vào nhiều pipeline một cách hiệu quả.

## StableDiffusion3ControlNetPipeline[[diffusers.StableDiffusion3ControlNetPipeline]]

#### diffusers.StableDiffusion3ControlNetPipeline[[diffusers.StableDiffusion3ControlNetPipeline]]

```python
diffusers.StableDiffusion3ControlNetPipeline(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, controlnet: diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel | list[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModel, image_encoder: transformers.models.siglip.modeling_siglip.SiglipVisionModel | None = None, feature_extractor: transformers.models.siglip.image_processing_pil_siglip.SiglipImageProcessorPil | None = None)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet.py#L143)

**Tham số:**

transformer ([SD3Transformer2DModel](/docs/diffusers/v0.43.0/vi/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel)) : Kiến trúc Transformer điều kiện (MMDiT) để khử nhiễu các latents ảnh đã mã hóa.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/vi/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Một trình lập lịch được sử dụng kết hợp với `transformer` để khử nhiễu các latent ảnh đã mã hóa.

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã hình ảnh sang và từ các biểu diễn ẩn.

text_encoder (`CLIPTextModelWithProjection`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection), cụ thể là biến thể [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14), với một lớp chiếu bổ sung được khởi tạo bằng một ma trận chéo có kích thước là `hidden_size`.

text_encoder_2 (`CLIPTextModelWithProjection`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection), cụ thể là biến thể [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k).

text_encoder_3 (`T5EncoderModel`) : Bộ mã hóa văn bản đóng băng. Stable Diffusion 3 sử dụng [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel), cụ thể là biến thể [t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl).

tokenizer (`CLIPTokenizer`) : Tokenizer của lớp [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

tokenizer_2 (`CLIPTokenizer`) : Tokenizer thứ hai thuộc lớp [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

tokenizer_3 (`T5TokenizerFast`) : Tokenizer của lớp [T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer).

controlnet ([SD3ControlNetModel](/docs/diffusers/v0.43.0/vi/api/models/controlnet_sd3#diffusers.SD3ControlNetModel) hoặc `list[SD3ControlNetModel]` hoặc `SD3MultiControlNetModel`) : Cung cấp điều kiện bổ sung cho `unet` trong quá trình khử nhiễu. Nếu bạn đặt nhiều ControlNet dưới dạng danh sách, đầu ra từ mỗi ControlNet sẽ được cộng lại với nhau để tạo thành một điều kiện bổ sung kết hợp.

image_encoder (`SiglipVisionModel`, *tùy chọn*) : Mô hình thị giác được huấn luyện trước cho IP Adapter.

feature_extractor (`SiglipImageProcessor`, *tùy chọn*) : Bộ xử lý ảnh cho IP Adapter.

#### __call__[[diffusers.StableDiffusion3ControlNetPipeline.__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, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, controlnet_conditioning_scale: float | list[float] = 1.0, controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = None, 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, 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: typing.Optional[torch.Tensor] = 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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet.py#L819)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền `prompt_embeds` thay thế.

prompt_2 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần được gửi đến `tokenizer_2` và `text_encoder_2`. Nếu không được định nghĩa, `prompt` sẽ được sử dụng thay thế

prompt_3 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần được gửi đến `tokenizer_3` và `text_encoder_3`. Nếu không được định nghĩa, `prompt` sẽ được sử dụng thay thế

height (`int`, *optional*, mặc định là self.unet.config.sample_size * self.vae_scale_factor) : Chiều cao của hình ảnh được tạo ra, tính bằng pixel. Giá trị mặc định là 1024 để đạt kết quả tốt nhất.

width (`int`, *optional*, mặc định là self.unet.config.sample_size * self.vae_scale_factor) : Độ rộng tính bằng pixel của hình ảnh được tạo ra. Mặc định được đặt là 1024 để đạt kết quả tốt nhất.

num_inference_steps (`int`, *optional*, mặc định là 50) : Số bước khử nhiễu. Số bước khử nhiễu nhiều hơn thường dẫn đến hình ảnh có chất lượng cao hơn, với cái giá là suy luận chậm hơn.

sigmas (`list[float]`, *optional*) : Các sigma tùy chỉnh để sử dụng cho quá trình khử nhiễu với các trình lập lịch hỗ trợ tham số `sigmas` trong phương thức `set_timesteps` của chúng. Nếu không được định nghĩa, hành vi mặc định khi `num_inference_steps` được truyền vào sẽ được sử dụng.

guidance_scale (`float`, *optional*, mặc định là 5.0) : Thang độ dẫn hướng như được định nghĩa trong [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` được định nghĩa là `w` của phương trình 2. trong [Imagen Paper](https://huggingface.co/papers/2205.11487). Thang độ dẫn hướng được kích hoạt bằng cách đặt `guidance_scale > 1`. Thang độ dẫn hướng cao hơn khuyến khích tạo ra các hình ảnh gắn kết chặt chẽ với `prompt` văn bản, thường phải đánh đổi bằng chất lượng hình ảnh thấp hơn.

control_guidance_start (`float` hoặc `list[float]`, *tuỳ chọn*, mặc định là 0.0) : Tỷ lệ phần trăm của tổng số bước mà tại đó ControlNet bắt đầu áp dụng.

control_guidance_end (`float` hoặc `list[float]`, *tuỳ chọn*, mặc định là 1.0) : Tỷ lệ phần trăm tổng số bước mà tại đó ControlNet ngừng áp dụng.

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]]` hoặc `list[list[PIL.Image.Image]]`): Điều kiện đầu vào của ControlNet để cung cấp hướng dẫn cho `unet` trong quá trình tạo ảnh. Nếu kiểu được chỉ định là `torch.Tensor`, nó sẽ được truyền vào ControlNet nguyên vẹn. `PIL.Image.Image` cũng có thể được chấp nhận dưới dạng ảnh. Kích thước của ảnh đầu ra mặc định là kích thước của `image`. Nếu chiều cao và/hoặc chiều rộng được truyền vào, `image` sẽ được thay đổi kích thước cho phù hợp. Nếu nhiều ControlNet được chỉ định trong `init`, các ảnh phải được truyền dưới dạng danh sách sao cho mỗi phần tử của danh sách có thể được nhóm (batch) chính xác để làm đầu vào cho một ControlNet duy nhất.

controlnet_conditioning_scale (`float` hoặc `list[float]`, *tuỳ chọn*, mặc định là 1.0) : Đầu ra của ControlNet được nhân với `controlnet_conditioning_scale` trước khi được cộng vào phần dư trong `unet` gốc. Nếu nhiều ControlNet được chỉ định trong `init`, bạn có thể đặt thang đo tương ứng dưới dạng danh sách.

controlnet_pooled_projections (`torch.FloatTensor` có shape `(batch_size, projection_dim)`) : Các embeddings được chiếu từ embeddings của các điều kiện đầu vào của controlnet.

negative_prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền `negative_prompt_embeds` thay thế. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu `guidance_scale` nhỏ hơn `1`).

negative_prompt_2 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh, sẽ được gửi đến `tokenizer_2` và `text_encoder_2`. Nếu không được định nghĩa, `negative_prompt` sẽ được sử dụng thay thế

negative_prompt_3 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh, sẽ được gửi đến `tokenizer_3` và `text_encoder_3`. Nếu không được định nghĩa, `negative_prompt` sẽ được sử dụng thay thế

num_images_per_prompt (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng hình ảnh cần tạo cho mỗi prompt.

generator (`torch.Generator` hoặc `list[torch.Generator]`, *tùy chọn*) : Một hoặc một danh sách [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) để đảm bảo quá trình sinh là tất định.

latents (`torch.FloatTensor`, *tùy chọn*) : Các latents nhiễu đã được tạo trước, được lấy mẫu từ phân phối Gaussian, dùng làm đầu vào cho việc tạo ảnh. Có thể dùng để tinh chỉnh cùng một quá trình tạo với các prompt khác nhau. Nếu không được cung cấp, một tensor latents sẽ được tạo ra bằng cách lấy mẫu sử dụng `generator` ngẫu nhiên được cung cấp.

prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số của prompt. Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

pooled_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các embedding văn bản đã được pool sẵn. Có thể dùng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, các embedding văn bản đã pool sẽ được tạo ra từ đối số đầu vào `prompt`.

negative_pooled_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các embedding văn bản pooled âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, pooled negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

ip_adapter_image (`PipelineImageInput`, *tùy chọn*) : Đầu vào hình ảnh tùy chọn để làm việc với IP Adapters.

ip_adapter_image_embeds (`torch.Tensor`, *tùy chọn*) : Các embedding ảnh đã tạo trước cho IP-Adapter. Phải là một tensor có hình dạng `(batch_size, num_images, emb_dim)`. Nó phải chứa embedding ảnh âm nếu `do_classifier_free_guidance` được đặt thành `True`. Nếu không được cung cấp, các embedding sẽ được tính toán từ đối số đầu vào `ip_adapter_image`.

output_type (`str`, *tùy chọn*, mặc định là `"pil"`) : Định dạng đầu ra của hình ảnh được tạo. Chọn giữa [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` hoặc `np.array`.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` thay vì một tuple thông thường hay không.

joint_attention_kwargs (`dict`, *tùy chọn*) : Một từ điển kwargs mà nếu được chỉ định sẽ được truyền đến `AttentionProcessor` như đã định nghĩa dưới `self.processor` trong [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

clip_skip (`int`, *optional*) : Số lượng lớp cần bỏ qua từ CLIP khi tính toán các prompt embeddings. Giá trị 1 có nghĩa là đầu ra của lớp trước lớp cuối cùng sẽ được sử dụng để tính toán các prompt embeddings.

callback_on_step_end (`Callable`, *tùy chọn*) : Một hàm được gọi vào cuối mỗi bước khử nhiễu trong quá trình suy luận. Hàm này được gọi với các đối số sau: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` sẽ bao gồm một danh sách tất cả các tensor như được chỉ định bởi `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *optional*) : Danh sách các đầu vào tensor cho hàm `callback_on_step_end`. Các tensor được chỉ định trong danh sách sẽ được truyền dưới dạng tham số `callback_kwargs`. Bạn chỉ có thể bao gồm các biến được liệt kê trong thuộc tính `._callback_tensor_inputs` của lớp pipeline của bạn.

max_sequence_length (`int` mặc định là 256) : Độ dài tối đa của chuỗi để sử dụng với `prompt`.

**Trả về:** `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` hoặc `tuple`

`~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` nếu `return_dict` là True, ngược lại là một `tuple`. Khi trả về tuple, phần tử đầu tiên là một danh sách chứa các hình ảnh đã tạo.

Hàm được gọi khi gọi pipeline cho việc sinh.

Ví dụ:
```py
>>> import torch
>>> from diffusers import StableDiffusion3ControlNetPipeline
>>> from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel
>>> from diffusers.utils import load_image

>>> controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny", torch_dtype=torch.float16)

>>> pipe = StableDiffusion3ControlNetPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet, torch_dtype=torch.float16
... )
>>> pipe.to("cuda")
>>> control_image = load_image(
...     "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/sd_controlnet/bird_canny.png"
... )
>>> prompt = "A bird in space"
>>> image = pipe(
...     prompt, control_image=control_image, height=1024, width=768, controlnet_conditioning_scale=0.7
... ).images[0]
>>> image.save("sd3.png")
```

#### encode_image[[diffusers.StableDiffusion3ControlNetPipeline.encode_image]]

```python
encode_image(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], device: device)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet.py#L742)

**Tham số:**

image (`PipelineImageInput`) : Ảnh đầu vào cần được mã hóa.

device : (`torch.device`): Thiết bị Torch.

**Trả về:** `torch.Tensor`

Biểu diễn đặc trưng của ảnh đã được mã hóa.

Mã hóa hình ảnh đã cho thành biểu diễn đặc trưng bằng cách sử dụng bộ mã hóa hình ảnh được huấn luyện trước.

#### encode_prompt[[diffusers.StableDiffusion3ControlNetPipeline.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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet.py#L365)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : prompt cần được mã hóa

prompt_2 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần được gửi đến `tokenizer_2` và `text_encoder_2`. Nếu không được định nghĩa, `prompt` sẽ được sử dụng trong tất cả các text-encoder

prompt_3 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần được gửi đến `tokenizer_3` và `text_encoder_3`. Nếu không được định nghĩa, `prompt` sẽ được sử dụng trong tất cả các text-encoder

device : (`torch.device`): thiết bị torch

num_images_per_prompt (`int`) : số lượng hình ảnh cần được tạo cho mỗi prompt

do_classifier_free_guidance (`bool`) : có sử dụng classifier free guidance hay không

negative_prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền `negative_prompt_embeds` thay thế. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu `guidance_scale` nhỏ hơn `1`).

negative_prompt_2 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh, sẽ được gửi đến `tokenizer_2` và `text_encoder_2`. Nếu không được định nghĩa, `negative_prompt` sẽ được sử dụng trong tất cả các text-encoder.

negative_prompt_3 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh, sẽ được gửi đến `tokenizer_3` và `text_encoder_3`. Nếu không được định nghĩa, `negative_prompt` sẽ được sử dụng trong tất cả các text-encoder.

prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số của prompt. Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

pooled_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các embedding văn bản đã được pool sẵn. Có thể dùng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, các embedding văn bản đã pool sẽ được tạo ra từ đối số đầu vào `prompt`.

negative_pooled_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các embedding văn bản pooled âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, pooled negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

clip_skip (`int`, *optional*) : Số lượng lớp cần bỏ qua từ CLIP khi tính toán các prompt embeddings. Giá trị 1 có nghĩa là đầu ra của lớp trước lớp cuối cùng sẽ được sử dụng để tính toán các prompt embeddings.

lora_scale (`float`, *tuỳ chọn*) : Một hệ số lora sẽ được áp dụng cho tất cả các lớp LoRA của text encoder nếu các lớp LoRA được nạp.

#### prepare_ip_adapter_image_embeds[[diffusers.StableDiffusion3ControlNetPipeline.prepare_ip_adapter_image_embeds]]

```python
prepare_ip_adapter_image_embeds(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: typing.Optional[torch.Tensor] = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet.py#L762)

**Tham số:**

ip_adapter_image (`PipelineImageInput`, *tùy chọn*) : Ảnh đầu vào để trích xuất đặc trưng cho IP-Adapter.

ip_adapter_image_embeds (`torch.Tensor`, *tùy chọn*) : Các embedding ảnh đã được tính trước.

device : (`torch.device`, *tùy chọn*): Thiết bị Torch.

num_images_per_prompt (`int`, mặc định là 1) : Số lượng hình ảnh cần được tạo cho mỗi prompt.

do_classifier_free_guidance (`bool`, mặc định là True) : Có sử dụng classifier free guidance hay không.

Chuẩn bị các vector nhúng hình ảnh để sử dụng trong IP-Adapter.

Phải truyền `ip_adapter_image` hoặc `ip_adapter_image_embeds`.

## StableDiffusion3ControlNetInpaintingPipeline[[diffusers.StableDiffusion3ControlNetInpaintingPipeline]]

#### diffusers.StableDiffusion3ControlNetInpaintingPipeline[[diffusers.StableDiffusion3ControlNetInpaintingPipeline]]

```python
diffusers.StableDiffusion3ControlNetInpaintingPipeline(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, controlnet: diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel | list[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModel, image_encoder: SiglipModel = None, feature_extractor: transformers.models.siglip.image_processing_pil_siglip.SiglipImageProcessorPil | None = None)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet_inpainting.py#L166)

**Tham số:**

transformer ([SD3Transformer2DModel](/docs/diffusers/v0.43.0/vi/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel)) : Kiến trúc Transformer điều kiện (MMDiT) để khử nhiễu các latents ảnh đã mã hóa.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/vi/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Một trình lập lịch được sử dụng kết hợp với `transformer` để khử nhiễu các latent ảnh đã mã hóa.

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã hình ảnh sang và từ các biểu diễn ẩn.

text_encoder (`CLIPTextModelWithProjection`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection), cụ thể là biến thể [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14), với một lớp chiếu bổ sung được khởi tạo bằng một ma trận chéo có kích thước là `hidden_size`.

text_encoder_2 (`CLIPTextModelWithProjection`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection), cụ thể là biến thể [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k).

text_encoder_3 (`T5EncoderModel`) : Bộ mã hóa văn bản đóng băng. Stable Diffusion 3 sử dụng [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel), cụ thể là biến thể [t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl).

tokenizer (`CLIPTokenizer`) : Tokenizer của lớp [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

tokenizer_2 (`CLIPTokenizer`) : Tokenizer thứ hai thuộc lớp [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

tokenizer_3 (`T5TokenizerFast`) : Tokenizer của lớp [T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer).

controlnet ([SD3ControlNetModel](/docs/diffusers/v0.43.0/vi/api/models/controlnet_sd3#diffusers.SD3ControlNetModel) hoặc `list[SD3ControlNetModel]` hoặc `SD3MultiControlNetModel`) : Cung cấp điều kiện bổ sung cho `transformer` trong quá trình khử nhiễu. Nếu bạn đặt nhiều ControlNet dưới dạng danh sách, đầu ra từ mỗi ControlNet sẽ được cộng lại với nhau để tạo thành một điều kiện bổ sung kết hợp.

image_encoder (`PreTrainedModel`, *tùy chọn*) : Mô hình thị giác được huấn luyện trước cho IP Adapter.

feature_extractor (`BaseImageProcessor`, *tùy chọn*) : Bộ xử lý ảnh cho IP Adapter.

#### __call__[[diffusers.StableDiffusion3ControlNetInpaintingPipeline.__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, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_mask: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, controlnet_conditioning_scale: float | list[float] = 1.0, controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = None, 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, 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: typing.Optional[torch.Tensor] = 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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet_inpainting.py#L986)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền `prompt_embeds` thay thế.

prompt_2 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần được gửi đến `tokenizer_2` và `text_encoder_2`. Nếu không được định nghĩa, `prompt` sẽ được sử dụng thay thế

prompt_3 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần được gửi đến `tokenizer_3` và `text_encoder_3`. Nếu không được định nghĩa, `prompt` sẽ được sử dụng thay thế

height (`int`, *optional*, mặc định là self.unet.config.sample_size * self.vae_scale_factor) : Chiều cao của hình ảnh được tạo ra, tính bằng pixel. Giá trị mặc định là 1024 để đạt kết quả tốt nhất.

width (`int`, *optional*, mặc định là self.unet.config.sample_size * self.vae_scale_factor) : Độ rộng tính bằng pixel của hình ảnh được tạo ra. Mặc định được đặt là 1024 để đạt kết quả tốt nhất.

num_inference_steps (`int`, *optional*, mặc định là 50) : Số bước khử nhiễu. Số bước khử nhiễu nhiều hơn thường dẫn đến hình ảnh có chất lượng cao hơn, với cái giá là suy luận chậm hơn.

sigmas (`list[float]`, *optional*) : Các sigma tùy chỉnh để sử dụng cho quá trình khử nhiễu với các trình lập lịch hỗ trợ tham số `sigmas` trong phương thức `set_timesteps` của chúng. Nếu không được định nghĩa, hành vi mặc định khi `num_inference_steps` được truyền vào sẽ được sử dụng.

guidance_scale (`float`, *optional*, mặc định là 5.0) : Thang độ dẫn hướng như được định nghĩa trong [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` được định nghĩa là `w` của phương trình 2. trong [Imagen Paper](https://huggingface.co/papers/2205.11487). Thang độ dẫn hướng được kích hoạt bằng cách đặt `guidance_scale > 1`. Thang độ dẫn hướng cao hơn khuyến khích tạo ra các hình ảnh gắn kết chặt chẽ với `prompt` văn bản, thường phải đánh đổi bằng chất lượng hình ảnh thấp hơn.

control_guidance_start (`float` hoặc `list[float]`, *tuỳ chọn*, mặc định là 0.0) : Tỷ lệ phần trăm của tổng số bước mà tại đó ControlNet bắt đầu áp dụng.

control_guidance_end (`float` hoặc `list[float]`, *tuỳ chọn*, mặc định là 1.0) : Tỷ lệ phần trăm tổng số bước mà tại đó ControlNet ngừng áp dụng.

control_image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]`, `list[np.ndarray]`) : `Image`, mảng numpy hoặc tensor đại diện cho một lô ảnh cần được inpaint (các phần của ảnh sẽ bị che bằng `control_mask` và được tô lại theo `prompt`). Đối với cả mảng numpy và tensor pytorch, khoảng giá trị mong đợi là từ `[0, 1]`. Nếu là tensor hoặc danh sách các tensor, hình dạng mong đợi phải là `(B, C, H, W)`. Nếu là mảng numpy hoặc danh sách các mảng, hình dạng mong đợi phải là `(B, H, W, C)` hoặc `(H, W, C)`.

control_mask (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]`, `list[np.ndarray]`) : `Image`, mảng numpy hoặc tensor đại diện cho một lô ảnh cần che `image`. Các pixel trắng trong mask sẽ được tô lại trong khi các pixel đen được giữ nguyên. Nếu `mask_image` là ảnh PIL, nó sẽ được chuyển đổi thành một kênh duy nhất (độ sáng) trước khi sử dụng. Nếu là mảng numpy hoặc tensor pytorch, nó phải chứa một kênh màu (L) thay vì 3, do đó hình dạng mong đợi cho tensor pytorch sẽ là `(B, 1, H, W)`. Và cho mảng numpy sẽ là `(B, H, W, 1)`, `(B, H, W)`, `(H, W, 1)` hoặc `(H, W)`.

controlnet_conditioning_scale (`float` hoặc `list[float]`, *tuỳ chọn*, mặc định là 1.0) : Đầu ra của ControlNet được nhân với `controlnet_conditioning_scale` trước khi được cộng vào phần dư trong `unet` gốc. Nếu nhiều ControlNet được chỉ định trong `init`, bạn có thể đặt thang đo tương ứng dưới dạng danh sách.

controlnet_pooled_projections (`torch.FloatTensor` có shape `(batch_size, projection_dim)`) : Các embeddings được chiếu từ embeddings của các điều kiện đầu vào của controlnet.

negative_prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền `negative_prompt_embeds` thay thế. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu `guidance_scale` nhỏ hơn `1`).

negative_prompt_2 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh, sẽ được gửi đến `tokenizer_2` và `text_encoder_2`. Nếu không được định nghĩa, `negative_prompt` sẽ được sử dụng thay thế

negative_prompt_3 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh, sẽ được gửi đến `tokenizer_3` và `text_encoder_3`. Nếu không được định nghĩa, `negative_prompt` sẽ được sử dụng thay thế

num_images_per_prompt (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng hình ảnh cần tạo cho mỗi prompt.

generator (`torch.Generator` hoặc `list[torch.Generator]`, *tùy chọn*) : Một hoặc một danh sách [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) để đảm bảo quá trình sinh là tất định.

latents (`torch.FloatTensor`, *tùy chọn*) : Các latents nhiễu đã được tạo trước, được lấy mẫu từ phân phối Gaussian, dùng làm đầu vào cho việc tạo ảnh. Có thể dùng để tinh chỉnh cùng một quá trình tạo với các prompt khác nhau. Nếu không được cung cấp, một tensor latents sẽ được tạo ra bằng cách lấy mẫu sử dụng `generator` ngẫu nhiên được cung cấp.

prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số của prompt. Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

pooled_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các embedding văn bản đã được pool sẵn. Có thể dùng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, các embedding văn bản đã pool sẽ được tạo ra từ đối số đầu vào `prompt`.

negative_pooled_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các embedding văn bản pooled âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, pooled negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

ip_adapter_image (`PipelineImageInput`, *tùy chọn*) : Đầu vào hình ảnh tùy chọn để làm việc với IP Adapters.

ip_adapter_image_embeds (`torch.Tensor`, *tùy chọn*) : Các embedding ảnh đã tạo trước cho IP-Adapter. Phải là một tensor có hình dạng `(batch_size, num_images, emb_dim)`. Nó phải chứa embedding ảnh âm nếu `do_classifier_free_guidance` được đặt thành `True`. Nếu không được cung cấp, các embedding sẽ được tính toán từ đối số đầu vào `ip_adapter_image`.

output_type (`str`, *tùy chọn*, mặc định là `"pil"`) : Định dạng đầu ra của hình ảnh được tạo. Chọn giữa [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` hoặc `np.array`.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` thay vì một tuple thông thường hay không.

joint_attention_kwargs (`dict`, *tùy chọn*) : Một từ điển kwargs mà nếu được chỉ định sẽ được truyền đến `AttentionProcessor` như đã định nghĩa dưới `self.processor` trong [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

clip_skip (`int`, *optional*) : Số lượng lớp cần bỏ qua từ CLIP khi tính toán các prompt embeddings. Giá trị 1 có nghĩa là đầu ra của lớp trước lớp cuối cùng sẽ được sử dụng để tính toán các prompt embeddings.

callback_on_step_end (`Callable`, *tùy chọn*) : Một hàm được gọi vào cuối mỗi bước khử nhiễu trong quá trình suy luận. Hàm này được gọi với các đối số sau: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` sẽ bao gồm một danh sách tất cả các tensor như được chỉ định bởi `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *optional*) : Danh sách các đầu vào tensor cho hàm `callback_on_step_end`. Các tensor được chỉ định trong danh sách sẽ được truyền dưới dạng tham số `callback_kwargs`. Bạn chỉ có thể bao gồm các biến được liệt kê trong thuộc tính `._callback_tensor_inputs` của lớp pipeline của bạn.

max_sequence_length (`int` mặc định là 256) : Độ dài tối đa của chuỗi để sử dụng với `prompt`.

**Trả về:** `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` hoặc `tuple`

`~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` nếu `return_dict` là True, ngược lại là một `tuple`. Khi trả về tuple, phần tử đầu tiên là một danh sách chứa các hình ảnh đã tạo.

Hàm được gọi khi gọi pipeline cho việc sinh.

Ví dụ:
```py
>>> import torch
>>> from diffusers.utils import load_image, check_min_version
>>> from diffusers.pipelines import StableDiffusion3ControlNetInpaintingPipeline
>>> from diffusers.models.controlnet_sd3 import SD3ControlNetModel

>>> controlnet = SD3ControlNetModel.from_pretrained(
...     "alimama-creative/SD3-Controlnet-Inpainting", use_safetensors=True, extra_conditioning_channels=1
... )
>>> pipe = StableDiffusion3ControlNetInpaintingPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers",
...     controlnet=controlnet,
...     torch_dtype=torch.float16,
... )
>>> pipe.text_encoder.to(torch.float16)
>>> pipe.controlnet.to(torch.float16)
>>> pipe.to("cuda")

>>> image = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog.png"
... )
>>> mask = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog_mask.png"
... )
>>> width = 1024
>>> height = 1024
>>> prompt = "A cat is sitting next to a puppy."
>>> generator = torch.Generator(device="cuda").manual_seed(24)
>>> res_image = pipe(
...     negative_prompt="deformed, distorted, disfigured, poorly drawn, bad anatomy, wrong anatomy, extra limb, missing limb, floating limbs, mutated hands and fingers, disconnected limbs, mutation, mutated, ugly, disgusting, blurry, amputation, NSFW",
...     prompt=prompt,
...     height=height,
...     width=width,
...     control_image=image,
...     control_mask=mask,
...     num_inference_steps=28,
...     generator=generator,
...     controlnet_conditioning_scale=0.95,
...     guidance_scale=7,
... ).images[0]
>>> res_image.save(f"sd3.png")
```

#### encode_image[[diffusers.StableDiffusion3ControlNetInpaintingPipeline.encode_image]]

```python
encode_image(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], device: device)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet_inpainting.py#L909)

**Tham số:**

image (`PipelineImageInput`) : Ảnh đầu vào cần được mã hóa.

device : (`torch.device`): Thiết bị Torch.

**Trả về:** `torch.Tensor`

Biểu diễn đặc trưng của ảnh đã được mã hóa.

Mã hóa hình ảnh đã cho thành biểu diễn đặc trưng bằng cách sử dụng bộ mã hóa hình ảnh được huấn luyện trước.

#### encode_prompt[[diffusers.StableDiffusion3ControlNetInpaintingPipeline.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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet_inpainting.py#L387)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : prompt cần được mã hóa

prompt_2 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần được gửi đến `tokenizer_2` và `text_encoder_2`. Nếu không được định nghĩa, `prompt` sẽ được sử dụng trong tất cả các text-encoder

prompt_3 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần được gửi đến `tokenizer_3` và `text_encoder_3`. Nếu không được định nghĩa, `prompt` sẽ được sử dụng trong tất cả các text-encoder

device : (`torch.device`): thiết bị torch

num_images_per_prompt (`int`) : số lượng hình ảnh cần được tạo cho mỗi prompt

do_classifier_free_guidance (`bool`) : có sử dụng classifier free guidance hay không

negative_prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền `negative_prompt_embeds` thay thế. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu `guidance_scale` nhỏ hơn `1`).

negative_prompt_2 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh, sẽ được gửi đến `tokenizer_2` và `text_encoder_2`. Nếu không được định nghĩa, `negative_prompt` sẽ được sử dụng trong tất cả các text-encoder.

negative_prompt_3 (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh, sẽ được gửi đến `tokenizer_3` và `text_encoder_3`. Nếu không được định nghĩa, `negative_prompt` sẽ được sử dụng trong tất cả các text-encoder.

prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số của prompt. Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

pooled_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các embedding văn bản đã được pool sẵn. Có thể dùng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, các embedding văn bản đã pool sẽ được tạo ra từ đối số đầu vào `prompt`.

negative_pooled_prompt_embeds (`torch.FloatTensor`, *tùy chọn*) : Các embedding văn bản pooled âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, pooled negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

clip_skip (`int`, *optional*) : Số lượng lớp cần bỏ qua từ CLIP khi tính toán các prompt embeddings. Giá trị 1 có nghĩa là đầu ra của lớp trước lớp cuối cùng sẽ được sử dụng để tính toán các prompt embeddings.

lora_scale (`float`, *tuỳ chọn*) : Một hệ số lora sẽ được áp dụng cho tất cả các lớp LoRA của text encoder nếu các lớp LoRA được nạp.

#### prepare_ip_adapter_image_embeds[[diffusers.StableDiffusion3ControlNetInpaintingPipeline.prepare_ip_adapter_image_embeds]]

```python
prepare_ip_adapter_image_embeds(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: typing.Optional[torch.Tensor] = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet_inpainting.py#L929)

**Tham số:**

ip_adapter_image (`PipelineImageInput`, *tùy chọn*) : Ảnh đầu vào để trích xuất đặc trưng cho IP-Adapter.

ip_adapter_image_embeds (`torch.Tensor`, *tùy chọn*) : Các embedding ảnh đã được tính trước.

device : (`torch.device`, *tùy chọn*): Thiết bị Torch.

num_images_per_prompt (`int`, mặc định là 1) : Số lượng hình ảnh cần được tạo cho mỗi prompt.

do_classifier_free_guidance (`bool`, mặc định là True) : Có sử dụng classifier free guidance hay không.

Chuẩn bị các vector nhúng hình ảnh để sử dụng trong IP-Adapter.

Phải truyền `ip_adapter_image` hoặc `ip_adapter_image_embeds`.

## StableDiffusion3PipelineOutput[[diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput]]

#### diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput[[diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput]]

```python
diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_diffusion_3/pipeline_output.py#L10)

**Tham số:**

images (`list[PIL.Image.Image]` hoặc `np.ndarray`) : danh sách các hình ảnh PIL đã khử nhiễu có độ dài `batch_size` hoặc mảng numpy có hình dạng `(batch_size, height, width, num_channels)`. Các hình ảnh PIL hoặc mảng numpy thể hiện các hình ảnh đã khử nhiễu của pipeline khuếch tán.

Lớp đầu ra cho các pipeline Stable Diffusion.