Hızlı Başlangıç

Modular Diffusers, esnek ve özelleştirilebilir pipeline'ları hızlı bir şekilde oluşturmak için bir çerçevedir. Bu pipeline'lar, standart DiffusionPipeline'ların yapabildiklerinin ötesine geçebilir. Modular Diffusers'ın çekirdeğinde, yeni iş akışlarına uyum sağlamak için diğer bloklarla birleştirilebilen ModularPipelineBlocks bulunur. Bloklar, üretim görevlerini çalıştırmak için kullanıcı dostu bir arayüz olan ModularPipeline'a dönüştürülür.

Bu kılavuz, modüler bir hattın (pipeline) nasıl çalıştırılacağını, yapısının nasıl anlaşıldığını ve onu oluşturan blokları değiştirerek nasıl özelleştirileceğini gösterir. DiffusionPipeline ile aşinalığınız varsa, farklı çalışan konular için önce DiffusionPipeline'dan Geliyorsanız bölümünü okuyun.

Bir pipeline çalıştırın

ModularPipeline, modüler boru hatlarını yükleme, çalıştırma ve yönetme için ana arayüzdür.

import torch
from diffusers import ModularPipeline, ComponentsManager

# Use ComponentsManager to enable auto CPU offloading for memory efficiency
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda:0")

pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

image = pipe(
    prompt="cat wizard with red hat, gandalf, lord of the rings, detailed, fantasy, cute, adorable, Pixar, Disney",
).images[0]
image

from_pretrained() tembel yükleme kullanır - her bileşenin nereden yükleneceğini öğrenmek için yapılandırmayı okur, ancak load_components() çağrılana kadar model ağırlıklarını gerçekten yüklemez. Bu, bileşenlerin ne zaman ve nasıl yükleneceği üzerinde size kontrol sağlar.

ComponentsManager, enable_auto_cpu_offload ile birlikte, büyük modeller (ör. Qwen-Image) için bellek kullanımını azaltmak amacıyla modelleri gerektiğinde otomatik olarak CPU ile GPU arasında taşır. Daha fazla bilgi için ComponentsManager kılavuzuna göz atın.

Offloading'e ihtiyacınız yoksa, components_manager argümanını kaldırın ve hattı to("cuda") ile cihazınıza manuel olarak taşıyın.

Pipeline oluşturma ve Bileşenleri yükleme kılavuzlarında pipeline oluşturma ve yükleme hakkında daha fazla bilgi edinin.

Yapıyı anlama

Bir ModularPipeline iki parçadan oluşur: bir tanım (bloklar) ve bir durum (yüklenmiş bileşenler ve yapılandırmalar).

Halinizi görmek için pipeline'ı yazdırın — bileşenler ve yükleme durumları ile yapılandırmaları.

print(pipe)

QwenImageModularPipeline {
  "_blocks_class_name": "QwenImageAutoBlocks",
  "_class_name": "QwenImageModularPipeline",
  "_diffusers_version": "0.37.0.dev0",
  "transformer": [
    "diffusers",
    "QwenImageTransformer2DModel",
    {
      "pretrained_model_name_or_path": "Qwen/Qwen-Image",
      "revision": null,
      "subfolder": "transformer",
      "type_hint": [
        "diffusers",
        "QwenImageTransformer2DModel"
      ],
      "variant": null
    }
  ],
  ...
}

Tanıma pipe.blocks üzerinden erişin — bu, hattın iş akışlarını, girdilerini, çıktılarını ve hesaplama mantığını tanımlayan ModularPipelineBlocks'tür.

print(pipe.blocks)

QwenImageAutoBlocks(
  Class: SequentialPipelineBlocks

  Description: Auto Modular pipeline for text-to-image, image-to-image, inpainting, and controlnet tasks using QwenImage.
      
      Supported workflows:
        - `text2image`: requires `prompt`
        - `image2image`: requires `prompt`, `image`
        - `inpainting`: requires `prompt`, `mask_image`, `image`
        - `controlnet_text2image`: requires `prompt`, `control_image`
        ...

  Components:
      text_encoder (`Qwen2_5_VLForConditionalGeneration`)
      vae (`AutoencoderKLQwenImage`)
      transformer (`QwenImageTransformer2DModel`)
      ...

  Sub-Blocks:
    [0] text_encoder (QwenImageAutoTextEncoderStep)
    [1] vae_encoder (QwenImageAutoVaeEncoderStep)
    [2] controlnet_vae_encoder (QwenImageOptionalControlNetVaeEncoderStep)
    [3] denoise (QwenImageAutoCoreDenoiseStep)
    [4] decode (QwenImageAutoDecodeStep)
)

Çıktı şunu döndürür:

Desteklenen iş akışları (text2image, image2image, inpainting vb.)
Bileşen olarak içerdiği Alt-Bloklar (text_encoder, vae_encoder, denoise, decode)

İş Akışları

Bu pipeline birden çok iş akışını destekler ve sağladığınız girdilere göre davranışını uyarlar. Örneğin, pipeline'a image geçirirseniz, metinden görüntüye değil, görüntüden görüntüye iş akışını çalıştırır. Bunun alt yapısında nasıl çalıştığı hakkında daha fazla bilgi için AutoPipelineBlocks kılavuzuna göz atın.

from diffusers.utils import load_image

input_image = load_image("https://github.com/Trgtuan10/Image_storage/blob/main/cute_cat.png?raw=true")

image = pipe(
    prompt="cat wizard with red hat, gandalf, lord of the rings, detailed, fantasy, cute, adorable, Pixar, Disney",
    image=input_image,
).images[0]

Belirli bir iş akışının bloklarını çıkarmak için get_workflow() kullanın. Yalnızca o iş akışına ait blokları almak için iş akışı adını (ör. "image2image", "inpainting", "controlnet_text2image") iletin. Bu, belirli bir iş akışını özelleştirmek veya hata ayıklamak istediğinizde kullanışlıdır. Kullanılabilir tüm iş akışlarını görmek için pipe.blocks.available_workflows öğesini kontrol edebilirsiniz.

img2img_blocks = pipe.blocks.get_workflow("image2image")

Alt bloklar

Bloklar, diğer blokları içerebilir. pipe.blocks üst düzey blok tanımını (burada QwenImageAutoBlocks) size verirken, sub_blocks içindeki daha küçük bloklara erişmenizi sağlar.

QwenImageAutoBlocks şu bileşenlerden oluşur: text_encoder, vae_encoder, controlnet_vae_encoder, denoise ve decode.

Bu alt bloklar sırayla çalışır ve veri bir bloktan diğerine doğrusal olarak akar — her bloğun intermediate_outputs değeri, bir sonraki blok için inputs olarak kullanılabilir hale gelir. SequentialPipelineBlocks tam olarak bu şekilde çalışır.

Bunlara sub_blocks özelliği üzerinden erişebilirsiniz. doc özelliği, girdileri, çıktıları ve bileşenleri dahil olmak üzere herhangi bir bloğun tam dokümantasyonunu görmek için kullanışlıdır.

vae_encoder_block = pipe.blocks.sub_blocks["vae_encoder"]
print(vae_encoder_block.doc)

Bu blok, init_pipeline() ile kendi başına çalışabilmesi için bir pipeline'a dönüştürülebilir.

vae_encoder_pipe = vae_encoder_block.init_pipeline()

# Reuse the VAE we already loaded, we can reuse it with update_components() method
vae_encoder_pipe.update_components(vae=pipe.vae)

# Run just this block
image_latents = vae_encoder_pipe(image=input_image).image_latents
print(image_latents.shape)

Orijinal hattımızdaki VAE'yi yeniden yüklemek yerine yeniden kullanır ve bellek kullanımını verimli tutar. Daha fazla bilgi için Bileşenleri yükleme kılavuzuna göz atın.

Bloklar birleştirilebilir olduğundan, yeni iş akışları oluşturmak için hattın tanımına blok ekleyerek, çıkararak veya değiştirerek değişiklik yapabilirsiniz. Bir sonraki bölümde, ön işlenmiş bir canny kenar haritası yerine normal bir görsel geçebilmeniz için bir ControlNet hattına canny kenar algılama bloğu ekleyeceğiz.

Yeni iş akışları oluşturun

Bir ControlNet hattına canny kenar algılama bloğu ekleyelim. Önce, Hub'dan hazır bir canny bloğu yükleyin (kendi bloğunuzu oluşturmak için Özel Blokların Oluşturulması bölümüne bakın).

from diffusers.modular_pipelines import ModularPipelineBlocks

# Load a canny block from the Hub
canny_block = ModularPipelineBlocks.from_pretrained(
    "diffusers-internal-dev/canny-filtering",
    trust_remote_code=True,
)

print(canny_block.doc)

class CannyBlock

  Inputs:
      image (`Union[Image, ndarray]`):
          Image to compute canny filter on
      low_threshold (`int`, *optional*, defaults to 50):
          Low threshold for the canny filter.
      high_threshold (`int`, *optional*, defaults to 200):
          High threshold for the canny filter.
      ...

  Outputs:
      control_image (`PIL.Image`):
          Canny map for input image

get_workflow işlevini kullanarak QwenImageAutoBlocks içinden ControlNet iş akışını çıkarın.

# Get the controlnet workflow that we want to work with
blocks = pipe.blocks.get_workflow("controlnet_text2image")
print(blocks.doc)

class SequentialPipelineBlocks

  Inputs:
      prompt (`str`):
          The prompt or prompts to guide image generation.
      control_image (`Image`):
          Control image for ControlNet conditioning.
      ...

Çıkarılan iş akışı bir SequentialPipelineBlocks olup şu anda girdi olarak control_image gerektirir. Hattın bir düzenli görüntü kabul etmesi için canny bloğunu başa ekleyin.

# Insert canny at the beginning
blocks.sub_blocks.insert("canny", canny_block, 0)

# Check the updated structure: CannyBlock is now listed as first sub-block
print(blocks)
# Check the updated doc
print(blocks.doc)

class SequentialPipelineBlocks

  Inputs:
      image (`Union[Image, ndarray]`):
          Image to compute canny filter on
      low_threshold (`int`, *optional*, defaults to 50):
          Low threshold for the canny filter.
      high_threshold (`int`, *optional*, defaults to 200):
          High threshold for the canny filter.
      prompt (`str`):
          The prompt or prompts to guide image generation.
      ...

Artık pipeline, control_image yerine image girdisi alır. Bir dizideki bloklar verileri otomatik olarak paylaştığı için, canny bloğunun çıktısı (control_image) buna ihtiyaç duyan denoise bloğuna akar ve canny bloğunun girdisi (image), daha önceki bir blok tarafından sağlanmadığı için bir pipeline girdisi haline gelir.

Değiştirilen bloklardan bir pipeline oluşturun ve bir ControlNet modeli yükleyin. ControlNet, orijinal model deposunun bir parçası değildir, bu nedenle ayrı olarak yükleyin ve update_components() ile ekleyin.

pipeline = blocks.init_pipeline("Qwen/Qwen-Image", components_manager=manager)

pipeline.load_components(dtype=torch.bfloat16)

# Load the ControlNet model
controlnet_spec = pipeline.get_component_spec("controlnet")
controlnet_spec.pretrained_model_name_or_path = "InstantX/Qwen-Image-ControlNet-Union"
controlnet = controlnet_spec.load(dtype=torch.bfloat16)
pipeline.update_components(controlnet=controlnet)

Şimdi hattı çalıştırın - canny bloğu, görüntüyü ControlNet için ön işler.

from diffusers.utils import load_image

prompt = "cat wizard with red hat, gandalf, lord of the rings, detailed, fantasy, cute, adorable, Pixar, Disney"
image = load_image("https://github.com/Trgtuan10/Image_storage/blob/main/cute_cat.png?raw=true")

output = pipeline(
    prompt=prompt,
    image=image,
).images[0]
output

Sonraki adımlar

Temelleri öğrenin

Özel bloklar oluşturun

Bileşenleri paylaş

Görsel arayüz

Update on GitHub