# واجهة سطر الأوامر `diffusers-cli` هو عميل سطر أوامر لتشغيل خطوط أنابيب Diffusers وفحصها وتغليفها. ## الأوامر المتاحة | أمر | الغرض | |---|---| | [`env`](#env) | اطبع معلومات البيئة لتقارير الأخطاء. | | [`schema`](#schema) | افحص توقيع `__call__` لخط الأنابيب دون تنزيل الأوزان. | | [`run`](#run) | شغّل خط أنابيب محليًا أو في بيئة Hugging Face Sandbox. | | [`custom_blocks`](#customblocks) | تغليف فئة فرعية محلية من `ModularPipelineBlocks` للمركز (Hub). | | [`fp16_safetensors`](#fp16safetensors) | تحويل نقطة التفتيش إلى `.safetensors` بصيغة fp16 | | [`skills`](#skills) | قم بتثبيت حزم المهارات الجاهزة في وكيل البرمجة الذكي الخاص بك. | > [!TIP] > لا توفر هذه الصفحة تفاصيل لجميع الخيارات تحت كل أمر فرعي. للحصول على قائمة كاملة ودائمة التحديث بالخيارات لأي أمر فرعي، نفّذ `diffusers-cli --help` (`diffusers-cli run --help`). ## env يطبع إصدارات Python وPyTorch وDiffusers، ومعلومات CUDA، والتبعيات الاختيارية المثبتة. استخدمه عند فتح مشكلة حتى يتمكن المسؤولون عن المشروع من إعادة إنشاء إعدادك. ```bash diffusers-cli env ``` ## مخطط يعيد المدخلات المقبولة في خط الأنابيب دون تنزيل الأوزان. استخدمه عند بناء `--pipeline-kwargs` لـ [`run`](#run). يتم جلب ملف الفهرس فقط. تقرأ خطوط الأنابيب القياسية `model_index.json`. وتقرأ خطوط الأنابيب المعيارية `modular_model_index.json`. وتقرأ المستودعات ذات الكتل المخصصة `modular_config.json` وتحتاج إلى `--trust-remote-code`، لأن تحميلها يشغّل كود Hub. ```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 ``` ## تشغيل شغّل خط أنابيب من البداية إلى النهاية. يكتشف سطر الأوامر تلقائيًا ما إذا كان المستودع قياسي أم معياري. كما يحمّل مدخلات الوسائط تلقائيًا من عناوين URL أو مسارات محلية، ويحفظ المخرجات بناءً على نوع الإرجاع الخاص بخط الأنابيب، ويمكنه التشغيل عن بُعد على Hugging Face Sandbox عبر `--remote`. مثال مبسّط: ```bash 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)`. القيم النصية عند مفاتيح إدخال الوسائط المعروفة تُحمَّل تلقائيًا: - Images (`image`، `last_image`، `mask_image`، `control_image`، `ip_adapter_image`، `image_2`) → `PIL.Image` عبر `load_image`. - Videos (`video`، `control_video`) → `list[PIL.Image]` عبر `load_video`. - Audio (`initial_audio_waveforms`، `reference_audio`، `src_audio`) → `torch.Tensor` عبر `torchaudio.load`. ```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}' ``` تقبل مفاتيح الوسائط ومفاتيح النص على حد سواء مصفوفة JSON لتشغيل دفعة كاملة عبر استدعاء واحد لخط المعالجة. يتم تحميل كل عنصر في قائمة الوسائط بشكل فردي (رابط URL، مسار محلي، أو مسار مُثبّت من الدلو)، بينما يعالج Diffusers القائمة بأكملها في تمريرة أمامية واحدة على وحدة معالجة الرسوميات (GPU): ```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" ] }' ``` ### جارٍ التحميل اضبط كيفية تحميل أوزان النموذج ورمز خط المعالجة المخصص بواسطة واجهة سطر الأوامر. - `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — نوع dtype للأوزان. - `--device-map ` — توزيع المكونات. يقبل سلسلة جهاز torch (`cuda`، `cuda:0`، `cpu`، `mps`)، أو `balanced` (يقسم المكونات تلقائيًا عبر وحدات معالجة الرسوميات المرئية)، أو قاموس JSON لتوزيع المكونات بشكل صريح لكل مكوّن. يتم اكتشافه تلقائيًا إذا تم حذفه. راجع [device_map](../optimization/device_map) لمزيد من التفاصيل. - `--variant fp16` — اختر نسخة الأوزان. - `--revision ` — تثبيت إصدار محدد من النموذج. - `--trust-remote-code` — السماح بالكود المخصص من Hub (مطلوب للمستودعات التي تتضمن فئات خط أنابيب مخصصة أو كتلًا معيارية). راجع [خطوط أنابيب المجتمع](../using-diffusers/custom_pipeline_overview) لخطوط الأنابيب المخصصة القياسية و[Modular Diffusers](../modular_diffusers/overview). - `--lora ` — إرفاق مُكيّف LoRA بعد التحميل. كل قيمة هي قاموس JSON. كرر العلم لتكديس عدة مُكيّفات. `lora_id` مطلوب لكل إدخال، و`lora_scale` افتراضيًا `1.0`، و`adapter_name` اختياري (يُولَّد تلقائيًا على شكل `lora_` عند التكديس). - فردية: `--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](../tutorials/using_peft_for_inference) للحصول على شرح أعمق حول تجميع المُكيِّفات، وجدولة المقياس، والتبديل الفوري. ### التحسينات - `--cpu-offload {model, group, auto}` — مصدر هدف التحميل هو `--device-map` (يتطلب سلسلة جهاز عادية للتفريغ). - `model` — `enable_model_cpu_offload` للأنابيب القياسية. راجع [إزاحة النموذج](../optimization/memory#model-offloading). - `group` — `enable_group_offload(offload_type="leaf_level", use_stream=True)` للأنابيب القياسية. راجع [إخلاء المجموعات](../optimization/memory#group-offloading). - `auto` — يعمل مع الأنماط المعيارية فقط عند استخدام [`ComponentsManager`](../modular_diffusers/components_manager). تثير الأنماط المعيارية استثناءً عند التعامل مع خطوط الأنابيب المعيارية. يثير `auto` استثناءً عند التعامل مع خطوط الأنابيب المعيارية. - `--offload-margin ` — مساحة ذاكرة الجهاز التي تُبقيها فارغة للتفعيلات عند استخدام `--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. راجع [واجهات الانتباه](../optimization/attention_backends). - `--vae-tiling` / `--vae-slicing` — لتقليل ذاكرة VRAM المستخدمة في فك ترميز VAE. راجع [تقسيم VAE](../optimization/memory#vae-tiling) و [تقطيع VAE](../optimization/memory#vae-slicing). - `--compile [JSON]` — تجميع وحدات مُزيل الضوضاء باستخدام [torch.compile](../optimization/fp16#torchcompile). تفضّل واجهة سطر الأوامر [التجميع الإقليمي](../optimization/fp16#regional-compilation) للوحدات التي تحتوي على كتل متكررة. استخدام `--compile` بمفرده يعتمد `fullgraph=true`. يُمرَّر كائن JSON إلى `torch.compile`. غير مدعوم مع `--context-parallel`. - `--context-parallel` — توازٍ سياقي بنمط Ulysses على خط أنابيب يعتمد على DiT. يتطلب محليًا استخدام torchrun، لكن عند استخدام `--remote` يقوم سطر الأوامر بتغليف `torchrun --nproc-per-node=gpu` نيابةً عنك. راجع [التوازي السياقي](../optimization/context_parallelism). ### خطوط أنابيب معيارية يكتشف `run` [مستودعًا معياريًا](../modular_diffusers/overview) تلقائيًا — إما لأنه يتضمن ملف `modular_model_index.json`، أو لأن ملف `model_index.json` الخاص به يشير إلى فئة فرعية من `ModularPipeline` — لذا لا حاجة إلى أي علم (flag) للانضمام. تعرف بعض المستودعات المعيارية عدة *مسارات عمل* تشبه المهام المسماة، حيث تتشارك في المكونات لكنها تختلف في الكتل التي تُنفَّذ والمدخلات التي تتلقاها. على سبيل المثال، يوفر [MiniMax-H3](../api/pipelines/minimax_h3) مسارات `t2va` (من نص إلى فيديو وصوت)، و`fl2va` (إطار مفتاحي أول و/أو أخير)، و`ref2va` (مزيج مرتب من مراجع الصور والفيديو والصوت). مرر `--workflow` لاختيار أحدها: ```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 ``` يؤدي اختيار سير عمل إلى الاحتفاظ بمكونات ذلك المهام فقط، بحيث تعلن خط الأنابيب عن المكونات التي تحتاجها فقط، ويجلب `load_components` مجلداتها الفرعية فقط. احذف `--workflow` للاحتفاظ بجميع سلاسل العمل المتاحة ودع خط الأنابيب يختار لكل استدعاء من المدخلات المقدمة إليه. ```bash diffusers-cli --format json schema --model MiniMaxAI/MiniMax-H3 --trust-remote-code ``` `--workflow` ينطبق على خطوط الأنابيب المعيارية فقط. يتم تجاهله مع تحذير في خطوط الأنابيب القياسية. يعيد خط أنابيب معياري كائن [`PipelineState`](../modular_diffusers/modular_pipeline) بدلاً من كائن مخرجات واحد، لذا يحدد `--output-key` اسم العنصر الوسيط الذي يجب حفظه. ### المخرجات `run` يكتشف نوع مخرجات خط الأنابيب: - `PIL.Image`/list → `.png` (مؤشر مُكمّل بالأصفار، مثل `0000.png`) - تسلسل الصور → `0000.mp4` (يتحكم `--fps` في معدل الإطارات، الافتراضي 8) - مصفوفة الصوت → `0000.wav` (يتحكم `--sampling-rate` في المعدل) - أي شيء آخر → إخراج JSON تنسيق مخرج الدليل الافتراضي هو `~/.diffusers/cli/run/outputs/diffusers-run--/`. يحصل كل تشغيل على دليل فرعي خاص به حتى لا تتجاوز الاستدعاءات المتتالية بعضها بعضًا. يمكنك تجاوز ذلك باستخدام `--output `. يعتمد توسيع المسار على شكله وحجم الدفعة: | `--output` | 1 مخرجات | N مخرجات | |---|---|---| | _مُستثنى_ | المجلد الافتراضي → `0000.png` | المجلد الافتراضي → `0000.png`، `0001.png`، `0002.png`، … | | `./results/` (بعلامة `/` في النهاية أو دليل موجود مسبقًا) | `./results/0000.png` | `./results/0000.png`, `./results/0001.png`, … | | `my-cat.png` (مسار الملف) | `my-cat.png` (يُستخدم كما هو) | `my-cat-0000.png`, `my-cat-0001.png`, … | تستخدم مخرجات المجلد دائمًا أسماءً مبطّنةً عارية (`0000`، `0001`، …). أما مسارات الملفات الصريحة فتحتفظ بالجذر الذي اخترته، ويُضاف إليه الفهرس المبطّن عندما ينتج عن الدفعة عدة مخرجات. استخدم `--push-to` لرفع المخرجات إلى [حاوية تخزين Hugging Face](https://huggingface.co/docs/hub/en/storage-buckets). يقبل: - معرّف دلو HF (`/`) - `hf://buckets//[/]` [URI الخاص بـ HF](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris) - عنوان المتصفح يُستخدم المسار الفرعي كبادئة للمجلد. يتم إنشاء الدلو إذا لم يكن موجودًا، وتُحفظ الكائنات تحت `[/]/`. ```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 ``` تصف الجدول أدناه عمليات التشغيل عن بُعد. أما في عمليات التشغيل المحلية، فإن `--push-to` يرفع المخرجات المحفوظة محليًا. ولا يمنع إنشاء الملفات محليًا. | هل تم تعيين `--push-to`؟ | هل تم تعيين `--output`؟ | النتيجة | |---|---|---| | لا | لا | تنزيل إلى المجلد المحلي الافتراضي | | لا | نعم | تنزيل إلى `--output` | | نعم | لا | دلو فقط، بدون تنزيل محلي | | نعم | نعم | bucket و `--output` | `--format` يحدد شكل بيانات الوصف في الإخراج القياسي (المسارات، التوقيت، معلومات بيئة العزل). لا يغيّر هذا الخيار صيغة الملف الخاصة بالوسائط نفسها. الصور المكتوبة تكون دائمًا بصيغة PNG، والفيديوهات بصيغة MP4، والصوت بصيغة WAV. ### التنفيذ عن بُعد (`--remote`) نفّذ نفس الاستدعاء داخل [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) — وهو جهاز افتراضي سحابي معزول تتحكم فيه أداة CLI عبر HTTP: يقوم برفع المدخلات، وتنفيذ خط المعالجة، وتنزيل المخرجات، ثم إنهاء بيئة العزل. يتطلب `huggingface_hub>=1.23`. تُشغَّل بيئة العزل من [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda)، وهو صورة جاهزة مسبقاً تتضمن بالفعل torch وCUDA والتبعيات الخاصة بأداة سطر الأوامر، مما يعني أن التشغيل البارد يبدأ في التوليد مباشرة بدلاً من التثبيت أولاً. ```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 ``` أعلام عن بُعد: - `--flavor ` — عتاد بيئة العزل (على سبيل المثال، `a10g-small`، `h200`، `rtx-pro-6000`). - `--timeout ` — الحد الأقصى للوقت الفعلي لأمر التشغيل داخل بيئة العزل (الافتراضي `10m`). - `--dependencies ` — تبعيات pip إضافية (قابلة للتكرار)، تُثبَّت فوق الصورة. مفيدة لتثبيت أرشيف فرع diffusers أو إضافة إضافات خاصة بخط أنابيب معين. - `--namespace ` — إنشاء بيئة العزل تحت منظمة/حساب HF مختلف. - `--image ` — تجاوز صورة بيئة العزل. يجب أن تتضمن `--flavor` متوافقًا مع محرك التشغيل الخاص بك. ثم يقوم سطر الأوامر بتثبيت تبعياته الخاصة فوق ذلك في كل بيئة عزل باردة، وهو ما تتجنبه الصورة الافتراضية. - `--volume [:]` — يُثبّت [حاوية تخزين HF](https://huggingface.co/docs/hub/en/storage-buckets) داخل بيئة العزل كمجلد قابل للقراءة والكتابة (يمكن تكراره). مسار التثبيت الافتراضي هو `/mnt/buckets/`. يمكن الإشارة إلى الملفات المثبتة من `--pipeline-kwargs` كما لو كانت مسارات محلية أخرى. يُطبَّق هذا الخيار فقط عند إنشاء بيئة عزل جديدة ويُتجاهل عند إعادة الاتصال عبر `--sandbox-id`. بشكل افتراضي، كل تشغيل لـ `--remote` مؤقت (إنشاء ← تشغيل ← تنزيل ← إنهاء). لإعادة استخدام بيئة اختبار دافئة عبر عمليات التشغيل — مع الإبقاء على التبعيات، وكاش أوزان النموذج، وكاش `torch.compile` على قرصها — أبقِها نشطة وأعد الاتصال بها: - `--keep-alive` — لا تُنهِ بيئة العزل بعد انتهاء التشغيل. يتم طباعته معرّفها. - `--sandbox-id ` — إعادة الاتصال ببيئة رملية محفوظة بدلاً من إنشاء بيئة جديدة. - `--idle-timeout ` — إيقاف تلقائي بعد هذه المدة من عدم النشاط (الافتراضي `10m`). يُطبَّق فقط عند إنشاء صندوق رمل جديد ويُتجاهل عند إعادة الاتصال عبر `--sandbox-id`. ```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` حزّم فئة فرعية محلية من `ModularPipelineBlocks` للرفع إلى Hub. يقرأ ملف Python، ويفحصه باستخدام AST بحثًا عن فئات مشتقة من `ModularPipelineBlocks` أو إحدى فئاتها الفرعية المركبة (`SequentialPipelineBlocks`، `AutoPipelineBlocks`، `ConditionalPipelineBlocks`، `LoopSequentialPipelineBlocks`)، ثم يُنشئ الكائن المختار، ويستدعي `save_pretrained` في المجلد الحالي. ```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 ``` يجب أن يكون من الممكن إنشاء كائن من فئة الكتلة دون أي معاملات في مُنشئها، مع ترميز القيم الافتراضية بشكل ثابت في `__init__` أو قراءة الإعدادات من `state` الخاص بالخط الأنابيب عند وقت الاستدعاء. ## `fp16_safetensors` > [!CAUTION] > أصبح هذا الأمر غير مدعوم وسيتم إزالته في إصدار مستقبلي. تحويل نقطة تحقق على Hub إلى `.safetensors` بصيغة fp16 ودفع النتيجة. مفيد لتقليل حجم أوزان المستودع لتحميل أسرع. راجع `diffusers-cli fp16_safetensors --help` لمعرفة المعاملات الدقيقة. ## `skills` قم بتثبيت المهارات من مستودع diffusers ([`.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 ``` بدون علم الهدف، يثبّت سطر الأوامر (CLI) للوك الذي أطلقه، أو لكل الوكلاء عندما لا يستطيع التمييز. يحصل Claude Code على حزمة إضافات تحت `.claude/skills/diffusers/` (بمساحة أسماء `/diffusers:`). يحصل Codex وCursor على `.agents/skills//`.