DDUF

Genel Bakış

DDUF (DDUF’un Diffusion Unified Format’ı), farklı model dağıtım yöntemlerini ve ağırlık kaydetme biçimlerini tüm model bileşenlerini tek bir dosyada paketleyerek birleştirmeyi amaçlayan, difüzyon modelleri için tek dosyalı bir biçimdir. Dil bağımsızdır ve tüm dosyanın indirilmesine gerek kalmadan uzaktan ayrıştırılabilir şekilde tasarlanmıştır.

Bu çalışma, GGUF biçiminden ilham almaktadır.

DDUF'da en popüler difüzyon modellerinden bazılarını kullanmaya başlamak için DDUF kuruluşuna göz atın.

Katkılarınızı kollarımızı açarak memnuniyetle karşılıyoruz!

Geniş çapta benimsenen bir dosya formatı oluşturmak için topluluktan erken geri bildirim alıyoruz. Henüz hiçbir şey kesinleşmedi ve herkesin görüşünü önemsiyoruz. Kullanım senaryonuz kapsamda değil mi? Lütfen DDUF organizasyonundaki tartışmalarda bize bildirin.

Öne çıkan özellikleri şunlardır.

1. Tek dosya paketleme.
2. Mevcut araçlardan yararlanmak için ZIP dosya biçimi tabanlıdır.
3. Sıkıştırma yok, hızlı yükleme ve kaydetme için mmap uyumluluğu sağlanır.
4. Dil bağımsız: araçlar Python, JavaScript, Rust, C++ vb. dillerde uygulanabilir.
5. HTTP uyumlu: metadata ve dosya yapısı, HTTP Range istekleri kullanılarak uzaktan alınabilir.
6. Esnek: Her model bileşeni, mevcut Diffusers yapısını takip ederek kendi dizininde saklanır.
7. Güvenli: ağırlık kaydetme biçimi olarak Safetensors kullanır ve ZIP bombalarını önlemek için iç içe geçmiş dizinleri yasaklar.

Teknik özellikler

Teknik olarak bir .dduf dosyası bir .zip arşividir. Evrensel olarak desteklenen bir dosya biçimi üzerine inşa ederek, zaten sağlam araçların mevcut olmasını sağlıyoruz. Ancak, difüzyon modellerinin gereksinimlerini karşılamak için bazı kısıtlamalar uygulanır:

• Veriler sıkıştırılmamış olarak saklanmalıdır (bayrak 0), bu da bellek eşlemesi kullanılarak tembel yüklemeye olanak tanır.
• Veriler, 4 GB üzerindeki dosyaların kaydedilmesine olanak tanıyan ZIP64 protokolü kullanılarak saklanmalıdır.
• Arşiv yalnızca .json, .safetensors, .model ve .txt dosyaları içerebilir.
• Arşivin kök dizininde bir model_index.json dosyası bulunmalıdır. Bu dosya, model ve bileşenleri hakkında metadata içeren bir anahtar-değer eşlemesi içermelidir.
• Her bileşen kendi dizininde saklanmalıdır (ör. vae/, text_encoder/). İç içe dosyalar UNIX tarzı yol ayraçlarını (/) kullanmalıdır.
• Her dizin, model_index.json dizinindeki bir bileşene karşılık gelmelidir.
• Her dizin bir json yapılandırma dosyası içermelidir (config.json, tokenizer_config.json, preprocessor_config.json, scheduler_config.json dosyalarından biri).
• Alt dizinler yasaktır.

Dosyanızın geçerli olup olmadığını kontrol etmek istiyor musunuz? Bunu şu Space ile kontrol edebilirsiniz: https://huggingface.co/spaces/DDUF/dduf-check.

Kullanım

huggingface_hub, Python'da DDUF dosyalarını işlemek için araçlar sağlar. Dosya bütünlüğünü doğrulamak için yerleşik kurallar ve DDUF dosyalarını okumak/dışa aktarmak için yardımcı işlevler içerir. Bu araçların, diffusers entegrasyonu gibi Python ekosisteminde benimsenmesi hedeflenmektedir. Benzer araçlar diğer diller (JavaScript, Rust, C++ vb.) için de geliştirilebilir.

DDUF dosyası nasıl okunur?

read_dduf_file fonksiyonuna bir DDUF dosyasının yolunu iletin. Bu işlem yalnızca meta verileri okur; bu nedenle hafif bir çağrıdır ve bellek kullanımınızı aşırı yormaz. Aşağıdaki örnekte, FLUX.1-dev.dduf dosyasını yerel olarak zaten indirdiğinizi varsayıyoruz.

>>> from huggingface_hub import read_dduf_file

# Read DDUF metadata
>>> dduf_entries = read_dduf_file("FLUX.1-dev.dduf")

read_dduf_file, DDUF arşivindeki her dosyaya karşılık gelen bir eşleme döndürür. Bir dosya, orijinal DDUF dosyasındaki girdinin dosya adını, ofsetini ve uzunluğunu içeren bir DDUFEntry veri sınıfı ile temsil edilir. Bu bilgi, dosyanın tamamını yüklemeksizin içeriğini okumak için faydalıdır. Pratikte, düşük seviyeli okuma işlemlerini kendiniz yönetmek yerine yardımcı işlevlere güveneceksiniz.

Örneğin, model_index.json içeriğinin yüklenmesi şu şekilde yapılır:

>>> import json
>>> json.loads(dduf_entries["model_index.json"].read_text())
{'_class_name': 'FluxPipeline', '_diffusers_version': '0.32.0.dev0', '_name_or_path': 'black-forest-labs/FLUX.1-dev', ...

İkili dosyalar için, as_mmap kullanarak ham baytlara erişmek isteyeceksiniz. Bu, baytları orijinal dosya üzerinde bir bellek eşlemesi (memory-mapping) olarak döndürür. Bellek eşlemesi, her şeyi belleğe yüklemeye gerek kalmadan yalnızca ihtiyacınız olan baytları okumanızı sağlar. Örneğin, safetensors ağırlıklarını yüklemenin yolu şöyledir:

>>> import safetensors.torch
>>> with dduf_entries["vae/diffusion_pytorch_model.safetensors"].as_mmap() as mm:
...     state_dict = safetensors.torch.load(mm) # `mm` is a bytes object

as_mmap, bellek eşleme özelliklerinden yararlanmak için bir bağlam yöneticisi içinde kullanılmalıdır.

DDUF dosyası nasıl yazılır?

Bir DDUF dosyası dışa aktarmak için export_folder_as_dduf fonksiyonuna bir klasör yolu iletin.

# Export a folder as a DDUF file
>>> from huggingface_hub import export_folder_as_dduf
>>> export_folder_as_dduf("FLUX.1-dev.dduf", folder_path="path/to/FLUX.1-dev")

Bu araç klasörü tarar, ilgili girdileri ekler ve dışa aktarılan dosyanın geçerli olduğunu doğrular. İşlem sırasında bir sorun oluşursa DDUFExportError yükseltilir.

Daha fazla esneklik için, nihai DDUF dosyasına dahil edilecek dosyaların listesini açıkça belirtmek için [export_entries_as_dduf] kullanın:

# Export specific files from the local disk.
>>> from huggingface_hub import export_entries_as_dduf
>>> export_entries_as_dduf(
...     dduf_path="stable-diffusion-v1-4-FP16.dduf",
...     entries=[ # List entries to add to the DDUF file (here, only FP16 weights)
...         ("model_index.json", "path/to/model_index.json"),
...         ("vae/config.json", "path/to/vae/config.json"),
...         ("vae/diffusion_pytorch_model.fp16.safetensors", "path/to/vae/diffusion_pytorch_model.fp16.safetensors"),
...         ("text_encoder/config.json", "path/to/text_encoder/config.json"),
...         ("text_encoder/model.fp16.safetensors", "path/to/text_encoder/model.fp16.safetensors"),
...         # ... add more entries here
...     ]
... )

export_entries_as_dduf, modelinizi diske kaydettiyseniz iyi çalışır. Peki, bellekte yüklü bir modeliniz varsa ve bunu doğrudan bir DDUF dosyasına serialize etmek istiyorsanız ne olur? export_entries_as_dduf, verinin nasıl iteratif olarak serialize edileceğini belirten bir Python generator sağlayarak bunu yapmanıza olanak tanır:

(...)

# Export state_dicts one by one from a loaded pipeline
>>> def as_entries(pipe: DiffusionPipeline) -> Generator[Tuple[str, bytes], None, None]:
...     # Build a generator that yields the entries to add to the DDUF file.
...     # The first element of the tuple is the filename in the DDUF archive. The second element is the content of the file.
...     # Entries will be evaluated lazily when the DDUF file is created (only 1 entry is loaded in memory at a time)
...     yield "vae/config.json", pipe.vae.to_json_string().encode()
...     yield "vae/diffusion_pytorch_model.safetensors", safetensors.torch.save(pipe.vae.state_dict())
...     yield "text_encoder/config.json", pipe.text_encoder.config.to_json_string().encode()
...     yield "text_encoder/model.safetensors", safetensors.torch.save(pipe.text_encoder.state_dict())
...     # ... add more entries here

>>> export_entries_as_dduf(dduf_path="my-cool-diffusion-model.dduf", entries=as_entries(pipe))

Diffusers ile bir DDUF dosyası yükleme

Diffusers, DDUF dosyaları için yerleşik bir entegrasyona sahiptir. Hub'da saklanan bir kontrol noktasından bir pipeline yüklemenin bir örneği aşağıdadır:

from diffusers import DiffusionPipeline
import torch

pipe = DiffusionPipeline.from_pretrained(
    "DDUF/FLUX.1-dev-DDUF", dduf_file="FLUX.1-dev.dduf", torch_dtype=torch.bfloat16
).to("cuda")
image = pipe(
    "photo a cat holding a sign that says Diffusers", num_inference_steps=50, guidance_scale=3.5
).images[0]
image.save("cat.png")

F.A.Q.

Neden ZIP üzerine inşa edelim?

ZIP çeşitli avantajlar sunar:

• Evrensel olarak desteklenen dosya biçimi
• Okuma için ek bağımlılık yok
• Yerleşik dosya indeksleme
• Geniş dil desteği

Arşivin başında bir içerik tablosu olan bir TAR neden kullanılmıyor?

Bu yorumdaki açıklamaya bakın.

Neden sıkıştırma yok?

• Büyük dosyaların doğrudan bellek eşlemesini etkinleştirir
• Tutarlı ve öngörülebilir uzak dosya erişimi sağlar
• Dosya okuma sırasında CPU yükünü önler
• safetensors ile uyumluluğu korur

Bir DDUF dosyasını değiştirebilir miyim?

Hayır. Şimdilik DDUF dosyaları değiştirilemez (immutable) olarak tasarlanmıştır. Bir modeli güncellemek için yeni bir DDUF dosyası oluşturun.

Hangi çerçeveler/uygulamalar DDUF'ları destekler?

• Diffusers

Diğer kütüphaneler ve çerçevelerle sürekli olarak temas kuruyoruz. Projenize destek eklemek isterseniz, DDUF org içinde bir Discussion açın.