Diffusers 文件
ControlNet 與 Hunyuan-DiT
並獲得增強的文件體驗
開始使用
ControlNet with Hunyuan-DiT
HunyuanDiTControlNetPipeline 是 Hunyuan-DiT 的 ControlNet 實現。
ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 《為文字到影像擴散模型新增條件控制》 中提出。
使用 ControlNet 模型，您可以提供額外的控制影像來調整和控制 Hunyuan-DiT 的生成。例如，如果您提供一張深度圖，ControlNet 模型將生成一張保留深度圖空間資訊的影像。這是一種更靈活、更精確的控制影像生成過程的方法。
論文摘要如下：
我們提出了 ControlNet，一種用於為大型預訓練文字到影像擴散模型新增空間條件控制的神經網路架構。ControlNet 鎖定生產就緒的大型擴散模型，並重用它們在數十億影像上預訓練的深度且魯棒的編碼層作為強大的骨幹網路，以學習各種條件控制。該神經網路架構透過“零卷積”（零初始化卷積層）連線，這些卷積層從零開始逐步增長引數，並確保不會有有害噪聲影響微調。我們使用 Stable Diffusion 測試了各種條件控制，例如，邊緣、深度、分割、人體姿態等，使用單一或多個條件，有無提示詞。我們表明 ControlNet 的訓練在小型（<50k）和大型（>1m）資料集上都具有魯棒性。大量結果表明 ControlNet 可能有助於控制影像擴散模型的更廣泛應用。
此程式碼由騰訊混元團隊實現。您可以在 Tencent Hunyuan 上找到 Hunyuan-DiT ControlNets 的預訓練檢查點。
HunyuanDiTControlNetPipeline
class diffusers.HunyuanDiTControlNetPipeline
< 來源 >( vae: AutoencoderKL text_encoder: BertModel tokenizer: BertTokenizer transformer: HunyuanDiT2DModel scheduler: DDPMScheduler safety_checker: StableDiffusionSafetyChecker feature_extractor: CLIPImageProcessor controlnet: typing.Union[diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel, typing.List[diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel], typing.Tuple[diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel], diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DMultiControlNetModel] text_encoder_2: typing.Optional[transformers.models.t5.modeling_t5.T5EncoderModel] = None tokenizer_2: typing.Optional[transformers.models.mt5.tokenization_mt5.MT5Tokenizer] = None requires_safety_checker: bool = True )
引數
- vae (AutoencoderKL) — 用於將影像編碼和解碼為潛在表示的變分自編碼器 (VAE) 模型。我們使用
sdxl-vae-fp16-fix。 - text_encoder (Optional[
~transformers.BertModel,~transformers.CLIPTextModel]) — 凍結的文字編碼器（clip-vit-large-patch14）。HunyuanDiT 使用經過微調的 [雙語 CLIP]。 - tokenizer (Optional[
~transformers.BertTokenizer,~transformers.CLIPTokenizer]) — 用於文字分詞的BertTokenizer或CLIPTokenizer。 - transformer (HunyuanDiT2DModel) — 騰訊混元設計的 HunyuanDiT 模型。
- text_encoder_2 (
T5EncoderModel) — mT5 嵌入器。具體來說，它是“t5-v1_1-xxl”。 - tokenizer_2 (
MT5Tokenizer) — mT5 嵌入器的分詞器。 - scheduler (DDPMScheduler) — 與 HunyuanDiT 結合使用以對編碼影像潛在表示去噪的排程器。
- controlnet (HunyuanDiT2DControlNetModel 或
List[HunyuanDiT2DControlNetModel]或 HunyuanDiT2DControlNetModel) — 在去噪過程中為unet提供額外的條件。如果將多個 ControlNet 設定為列表，則每個 ControlNet 的輸出將被相加以建立組合的額外條件。
用於使用 HunyuanDiT 生成英語/中文影像的管道。
此模型繼承自 DiffusionPipeline。請檢視超類文件，瞭解庫為所有管道實現的通用方法（例如下載或儲存、在特定裝置上執行等）。
HunyuanDiT 使用兩個文字編碼器：mT5 和 [雙語 CLIP]（我們自己微調的）
__call__
< 來源 >( prompt: typing.Union[str, typing.List[str]] = None height: typing.Optional[int] = None width: typing.Optional[int] = None num_inference_steps: typing.Optional[int] = 50 guidance_scale: typing.Optional[float] = 5.0 control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] = None controlnet_conditioning_scale: typing.Union[float, typing.List[float]] = 1.0 negative_prompt: typing.Union[str, typing.List[str], NoneType] = None num_images_per_prompt: typing.Optional[int] = 1 eta: typing.Optional[float] = 0.0 generator: typing.Union[torch._C.Generator, typing.List[torch._C.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: typing.Optional[str] = 'pil' return_dict: bool = True callback_on_step_end: typing.Union[typing.Callable[[int, int, typing.Dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'] guidance_rescale: float = 0.0 original_size: typing.Optional[typing.Tuple[int, int]] = (1024, 1024) target_size: typing.Optional[typing.Tuple[int, int]] = None crops_coords_top_left: typing.Tuple[int, int] = (0, 0) use_resolution_binning: bool = True ) → StableDiffusionPipelineOutput or tuple
引數
- prompt (
str或List[str], 可選) — 用於引導影像生成的提示詞或提示詞列表。如果未定義，您需要傳遞prompt_embeds。 - height (
int) — 生成影像的高度（畫素）。 - width (
int) — 生成影像的寬度（畫素）。 - num_inference_steps (
int, 可選, 預設為 50) — 去噪步數。更多的去噪步數通常會帶來更高的影像質量，但推理速度會更慢。此引數受strength調製。 - guidance_scale (
float, 可選, 預設為 7.5) — 較高的引導比例值鼓勵模型生成與文字prompt緊密相關的影像，但影像質量會降低。當guidance_scale > 1時啟用引導比例。 - control_guidance_start (
float或List[float], 可選, 預設為 0.0) — ControlNet 開始應用的步驟總數百分比。 - control_guidance_end (
float或List[float], 可選, 預設為 1.0) — ControlNet 停止應用的步驟總數百分比。 - control_image (
torch.Tensor,PIL.Image.Image,np.ndarray,List[torch.Tensor],List[PIL.Image.Image],List[np.ndarray], —List[List[torch.Tensor]],List[List[np.ndarray]]或List[List[PIL.Image.Image]]): 用於為unet提供生成指導的 ControlNet 輸入條件。如果型別指定為torch.Tensor，則直接將其傳遞給 ControlNet。PIL.Image.Image也可以作為影像接受。輸出影像的尺寸預設為image的尺寸。如果傳遞了 height 和/或 width，則image會相應地調整大小。如果在init中指定了多個 ControlNet，則影像必須作為列表傳遞，以便列表的每個元素都可以正確批處理以輸入到單個 ControlNet。 - controlnet_conditioning_scale (
float或List[float], 可選, 預設為 1.0) — ControlNet 的輸出在新增到原始unet的殘差之前會乘以controlnet_conditioning_scale。如果在init中指定了多個 ControlNet，您可以將相應的比例設定為列表。 - 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用於使生成具有確定性。 - prompt_embeds (
torch.Tensor, 可選) — 預生成的文字嵌入。可用於輕鬆調整文字輸入（提示詞權重）。如果未提供，則從prompt輸入引數生成文字嵌入。 - prompt_embeds_2 (
torch.Tensor, 可選) — 預生成的文字嵌入。可用於輕鬆調整文字輸入（提示詞權重）。如果未提供，將從 `prompt` 輸入引數生成文字嵌入。 - negative_prompt_embeds (
torch.Tensor, 可選) — 預生成的負向文字嵌入。可用於輕鬆調整文字輸入（提示詞權重）。如果未提供，將從 `negative_prompt` 輸入引數生成 `negative_prompt_embeds`。 - negative_prompt_embeds_2 (
torch.Tensor, 可選) — 預生成的負向文字嵌入。可用於輕鬆調整文字輸入（提示詞權重）。如果未提供，將從 `negative_prompt` 輸入引數生成 `negative_prompt_embeds`。 - 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, Dict], None],PipelineCallback,MultiPipelineCallbacks, 可選) — 在每個去噪步驟結束時呼叫的回撥函式或回撥函式列表。 - callback_on_step_end_tensor_inputs (
List[str], 可選) — 應該傳遞給回撥函式的張量輸入列表。如果未定義，將傳遞所有張量輸入。 - guidance_rescale (
float, 可選, 預設為 `0.0`) — 根據 `guidance_rescale` 重新調整 noise_cfg。基於 Common Diffusion Noise Schedules and Sample Steps are Flawed 的發現。參見第 3.4 節。 - original_size (
Tuple[int, int], 可選, 預設為 `(1024, 1024)`) — 影像的原始尺寸。用於計算時間 ID。 - target_size (
Tuple[int, int], 可選) — 影像的目標尺寸。用於計算時間 ID。 - crops_coords_top_left (
Tuple[int, int], 可選, 預設為 `(0, 0)`) — 裁剪區域的左上角座標。用於計算時間 ID。 - use_resolution_binning (
bool, 可選, 預設為 `True`) — 是否使用解析度分箱。如果為 `True`，輸入解析度將被對映到最接近的標準解析度。支援的解析度為 1024x1024、1280x1280、1024x768、1152x864、1280x960、768x1024、864x1152、960x1280、1280x768 和 768x1280。建議設定為 `True`。
返回
StableDiffusionPipelineOutput 或 tuple
如果 `return_dict` 為 `True`，將返回 StableDiffusionPipelineOutput，否則返回一個 `tuple`，其中第一個元素是生成的影像列表，第二個元素是一個 `bool` 列表，指示相應的生成影像是否包含“不適合工作”（nsfw）內容。
使用 HunyuanDiT 生成的管線呼叫函式。
示例
from diffusers import HunyuanDiT2DControlNetModel, HunyuanDiTControlNetPipeline
import torch
controlnet = HunyuanDiT2DControlNetModel.from_pretrained(
"Tencent-Hunyuan/HunyuanDiT-v1.1-ControlNet-Diffusers-Canny", torch_dtype=torch.float16
)
pipe = HunyuanDiTControlNetPipeline.from_pretrained(
"Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers", controlnet=controlnet, torch_dtype=torch.float16
)
pipe.to("cuda")
from diffusers.utils import load_image
cond_image = load_image(
"https://huggingface.co/Tencent-Hunyuan/HunyuanDiT-v1.1-ControlNet-Diffusers-Canny/resolve/main/canny.jpg?download=true"
)
## You may also use English prompt as HunyuanDiT supports both English and Chinese
prompt = "在夜晚的酒店門前，一座古老的中國風格的獅子雕像矗立著，它的眼睛閃爍著光芒，彷彿在守護著這座建築。背景是夜晚的酒店前，構圖方式是特寫，平視，居中構圖。這張照片呈現了真實攝影風格，蘊含了中國雕塑文化，同時展現了神秘氛圍"
# prompt="At night, an ancient Chinese-style lion statue stands in front of the hotel, its eyes gleaming as if guarding the building. The background is the hotel entrance at night, with a close-up, eye-level, and centered composition. This photo presents a realistic photographic style, embodies Chinese sculpture culture, and reveals a mysterious atmosphere."
image = pipe(
prompt,
height=1024,
width=1024,
control_image=cond_image,
num_inference_steps=50,
).images[0]encode_prompt
< 來源 >( prompt: str device: device = None dtype: dtype = None num_images_per_prompt: int = 1 do_classifier_free_guidance: bool = True negative_prompt: typing.Optional[str] = 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: typing.Optional[int] = None text_encoder_index: int = 0 )
引數
- prompt (
str或List[str], 可選) — 待編碼的提示詞 - device — (
torch.device): torch 裝置 - dtype (
torch.dtype) — torch 資料型別 - num_images_per_prompt (
int) — 每個提示詞應生成的影像數量 - do_classifier_free_guidance (
bool) — 是否使用分類器自由引導 - negative_prompt (
str或List[str], 可選) — 不用於引導影像生成的提示詞或提示詞列表。如果未定義，則必須傳入 `negative_prompt_embeds`。當不使用引導時（即，如果 `guidance_scale` 小於 `1`），此引數將被忽略。 - prompt_embeds (
torch.Tensor, 可選) — 預生成的文字嵌入。可用於輕鬆調整文字輸入，例如提示詞權重。如果未提供，將從 `prompt` 輸入引數生成文字嵌入。 - negative_prompt_embeds (
torch.Tensor, 可選) — 預生成的負向文字嵌入。可用於輕鬆調整文字輸入，例如提示詞權重。如果未提供，`negative_prompt_embeds` 將從 `negative_prompt` 輸入引數生成。 - prompt_attention_mask (
torch.Tensor, 可選) — 提示詞的注意力掩碼。當直接傳入 `prompt_embeds` 時必須提供。 - negative_prompt_attention_mask (
torch.Tensor, 可選) — 負向提示詞的注意力掩碼。當直接傳入 `negative_prompt_embeds` 時必須提供。 - max_sequence_length (
int, 可選) — 提示詞使用的最大序列長度。 - text_encoder_index (
int, 可選) — 要使用的文字編碼器索引。`0` 表示 clip，`1` 表示 T5。
將提示編碼為文字編碼器隱藏狀態。