واجهة سطر الأوامر

diffusers-cli هو عميل سطر أوامر لتشغيل خطوط أنابيب Diffusers وفحصها وتغليفها.

الأوامر المتاحة

لا توفر هذه الصفحة تفاصيل لجميع الخيارات تحت كل أمر فرعي. للحصول على قائمة كاملة ودائمة التحديث بالخيارات لأي أمر فرعي، نفّذ diffusers-cli <command> --help (diffusers-cli run --help).

env

يطبع إصدارات Python وPyTorch وDiffusers، ومعلومات CUDA، والتبعيات الاختيارية المثبتة. استخدمه عند فتح مشكلة حتى يتمكن المسؤولون عن المشروع من إعادة إنشاء إعدادك.

diffusers-cli env

مخطط

يعيد المدخلات المقبولة في خط الأنابيب دون تنزيل الأوزان. استخدمه عند بناء --pipeline-kwargs لـ run.

يتم جلب ملف الفهرس فقط. تقرأ خطوط الأنابيب القياسية model_index.json. وتقرأ خطوط الأنابيب المعيارية modular_model_index.json. وتقرأ المستودعات ذات الكتل المخصصة modular_config.json وتحتاج إلى --trust-remote-code، لأن تحميلها يشغّل كود Hub.

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

تشغيل

شغّل خط أنابيب من البداية إلى النهاية. يكتشف سطر الأوامر تلقائيًا ما إذا كان المستودع قياسي أم معياري. كما يحمّل مدخلات الوسائط تلقائيًا من عناوين URL أو مسارات محلية، ويحفظ المخرجات بناءً على نوع الإرجاع الخاص بخط الأنابيب، ويمكنه التشغيل عن بُعد على Hugging Face Sandbox عبر --remote.

مثال مبسّط:

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

تمرير حِجج خط الأنابيب

--pipeline-kwargs يتلقى كائن JSON يُمرَّر إلى pipeline(**kwargs). القيم النصية عند مفاتيح إدخال الوسائط المعروفة تُحمَّل تلقائيًا:

• الصور (image، last_image، mask_image، control_image، ip_adapter_image، image_2) → PIL.Image عبر load_image.
• الفيديوهات (video، control_video) → list[PIL.Image] عبر load_video.
• الصوت (initial_audio_waveforms، reference_audio، src_audio) → torch.Tensor عبر torchaudio.load.

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}'

تقبل مفاتيح الوسائط ومفاتيح النص على حد سواء مصفوفة JSON لتشغيل دفعة كاملة عبر استدعاء واحد لخط المعالجة. يتم تحميل كل عنصر في قائمة الوسائط بشكل فردي (رابط URL، مسار محلي، أو مسار موصول بوعاء التخزين)، بينما يعالج Diffusers القائمة بأكملها في تمريرة أمامية واحدة على وحدة معالجة الرسوميات (GPU):

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"
        ]
    }'

جارٍ التحميل

اضبط كيفية تحميل أوزان النموذج ورمز خط المعالجة المخصص بواسطة واجهة سطر الأوامر.

• --dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32} — نوع dtype للأوزان.

• --device-map <value> — توزيع المكونات. يقبل سلسلة جهاز torch (cuda، cuda:0، cpu، mps)، أو balanced (يقسم المكونات تلقائيًا عبر وحدات معالجة الرسوميات المرئية)، أو قاموس JSON لتوزيع المكونات بشكل صريح لكل مكوّن. يتم اكتشافه تلقائيًا إذا تم حذفه. راجع device_map لمزيد من التفاصيل.

• --variant fp16 — اختر نسخة الأوزان.

• --revision <sha> — تثبيت إصدار محدد من النموذج.

• --trust-remote-code — السماح بالكود المخصص من Hub (مطلوب للمستودعات التي تتضمن فئات pipeline مخصصة أو كتل modulare). راجع خطوط أنابيب المجتمع لخطوط الأنابيب المخصصة القياسية وModular Diffusers.

• --lora <spec> — إرفاق مُكيّف LoRA بعد التحميل. كل قيمة هي قاموس JSON. كرر العلم لتكديس عدة مُكيّفات. lora_id مطلوب لكل إدخال، وlora_scale افتراضيًا 1.0، وadapter_name اختياري (يُولَّد تلقائيًا على شكل lora_<i> عند التكديس).

  • فردية: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'
  • متعددة: --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}'

  تُحمَّل جميع المواصفات بواسطة pipeline.load_lora_weights(...)، ثم تُفعَّل معًا عبر استدعاء واحد لـ pipeline.set_adapters(names, adapter_weights=scales). راجع LoRA للحصول على شرح أعمق حول تجميع المُكيِّفات، وجدولة المقياس، والتبديل الفوري.

التحسينات

• --cpu-offload {model, group, auto} — يأتي هدف التحميل من --device-map (سلسلة جهاز عادية مطلوبة للترحيل). model — تفعيل enable_model_cpu_offload للأنابيب القياسية. راجع ترحيل النموذج. group — تفعيل enable_group_offload(offload_type="leaf_level", use_stream=True) للأنابيب القياسية. راجع ترحيل المجموعة. auto — خاص بالأنابيب المودولية مع ComponentsManager فقط. تثير الأوضاع القياسية استثناءً في الأنابيب المودولية، وتثير auto استثناءً في الأنابيب القياسية.
  • model — enable_model_cpu_offload للأنابيب القياسية. راجع إزاحة النموذج.
  • group — enable_group_offload(offload_type="leaf_level", use_stream=True) للأنابيب القياسية. راجع إخلاء المجموعات.
  • auto — يعمل مع الأنماط المعيارية فقط عند استخدام ComponentsManager. تثير الأنماط المعيارية استثناءً عند التعامل مع خطوط الأنابيب المعيارية. يثير auto استثناءً عند التعامل مع خطوط الأنابيب المعيارية.
• --offload-margin <size> — مساحة ذاكرة الجهاز التي تُبقيها فارغة للتفعيلات عند استخدام --cpu-offload auto، وتُمرَّر إلى enable_auto_cpu_offload باسم memory_reserve_margin (الافتراضي 3GB). ارفع هذه القيمة عندما تنفد ذاكرة بطاقة كبيرة أثناء تنفيذ الأمامي. يحتفظ المُحمِّل بالمكونات مقيمة طالما كانت تتسع، لذا على بطاقة ذاكرة عالية السعة قد تترك الهامش الافتراضي مساحة غير كافية لتفعيلات فيديو طويل.
• --attention-backend — نواة انتباه مستضافة على Hub، يتم تنزيلها تلقائيًا عند الاستخدام الأول. الخيارات هي default بالإضافة إلى واجهات Hub المسجلة في Diffusers (مثل flash_hub، flash_varlen_hub، flash_4_hub، sage_hub، sage_blackwell_hub). شغّل diffusers-cli run --help للحصول على القائمة الحالية. يدعم خطوط الأنابيب المبنية على Transformer فقط، ويتم تجاهله مع تحذير في خطوط الأنابيب القديمة UNet. راجع واجهات الانتباه.
• --vae-tiling / --vae-slicing — لتقليل ذاكرة VRAM المستخدمة في فك ترميز VAE. راجع تقسيم VAE و تقطيع VAE.
• --compile [JSON] — تجميع وحدات مُزيل الضوضاء باستخدام torch.compile. تفضّل واجهة سطر الأوامر التجميع الإقليمي للوحدات التي تحتوي على كتل متكررة. استخدام --compile بمفرده يعتمد fullgraph=true. يُمرَّر كائن JSON إلى torch.compile. غير مدعوم مع --context-parallel.
• --context-parallel — توازٍ سياقي بنمط Ulysses على خط أنابيب يعتمد على DiT. يتطلب محليًا استخدام torchrun، لكن عند استخدام --remote يقوم سطر الأوامر بتغليف torchrun --nproc-per-node=gpu نيابةً عنك. راجع التوازي السياقي.

خطوط أنابيب معيارية

يكتشف run مستودعًا معياريًا تلقائيًا — إما لأنه يتضمن modular_model_index.json، أو لأن model_index.json الخاص به يحدد فئة فرعية من ModularPipeline — لذا لا حاجة إلى أي علم (flag) للانضمام.

تعرف بعض المستودعات المعيارية على عدة مسارات عمل تشبه المهام المسماة، حيث تتشارك في المكونات لكنها تختلف في الكتل التي تُنفَّذ والمدخلات التي تتلقاها. على سبيل المثال، يوفر MiniMax-H3 مسارات t2va (من نص إلى فيديو وصوت)، وfl2va (إطار مفتاحي أول و/أو أخير)، وref2va (مزيج مرتب من مراجع الصور والفيديو والصوت). مرر --workflow لاختيار أحدها:

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

يؤدي اختيار سير عمل إلى الاحتفاظ بمكاتب المهمة المعنية فقط، بحيث تعلن خط الأنابيب عن المكونات التي تحتاجها فقط، ويجلب load_components مجلداتها الفرعية فقط. احذف --workflow للاحتفاظ بجميع سلاسل العمل المتاحة ودع خط الأنابيب يختار لكل استدعاء من المدخلات المقدمة إليه.

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

--workflow ينطبق على خطوط الأنابيب المعيارية فقط. يتم تجاهله مع تحذير في خطوط الأنابيب القياسية.

يعيد خط أنابيب معياري كائن PipelineState بدلاً من كائن مخرجات واحد، لذا يحدد --output-key اسم العنصر الوسيط الذي يجب حفظه.

المخرجات

run يكتشف نوع مخرجات خط الأنابيب:

• PIL.Image/list → <NNNN>.png (مؤشر مُكمّل بالأصفار، مثل 0000.png)
• تسلسل الصور → 0000.mp4 (يتحكم --fps في معدل الإطارات، الافتراضي 8)
• مصفوفة الصوت → 0000.wav (يتحكم --sampling-rate في المعدل)
• أي شيء آخر → إخراج JSON

تنسيق مخرج الدليل الافتراضي هو ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/. يحصل كل تشغيل على دليل فرعي خاص به حتى لا تتجاوز الاستدعاءات المتتالية بعضها بعضًا.

يمكنك تجاوز ذلك باستخدام --output <path>. يعتمد توسيع المسار على شكله وحجم الدفعة:

تستخدم مخرجات المجلد دائمًا أسماءً مبطّنة عارية (0000، 0001، …). أما مسارات الملفات الصريحة فتحتفظ بالجذر الذي اخترته، ويُضاف إليه الفهرس المبطّن عندما ينتج عن الدفعة عدة مخرجات.

استخدم --push-to لرفع المخرجات إلى حاوية تخزين Hugging Face. يقبل:

• معرّف دلو HF (<namespace>/<name>)
• hf://buckets/<namespace>/<name>[/<subpath>] URI الخاص بـ HF
• عنوان المتصفح

يُستخدم المسار الفرعي كبادئة للمجلد. يتم إنشاء الدلو إذا لم يكن موجودًا، وتُحفظ الكائنات تحت [<subpath>/]<run_id>/<filename>.

# 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

تصف الجدول أدناه عمليات التشغيل عن بُعد. أما في عمليات التشغيل المحلية، فإن --push-to يرفع المخرجات المحفوظة محليًا. ولا يمنع إنشاء الملفات محليًا.

--format يحدد شكل بيانات الوصف في الإخراج القياسي (المسارات، التوقيت، معلومات بيئة العزل). لا يغيّر هذا الخيار صيغة الملف الخاصة بالوسائط نفسها. الصور المكتوبة تكون دائمًا بصيغة PNG، والفيديوهات بصيغة MP4، والصوت بصيغة WAV.

التنفيذ عن بُعد ( --remote )

نفّذ نفس الاستدعاء داخل Hugging Face Sandbox — وهو جهاز افتراضي سحابي معزول تتحكم فيه أداة CLI عبر HTTP: يقوم برفع المدخلات، وتنفيذ خط المعالجة، وتنزيل المخرجات، ثم إنهاء بيئة العزل. يتطلب huggingface_hub>=1.23.

تُشغَّل بيئة العزل من diffusers/diffusers-cli-cuda، وهو صورة جاهزة مسبقاً تتضمن بالفعل torch وCUDA والتبعيات الخاصة بأداة سطر الأوامر، مما يعني أن التشغيل البارد يبدأ في التوليد مباشرة بدلاً من التثبيت أولاً.

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

أعلام عن بُعد:

• --flavor <name> — عتاد بيئة العزل (على سبيل المثال، a10g-small، h200، rtx-pro-6000).
• --timeout <duration> — الحد الأقصى للوقت الفعلي لأمر التشغيل داخل بيئة العزل (الافتراضي 10m).
• --dependencies <pkg> — تبعيات pip إضافية (قابلة للتكرار)، تُثبَّت فوق الصورة. مفيدة لتثبيت فرع tarball لـ diffusers أو لإضافة إضافات خاصة بخط أنابيب معين.
• --namespace <name> — إنشاء بيئة العزل تحت منظمة/حساب HF مختلف.
• --image <ref> — تجاوز صورة بيئة العزل. يجب أن تتضمن --flavor المتوافق مع محرك التشغيل الخاص بك. ثم يقوم سطر الأوامر بتثبيت تبعياته الخاصة فوقها في كل بيئة عزل باردة، وهو ما تتجنبه الصورة الافتراضية.
• --volume <bucket-id>[:<mount-path>] — يُثبّت حاوية تخزين HF داخل بيئة العزل كمجلد قابل للقراءة والكتابة (يمكن تكراره). مسار التثبيت الافتراضي هو /mnt/buckets/<bucket-id>. يمكن الإشارة إلى الملفات المثبتة من --pipeline-kwargs كما لو كانت مسارات محلية أخرى. يُطبَّق هذا الخيار فقط عند إنشاء بيئة عزل جديدة ويُتجاهل عند إعادة الاتصال عبر --sandbox-id.

بشكل افتراضي، كل تشغيل لـ --remote مؤقت (إنشاء ← تشغيل ← تنزيل ← إنهاء). لإعادة استخدام بيئة اختبار دافئة عبر التشغيلات — مع الحفاظ على التبعيات، وكاش أوزان النموذج، وكاش torch.compile على قرصها — أبقِها نشطة وأعد الاتصال بها:

• --keep-alive — لا تُنهِ بيئة العزل بعد انتهاء التشغيل. يتم طباعته معرّفها.
• --sandbox-id <id> — إعادة الاتصال ببيئة رملية محفوظة بدلاً من إنشاء بيئة جديدة.
• --idle-timeout <duration> — إيقاف تلقائي بعد هذه المدة من عدم النشاط (الافتراضي 10m). يُطبَّق فقط عند إنشاء صندوق رمل جديد ويُتجاهل عند إعادة الاتصال عبر --sandbox-id.

# 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

تغليف فئة فرعية محلية من ModularPipelineBlocks للرفع إلى Hub. يقرأ ملف Python، ويفحصه باستخدام AST بحثاً عن فئات مشتقة من ModularPipelineBlocks أو إحدى فئاتها الفرعية المركبة (SequentialPipelineBlocks، AutoPipelineBlocks، ConditionalPipelineBlocks، LoopSequentialPipelineBlocks)، ثم يولّد مثيلاً للفئة المختارة، ويستدعي save_pretrained في مجلد العمل الحالي.

# 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

يجب أن يكون من الممكن إنشاء كائن من فئة الكتلة دون أي معاملات في مُنشئها، مع ترميز القيم الافتراضية بشكل ثابت في __init__ أو قراءة الإعدادات من state الخاص بالخط الأنابيب عند وقت الاستدعاء.

fp16_safetensors

أصبح هذا الأمر غير مدعوم وسيتم إزالته في إصدار مستقبلي.

تحويل نقطة تفتيش على Hub إلى .safetensors بصيغة fp16 ودفع النتيجة. مفيد لتقليل حجم الأوزان في المستودع لتحميل أسرع. راجع diffusers-cli fp16_safetensors --help لمعرفة الحجة الدقيقة.

المهارات

قم بتثبيت المهارات من مستودع diffusers (.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

بدون علم الهدف، يثبّت سطر الأوامر (CLI) للوك الذي أطلقه، أو لكل الوكلاء عندما لا يستطيع التمييز. يحصل Claude Code على حزمة إضافات تحت .claude/skills/diffusers/ (بمساحة أسماء /diffusers:<skill name>). يحصل Codex وCursor على .agents/skills/<skill name>/.