# 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 | Komut | Amaç | |---|---| | [`env`](#env) | Hata raporları için ortam bilgilerini yazdırın. | | [`schema`](#schema) | Ağırlıkları indirmeden bir hattın `__call__` imzasını inceleyin. | | [`run`](#run) | Bir pipeline'ı yerel olarak veya bir Hugging Face Sandbox'ta çalıştırın. | | [`custom_blocks`](#customblocks) | Yerel bir `ModularPipelineBlocks` alt sınıfını Hub için paketleyin. | | [`fp16_safetensors`](#fp16safetensors) | Bir kontrol noktasını `.safetensors` olarak fp16'ya dönüştürün. | | [`skills`](#skills) | Yapay zekâ kodlama aracınıza önceden oluşturulmuş beceri demetlerini yükleyin. | > [!TIP] > 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 --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 kullanın; böylece bakıcılar (maintainers) kurulumunuzu yeniden oluşturabilir. ```bash diffusers-cli env ``` ## şema Ağırlıkları indirmeden hattın kabul ettiği girdileri döndürür. [`run`](#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. ```bash 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 olarak yükler, pipeline'ın dönüş türüne göre çıktıları kaydeder ve `--remote` aracılığıyla Hugging Face Sandbox üzerinde uzaktan çalıştırılabilir. Minimal örnek: ```bash 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 giriş anahtarlarındaki dize değerleri otomatik olarak yüklenir: - Images (`image`, `last_image`, `mask_image`, `control_image`, `ip_adapter_image`, `image_2`) → `load_image` üzerinden `PIL.Image`. - Videos (`video`, `control_video`) → `list[PIL.Image]`, `load_video` ile. - Audio (`initial_audio_waveforms`, `reference_audio`, `src_audio`) → `torch.Tensor`, `torchaudio.load` ile. ```bash 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, tüm listeyi GPU üzerinde tek bir ileri geçişte işler: ```bash 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 ` — 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](../training/distributed_inference#devicemap) bölümüne bakın. - `--variant fp16` — bir ağırlık varyantı seçin. - `--revision ` — 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 [Community pipelines](../using-diffusers/custom_pipeline_overview) ve [Modular Diffusers](../modular_diffusers/overview) konusuna bakın. - `--lora ` — 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_` 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](../tutorials/using_peft_for_inference) bölümüne bakın. ### Optimizasyonlar - `--cpu-offload {model, group, auto}` — onload hedefi `--device-map` parametresinden gelir (offload için düz bir cihaz dizisi gereklidir). - `model` — standart boru hatları için `enable_model_cpu_offload`. [Model offloading](../optimization/memory#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](../optimization/memory#group-offloading) bölümüne bakın. - `auto` — yalnızca [`ComponentsManager`](../modular_diffusers/components_manager) 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 ` — `--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ı](../optimization/attention_backends) bölümüne bakın. - `--vae-tiling` / `--vae-slicing` — VAE decode VRAM'ını düşürür. [VAE tiling](../optimization/memory#vae-tiling) ve [VAE slicing](../optimization/memory#vae-slicing) konularına bakın. - `--compile [JSON]` — denoiser modüllerini [torch.compile](../optimization/fp16#torchcompile) ile derler. CLI, tekrar eden bloklara sahip modüller için [regional compilation](../optimization/fp16#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](../training/distributed_inference#context-parallelism) bölümüne bakın. ### Modüler hatlar `run`, bir [modüler depo](../modular_diffusers/overview)’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 *workflow* tanımlar. Örneğin [MiniMax-H3](../api/pipelines/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: ```bash 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. ```bash 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`](../modular_diffusers/modular_pipeline) 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 → `.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--/`'dir. Her çalıştırma kendi alt dizinine sahip olur, böylece ardışık çağrılar birbirinin üzerine yazmaz. `--output ` ile geçersiz kılınabilir. Yolun nasıl genişletildiği, biçimine ve parti boyutuna bağlıdır: | `--output` | 1 çıktı | N çıktı | |---|---|---| | _atlandı_ | varsayılan dizin → `0000.png` | varsayılan dizin → `0000.png`, `0001.png`, `0002.png`, … | | `./results/` (sonunda `/` veya mevcut bir dizin) | `./results/0000.png` | `./results/0000.png`, `./results/0001.png`, … | | `my-cat.png` (dosya yolu) | `my-cat.png` (olduğu gibi kullanılır) | `my-cat-0000.png`, `my-cat-0001.png`, … | 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](https://huggingface.co/docs/hub/en/storage-buckets) yüklemek için `--push-to` kullanın. Aşağıdakilerden birini kabul eder: - HF bucket kimliği (`/`) - `hf://buckets//[/]` [HF URI](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris) - tarayıcı URL'si Alt yol, klasör öneki olarak kullanılır. Var olmayan bucket oluşturulur ve nesneler `[/]/` altında yer alır. ```bash # HF bucket id — files at hf://buckets/alice/edit-outputs// --push-to alice/edit-outputs # URI with subpath — files at hf://buckets/alice/edit-outputs/greyscale/2026-07// --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. | `--push-to` ayarlandı mı? | `--output` ayarlandı mı? | Sonuç | |---|---|---| | hayır | hayır | varsayılan yerel dizine indir | | hayır | evet | `--output` adresine indir | | evet | hayır | sadece bucket, yerel indirme yok | | evet | evet | bucket VE `--output` | `--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](https://huggingface.co/docs/huggingface_hub/en/guides/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`](https://hub.docker.com/r/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ırmada önce kurulum yapmak yerine doğrudan üretim başlar. ```bash 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 ` — sandbox donanımı (örneğin, `a10g-small`, `h200`, `rtx-pro-6000`). - `--timeout ` — sandbox içindeki run komutu için maksimum duvar saati (varsayılan `10m`). - `--dependencies ` — ek pip bağımlılıkları (tekrarlanabilir), imajın üzerine kurulur. diffusers dalı tar dosyasını sabitlemek veya pipeline'a özel ekler eklemek için faydalıdır. - `--namespace ` — sandbox'ı farklı bir HF org/hesabı altında oluşturur. - `--image ` — sandbox görüntüsünü geçersiz kılar. `--flavor`'nün sürücüsüyle uyumlu torch + CUDA içermelidir. CLI, her soğuk sandbox'ta kendi bağımlılıklarını üstüne kurar; varsayılan görüntü bunu önler. - `--volume [:]` — bir [HF depolama kovasını](https://huggingface.co/docs/hub/en/storage-buckets) sandbox içine okuma-yazma dizini olarak bağlar (tekrarlanabilir). Varsayılan bağlama yolu `/mnt/buckets/`'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 → sonlandı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 canlı 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 ` — yeni bir tane oluşturmak yerine, açık tutulan bir sandbox'a yeniden bağlanın. - `--idle-timeout ` — 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. ```bash # First run keeps the sandbox alive and prints sandbox_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 # Stop it when done (or let it timeout). hf sandbox kill ``` ## `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. ```bash # 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` > [!CAUTION] > 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çimine fp16 olarak 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. ## `skills` diffusers deposundan becerileri yükleyin ([`.ai/skills/`](https://github.com/huggingface/diffusers/tree/main/.ai/skills)). ```bash # Install a single skill diffusers-cli skills add "" # 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:` olarak adlandırılır). Codex ve Cursor ise `.agents/skills//` alır.