Komut satırı arayüzü

diffusers-cli, Diffusers pipeline'lerini çalıştırmak, denetlemek ve paketlemek için kullanılan bir komut satırı istemcisidir.

Kullanılabilir komutlar

Bu sayfa, her alt komutun altındaki tüm seçenekler için ayrıntılar sunmaz. Herhangi bir alt komut için tam ve her zaman güncel seçenek listesini görmek için diffusers-cli <command> --help (diffusers-cli run --help) komutunu çalıştırın.

env

Python, PyTorch, Diffusers sürümlerini, CUDA bilgilerini ve kurulu isteğe bağlı bağımlılıkları yazdırır. Sorun açarken, bakımcıların kurulumunuzu yeniden oluşturabilmesi için bunu kullanın.

diffusers-cli env

şema

Ağırlıkları indirmeden hattın kabul ettiği girdileri döndürür. run için --pipeline-kwargs oluştururken kullanın.

Yalnızca indeks dosyası alınır. Standart iş akışları model_index.json dosyasını okur. Modüler iş akışları modular_model_index.json dosyasını okur. Özel blok depoları modular_config.json dosyasını okur ve Hub kodunun çalıştırılması gerektiğinden --trust-remote-code parametresine ihtiyaç duyar.

diffusers-cli --format json schema --model black-forest-labs/FLUX.1-dev
diffusers-cli schema --model my-org/my-custom-blocks --trust-remote-code

çalıştır

Bir pipeline’ı uçtan uca çalıştırın. CLI, standart ve modüler depoları otomatik olarak algılar. Medya girdilerini URL’lerden veya yerel yollardan otomatik yükler, pipeline’ın dönüş türüne göre çıktıları kaydeder ve --remote ile Hugging Face Sandbox üzerinde uzaktan çalıştırılabilir.

Minimal örnek:

diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev \
    --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}'

Hattın argümanlarını iletme

--pipeline-kwargs, pipeline(**kwargs) ile iletilecek bir JSON nesnesi alır. Bilinen medya-girdi anahtarlarındaki dize değerleri otomatik olarak yüklenir:

• Görseller (image, last_image, mask_image, control_image, ip_adapter_image, image_2) → load_image ile PIL.Image.
• Videolar (video, control_video) → load_video ile list[PIL.Image].
• Ses (initial_audio_waveforms, reference_audio, src_audio) → torchaudio.load üzerinden torch.Tensor.

diffusers-cli run \
    --model black-forest-labs/FLUX.2-klein-9B --dtype bf16 \
    --pipeline-kwargs '{"prompt": "make the fur grey", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png", "strength": 0.6}'

Hem medya anahtarları hem de metin anahtarları, bir partiyi tek bir pipeline çağrısıyla çalıştırmak için JSON dizisi kabul eder. Medya listesindeki her giriş ayrı ayrı yüklenir (URL, yerel yol veya bucket-mount yolu) ve Diffusers, listeyi GPU üzerinde tek bir ileri geçişte işler:

diffusers-cli run \
    --model black-forest-labs/FLUX.1-Kontext-dev --dtype bf16 \
    --pipeline-kwargs '{
        "prompt": ["make it grey", "make it pink", "make it blue"],
        "image": [
            "https://.../cat1.png",
            "https://.../cat2.png",
            "https://.../cat3.png"
        ]
    }'

Yükleniyor

CLI'nin model ağırlıklarını ve özel pipeline kodunu nasıl yükleyeceğini yapılandırın.

• --dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32} — ağırlık dtype.

• --device-map <value> — bileşen yerleşimi. Bir torch cihaz dizisi (cuda, cuda:0, cpu, mps), balanced (bileşenleri görünür GPU'lar arasında otomatik olarak böler) veya bileşen başına açık yerleşim için bir JSON sözlüğü kabul eder. Atlanırsa otomatik olarak algılanır. Daha fazla ayrıntı için device_map bölümüne bakın.

• --variant fp16 — bir ağırlık varyantı seçin.

• --revision <sha> — belirli bir model revizyonunu sabitlemek için kullanılır.

• --trust-remote-code — Hub'dan özel kodlara izin verir (özel pipeline sınıfları veya modüler bloklar içeren depolar için gereklidir). Standart özel pipeline'lar için Topluluk pipeline'ları ve Modüler Diffusers konusuna bakın.

• --lora <spec> — yükleme işleminden sonra bir LoRA adaptörü ekler. Her değer bir JSON sözlüğüdür. Birden fazla adaptörü yığmak için bayrağı tekrarlayın. Her giriş için lora_id zorunludur, lora_scale varsayılan olarak 1.0 değerini alır ve adapter_name isteğe bağlıdır (yığınlama sırasında lora_<i> olarak otomatik oluşturulur).

  • Tekli: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'
  • Birden fazla: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.6, "adapter_name": "koda"}' --lora '{"lora_id": "Shakker-Labs/FLUX.1-dev-LoRA-AntiBlur", "lora_scale": 0.4}'

  Tüm özellikler pipeline.load_lora_weights(...) ile yüklenir, ardından tek bir pipeline.set_adapters(names, adapter_weights=scales) çağrısıyla birlikte etkinleştirilir. Adaptör yığınlama, ölçek zamanlaması ve sıcak değiştirme konularının daha ayrıntılı açıklaması için LoRA bölümüne bakın.

Optimizasyonlar

• --cpu-offload {model, group, auto} — onload hedefi şuradan gelir --device-map (offload için düz cihaz dizgesi gereklidir).
  • model — standart boru hatları için enable_model_cpu_offload. Model offloading bölümüne bakın.
  • group — standart iş akışları için enable_group_offload(offload_type="leaf_level", use_stream=True). Grup offloading bölümüne bakın.
  • auto — yalnızca ComponentsManager ile modüler. Standart modlar, modüler boru hatlarında hata fırlatır. auto, standart boru hatlarında hata fırlatır.
• --offload-margin <size> — --cpu-offload auto altında aktivasyonlar için serbest bırakılan cihaz belleği, enable_auto_cpu_offload fonksiyonuna memory_reserve_margin parametresi olarak iletilir (varsayılan 3GB). Büyük bir tuvalin ileri yayılım sırasında bellek yetersizliği yaşaması durumunda bu değeri artırın. Offloader, bileşenler sığdığı sürece bunları bellekte tutar; bu nedenle yüksek VRAM'li bir kartta varsayılan marj, uzun bir videonun aktivasyonları için yeterince yer bırakmayabilir.
• --attention-backend — Hub üzerinden barındırılan dikkat çekirdekleri, ilk kullanımda otomatik olarak indirilir. Seçenekler default ve Diffusers'ta kayıtlı Hub arka uçlarıdır (örneğin flash_hub, flash_varlen_hub, flash_4_hub, sage_hub, sage_blackwell_hub). Güncel liste için diffusers-cli run --help komutunu çalıştırın. Yalnızca Transformer tabanlı iş akışlarını destekler ve eski UNet iş akışlarında bir uyarıyla yoksayılır. Dikkat arka uçları bölümüne bakın.
• --vae-tiling / --vae-slicing — VAE decode VRAM'ını düşürür. VAE tiling ve VAE slicing konularına bakın.
• --compile [JSON] — denoiser modüllerini torch.compile ile derler. CLI, tekrar eden bloklara sahip modüller için regional compilation tercih eder. Sadece --compile kullanıldığında fullgraph=true kullanılır. JSON nesnesi torch.compile iletilir. --context-parallel ile desteklenmez.
• --context-parallel — DiT tabanlı bir pipeline üzerinde Ulysses tarzı bağlam paralelliği. Yerel kullanımda torchrun gerektirir, ancak --remote altında CLI, torchrun --nproc-per-node=gpu komutunu sizin için sarar. Bağlam paralelliği bölümüne bakın.

Modüler hatlar

run, bir modüler depo’yu otomatik olarak algılar — ya bir modular_model_index.json içerdiği ya da model_index.json dosyasının bir ModularPipeline alt sınıfını adlandırması nedeniyle — bu nedenle dahil olmak için bir bayrak gerekmez.

Bazı modüler depolar, bileşenleri paylaşan ancak çalıştırılan blokların ve alınan girdilerin farklı olduğu, adlandırılmış görevler gibi birden fazla iş akışı tanımlar. Örneğin MiniMax-H3, t2va (metinden video ve ses), fl2va (ilk ve/veya son ana kare) ve ref2va (görsel, video ve ses referanslarının sıralı bir karışımı) seçeneklerini sunar. Birini seçmek için --workflow parametresini iletin:

diffusers-cli run \
    --model MiniMaxAI/MiniMax-H3 --workflow fl2va \
    --pipeline-kwargs '{
        "prompt": "the camera pushes in slowly as rain falls",
        "image": "opening-frame.png",
        "last_image": "closing-frame.png",
        "num_frames": 124
    }' \
    --output-key videos --output-key audio \
    --fps 24 --sampling-rate 32000 \
    --cpu-offload auto --dtype bf16

Bir iş akışı seçildiğinde yalnızca o görevin blokları korunur; bu sayede pipeline yalnızca ihtiyaç duyduğu bileşenleri bildirir ve load_components yalnızca bu bileşenlerin alt klasörlerini alır. Tüm iş akışlarının kullanılabilir kalmasını sağlamak ve pipeline'ın her çağrıda kendisine verilen girdilere göre seçim yapmasını istiyorsanız --workflow parametresini atlayın.

diffusers-cli --format json schema --model MiniMaxAI/MiniMax-H3 --trust-remote-code

--workflow yalnızca modüler iş akışlarına uygulanır. Standart iş akışlarında bir uyarıyla yok sayılır.

Modüler bir pipeline, tek bir çıktı nesnesi yerine PipelineState döndürür, bu nedenle --output-key kaydedilecek ara çıktıyı adlandırır.

Çıktılar

run, hattın çıktı türünü algılar:

• PIL.Image/list → <NNNN>.png (sıfır dolgulu indeks, örn. 0000.png)
• Görsel dizisi → 0000.mp4 (--fps kare hızını kontrol eder, varsayılan 8)
• Ses dizisi → 0000.wav (--sampling-rate oranı kontrol eder)
• Diğer her şey → JSON dökümü

Varsayılan çıktı dizini biçimi ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/'dir. Her çalıştırma kendi alt dizinine sahip olur, böylece ardışık çağrılar birbirinin üzerine yazmaz.

--output <path> ile geçersiz kılınabilir. Yolun nasıl genişletildiği, biçimine ve parti boyutuna bağlıdır:

Dizin çıktıları her zaman çıplak, sıfır dolgulu adlar kullanır (0000, 0001, …). Açık dosya yolları, seçtiğiniz kökü korur ve parti birden fazla çıktı ürettiğinde sıfır dolgulu indeks eklenir.

Çıktıları bir Hugging Face depolama kovasına yüklemek için --push-to kullanın. Aşağıdakilerden birini kabul eder:

• HF bucket kimliği (<namespace>/<name>)
• hf://buckets/<namespace>/<name>[/<subpath>] HF URI
• tarayıcı URL'si

Alt yol, klasör öneki olarak kullanılır. Var olmayan bucket oluşturulur ve nesneler [<subpath>/]<run_id>/<filename> altında yer alır.

# HF bucket id — files at hf://buckets/alice/edit-outputs/<run_id>/<file>
--push-to alice/edit-outputs

# URI with subpath — files at hf://buckets/alice/edit-outputs/greyscale/2026-07/<run_id>/<file>
--push-to hf://buckets/alice/edit-outputs/greyscale/2026-07

# Browser URL copy-paste from the Hub also works.
--push-to https://huggingface.co/buckets/alice/edit-outputs/tree/greyscale/2026-07

Aşağıdaki tablo uzak çalıştırmaları açıklar. Yerel çalıştırmalarda --push-to, yerel olarak kaydedilen çıktıyı yükler. Yerel dosya oluşturmayı engellemez.

--format, stdout meta verilerini (yollar, zamanlama, sandbox bilgisi) biçimlendirir. Medyanın kendisinin dosya biçimini değiştirmez. Yazılan görüntüler her zaman PNG, videolar MP4, sesler WAV'dir.

Uzak yürütme ( --remote )

Aynı çağrıyı Hugging Face Sandbox içinde çalıştırın — CLI'nin HTTP üzerinden yönettiği yalıtılmış bir bulut VM: girdileri yükler, hattı çalıştırır, çıktıları indirir ve ardından sandbox'ı sonlandırır. huggingface_hub>=1.23 gerektirir.

Sandbox, diffusers/diffusers-cli-cuda adlı, torch, CUDA ve CLI bağımlılıklarını zaten içeren önceden derlenmiş bir imajdan başlatılır; bu sayede soğuk bir çalıştırma önce kurulum yapmak yerine doğrudan üretmeye başlar.

diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}' \
    --remote --flavor a100-large

Uzak bayraklar:

• --flavor <name> — sandbox donanımı (örneğin, a10g-small, h200, rtx-pro-6000).
• --timeout <duration> — sandbox içindeki run komutu için maksimum duvar saati (varsayılan 10m).
• --dependencies <pkg> — ek pip bağımlılıkları (tekrarlanabilir), imajın üzerine kurulur. diffusers dalı tar dosyasını sabitlemek veya hattına özgü ekleri eklemek için faydalıdır.
• --namespace <name> — sandbox'ı farklı bir HF org/hesabı altında oluşturur.
• --image <ref> — sandbox görüntüsünü geçersiz kılar. --flavor sürücüsüyle uyumlu torch + CUDA içermelidir. CLI, varsayılan görüntünün kaçındığı bu işlemi, her soğuk sandbox'ta kendi bağımlılıklarını üstüne kurarak gerçekleştirir.
• --volume <bucket-id>[:<mount-path>] — bir HF depolama kovasını sandbox içine okuma-yazma dizini olarak bağlar (tekrarlanabilir). Varsayılan bağlama yolu /mnt/buckets/<bucket-id>'dir. Bağlanan dosyalara --pipeline-kwargs içinde herhangi bir yerel yol gibi başvurun. Yalnızca yeni sandbox oluşturulduğunda uygulanır ve --sandbox-id ile yeniden bağlanırken yok sayılır.

Varsayılan olarak her --remote çalıştırması geçicidir (oluştur → çalıştır → indir → öldür). Çalıştırmalar arasında sıcak bir kum havuzunu yeniden kullanmak için — bağımlılıkları, model ağırlık önbelleğini ve torch.compile önbelleğini diskinde tutmak için — onu hayatta tutun ve yeniden bağlanın:

• --keep-alive — çalıştırma sonrasında sandbox'u sonlandırmaz. Kimliği yazdırılır.
• --sandbox-id <id> — yeni bir tane oluşturmak yerine, açık tutulan bir sandbox'a yeniden bağlanın.
• --idle-timeout <duration> — bu kadar süre hareketsizlikten sonra otomatik kapatma (varsayılan 10m). Yalnızca yeni bir sandbox oluşturulduğunda uygulanır ve --sandbox-id ile yeniden bağlanırken yok sayılır.

# First run keeps the sandbox alive and prints sandbox_id=<id>.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a cat"}' --remote --flavor a100-large --keep-alive

# Reconnect for the next run — the model is already cached, so only inference runs.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a dog"}' --remote --flavor a100-large --sandbox-id <id>

# Stop it when done (or let it timeout).
hf sandbox kill <id>

custom_blocks

Yerel bir ModularPipelineBlocks alt sınıfını Hub'a yüklemek için paketler. Bir Python dosyasını okur, ModularPipelineBlocks'ten veya bileşik alt sınıflarından (SequentialPipelineBlocks, AutoPipelineBlocks, ConditionalPipelineBlocks, LoopSequentialPipelineBlocks) türeyen sınıfları AST taraması ile bulur, seçilen sınıfı örnekler ve mevcut çalışma dizininde save_pretrained çağrısını yapar.

# Package the first block found in ./block.py
diffusers-cli custom_blocks

# Point at a different file / pick a specific class
diffusers-cli custom_blocks --block_module_name my_block.py --block_class_name MyDenoiseBlock

Block sınıfı, sıfır yapıcı argümanla örneklenmeli ve varsayılanları __init__ içinde sabit kodlamalı veya çağrı anında pipeline state'inden yapılandırmayı okumalıdır.

fp16_safetensors

Bu komut artık kullanımdan kaldırılmıştır ve gelecekteki bir sürümde kaldırılacaktır.

Hub'daki bir kontrol noktasını .safetensors biçiminde fp16'ya dönüştürün ve sonucu ittirin. Daha hızlı yükleme için bir repodaki ağırlık boyutunu küçültmek için kullanışlıdır. Kesin argümanlar için diffusers-cli fp16_safetensors --help komutuna bakın.

beceriler

diffusers deposundan becerileri yükleyin (.ai/skills/).

# Install a single skill
diffusers-cli skills add "<skill name>"

# Install every skill in the registry
diffusers-cli skills add --all

# List available skills with a one-line summary of each
diffusers-cli skills list

# Preview a skill's SKILL.md without installing
diffusers-cli skills preview diffusers-cli

# Refetch and reinstall every managed skill
diffusers-cli skills update

# Install to the user-level directory instead of the current project
diffusers-cli skills add diffusers-cli --global

# Install for one agent instead of detecting it from the environment
diffusers-cli skills add --all --claude   # or --codex / --cursor

Hedef bayrağı olmadan, CLI onu başlatan ajan için veya ayırt edemediğinde tüm ajanlar için kurulumu yapar. Claude Code, .claude/skills/diffusers/ altında bir eklenti paketi alır (ad alanı olarak /diffusers:<skill name> olarak adlandırılır). Codex ve Cursor ise .agents/skills/<skill name>/ alır.