ModularPipeline

ModularPipeline, ModularPipelineBlocks bileşenlerini, modelleri yükleyen ve bloklarda tanımlanan hesaplama adımlarını gerçekleştiren çalıştırılabilir bir pipeline'a dönüştürür. Bir pipeline'ı çalıştırmak için ana arayüzdür ve API'si DiffusionPipeline'a çok benzer, ancak birkaç önemli fark içerir.

Yükleme tembel (lazy)dir. DiffusionPipeline ile from_pretrained() hattı oluşturur ve tüm modelleri aynı anda yükler. ModularPipeline ile oluşturma ve yükleme iki ayrı adımdır: from_pretrained() yapılandırmayı okur ve her bileşenin nereden yükleneceğini bilir, ancak model ağırlıklarını fiilen yüklemez. Modelleri daha sonra dtype ve quantization_config gibi yükleme argümanlarını geçtiğiniz load_components() ile yüklersiniz.
Pipeline oluşturma için iki yol. Mevcut bir diffusers model deposuyla from_pretrained() kullanabilirsiniz — bu, varsayılan pipeline bloklarına otomatik olarak eşler ve ardından ek bir kurulum gerektirmeden ModularPipeline olarak dönüştürür. Şu anda hangi modellerin desteklendiğini görmek için modular_pipelines_directory öğesini kontrol edebilirsiniz. Ayrıca kendi pipeline'ınızı ModularPipelineBlocks bileşenlerinden oluşturup init_pipeline() yöntemiyle dönüştürebilirsiniz (daha fazla ayrıntı için bkz. Pipeline oluşturma).
Pipeline'in çalıştırılması aynıdır. Yüklendikten sonra, pipeline'ı alışık olduğunuz aynı argümanlarla çağırırsınız. Pipeline blokları AutoPipelineBlocks kullanarak girdilerinize dayanarak iş akışını otomatik olarak seçtiğinde, tek bir ModularPipeline birden fazla iş akışını (metinden görüntüye, görüntüden görüntüye, inpainting vb.) destekleyebilir.

Aşağıda SDXL ile metinden görüntüye, görüntüden görüntüye ve inpainting için tam örnekler yer almaktadır.

metinden görüntüye

görselden görseli

inpainting

Bu kılavuz, bir ModularPipeline oluşturmayı, bileşenlerini yönetmeyi ve hattı çalıştırmayı gösterir.

Bir pipeline oluşturma

ModularPipeline oluşturmanın iki yolu vardır. ModularPipelineBlocks birleştirerek ve init_pipeline() ile bir pipeline oluşturabilir veya mevcut bir pipeline'ı from_pretrained() ile yükleyebilirsiniz.

Ayrıca, cihaz yerleşimi ve bellek yönetimini ele almak için bir ComponentsManager da başlatabilirsiniz. Otomatik offloading'e ihtiyacınız yoksa, bu adımı atlayabilir ve hattı pipeline.to("cuda") ile cihazınıza manuel olarak taşıyabilirsiniz.

Bileşenlerin farklı iş akışları arasında nasıl yönetilebileceğine dair daha fazla ayrıntı için ComponentsManager belgesine bakın.

init_pipeline

init_pipeline(), herhangi bir ModularPipelineBlocks nesnesini ModularPipeline nesnesine dönüştürür.

Nasıl çalıştığını görmek için minimal bir blok tanımlayalım:

from transformers import CLIPTextModel
from diffusers.modular_pipelines import (
    ComponentSpec,
    ModularPipelineBlocks,
    PipelineState,
)

class MyBlock(ModularPipelineBlocks):
    @property
    def expected_components(self):
        return [
            ComponentSpec(
                name="text_encoder",
                type_hint=CLIPTextModel,
                pretrained_model_name_or_path="openai/clip-vit-large-patch14",
            ),
        ]

    def __call__(self, components, state: PipelineState) -> PipelineState:
        return components, state

Bunu bir pipeline'a dönüştürmek için init_pipeline() çağırın. Pipeline'daki blocks özniteliği, oluşturulduğu bloklardır — beklenen girdileri, çıktıları ve hesaplama mantığını belirler.

block = MyBlock()
pipe = block.init_pipeline()
pipe.blocks

MyBlock {
  "_class_name": "MyBlock",
  "_diffusers_version": "0.37.0.dev0"
}

Bloklar değiştirilebilirdir — bir pipeline oluşturmadan önce blokları serbestçe ekleyebilir, kaldırabilir veya değiştirebilirsiniz. Ancak bir pipeline oluşturulduktan sonra pipeline.blocks öğesini değiştirmek, bir kopya döndürdüğü için pipeline üzerinde etkili olmaz. Farklı bir blok yapısı istiyorsanız, blokları değiştirdikten sonra yeni bir pipeline oluşturun.

init_pipeline() fonksiyonunu bir depo belirtmeden çağırdığınızda, her bileşenin nereden yükleneceğini belirlemek için bloğun ComponentSpec içinde tanımlanan pretrained_model_name_or_path değerini kullanır. Pipeline'ı yazdırma işlemi, bileşen yükleme yapılandırmasını gösterir.

pipe
ModularPipeline {
  "_blocks_class_name": "MyBlock",
  "_class_name": "ModularPipeline",
  "_diffusers_version": "0.37.0.dev0",
  "text_encoder": [
    null,
    null,
    {
      "pretrained_model_name_or_path": "openai/clip-vit-large-patch14",
      "revision": null,
      "subfolder": "",
      "type_hint": [
        "transformers",
        "CLIPTextModel"
      ],
      "variant": null
    }
  ]
}

init_pipeline() fonksiyonuna bir depo geçirirseniz, bloğunuzun bileşenlerini o depodaki pipeline yapılandırmasıyla (model_index.json veya modular_model_index.json) eşleştirerek yükleme yolunu devre dışı bırakır. Yükleme özelliklerinin nasıl kaydedildiğini ve saklandığını görmek için Modular repository bölümüne bakın.

Aşağıdaki örnekte pretrained_model_name_or_path, "stabilityai/stable-diffusion-xl-base-1.0" olarak güncellenecektir.

pipe = block.init_pipeline("stabilityai/stable-diffusion-xl-base-1.0")
pipe
ModularPipeline {
  "_blocks_class_name": "MyBlock",
  "_class_name": "ModularPipeline",
  "_diffusers_version": "0.37.0.dev0",
  "text_encoder": [
    null,
    null,
    {
      "pretrained_model_name_or_path": "stabilityai/stable-diffusion-xl-base-1.0",
      "revision": null,
      "subfolder": "text_encoder",
      "type_hint": [
        "transformers",
        "CLIPTextModel"
      ],
      "variant": null
    }
  ]
}

Blokunuzdaki bir bileşen depoda yoksa null olarak kalır ve load_components() sırasında atlanır.

from_pretrained

from_pretrained(), blokları kendiniz tanımlamadan bir ModularPipeline oluşturmanın pratik bir yoludur.

Üç tür depoyla çalışır.

Bir diffusers deposu. Desteklenen herhangi bir model deposunu iletin; varsayılan pipeline bloklarına otomatik olarak eşlenir. Şu anda desteklenen modeller arasında SDXL, Wan, Qwen, Z-Image, Flux ve Flux2 yer alır.

from diffusers import ModularPipeline, ComponentsManager

components = ComponentsManager()
pipeline = ModularPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", components_manager=components
)

Modüler bir depo. Bu depolar, her bileşenin nereden yükleneceğini belirten bir modular_model_index.json dosyası içerir; bileşenler farklı depolardan gelebilir ve modüler depo kendisi hiçbir model ağırlığı içermeyebilir. Örneğin, diffusers/flux2-bnb-4bit-modular bir depodan kuantize edilmiş bir transformer yüklerken kalan bileşenleri başka bir depodan yükler. Format hakkında daha fazla ayrıntı için Modüler depo bölümüne bakın.

from diffusers import ModularPipeline, ComponentsManager

components = ComponentsManager()
pipeline = ModularPipeline.from_pretrained(
    "diffusers/flux2-bnb-4bit-modular", components_manager=components
)

Özel kod içeren modüler bir depo. Bazı depolar, yükleme yapılandırmasının yanı sıra özel pipeline blokları içerir. Bunları yüklemek için trust_remote_code=True ekleyin. Kendi bloklarınızı nasıl oluşturacağınızı görmek için Özel bloklar bölümüne bakın.

from diffusers import ModularPipeline, ComponentsManager

components = ComponentsManager()
pipeline = ModularPipeline.from_pretrained(
    "diffusers/Florence2-image-Annotator", trust_remote_code=True, components_manager=components
)

Pipeline blokları iş akışlarını tanımladığında (pipeline.blocks.available_workflows kontrol edin), yalnızca ilgili iş akışının bloklarını korumak için workflow= parametresini iletin — bu, get_workflow() ile aynı budama işlemidir. Pipeline bu durumda yalnızca o iş akışının kullandığı bileşenleri bildirir ve docstring'i tam olarak o iş akışının girdilerini açıklar.

pipeline = ModularPipeline.from_pretrained("Qwen/Qwen-Image", workflow="inpainting")

Bileşenler yükleniyor

ModularPipeline bileşenlerle otomatik olarak örneklenmez. Yalnızca yapılandırmayı ve bileşen tanımlarını yükler. Bileşenleri load_components() ile yükleyebilirsiniz.

Bu, geçerli bir yükleme özelliğine sahip tüm bileşenleri yükleyecektir.

import torch

pipeline.load_components(dtype=torch.float16)

Belirli bileşenleri adlarıyla da yükleyebilirsiniz. Aşağıdaki örnek yalnızca text_encoder bileşenini yükler.

pipeline.load_components(names=["text_encoder"], dtype=torch.float16)

Blokların iş akışlarını tanımladığı bir pipeline'da, workflow= yalnızca o iş akışının kullandığı bileşenleri yükler. Pipeline tüm bloklarını koruduğu için, tek bir pipeline'ı farklı iş akışları arasında çalıştırmak için pratik yol budur: her çağrı, yeni iş akışının hâlâ eksik bıraktığı bileşenleri ekler.

pipeline.load_components(workflow="inpainting", dtype=torch.float16)

Yükleme işleminden sonra, hattı yazdırma hangi bileşenlerin yüklendiğini gösterir — ilk iki alan, null değerinden bileşenin kütüphanesine ve sınıfına değişir.

pipeline

# text_encoder is loaded - shows library and class
"text_encoder": [
  "transformers",
  "CLIPTextModel",
  { ... }
]

# unet is not loaded yet - still null
"unet": [
  null,
  null,
  { ... }
]

dtype, variant, revision ve quantization_config gibi anahtar kelime argümanları, her bileşen için from_pretrained() fonksiyonuna aktarılır. Tüm bileşenlere uygulanacak tek bir değer geçebilir veya bileşen bazlı değerleri ayarlamak için bir sözlük (dict) geçebilirsiniz.

# apply bfloat16 to all components
pipeline.load_components(dtype=torch.bfloat16)

# different dtypes per component
pipeline.load_components(dtype={"transformer": torch.bfloat16, "default": torch.float32})

load_components() yalnızca henüz yüklenmemiş ve geçerli bir yükleme spec’i olan bileşenleri yükler. Bu, pipeline üzerinde bir bileşeni zaten ayarladıysanız, load_components() fonksiyonunu tekrar çağırmanın onu yeniden yüklemeyeceği anlamına gelir.

Bileşenleri güncelleme

update_components(), pipeline içindeki bir bileşeni yenisiyle değiştirir. Bir bileşen güncellendiğinde, yükleme spesifikasyonları da pipeline yapılandırmasında güncellenir ve load_components() sonraki çağrılarda bu bileşeni atlar.

AutoModel'den

AutoModel.from_pretrained() ile yüklenmiş bir model nesnesi geçebilirsiniz. Bu şekilde yüklenen modeller, yükleme bilgileriyle otomatik olarak etiketlenir.

from diffusers import AutoModel

unet = AutoModel.from_pretrained(
    "RunDiffusion/Juggernaut-XL-v9", subfolder="unet", variant="fp16", dtype=torch.float16
)
pipeline.update_components(unet=unet)

ComponentSpec'ten

Mevcut bileşen spesifikasyonunun bir kopyasını almak, onu düzenlemek ve yeni bir bileşen yüklemek için get_component_spec() kullanın.

unet_spec = pipeline.get_component_spec("unet")

# modify to load from a different repository
unet_spec.pretrained_model_name_or_path = "RunDiffusion/Juggernaut-XL-v9"

# load and update
unet = unet_spec.load(dtype=torch.float16)
pipeline.update_components(unet=unet)

Ayrıca, ComponentSpec nesnesini sıfırdan oluşturabilirsiniz.

Tüm bileşenler önceden eğitilmiş ağırlıklardan yüklenmez — bazıları bir yapılandırmadan oluşturulur (pipeline.config_component_names altında listelenir). Bunlar için load() yerine create() kullanın.

guider_spec = pipeline.get_component_spec("guider")
guider_spec.config = {"guidance_scale": 5.0}
guider = guider_spec.create()
pipeline.update_components(guider=guider)

Veya nesneyi doğrudan iletin.

from diffusers.guiders import ClassifierFreeGuidance

guider = ClassifierFreeGuidance(guidance_scale=5.0)
pipeline.update_components(guider=guider)

Kullanılabilir guiderlar ve bunların nasıl yapılandırılacağına dair daha fazla ayrıntı için Guiders kılavuzuna bakın.

Bir hattın aşamalara bölünmesi

Bloklar birleştirilebilir olduğundan, bir hattı parçalara ayırıp her aşama için ayrı hatlar oluşturabilirsiniz. Aşağıdaki örnek, metin kodlayıcı bloğunun hattın geri kalanından nasıl ayrıldığını gösterir; böylece istemi bağımsız olarak kodlayıp gömme değerlerini ana hatta iletebilirsiniz.

from diffusers import ModularPipeline, ComponentsManager
import torch

device = "cuda"  # or "mps", "xpu", "cpu"
dtype = torch.bfloat16
repo_id = "black-forest-labs/FLUX.2-klein-4B"

# get the blocks and separate out the text encoder
blocks = ModularPipeline.from_pretrained(repo_id).blocks
text_block = blocks.sub_blocks.pop("text_encoder")

# use ComponentsManager to handle offloading across multiple pipelines
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device=device)

# create separate pipelines for each stage
text_encoder_pipeline = text_block.init_pipeline(repo_id, components_manager=manager)
pipeline = blocks.init_pipeline(repo_id, components_manager=manager)

# encode text
text_encoder_pipeline.load_components(dtype=dtype)
text_embeddings = text_encoder_pipeline(prompt="a cat").get_by_kwargs("denoiser_input_fields")

# denoise and decode
pipeline.load_components(dtype=dtype)
output = pipeline(
    **text_embeddings,
    num_inference_steps=4,
).images[0]

ComponentsManager, birden çok pipeline arasında belleği yönetir. DiffusionPipeline içindeki, sabit bir sırayı izleyen offloading stratejilerinin aksine ComponentsManager, her model forward pass çalıştığında mevcut bellek durumuna göre offloading kararlarını dinamik olarak alır. Bu, kaç pipeline oluşturduğunuzdan veya bunları hangi sırayla çalıştırdığınızdan bağımsız olarak çalıştığı anlamına gelir. Daha fazla ayrıntı için ComponentsManager kılavuzuna bakın.

Pipeline aşamaları bileşenleri paylaşıyorsa (örneğin, kodlama ve çözümlendirme için kullanılan aynı VAE), yeniden yüklemek yerine update_components() ile zaten yüklenmiş bir bileşeni başka bir pipeline'a aktarabilirsiniz.

Modüler depo

Hatta önceden eğitilmiş bileşenler kullanılıyorsa bile bir depo gereklidir. Depo, yükleme spesifikasyonlarını ve meta verileri sağlar.

ModularPipeline, standart diffusers depolarıyla hazır olarak çalışır. Ancak daha fazla esneklik için bir modüler depo da oluşturabilirsiniz. Modüler depo, aşağıdaki 3 öğeyi içeren bir modular_model_index.json dosyası içerir.

library ve class, bileşenin hangi kütüphaneden yüklendiğini ve sınıfını gösterir. null ise bileşen henüz yüklenmemiş demektir.
loading_specs_dict, bileşenin yükleneceği depo ve alt klasör gibi bileşeni yüklemek için gereken bilgileri içerir.

Modüler bir deponun temel avantajı, bileşenlerin farklı depolardan yüklenebilmesidir. Örneğin, diffusers/flux2-bnb-4bit-modular, kuantize edilmiş dönüştürücüyü diffusers/FLUX.2-dev-bnb-4bit deposundan yüklerken, kalan bileşenleri black-forest-labs/FLUX.2-dev deposundan yükler.

Düzenli bir diffusers deposunu modüler bir depoya dönüştürmek için, pipeline'ı düzenli depoyu kullanarak oluşturun ve ardından Hub'a gönderin. Kaydedilen depo, tüm yükleme spesifikasyonlarını içeren bir modular_model_index.json dosyası içerecektir.

from diffusers import ModularPipeline

# load from a regular repo
pipeline = ModularPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0")

# push as a modular repository
pipeline.save_pretrained("local/path", repo_id="my-username/sdxl-modular", push_to_hub=True)

Varsayılan olarak, save_pretrained() Diffusers'ın serialize edebildiği, şu anda yüklü olan her bileşeni yazar. Yüklenmemiş veya serialize edilemeyen bileşenler yazılmaz ve mevcut yükleme spesifikasyonlarını korurlar. Bu, ne yapmak istediğinize bağlı olarak size iki farklı kaydetme yöntemi sunar.

Bağımsız bir kopya kaydet

Tüm bileşenleri yükleyin, ardından kaydedin. Her spec, çevrimdışı dahil olmak üzere her şeyi tek bir yerden yeniden yükleyecek şekilde sonuca işaret eder.

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.load_components()
pipe.save_pretrained("path/to/local-copy")

modular_model_index.json dosyasında kaydedilen hedef, save_pretrained() fonksiyonunun yazdığı yerdir: yerel bir kayıt için save_directory, push_to_hub=True parametresini geçirirseniz repo_id.

huggingface_hub>=1.32.0 sürümünde, aynı Xet destekli dosyalar herhangi bir Hub deposu arasında tek bir önbelleğe alınmış yükü paylaşabilir. Bu, parçalı bir kontrol noktasındaki (sharded checkpoint) bireysel dosyaları da içerir: aynı Xet hash'ine sahip bir parça (shard), diğer parçalar farklı olsa bile yeniden kullanılabilir. Her iki indirme de sembolik bağlantı (symlink) desteğine sahip aynı Hub önbellek dizinini kullanmalıdır. dtype, seri hale getirme (serialization) veya parça sınırlarının değiştirilmesi, dosya hash'lerini değiştirebilir ve yeniden kullanımı engelleyebilir. Bu, indirme trafiğini ve disk alanını tasarruf eder; yüklenen bileşenlerin kullandığı belleği değil.

Ortak önbellekleme en iyi çaba (best-effort) esasına dayanır. HF_HUB_DISABLE_SHARED_BLOBS=1 ayarlandığında yükleme işlemi yine de desteklenir, ancak ayrı kopyalar önbelleğe alınır. modular_model_index.json içindeki mevcut bileşen referansları değiştirilmez; modüler depoda saklanmayan bileşenler için dış referansları koruyun.

Mevcut modüler bir dizini güncelle

Göç isteğe bağlıdır: orijinal depoya yapılan referanslar zaten önbelleğe alınmış dosyalarını yeniden kullanır. Bir referans yalnızca yinelenen indirmeleri önlemek için kullanıldıysa ve bu bileşenin modüler depodan yüklenmesini istiyorsanız, referansı güncelleyin.

Öncelikle, modüler depoda aynı bileşen yapılandırmasının ve tüm gerekli ağırlık dosyalarının, ağırlık dizini ve parçalı bir kontrol noktası için her parçayı da kapsayacak şekilde, mevcut olduğunu kontrol edin. Eşleşen Xet özetleri, hangi ağırlık dosyalarının paylaşılan önbelleği yeniden kullanabileceğini belirler. Eksik olan veya bilinçli olarak başka bir kontrol noktasından yüklenen bileşenlere atıfları koruyun.

modular_model_index.json dosyasının yerel bir kopyasında yalnızca ilgili yükleme tanımını düzenleyin. Örneğin, modüler depodaki vae/ altında saklanan bir VAE'yi aynı ağırlık varyantıyla kullanmak için:

import json
from pathlib import Path

index_path = Path("path/to/local-copy/modular_model_index.json")
index = json.loads(index_path.read_text())
spec = index["vae"][2]
spec["pretrained_model_name_or_path"] = "my-username/my-modular-repo"
spec.pop("repo", None)
spec["subfolder"] = "vae"
spec["revision"] = None
index_path.write_text(json.dumps(index, indent=2) + "\n")

Bu, eski repo alanını da kaldırır. Kaynak depodaki bir revizyon, hedefteki bir revizyonu tanımlamaz: hedefin varsayılan dalı için None kullanın veya bileşeni içeren bir hedef revizyonunu sabitleyin. Dosya adları farklıysa subfolder ve variant değerlerini ayarlayın.

Güncellenmiş dizini yayınlamadan önce, ModularPipeline.from_pretrained("path/to/local-copy") ile yükleyin, load_components(names="vae") çağrısını yapın ve bileşenin beklenen parametrelerle yüklendiğini doğrulayın. Yalnızca düzenlenmiş dizini yükleyin; ağırlıkları yeniden kaydetmek, özniteliklerini değiştirebilir ve önbellek yeniden kullanımını engelleyebilir.

Mevcut bileşenlere atıfları koruyun

Sadece yenilerini (veya hiçbirisini) yükleyin. Yalnızca yüklenen bileşenler kaydedilir; diğerleri orijinal depolarına işaret eden birer imleç olarak kalır. Bir bileşeni değiştirirken diğerlerini orijinal depolarından yüklemeye devam etmek istediğinizde bu modu kullanın. Örneğin, özel bir transformer kaydedilirken kalan bileşenler temel depodan yüklenmeye devam eder.

pipe = ModularPipeline.from_pretrained("black-forest-labs/FLUX.2-dev")
pipe.update_components(transformer=my_custom_transformer)  # the only component in memory
pipe.save_pretrained("local/path", repo_id="my-username/flux2-custom-transformer", push_to_hub=True)

overwrite_modular_index=False parametresini geçerek modular_model_index.json içindeki yükleme özelliklerini olduğu gibi koruyabilirsiniz. Yükleme özelliği boş olan kaydedilmiş bir bileşen yine de hedefle doldurulur, çünkü korunacak bir şey yoktur.

Dosyaları başka bir şekilde taşımak, indeksi yeniden yazar. hf download --local-dir ile indirilen bir kopya hâlâ çalışır: bir pipeline yerel bir dizinden yüklendiğinde, o dizinde dosyaları bulunan her bileşen, kayıtlı depodan değil o dizinden yüklenir. hf upload ile yüklenen bir kopya eski konuma işaret etmeye devam eder, bu nedenle o durumda indeksi manuel olarak güncelleyin.

Modüler bir depo, Python kodu olarak özel pipeline blokları da içerebilir. Bu, Diffusers'a yerel olmayan özel blokları paylaşmanızı sağlar. Örneğin, diffusers/Florence2-image-Annotator yükleme yapılandırmasının yanı sıra özel bloklar da içerir:

Florence2-image-Annotator/
├── block.py                    # Custom pipeline blocks implementation
├── config.json                 # Pipeline configuration and auto_map
├── mellon_config.json          # UI configuration for Mellon
└── modular_model_index.json    # Component loading specifications

config.json dosyası, ModularPipeline'in özel blokları nerede bulacağını bildiren bir auto_map anahtarı içerir:

{
  "_class_name": "Florence2AnnotatorBlocks",
  "auto_map": {
    "ModularPipelineBlocks": "block.Florence2AnnotatorBlocks"
  }
}

Özel kod depolarını, from_pretrained içinde gösterildiği gibi trust_remote_code=True ile yükleyin. Kendi bloklarınızı nasıl oluşturacağınızı ve paylaşacağınızı görmek için Özel bloklar bölümüne bakın.

Update on GitHub