diffusers/main/tr/using-diffusers/other-formats.md

Model formatları

Diffusion modelleri genellikle Diffusers biçiminde veya tek dosya biçiminde saklanır. Model dosyaları, safetensors veya ckpt gibi çeşitli dosya türlerinde saklanabilir.

Format, ağırlıkların bir dizin yapısında saklanıp saklanmadığına; dosya türü ise bu ağırlıkların nasıl serileştirildiğine (örneğin safetensors veya ckpt) işaret eder.

Diffusers format                    Single-file format
model/                              model.safetensors   (or .ckpt)
├─ model_index.json                 └─ all components in one file
├─ unet/  (or transformer/)
├─ text_encoder/
├─ vae/
└─ scheduler/

Bu kılavuz, bu formatlardan ve dosyalardan pipeline ve modellerin nasıl yükleneceğini gösterecektir.

Diffusers biçimi

Diffusers biçimi, her modeli (UNet, transformer, text encoder) ayrı bir alt klasörde saklar. Modelleri ayrı saklamanın çeşitli avantajları vardır.

• İhtiyacınız olan tekil modeli yükleyebileceğiniz veya hepsini paralel olarak yükleyebileceğiniz için genel pipeline başlatma işlemi daha hızlıdır.
• Sadece bir modele ihtiyacınız varsa tüm pipeline bileşenlerini yüklemenize gerek kalmadığı için bellek kullanımı azalır. Birden fazla pipeline arasında paylaşılan bir modeli yeniden kullanın.
• Birden çok boru hattı arasında paylaşılan ortak modeller yalnızca bir kez indirildiği için depolama gereksinimleri daha düşüktür.
• Bir boru hattında yeni veya geliştirilmiş modelleri kullanma esnekliği.

Tek dosya biçimi

Tek dosya formatı, model ağırlıklarının tümünü (UNet, transformer, text encoder) tek bir dosyada saklar. Tek dosya formatlarının avantajları şunlardır:

• ComfyUI veya Automatic1111 ile daha yüksek uyumluluk.
• Tek bir dosyanın indirilmesi ve paylaşılması daha kolaydır.

Tek bir dosya yüklemek için from_single_file() kullanın.

import torch
from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)

from_single_file() metodu, yeni modeller veya zamanlayıcılar geçilmesini de destekler.

import torch
from diffusers import FluxPipeline, FluxTransformer2DModel

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/Kijai/flux-fp8/blob/main/flux1-dev-fp8.safetensors", dtype=torch.bfloat16
)
pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)

Yapılandırma seçenekleri

Diffusers format modelleri, katman sayısı ve dikkat başlıkları gibi önemli öznitelikleri içeren config.json dosyasına sahiptir. from_single_file() metodu, config.json dosyasından kullanılacak uygun yapılandırmayı otomatik olarak belirler. Ancak bu, nadir durumlarda başarısız olabilir; bu durumda config argümanını kullanmalısınız.

Hattadaki modellerin orijinal uygulamadan farklı olması veya doğru yapılandırmayı belirlemek için gerekli üstverilere sahip olmaması durumunda config argümanını da kullanmalısınız.

from diffusers import StableDiffusionXLPipeline

ckpt_path = "https://huggingface.co/segmind/SSD-1B/blob/main/SSD-1B.safetensors"

pipeline = StableDiffusionXLPipeline.from_single_file(ckpt_path, config="segmind/SSD-1B")

original_config parametresini local_files_only=True ile birlikte geçirdiğinizde Diffusers, pipeline bileşenlerini pipeline sınıfı imzasından çıkarır. Hub'dan yapılandırma dosyalarını indirmez; bu da çevrimdışıyken bozucu değişikliklerin önüne geçer. Bu yol, config parametresine yerel bir model yolu vermenin güvenilirliğinin altındadır ve hata verebilir. Çevrimdışıyken daha sonra bunlara ihtiyacınız olursa, yapılandırmaların yerel önbelleğe yerleşmesi için bir kez local_files_only=False ile çalıştırın.

Varsayılan yapılandırmaları, argümanları doğrudan from_single_file() fonksiyonuna geçirerek geçersiz kılabilirsiniz. Aşağıdaki örnekler, bir pipeline veya modelde yapılandırmaların nasıl geçersiz kılınacağını göstermektedir.

from diffusers import StableDiffusionXLInstructPix2PixPipeline

ckpt_path = "https://huggingface.co/stabilityai/cosxl/blob/main/cosxl_edit.safetensors"
pipeline = StableDiffusionXLInstructPix2PixPipeline.from_single_file(
    ckpt_path, config="diffusers/sdxl-instructpix2pix-768", is_cosxl_edit=True
)

from diffusers import UNet2DConditionModel

ckpt_path = "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0_0.9vae.safetensors"
model = UNet2DConditionModel.from_single_file(ckpt_path, upcast_attention=True)

Yerel dosyalar

from_single_file() yöntemi, checkpoint dosyasındaki anahtarlardan model türünü çıkararak bir pipeline veya model yapılandırmaya çalışır. Örneğin, Stable Diffusion XL taban modeline dayalı herhangi bir tek dosyalı checkpoint, stabilityai/stable-diffusion-xl-base-1.0 üzerinden yapılandırılır.

Yerel dosyalarla çalışıyorsanız, yapılandırma dosyalarını snapshot_download yöntemiyle ve model kontrol noktasını hf_hub_download ile indirin. Bu dosyalar önbellek dizininize indirilir, ancak local_dir argümanını kullanarak belirli bir dizine indirebilirsiniz.

from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors"
)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)

Simge bağlantısı

Simge bağlantılarını desteklemeyen bir dosya sistemiyle çalışıyorsanız, kontrol noktası dosyasını önce local_dir parametresiyle yerel bir dizine indirin. local_dir parametresini kullanmak simge bağlantılarını otomatik olarak devre dışı bırakır.

from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors",
    local_dir="my_local_checkpoints",
)
print("My local checkpoint: ", my_local_checkpoint_path)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)
print("My local config: ", my_local_config_path)

Bu yolları from_single_file() işlevine iletin.

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)

Dosya türleri

Modeller birden fazla dosya türünde saklanabilir. Safetensors en yaygın dosya türüdür ancak Hub'da veya difüzyon topluluğunda diğer dosya türleriyle karşılaşabilirsiniz.

safetensors

Safetensors, tensörleri güvenli bir şekilde depolamak ve yüklemek için güvenli ve hızlı bir dosya türüdür. Belirli saldırı türlerini sınırlamak için başlık boyutunu kısıtlar, tembel yüklemeyi (lazy loading) destekler (dağıtık kurulumlar için faydalıdır) ve genel olarak daha hızlı yüklenir.

Diffusers, safetensors dosyaları mevcut ve Safetensors kütüphanesi yüklüyse varsayılan olarak (zorunlu bir bağımlılık) safetensors dosyasını yükler.

Safetensor dosyalarını yüklemek için from_pretrained() veya from_single_file() kullanın.

import torch
from diffusers import DiffusionPipeline, StableDiffusionXLPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    dtype=torch.float16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
)

Diffusers eğitim betiğiyle eğitilmiş bir checkpoint kullanıyorsanız, LoRA yapılandırması gibi meta veriler otomatik olarak kaydedilir. Dosya yüklendiğinde, bu meta veriler ayrıştırılır ve LoRA doğru şekilde yapılandırılır. Hub'daki dosyanın yanındaki simgesine tıklayarak safetensors dosyasının meta verilerini inceleyebilirsiniz.

Diffusers ile eğitilmemiş kontrol noktaları için LoRA adaptör meta verilerini, bunları save_lora_weights() fonksiyonuna geçirerek kaydedin. Transformer için transformer_lora_adapter_metadata, metin kodlayıcı için text_encoder_lora_adapter_metadata kullanın. Ayrıca save_directory ve transformer_lora_layers veya text_encoder_lora_layers parametrelerinden en az birini de geçirmeniz gerekir. Bu yol yalnızca safetensors dosyaları için desteklenir.

import torch
from peft.utils import get_peft_model_state_dict
from diffusers import FluxPipeline

pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.load_lora_weights("linoyts/yarn_art_Flux_LoRA")

transformer_lora_layers = get_peft_model_state_dict(pipeline.transformer)
pipeline.save_lora_weights(
    save_directory="path/to/lora",
    transformer_lora_layers=transformer_lora_layers,
    transformer_lora_adapter_metadata={"r": 8, "lora_alpha": 8},
)

ckpt

Eski model ağırlıkları genellikle Python'un pickle aracıyla bir ckpt dosyasında kaydedilir.

Pickled dosyalar, kötü amaçlı kodun çalıştırılmasına izin verebileceği için güvensiz olabilir. Safetensors dosyaları kullanmak veya ağırlıkları safetensors dosyalarına dönüştürmek önerilir.

Bir ckpt dosyasını yüklemek için from_single_file() kullanın.

from diffusers import StableDiffusionPipeline

pipeline = StableDiffusionPipeline.from_single_file(
    "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.ckpt"
)

GGUF

GGUF, önceden kuantize edilmiş ağırlıkları tek bir dosyada saklar. Diffusers, GGUF'i GGUFQuantizationConfig ile model from_single_file() üzerinden yükler. Pipeline düzeyinde GGUF yükleme desteklenmez.

Kurulum adımları ve tam örnekler için GGUF sayfasına bakın.

import torch
from diffusers import FluxTransformer2DModel, GGUFQuantizationConfig

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf",
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
)

Biçim ve dosyaları dönüştürme

Diffusers, difüzyon ekosistemindeki daha fazla aracın bu formatları ve dosyaları kullanabilmesi için format ve dosya dönüştürme betikleri ve yöntemleri sağlar.

Dönüştürme betiğini bulmak için diffusers/scripts klasörüne göz atın. Sonuna "to_diffusers" eklenmiş betikler, bir modeli Diffusers biçimine dönüştürür. Her betiğin, dönüştürmeyi yapılandırmak için belirli bir argüman seti vardır. Kullanılabilir argümanları kontrol etmeyi unutmayın.

Aşağıdaki örnek, Diffusers biçiminde saklanan bir modeli tek dosya biçimine dönüştürür. Dönüştürülecek modelin yolunu ve dönüştürülmüş modelin kaydedileceği konumu belirtin. İsteğe bağlı olarak, modelin hangi dosya türü ve veri türü olarak kaydedileceğini de belirtebilirsiniz.

python convert_diffusers_to_original_sdxl.py --model_path path/to/model/to/convert --checkpoint_path path/to/save/model/to --use_safetensors

save_pretrained() metodu, bir modeli Diffusers biçiminde de kaydeder ve her model için alt klasörlerin oluşturulmasını sağlar. Varsayılan olarak dosyaları safetensor dosyaları olarak kaydeder.

from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
)
pipeline.save_pretrained("path/to/save/model")

Sonraki adımlar

• Tasarım kararları hakkında ve model ağırlıklarının kaydedilmesi ve yüklenmesi için neden Safetensors audited as really safe and becoming the default blog gönderisinde de belirtildiği gibi safetensor dosyalarının tercih edildiği hakkında daha fazla bilgi edinin.