Ana içeriğe geç

LoRA eğitimi

imagehub.training, kendi görüntülerinizle bir LoRA adaptörü eğitir. Kendi LoRA katmanlarıyla ve kendi eğitim döngüsüyle gelir (PEFT veya Accelerate gerekmez) ve isteğe bağlı olarak kurulur; çekirdek paket yalnızca PyTorch'a bağlı kalır.

1. Kurulum ve indirme

pip install "imagehub[training]"
python -m imagehub.pretrained sd-v1-5 checkpoints/sd-v1-5

2. Görüntüleri hazırlama

Görüntüleri tek bir klasöre koyun; yanlarına her görüntü için bir satır içeren bir metadata.jsonl dosyası ekleyin:

my_images/
  metadata.jsonl
  0001.png
  0002.jpg
{"file_name": "0001.png", "text": "a photo of sks dog on the beach"}
{"file_name": "0002.jpg", "text": "a photo of sks dog in the snow"}

Eksik dosyalar, boş alt yazılar ve okunamayan görüntüler veri seti oluşturulurken bildirilir. Öğeleri {"image": PIL görüntüsü, "text": str} olan, uzunluğu bilinen her veri seti de çalışır; örneğin bir Hugging Face datasets veri seti. imagehub o pakete bağımlı değildir.

3. Eğitme

from imagehub.training import ImageFolderDataset, Trainer, TrainingArguments

trainer = Trainer(
    model="sd-v1-5",
    checkpoint="checkpoints/sd-v1-5",
    args=TrainingArguments(output_dir="runs/my-dog", max_steps=1000),
    train_dataset=ImageFolderDataset("my_images"),
)
result = trainer.train()
print(result.training_loss)
trainer.save_model("runs/my-dog/final")

Loss her logging_steps adımda yazdırılır. Her save_steps adımda ve sonda, eğitici output_dir/checkpoint-N/ klasörüne adaptörü ve eğitimin tam durumunu yazar. Eğitim yarıda kalırsa son kayıttan devam edin:

trainer.train(resume_from_checkpoint=True)

Devam ettirilen eğitim, kesintisiz eğitimle birebir aynı adaptörü verir.

4. Adaptörü kullanma

from imagehub import pipeline

with pipeline(
    "t2i",
    backend="sd-v1-5",
    model="checkpoints/sd-v1-5",
    lora="runs/my-dog/final/adapter.safetensors",
) as pipe:
    image = pipe("a photo of sks dog in a bucket", seed=0).images[0]

adapter.safetensors diffusers düzenindedir; diffusers load_lora_weights de okur.

Değerlendirme ve örnek görüntüler

trainer = Trainer(
    model="sd-v1-5",
    checkpoint="checkpoints/sd-v1-5",
    args=TrainingArguments(
        output_dir="runs/my-dog",
        max_steps=1000,
        eval_strategy="steps",
        eval_steps=200,
        validation_prompts=["a photo of sks dog in a bucket"],
    ),
    train_dataset=ImageFolderDataset("my_images"),
    eval_dataset=ImageFolderDataset("my_val_images"),
)
trainer.train()
print(trainer.evaluate())  # {"eval_loss": 0.1234}

eval_loss, değerlendirme görüntüleri üzerinde gradyansız hesaplanan eğitim loss'udur. Difüzyon loss'u rastgele gürültüye ve zaman adımına bağlıdır; bu yüzden bunlar görüntünün sırasına göre tohumlanır ve görüntüler ortadan kırpılır. Aynı adaptörü iki kez değerlendirmek aynı sayıyı verir; eğitim boyunca eğri zara değil adaptöre göre değişir. Her değerlendirme noktasında (ve sonda) her doğrulama prompt'u o anki adaptörle output_dir/samples/step-N/<i>.png olarak çizilir; görüntü, seed, validation_num_inference_steps ve validation_guidance_scale ile pipeline(..., lora=...) çıktısının aynısıdır.

Özel batch'ler

data_collator, veri setinden gelen öğe listesini bir batch'e çevirir. Varsayılanı görüntüleri yeniden boyutlandırır, kırpar, çevirir, normalize eder ve alt yazıları tokenize eder. Kendi collator'ınız {"pixel_values": [-1, 1] aralığında (B, 3, H, W), "input_ids": (B, 77)} döndürmelidir:

trainer = Trainer(..., data_collator=my_collator)

Birebir devam ettirme, rastgelelik durumu checkpoint'te saklanan varsayılan collator için garantilidir.

Birden fazla GPU

Aynı betiği torchrun ile çalıştırın; içinde hiçbir şey değişmez:

torchrun --nproc_per_node=4 train.py

Her süreç her batch'in kendi payıyla eğitilir ve adaptör gradyanlarının ortalaması alınır; böylece bütün süreçlerde aynı adaptör kalır. Etkin batch per_device_train_batch_size × gradient_accumulation_steps × süreç sayısıdır. Yalnız ilk süreç yazdırır; checkpoint'leri, örnek görüntüleri ve save_model çıktısını o yazar. Checkpoint aynı süreç sayısıyla devam ettirilir. Dağıtık eğitim CUDA (NCCL) veya CPU (gloo) ile çalışır; MPS ile çalışmaz.

Ayarlar

Yalnızca output_dir ve max_steps zorunludur. Varsayılanlar diffusers'ın train_text_to_image_lora.py betiğini izler.

Argüman Varsayılan Anlamı
learning_rate 1e-4 AdamW öğrenme hızı
per_device_train_batch_size, per_device_eval_batch_size 1, 1 her süreçte mikro-batch başına görüntü
gradient_accumulation_steps 1 optimizer adımı başına mikro-batch
lr_scheduler, lr_warmup_steps "constant", 0 ayrıca constant_with_warmup, linear, cosine
max_grad_norm 1.0 gradyan kırpma; 0 kapatır
adam_beta1, adam_beta2, adam_weight_decay, adam_epsilon 0.9, 0.999, 1e-2, 1e-8 AdamW ayarları
mixed_precision "no" "fp16" veya "bf16"; adaptör ve optimizer float32 kalır
resolution, center_crop, random_flip 512, False, False görüntü dönüşümü
lora_rank, lora_alpha, lora_dropout model betiğinin varsayılanı, model betiğinin varsayılanı, 0.0 adaptör boyutu ve ölçeği (alpha / rank); Qwen-Image 2.1 (16 / 16) ve Krea 2 (32 / 32) hariç 4 / 4
lora_target_modules ailenin varsayılanı adaptör takılan katmanlar: U-Net'lerde, Qwen-Image, Z-Image ve Lumina 2'de to_q, to_k, to_v, to_out.0; FLUX.2 klein'de ayrıca to_qkv_mlp_proj ve ilk 24 tek blok için değişmez attn.to_out yolları; HiDream-I1 görüntü dikkatinde to_q, to_k, to_v, to_out; SD 3'te sekiz ortak dikkat izdüşümü; Sana'da to_k, to_q, to_v
gradient_checkpointing False belleği azaltmak için U-Net ya da transformer bloklarını geri yayılımda yeniden hesaplar
noise_offset, snr_gamma, prediction_type 0.0, None, zamanlayıcınınki U-Net (DDPM) hedef seçenekleri
weighting_scheme, logit_mean, logit_std, mode_scale ailenin varsayılanı (SD 3 için "logit_normal", FLUX.1, FLUX.2 klein, Krea 2, Sana, Qwen-Image, Z-Image, Lumina 2 ve HiDream-I1 için "none"), 0.0, 1.0, 1.29 flow matching zaman adımı örneklemesi: ayrıca mode, sigma_sqrt, cosmap, none
precondition_outputs True flow matching: noise - latents yerine ön koşullanmış çıktıyı latent'lerle karşılaştırır
max_sequence_length 77 (SD 3), 512 (FLUX.1, FLUX.2 klein, Krea 2, Qwen-Image ve Z-Image), 300 (Sana), 256 (Lumina 2), 128 (HiDream-I1) metin prompt uzunluğu
system_prompt None Lumina 2'nin isteğe bağlı Gemma sistem prompt'u; diğer aileler reddeder
complex_human_instruction None Sana'nın isteğe bağlı prompt iyileştirme yönergesi; diğer aileler reddeder
guidance_scale 3.5 FLUX.1 ve FLUX.2 klein: guidance embedding'i olan checkpoint'lerde eğitim sırasındaki değeri
logging_steps, save_steps 10, 500 kayıt ve checkpoint sıklığı
eval_strategy, eval_steps "no", logging_steps "steps" her eval_steps adımda değerlendirir
validation_prompts yok her değerlendirme noktasında çizilen prompt'lar
validation_num_inference_steps, validation_guidance_scale 25, 7.5 bu görüntülerin örnekleme ayarları
report_to, run_name "none", None "wandb", "clearml" ya da ikisi bir liste olarak: train_loss, lr, eval_loss ve örnek görüntüleri gönderir (paket kurulu olmalı)
seed, device 0, "cpu" rastgelelik tohumu; GPU için "cuda" veya "mps"

Rank ve alpha seçimi

Adaptörün güncellemesi lora_alpha / lora_rank ile ölçeklenir. Difüzyon araçları küçük rank ve 1 civarı ölçek kullanır; dil ve konuşma eğiticileri genelde daha büyüklerini kullanır:

Kaynak Rank Alpha Ölçek
imagehub varsayılanı, diffusers eğitim betikleri (SD 1.5, SDXL, FLUX.1) 4 4 1
kohya sd-scripts varsayılanı 4 1 0.25
PEFT varsayılanı 8 8 1

Bir stil ya da basit bir konu için rank 4 yeter. Daha fazla ayrıntı için rank'ı 16-32'ye çıkarın ve alpha'yı rank'a eşit tutun; böylece ölçek ve uygun öğrenme hızı değişmez.

Desteklenen modeller

get_training_spec(model_id) bir modelin eğitilip eğitilemeyeceğini söyler; list_training_specs() katalogdaki her modeli listeler.

from imagehub.training import get_training_spec

spec = get_training_spec("sd-v1-5")
print(spec.support.value, spec.methods)  # native ('lora',)

native, modelin görüntü ve alt yazılarla, referans eğitim betiğine karşı doğrulanmış bir hedefle eğitildiği anlamına gelir; inference_only henüz eğitim yolu olmadığını söyler. methods neyin eğitilebildiğini listeler (bugün lora).

Model Destek Yöntemler
qwen-image native lora
sd-v1-1 native lora
sd-v1-2 native lora
sd-v1-3 native lora
sd-v1-4 native lora
sd-v1-5 native lora
dreamshaper-8 native lora
segmind-small-sd native lora
segmind-tiny-sd native lora
bk-sdm-base native lora
bk-sdm-small native lora
bk-sdm-tiny native lora
sd-v2-1 native lora
bk-sdm-v2-base native lora
bk-sdm-v2-small native lora
bk-sdm-v2-tiny native lora
sdxl-base-1.0 native lora
juggernaut-xl-v9 native lora
animagine-xl-4.0 native lora
dreamshaper-xl-1.0 native lora
z-image native lora
qwen-image-2.1 native lora
sd3-medium native lora
sd3.5-medium native lora
sd3.5-large native lora
flux2-klein-4b native lora
flux2-klein-9b native lora
flux1-dev native lora
flux1-krea-dev native lora
flux-1-lite-8b native lora
flux1-kontext-dev native lora
sana-1600m-1024 native lora
sana-600m-1024 native lora
sana-1.5-4.8b-1024 native lora
lumina-image-2.0 native lora
krea2-turbo native lora
ssd-1b native lora
segmind-vega native lora
koala-700m native lora
koala-1b native lora
playground-v2 native lora
hidream-i1-dev native lora
hidream-i1-full native lora

Diğer bütün modeller şimdilik inference_only: birkaç adımlık damıtılmış checkpoint'ler (sd-turbo, lcm-dreamshaper-v7, sdxs-512-0.9, SDXL Lightning, Hyper-SD, DMD2, sdxl-turbo, KOALA Lightning), SDXL refiner (görüntüden görüntüye), Playground v2.5 (DDPM değil, EDM) ve sd3.5-large-turbo (birkaç adımlık damıtılmış), sana-sprint-1.6b-1024 (damıtılmış) ve girdi görüntüsüne koşullu olan, diffusers'ta eğitim betiği bulunmayan Qwen-Image-Edit checkpoint'leri.

Sana yalnızca transformer'ını, betikteki to_k, to_q, to_v hedefleriyle eğitir. DC-AE'nin latentleri deterministiktir; bu nedenle rastgele akış önce gürültüyü, sonra flow zaman adımını çeker ve karışık hassasiyette otomatik kodlayıcı float32 kalır. Gemma 2 koşullaması Sana'nın attention maskesini ve 300 token varsayılanını kullanır; complex-human yönergesi isteğe bağlıdır ve betikteki gibi varsayılanı None'dır. Gradient checkpointing Sana transformer bloklarını geri yayılımda yeniden hesaplar.

Qwen-Image ve Qwen-Image 2.1 yalnızca transformer LoRA adaptörlerini to_k, to_q, to_v ve to_out.0 üzerinde eğitir. Her ikisi noise - latents flow hedefini, betiklerin "none" yoğunluk varsayılanını ve VAE posterior normalizasyonunu kullanır. Özgün Qwen-Image 512 tokenlık betimleyici sohbet prompt'unu, tek-kare latenti ve 2×2 uzamsal paketlemeyi kullanır; 2.1 sistem prompt tokenlarını çıkarır ve birleşik prompt/görüntü dizisini image-slot maskesiyle eğitir. max_sequence_length=512 yalnızca özgün sürüm içindir. Rank ve alpha ayarlanmadığında Qwen-Image betiğinin 4 / 4, Qwen-Image 2.1 ise 16 / 16 varsayılanlarını kullanır. Her iki backend de transformer adaptörlerini lora=, lora_scale= ve lora_fuse= ile yükler.

Krea 2, rank / alpha 32 / 32, betiğin "none" ağırlıklandırması, 512 tokenlık prompt ve 5-B posterior latent paketleme ile yalnızca transformer adaptörlerini eğitir. Turbo, 8 adımlı damıtılmış bir checkpoint olduğundan eğitilmez. Krea 2 Community License'ı kabul edip krea/Krea-2-Raw eğitim checkpoint'ini 6b0ece7fffb640c5e3bcbe0a7f10f66b8e60a603 revizyonunda indirin; Raw ile eğitilen adaptörler bu lisansa bağlıdır ve Turbo üzerinde lora=, lora_scale= ve lora_fuse= ile çalışır. Doğrulama eğitim snapshot'ında 8 adım ve guidance 0 kullanır.

Ideogram 4, tüm resmi checkpoint'leri nicemlenmiş olduğu için inference_only kalır. fp8 backend'i yine de transformer adaptörlerini lora=, lora_scale= ve lora_fuse= ile yükler. Diffusers düzenindeki transformer dosyaları attention.to_q, to_k, to_v ve to_out.0 kullanır; backend üç ayrı dikkat güncellemesini birleşik attention.qkv ağırlığının ilgili satır bloklarına, to_out.0 güncellemesini de attention.o katmanına eşler. Birleştirme, güncellemeleri uygulamadan önce fp8 ağırlığını hesaplama veri tipine nicemsizleştirir.

Z-Image yalnızca transformer LoRA adaptörlerini to_k, to_q, to_v ve to_out.0 üzerinde eğitir; betikteki rank / alpha varsayılanı 4 / 4, ağırlıklandırma "none", sohbet şablonu prompt uzunluğu 512'dir. KL VAE'nin deterministik posterior ortalaması yayınlanan shift ve scale ile normalleştirilir; modele (1000 - timestep) / 1000 verilir ve ters işaretli tahmin noise - latents ile karşılaştırılır. Gradient checkpointing her Z-Image transformer bloğunu yeniden hesaplar. Backend, transformer adaptörlerini lora=, lora_scale= ve lora_fuse= ile yükler. z-image-turbo damıtılmıştır ve inference_only kalır.

FLUX.2 klein 4B ve 9B yalnızca transformer LoRA adaptörlerini betikteki değişmez hedeflerle eğitir: to_k, to_q, to_v, to_out.0, to_qkv_mlp_proj ve single_transformer_blocks.0 ile .23 arasındaki attn.to_out. Rank / alpha varsayılanı 4 / 4, ağırlıklandırma "none", Qwen prompt'u 512 token ve resmi FLUX.2 kodu ile klein pipeline'ının çıkarımda kullandığı 9, 18 ve 27. katmanları kullanır. Eğitim betiğinin --text_encoder_out_layers varsayılanı olan 10, 20 ve 30, FLUX.2 [dev]'in Mistral katmanlarıdır; referans testi betiği 9, 18 ve 27 ile çalıştırır. Deterministik VAE posteriörü patchify edilir, VAE batch-normalization istatistikleriyle normalize edilir ve noise - latents hedefiyle flow matching yapılır; gradient checkpointing çift ve tek akış bloklarını kapsar. Guidance değeri yalnızca guidance embedding'i olan checkpoint'lere verilir; diğer klein checkpoint'leri yalnızca varsayılan eğitim değerini kabul eder. Backend transformer adaptörlerini lora=, lora_scale= ve lora_fuse= ile yükler.

Lumina-Image 2.0 yalnızca transformer LoRA adaptörlerini to_k, to_q, to_v ve to_out.0 üzerinde eğitir; betikteki rank / alpha varsayılanı 4 / 4, ağırlıklandırma "none", Gemma prompt uzunluğu 256 ve sistem prompt'u varsayılandır. Float32 KL VAE posteriörü kaydırılıp ölçeklendikten sonra ters flow matching kullanılır: transformer timestep / 1000 alır ve latents - noise tahmin eder. Gradient checkpointing Lumina 2 transformer bloklarını yeniden hesaplar. Backend adaptörleri lora=, lora_scale= ve lora_fuse= ile yükler; Lumina-Next ve Lumina-DiMOO inference_only kalır. Referans testleri betik varsayılanlarını, görüntü dönüşümünü, varsayılan sistem prompt'lu token kimlikleri ve dikkat maskesini, her ağırlıklandırmadaki adım çekilişlerini/kayıp/gradientleri ve diffusers yüklemesinden sonra rastgele veya üç adımda eğitilmiş adaptörlerin son latentleri ile uint8 piksellerini tam olarak karşılaştırır.

HiDream-I1 Dev ve Full yalnızca transformer LoRA adaptörlerini görüntü akışının to_k, to_q, to_v ve to_out izdüşümlerinde eğitir; rank / alpha 4 / 4, ağırlıklandırma "none", T5 ve Llama için prompt uzunluğu 128'dir. Dört metin kodlayıcısı ve VAE eğitim ağırlık dtype'ını kullanır. Örneklenen, kaydırılan ve ölçeklenen VAE latenti (1 - sigma) * latents + sigma * noise ile karıştırılır; ham zaman adımı inference-MoE transformer'a verilir ve ters işaretli tahmin noise - latents ile karşılaştırılır. Gradient checkpointing çift ve tek akış bloklarını kapsar. Backend transformer adaptörlerini lora=, lora_scale= ve lora_fuse= ile yükler. Referans testleri, diffusers içinde rastgele tekli, yığılı (0.8 / 0.5) ve birleştirilmiş adaptörlerle üç adımda eğitilmiş bir adaptörü yükler; kayıtlı hedefleri, değişen çıktıları ve aynı açık başlangıç latentlerinden elde edilen son latentleri ile uint8 pikselleri karşılaştırır. hidream-i1-fast damıtılmıştır ve inference_only kalır.

SDXL'de dönüşüm, diffusers'ın SDXL betiğindeki gibi önce yeniden boyutlandırır, sonra çevirir, sonra kırpar; her görüntünün özgün boyutunu ve kırpma köşesini U-Net'in boyut koşullaması olarak kaydeder. Karışık hassasiyette otomatik kodlayıcı float32 kalır. gradient_checkpointing=True, bellekten kazanmak için U-Net'in transformer ve resnet bloklarını geri yayılımda yeniden hesaplar; gradyanlar aynıdır.

SD 3 / 3.5, diffusers'ın train_dreambooth_lora_sd3.py betiğindeki flow matching hedefiyle eğitilir: zaman adımları kaydırılmış plandan weighting_scheme'e göre çekilir, gürültülü latent (1 - sigma) * latents + sigma * noise olur ve ön koşullanmış çıktı latent'lerle karşılaştırılır. Prompt, çıkarımdaki gibi CLIP-L ve CLIP-G'nin sondan bir önceki katmanlarını T5 ile birleştirir. DDPM seçenekleri (snr_gamma, prediction_type, noise_offset) SD 3'te, flow matching seçenekleri de U-Net ailelerinde reddedilir.

FLUX.1 dev, Krea dev ve Lite, diffusers'ın karşılık gelen FLUX DreamBooth adımıyla eğitilir: float32 VAE latentleri kaydırılır ve ölçeklenir, FLUX image id'leriyle paketlenir ve doğrudan noise - latents ile karşılaştırılır. CLIP havuzlanmış izdüşümü ve T5 prompt'u varsayılan olarak 512 token kullanır. Guidance embedding yalnızca kullanan checkpoint'lerde guidance_scale alır. Adaptör hedefleri hem çift-akışlı hem tek-akışlı blokları kapsar. flux1-kontext-dev, Kontext betiğinin koşul görüntüsü olmadan yaptığı gibi aynı adımla eğitilir ve tek akışlı proj_mlp katmanlarını da hedefler; görüntü koşullu Kontext eğitimi dahil değildir. flux1-schnell birkaç adımlık damıtılmış olduğundan inference_only kalır.

trainer = Trainer(
    model="sd3.5-medium",
    checkpoint="checkpoints/sd3.5-medium",
    args=TrainingArguments(
        output_dir="runs/my-dog-sd35",
        max_steps=1000,
        resolution=1024,
        mixed_precision="bf16",
        gradient_checkpointing=True,
        weighting_scheme="logit_normal",
    ),
    train_dataset=ImageFolderDataset("my_images"),
)

Neler doğrulandı

CPU'da float32 ile ilk adımın loss'u ve bütün LoRA gradyanları, küçük modellerde ve sd-v1-5'te diffusers eğitim adımıyla birebir aynıdır. Isınma, cosine planı ve kırpma içeren dört eğitim adımı diffusers + PEFT döngüsüyle aynıdır. Kaydedilen bir adaptör imagehub'da ve diffusers'ta aynı görüntüyü verir. Ayrıntılar doğrulama kaydında.