Hub Python Library documentation

واجهة سطر الأوامر (CLI)

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

واجهة سطر الأوامر (CLI)

يأتي حزمة huggingface_hub بلغة بايثون مع سطر أوامر مدمج يُسمى hf. يتيح لك هذا الأداة التفاعل مع Hugging Face Hub مباشرةً من الطرفية. على سبيل المثال، يمكنك تسجيل الدخول إلى حسابك، وإنشاء مستودع، ورفع الملفات وتنزيلها، وما إلى ذلك. كما يأتي بميزات عملية لضبط إعدادات جهازك أو إدارة ذاكرته المؤقتة. في هذا الدليل، سنلقي نظرة على الميزات الرئيسية لسطر الأوامر وكيفية استخدامها.

يتناول هذا الدليل أهم ميزات واجهة سطر الأوامر hf. للاطلاع على مرجع كامل لجميع الأوامر والخيارات، راجع مرجع واجهة سطر الأوامر.

هل تستخدم hf CLI مع وكلاء الذكاء الاصطناعي؟ ثبّت المهارة واستعرض دليل Hugging Face CLI for AI Agents.
# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add
يقوم المثبّت المستقل بتثبيته نيابةً عنك (انظر أدناه)، ويحدّثه الأمر hf update.

البدء

مثبّت مستقل (موصى به)

يمكنك تثبيت واجهة hf السطرية بأمر واحد:

على macOS و Linux:

>>> curl -LsSf https://hf.co/cli/install.sh | bash

على نظام ويندوز:

>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

يقوم المثبّت أيضاً بتثبيت مهارة hf-cli على مستوى النظام، لـ Claude Code وأي وكيل يقرأ من ~/.agents/skills. مرّر --exclude-skill لتخطيها:

>>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill

>>> powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"

بعد التثبيت، يمكنك التحقق من أن سطر الأوامر مُعدّ بشكل صحيح:

>>> hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:
  --skills              Print the `hf-cli` SKILL.md to stdout (alias for `hf skills preview`).
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  -h, --help            Show this message and exit.

Main commands:
  auth                 Manage authentication (login, logout, etc.).
  buckets              Commands to interact with buckets.
  cache                Manage local cache directory.
  collections          Interact with collections on the Hub.
  datasets             Interact with datasets on the Hub.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  extensions           Manage hf CLI extensions.
  jobs                 Run and manage Jobs on the Hub.
  models               Interact with models on the Hub.
  papers               Interact with papers on the Hub.
  repos                Manage repos on the Hub.
  skills               Manage skills for AI assistants.
  spaces               Interact with spaces on the Hub.
  sync                 Sync files between local directory and a bucket.
  upload               Upload a file or a folder to the Hub.

Help commands:
  env      Print information about the environment.
  version  Print information about the hf version.

إذا تم تثبيت واجهة سطر الأوامر بشكل صحيح، فيجب أن ترى قائمة بجميع الخيارات المتاحة في واجهة سطر الأوامر. إذا ظهر لك رسالة خطأ مثل command not found: hf، فيرجى الرجوع إلى دليل التثبيت.

يُعدّ الخيار --help مريحًا جدًا للحصول على مزيد من التفاصيل حول أمر ما. يمكنك استخدامه في أي وقت لعرض جميع الخيارات المتاحة وتفاصيلها. على سبيل المثال، يوفر hf upload --help معلومات إضافية حول كيفية رفع الملفات باستخدام سطر الأوامر.

استخدام uv

أسهل طريقة لاستخدام سطر أوامر hf هي من خلال uvx. فهو يشغّل دائمًا أحدث إصدار في بيئة معزولة - دون الحاجة إلى أي تثبيت!

تأكد أولاً من تثبيت uv. راجع دليل تثبيت uv للحصول على التعليمات.

ثم استخدم سطر الأوامر مباشرةً:

>>> uvx hf auth login
>>> uvx hf download
>>> uvx hf ...

uvx hf يستخدم حزمة hf على PyPI.

التثبيت باستخدام pip

يُشحن سطر الأوامر أيضًا مع الحزمة الأساسية huggingface_hub:

>>> pip install -U "huggingface_hub"

باستخدام Homebrew

يمكنك أيضًا تثبيت CLI باستخدام Homebrew:

>>> brew install hf

اطّلع على صفحة Homebrew الخاصة بـ huggingface هنا لمزيد من التفاصيل.

التحديث

لترقية إلى أحدث إصدار، قم بتشغيل:

>>> hf update

يكتشف هذا الأمر كيفية تثبيت hf (عبر Homebrew، أو المثبّت المستقل، أو pip) وينفّذ أمر التحديث المطابق. إذا كان مهارة hf-cli مثبّتة على مستوى النظام، فسيتم تحديثها أيضاً حتى ترى الوكلاء واجهة الأوامر الجديدة. أما إذا لم تكن مثبّتة، فتبقى غير مثبّتة: فالتحديث لا يعيدها أبداً إذا كنت قد تجاوزتها أو أزلتها.

بشكل افتراضي، يطبع سطر الأوامر أيضًا تحذيرًا أحادي السطر باللون الأصفر إلى stderr عند توفر إصدار أحدث على PyPI. لكتمه (مثلًا في CI دون اتصال)، اضبط HF_HUB_DISABLE_UPDATE_CHECK=1.

تنسيق المخرجات

تقبل معظم أوامر hf نفس مجموعة أعلام التنسيق العامة. وهي موثقة في قسم Formatting options مخصص في كل صفحة --help، ويمكن إضافتها إلى أي أمر دون الحاجة إلى إعلانه لكل أمر على حدة:

علم	المكافئ	الوصف
`--format <value>`	—	حدد صيغة المخرجات بشكل صريح. القيم المقبولة: `auto` (الافتراضي)، `human`، `agent`، `json`، `quiet`.
`--json`	`--format json`	اطبع JSON منظم. مفيد للتوصيل إلى `jq` أو سكربتات أخرى.
`-q`, `--quiet`	`--format quiet`	اطبع المعرّفات فقط (واحد في كل سطر). مفيد لتوجيه المعرّفات إلى أوامر أخرى.
`--no-truncate`	—	اعرض القيم الكاملة في الجداول البشرية بدلاً من اختصار القيم الطويلة باستخدام `...`. قد يتجاوز الجدول عرض الطرفية. استخدم `--format json` للحصول على مخرجات منظمة لأعمدة القوائم/التشكيلات.

auto (الافتراضي) يختار human لواجهة طرفية تفاعلية وagent عندما يُستدعى سطر الأوامر بواسطة وكيل ذكاء اصطناعي. يضيف human الألوان والجداول المنسّقة؛ بينما يُنتج agent قيمًا مفصولة بتبويب دون أي اقتطاع؛ ويُصدر json كائنًا أو مصفوفة JSON مدمجة. يؤدي دمج علامتي وضع إخراج (مثل --json مع --format table) إلى رفع خطأ في الاستخدام.

تتكيّف الجداول البشرية تلقائيًا مع عرض الطرفية: يتم تقصير الأعمدة الأوسع فقط عندما تتجاوز العرض الطبيعي الشاشة (لذا على طرفية واسعة ترى عادةً القيم الكاملة دون ...). مرّر --no-truncate لفرض عرض القيم الكاملة بغض النظر عن العرض؛ واستخدم --format json للحصول على مخرجات منظمة لأعمدة القوائم/التشكيلات.

# JSON output for scripting
>>> hf models ls --search bert --limit 2 --json | jq '.[].id'

# IDs only, one per line
>>> hf collections ls --owner nvidia -q
nvidia/nemotron-supervised-fine-tuning-69eab9824c9120a3a3b1e25e
nvidia/nvidia-nemotron-v3-69388dda16167bb1607171ea

hf auth login

في كثير من الحالات، يجب تسجيل الدخول إلى حساب Hugging Face للتفاعل مع Hub (تنزيل المستودعات الخاصة، رفع الملفات، إنشاء طلبات الدمج، إلخ). للقيام بذلك، نفّذ الأمر التالي في الطرفية:

>>> hf auth login

إذا كنت مسجّل الدخول بالفعل، فسيُغفل هذا الأمر عن طلب الإدخال ويعرض رسالة. لفرض تسجيل الدخول من جديد (مثلًا لتبديل الرموز)، استخدم --force:

>>> hf auth login --force

بشكل افتراضي، يسجّل الأمر دخولك عبر متصفحك: حيث يطبع رابطاً (URL) ورمزاً قصيراً. افتح الرابط، وأدخل الرمز، ووافق على الطلب، ثم يسترد خط الأوامر (CLI) رمز الوصول ويحفظه على جهازك. ينتهي صلاحية الرمز بعد فترة، لكنه يُحدَّث تلقائياً ما دمت تستمر في استخدامه.

? How would you like to log in?  [Use arrows, Enter to confirm]
> Log in with your browser
  Paste an access token

    Open this URL in your browser:
        https://huggingface.co/oauth/device

    And enter the code: ABCD-EFGH

    Waiting for authorization...
Token is valid.
The token `oauth-wauplin` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful.

يمكنك أيضًا اختيار لصق رمز وصول المستخدم الذي تم إنشاؤه من صفحة الإعدادات الخاصة بك، إما تفاعليًا (باختيار لصق رمز وصول) أو مباشرةً من سطر الأوامر. ولزيادة الأمان، ننصح بتمرير رمزك كمتغير بيئة لتجنب لصقه في سجل أوامرك.

# Or using an environment variable
>>> hf auth login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`

عند التشغيل بواسطة وكيل ذكاء اصطناعي (يتم اكتشافه تلقائيًا، أو باستخدام --format agent)، لا يطلب الأمر أي إدخال أبدًا: فهو ينفذ تدفق المتصفح ويُخرج تعليمات نصية بسيطة يمكن للوكيل تمريرها إلى مستخدمه، ثم ينتظر الترخيص:

>>> hf auth login --format agent
Ask the user to open https://huggingface.co/oauth/device in a browser and enter the code ABCD-EFGH. The code expires in 900 seconds. Waiting for authorization...
Login successful: logged in as wauplin (token saved as 'oauth-wauplin').

أمر hf auth login تفاعلي، لذا لا يُدعم --format json أو --format quiet: استخدم --token لتسجيل الدخول عبر السكربتات بشكل غير تفاعلي.

لمزيد من التفاصيل حول المصادقة، راجع هذا القسم.

hf auth whoami

إذا كنت ترغب في معرفة ما إذا كنت مسجلاً الدخول، يمكنك استخدام hf auth whoami. لا يحتوي هذا الأمر على أي خيارات، بل يطبع ببساطة اسم المستخدم الخاص بك والمنظمات التي أنت عضو فيها على Hub:

hf auth whoami
Wauplin
orgs:  huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster

إذا لم تكن مسجلاً الدخول، فسيتم طباعة رسالة خطأ.

hf auth logout

يسجّل هذا الأمر خروجك. عملياً، سيقوم بحذف جميع الرموز (Tokens) المخزّنة على جهازك. إذا كنت ترغب في إزالة رمز محدد، يمكنك تحديد اسم الرمز كحجة.

لن يُسجّل هذا الأمر خروجك إذا كنت مسجّل الدخول باستخدام متغير البيئة HF_TOKEN (انظر المرجع). إذا كان هذا هو الحال، فيجب عليك إلغاء تعيين متغير البيئة في إعدادات جهازك.

hf download

استخدم أمر hf download لتنزيل الملفات من Hub مباشرة. داخليًا، يستخدم نفس أدوات المساعدة hf_hub_download() و snapshot_download() الموصوفة في دليل Download ويخرج المسار المُعاد إلى الطرفية. في الأمثلة أدناه، سنستعرض أكثر حالات الاستخدام شيوعًا. للحصول على قائمة كاملة بالخيارات المتاحة، يمكنك تشغيل:

hf download --help

تنزيل ملف واحد

لتحميل ملف واحد من مستودع، ما عليك سوى تقديم repo_id واسم الملف على النحو التالي:

>>> hf download gpt2 config.json
downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o
(…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

ستطبع الأوامر دائمًا في السطر الأخير مسار الملف على جهازك المحلي.

لتحميل ملف موجود في مجلد فرعي من المستودع، يجب عليك تقديم مسار الملف داخل المستودع بتنسيق posix على النحو التالي:

>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensors

تنزيل مستودع كامل

في بعض الحالات، قد ترغب فقط في تنزيل جميع الملفات من مستودع. يمكن تحقيق ذلك بمجرد تحديد معرف المستودع:

>>> hf download HuggingFaceH4/zephyr-7b-beta
Fetching 23 files:   0%|                                                | 0/23 [00:00<?, ?it/s]
...
...
/home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720

تنزيل ملفات متعددة

يمكنك أيضًا تنزيل مجموعة فرعية من الملفات من مستودع بأمر واحد. يمكن القيام بذلك بطريقتين. إذا كان لديك بالفعل قائمة دقيقة بالملفات التي تريد تنزيلها، يمكنك ببساطة تقديمها تباعًا:

>>> hf download gpt2 config.json model.safetensors
Fetching 2 files:   0%|                                                                        | 0/2 [00:00<?, ?it/s]
downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o
(…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s]
Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00,  3.76it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

النهج الآخر هو تقديم أنماط لتصفية الملفات التي تريد تنزيلها باستخدام --include و--exclude. على سبيل المثال، إذا كنت تريد تنزيل جميع ملفات safetensors من stabilityai/stable-diffusion-xl-base-1.0 باستثناء الملفات بدقة FP16:

>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files:   0%|                                                                         | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7b

تحميل مجموعة بيانات أو مساحة أو نواة

تُظهر الأمثلة أعلاه كيفية التحميل من مستودع نموذج. لتحميل مجموعة بيانات أو مساحة أو نواة، استخدم خيار --repo-type:

# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset

# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space

...

تنزيل إصدار محدد

تُظهر الأمثلة أعلاه كيفية التنزيل من أحدث التزامن على الفرع الرئيسي. لتنزيل من إصدار محدد (تجزئة التزامن، اسم الفرع أو وسم)، استخدم خيار --revision:

>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
...

استخدام معرّف URI بصيغة hf://

بدلاً من تمرير نوع المستودع والمراجعة ومسار الملف كحجج وخيارات منفصلة، يمكنك تقديم hf:// URI واحد. يرمّز URI كل شيء دفعة واحدة، متبعًا القواعد النحوية hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (انظر مرجع HF URIs للحصول على الصياغة الكاملة):

# Equivalent to: hf download bigcode/the-stack --repo-type dataset --revision v1.1
>>> hf download hf://datasets/bigcode/the-stack@v1.1

# Download a single file from a specific revision
>>> hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet

# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/HuggingFaceM4/FineVision/art/

# A bare id still works and defaults to a model repo
>>> hf download hf://openai-community/gpt2/config.json

عند تقديم معرّف موحّد (URI)، لا يمكن تعيين --repo-type و--revision أيضاً لأنهما جزء بالفعل من المعرّف الموحّد (يُستدعى خطأً في حال العكس)، ولا يمكن دمج مسار ملف مضمّن في المعرّف الموحّد مع أسماء الملفات الموضعية. يشير وجود / في نهاية المسار إلى مجلد فرعي (كما هو الحال مع الحجة الموضعية). يجب ترميز أسماء الفروع التي تحتوي على / على شكل %2F (مثلاً hf://my-org/my-model@feature%2Ffoo).

التحميل إلى مجلد محلي

الطريقة الموصى بها (والافتراضية) لتنزيل الملفات من Hub هي استخدام نظام التخزين المؤقت. ومع ذلك، في بعض الحالات قد ترغب في تنزيل الملفات ونقلها إلى مجلد محدد. وهذا مفيد لجعل سير العمل أقرب إلى ما توفره أوامر git. يمكنك القيام بذلك باستخدام خيار --local-dir.

يتم إنشاء مجلد .cache/huggingface/ في جذر مجلدك المحلي يحتوي على بيانات وصفية عن الملفات التي تم تنزيلها. يمنع هذا إعادة تنزيل الملفات إذا كانت محدّثة بالفعل. إذا تغيّرت البيانات الوصفية، يتم تنزيل النسخة الجديدة من الملف. وهذا يجعل local-dir مُحسّنًا لجلب أحدث التغييرات فقط.

لمزيد من التفاصيل حول كيفية عمل التحميل إلى ملف محلي، راجع دليل download.

>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensors

وضع التشغيل التجريبي

في بعض الحالات، قد ترغب في التحقق من الملفات التي سيتم تنزيلها قبل تنزيلها فعليًا. يمكنك التحقق من ذلك باستخدام معامل --dry-run. يقوم هذا المعامل بإدراج جميع الملفات المراد تنزيلها في المستودع والتحقق مما إذا كانت قد تم تنزيلها بالفعل أم لا. وهذا يمنح فكرة عن عدد الملفات التي يجب تنزيلها وأحجامها.

>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00,  6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File                              Bytes to download
--------------------------------- -----------------
.gitattributes                    -
64-8bits.tflite                   125.2M
64-fp16.tflite                    248.3M
64.tflite                         495.8M
README.md                         -
config.json                       -
flax_model.msgpack                497.8M
generation_config.json            -
merges.txt                        -
model.safetensors                 548.1M
onnx/config.json                  -
onnx/decoder_model.onnx           653.7M
onnx/decoder_model_merged.onnx    655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json       -
onnx/merges.txt                   -
onnx/special_tokens_map.json      -
onnx/tokenizer.json               -
onnx/tokenizer_config.json        -
onnx/vocab.json                   -
pytorch_model.bin                 548.1M
rust_model.ot                     702.5M
tf_model.h5                       497.9M
tokenizer.json                    -
tokenizer_config.json             -
vocab.json                        -

لمزيد من التفاصيل، راجع دليل التنزيل.

تحديد مجلد التخزين المؤقت

إذا لم يتم استخدام --local-dir، فسيتم تنزيل جميع الملفات افتراضيًا إلى مجلد التخزين المؤقت المعرّف بمتغير البيئة HF_HOME environment variable. يمكنك تحديد مجلد تخزين مؤقت مخصص باستخدام --cache-dir:

>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745

تحديد رمز

للوصول إلى المستودعات الخاصة أو المحمية، يجب عليك استخدام رمز. بشكل افتراضي، سيتم استخدام الرمز المحفوظ محليًا (باستخدام hf auth login). إذا كنت ترغب في المصادقة بشكل صريح، استخدم خيار --token:

>>> hf download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

وضع الصمت

بشكل افتراضي، يكون أمر hf download مفصّلًا. حيث يطبع تفاصيل مثل رسائل التحذير، ومعلومات حول الملفات التي تم تنزيلها، وأشرطة التقدم. إذا كنت ترغب في كتم جميع هذه المخرجات، فاستخدم خيار --quiet. في هذه الحالة، يُطبع السطر الأخير فقط (أي المسار إلى الملفات التي تم تنزيلها). وقد يكون ذلك مفيدًا إذا كنت ترغب في تمرير المخرجات إلى أمر آخر ضمن سكربت.

>>> hf download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

مهلة انتهاء التحميل

على الأجهزة ذات الاتصالات البطيئة، قد تواجه مشاكل انتهاء المهلة الزمنية مثل هذه:

`httpx2.TimeoutException: (TimeoutException("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`

للتخفيف من هذه المشكلة، يمكنك تعيين متغير البيئة HF_HUB_DOWNLOAD_TIMEOUT إلى قيمة أعلى (القيمة الافتراضية هي 10):

export HF_HUB_DOWNLOAD_TIMEOUT=30

لمزيد من التفاصيل، راجع مرجع متغيرات البيئة. ثم أعد تشغيل أمر التنزيل.

hf upload

استخدم أمر hf upload لرفع الملفات إلى Hub مباشرة. داخليًا، يستخدم نفس أدوات المساعدة upload_file() و upload_folder() الموصوفة في دليل Upload. في الأمثلة أدناه، سنستعرض أكثر حالات الاستخدام شيوعًا. للحصول على قائمة كاملة بالخيارات المتاحة، يمكنك تشغيل:

>>> hf upload --help

رفع مجلد كامل

الاستخدام الافتراضي لهذا الأمر هو:

# Usage:  hf upload [repo_id] [local_path] [path_in_repo]

لرفع المجلد الحالي في جذر المستودع، استخدم:

>>> hf upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/

إذا لم يكن المستودع موجودًا بعد، فسيتم إنشاؤه تلقائيًا.

يمكنك أيضًا رفع مجلد محدد:

>>> hf upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/

أخيرًا، يمكنك رفع مجلد إلى وجهة محددة في المستودع:

>>> hf upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train

رفع ملف واحد

يمكنك أيضًا رفع ملف واحد عن طريق تعيين local_path ليُشير إلى ملف على جهازك. في هذه الحالة، يكون path_in_repo اختياريًا وسيُستخدم افتراضيًا اسم ملفك المحلي:

>>> hf upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors

إذا كنت ترغب في رفع ملف واحد إلى مجلد محدد، فاضبط path_in_repo وفقًا لذلك:

>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors

رفع ملفات متعددة

لرفع عدة ملفات من مجلد دفعة واحدة دون رفع المجلد بأكمله، استخدم أنماط --include و--exclude. كما يمكن دمج ذلك مع خيار --delete لحذف الملفات من المستودع أثناء رفع ملفات جديدة. في المثال أدناه، نزامن المساحة المحلية عن طريق حذف الملفات البعيدة ورفع جميع الملفات باستثناء تلك الموجودة في /logs:

# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...

الرفع إلى مجموعة بيانات أو مساحة

لرفع البيانات إلى مجموعة بيانات أو مساحة، استخدم خيار --repo-type:

>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...

الرفع إلى منظمة

لرفع المحتوى إلى مستودع مملوك لمنظمة بدلاً من مستودع شخصي، يجب عليك تحديد ذلك صراحةً في repo_id:

>>> hf upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/

الرفع إلى إصدار محدد

بشكل افتراضي، يتم رفع الملفات إلى الفرع main. إذا كنت ترغب في رفع الملفات إلى فرع أو مرجع آخر، فاستخدم الخيار --revision:

# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...

ملاحظة: إذا لم يكن revision موجودًا ولم يتم تعيين --create-pr، فسيتم إنشاء فرع تلقائيًا من الفرع main.

استخدام معرّف URI بصيغة hf://

كما هو الحال مع hf download، يمكن التعبير عن الوجهة كوحدة hf:// URI واحدة تتبع القواعد النحوية hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (انظر مرجع HF URIs للحصول على الصياغة الكاملة). يتم قراءة نوع المستودع والمراجعة وpath_in_repo جميعها من URI:

# Equivalent to: hf upload Wauplin/my-cool-dataset ./train.csv data/train.csv --repo-type dataset --revision my-branch
>>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv

# Upload a whole folder to the root of a model repo
>>> hf upload hf://Wauplin/my-cool-model ./models

عند تقديم معرّف موحّد (URI)، لا يمكن تعيين --repo-type و--revision أيضاً لأنهما جزء بالفعل من المعرّف الموحّد (يُستدعى خطأ في حال العكس)، كما لا يمكن دمج المسار المضمن في المعرّف الموحّد مع الحجة path_in_repo.

الرفع وإنشاء طلب دمج

إذا لم يكن لديك إذن لدفع التغييرات إلى مستودع، فيجب عليك فتح طلب سحب (PR) وإعلام المؤلفين بالتغييرات التي تريد إجراؤها. يمكن القيام بذلك من خلال تعيين الخيار --create-pr:

# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/

الرفع على فترات منتظمة

في بعض الحالات، قد ترغب في دفع تحديثات دورية إلى مستودع. على سبيل المثال، يكون هذا مفيدًا إذا كنت تقوم بتدريب نموذج وتريد رفع مجلد السجلات كل 10 دقائق. يمكنك القيام بذلك باستخدام خيار --every:

# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10

تحديد رسالة التزام

استخدم --commit-message و--commit-description لتعيين رسالة ووصف مخصصين لالتزامك بدلاً من الافتراضي

>>> hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/main

تحديد رمز

لرفع الملفات، يجب عليك استخدام رمز. بشكل افتراضي، سيتم استخدام الرمز المحفوظ محليًا (باستخدام hf auth login). إذا كنت ترغب في المصادقة بشكل صريح، استخدم خيار --token:

>>> hf upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/main

وضع الصمت

بشكل افتراضي، يكون أمر hf upload مفصّلاً. حيث يطبع تفاصيل مثل رسائل التحذير، ومعلومات حول الملفات المرفوعة، وأشرطة التقدم. إذا كنت ترغب في كتم جميع هذه المخرجات، فاستخدم خيار --quiet. في هذه الحالة، يُطبع السطر الأخير فقط (أي الرابط إلى الملفات المرفوعة). وقد يكون ذلك مفيداً إذا كنت تريد تمرير المخرجات إلى أمر آخر في سكربت.

>>> hf upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/main

hf buckets

استخدم hf buckets لإدارة الدلاء (buckets) على Hugging Face Hub. توفر الدلاء تخزينًا للكائنات مشابهًا لـ S3 على Hugging Face، مدعومًا بخلفية التخزين Xet. على عكس المستودعات (التي تعتمد على git وتتتبع تاريخ الملفات)، فإن الدلاء هي حاويات تخزين كائنات عن بُعد مصممة للملفات واسعة النطاق مع إزالة التكرار المعتمدة على المحتوى. وهي مصممة لحالات الاستخدام التي تحتاج فيها إلى تخزين بسيط وسريع وقابل للتعديل، مثل تخزين نقاط الفحص (checkpoints) للتدريب، والسجلات، والمخرجات الوسيطة، أو أي مجموعة كبيرة من الملفات التي لا تحتاج إلى التحكم في الإصدارات. في الأمثلة أدناه، سنستعرض حالات الاستخدام الأكثر شيوعًا. للحصول على دليل كامل، راجع دليل الدلاء (Buckets guide).

إنشاء دلو

لإنشاء دلو جديد، استخدم hf buckets create. سيتم إنشاء الدلو ضمن نطاقك الافتراضي:

>>> hf buckets create my-bucket

يمكنك أيضًا إنشاء دلو خاص باستخدام علم --private:

>>> hf buckets create my-bucket --private

قائمة الدلاء وفحصها

لإدراج جميع دلاءك، استخدم hf buckets list (أو اختصاره hf buckets ls). يمكنك أيضاً إدراج الدلاء في منظمة محددة:

>>> hf buckets list
ID                   PRIVATE       SIZE TOTAL_FILES CREATED_AT
-------------------- ------- ---------- ----------- ----------
username/my-bucket                   32           5 2026-02-16
username/checkpoints         117609095         700 2026-02-13
username/logs                321757477        2000 2026-02-13

# Human-readable sizes
>>> hf buckets list -h
ID                   PRIVATE     SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket               32 B           5 2026-02-16
username/checkpoints         117.6 MB         700 2026-02-13
username/logs                321.8 MB        2000 2026-02-13

# List buckets in a specific namespace
>>> hf buckets ls my-org

# Filter buckets by name
>>> hf buckets list --search "checkpoint"

للحصول على معلومات مفصّلة حول دلوّ (bucket) محدّد (تُعاد بصيغة JSON)، استخدم hf buckets info:

>>> hf buckets info username/my-bucket
{
  "id": "username/my-bucket",
  "private": false,
  "created_at": "2026-02-16T15:28:32+00:00",
  "size": 32,
  "total_files": 5
}

تغيير حالة عرض الدلو

لتبديل الدلو بين الخاص والعام، استخدم hf buckets settings:

# Make a bucket private
>>> hf buckets settings username/my-bucket --private

# Make it public again
>>> hf buckets settings username/my-bucket --public

حذف دلو

لحذف دلو، استخدم hf buckets delete. سيُطلب منك تأكيد العملية ما لم تمرر --yes:

>>> hf buckets delete username/my-bucket --yes

إزالة الملفات

استخدم hf buckets remove (أو اختصاره hf buckets rm) لإزالة الملفات من الدلو.

لحذف ملف واحد، حدد مساره:

>>> hf buckets rm username/my-bucket/old-model.bin

لحذف جميع الملفات الموجودة تحت بادئة معينة، استخدم --recursive:

>>> hf buckets rm username/my-bucket/logs/ --recursive

يمكنك أيضًا استهداف جميع الملفات في الدلو دون بادئة:

>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"

استخدم --dry-run لمعاينة ما سيتم حذفه دون حذف أي شيء فعليًا:

>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run

تصفح الملفات

استخدم hf buckets list مع معبّر عن دلو (bucket ID) لعرض الملفات الموجودة في الدلو:

>>> hf buckets list username/my-bucket
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
              2026-01-15 10:30:00  sub/

أضف -R لعرض قائمة متكررة، و-h لعرض أحجام الملفات وتواريخ مختصرة بصيغة مقروءة للبشر. يمكنك أيضًا عرض شجرة بصيغة ASCII باستخدام --tree، أو استخدام --tree --quiet لعرض شجرة نظيفة دون بيانات وصفية:

# Recursive with human-readable sizes
>>> hf buckets list username/my-bucket -R -h
      2.0 KB         Jan 15 10:30  big.bin
         5 B         Jan 15 10:30  file.txt
        14 B         Jan 15 10:30  sub/nested.txt
         4 B         Jan 15 10:30  sub/deep/file.txt

# Tree with human-readable sizes
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB  Jan 15 10:30  ├── big.bin
   5 B  Jan 15 10:30  ├── file.txt
                      └── sub/
                          ├── deep/
   4 B  Jan 15 10:30  │       └── file.txt
  14 B  Jan 15 10:30  └── nested.txt

# Clean tree without metadata
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
    ├── deep/
    │   └── file.txt
    └── nested.txt

لترشيح حسب البادئة، أضف البادئة إلى مسار الدلو:

>>> hf buckets list username/my-bucket/sub -R

نسخ الملفات

استخدم hf cp لنسخ ملف واحد بين جهازك المحلي والمستودعات والخزانات. يمكن أن يكون المصدر والوجهة، كلٌّ على حدة، مسارًا محليًا، أو معرّفًا hf:// (مستودع أو خزان)، أو - (مدخل/مخرج قياسي).

يُعرَض hf cp أيضًا على شكل hf repos cp وhf buckets cp — جميعها هي نفس الأمر تمامًا. استخدم أيًّا منها حسب ما يناسب سير عملك.

لرفع ملف (محلي ← مستودع أو حاوية):

# To a repository
>>> hf cp ./model.safetensors hf://username/my-model/model.safetensors

# To a bucket (uses the local filename when the destination ends with /)
>>> hf cp ./data.csv hf://buckets/username/my-bucket/logs/

لتحميل ملف (مستودع أو دلو ← محلي):

# From a repository
>>> hf cp hf://datasets/username/my-dataset@refs/pr/1/data.csv ./data.csv

# From a bucket, to the current directory (destination omitted)
>>> hf cp hf://buckets/username/my-bucket/config.json

يمكنك أيضًا البث إلى stdout أو من stdin باستخدام -:

# Download to stdout
>>> hf cp hf://buckets/username/my-bucket/config.json - | jq .

# Upload from stdin
>>> echo "hello" | hf cp - hf://username/my-model/hello.txt

لنسخ بين موقعين على Hub (مستودع/دلو ← مستودع/دلو):

# Repo to repo
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Repo to bucket
>>> hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/

# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/

عند نسخ المجلدات بين موقعين على Hub، يتحكم وجود / في نهاية المسار المصدر في ما إذا كان المجلد نفسه سيُضمَّن داخل مجلد آخر أم أن محتوياته فقط هي التي ستُنسخ (على غرار أسلوب rsync):

# Without trailing slash: "logs" dir is nested => archive/logs/...
>>> hf cp hf://buckets/username/my-bucket/logs hf://buckets/username/archive-bucket/

# With trailing slash: only contents of "logs" are copied => archive/...
>>> hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/

ملاحظات:

ينسخ hf cp ملفًا واحدًا عندما يتعلق الأمر بمسار محلي. لنسخ المجلدات كاملة إلى/من المسار المحلي، استخدم hf upload/hf download (المستودعات) أو hf buckets sync (الدلاء).
نسخة من الدلو إلى المستودع غير مدعومة بعد.
نسخة محلية إلى محلية غير مدعومة (استخدم cp في shell الخاص بك).
لا تعمل عمليات النسخ بين موقعين على Hub إلا ضمن نطاق تخزين واحد.

مزامنة المجلدات

استخدم hf buckets sync لمزامنة المجلدات بين جهازك المحلي ودلو. يقارن المصدر والوجهة وينقل الملفات التي تم تغييرها فقط.

لرفع مجلد محلي إلى حاوية:

>>> hf buckets sync ./data hf://buckets/username/my-bucket

لتحميل البيانات من دلو إلى مجلد محلي:

>>> hf buckets sync hf://buckets/username/my-bucket ./data

استخدم --delete لإزالة الملفات الموجودة في الوجهة والتي لا توجد في المصدر:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --delete

يمكنك تصفية الملفات المراد مزامنتها باستخدام أنماط --include و--exclude:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"

لتحديث الملفات الموجودة فقط (وتخطي الجديدة)، استخدم --existing. لإنشاء الملفات الجديدة فقط (وتخطي الموجودة)، استخدم --ignore-existing:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existing

لأمان إضافي، يمكنك توليد خطة للمراجعة قبل التنفيذ، ثم تطبيقها:

# Generate a plan
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl

# Review and apply the plan
>>> hf buckets sync --apply sync-plan.jsonl

استخدم --dry-run لطباعة خطة المزامنة بصيغة JSONL إلى الإخراج القياسي دون تنفيذ أي شيء. هذا مفيد للتوصيل إلى jq أو أدوات أخرى:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .

hf sync هو اسم مستعار علوي مريح لـ hf buckets sync. راجع دليل Buckets للحصول على تفاصيل كاملة حول جميع خيارات المزامنة.

hf models

استخدم hf models لعرض النماذج على Hub والحصول على معلومات مفصّلة عن نموذج معيّن.

قائمة النماذج

# List trending models
>>> hf models ls

# Search for models
>>> hf models ls --search "lora"

# Filter by author
>>> hf models ls --author Qwen

# Filter by pipeline tag
>>> hf models ls --pipeline-tag summarization

# Filter by parameter count
>>> hf models ls --num-parameters min:6B,max:128B

# Only non-gated models
>>> hf models ls --no-gated --author google

# Only models runnable by a given app
>>> hf models ls --apps llama.cpp

# Sort by downloads
>>> hf models ls --sort downloads --limit 10

عند الاستدعاء مع معرّف نموذج، يعرض hf models ls الملفات في مستودع ذلك النموذج:

# List files in a model repo
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct

# List files recursively
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct -R

# Tree view with human-readable sizes
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h

# List files at a specific revision
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --revision main

الحصول على معلومات النموذج

>>> hf models info Lightricks/LTX-2

استخدم --expand لجلب خصائص إضافية مثل downloads، likes، tags، وما إلى ذلك.

الحصول على بطاقة النموذج

استخدم hf models card لجلب بطاقة النموذج (README) لنموذج معين. بشكل افتراضي، يطبع المحتوى الكامل للبطاقة إلى stdout.

# Full card (metadata + text)
>>> hf models card google/gemma-4-31B-it

# Just the metadata (from the YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --metadata

# Metadata as JSON (useful for scripting and agents)
>>> hf models card google/gemma-4-31B-it --metadata --format json

# Just the text body (no YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --text

hf datasets

استخدم hf datasets لعرض مجموعات البيانات على Hub والحصول على معلومات مفصّلة عن مجموعة بيانات محددة.

قوائم مجموعات البيانات

# List trending datasets
>>> hf datasets ls

# Search for datasets
>>> hf datasets ls --search "code"

# List official benchmark datasets
>>> hf datasets ls --filter benchmark:official

# Sort by downloads
>>> hf datasets ls --sort downloads --limit 10

عند الاستدعاء مع معرّف مجموعة بيانات، يعرض hf datasets ls الملفات في مستودع تلك المجموعة:

# List files in a dataset repo
>>> hf datasets ls HuggingFaceFW/fineweb

# List files recursively with human-readable sizes
>>> hf datasets ls HuggingFaceFW/fineweb -R -h

# Tree view
>>> hf datasets ls HuggingFaceFW/fineweb --tree

قائمة لوحة صدارة مجموعة بيانات

استخدم hf datasets leaderboard لعرض درجات النماذج المُرسلة إلى مجموعة بيانات مرجعية، حتى تتمكن من إيجاد أفضل النماذج لمهمة معينة أو مقارنة النماذج بناءً على درجاتها المرجعية.

>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format json

الحصول على معلومات مجموعة البيانات

>>> hf datasets info HuggingFaceFW/fineweb

الحصول على بطاقة مجموعة البيانات

استخدم hf datasets card لجلب بطاقة البيانات (README) لمجموعة بيانات. بشكل افتراضي، يطبع المحتوى الكامل للبطاقة إلى stdout.

# Full card (metadata + text)
>>> hf datasets card HuggingFaceFW/fineweb

# Just the metadata (from the YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --metadata

# Metadata as JSON (useful for scripting and agents)
>>> hf datasets card HuggingFaceFW/fineweb --metadata --format json

# Just the text body (no YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --text

قائمة عناوين URL لملفات parquet

استخدم hf datasets parquet لاكتشاف عناوين ملفات Parquet الخاصة بمجموعة بيانات قبل كتابة استعلامات SQL. تُحوَّل مجموعات البيانات على Hub تلقائيًا إلى Parquet في الخلفية بواسطة خدمة Dataset Viewer (للمجموعات المؤهلة). راجع دليل تحويل Parquet للتفاصيل.

>>> hf datasets parquet cfahlgren1/hub-stats
>>> hf datasets parquet cfahlgren1/hub-stats --subset models
>>> hf datasets parquet cfahlgren1/hub-stats --split train
>>> hf datasets parquet cfahlgren1/hub-stats --format json

يشمل مخرجات الجدول الافتراضية مجموعة فرعية، وقسم، ورابط ملف parquet من واجهة برمجة تطبيقات Hub.

تشغيل SQL على parquet للبيانات

استخدم hf datasets sql لتنفيذ استعلامات SQL خام باستخدام DuckDB على عناوين URL الخاصة بملفات parquet في مجموعة البيانات. اكتشف العناوين أولاً باستخدام hf datasets parquet، ثم استعلم عنها مباشرةً باستخدام read_parquet(...).

>>> hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')"
>>> hf datasets sql "SELECT * FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet') LIMIT 5" --format json

قم بتثبيت DuckDB أولاً إذا لزم الأمر:

# Python package
>>> pip install duckdb

# or standalone DuckDB CLI (Homebrew: macOS/Linux)
>>> brew install duckdb

hf spaces

استخدم hf spaces لعرض مساحات (Spaces) على Hub والحصول على معلومات مفصّلة عن مساحة محددة.

قائمة المساحات

# List trending Spaces
>>> hf spaces ls

# Search for Spaces
>>> hf spaces ls --search "3d"

# Sort by likes
>>> hf spaces ls --sort likes --limit 10

عند الاستدعاء مع معرّف مساحة، يعرض hf spaces ls الملفات في مستودع تلك المساحة:

# List files in a Space repo
>>> hf spaces ls victor/deepsite

# List files recursively with tree view
>>> hf spaces ls victor/deepsite --tree -R -h

الحصول على معلومات المساحة

>>> hf spaces info victor/deepsite

احصل على بطاقة مساحة

استخدم hf spaces card لجلب بطاقة المساحة (README) لمساحة معينة. بشكل افتراضي، يطبع المحتوى الكامل للبطاقة إلى الإخراج القياسي.

# Full card (metadata + text)
>>> hf spaces card mteb/leaderboard

# Just the card metadata (from the YAML frontmatter)
>>> hf spaces card mteb/leaderboard --metadata

# Card metadata as JSON
>>> hf spaces card mteb/leaderboard --metadata --format json

# Just the text body (no YAML frontmatter)
>>> hf spaces card mteb/leaderboard --text

إن إيقاف مساحة مؤقتًا أو إعادة تشغيلها يؤدي إلى تفكيك حاويتها، وبالتالي يُفقد أي شيء كُتب على نظام الملفات المؤقت. ولحفظ البيانات عبر عمليات إعادة التشغيل، قم بتركيب وحدة تخزين أو دلو باستخدام hf spaces volumes set (شغّل hf spaces volumes --help للاطلاع على التفاصيل).

إيقاف مساحة مؤقتًا

استخدم hf spaces pause لإيقاف مساحة مؤقتًا عندما لا تكون قيد الاستخدام (لا يتم احتساب رسوم وقت الإيقاف المؤقت). أعد تشغيلها لاحقًا باستخدام hf spaces restart.

>>> hf spaces pause username/my-space

إعادة تشغيل مساحة

استخدم hf spaces restart لإعادة تشغيل مساحة. مرّر --factory-reboot لإعادة بناء المساحة من الصفر دون استخدام ذاكرة التخزين المؤقت للبناء.

>>> hf spaces restart username/my-space
>>> hf spaces restart username/my-space --factory-reboot

انتظار مساحة

استخدم hf spaces wait للحجب حتى ينتهي بناء مساحة أو بدء تشغيلها وتصل إلى مرحلة مستقرة. ينتهي الأمر برمز 0 إذا كانت المساحة RUNNING، أو برمز غير صفري في الحالات الأخرى (مثل BUILD_ERROR). مفيد للتبويب بعد إعادة التشغيل أو تغيير العتاد.

>>> hf spaces wait username/my-space

# With a timeout
>>> hf spaces wait username/my-space --timeout 5m

# Chain with restart
>>> hf spaces restart username/my-space && hf spaces wait username/my-space

قائمة الأجهزة المتاحة

استخدم hf spaces hardware لعرض جميع خيارات الأجهزة المتاحة لـ Spaces، بما في ذلك التسعير.

>>> hf spaces hardware

تحقق من حصة ZeroGPU الخاصة بك

استخدم hf spaces zero-gpu quota للتحقق من مقدار حصة ZeroGPU المتبقية لديك ومتى تُعاد ضبطها. وهذا مفيد لتتبع استخدامك عند استدعاء مساحات ZeroGPU من السكربتات أو التطبيقات أو الوكلاء.

>>> hf spaces zero-gpu quota
✓ ZeroGPU quota (in GPU-seconds)
  remaining: 1810
  base: 2400
  resets_at: 2026-09-30T18:12:03+00:00
  overquota_used: 0

>>> hf spaces zero-gpu quota --format json
{"remaining": 1810, "base": 2400, "resets_at": "2026-09-30T18:12:03+00:00", "overquota_used": 0}

إذا كان رصيدك منخفضًا، يقترح الأمر شراء أرصدة من إعدادات الفوترة للمتابعة في استخدام ZeroGPU بعد تجاوز الحصة اليومية (لمستخدمي PRO وTeam وEnterprise فقط).

تحديث إعدادات المساحة

استخدم hf spaces settings لتحديث إعدادات مساحة.

>>> hf spaces settings username/my-space --sleep-time 3600
>>> hf spaces settings username/my-space --hardware t4-medium

--sleep-time: وقت الخمول بالثواني قبل أن يدخل المساحة في وضع السكون. استخدم -1 لمنع الدخول في وضع السكون. متوفر فقط على الأجهزة المطوّرة (انظر وثائق وقت سكون المساحات).
--hardware: نوع العتاد (مثل cpu-basic، t4-medium، l4x4). شغّل hf spaces hardware لعرض جميع الخيارات.

إدارة أسرار المساحة

استخدم hf spaces secrets ls لعرض الأسرار على مساحة، وhf spaces secrets add لإضافة سر واحد أو أكثر أو تحديثه، وhf spaces secrets delete لحذف سر. مرّر --secrets-file PATH لتحميل الأسرار من ملف بنمط .env. يتم تجاوز المفاتيح الموجودة مسبقًا.

>>> hf spaces secrets ls username/my-space
>>> hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...
>>> hf spaces secrets add username/my-space --secrets-file .env.secrets
>>> hf spaces secrets delete username/my-space OPENAI_API_KEY --yes

قيم الأسرار قابلة للكتابة فقط، لذا يعرض hf spaces secrets ls المفاتيح والوصوف وطوابع التحديث، لكنه لا يعرض قيم الأسرار نفسها أبدًا.

إدارة متغيرات البيئة في Space

استخدم hf spaces variables لإدارة متغيرات البيئة غير السرية على مساحة. على عكس الأسرار، يمكن قراءة المتغيرات، لذا يعرض ls كلا من المفاتيح والقيم. مرّر --env-file PATH عند add للتحميل من ملف بنمط .env.

>>> hf spaces variables ls username/my-space
>>> hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512
>>> hf spaces variables add username/my-space --env-file .env
>>> hf spaces variables delete username/my-space MAX_TOKENS --yes

الاتصال عبر SSH بمساحة (وضع التطوير)

استخدم hf spaces ssh لفتح جلسة SSH داخل حاوية وضع التطوير (Dev Mode) الخاصة بمساحة (Space). إذا لم يكن وضع التطوير مفعلاً، فسيطلب منك سطر الأوامر تفعيله (أو استخدم --auto لتخطي الطلب).

يجب تسجيل مفتاح SSH العام الخاص بك في إعداداتك. راجع توثيق وضع المطور لمزيد من التفاصيل.

# SSH into a Space
>>> hf spaces ssh username/my-space

# Print the SSH command without running it
>>> hf spaces ssh username/my-space --dry-run

# Auto-enable Dev Mode if disabled
>>> hf spaces ssh username/my-space --auto

# Use a specific SSH key
>>> hf spaces ssh username/my-space -i ~/.ssh/id_ed25519

hf papers

استخدم hf papers لعرض قائمة بالأوراق البحثية والبحث فيها والحصول على معلومات منظمة وقراءة محتوى الأوراق بصيغة Markdown على Hub.

قائمة الأوراق

# List most recent daily papers
>>> hf papers ls

# List trending papers
>>> hf papers ls --sort=trending

# List papers from a specific date
>>> hf papers ls --date=2025-01-23

# List today's papers
>>> hf papers ls --date=today

# List papers from a specific week
>>> hf papers ls --week=2025-W09

# List papers from a specific month
>>> hf papers ls --month=2025-02

# List papers submitted by a specific user
>>> hf papers ls --submitter=akhaliq

# Limit results
>>> hf papers ls --sort=trending --limit=5

البحث في الأوراق

# Search papers by keyword
>>> hf papers search "vision language"

# Limit search results
>>> hf papers search "diffusion models" --limit=10

# Output as JSON
>>> hf papers search "attention" --format=json

الحصول على معلومات الورقة

# Get structured metadata for a paper (returns JSON)
>>> hf papers info 2601.15621

قراءة الورقة بصيغة Markdown

# Read the full paper content as markdown
>>> hf papers read 2601.15621

hf discussions

استخدم hf discussions لإدارة النقاشات وطلبات الدمج في مستودعات Hub مباشرةً من الطرفية. يمكنك عرض قائمة بالنقاشات وطلبات الدمج، وعرضها، وإنشاؤها، والتعليق عليها، وإغلاقها، وإعادة فتحها، ودمجها. للاطلاع على دليل كامل حول كيفية عمل ميزات المجتمع في Hub، راجع دليل النقاشات وطلبات الدمج.

قائمة المناقشات

لإدراج المناقشات وطلبات الدمج المفتوحة في مستودع، مرّر معرّف المستودع إلى hf discussions list (أو اختصاره hf discussions ls):

>>> hf discussions list username/my-model

يمكنك تضييق نطاق النتائج حسب النوع (discussion أو pull_request)، أو الحالة (open، closed، merged، أو all)، أو المؤلف:

>>> hf discussions list username/my-model --kind pull_request --status merged
>>> hf discussions list username/my-model --author alice

لأغراض البرمجة النصية، استخدم --format json للحصول على مخرجات منظمة، أو --quiet لطباعة أرقام المناقشات فقط (واحد في كل سطر):

>>> hf discussions list username/my-model --format json
>>> hf discussions ls username/my-model --quiet

الحصول على معلومات حول نقاش أو طلب دمج

لفحص نقاش أو طلب دمج محدد، مرّر معرّف المستودع ورقم النقاش:

>>> hf discussions info username/my-model 5

تحتوي المخرجات على بيانات وصفية للنقاش (العنوان، الحالة، المؤلف، إلخ) إلى جانب القائمة الكاملة لأحداث المحادثة. لعرض اختلافات طلب السحب، استخدم hf discussions diff بدلاً من ذلك.

استخدم --format json للحصول على مخرجات قابلة للقراءة آليًا، واضبط NO_COLOR=1 لإزالة ألوان ANSI عند تمرير البيانات إلى أدوات أخرى.

إنشاء نقاش أو طلب دمج

لفتح نقاش جديد، قدّم عنوانًا باستخدام --title. يمكنك اختيارًا تضمين وصف مضمّن باستخدام --body، أو تحميله من ملف باستخدام --body-file:

>>> hf discussions create username/my-model --title "Bug report"
>>> hf discussions create username/my-model --title "Feature request" --body "Please add X"
>>> hf discussions create username/my-model --title "Report" --body-file report.md

لإنشاء طلب سحب بدلاً من نقاش عادي، أضف علم --pull-request:

>>> hf discussions create username/my-model --title "Fix typo" --pull-request

التعليق على نقاش أو طلب دمج

أضِف تعليقًا إلى نقاش أو طلب سحب قائم من خلال تحديد رقمه. يمكن تمرير نص التعليق مباشرةً باستخدام --body، أو قراءته من ملف باستخدام --body-file، أو تمريره من مدخل البيانات القياسي باستخدام --body-file -:

>>> hf discussions comment username/my-model 5 --body "Thanks for reporting!"
>>> hf discussions comment username/my-model 5 --body-file review.md
>>> echo "LGTM" | hf discussions comment username/my-model 5 --body-file -

تعديل تعليق

قم بتعديل تعليق موجود في مكانه عن طريق تمرير رقم النقاش ومعرّف التعليق. يمكن الحصول على معرّفات التعليقات باستخدام hf discussions info:

>>> hf discussions edit username/my-model 5 abc123 --body "Updated comment."
>>> hf discussions edit username/my-model 5 abc123 --body-file fixed.md

إرفاق الصور والفيديوهات

مرّر --attach إلى hf discussions create أو comment أو edit لرفع صورة أو فيديو أو ملف صوتي وتضمينه في النص، كما تفعل عند سحب ملف إلى مربع التعليق على Hub. إذا كان النص يشير بالفعل إلى الملف، كما في ![Before the fix](./before.png)، فإن الإشارة تشير إلى الملف المرفوع. وإلا، يُضاف الملف إلى النص. لضبط النص البديل لصورة مضافة، أضفه بعد #:

>>> hf discussions create username/my-model --title "Fix rendering" --pr --body "Before: ![Before the fix](./before.png)" --attach ./before.png --attach "./after.png#After the fix"
>>> hf discussions comment username/my-model 5 --body "Here is a demo:" --attach demo.mp4

الصيغ المدعومة هي PNG وJPEG وGIF وWebP وMP4 وMOV وWebM وMP3 وWAV، بحد أقصى 10 ميغابايت (50 ميغابايت للفيديوهات).

الإغلاق، إعادة الفتح، والدمج

يمكنك إغلاق نقاش أو طلب سحب باستخدام hf discussions close. بشكل افتراضي، سيُطلب منك تأكيد الإجراء. مرّر --yes لتخطي طلب التأكيد، و--comment لإضافة رسالة إغلاق:

>>> hf discussions close username/my-model 5
>>> hf discussions close username/my-model 5 --yes --comment "Resolved"

لإعادة فتح نقاش أُغلق سابقًا، استخدم hf discussions reopen:

>>> hf discussions reopen username/my-model 5 --yes

لدمج طلب سحب، استخدم hf discussions merge:

>>> hf discussions merge username/my-model 5 --yes

إعادة التسمية والفرق

يمكنك إعادة تسمية نقاش من خلال تقديم العنوان الجديد:

>>> hf discussions rename username/my-model 5 "Updated title"

لعرض اختلافات طلب الدمج مباشرةً في الطرفية، استخدم hf discussions diff:

>>> hf discussions diff username/my-model 5

hf repos

hf repos يتيح لك سرد المستودعات وإنشاؤها ونسخها وحذفها ونقلها، وتحديث إعداداتها، وحذف الملفات على Hugging Face Hub. كما يتضمن أوامر فرعية لإدارة الفروع والوسوم.

قائمة المستودعات

استخدم hf repos ls لعرض جميع مستودعاتك (النماذج، مجموعات البيانات، المساحات، والدلاء) مع معلومات التخزين، مرتبة حسب استهلاك التخزين. بشكل افتراضي، يتم عرض أول 30 مستودعًا فقط:

# List all your repos (first 30)
>>> hf repos ls
REPOSITORY                TYPE     UPDATED      VISIBILITY   STORAGE  % OF TOTAL
------------------------  -------  ----------   ----------  --------  ----------
username/bucket-raw       bucket   2026-04-29   public        1.7 TB       72.3%
username/my-model         model    2026-05-06   public        4.8 GB       18.1%
username/my-dataset       dataset  2024-09-14   private     598.4 MB        5.2%
Hint: Showing 30 of 42 repos. Use `--limit 0` to list all.

تصفية حسب نوع المستودع، أو البحث بالاسم، أو تعديل الحد:

# List only models
>>> hf repos ls --type model

# Search by name
>>> hf repos ls --search "bert"

# List repos from an organization
>>> hf repos ls --namespace my-org

# Combine filters
>>> hf repos ls --namespace my-org --type dataset --search "train"

# List all repos (no limit)
>>> hf repos ls --limit 0

استخدم --format json لأغراض البرمجة أو -q للحصول على المعرّفات فقط. عند استخدام الأنابيب (piping)، استخدم --limit 0 لتصدير جميع المستودعات:

>>> hf repos ls --limit 0 --format json | jq '.[].id'
>>> hf repos ls -q

إنشاء مستودع

>>> hf repos create Wauplin/my-cool-model
Successfully created Wauplin/my-cool-model on the Hub.
Your repo is now available at https://huggingface.co/Wauplin/my-cool-model

إنشاء مجموعة بيانات خاصة أو مساحة:

>>> hf repos create my-cool-dataset --repo-type dataset --private
>>> hf repos create my-gradio-space --repo-type space --sdk gradio

استخدم --exist-ok إذا كان المستودع قد يكون موجودًا بالفعل، و--resource-group-id لاستهداف مجموعة موارد Enterprise.

إنشاء مستودع في منطقة محددة:

>>> hf repos create my-model --region us

نسخ مستودع

استخدم hf repos duplicate لنسخ نموذج أو مجموعة بيانات أو مساحة موجودة إلى حسابك (أو إلى منظمة). يتم النسخ على الخادم ويحافظ على سجل git:

>>> hf repos duplicate openai/gdpval --type dataset
>>> hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --private

قد لا تزال ملفات LFS/Xet في المستودع الجديد تُنسخ في الخلفية بعد عودة الأمر. في هذه الحالة، يتم طباعة تحذير وقد يفشل تنزيل هذه الملفات من المستودع الجديد حتى اكتمال عملية النسخ.

حذف مستودع

>>> hf repos delete Wauplin/my-cool-model

مجموعات البيانات والمساحات:

>>> hf repos delete my-cool-dataset --repo-type dataset
>>> hf repos delete my-gradio-space --repo-type space

نقل مستودع

>>> hf repos move old-namespace/my-model new-namespace/my-model

تحديث إعدادات المستودع

>>> hf repos settings Wauplin/my-cool-model --gated auto
>>> hf repos settings Wauplin/my-cool-model --private true
>>> hf repos settings Wauplin/my-cool-model --private false

--gated: أحد auto، manual، false
--private true|false: تحديد خصوصية المستودع

حذف الملفات من مستودع

تتيح لك الأوامر الفرعية hf repos delete-files <repo_id> حذف الملفات من المستودع. فيما يلي بعض الأمثلة على الاستخدام.

حذف مجلد:

>>> hf repos delete-files Wauplin/my-cool-model folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

حذف ملفات متعددة:

>>> hf repos delete-files Wauplin/my-cool-model file.txt folder/pytorch_model.bin
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

استخدم أنماط النطاقات الحرة (wildcard patterns) لحذف مجموعات من الملفات. الأنماط هي أنماط النطاقات القياسية (globbing patterns) كما هو موثق هنا. يعتمد مطابقة الأنماط على fnmatch.

لاحظ أن fnmatch يطابق * عبر حدود المسارات، على عكس نمط Unix التقليدي. على سبيل المثال، سيؤدي "data/*.json" إلى مطابقة كل من data/file.json و data/subdir/file.json. لمطابقة الملفات الموجودة في المجلد المباشر فقط، يجب عليك إدراجها صراحةً أو استخدام أنماط أكثر تحديدًا.

>>> hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

لحذف الملفات من مستودع، يجب أن تكون مُوثَّقًا ومُخوَّلًا. افتراضيًا، سيتم استخدام الرمز المحفوظ محليًا (باستخدام hf auth login). إذا كنت ترغب في المصادقة بشكل صريح، استخدم خيار --token:

>>> hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txt

hf repos branch

استخدم hf repos branch لإنشاء فروع وحذفها للمستودعات على Hub.

# Create a branch
>>> hf repos branch create Wauplin/my-cool-model dev

# Create a branch from a specific revision
>>> hf repos branch create Wauplin/my-cool-model release-1 --revision refs/pr/104

# Delete a branch
>>> hf repos branch delete Wauplin/my-cool-model dev

تقبل جميع الأوامر --repo-type (إحدى القيم: model، dataset، space) و--token إذا كنت بحاجة إلى المصادقة بشكل صريح. استخدم --help مع أي أمر لعرض جميع الخيارات.

hf cache

استخدم hf cache لإدارة مجلد ذاكرة التخزين المؤقت المحلية الخاصة بك على Hugging Face. تخزّن هذه الذاكرة النماذج ومجموعات البيانات وSpaces والنوى التي تم تنزيلها من Hub.

# List cached repositories
>>> hf cache ls

# List cached revisions
>>> hf cache ls --revisions

# Remove specific items from cache
>>> hf cache rm model/gpt2

# Remove unreferenced revisions
>>> hf cache prune

# Verify cached file checksums
>>> hf cache verify gpt2

hf cache ls

استخدم hf cache ls لفحص ما هو مخزَّن محليًا في ذاكرة التخزين المؤقت لحسابك على Hugging Face. افتراضيًا، يقوم بتجميع المعلومات حسب المستودع:

>>> hf cache ls
ID                          SIZE     LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue          157.4M 2 days ago    2 days ago    main script
model/LiquidAI/LFM2-VL-1.6B     3.2G 4 days ago    4 days ago    main
model/microsoft/UserLM-8b      32.1G 4 days ago    4 days ago    main

Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.

أضف --revisions للتعمق في لقطات محددة، وسلسل عوامل التصفية للتركيز على ما يهم:

>>> hf cache ls --filter "size>30g" --revisions
ID                        REVISION                                 SIZE     LAST_MODIFIED REFS
------------------------- ---------------------------------------- -------- ------------- ----
model/microsoft/UserLM-8b be8f2069189bdf443e554c24e488ff3ff6952691    32.1G 4 days ago    main

Found 1 repo(s) for a total of 1 revision(s) and 32.1G on disk.

يدعم الأمر عدة صيغ مخرجات لأغراض البرمجة: يطبع --format json كائنات منظمة، ويكتب --format csv صفوفًا مفصولة بفواصل، بينما يطبع --quiet المعرّفات فقط. استخدم --sort لترتيب الإدخالات حسب accessed أو modified أو name أو size (أضف :asc أو :desc للتحكم في الترتيب)، واستخدم --limit لتقييد النتائج بأفضل N إدخالات. اجمع هذه الخيارات مع --cache-dir لاستهداف مواقع تخزين مؤقت بديلة. راجع دليل إدارة ذاكرتك المؤقتة للحصول على سير عمل متقدمة.

احذف إدخالات ذاكرة التخزين المؤقت المحددة باستخدام hf cache ls --q عن طريق تمرير المعرّفات إلى hf cache rm:

>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
  - model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
  - model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.

hf cache rm

hf cache rm يحذف المستودعات المخزنة مؤقتًا، أو المراجعات الفردية، أو الملفات المنفردة. مرّر معرّفًا واحدًا أو أكثر للمستودعات (model/bert-base-uncased)، أو عناوين hf://، أو تجزئات المراجعة:

>>> hf cache rm model/LiquidAI/LFM2-VL-1.6B
About to delete 1 repo(s) totalling 3.2G.
  - model/LiquidAI/LFM2-VL-1.6B (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 2 revision(s); freed 3.2G.

يتم أيضًا دعم عناوين URI على مستوى المستودع hf:// :

>>> hf cache rm hf://models/openai-community/gpt2 --dry-run
About to delete 1 repo(s) totalling 1.1G.
  - model/openai-community/gpt2 (entire repo)
Dry run: no files were deleted.

لحذف ملف واحد بدلاً من مستودع كامل، على سبيل المثال كميّة GGUF واحدة، مرّر عنوان URI للملف بصيغة hf://. يُحذف الملف من كل نسخة مخبأة من المستودع، ولا يُحذف blob الخاص به إلا إذا لم يكن أي ملف مخبأ آخر لا يزال يشير إليه:

>>> hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
  - model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.

تبقى النسخة قابلة للاستخدام، ويُعاد تنزيل الملف المحذوف في المرة التالية التي يُحتاج فيها. يجب أن تتطابق المسارات تمامًا: لا يتم دعم المجلدات أو أنماط globs، ولا يمكن خلط أهداف الملفات مع المستودعات أو النسخ في نفس الاستدعاء.

اخلط المستودعات والمراجعات المحددة في نفس الاستدعاء. استخدم --dry-run لمعاينة الأثر، أو --yes لتخطي مطالبة التأكيد—مما يجعلها مفيدة في السكربتات الآلية:

>>> hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
  - model/t5-small:
      8f3ad1c [main] 1.1G
Dry run: no files were deleted.

عند العمل خارج موقع التخزين المؤقت الافتراضي، اجمع الأمر مع --cache-dir PATH.

hf cache prune

hf cache prune اختصار مريح لاستعادة المساحة التي تشغلها نفايات الكاش: كل نسخة منفصلة (غير مُشار إليها) (مع الإبقاء فقط على النسخ التي لا تزال قابلة للوصول عبر فرع أو وسم)، وأي ملفات .incomplete متبقية من عمليات تنزيل مُقاطعة، وأي كتل مشتركة لم تعد مُشار إليها من أي مستودع مخزّن مؤقتًا:

>>> hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
  - model/t5-small:
      1c610f6b [refs/pr/1] 820.1M
      d4ec9b72 [(detached)] 640.5M
  - dataset/google/fleurs:
      2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.

ملفات .incomplete هي تنزيلات جزئية تُترك خلفها عندما ينقطع التنزيل. لا تتتبعها أوامر hf cache ls/rm (التي تعمل على مستوى المراجعة)، لذا يُشير إليها hf cache ls مع تلميح، ويقوم hf cache prune بإزالتها تلقائيًا.

كما هو الحال مع أوامر الكاش الأخرى، يتوفر --dry-run و--yes و--cache-dir. راجع دليل إدارة الكاش لمزيد من الأمثلة.

hf cache verify

استخدم hf cache verify للتحقق من الملفات المحلية مقابل قيم التجزئة الخاصة بها على Hub. يمكنك التحقق إما من لقطة مؤقت (cache snapshot) أو من مجلد محلي عادي.

أمثلة:

# Verify main revision of a model in cache
>>> hf cache verify deepseek-ai/DeepSeek-OCR

# Verify a specific revision
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision ef93bf4a377c5d5ed9dca78e0bc4ea50b26fe6a4

# Verify a private repo
>>> hf cache verify me/private-model --token hf_***

# Verify a dataset
>>> hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset

# Verify files in a local directory
>>> hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo

بشكل افتراضي، يُصدر الأمر تحذيرات بشأن الملفات المفقودة أو الإضافية. استخدم الأعلام لتحويل هذه التحذيرات إلى أخطاء:

>>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-files

عند النجاح، ستظهر لك ملخّص:

✅ Verified 13 file(s) for 'deepseek-ai/DeepSeek-OCR' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6
  All checksums match.

إذا تم اكتشاف عدم تطابق، يطبع الأمر قائمة مفصلة وينتهي بحالة غير صفرية.

hf repos tag

استخدم hf repos tag لإنشاء وسوم المستودعات على Hub وقوائمها وحذفها.

# Create a tag
>>> hf repos tag create my-model v1.0

# List tags
>>> hf repos tag list my-model

# Delete a tag
>>> hf repos tag delete my-model v1.0

وسم نموذج

لوضع وسم على مستودع، يجب عليك تقديم repo_id واسم tag:

>>> hf repos tag create Wauplin/my-cool-model v1.0
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-model

وسم نموذج عند إصدار محدد

إذا كنت ترغب في وضع علامة على إصدار محدد، يمكنك استخدام خيار --revision. بشكل افتراضي، سيتم إنشاء العلامة على الفرع main:

>>> hf repos tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-model

وسم مجموعة بيانات أو مساحة

إذا كنت ترغب في وضع وسم على مجموعة بيانات أو مساحة، فيجب عليك تحديد خيار --repo-type:

>>> hf repos tag create bigcode/the-stack v1.0 --repo-type dataset
You are about to create tag v1.0 on dataset bigcode/the-stack
Tag v1.0 created on bigcode/the-stack

قائمة الوسوم

لإدراج جميع الوسوم الخاصة بمستودع، استخدم أمر الفرع list (أو ls):

>>> hf repos tag list Wauplin/gradio-space-ci --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1

حذف وسم

لحذف وسم، استخدم أمر delete الفرعي:

>>> hf repos tag delete Wauplin/my-cool-model v1.0
You are about to delete tag v1.0 on model Wauplin/my-cool-model
Proceed? [Y/n] y
Tag v1.0 deleted on Wauplin/my-cool-model

يمكنك أيضًا تمرير -y لتخطي خطوة التأكيد.

hf env

يطبع الأمر hf env تفاصيل حول إعداد جهازك. وهذا مفيد عند فتح مشكلة على GitHub لمساعدة المشرفين على التحقيق في مشكلتك.

>>> hf env

Copy-and-paste the text below in your GitHub issue.

- huggingface_hub version: 1.0.0.rc6
- Platform: Linux-6.8.0-85-generic-x86_64-with-glibc2.35
- Python version: 3.11.14
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Running in Google Colab Enterprise ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- Installation method: unknown
- Torch: N/A
- httpx2: 2.0.0
- hf_xet: 1.1.10
- gradio: 5.41.1
- tensorboard: N/A
- pydantic: 2.11.7
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_STORED_TOKENS_PATH: /home/wauplin/.cache/huggingface/stored_tokens
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_DISABLE_XET: False
- HF_HUB_DISABLE_SHARED_BLOBS: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10

hf jobs

شغّل مهام الحساب على بنية Hugging Face التحتية بواجهة تشبه Docker مألوفة.

hf jobs هو أداة سطر أوامر تتيح لك تشغيل أي شيء على بنية Hugging Face التحتية (بما في ذلك وحدات GPU و TPU!) بأوامر بسيطة. فكّر في الأمر على أنه docker run، لكن لتشغيل الأكواد على وحدات A100.

لمراجعة عامة حول الوظائف والأسعار، راجع توثيق وظائف Hub. لاستخدام واجهة برمجة التطبيقات Python إلى جانب سطر الأوامر، راجع دليل تشغيل الوظائف وإدارتها.

# Directly run Python code
>>> hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")'

# Use GPUs without any setup
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(torch.cuda.get_device_name())"

# Run in an organization account
>>> hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'

# Run from Hugging Face Spaces
>>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'

# Run a Python script with `uv` (experimental)
>>> hf jobs uv run --name my-script my_script.py

يتوفر وظائف Hugging Face لأي مستخدم أو منظمة تمتلك رصيدًا مدفوعًا مسبقًا.

البدء السريع

1. تشغيل أول مهمة

# Run a simple Python script
>>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'

تشغّل هذه الأوامر المهمة وتعرض السجلات. يمكنك تمرير --detach لتشغيل المهمة في الخلفية وطباعة معرّف المهمة فقط. أضف -q لطباعة معرّف المهمة وحده، وهو أمر مفيد لالتقاطه في سكربت:

>>> JOB_ID=$(hf jobs run -dq python:3.12 python train.py)
>>> hf jobs wait "$JOB_ID"

2. التحقق من حالة المهمة

# List your running jobs
>>> hf jobs ls
# List all jobs
>>> hf jobs ls -a

# Inspect the status of a job
>>> hf jobs inspect <job_id>

# View logs from a job
>>> hf jobs logs <job_id>

# View resources usage stats and metrics of running jobs
>>> hf jobs stats
# View resources usage stats and metrics of some jobs
>>> hf jobs stats [job_ids]...
# Follow live stats until the jobs complete
>>> hf jobs stats -f [job_ids]...

# Cancel a job
>>> hf jobs cancel <job_id>

# Wait until one or more jobs finish (exit code 0 only if all jobs completed successfully)
>>> hf jobs wait <job_id> [<job_id>...]

# Wait for all currently running jobs
>>> hf jobs ls -q | xargs hf jobs wait

تخرج أوامر hf jobs run وhf jobs wait غير المنفصلة برمز غير صفري إذا فشل Job، مما يتيح لك ربط الأوامر باستخدام &&:

>>> hf jobs run python:3.12 python train.py && echo "training succeeded"

3. التشغيل على وحدة معالجة الرسوميات

يمكنك أيضًا تشغيل المهام على وحدات معالجة الرسوميات (GPUs) أو وحدات المعالجة المخصصة (TPUs) باستخدام خيار --flavor. على سبيل المثال، لتشغيل مهمة PyTorch على وحدة معالجة رسومات A10G:

# Use an A10G GPU to check PyTorch CUDA
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'

عند تشغيل هذا، ستظهر المخرجات التالية!

This code ran with the following GPU: NVIDIA A10G

استخدم -- لفصل خيارات Jobs عن الحُجج المُمرَّرة إلى أمر أو سكربت. لا تُفسِّر Jobs الخيارات التي تأتي بعد --.

>>> hf jobs run --flavor cpu-basic python:3.12 -- python --help

هذا كل شيء! أنت الآن تشغّل الكود على بنية Hugging Face التحتية.

حالات الاستخدام الشائعة

تدريب النماذج: ضبط النماذج الدقيقة أو تدريبها على وحدات معالجة الرسوميات (T4، A10G، A100) دون الحاجة إلى إدارة البنية التحتية
توليد البيانات الاصطناعية: توليد مجموعات بيانات واسعة النطاق باستخدام نماذج اللغة الكبيرة على أجهزة قوية
معالجة البيانات: معالجة مجموعات بيانات ضخمة باستخدام تكوينات عالية المعالجة المركزية للأحمال المتوازية
الاستدلال الدُفعي: تشغيل الاستدلال دون اتصال على آلاف العينات باستخدام إعدادات وحدات معالجة الرسوميات المُحسّنة
التجارب والمعايير: تشغيل تجارب تعلم الآلة على أجهزة متسقة للحصول على نتائج قابلة للتكرار
التطوير والتصحيح: اختبار كود GPU دون الحاجة إلى إعداد CUDA محلي

تمرير متغيرات البيئة والأسرار

يمكنك تمرير متغيرات البيئة إلى مهمتك باستخدام

# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass secrets by name - the value is read from your environment, never from the command line
>>> hf jobs run -s MY_SECRET python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'

# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs run --secrets-file .env.secrets python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'

# Or pipe them in, so the values touch neither the command line nor the disk
>>> printf 'MY_SECRET=psswrd\n' | hf jobs run --secrets-file - python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'

تُشفَّر الأسرار على جانب الخادم في جميع الأشكال الثلاثة. يعمل أيضًا -s MY_SECRET=psswrd، لكن القيمة ستنتهي في سجلّ shell لديك وفي قائمة العمليات (/proc/<pid>/cmdline على Linux)، لذلك يطبع CLI تحذيرًا إلى stderr عند استخدامه؛ احتفظ بهذا الشكل للقيم التي ليست حساسة حقًا. ينطبق الأمر نفسه على --token <value>: يُفضَّل استخدام hf auth login أو متغير البيئة HF_TOKEN. يجب أن يكون ملف البيئة أو الأسرار قابلًا للقراءة من قبلك فقط (chmod 600) — يحذّر CLI إذا لم يكن كذلك.

استخدم --secrets HF_TOKEN لتسليم رمز Hugging Face المحلي بشكل ضمني. مع هذه الصياغة، يتم استرجاع السر من متغير البيئة. بالنسبة إلى HF_TOKEN، قد يقرأ ملف الرمز الموجود في مجلد Hugging Face الرئيسي إذا لم يتم تعيين متغير البيئة.

متغيرات البيئة المدمجة

داخل حاوية المهمة، تتوفر متغيرات البيئة التالية تلقائيًا:

متغير	الوصف
`JOB_ID`	المعرّف الفريد للوظيفة الحالية. استخدم هذا للإشارة إلى الوظيفة برمجياً.
`ACCELERATOR`	نوع المُسرِّع المتاح (مثلًا `t4-medium`، `a10g-small`، `a100x4`). يكون فارغًا إذا لم يتوفر مُسرِّع.
`CPU_CORES`	عدد أنوية وحدة المعالجة المركزية المتاحة للعمل (مثلًا `2`، `4`، `8`).
`MEMORY`	الكمية من الذاكرة المتاحة للعمل (مثلًا `16Gi`، `32Gi`).

# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"

انتهاء مهلة المهام

تتمتع المهلات بوقت انقضاء افتراضي مدته 30 دقيقة، وبعد ذلك تتوقف تلقائيًا. للمهام طويلة الأمد مثل تدريب النماذج، اضبط وقت انقضاء مخصصًا باستخدام خيار --timeout:

# Set timeout in seconds (default unit)
>>> hf jobs run --timeout 7200 python:3.12 python train.py

# Use time units: s (seconds), m (minutes), h (hours), d (days)
>>> hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.py
>>> hf jobs run --timeout 90m python:3.12 python process_data.py
>>> hf jobs run --timeout 1.5h python:3.12 python train.py  # floats are supported

يعمل خيار --timeout أيضًا مع سكربتات UV والمهام المجدولة:

# UV script with timeout
>>> hf jobs uv run --timeout 2h training_script.py

# Scheduled job with timeout
>>> hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.py

إذا تجاوزت مهمّتك مهلة الانتهاء، فسيتم إنهاؤها تلقائيًا. اضبط دائمًا مهلة مناسبة مع هامش زمني للمهام طويلة الأمد لتجنّب إنهاء المهام بشكل غير متوقع.

إعادة المحاولة وإعادة تشغيل مهمة

--attempts يحدد الحد الأقصى لعدد المحاولات، بما في ذلك التشغيل الأول. يعمل مع Docker وUV والمهام المجدولة. إعادة تشغيل مهمة تبدأ مهمة جديدة بنفس المواصفات المحفوظة:

>>> hf jobs run --attempts 3 --detach python:3.12 python train.py
>>> hf jobs rerun <job_id>

يسمح عدد محاولات يساوي 3 بإجراء محاولتين لإعادة التشغيل كحد أقصى عند فشل المهمة. كما يعيد hf jobs rerun استخدام عدد المحاولات الأصلي. وكما هو الحال مع hf jobs run، فإنه يبث سجلات المهمة الجديدة حتى تكتمل. استخدم --detach للعودة فوراً.

الأجهزة

خيارات --flavor المتاحة:

وحدة المعالجة المركزية: cpu-basic, cpu-upgrade
وحدة معالجة الرسوميات: t4-small، t4-medium، l4x1، l4x4، a10g-small، a10g-large، a10g-largex2، a10g-largex4، a100-large
TPU: v5e-1x1، v5e-2x2، v5e-2x4

(تم التحديث في 07/2025 من وثائق suggested_hardware الخاصة بـ Hugging Face)

الأحجام

قم بتركيب وحدة تخزين على قرص المهمة باستخدام -v أو --volume.

يمكنك تثبيت أي مستودع على Hugging Face (نموذج/مجموعة بيانات/مساحة) أو حاوية تخزين باستخدام مخطط عنوان hf://. على سبيل المثال:

تثبيت مستودع نموذج: -v hf://openai/gpt-oss-120b:/model
تثبيت مستودع مجموعة بيانات: -v hf://datasets/HuggingFaceFW/fineweb:/data
تثبيت حاوية تخزين: -v hf://buckets/username/my-bucket:/mnt
تثبيت مساحة: -v hf://spaces/username/my-space:/app
تثبيت مجلد فرعي داخل مستودع: -v hf://datasets/org/ds/train:/data

ثم يمكنك استخدام المجلد المُثبَّت كمجلد محلي:

# Docker Job with a mounted volume as input
>>> hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \
...     duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"

# UV Job with a mounted volume to save checkpoints when training a model
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
...     sft.py --output-dir /training-outputs/training-v3-final ...

تُركَّب النماذج ومجموعات البيانات والمساحات دائمًا للقراءة فقط. أما حاويات التخزين فتكون للقراءة والكتابة افتراضيًا — وهذا مفيد بشكل خاص للبيانات التي تتغير بشكل متكرر، إذ يمكن تجاوز الملفات أو حذفها في مكانها.

استخدم :ro لتفعيل وضع القراءة فقط:

تثبيت حاوية تخزين للقراءة فقط: -v hf://buckets/username/my-bucket:/mnt:ro

تثبيت البيانات المحلية

يمكن أن يكون الجانب المصدر لـ -v أيضًا مجلدًا محليًا. يتم مزامنته أولًا مع jobs-artifacts الخاص بك Storage Bucket ثم يُركَّب مجلد الدلو الناتج في المهمة:

>>> hf jobs uv run -v ./my-data:/data process.py

يعمل إعادة تشغيل الأمر على رفع الملفات الجديدة أو المعدّلة فقط. تُركَّب المجلدات المحلية للقراءة فقط افتراضيًا. استخدم :rw للسماح للوظيفة بالكتابة إلى وحدة التخزين، على سبيل المثال لاستخراج المخرجات بعد اكتمال الوظيفة (يعمل المجلد المحلي الفارغ أيضًا):

>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py
...
Hint: Volume '/output' is mounted read-write. Once the job is over, pull back its data with:
  hf buckets sync hf://buckets/username/jobs-artifacts/md-out-a1b2c3d4 ./md-out

التسميات

أضِف تسميات إلى مهمة باستخدام -l أو --label. التسميات هي أزواج مفتاح=قيمة تُطبَّق بيانات وصفية على مهمة. لتسمية مهمة بتسميتين، كرر علم التسمية (-l أو --label):

>>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"

لا يحدد المفتاح my-label قيمة، لذا فإن قيمته الافتراضية هي سلسلة فارغة ("").

استخدم --name لإضافة تسمية name عند إنشاء مهمة. تُسهّل التسميات العثور على المهام وتحديد هويتها في واجهة المستخدم؛ وهي اختيارية ولا يتعين أن تكون فريدة. إذا لم تقم بتمرير --name، فسيتم اشتقاق اسم تلقائيًا من صورة Docker أو من السكربت، بالإضافة إلى تجزئة قصيرة للأمر ولإعدادات وقت التشغيل المُحلَّلة (النوع، مهلة الانتهاء، قيم البيئة، …)، بحيث ينتج عن نفس الإعداد دائمًا نفس الاسم (مثلًا python:3.12 foo --truc → python-3-12-1a2b3c4d). يؤدي تغيير أي إعداد إلى تغيير الاسم، حتى لو بقي الأمر كما هو. يمكنك أيضًا إعادة تسمية مهمة موجودة مسبقًا:

>>> hf jobs run --name training-v2 python:3.12 python train.py
>>> hf jobs labels <job_id> --name training-v2

استخدم --status و--label و--name في hf jobs ls لتصفية المهام. يقبل --status حالة واحدة أو أكثر، ويقبل --label أزواجًا بصيغة key=value، بينما --name اختصار لـ--label name=NAME. يجب أن تتطابق المهمة مع كل عامل تصفية حتى تُدرج في القائمة. كما يُعرض اسم المهمة في عمود مستقل باسم NAME:

# Show completed Jobs
>>> hf jobs ls -a --status completed

# Show running or scheduling Jobs
>>> hf jobs ls --status running,scheduling

# Show Jobs named `training-v2`
>>> hf jobs ls -a --name training-v2

# Show Jobs with the `model=Qwen3-06B` label
>>> hf jobs ls -a --label model=Qwen3-06B

# Combine filters: running Jobs labelled both `env=prod` and `team=ml`
>>> hf jobs ls --status running --label env=prod --label team=ml

يعرض hf jobs ps افتراضياً ما يصل إلى 100 مهمة لتجنب إرباك الطرفية. استخدم --limit لتغيير ذلك، أو --limit 0 لعرض جميعها:

# Show up to 500 Jobs
>>> hf jobs ps -a --limit 500

# Show all Jobs (no limit)
>>> hf jobs ps -a --limit 0

تفعيل منافذ المهمة

استخدم --expose لمنفذ محمي برمز وصول، و--expose-public لمنفذ يجب أن يسمح بالوصول دون مصادقة. يمكن تكرار كلا العلمين ودمجهما، ويعملان مع Docker وUV والمهام المجدولة.

# Start a Job with a public HTTP server
>>> hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000

# Replace the configuration on a running Job: port 8000 is private, 9000 is public
>>> hf jobs expose <job_id> 8000 --public 9000

# Close all exposed ports
>>> hf jobs expose <job_id> --clear

hf jobs expose يتلقى المنافذ المحمية برمز المصادقة كحجج موضعية، والمنافذ العامة عبر --public. يطبّق الأمر التغيير دون إعادة تشغيل المهمة. تُغلق المنافذ غير المدرجة في قائمة الاستبدال.

الدخول إلى مهمة عبر SSH

مرّر --ssh إلى hf jobs run (أو hf jobs uv run) لجعل حاوية المهمة قابلة للوصول عبر SSH، ثم اتصل باستخدام hf jobs ssh:

# Start a job with SSH enabled
>>> hf jobs run --ssh --detach python:3.12 sleep infinity

# Open an SSH session into it
>>> hf jobs ssh <job_id>

# Print the SSH command instead of running it
>>> hf jobs ssh <job_id> --dry-run

# Use a specific identity file
>>> hf jobs ssh <job_id> -i ~/.ssh/id_ed25519

يُسمح فقط للمستخدمين الذين لديهم صلاحية الكتابة في مساحة الاسم الخاصة بالمهمة (صاحب المهمة، أو أعضاء المنظمة المالكة) بالدخول، وذلك عبر المصادقة بمفتاح SSH عام مسجّل في https://huggingface.co/settings/keys.

مجموعات الشبكات

مرّر --network-group <name> إلى hf jobs run (أو hf jobs uv run) للسماح للمهام (Jobs) الموجودة في نفس مساحة الاسم ومجموعة الموارد بالتواصل مع بعضها البعض على جميع المنافذ. داخل كل عضو، يُحلّ $HF_NETWORK_GROUP_HOSTNAME إلى كل مهمة في المجموعة، بينما يُحلّ ${HF_NETWORK_GROUP_PREFIX}<alias> إلى الأعضاء الذين ادّعوا مستعارًا (alias) باستخدام --network-alias <alias>:

# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000

# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'

يمكن حلّ الأعضاء قبل أن يصبحوا جاهزين، لذا اربط مع إعادة المحاولة. أسماء المجموعات والرموز المستعارة هي أحرف صغيرة وأرقام وشرطات، بحد أقصى 46 و34 حرفًا على التوالي.

UV السكربتات (تجريبي)

شغّل سكربتات UV (سكربتات بايثون تتضمن تبعياتها بشكل مضمّن) على بنية HF التحتية. سكربتات UV هي سكربتات بايثون تتضمن تبعياتها مباشرةً داخل الملف باستخدام صيغة تعليق خاصة.

# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py

# Run with persistent repo
>>> hf jobs uv run --repo my-uv-scripts my_script.py

# Run with GPU
>>> hf jobs uv run --flavor t4-small ml_training.py

# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet

# Add dependencies
>>> hf jobs uv run --with transformers --with torch train.py

# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py

# Run a command
>>> hf jobs uv run --with lighteval python -c 'import lighteval'

تُعدّ سكربتات UV سكربتات بلغة بايثون تتضمن تبعياتها مباشرةً داخل الملف باستخدام صيغة تعليق خاصة. وهذا يجعلها مثالية للمهام المستقلة التي لا تتطلب إعدادات مشاريع معقدة. لمعرفة المزيد حول سكربتات UV، راجع وثائق UV.

استخدم -- لتمرير الخيارات المتعارضة إلى سكربت الخاص بك. هنا، يصل --help إلى train.py بدلاً من عرض مساعدة Jobs:

>>> hf jobs uv run --flavor t4-small train.py -- --help

وينطبق هذا أيضًا على أعلام التنسيق: تستهلك hf jobs run وhf jobs uv run ومتغيراتهما scheduled الأعلام --format و--json و-q أينما ظهرت، لذا استخدم -- عندما يحتاج سكربتك إليها.

أرسل إعدادات الإطلاق مع السكربت

تعمل بعض السكربتات بشكل صحيح فقط على بيئة تشغيل محددة: صورة معينة، أو نوع معيّن من وحدات معالجة الرسوميات (GPU)، أو مُفسِّر نظام، وما إلى ذلك. يمكن أن يحمل السكربت تلك الإعدادات معه في جدول اختياري [tool.hf-jobs] داخل ترويسة PEP 723 الخاصة به:

# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# name    = "unlimited-ocr"
# image   = "vllm/vllm-openai:unlimited-ocr"
# flavor  = "l4x1"
# python  = "/usr/bin/python3"
# timeout = "2h"
# env     = { PYTHONPATH = "/usr/local/lib/python3.12/dist-packages", BATCH_SIZE = "64" }
# secrets = ["HF_TOKEN"]
# labels  = { task = "ocr" }
# volumes = ["hf://datasets/org/pdfs:/input"]
# ///

hf jobs uv run ocr.py in_ds out_ds ثم يُشغَّل بالبيئة التشغيلية الصحيحة، بدلاً من التشغيل الصامت على صورة CPU بمفسّر غير مناسب. الجدول غير مرئي لـ uv run العادي: جداول [tool.*] جزء من PEP 723 وتتجاهل الأدوات الجداول التي لا تملكها.

المفاتيح المدعومة، وكلها اختيارية: image، flavor، python، timeout، name، namespace، env، secrets، labels، volumes، network_group وnetwork_aliases. تُطابَق هذه المفاتيح مع الأعلام التي تحمل نفس الاسم (name يُخزَّن كوسم name، وvolumes يتقبل مواصفات hf://...:/MOUNT_PATH نفسها التي يتقبلها -v، وnetwork_aliases هو قائمة من قيم --network-alias). أي مفتاح غير معروف يُعد خطأً بدلاً من أن يكون نية تُهمل بصمت — فخطأ إملائي مثل flavour هو بالضبط الفشل الذي وُجدت هذه الميزة من أجل منعه.

يجب أن تكون جميع القيم نصوصاً، بما في ذلك قيم env وlabels: يُترجم -e BATCH_SIZE=64 إلى env = { BATCH_SIZE = "64" }، وليس env = { BATCH_SIZE = 64 } (يقرأ TOML القيمة الأخيرة كعدد صحيح ويُرفض الجدول). الاستثناء الوحيد هو timeout، الذي يقبل أيضاً عدداً صحيحاً بالثواني (timeout = 7200 هو نفسه timeout = "2h").

القيم الواردة من السكربت هي قيم افتراضية: فالحرف الصريح يفوز دائمًا، وتتم دمج env وsecrets وlabels وvolumes عنصرًا بعنصر، بحيث يمكن لـ-e و-v إضافة إلى ما يصرّح به السكربت:

# Same script, on bigger hardware, with one extra env var
>>> hf jobs uv run --flavor a10g-large -e BATCH_SIZE=64 ocr.py in_ds out_ds

network_aliases هو الاستثناء: فالتعليقات التي يدّعيها Job تشكّل مجموعة، لذا يستبدل --network-alias قائمة السكربت بدلاً من الإضافة إليها. ولا تمتلك Jobs المجدولة أي مجموعة شبكة على الإطلاق، لذلك يرفض hf jobs scheduled uv run أي سكربت يُعلن عن network_group أو network_aliases.

secrets يعرض أسماء الأسرار names فقط: فالقيم تأتي دائمًا من بيئة الشخص الذي يشغّل السكربت، وليس من السكربت نفسه (HF_TOKEN يُحلّ أيضًا من hf auth login). إذا طُلب سرّ غير مُعيَّن محليًا، فسيُنتج خطأً، بدلاً من أن يستقبل Job قيمة فارغة بصمت. عند استخدام --dry-run، يُعرض بدلاً من ذلك على شكل <not set>، بحيث تبقى إعدادات السكربت الذي لم تُجهَّز أسرارُه بعد مرئية.

تعيد كل عملية تشغيل صدى الإعدادات التي تُرسلها، مع تحديد القيم القادمة من السكربت. استخدم --dry-run لطباعتها دون إطلاق أي شيء:

>>> hf jobs uv run --dry-run --flavor a10g-large ocr.py in_ds out_ds
Warning: The script's [tool.hf-jobs] table requests HF_TOKEN: the value(s) from your local environment would be sent to the Job.
Job configuration:
  script   ocr.py
  args     in_ds out_ds
  image    vllm/vllm-openai:unlimited-ocr (from script)
  flavor   a10g-large
  python   /usr/bin/python3 (from script)
  timeout  2h (from script)
  env      PYTHONPATH=/usr/local/lib/python3.12/dist-packages (from script)
           BATCH_SIZE=64 (from script)
  secrets  HF_TOKEN=*** (from script)
  volumes  hf://datasets/org/pdfs:/input (from script)
  labels   task=ocr (from script)
           name=unlimited-ocr (from script)
(dry run) Job not submitted.

يعمل هذا أيضًا مع السكربتات الموجودة خلف عنوان URL: يتم تنزيل السكربت مرة واحدة عند إرسال المهمة (Job) (لقراءة ترويسته) ثم يُرسل إلى المهمة (Job) كما لو كان سكربتًا محليًا، بدلاً من أن يتم تنزيله مرة أخرى بواسطة الحاوية. يجب أن يكون العنوان URL قابلًا للوصول من جهازك. وبالمثل مع السكربتات المحلية، تستخدم سكربتات URL نقطة تركيب المخرجات المحجوزة /data؛ استخدم مسار تركيب آخر لمجموعات الإدخال الخاصة بك.

في حالة hf jobs scheduled uv run، تُثبّت هذه الخاصية السكربت على محتواه وقت الإنشاء. لم يعد تحديث عنوان المصدر (URL) يغيّر التشغيلات المستقبلية: أعد إنشاء المهمة المجدولة (Job) لاستيعاب إصدار جديد.

--dry-run متاح أيضًا في hf jobs run وhf jobs scheduled run وhf jobs scheduled uv run. يتخطى هذا الخيار عملية الإرسال ورفع أحجام التخزين المحلية. تتضمن الأسماء المولّدة تلقائيًا لكل من مهام Docker ومهام UV إعدادات الإقلاع المُحلَّلة، لذا فإن تغيير إعدادات وقت التشغيل أو قيم البيئة يؤدي إلى تغيير الاسم.

hf jobs scheduled

جدولة وإدارة المهام التي ستُنفَّذ على بنية HF التحتية.

يجب أن يكون الجدول الزمني أحد @annually، @yearly، @monthly، @weekly، @daily، @hourly، أو تعبير جدولة CRON (مثل "0 9 * * 1" للساعة 9 صباحاً كل يوم اثنين).

# Schedule a job that runs every hour
>>> hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'

# Use the CRON syntax
>>> hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'

# Schedule with GPU
>>> hf jobs scheduled run @hourly --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'

# Schedule a UV script
>>> hf jobs scheduled uv run @hourly --name hourly-script my_script.py

استخدم نفس المعلمات الموجودة في hf jobs run لتسليم متغيرات البيئة والأسرار والوقت المحدد وما إلى ذلك.

إدارة المهام المجدولة باستخدام

# List your active scheduled jobs
>>> hf jobs scheduled ls

# Same filters as `hf jobs ls`: --status, --label and --name
>>> hf jobs scheduled ls --all
>>> hf jobs scheduled ls --status suspended
>>> hf jobs scheduled ls --name hourly-task --label env=prod

# Inspect the status of a job
>>> hf jobs scheduled inspect <scheduled_job_id>

# Suspend (pause) a scheduled job
>>> hf jobs scheduled suspend <scheduled_job_id>

# Resume a scheduled job
>>> hf jobs scheduled resume <scheduled_job_id>

# Change future run times (Mondays at 9:00)
>>> hf jobs scheduled reschedule <scheduled_job_id> "0 9 * * 1"

# Trigger a scheduled job to run right now (does not change the schedule)
>>> hf jobs scheduled trigger <scheduled_job_id>

# Delete a scheduled job
>>> hf jobs scheduled delete <scheduled_job_id>

hf sandbox

hf sandbox يُشغّل أجهزة سحابية معزولة مبنية على Jobs: أنشئ جهازًا، ونفّذ أوامر مع بث مباشر للمخرجات، وانسخ الملفات إليه ومنه. تعمل أي صورة Docker تحتوي على /bin/sh. راجع دليل Sandboxes لواجهة Python البرمجية، والدليل المفاهيمي لفهم آلية العمل الداخلية.

البيئات المعزولة تجريبية، وقد تتغير واجهات برمجياتها وسلوكها دون إشعار مسبق. البيئات المعزولة المشتركة مخصصة للأحمال العاملة ضمن نطاق ثقة واحد؛ استخدم بيئة معزولة مخصصة للأحمال التي لا تثق ببعضها البعض.

# Create a sandbox (waits until it is ready, prints its id)
>>> hf sandbox create
✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s

# Attach labels to the underlying Job
>>> hf sandbox create --label controller-run=run-42 --label team=data-infra

# Run commands inside it (output is streamed, exit code is propagated)
>>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')"
hi

# Copy files in and out (docker-style)
>>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv
>>> hf sandbox cp 687f911eaea852de79c4a50a:/app/results.json results.json

# Terminate a sandbox
>>> hf sandbox kill 687f911eaea852de79c4a50a

استخدم --flavor لاختيار العتاد (مثل a10g-small)، و--idle-timeout لتحديد مدة صلاحية بيئة العزل، و-l / --label لإرفاق تسميات بمهمة Job الخاصة بها. ولتوزيع العديد من بيئات العزل الرخيصة المعتمدة على المعالج، قم بتسخين مجموعة باستخدام hf sandbox pool create ثم أنشئ بيئات داخلها باستخدام hf sandbox create --pool <id> (راجع دليل بيئات العزل).

تمرير متغيرات البيئة والأسرار إلى بيئة معزولة

يوجد قناتان منفصلتان، بخصائص تخزين مختلفة:

قناة	أعلام	بيئة معزولة مخصصة	صندوق رمل مجمّع (`--pool`)
بيئة	`-e` / `--env`, `--env-file`	المُخزَّنة في بيانات وصفية للعمل	تُسلَّم إلى المضيف عند الإنشاء، ولا تُخزَّن في بيانات وصفية المهمة
secrets	`-s` / `--secrets`, `--secrets-file`	مشفّر على جانب الخادم	غير متوفر — استخدم `--env`

# Plain environment variables
>>> hf sandbox create -e LOG_LEVEL=debug --env-file .env

# Secrets, read from your environment by name (nothing sensitive on the command line)
>>> hf sandbox create -s OPENAI_API_KEY -s HF_TOKEN

# Secrets from a file, or piped in on stdin
>>> hf sandbox create --secrets-file .env.secrets
>>> printf 'OPENAI_API_KEY=sk-...\n' | hf sandbox create --secrets-file -

يعمل -s KEY=value أيضًا، لكن القيمة ستظهر في سجلّ shell وفي قائمة العمليات، لذا يحذّر CLI من ذلك على stderr، بما في ذلك في الوضع الهادئ. ترفض بيئات sandbox المجمّعة --secrets بشكل قاطع: فالجمع لا يحتوي على قناة للأسرار المشفّرة، ويؤدي hf sandbox create --pool <id> -s KEY=value إلى خطأ مع إشارة إلى --env.

hf webhooks

hf webhooks يتيح لك إدارة الخطافات (webhooks) على Hugging Face Hub مباشرةً من سطر الأوامر. تتيح لك الخطافات الاستماع إلى الأحداث (مثل عمليات الدفع push، والمناقشات، وغيرها) في المستودعات أو المستخدمين أو المنظمات، ثم تشغيل إجراءات — إما عبر إرسال طلب إلى عنوان URL عن بُعد، أو عبر تشغيل مهمة (Job) على بنية Hugging Face التحتية.

قائمة الخطافات

>>> hf webhooks ls
ID           URL                                DISABLED  DOMAINS  WATCHED
wh-abc123    https://example.com/hook            False     repo     model:bert-base-uncased
wh-def456    https://example.com/other-hook      False     repo     org:HuggingFace

استخدم --format json للحصول على مخرجات قابلة للقراءة آليًا، أو -q لطباعة المعرّفات فقط:

>>> hf webhooks ls --format json
>>> hf webhooks ls -q

الحصول على معلومات خطاف الويب

>>> hf webhooks info wh-abc123

يطبع تفاصيل Webhook كاملة بصيغة JSON.

إنشاء خطاف ويب

أنشئ خطاف ويب (webhook) يرسل حمولات (payloads) إلى عنوان URL:

>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased
>>> hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repo

أو أنشئ webhook يستدعي Job بدلاً من ذلك:

>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-c

لا يتم نسخ أسرار مهمة المصدر إلى خطاف الويب. استخدم --secrets أو --secrets-file (بنفس الصيغة المستخدمة في hf jobs run) لتسليمها إلى المهمة المُفعَّلة. على سبيل المثال، --secrets HF_TOKEN يمرر رمز Hugging Face المحلي الخاص بك:

>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKEN

تستخدم الخطة --watch التنسيق type:name حيث يكون type أحد model أو dataset أو space أو bucket أو org أو user. يمكن تكرارها لمراقبة عدة عناصر. استخدم --domain لتصفية الأحداث إلى repo أو discussion، و--secret لضبط سر التوقيع.

تحديث خطاف ويب

>>> hf webhooks update wh-abc123 --url https://new-url.com/hook
>>> hf webhooks update wh-abc123 --watch model:gpt2 --domain repo

تُعدَّل الخيارات المُقدَّمة فقط. لاحظ أن --watch يستبدل قائمة المراقبة بالكامل عند تحديده.

لتحديث أسرار خطاف الويب (webhook) المرتبط بمهمة (Job)، مرّر --job-id مع --secrets. تُستبدل الأسرار المذكورة بالقيم المخزنة وتُحفظ جميع الأسرار الأخرى:

>>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKEN

تفعيل / تعطيل خطاف ويب

>>> hf webhooks enable wh-abc123
>>> hf webhooks disable wh-abc123

حذف خطاف ويب

>>> hf webhooks delete wh-abc123
Are you sure you want to delete webhook 'wh-abc123'? [y/N]: y
Webhook deleted: wh-abc123

استخدم --yes لتخطي مطالبة التأكيد:

>>> hf webhooks delete wh-abc123 --yes

تقبل جميع الأوامر --token لتجاوز المصادقة. استخدم --help مع أي أمر لعرض جميع الخيارات.

hf endpoints

استخدم hf endpoints لعرض نقاط الاستدلال ونشرها ووصفها وإدارتها مباشرةً من الطرفية. ولا يزال الاسم المستعار القديم hf inference-endpoints متاحًا من أجل التوافق.

# Lists endpoints in your namespace
>>> hf endpoints ls

# List the hardware you can deploy on
>>> hf endpoints hardware

# Deploy an endpoint from Model Catalog
>>> hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpoint

# Deploy an endpoint from the Hugging Face Hub
>>> hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl

# List catalog entries
>>> hf endpoints catalog ls

# Show status and metadata
>>> hf endpoints describe my-endpoint

# Pause the endpoint
>>> hf endpoints pause my-endpoint

# Delete without confirmation prompt
>>> hf endpoints delete my-endpoint --yes

أضف --namespace لاستهداف منظمة، و--token لتجاوز المصادقة.

ابحث عن أجهزة لتوزيع عليها

يتطلب hf endpoints deploy خمسة أعلام للأجهزة (--vendor، --region، --accelerator، --instance-type و--instance-size). يعرض hf endpoints hardware التوليفات الصالحة، مع سعر الساعة لكل نسخة بالدولار الأمريكي وحصة المعالج الخاص بمساحة الاسم الخاصة بك:

>>> hf endpoints hardware --vendor aws --region eu-west-1
VENDOR REGION    ACCELERATOR INSTANCE_TYPE INSTANCE_SIZE MEMORY_GB GPU_MEMORY_GB PRICE_PER_HOUR QUOTA STATUS
------ --------- ----------- ------------- ------------- --------- ------------- -------------- ----- ---------
aws    eu-west-1 cpu         intel-spr     x1                  2.0                        0.033 0/60  available
aws    eu-west-1 cpu         intel-spr     x2                  4.0                        0.067 0/60  available
aws    eu-west-1 cpu         intel-spr     x4                  8.0                        0.134 0/60  available
aws    eu-west-1 cpu         intel-spr     x8                 16.0                        0.268 0/60  available
aws    eu-west-1 cpu         intel-spr     x16                32.0                        0.536 0/60  available
aws    eu-west-1 gpu         nvidia-a10g   x1                 30.0            24            1.0 0/16  available
aws    eu-west-1 gpu         nvidia-t4     x1                 15.0            16            0.5 1/30  available
Hint: Deploy on one of these, e.g.: hf endpoints deploy my-endpoint --repo <repo> --framework <framework> --vendor aws --region eu-west-1 --accelerator cpu --instance-type intel-spr --instance-size x1

أعلام التصفية هي أعلام النشر (--vendor، --region، --accelerator، --instance-type)، لذا فإن ما تصفيه به هو ما تمرره إلى deploy. يتم سرد الأجهزة فقط التي يمكنك النشر عليها الآن: حالة قابلة للاستخدام، وحصص كافية من المعجلات المتبقية في مساحة الاسم الخاصة بك لنسخة واحدة. أضف --all لرؤية ما هو متقادم أو غير متاح مؤقتًا أو خارج الحصص أيضًا. يضيف --format json المواصفات المتبقية لكل نسخة (وحدات المعالجة المركزية الافتراضية، البنية، عدد المعجلات) إلى كل إدخال.

الحصة تُحسب لكل مساحة أسماء (namespace) على حدة، وهي التي تحدد الصفوف التي ستُعرض أصلًا. إذا كنت تنشر داخل منظمة، فمرّر نفس --namespace الذي ستمرره إلى deploy — وإلا فأنت تنظر إلى حصتك الشخصية، والتي قد تخفي أجهزة يمكن للمنظمة النشر عليها، كما قد تعرض أجهزة لا تستطيع النشر عليها.

نشر حاوية مخصصة

لنشر صورة Docker خاصة بك بدلاً من صورة مُدارة من Hugging Face، مرّر --framework custom مع --custom-image. يتم تركيب مستودع النموذج في /repository داخل الحاوية. استخدم --container-args (وإختياريًا --container-command) لتمرير سلسلة إطلاق محاطة بعلامات اقتباس، و--env/--secrets لحقن متغيرات البيئة، و--type لضبط نوع الوصول (public أو authenticated أو private):

>>> hf endpoints deploy nex-n2-pro \
      --repo nex-agi/Nex-N2-Pro \
      --framework custom \
      --accelerator gpu --vendor aws --region us-east-1 \
      --instance-type nvidia-h200 --instance-size x8 \
      --custom-image nexagi/sglang:v0.5.12 \
      --health-route /health --port 30000 \
      --container-args "--reasoning-parser qwen3 --tool-call-parser qwen3_coder --mamba-scheduler-strategy extra_buffer --tp 8" \
      --env MODEL_ID=/repository \
      --type authenticated

لا تقتصر --container-args و--container-command على الصور المخصصة فحسب: فهي تتوافق مع model.args وmodel.command في حمولة الواجهة البرمجية، والتي تنطبق أيضًا على الصور المُدارة. في نقطة نهاية موجودة مسبقًا، تحل هاتان العلمتان محل القيمة الحالية بدلاً من الإضافة إليها، لذا مرر القائمة الكاملة التي تريدها واستخدم سلسلة فارغة لمسحها. تأتي نقاط النهاية المنفذة من الكتالوج بالفعل مع أعلام محرك مُضبوطة، لذا تحقق من hf endpoints describe قبل تجاوزها:

>>> hf endpoints update my-endpoint \
      --container-args "--enable-auto-tool-choice --tool-call-parser lfm2"

نشر صورة محرك مُدار

استخدام --custom-image بمفرده ينشر حاوية اختيارية. أضف --engine لتشغيلها كأحد المحركات التي تديرها الواجهة البرمجية (vllm، sglang، tgi، tei، llamacpp، hf-serve، …)، مما يتيح إعدادات ذلك المحرك، بما في ذلك --tensor-parallel-size و--data-parallel-size. يعتمد vLLM وSGLang على معالج تسريع واحد افتراضيًا بينما يحصل نقطة النهاية على كل معالجات التسريع في مثيلها، لذا فإن ترك كلا الإعدادين غير مضبوط سيؤدي إلى تحميل النموذج على معالج واحد وترك البقية خاملة مع الاستمرار في الإبلاغ عن الحالة الصحية، ولهذا السبب ترفض الواجهة البرمجية الآن هذا التكوين:

>>> hf endpoints deploy gpt-oss-120b-vllm \
      --repo openai/gpt-oss-120b \
      --framework custom \
      --accelerator gpu --vendor aws --region us-east-1 \
      --instance-type nvidia-h200 --instance-size x8 \
      --engine vllm --custom-image vllm/vllm-openai:v0.23.0 \
      --tensor-parallel-size 8

هذا ليس هو نفسه --container-args "... --tp 8" المذكور أعلاه: فـ--tensor-parallel-size يُكتب في إعدادات model.image للمحرك، وهو ما تتحقق منه الواجهة البرمجية مقابل عدد معالجات التسريع في المثيل، بينما --container-args يُلحق علمًا بسطر الأوامر فقط. استخدم --container-args لأعلام المحرك التي لا تملك حقل صورة، ولحاويات مخصصة بسيطة لا تملك حقول توازٍ.

لإعادة ضبط نقطة نهاية قيد التشغيل، مرّر الأحجام بشكل منفصل. يُرسل model.image كوحدة كاملة ويتطلب url، لذا يتم جلب الصورة الحالية لنقطة النهاية وتحديثها في مكانها:

>>> hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2

hf endpoints update يقبل أيضًا --custom-image و--engine، وهي الطريقة الوحيدة لتغيير صورة نقطة النهاية من سطر الأوامر. تستبدل هذه المسار model.image بدلاً من تعديله، لذا شغّل hf endpoints describe أولاً ثم مرّر ما تريد الاحتفاظ به.

hf endpoints catalog

استخدم hf endpoints catalog للتفاعل مع كتالوج نماذج نقاط الاستدلال. انشر النماذج مباشرةً من الكتالوج مع إعدادات مُحسَّنة.

يأتي كل نموذج في الكتالوج مع وصفة أو أكثر recipes: وهي مجموعة من العتاد ومحرك الاستدلال التي تم اختبارها لهذا النموذج. يطبع الأمر hf endpoints catalog ls صفًا واحدًا لكل وصفة، لذا فإن النموذج الذي يحتوي على وصفة للوحات GPU وأخرى للوحات Neuron سيظهر مرتين:

# List available catalog models
>>> hf endpoints catalog ls
REPO_ID                             TASK               LICENSE    ACCELERATOR ENGINE   GGUF_FILE                     RECIPE_ID
----------------------------------- ------------------ ---------- ----------- -------- ----------------------------- -------------------------
meta-llama/Llama-3.1-8B-Instruct    text-generation    Llama 3.1  gpu         vllm                                   sizzling-biryani-g4xsi1ac
meta-llama/Llama-3.1-8B-Instruct    text-generation    Llama 3.1  neuron      vllmNeuron                             artisanal-quinoa-yz9ynamx
bartowski/QwQ-32B-Preview-GGUF      text-generation    Apache 2.0 gpu         llamacpp QwQ-32B-Preview-Q8_0.gguf     baked-orange-m863gx7d

# Narrow it down
>>> hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10

--accelerator و--engine و--license و--task و--search و--limit كلها تُفلتر على جانب الخادم.

# Deploy the default recipe of a model
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct

# Deploy an exact recipe listed above
>>> hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamx

# Deploy with a custom name
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct --name my-llama-endpoint

مع --repo، يمكن تضييق نطاق الوصفة الافتراضية باستخدام --accelerator (cpu، gpu، neuron) و--gguf-file (للنماذج التي تحتوي على وصفة واحدة لكل عملية تكميم). يتم رفض كلا الخيارين معًا مع --recipe، الذي يحدد وصفة واحدة بالفعل.

Update on GitHub

←الدلاء إنشاء امتداد لسطر الأوامر→