# ControlNet с Flux.1 FluxControlNetPipeline — это реализация ControlNet для Flux.1. ControlNet был представлен в статье [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) авторами Lvmin Zhang, Anyi Rao и Maneesh Agrawala. С помощью модели ControlNet можно передать дополнительное управляющее изображение для настройки и управления генерацией в Stable Diffusion. Например, если вы предоставите карту глубины, модель ControlNet сгенерирует изображение, сохраняющее пространственную информацию из карты глубины. Это более гибкий и точный способ управления процессом генерации изображений. Аннотация из статьи: *Мы представляем ControlNet — архитектуру нейронной сети для добавления пространственного управления условиями к крупным предобученным диффузионным моделям «текст в изображение». ControlNet фиксирует готовые к производству крупные диффузионные модели и повторно использует их глубокие и устойчивые слои кодирования, предобученные на миллиардах изображений, в качестве мощного каркаса для обучения разнообразному набору условных контролей. Нейронная архитектура соединяется с «нулевыми свёртками» (слоями свёртки с нулевой инициализацией), которые постепенно наращивают параметры от нуля и гарантируют, что вредоносный шум не может повлиять на дообучение. Мы тестируем различные условные контроли, например, края, глубину, сегментацию, позу человека и т. д., с Stable Diffusion, используя одно или несколько условий, с промптами или без них. Мы показываем, что обучение ControlNet устойчиво как на малых (<50k), так и на больших (>1m) наборах данных. Обширные результаты демонстрируют, что ControlNet может способствовать более широкому применению для управления диффузионными моделями изображений.* This controlnet code is implemented by [The InstantX Team](https://huggingface.co/InstantX). You can find pre-trained checkpoints for Flux-ControlNet in the table below: | Тип ControlNet | Разработчик | Ссылка | | -------- | ---------- | ---- | | Canny | [Команда InstantX](https://huggingface.co/InstantX) | [Ссылка](https://huggingface.co/InstantX/FLUX.1-dev-Controlnet-Canny) | | Глубина | [Команда InstantX](https://huggingface.co/InstantX) | [Ссылка](https://huggingface.co/Shakker-Labs/FLUX.1-dev-ControlNet-Depth) | | Union | [Команда InstantX](https://huggingface.co/InstantX) | [Ссылка](https://huggingface.co/InstantX/FLUX.1-dev-Controlnet-Union) | Также поддерживаются ControlNets от XLabs, которые были предоставлены командой [XLabs](https://huggingface.co/XLabs-AI). | Тип ControlNet | Разработчик | Ссылка | | -------- | ---------- | ---- | | Canny | [Команда XLabs](https://huggingface.co/XLabs-AI) | [Ссылка](https://huggingface.co/XLabs-AI/flux-controlnet-canny-diffusers) | | Глубина | [Команда XLabs](https://huggingface.co/XLabs-AI) | [Ссылка](https://huggingface.co/XLabs-AI/flux-controlnet-depth-diffusers) | | HED | [Команда XLabs](https://huggingface.co/XLabs-AI) | [Ссылка](https://huggingface.co/XLabs-AI/flux-controlnet-hed-diffusers) | > [!TIP] > Обязательно ознакомьтесь с [руководством по планировщикам](../../using-diffusers/schedulers), чтобы узнать, как исследовать баланс между скоростью и качеством планировщика, а также с разделом [повторное использование компонентов в разных конвейерах](../../using-diffusers/loading#reusing-models-in-multiple-pipelines), чтобы узнать, как эффективно загружать одни и те же компоненты в несколько конвейеров. ## FluxControlNetPipeline[[diffusers.FluxControlNetPipeline]] #### diffusers.FluxControlNetPipeline[[diffusers.FluxControlNetPipeline]] ```python diffusers.FluxControlNetPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, text_encoder_2: T5EncoderModel, tokenizer_2: T5Tokenizer, transformer: FluxTransformer2DModel, controlnet: diffusers.models.controlnets.controlnet_flux.FluxControlNetModel | list[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel] | tuple[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel] | diffusers.models.controlnets.controlnet_flux.FluxMultiControlNetModel, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/flux/pipeline_flux_controlnet.py#L177) **Параметры:** transformer ([FluxTransformer2DModel](/docs/diffusers/v0.43.0/ru/api/models/flux_transformer#diffusers.FluxTransformer2DModel)) : архитектура условного Transformer (MMDiT) для удаления шума из закодированных латентов изображения. scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : планировщик, используемый в связке с `transformer` для удаления шума из закодированных латентов изображения. vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них. text_encoder (`CLIPTextModel`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel), а именно вариант [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14). text_encoder_2 (`T5EncoderModel`) : [T5](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5EncoderModel), а именно вариант [google/t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl). tokenizer (`CLIPTokenizer`) : Токенизатор класса [CLIPTokenizer](https://huggingface.co/docs/transformers/en/model_doc/clip#transformers.CLIPTokenizer). tokenizer_2 (`T5TokenizerFast`) : Второй токенизатор класса [T5TokenizerFast](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5TokenizerFast). Пайплайн Flux для генерации изображений по тексту. Ссылка: https://blackforestlabs.ai/announcing-black-forest-labs/ #### __call__[[diffusers.FluxControlNetPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, negative_prompt: str | list[str] = None, negative_prompt_2: str | list[str] | None = None, true_cfg_scale: float = 1.0, 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_mode: int | list[int] | None = None, controlnet_conditioning_scale: float | list[float] = 1.0, 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, 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: list[torch.Tensor] | None = None, negative_ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, negative_ip_adapter_image_embeds: list[torch.Tensor] | None = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, 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 = 512) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/flux/pipeline_flux_controlnet.py#L677) **Параметры:** prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds` вместо него. prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые будут переданы в `tokenizer_2` и `text_encoder_2`. Если не задано, вместо этого будет использоваться `prompt` negative_prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передать `negative_prompt_embeds`. Игнорируется, если не используется направляющая (то есть игнорируется, если `true_cfg_scale` не больше `1`). negative_prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые не должны направлять генерацию изображения, и которые передаются в `tokenizer_2` и `text_encoder_2`. Если не задан, `negative_prompt` используется во всех текстовых кодировщиках. true_cfg_scale (`float`, *необязательный*, по умолчанию 1.0) : Истинное классификаторное свободное наведение (масштаб наведения) включается, когда `true_cfg_scale` > 1 и указан `negative_prompt`. height (`int`, *optional*, по умолчанию self.unet.config.sample_size * self.vae_scale_factor) : Высота генерируемого изображения в пикселях. По умолчанию установлено значение 1024 для достижения наилучших результатов. width (`int`, *optional*, по умолчанию self.unet.config.sample_size * self.vae_scale_factor) : Ширина генерируемого изображения в пикселях. По умолчанию установлено значение 1024 для достижения наилучших результатов. num_inference_steps (`int`, *optional*, по умолчанию 50) : Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода. sigmas (`list[float]`, *optional*) : Пользовательские сигмы для процесса денойзинга в планировщиках, поддерживающих аргумент `sigmas` в методе `set_timesteps`. Если не задано, будет использовано поведение по умолчанию при передаче `num_inference_steps`. guidance_scale (`float`, *optional*, по умолчанию 7.0) : Масштаб руководства, определённый в [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` определяется как `w` из уравнения 2 в [Imagen Paper](https://huggingface.co/papers/2205.11487). Масштаб руководства активируется при установке `guidance_scale > 1`. Более высокий масштаб руководства способствует генерации изображений, тесно связанных с текстовым `prompt`, обычно за счёт снижения качества изображения. 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]]` or `list[list[PIL.Image.Image]]`): Вводное условие ControlNet, задающее направление для `unet` при генерации. Если тип указан как `torch.Tensor`, значение передаётся в ControlNet без изменений. В качестве изображения также допускается `PIL.Image.Image`. Размеры выходного изображения по умолчанию совпадают с размерами `image`. Если переданы высота и/или ширина, `image` масштабируется соответственно. Если в `init` указано несколько ControlNet, изображения необходимо передавать в виде списка, чтобы каждый элемент списка мог быть корректно сгруппирован в батч для входа в один ControlNet. controlnet_conditioning_scale (`float` или `list[float]`, *необязательный*, по умолчанию 1.0) : Выходные данные ControlNet умножаются на `controlnet_conditioning_scale` перед добавлением к остаточному соединению в исходном `unet`. Если в `init` указано несколько ControlNet, соответствующий масштаб можно задать в виде списка. control_mode (`int` или `list[int]`,, *необязательный*, по умолчанию None) : Режим управления при применении ControlNet-Union. num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос. generator (`torch.Generator` или `list[torch.Generator]`, *необязательный*) : Один или список [генераторов torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации. latents (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Позволяет корректировать одну и ту же генерацию с помощью разных промптов. Если не заданы, тензор латентов будет сгенерирован путём выборки с использованием переданного случайного `generator`. prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`. pooled_prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, пул-эмбеддинги текста будут сгенерированы из аргумента входных данных `prompt`. negative_prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`. negative_pooled_prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные отрицательные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промптов. Если не предоставлены, пул-эмбеддинги negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`. ip_adapter_image : (`PipelineImageInput`, *необязательный*): Необязательное входное изображение для работы с IP-адаптерами. ip_adapter_image_embeds (`list[torch.Tensor]`, *optional*) : Предварительно сгенерированные эмбеддинги изображений для IP-Adapter. Должно быть списком той же длины, что и количество IP-адаптеров. Каждый элемент должен быть тензором формы `(batch_size, num_images, emb_dim)`. Если не указано, эмбеддинги вычисляются из входного аргумента `ip_adapter_image`. negative_ip_adapter_image : (`PipelineImageInput`, *необязательный*): Необязательное входное изображение для работы с IP-адаптерами. negative_ip_adapter_image_embeds (`list[torch.Tensor]`, *optional*) : Предварительно сгенерированные эмбеддинги изображений для IP-Adapter. Должно быть списком той же длины, что и количество IP-адаптеров. Каждый элемент должен быть тензором формы `(batch_size, num_images, emb_dim)`. Если не указано, эмбеддинги вычисляются из входного аргумента `ip_adapter_image`. output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода для генерируемого изображения. Выберите между [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` или `np.array`. return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли `~pipelines.flux.FluxPipelineOutput` вместо обычного кортежа. joint_attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который при указании передается в `AttentionProcessor`, определенный в `self.processor` в [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py). 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`, *optional*) : Список тензорных входных данных для функции `callback_on_step_end`. Тензоры, указанные в списке, будут переданы в качестве аргумента `callback_kwargs`. Вы сможете включать только переменные, перечисленные в атрибуте `._callback_tensor_inputs` вашего класса pipeline. max_sequence_length (`int` по умолчанию 512) : Максимальная длина последовательности, используемая с `prompt`. **Возвращает:** `~pipelines.flux.FluxPipelineOutput` или `tuple` `~pipelines.flux.FluxPipelineOutput`, если `return_dict` равно True, иначе `tuple`. При возврате кортежа первым элементом является список с сгенерированными изображениями. Функция, вызываемая при обращении к конвейеру для генерации. Примеры: ```py >>> import torch >>> from diffusers.utils import load_image >>> from diffusers import FluxControlNetPipeline >>> from diffusers import FluxControlNetModel >>> base_model = "black-forest-labs/FLUX.1-dev" >>> controlnet_model = "InstantX/FLUX.1-dev-controlnet-canny" >>> controlnet = FluxControlNetModel.from_pretrained(controlnet_model, torch_dtype=torch.bfloat16) >>> pipe = FluxControlNetPipeline.from_pretrained( ... base_model, controlnet=controlnet, torch_dtype=torch.bfloat16 ... ) >>> pipe.to("cuda") >>> control_image = load_image("https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg") >>> prompt = "A girl in city, 25 years old, cool, futuristic" >>> image = pipe( ... prompt, ... control_image=control_image, ... control_guidance_start=0.2, ... control_guidance_end=0.8, ... controlnet_conditioning_scale=1.0, ... num_inference_steps=28, ... guidance_scale=3.5, ... ).images[0] >>> image.save("flux.png") ``` #### encode_prompt[[diffusers.FluxControlNetPipeline.encode_prompt]] ```python encode_prompt(prompt: str | list[str], prompt_2: str | list[str] | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, max_sequence_length: int = 512, lora_scale: float | None = None) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/flux/pipeline_flux_controlnet.py#L344) **Параметры:** prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые будут отправлены в `tokenizer_2` и `text_encoder_2`. Если не задано, во всех text-encoders используется `prompt` device : (`torch.device`): устройство torch num_images_per_prompt (`int`) : количество изображений, которые должны быть сгенерированы для каждого промпта prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`. pooled_prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, пул-эмбеддинги текста будут сгенерированы из аргумента входных данных `prompt`. lora_scale (`float`, *optional*) : масштаб lora, который будет применён ко всем слоям LoRA текстового энкодера, если слои LoRA загружены. ## FluxPipelineOutput[[diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput]] #### diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput[[diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput]] ```python diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/flux/pipeline_output.py#L11) **Параметры:** images (`list[PIL.Image.Image]` или `torch.Tensor` или `np.ndarray`) : список денойзированных изображений PIL длиной `batch_size` или массив numpy или тензор torch формы `(batch_size, height, width, num_channels)`. Изображения PIL или массив numpy представляют денойзированные изображения диффузионного конвейера. Тензоры torch могут представлять либо денойзированные изображения, либо промежуточные латенты, готовые к передаче в декодер. Класс вывода для пайплайнов генерации изображений Flux.