Hugging Face's logo

Hub Python Library documentation

عميل HfApi

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

عميل HfApi

فيما يلي توثيق لفئة HfApi، والتي تعمل كغلاف بلغة بايثون لواجهة برمجة التطبيقات الخاصة بـ Hugging Face Hub.

جميع الطرق من HfApi متاحة أيضًا مباشرةً من جذر الحزمة. وتُفصَّل كلا الطريقتين أدناه.

يُعد استخدام طريقة الجذر أكثر مباشرة، لكن فئة HfApi تمنحك مرونة أكبر. على وجه التحديد، يمكنك تمرير رمز (token) يُعاد استخدامه في جميع استدعاءات HTTP. وهذا يختلف عن hf auth login أو login() لأن الرمز لا يُحفظ على الجهاز. كما يمكن توفير نقطة نهاية (endpoint) مختلفة أو تكوين وكيل مستخدم (user-agent) مخصص.

from huggingface_hub import HfApi, list_models

# Use root method
models = list_models()

# Or configure a HfApi client
hf_api = HfApi(
    endpoint="https://huggingface.co", # Can be a Private Hub endpoint.
    token="hf_xxx", # Token is not persisted on the machine.
)
models = hf_api.list_models()

HfApi

فئة huggingface_hub.HfApi

< >

( endpoint: str | None = Nonetoken: str | bool | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = None )

المعاملات

  • endpoint (str، اختياري) — نقطة النهاية الخاصة بـ Hub. القيمة الافتراضية هي https://huggingface.co.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • library_name (str، اختياري) — اسم المكتبة التي تُرسل طلب HTTP. سيُضاف إلى ترويسة user-agent. مثال: "transformers".
  • library_version (str، اختياري) — إصدار المكتبة التي تُرسل طلب HTTP. سيُضاف إلى ترويسة user-agent. مثال: "4.24.0".
  • user_agent (str، dict، اختياري) — معلومات وكيل المستخدم على شكل قاموس أو سلسلة نصية واحدة. سيتم استكمالها بمعلومات حول الحزم المثبتة.
  • headers (dict، اختياري) — رؤوس إضافية تُرسل مع كل طلب. مثال: {"X-My-Header": "value"}. تتمتع الرؤوس المُمررة هنا بأولوية أعلى من الرؤوس الافتراضية.

عميل للتفاعل مع Hugging Face Hub عبر HTTP.

يتم تهيئة العميل ببعض الإعدادات عالية المستوى المستخدمة في جميع الطلبات المرسلة إلى Hub (نقطة نهاية HF، المصادقة، وكلاء المستخدم…). يُفضَّل استخدام عميل HfApi لكنه ليس إلزاميًا، إذ تُعرَض جميع طرقه العامة مباشرةً في جذر huggingface_hub.

accept_access_request

< >

( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي تريد قبول طلب الوصول إليه.
  • user (str، اختياري) — اسم المستخدم الذي يجب قبول طلب الوصول الخاص به. يجب تقديم واحد فقط من user أو request_id.
  • request_id (str، اختياري) — المعرّف الخاص بطلب الوصول الذي سيتم قبوله (انظر AccessRequest). مطلوب عندما يتم تكوين المستودع بحيث لا يُشارك أسماء المستخدمين للمقدمين للطلب. يجب تقديم واحد فقط من user أو request_id.
  • repo_type (str، اختياري) — نوع المستودع الذي يُقبل طلب الوصول إليه. يجب أن يكون أحد model أو dataset أو space. الافتراضي هو model.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 إذا لم يكن المستودع محميًا.
  • HfHubHTTPError — HTTP 403 إذا كان لديك وصول للقراءة فقط إلى المستودع. قد يحدث ذلك إذا لم تكن لديك دور write أو admin في المنظمة التي ينتمي إليها المستودع، أو إذا قمت بتمرير رمز read.
  • HfHubHTTPError — خطأ HTTP 404 إذا لم يكن المستخدم موجودًا على Hub.
  • HfHubHTTPError — HTTP 404 إذا تعذّر العثور على طلب وصول المستخدم.
  • HfHubHTTPError — HTTP 404 إذا كان طلب وصول المستخدم موجودًا بالفعل في قائمة المقبولين.

قبول طلب وصول من مستخدم لمتخزن محكوم محدد.

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

لمزيد من المعلومات حول المستودعات المُقيَّدة، راجع https://huggingface.co/docs/hub/models-gated.

add_collection_item

< >

( collection_slug: stritem_id: stritem_type: CollectionItemType_Tnote: str | None = Noneexists_ok: bool = Falsetoken: bool | str | None = None )

المعاملات

  • collection_slug (str) — اسم الرابط (Slug) للمجموعة المراد تحديثها. مثال: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_id (str) — Id of the item to add to the collection. Use the repo_id for repos/spaces/datasets, the paper id for papers, the slug of another collection (e.g. "moonshotai/kimi-k2") or a bucket id (e.g. "namespace/bucket-name").
  • item_type (str) — نوع العنصر المُضاف. يمكن أن يكون أحد "model"، "dataset"، "space"، "paper"، "collection" أو "bucket".
  • note (str، اختياري) — ملاحظة تُرفق بالعنصر في المجموعة. الحد الأقصى لحجم الملاحظة هو 500 حرف.
  • exists_ok (bool، اختياري) — إذا كان True، فلا ترفع خطأً إذا كان العنصر موجودًا بالفعل.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 403 إذا كان لديك وصول للقراءة فقط إلى المستودع. قد يحدث ذلك إذا لم تكن لديك دور write أو admin في المنظمة التي ينتمي إليها المستودع، أو إذا قمت بتمرير رمز read.
  • HfHubHTTPError — خطأ HTTP 404 إذا كان العنصر الذي تحاول إضافته إلى المجموعة غير موجود على Hub.
  • HfHubHTTPError — خطأ HTTP 409 إذا كان العنصر الذي تحاول إضافته إلى المجموعة موجودًا بالفعل في المجموعة (وكان exists_ok=False)

أضف عنصرًا إلى مجموعة على Hub.

يعيد: Collection

مثال:

>>> from huggingface_hub import add_collection_item
>>> collection = add_collection_item(
...     collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
...     item_id="pierre-loic/climate-news-articles",
...     item_type="dataset"
... )
>>> collection.items[-1].item_id
"pierre-loic/climate-news-articles"
# ^item got added to the collection on last position

# Add item with a note
>>> add_collection_item(
...     collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
...     item_id="datasets/climate_fever",
...     item_type="dataset",
...     note="This dataset adopts the FEVER methodology that consists of 1,535 real-world claims regarding climate-change collected on the internet."
... )
(...)

add_space_secret

< >

( repo_id: strkey: strvalue: strdescription: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم تحديثه. مثال: "bigcode/in-the-stack".
  • key (str) — المفتاح السري. مثال: "GITHUB_API_KEY"
  • value (str) — القيمة السرية. مثال: "your_github_api_key".
  • description (str، اختياري) — وصف السر. مثال: "Github API key to access the Github API".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يضيف أو يحدّث سراً في مساحة.

تتيح لك المفاتيح السرية تعيين مفاتيح أو رموز سرية لمساحة دون الحاجة إلى تضمينها في الكود. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

add_space_variable

< >

( repo_id: strkey: strvalue: strdescription: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم تحديثه. مثال: "bigcode/in-the-stack".
  • key (str) — مفتاح المتغير. مثال: "MODEL_REPO_ID"
  • value (str) — قيمة المتغير. مثال: "the_model_repo_id".
  • description (str) — وصف المتغير. مثال: "Model Repo ID of the implemented model".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يضيف متغيّرًا في مساحة أو يحدّثه.

تتيح المتغيرات تعيين متغيرات البيئة لمساحة دون الحاجة إلى ترميزها بشكل ثابت. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

auth_check

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = Nonewrite: bool = False )

المعاملات

  • repo_id (str) — المستودع الذي سيتم التحقق من الوصول إليه. يجب أن يكون التنسيق "user/repo_name". مثال: "user/my-cool-model".
  • repo_type (str، اختياري) — نوع المستودع. يجب أن يكون أحد "model" أو "dataset" أو "space". إذا لم يُحدد، فإن القيمة الافتراضية هي "model".
  • token (Union[bool, str, None]، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيُستخدم الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.
  • write (bool، اختياري) — إذا كان True، يتحقق مما إذا كان لدى المستخدم إذن كتابة المحتوى على المستودع. إذا كان False (الافتراضي)، يتحقق فقط من الوصول للقراءة.

يرفع

RepositoryNotFoundError أو GatedRepoError

  • RepositoryNotFoundError — تُستدعى إذا لم يكن المستودع موجودًا، أو كان خاصًا، أو لم يكن لدى المستخدم صلاحية الوصول. وقد يحدث ذلك إذا كان repo_id أو repo_type غير صحيح، أو إذا كان المستودع خاصًا لكن المستخدم غير مصادَق.

  • GatedRepoError — تُستدعى إذا كان المستودع موجودًا لكنه محمي (gated) ولم يكن للمستخدم صلاحية الوصول إليه.

تحقق مما إذا كان رمز المستخدم المُقدَّم لديه وصول إلى مستودع محدد على Hugging Face Hub.

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

مثال:

تحقق مما إذا كان لدى المستخدم صلاحية الوصول إلى مستودع:

>>> from huggingface_hub import auth_check
>>> from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError

try:
    auth_check("user/my-cool-model")
except GatedRepoError:
    # Handle gated repository error
    print("You do not have permission to access this gated repository.")
except RepositoryNotFoundError:
    # Handle repository not found error
    print("The repository was not found or you do not have access.")

في هذا المثال:

  • إذا كان للمستخدم صلاحية الوصول، فإن الطريقة تكتمل بنجاح.
  • إذا كان المستودع محميًا أو غير موجود، تُثار استثناءات مناسبة، مما يتيح للمستخدم التعامل معها وفقًا لذلك.

batch_bucket_files

< >

( bucket_id: stradd: list[tuple[str | Path | bytes, str]] | None = Nonecopy: list[tuple[str, str, str, str]] | None = Nonedelete: list[str] | None = Nonetoken: str | bool | None = None )

المعاملات

  • bucket_id (str) — معرّف الدلو (مثلًا "username/my-bucket").
  • add (list of tuple, اختياري) — الملفات المراد رفعها. كل عنصر هو (source, destination) حيث source هو مسار إلى ملف محلي (str أو Path) أو محتوى خام bytes، وdestination هو المسار داخل الدلو.
  • copy (list من tuple, اختياري) — الملفات التي سيتم نسخها عبر xet hash. كل عنصر هو (source_repo_type, source_repo_id, xet_hash, destination) tuple حيث:
    • source_repo_type هو نوع المستودع المصدر: "model"، "dataset"، "space"، أو "bucket".
    • source_repo_id هو معرّف المستودع أو الدلو المصدر (مثل "username/my-model").
    • xet_hash هو تجزئة xet للملف الذي سيتم نسخه.
    • destination هو مسار الوجهة داخل الدلو. هذه عملية جانب الخادم — لا يتم تنزيل البيانات أو إعادة رفعها.
  • delete (list of str, اختياري) — مسارات الملفات التي سيتم حذفها من الدلو.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

BucketBatchError

  • BucketBatchError — إذا أبلغ الخادم عن فشل بعض العمليات. يتم رفع الخطأ مرة واحدة بعد إرسال كل عملية، مما يعني أن العمليات الأخرى في الدفعة قد تم تطبيقها.

أضِف ملفات وانسخها و/أو احذفها في الدلو.

هذه عملية غير معاملة. إذا حدث خطأ أثناء العملية، فقد تكون بعض الملفات قد تم رفعها أو نسخها أو حذفها بينما لم يتم ذلك لبقية الملفات.

مثال:

>>> from huggingface_hub import batch_bucket_files

# Upload files
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         ("./model.safetensors", "models/model.safetensors"),
...         (b'{{"key": "value"}}', "config.json"),
...     ],
... )

# Copy xet files from another bucket or repo (server-side, no data transfer)
>>> batch_bucket_files(
...     "username/my-bucket",
...     copy=[
...         ("bucket", "username/source-bucket", "<xethash_1>", "models/model.safetensors"),
...         ("model", "username/my-model", "<xethash_2>", "models/config.safetensors"),
...     ],
... )

# Delete files
>>> batch_bucket_files("username/my-bucket", delete=["old-model.bin"])

# Upload and delete in one batch
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[("./new.txt", "new.txt")],
...     delete=["old.txt"],
... )

bucket_info

< >

( bucket_id: strtoken: bool | str | None = None ) → BucketInfo

المعاملات

  • bucket_id (str) — معرّف الدلو (مثلًا "username/my-bucket").
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

BucketInfo

معلومات الدلو.

يرفع

BucketNotFoundError أو or

  • BucketNotFoundError — إذا تعذّر العثور على الدلو. قد يكون السبب عدم وجوده،
  • or — لأنه مُعيَّن على private ولا تملك صلاحية الوصول إليه.

احصل على معلومات حول دلو (bucket) محدد على Hub.

مثال:

>>> from huggingface_hub import bucket_info
>>> info = bucket_info(bucket_id="Wauplin/first-bucket")
>>> info.id
'Wauplin/first-bucket'
>>> info.private
False
>>> info.created_at
datetime.datetime(2026, 2, 6, 17, 37, 57, tzinfo=datetime.timezone.utc)
>>> info.size
551879671
>>> info.total_files
12

إلغاء طلب الوصول

< >

( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي تريد إلغاء طلب الوصول إليه.
  • user (str، اختياري) — اسم المستخدم الذي يجب إلغاء طلب الوصول الخاص به. يجب تقديم بالضبط واحد من user أو request_id.
  • request_id (str, اختياري) — معرّف طلب الوصول الذي يجب إلغاؤه (انظر AccessRequest). مطلوب عندما يتم تكوين المستودع بحيث لا يُشارك أسماء مستخدمي مقدمي الطلبات. يجب تقديم واحد فقط من user أو request_id.
  • repo_type (str، اختياري) — نوع المستودع الذي تريد إلغاء طلب الوصول إليه. يجب أن يكون أحد model أو dataset أو space. القيمة الافتراضية هي model.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 إذا لم يكن المستودع محميًا.
  • HfHubHTTPError — HTTP 403 إذا كان لديك وصول للقراءة فقط إلى المستودع. قد يحدث ذلك إذا لم تكن لديك دور write أو admin في المنظمة التي ينتمي إليها المستودع، أو إذا قمت بتمرير رمز read.
  • HfHubHTTPError — خطأ HTTP 404 إذا لم يكن المستخدم موجودًا على Hub.
  • HfHubHTTPError — HTTP 404 إذا تعذّر العثور على طلب وصول المستخدم.
  • HfHubHTTPError — HTTP 404 إذا كان طلب وصول المستخدم موجودًا بالفعل في قائمة الطلبات المعلّقة.

إلغاء طلب وصول من مستخدم لمستودع محكوم به معين.

ستعود الطلبات الملغاة إلى قائمة الطلبات المعلقة، وسيفقد المستخدم الوصول إلى المستودع.

لمزيد من المعلومات حول المستودعات المُقيَّدة، راجع https://huggingface.co/docs/hub/models-gated.

cancel_job

< >

( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • job_id (str) — معرّف المهمة.
  • namespace (str، اختياري) — المجال (namespace) الذي يعمل فيه Job. القيمة الافتراضية هي مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

إلغاء مهمة حساب على بنية Hugging Face التحتية.

change_discussion_status

< >

( repo_id: strdiscussion_num: intnew_status: Literal['open', 'closed']token: bool | str | None = Nonecomment: str | None = Nonerepo_type: str | None = None ) → DiscussionStatusChange

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • discussion_num (int) — رقم المناقشة أو طلب السحب. يجب أن يكون عددًا صحيحًا موجبًا تمامًا.
  • new_status (str) — الحالة الجديدة للنقاش، إما "open" أو "closed".
  • comment (str، اختياري) — تعليق اختياري يُنشر مع تغيير الحالة.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

DiscussionStatusChange

حدث تغيير الحالة

يُغلق نقاشًا أو طلب سحب أو يعيد فتحه.

أمثلة:

>>> HfApi().change_discussion_status(
...     repo_id="username/repo_name",
...     discussion_num=34,
...     new_status="closed"
... )
# DiscussionStatusChange(id='deadbeef0000000', type='status-change', ...)

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

comment_discussion

< >

( repo_id: strdiscussion_num: intcomment: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • discussion_num (int) — رقم المناقشة أو طلب السحب. يجب أن يكون عددًا صحيحًا موجبًا تمامًا.
  • comment (str) — محتوى التعليق الذي سيتم إنشاؤه. تدعم التعليقات تنسيق Markdown.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

تعليق المناقشة

التعليق الذي تم إنشاؤه حديثاً

ينشئ تعليقًا جديدًا على المناقشة المحددة.

أمثلة:


>>> comment = """
... Hello @otheruser!
...
... # This is a title
...
... **This is bold**, *this is italic* and ~this is strikethrough~
... And [this](http://url) is a link
... """

>>> HfApi().comment_discussion(
...     repo_id="username/repo_name",
...     discussion_num=34,
...     comment=comment
... )
# DiscussionComment(id='deadbeef0000000', type='comment', ...)

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

copy_files

< >

( source: strdestination: strtoken: str | bool | None = None )

المعاملات

  • source (str) — موقع المصدر على شكل hf:// URI. يمكن أن يكون مسار دلو (مثل "hf://buckets/my-bucket/path/to/file") أو مسار مستودع (مثل "hf://username/my-model/weights.bin"، "hf://datasets/username/my-dataset/data/").
  • destination (str) — موقع الوجهة على شكل hf:// URI يشير إلى دلو (e.g. "hf://buckets/my-bucket/target/path") أو مستودع (e.g. "hf://username/my-model/target/path").
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

ValueError

  • ValueError — إذا كانت عناوين URI للمصدر/الوجهة غير صالحة، أو عند النسخ من دلو إلى مستودع.

انسخ الملفات بين المواقع على Hub.

انسخ الملفات من دلو أو مستودع (نموذج، مجموعة بيانات، مساحة) إلى دلو أو مستودع آخر. يتم دعم الملفات الفردية والمجلدات الكاملة.

عند نسخ المجلدات، فإن وجود / في نهاية مسار المصدر يستخدم دلالات من نمط rsync: نسخ المحتويات الخاصة بالمجلد إلى الوجهة، دون تضمين مجلد المصدر نفسه. أما في حال عدم وجود / في النهاية، فيتم تضمين مجلد المصدر داخل الوجهة (مثل cp -r).

عند النسخ من مستودع إلى دلو، تُستبعد ملفات .gitattributes تلقائيًا لأنها بيانات وصفية خاصة بـ git ولا تنطبق في سياق الدلو.

تستخدم عمليات النسخ من مستودع إلى مستودع CommitOperationCopy في الخلفية وتُنشئ التزامًا في المستودع الوجهة. ولا تُدعم عمليات النسخ من دلو إلى مستودع.

تعمل النسخ على جانب الخادم فقط ضمن نطاق تخزين واحد.

مثال:

>>> from huggingface_hub import copy_files

# Copy a single file between buckets
>>> copy_files("hf://buckets/my-bucket/data.bin", "hf://buckets/other-bucket/data.bin")

# Copy a folder into another bucket (nests: backup/models/...)
>>> copy_files("hf://buckets/my-bucket/models", "hf://buckets/other-bucket/backup/")

# Copy folder contents (trailing /): files go directly into backup/
>>> copy_files("hf://buckets/my-bucket/models/", "hf://buckets/other-bucket/backup/")

# Copy a file from a model repo to a bucket
>>> copy_files("hf://username/my-model/model.safetensors", "hf://buckets/my-bucket/")

# Copy an entire dataset to a bucket
>>> copy_files("hf://datasets/username/my-dataset/", "hf://buckets/my-bucket/datasets/")

# Copy files between repositories
>>> copy_files("hf://username/source-model/", "hf://username/dest-model/")

# Copy a file from one repo to another
>>> copy_files("hf://username/source-model/config.json", "hf://username/dest-model/config.json")

create_branch

< >

( repo_id: strbranch: strrevision: str | None = Nonetoken: bool | str | None = Nonerepo_type: str | None = Noneexist_ok: bool = False )

المعاملات

  • repo_id (str) — المستودع الذي سيتم إنشاء الفرع فيه. مثال: "user/my-cool-model".
  • branch (str) — اسم الفرع الذي سيتم إنشاؤه.
  • revision (str, اختياري) — مراجعة git لإنشاء الفرع منها. يمكن أن يكون اسم فرع أو OID/SHA لالتزام، كنص سداسي عشري. الافتراضي هو رأس فرع "main".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند إنشاء فرع على مجموعة بيانات أو مساحة، أو None أو "model" عند وضع علامة على نموذج. القيمة الافتراضية هي None.
  • exist_ok (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فلا يتم رفع خطأ إذا كان الفرع موجودًا مسبقًا.

يرفع

RepositoryNotFoundError أو BadRequestError أو HfHubHTTPError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type غير صحيح، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • BadRequestError — إذا كان المرجع الخاص بفرع غير صالح. مثال: refs/pr/5 أو ‘refs/foo/bar’.
  • HfHubHTTPError — إذا كان الفرع موجودًا مسبقًا في المستودع (خطأ 409) وتم ضبط exist_ok على False.

أنشئ فرعًا جديدًا لمستودع على Hub، بدءًا من المراجعة المحددة (الافتراضي هو main). لاستكشاف مراجعة تناسب احتياجاتك، يمكنك استخدام list_repo_refs() أو list_repo_commits().

create_bucket

< >

( bucket_id: strprivate: bool | None = Nonevisibility: Literal['public', 'private'] | None = Noneresource_group_id: str | None = Noneregion: REPO_REGIONS | None = Noneexist_ok: bool = Falsetoken: bool | str | None = None ) → BucketUrl

المعاملات

  • bucket_id (str) — مساحة اسم (مستخدم أو منظمة) واسم دلو مفصولان بـ/. إذا لم تُقدَّم مساحة اسم، فسيتم إنشاء الدلو في مساحة اسم المستخدم الحالي.
  • private (bool، اختياري) — ما إذا كان سيتم جعل الدلو خاصًا. إذا كان None (الافتراضي)، فسيكون الدلو عامًا ما لم يكن الافتراضي للمنظمة هو الخاص. لا يمكن تمريره مع visibility.
  • visibility (Literal["public", "private"], اختياري) — رؤية الدلو. يمكن أن تكون "public" أو "private". إذا كانت None (الافتراضي)، فسيكون الدلو عامًا ما لم يكن الافتراضي للمنظمة هو الخاص.
  • resource_group_id (str, اختياري) — مجموعة الموارد التي سيتم إنشاء الدلو (bucket) فيها. مجموعات الموارد متاحة فقط لمنظمات Enterprise Hub، وتتيح تحديد أعضاء المنظمة الذين يمكنهم الوصول إلى المورد. يمكن العثور على معرّف مجموعة الموارد في عنوان URL لصفحة المورد على Hub (مثل "66670e5163145ca562cb1988"). لمعرفة المزيد حول مجموعات الموارد، راجع https://huggingface.co/docs/hub/en/security-resource-groups.
  • region (Literal["us", "eu"], اختياري) — منطقة السحابة التي سيتم فيها إنشاء الدلو. يمكن أن تكون "us" أو "eu". إذا لم يتم تحديد المنطقة، فسيتم إنشاء الدلو في المنطقة الافتراضية. يتطلب خطة Team أو أعلى.
  • exist_ok (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فلا يتم رفع خطأ إذا كان الدلو موجودًا بالفعل.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

BucketUrl

رابط إلى الدلو (bucket) الذي تم إنشاؤه حديثًا والذي يحتوي على خصائص مثل endpoint وnamespace وbucket_id.

أنشئ دلو على Hub.

مثال:

>>> from huggingface_hub import create_bucket

>>> url = create_bucket(bucket_id="my-bucket")
>>> url.bucket_id
'user/my-bucket'
>>> url.url
'https://huggingface.co/buckets/user/my-bucket'
>>> url.uri.to_uri()
'hf://buckets/user/my-bucket'

>>> create_bucket(bucket_id="my-bucket", private=True, exist_ok=True)
BucketUrl(...)

>>> create_bucket(bucket_id="my-bucket", region="us")
BucketUrl(...)

create_collection

< >

( title: strnamespace: str | None = Nonedescription: str | None = Noneprivate: bool = Falseresource_group_id: str | None = Noneexists_ok: bool = Falsetoken: bool | str | None = None )

المعاملات

  • title (str) — عنوان المجموعة التي سيتم إنشاؤها. مثال: "Recent models".
  • namespace (str، اختياري) — المجال (اسم المستخدم أو المنظمة) للمجموعة التي سيتم إنشاؤها. سيُستخدم اسم المالك افتراضيًا.
  • description (str، اختياري) — وصف المجموعة التي سيتم إنشاؤها. الحد الأقصى لحجم الوصف هو 150 حرفًا.
  • private (bool، اختياري) — ما إذا كان يجب أن تكون المجموعة خاصة أم لا. القيمة الافتراضية هي False (أي مجموعة عامة).
  • resource_group_id (str, اختياري) — يُعيّن المجموعة إلى مجموعة موارد تابعة للمنظمة المالكة. صالح فقط للمجموعات المملوكة للمنظمة. معرّف مجموعة الموارد هو نص سداسي عشري مكون من 24 حرفًا.
  • exists_ok (bool، اختياري) — إذا كان True، فلا ترفع خطأً إذا كانت المجموعة موجودة مسبقًا.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

أنشئ مجموعة جديدة على Hub.

يعيد: Collection

مثال:

>>> from huggingface_hub import create_collection
>>> collection = create_collection(
...     title="ICCV 2023",
...     description="Portfolio of models, papers and demos I presented at ICCV 2023",
... )
>>> collection.slug
"username/iccv-2023-64f9a55bb3115b4f513ec026"

create_commit

< >

( repo_id: stroperations: Iterable[CommitOperation]commit_message: strcommit_description: str | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Nonenum_threads: int = 5parent_commit: str | None = Nonerun_as_future: bool = False_hot_reload: bool | None = None ) → CommitInfo or Future

المعاملات

  • repo_id (str) — المستودع الذي سيتم فيه إنشاء الالتزام، على سبيل المثال: "username/custom_transformers"
  • operations (Iterable من ~hf_api.CommitOperation) — قائمة قابلة للتكرار من العمليات التي يجب تضمينها في عملية الإرسال، وهي إما:
    • ~hf_api.CommitOperationAdd لرفع ملف
    • ~hf_api.CommitOperationDelete لحذف ملف
    • ~hf_api.CommitOperationCopy لنسخ ملف

    ستُعدَّل كائنات العمليات لتشمل معلومات تتعلق بالرفع. لا تعِد استخدام الكائنات نفسها لعمليات التزامن المتعددة.

  • commit_message (str) — ملخص (السطر الأول) للالتزام الذي سيتم إنشاؤه.
  • commit_description (str, اختياري) — وصف الالتزام الذي سيتم إنشاؤه
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" أو "kernel" إذا كنت ترفع إلى مستودع مجموعة بيانات أو مساحة أو نواة، أو على None أو "model" إذا كنت ترفع إلى نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".
  • create_pr (boolean, اختياري) — ما إذا كان سيتم إنشاء طلب سحب (Pull Request) بهذا الالتزام أم لا. القيمة الافتراضية هي False. إذا لم يتم تعيين revision، يُفتح طلب السحب ضد فرع "main". إذا تم تعيين revision وكان فرعاً، يُفتح طلب السحب ضد هذا الفرع. إذا تم تعيين revision ولم يكن اسم فرع (مثال: معرف التزام)، يُرجع الخادم RevisionNotFoundError.
  • num_threads (int، اختياري) — عدد الخيوط المتزامنة لرفع الملفات. القيمة الافتراضية هي 5. إعدادها على 2 يعني أن أقصى عدد من الملفات التي يمكن رفعها بالتزامن هو 2.
  • parent_commit (str, اختياري) — المعرّف OID / SHA للالتزام الأب، كسلسلة سداسية عشرية. يُقبل أيضًا استخدام الاختصارات (الأحرف السبعة الأولى). إذا تم تحديد هذا المعرّف وكان create_pr هو False، فسيُفشل الالتزام إذا لم يُشير revision إلى parent_commit. وإذا تم تحديده وكان create_pr هو True، فسيتم إنشاء طلب السحب من parent_commit. يُضمن تحديد parent_commit عدم تغيّر المستودع قبل الالتزام بالتغييرات، وقد يكون مفيدًا بشكل خاص إذا كان المستودع يُحدَّث / يُلتزم به بشكل متزامن.
  • run_as_future (bool, اختياري) — ما إذا كان سيتم تنفيذ هذه الطريقة في الخلفية أم لا. تُنفَّذ مهام الخلفية بشكل تسلسلي دون إعاقة الخيط الرئيسي. تمرير run_as_future=True سيعيد كائن Future. القيمة الافتراضية هي False.

يعيد

CommitInfo أو Future

مثال من CommitInfo يحتوي على معلومات حول الالتزام الجديد الذي تم إنشاؤه (تجزئة الالتزام، رابط الالتزام، رابط طلب الدمج، رسالة الالتزام، ...). إذا تم تمرير run_as_future=True، تُرجع كائن Future الذي سيحتوي على النتيجة عند التنفيذ.

يرفع

ValueError أو RepositoryNotFoundError

  • ValueError — إذا كانت رسالة الالتزام فارغة.
  • ValueError — إذا لم يكن التثبيت الأب OID صالحًا.
  • ValueError — إذا تم إرسال ملف README.md يحتوي على قسم بيانات وصفية غير صالح. في هذه الحالة، سيفشل الإرسال في مرحلة مبكرة، قبل محاولة رفع أي ملف.
  • ValueError — إذا كان create_pr هو True وكان None أو "main" ليس هو المراجعة.
  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type غير صحيح، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.

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

سيتم تعديل قائمة الإدخال من CommitOperation أثناء عملية الالتزام. لا تعيد استخدام نفس الكائنات لعمليات التزام متعددة.

create_commit يفترض أن المستودع موجود مسبقًا على Hub. إذا واجهت خطأ Client 404، فتأكد من أنك مسجّل الدخول، وأن رمزك (token) يحمل الصلاحيات المطلوبة، وأن repo_id وrepo_type مضبوطة بشكل صحيح. إذا لم يكن المستودع موجودًا، أنشئه أولًا باستخدام create_repo().

create_commit محدود بـ 25 ألف ملف LFS وحجم حمولة يبلغ 1 جيجابايت للملفات العادية.

create_discussion

< >

( repo_id: strtitle: strtoken: bool | str | None = Nonedescription: str | None = Nonerepo_type: str | None = Nonepull_request: bool = False )

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • title (str) — عنوان المناقشة. يمكن أن يصل طوله إلى 200 حرف، ويجب أن يكون طوله 3 أحرف على الأقل. سيتم حذف المسافات الفضائية في البداية والنهاية.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • description (str، اختياري) — وصف اختياري لطلب الدمج. الافتراضي هو "Discussion opened with the huggingface_hub Python library"
  • pull_request (bool, اختياري) — ما إذا كان سيتم إنشاء طلب سحب أو نقاش. إذا كان True، يتم إنشاء طلب سحب. إذا كان False، يتم إنشاء نقاش. القيمة الافتراضية هي False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.

ينشئ نقاشاً أو طلب سحب.

ستكون طلبات الدمج (Pull Requests) التي يتم إنشاؤها برمجياً في حالة "draft".

يمكن أيضًا إنشاء طلب سحب يتضمن التغييرات دفعة واحدة باستخدام HfApi.create_commit().

يعيد: DiscussionWithDetails

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

create_inference_endpoint

< >

( name: strrepository: strframework: straccelerator: strinstance_size: strinstance_type: strregion: strvendor: straccount_id: str | None = Noneprivate_link_account_id: str | None = Noneprivate_link_region: str | None = Nonemin_replica: int = 1max_replica: int = 1scaling_metric: InferenceEndpointScalingMetric | None = Nonescaling_threshold: float | None = Nonescale_to_zero_timeout: int | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_registry_username: str | None = Nonecontainer_registry_password: str | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Noneenv: dict[str, str] | None = Nonesecrets: dict[str, str] | None = Nonetype: InferenceEndpointType | str = <InferenceEndpointType.AUTHENTICATED: 'authenticated'>domain: str | None = Nonepath: str | None = Nonecache_http_responses: bool | None = Nonetags: list[str] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

المعاملات

  • name (str) — الاسم الفريد لنقطة الاستدلال (Inference Endpoint) الجديدة.
  • repository (str) — اسم مستودع النموذج المرتبط بنقطة الاستدلال (Inference Endpoint) (مثل "gpt2").
  • framework (str) — إطار التعلم الآلي المستخدم للنموذج (مثل "custom").
  • accelerator (str) — مُسرِّع العتاد الذي سيُستخدم للاستدلال (مثل "cpu").
  • instance_size (str) — الحجم أو النوع للمثال (instance) الذي سيُستخدم لاستضافة النموذج (مثل "x4").
  • instance_type (str) — نوع مثيل السحابة الذي سيتم نشر نقطة الاستدلال عليه (مثل "intel-icl").
  • region (str) — منطقة السحابة التي سيتم فيها إنشاء نقطة الاستدلال (Inference Endpoint) (مثل "us-east-1").
  • vendor (str) — مزوّد السحابة أو الجهة التي سيُستضاف عليها نقطة الاستدلال (Inference Endpoint) (مثلًا "aws").
  • account_id (str، اختياري) — تم إيقاف استخدامه وتجاهله. استخدم private_link_account_id وprivate_link_region لإعداد AWS PrivateLink.
  • private_link_account_id (str، اختياري) — معرف حساب AWS المسموح له بالوصول إلى نقطة النهاية للاستدلال عبر AWS PrivateLink. يتطلب private_link_region.
  • private_link_region (str، اختياري) — منطقة AWS لنقطة دخول PrivateLink ("us-east-1" أو "eu-west-1")، حيث سيتصل منفذ VPC الخاص بـprivate_link_account_id. مستقل عن region وvendor الحسابات.
  • min_replica (int, اختياري) — الحد الأدنى لعدد النسخ (المهامات) التي يجب إبقاؤها قيد التشغيل لنقطة الاستدلال. لتفعيل التوسع إلى الصفر، اضبط هذه القيمة على 0 وعدّل scale_to_zero_timeout وفقاً لذلك. القيمة الافتراضية هي 1.
  • max_replica (int، اختياري) — الحد الأقصى لعدد النسخ (المهام) التي يمكن التوسع إليها لنقطة الاستدلال. القيمة الافتراضية هي 1.
  • scaling_metric (str أو InferenceEndpointScalingMetric ، اختياري) — مرجع المقياس للتوسيع. إما “pendingRequests” أو “hardwareUsage” عند تقديمه. القيمة الافتراضية هي None (أي: اترك خدمة HF Endpoints تحدد المقياس).
  • scaling_threshold (float, اختياري) — حدّ مقياس التوسيع المستخدم لتفعيل التوسيع. يتم تجاهله عندما لا يُوفَّر مقياس التوسيع. القيمة الافتراضية هي None (أي: اترك خدمة HF Endpoints تحدد الحدّ).
  • scale_to_zero_timeout (int, اختياري) — المدة بالدقائق قبل أن يُقلَّص حجم نقطة النهاية غير النشطة إلى صفر، أو عدم تقليص الحجم إلى صفر إذا تم ضبطه على None وكان min_replica ليس 0. القيمة الافتراضية هي None.
  • revision (str، اختياري) — المراجعة المحددة للنموذج التي سيتم نشرها على نقطة الاستدلال (Inference Endpoint) (مثل "6c0e6080953db56375760c0471a8c5f2929baf11").
  • task (str، اختياري) — المهمة التي سيتم نشر النموذج عليها (مثل "text-classification").
  • custom_image (dict، اختياري) — صورة الحاوية التي سيتم تشغيلها. إما قاموس مفاتيحه هي نسخ الصور (مثل {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}، وكذلك sGLang، tgi، tei، llamacpp، hfServe، …)، والذي يُمرَّر كما هو، أو قاموس مسطّح يصف حاوية مخصصة (مثل {"url": ..., "port": ...})، والذي يُرسل على شكل {"custom": ...} (انظر الأمثلة). الافتراضي هو الصورة المُدارة من قبل Hugging Face.
  • container_registry_username (str، اختياري) — اسم المستخدم المستخدم للمصادقة مع السجل الذي يستضيف صورة حاوية مخصصة.
  • container_registry_password (str، اختياري) — كلمة المرور المستخدمة للمصادقة مع السجل الذي يستضيف صورة حاوية مخصصة. يتطلب container_registry_username. يُستثنى من حمولة الواجهة البرمجية للتطبيقات (API payload) عند عدم تقديمه.
  • container_command (list[str], اختياري) — تجاوز أمر نقطة الدخول للحاوية (يتوافق مع model.command في حمولة الواجهة البرمجية). يعمل مع صور محركات مُدارة (مثل vLLM وSGLang) والصور المخصصة.
  • container_args (list[str]، اختياري) — الحُجج المُلحَقة بنقطة دخول الحاوية (تتوافق مع model.args في حمولة الواجهة البرمجية). تعمل مع صور المحركات المُدارة (مثل vLLM وSGLang) والصور المخصصة.
  • env (dict[str, str]، اختياري) — متغيرات بيئة غير سرية تُحقن في بيئة الحاوية.
  • secrets (dict[str, str]، اختياري) — قيم سرية تُحقن في بيئة الحاوية.
  • type ([`InferenceEndpointType], *optional*) -- The type of the Inference Endpoint, which can be “authenticated”(default),“public”or“private”`.
  • domain (str، اختياري) — النطاق المخصص لنشر نقطة الاستدلال (Inference Endpoint)، فإذا تم ضبطه ستكون نقطة الاستدلال متاحة عبر هذا النطاق (مثلًا "my-new-domain.cool-website.woof").
  • path (str، اختياري) — المسار المخصص للنموذج المُنفَّذ، يجب أن يبدأ بـ / (مثل "/models/google-bert/bert-base-uncased").
  • cache_http_responses (bool، اختياري) — ما إذا كان سيتم تخزين استجابات HTTP من نقطة الاستدلال مؤقتًا. القيمة الافتراضية هي False.
  • tags (list[str]، اختياري) — قائمة من الوسوم التي سيتم ربطها بنقطة الاستدلال (Inference Endpoint).
  • namespace (str، اختياري) — المجال الذي سيتم فيه إنشاء نقطة الاستدلال. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

InferenceEndpoint

معلومات حول نقطة الاستدلال المحدّثة.

أنشئ نقطة استنتاج جديدة.

تعتمد قيم accelerator وinstance_size وinstance_type وregion وvendor على بعضها البعض؛ استخدم list_inference_endpoints_hardware() لعرض التوليفات الصالحة.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "my-endpoint-name",
...     repository="gpt2",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="cpu",
...     vendor="aws",
...     region="us-east-1",
...     type="authenticated",
...     instance_size="x2",
...     instance_type="intel-icl",
... )
>>> endpoint
InferenceEndpoint(name='my-endpoint-name', status="pending",...)

# Run inference on the endpoint
>>> endpoint.client.text_generation(...)
"..."
# Start an Inference Endpoint running Zephyr-7b-beta on TGI
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "aws-zephyr-7b-beta-0486",
...     repository="HuggingFaceH4/zephyr-7b-beta",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="gpu",
...     vendor="aws",
...     region="us-east-1",
...     type="authenticated",
...     instance_size="x1",
...     instance_type="nvidia-a10g",
...     env={
...           "MAX_BATCH_PREFILL_TOKENS": "2048",
...           "MAX_INPUT_LENGTH": "1024",
...           "MAX_TOTAL_TOKENS": "1512",
...           "MODEL_ID": "/repository"
...         },
...     custom_image={
...         "healthRoute": "/health",
...         "url": "ghcr.io/huggingface/text-generation-inference:1.1.0",
...     },
...    secrets={"MY_SECRET_KEY": "secret_value"},
...    tags=["dev", "text-generation"],
... )
# Start an Inference Endpoint running ProsusAI/finbert while scaling to zero in 15 minutes
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "finbert-classifier",
...     repository="ProsusAI/finbert",
...     framework="pytorch",
...     task="text-classification",
...     min_replica=0,
...     scale_to_zero_timeout=15,
...     accelerator="cpu",
...     vendor="aws",
...     region="us-east-1",
...     type="authenticated",
...     instance_size="x2",
...     instance_type="intel-icl",
... )
>>> endpoint.wait(timeout=300)
# Run inference on the endpoint
>>> endpoint.client.text_generation(...)
TextClassificationOutputElement(label='positive', score=0.8983615040779114)

create_inference_endpoint_from_catalog

< >

( repo_id: str | None = Nonerecipe_id: str | None = Nonename: str | None = Noneaccelerator: Literal['cpu', 'gpu', 'neuron'] | str | None = Nonegguf_file: str | None = Nonetoken: bool | str | None = Nonenamespace: str | None = None ) → InferenceEndpoint

المعاملات

  • repo_id (str، اختياري) — معرّف النموذج في الكتالوج الذي سيتم نشره كنقطة استنتاج. يتعارض مع recipe_id.
  • recipe_id (str، اختياري) — معرّف وصفة الكتالوج التي سيتم نشرها (انظر InferenceCatalogRecipe). يتعارض مع repo_id.
  • name (str، اختياري) — الاسم الفريد لنقطة الاستدلال (Inference Endpoint) الجديدة. إذا لم يُقدَّم، سيتم توليد اسم عشوائي.
  • accelerator (str، اختياري) — مُسرِّع العتاد الذي سيُستخدم للاستدلال. تشمل القيم الممكنة "cpu" و"gpu" و "neuron". إذا لم يُقدَّم، فسيستخدم الخادم قيمة افتراضية مناسبة للنموذج. صالح فقط مع repo_id.
  • gguf_file (str، اختياري) — ملف GGUF الذي سيتم نشره، وذلك بالنسبة للنماذج التي تحتوي على وصفة واحدة لكل كميّة (e.g. "Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf"). صالح فقط مع repo_id.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication).
  • namespace (str، اختياري) — المجال الذي سيتم فيه إنشاء نقطة الاستدلال. الافتراضي هو مجال المستخدم الحالي.

يعيد

InferenceEndpoint

معلومات حول نقطة الاستدلال الجديدة.

أنشئ نقطة استنتاج جديدة من كتالوج الاستنتاج الخاص بـ Hugging Face.

تتمثل غاية كتالوج الاستدلال في توفير قائمة مُنتقاة من النماذج المُحسَّنة للاستدلال والتي تم اختبار الإعدادات الافتراضية لها. راجع https://huggingface.co/proxy/endpoints.huggingface.co/catalog للاطلاع على قائمة النماذج المتاحة في الكتالوج.

يتم نشر كل نموذج في الكتالوج عبر وصفة: وهي مجموعة من العتاد ومحرك الاستدلال التي تم اختبارها لهذا النموذج. مرّر repo_id لنشر الوصفة الافتراضية للنموذج، مع إمكانية تضييق النطاق اختياريًا باستخدام accelerator وgguf_file، أو مرّر recipe_id لنشر وصفة محددة تمامًا من تلك التي تُعرض بواسطة list_inference_catalog().

create_inference_endpoint_from_catalog تجريبي. قد تتغير واجهته البرمجية (API) في المستقبل. يرجى تقديم ملاحظاتك إذا كان لديك أي اقتراحات أو طلبات.

create_pull_request

< >

( repo_id: strtitle: strtoken: bool | str | None = Nonedescription: str | None = Nonerepo_type: str | None = None )

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • title (str) — عنوان المناقشة. يمكن أن يصل طوله إلى 200 حرف، ويجب أن يكون طوله 3 أحرف على الأقل. سيتم حذف المسافات الفضائية في البداية والنهاية.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • description (str، اختياري) — وصف اختياري لطلب الدمج. الافتراضي هو "Discussion opened with the huggingface_hub Python library"
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.

ينشئ طلب سحب. تكون طلبات السحب التي يتم إنشاؤها برمجياً في حالة "draft".

يمكن أيضًا إنشاء طلب سحب يتضمن التغييرات دفعة واحدة باستخدام HfApi.create_commit();

هذا غلاف حول HfApi.create_discussion().

يعيد: DiscussionWithDetails

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

create_repo

< >

( repo_id: strtoken: str | bool | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonerepo_type: str | None = Noneexist_ok: bool = Falseresource_group_id: str | None = Noneregion: REPO_REGIONS | None = Nonespace_sdk: str | None = Nonespace_hardware: SpaceHardware | None = Nonespace_sleep_time: int | None = Nonespace_secrets: list[dict[str, str]] | None = Nonespace_variables: list[dict[str, str]] | None = Nonespace_volumes: list[Volume] | None = Nonespace_template: str | None = None ) → RepoUrl

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • private (bool، اختياري) — ما إذا كان سيتم جعل المستودع خاصًا. إذا كان None (الافتراضي)، فسيكون المستودع عامًا ما لم يكن الافتراضي للمنظمة هو الخاص. يتم تجاهل هذه القيمة إذا كان المستودع موجودًا بالفعل. لا يمكن تمريرها مع visibility.
  • visibility (Literal["public", "private", "protected"], اختياري) — رؤية المستودع. يمكن أن تكون "public" أو "private"، أو "protected" لـ Spaces. إذا كانت None (الافتراضي)، فسيكون المستودع عامًا ما لم يكن الافتراضي للمنظمة خاصًا. يتم تجاهل هذه القيمة إذا كان المستودع موجودًا بالفعل.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • exist_ok (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فلا يتم رفع خطأ إذا كان المستودع موجودًا مسبقًا.
  • resource_group_id (str, اختياري) — مجموعة الموارد التي سيتم إنشاء المستودع فيها. مجموعات الموارد متاحة فقط لمنظمات Enterprise Hub، وتتيح تحديد أعضاء المنظمة الذين يمكنهم الوصول إلى المورد. يمكن العثور على معرّف مجموعة الموارد في عنوان URL لصفحة المورد على Hub (مثل "66670e5163145ca562cb1988"). لمعرفة المزيد حول مجموعات الموارد، راجع https://huggingface.co/docs/hub/en/security-resource-groups.
  • region (Literal["us", "eu"], اختياري) — منطقة السحابة التي سيتم فيها إنشاء المستودع. يمكن أن تكون "us" أو "eu". إذا لم يتم تحديد المنطقة، فسيتم إنشاء المستودع في المنطقة الافتراضية. يتطلب ذلك خطة Team أو أعلى.
  • space_sdk (str، اختياري) — اختيار SDK للاستخدام إذا كان repo_type هو “space”. يمكن أن يكون “streamlit” أو “gradio” أو “docker” أو “static”. مساحات "static" مجانية للجميع. أما SDKs الأخرى فتعمل على أجهزة الحوسبة: على العتاد المجاني cpu-basic، تتطلب اشتراكًا (PRO للمستخدمين، أو Team أو Enterprise للمنظمات)، بينما يتطلب العتاد المدفوع فقط الفوترة (طريقة دفع وأرصدة مسبقة الدفع).
  • space_hardware (SpaceHardware أو str، اختياري) — اختيار العتاد إذا كان repo_type هو “space”. راجع SpaceHardware للحصول على قائمة كاملة.
  • space_sleep_time (int, اختياري) — عدد ثوانٍ من عدم النشاط التي يجب انتظارها قبل وضع مساحة في وضع السكون. اضبط القيمة على -1 إذا كنت لا تريد لمساحتك أن تدخل في وضع السكون (وهو السلوك الافتراضي للأجهزة المُحدَّثة). أما بالنسبة للأجهزة المجانية، فلا يمكنك ضبط وقت السكون (القيمة ثابتة عند 48 ساعة من عدم النشاط). راجع https://huggingface.co/docs/hub/spaces-gpus#sleep-time لمزيد من التفاصيل.
  • space_secrets (list[dict[str, str]]، اختياري) — قائمة بمفاتيح سرية لضبطها في مساحتك. كل عنصر يكون على شكل {"key": ..., "value": ..., "description": ...} حيث أن description اختياري. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets.
  • space_variables (list[dict[str, str]]، اختياري) — قائمة متغيرات البيئة العامة التي سيتم ضبطها في مساحتك. كل عنصر يكون على شكل {"key": ..., "value": ..., "description": ...} حيث يكون الوصف اختياريًا. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables.
  • space_volumes (list[Volume]، اختياري) — قائمة من كائنات Volume تُركَّب في المساحة عند الإنشاء. يحتوي كل حجم على type ("bucket" أو "model" أو "dataset" أو "space")، وsource (معرّف المستودع أو الدلو)، وmount_path (المسار داخل الحاوية)، وحقول اختيارية revision وread_only وpath. لا ينطبق إلا إذا كان repo_type هو “space”.
  • space_template (str, اختياري) — بذر المساحة الجديدة من قالب رسمي. يمكن أن يكون معرّف مستودع القالب (مثل "SpacesExamples/jupyterlab") أو اسمه المختصر (مثل "JupyterLab"). استخدم HfApi.list_space_templates() لعرض القوالب المتاحة. ينطبق فقط إذا كان repo_type هو “space”. إذا كان يُوصى بأن يكون القالب خاصاً ولم يتم تعيين الرؤية بشكل صريح، يتم إنشاء المساحة كخاصة.

يعيد

RepoUrl

رابط إلى المستودع الذي تم إنشاؤه حديثاً. القيمة هي فئة فرعية من str تحتوي على سمات مثل endpoint وrepo_type وrepo_id.

أنشئ مستودعًا فارغًا على HuggingFace Hub.

create_scheduled_job

< >

( image: strcommand: list[str]schedule: strsuspend: bool | None = Noneconcurrency: bool | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • image (str) — صورة Docker التي سيتم استخدامها. أمثلة: "ubuntu"، "python:3.12"، "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel". مثال على صورة من Space: "hf.co/spaces/lhoestq/duckdb".
  • command (list[str]) — الأمر الذي سيتم تنفيذه. مثال: ["echo", "hello"].
  • schedule (str) — إحدى القيم التالية: “@annually” أو “@yearly” أو “@monthly” أو “@weekly” أو “@daily” أو “@hourly”، أو تعبير جدولة CRON (مثل ‘0 9 * * 1’ للساعة 9 صباحًا كل يوم اثنين).
  • suspend (bool، اختياري) — إذا كانت القيمة True، يتم تعليق (إيقاف مؤقت) المهمة المجدولة. القيمة الافتراضية هي False.
  • concurrency (bool، اختياري) — إذا كانت القيمة True، يمكن تشغيل عدة نسخ من هذا Job بالتوازي. القيمة الافتراضية هي False.
  • env (dict[str, Any]، اختياري) — يحدد متغيرات البيئة الخاصة بالمهمة.
  • secrets (dict[str, Any]، اختياري) — يحدد متغيرات البيئة السرية للعمل.
  • flavor (str، اختياري) — النوع الخاص بالعتاد. راجع JobHardware لمعرفة القيم الممكنة. القيمة الافتراضية هي "cpu-basic".
  • timeout (Union[int, float, str], اختياري) — المدة القصوى للـ Job: int مع s (ثوانٍ، الافتراضي)، m (دقائق)، h (ساعات) أو d (أيام). مثال: 300 أو "5m" لمدة 5 دقائق.
  • attempts (int، اختياري) — الحد الأقصى لعدد المحاولات لكل تشغيل، بما في ذلك المحاولة الأولية. القيمة الافتراضية هي 1.
  • name (str، اختياري) — اسم للوظيفة المجدولة. يُخزَّن كوسم name. لا يمكن تمريره مع مفتاح name في labels. لا يجب أن تكون الأسماء فريدة. القيمة الافتراضية هي اسم مشتق من الصورة والأمر (مع لاحقة تجزئة قصيرة).
  • labels (dict[str, str]، اختياري) — التسميات التي سيتم إرفاقها بالمهمة (أزواج مفتاح-قيمة).
  • volumes (list[Volume]، اختياري) — حاويات Hugging Face Buckets أو مستودعات Repos تُركَّب كحجميات داخل حاوية المهمة. كل حجمية هي Volume تحتوي على type ("bucket"، "model"، "dataset"، أو "space")، وsource (مثل "username/my-bucket")، وmount_path (مثل "/data").
  • expose (list[int]، اختياري) — منافذ الحاوية التي يجب كشفها عبر وكيل المهام. كل منفذ مدرج يكون متاحًا على نطاق المهام العام (مثل https://<job_id>--8000.hf.jobs). يتطلب الوصول دائمًا رمز HF مع صلاحية القراءة في مساحة أسماء المهمة. استخدم expose_public للوصول غير الموثق.
  • expose_public (list[int], اختياري) — منافذ يجب كشفها عبر وكيل Jobs دون مصادقة. لا يلزم إدراجها في expose.
  • resource_group_id (str, اختياري) — معرّف مجموعة الموارد التي سيتم إنشاء المهمة المجدولة فيها. يُستخدم للتحكم في الوصول إلى الموارد داخل المنظمة وللميزات المتعلقة بتخصيص التكاليف وحدود الإنفاق. إذا لم يُقدَّم، فسيتم إنشاء المهمة المجدولة خارج أي مجموعة موارد.
  • namespace (str، اختياري) — المجال الذي سيتم فيه إنشاء المهمة. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

أنشئ مهام حساب مجدولة على بنية Hugging Face التحتية.

مثال:

أنشئ مهمة مجدولة أولى:

>>> from huggingface_hub import create_scheduled_job
>>> create_scheduled_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"], schedule="@hourly")

استخدم تعبير جدولة CRON:

>>> from huggingface_hub import create_scheduled_job
>>> create_scheduled_job(image="python:3.12", command=["python", "-c" ,"print('this runs every 5min')"], schedule="*/5 * * * *")

إنشاء مهمة GPU مجدولة:

>>> from huggingface_hub import create_scheduled_job
>>> image = "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"
>>> command = ["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"]
>>> create_scheduled_job(image=image, command=command, flavor="a10g-small", schedule="@hourly")

create_scheduled_uv_job

< >

( script: strscript_args: list[str] | None = Noneschedule: strsuspend: bool | None = Noneconcurrency: bool | None = Nonedependencies: list[str] | None = Nonepython: str | None = Noneimage: str | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • script (str) — مسار أو عنوان URL لسكربت UV، أو أمر.
  • script_args (list[str]، اختياري) — الحجج المراد تمريرها إلى السكربت أو الأمر.
  • schedule (str) — إحدى القيم التالية: “@annually” أو “@yearly” أو “@monthly” أو “@weekly” أو “@daily” أو “@hourly”، أو تعبير جدولة CRON (مثل ‘0 9 * * 1’ للساعة 9 صباحًا كل يوم اثنين).
  • suspend (bool، اختياري) — إذا كانت القيمة True، يتم تعليق (إيقاف مؤقت) المهمة المجدولة. القيمة الافتراضية هي False.
  • concurrency (bool، اختياري) — إذا كانت القيمة True، يمكن تشغيل عدة نسخ من هذا Job بالتوازي. القيمة الافتراضية هي False.
  • dependencies (list[str]، اختياري) — التبعيات المستخدمة لتشغيل سكريبت UV.
  • python (str، اختياري) — استخدم إصدارًا محددًا من Python. الافتراضي هو 3.12.
  • image (str، اختياري، القيمة الافتراضية هي “ghcr.io/astral-sh/uv —python3.12-bookworm”): استخدم صورة Docker مخصصة مع تثبيت uv.
  • env (dict[str, Any]، اختياري) — يحدد متغيرات البيئة الخاصة بالمهمة.
  • secrets (dict[str, Any]، اختياري) — يحدد متغيرات البيئة السرية للعمل.
  • flavor (str، اختياري) — النوع الخاص بالعتاد. راجع JobHardware لمعرفة القيم الممكنة. القيمة الافتراضية هي "cpu-basic".
  • timeout (Union[int, float, str], اختياري) — المدة القصوى للـ Job: int مع s (ثوانٍ، الافتراضي)، m (دقائق)، h (ساعات) أو d (أيام). مثال: 300 أو "5m" لمدة 5 دقائق.
  • attempts (int، اختياري) — الحد الأقصى لعدد المحاولات لكل تشغيل، بما في ذلك المحاولة الأولية. القيمة الافتراضية هي 1.
  • name (str، اختياري) — اسم للوظيفة المجدولة. يُخزَّن كوسم name. لا يمكن تمريره مع مفتاح name في labels. لا يجب أن تكون الأسماء فريدة. القيمة الافتراضية هي اسم مشتق من السكربت وحوامله (مع لاحقة تجزئة قصيرة).
  • labels (dict[str, str]، اختياري) — التسميات التي سيتم إرفاقها بالمهمة (أزواج مفتاح-قيمة).
  • volumes (list[Volume]، اختياري) — حاويات Hugging Face Buckets أو مستودعات Repos تُركَّب كحجميات داخل حاوية المهمة. كل حجمية هي Volume تحتوي على type ("bucket"، "model"، "dataset"، أو "space")، وsource (مثل "username/my-bucket")، وmount_path (مثل "/data").
  • expose (list[int]، اختياري) — منافذ الحاوية التي يجب كشفها عبر وكيل المهام. كل منفذ مدرج يكون متاحًا على نطاق المهام العام (مثل https://<job_id>--8000.hf.jobs). يتطلب الوصول دائمًا رمز HF مع صلاحية القراءة في مساحة أسماء المهمة. استخدم expose_public للوصول غير الموثق.
  • expose_public (list[int], اختياري) — منافذ يجب كشفها عبر وكيل Jobs دون مصادقة. لا يلزم إدراجها في expose.
  • resource_group_id (str, اختياري) — معرّف مجموعة الموارد التي سيتم إنشاء المهمة المجدولة فيها. يُستخدم للتحكم في الوصول إلى الموارد داخل المنظمة وللميزات المتعلقة بتخصيص التكاليف وحدود الإنفاق. إذا لم يُقدَّم، فسيتم إنشاء المهمة المجدولة خارج أي مجموعة موارد.
  • namespace (str، اختياري) — المجال الذي سيتم فيه إنشاء المهمة. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

شغّل مهمة سكربت UV على بنية Hugging Face التحتية.

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

مثال:

جدولة سكربت من عنوان URL:

>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small", schedule="@weekly")

جدولة سكربت محلي:

>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small", schedule="@weekly")

جدولة أمر:

>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "lighteval"
>>> script_args= ["endpoint", "inference-providers", "model_name=openai/gpt-oss-20b,provider=auto", "lighteval|gsm8k|0|0"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["lighteval"], flavor="a10g-small", schedule="@weekly")

create_tag

< >

( repo_id: strtag: strtag_message: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonerepo_type: str | None = Noneexist_ok: bool = False )

المعاملات

  • repo_id (str) — المستودع الذي سيتم وضع علامة على التزامن فيه. مثال: "user/my-cool-model".
  • tag (str) — اسم الوسم الذي سيتم إنشاؤه.
  • tag_message (str، اختياري) — وصف الوسم الذي سيتم إنشاؤه.
  • revision (str، اختياري) — مراجعة git التي سيتم وضع علامة عليها. يمكن أن تكون اسم فرع أو OID/SHA لالتزام، كنص سداسي عشري. يتم دعم الاختصارات (أول 7 أحرف) أيضًا. الافتراضي هو رأس فرع "main".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنت تضيف وسمًا إلى مجموعة بيانات أو مساحة، أو None أو "model" إذا كنت تضيف وسمًا إلى نموذج. القيمة الافتراضية هي None.
  • exist_ok (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فلا يتم رفع خطأ إذا كان الوسم موجودًا مسبقًا.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError أو HfHubHTTPError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type غير صحيح، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • RevisionNotFoundError — إذا لم يتم العثور على المراجعة (خطأ 404) في المستودع.
  • HfHubHTTPError — إذا كان الفرع موجودًا مسبقًا في المستودع (خطأ 409) وتم ضبط exist_ok على False.

تعيين وسم لالتزام معين في مستودع على Hub.

create_webhook

< >

( url: str | None = Nonejob_id: str | None = Nonewatched: list[dict | WebhookWatchedItem]domains: list[constants.WEBHOOK_DOMAIN_T] | None = Nonesecret: str | None = Nonesecrets: dict[str, str] | None = Nonetoken: bool | str | None = None ) → WebhookInfo

المعاملات

  • url (str) — رابط URL لإرسال الحمولة إليه.
  • job_id (str) — معرّف مهمة المصدر التي سيتم تشغيلها عبر حمولة webhook في متغير البيئة WEBHOOK_PAYLOAD. تتوفر متغيرات بيئة إضافية لتسهيل الاستخدام: WEBHOOK_REPO_ID وWEBHOOK_REPO_TYPE وWEBHOOK_SECRET.
  • watched (list[WebhookWatchedItem]) — قائمة من WebhookWatchedItem التي سيقوم الـ webhook بمراقبتها. يمكن أن تكون هذه العناصر مستخدمين أو منظمات أو نماذج أو مجموعات بيانات أو مساحات أو دلاءً. يمكن أيضًا تقديم العناصر المرصودة كمعاجم (dictionaries) عادية.
  • domains (list[Literal["repo", "discussion"]], اختياري) — قائمة بالمجالات المراد مراقبتها. يمكن أن تكون “repo” أو “discussion” أو كلاهما. الافتراضي هو كلاهما.
  • secret (str, اختياري) — سرّ يُستخدم لتوقيع الحمولة.
  • secrets (dict[str, str], اختياري) — متغيرات البيئة السرية الخاصة بالمهمة (Job) التي يُطلقها خطاف الويب (webhook) (مثل {"HF_TOKEN": "hf_***"}). صالح فقط مع job_id. لا يتم نسخ أسرار المهمة المصدرية إلى خطاف الويب، لذا مرّرها هنا.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

WebhookInfo

معلومات حول خطّ الواب (webhook) الذي تم إنشاؤه حديثًا.

إنشاء webhook جديد.

يمكن أن يرسل خطاف الويب حمولة إلى عنوان URL، أو أن يُطلق مهمة (Job) لتشغيلها على بنية Hugging Face التحتية. يجب استدعاء هذه الدالة بإحدى القيمتين url أو job_id، وليس بكلتاهما معاً.

مثال:

إنشاء خطاف ويب (webhook) يرسل حمولة (payload) إلى عنوان URL

>>> from huggingface_hub import create_webhook
>>> payload = create_webhook(
...     watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
...     url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
...     domains=["repo", "discussion"],
...     secret="my-secret",
... )
>>> print(payload)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    job=None,
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=False,
)

تشغيل مهمة ثم إنشاء خطاف ويب (webhook) يُطلق هذه المهمة

>>> from huggingface_hub import create_webhook, run_job
>>> job = run_job(
...     image="ubuntu",
...     command=["bash", "-c", r"echo An event occurred in $WEBHOOK_REPO_ID: $WEBHOOK_PAYLOAD"],
... )
>>> payload = create_webhook(
...     watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
...     job_id=job.id,
...     domains=["repo", "discussion"],
...     secret="my-secret",
... )
>>> print(payload)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url=None,
    job=JobSpec(
        docker_image='ubuntu',
        space_id=None,
        command=['bash', '-c', 'echo An event occurred in $WEBHOOK_REPO_ID: $WEBHOOK_PAYLOAD'],
        arguments=[],
        environment={},
        secrets=[],
        flavor='cpu-basic',
        timeout=None,
        tags=None,
        arch=None
    ),
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=False,
)

dataset_info

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandDatasetProperty_T] | None = Nonetoken: bool | str | None = None ) → hf_api.DatasetInfo

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • revision (str، اختياري) — إصدار مستودع مجموعة البيانات الذي سيتم منه الحصول على المعلومات.
  • timeout (float، اختياري) — ما إذا كان يجب تعيين مهلة زمنية للطلب الموجّه إلى Hub.
  • files_metadata (bool، اختياري) — ما إذا كان سيتم استرداد البيانات الوصفية للملفات في المستودع (الحجم، بيانات LFS الوصفية، إلخ). القيمة الافتراضية هي False.
  • expand (list[ExpandDatasetProperty_T], اختياري) — قائمة بالخصائص التي يجب إرجاعها في الاستجابة. عند الاستخدام، لن تُرجع إلا الخصائص الموجودة في القائمة. لا يمكن استخدام هذا المعامل إذا تم تمرير files_metadata. القيم الممكنة هي "author"، "cardData"، "citation"، "createdAt"، "disabled"، "description"، "downloads"، "downloadsAllTime"، "gated"، "lastModified"، "likes"، "mainSize"، "paperswithcode_id"، "private"، "siblings"، "sha"، "tags"، "trendingScore"، "usedStorage"، و"resourceGroup".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

hf_api.DatasetInfo

معلومات مستودع مجموعة البيانات.

احصل على معلومات حول مجموعة بيانات محددة على huggingface.co.

يمكن أن يكون Dataset خاصاً إذا مررت برمز (token) مقبول.

يرفع الأخطاء التالية:

  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • RevisionNotFoundError إذا تعذّر العثور على المراجعة التي يجب التحميل منها.

delete_branch

< >

( repo_id: strbranch: strtoken: bool | str | None = Nonerepo_type: str | None = None )

المعاملات

  • repo_id (str) — المستودع الذي سيتم حذف فرع منه. مثال: "user/my-cool-model".
  • branch (str) — اسم الفرع المراد حذفه.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند إنشاء فرع على مجموعة بيانات أو مساحة، أو None أو "model" عند وضع علامة على نموذج. القيمة الافتراضية هي None.

يرفع

RepositoryNotFoundError أو HfHubHTTPError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type غير صحيح، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • HfHubHTTPError — إذا حاولتَ حذف فرع محمي. مثال: لا يمكن حذف main.
  • HfHubHTTPError — عند محاولة حذف فرع غير موجود.

حذف فرع من مستودع على Hub.

delete_bucket

< >

( bucket_id: strmissing_ok: bool = Falsetoken: bool | str | None = None )

المعاملات

  • bucket_id (str) — معرّف الدلو (مثلًا "username/my-bucket").
  • missing_ok (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فلا يتم رفع خطأ إذا لم يكن الحوض موجودًا.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

BucketNotFoundError

  • BucketNotFoundError — إذا تعذّر العثور على الدلو وكان missing_ok مضبوطًا على False (الافتراضي).

حذف دلو من Hub.

مثال:

>>> from huggingface_hub import delete_bucket
>>> delete_bucket(bucket_id="Wauplin/first-bucket")
>>> delete_bucket(bucket_id="Wauplin/first-bucket", missing_ok=True)

delete_collection

< >

( collection_slug: strmissing_ok: bool = Falsetoken: bool | str | None = None )

المعاملات

  • collection_slug (str) — اسم الرابط (Slug) للمجموعة المراد حذفها. مثال: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • missing_ok (bool، اختياري) — إذا كان True، فلا ترفع خطأً إذا لم يكن المجموع موجودًا.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

حذف مجموعة على الـ Hub.

مثال:

>>> from huggingface_hub import delete_collection
>>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True)

هذا إجراء غير قابل للتراجع. لا يمكن استعادة مجموعة محذوفة.

delete_collection_item

< >

( collection_slug: stritem_object_id: strmissing_ok: bool = Falsetoken: bool | str | None = None )

المعاملات

  • collection_slug (str) — اسم الرابط (Slug) للمجموعة المراد تحديثها. مثال: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_object_id (str) — معرّف العنصر في المجموعة. هذا ليس معرّف العنصر على Hub (repo_id أو paper id). يجب استرداده من كائن CollectionItem. مثال: collection.items[0].item_object_id.
  • missing_ok (bool، اختياري) — إذا كان True، فلا ترفع خطأً إذا لم يكن العنصر موجودًا.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

حذف عنصر من مجموعة.

مثال:

>>> from huggingface_hub import get_collection, delete_collection_item

# Get collection first
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")

# Delete item based on its ID
>>> delete_collection_item(
...     collection_slug="TheBloke/recent-models-64f9a55bb3115b4f513ec026",
...     item_object_id=collection.items[-1].item_object_id,
... )

delete_file

< >

( path_in_repo: strrepo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )

المعاملات

  • path_in_repo (str) — مسار الملف النسبي داخل المستودع، على سبيل المثال: "checkpoints/1fec34a/weights.bin"
  • repo_id (str) — المستودع الذي سيتم حذف الملف منه، على سبيل المثال: "username/custom_transformers"
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — يُضبط على "dataset" أو "space" إذا كان الملف في مجموعة بيانات أو مساحة، أو None أو "model" إذا كان في نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".
  • commit_message (str، اختياري) — ملخص / عنوان / السطر الأول للالتزام المولّد. القيمة الافتراضية هي f"Delete {path_in_repo} with huggingface_hub".
  • commit_description (str، اختياري) — وصف الالتزام المُولَّد
  • create_pr (boolean, اختياري) — ما إذا كان سيتم إنشاء طلب سحب (Pull Request) بهذا الالتزام أم لا. القيمة الافتراضية هي False. إذا لم يتم تعيين revision، يُفتح طلب السحب ضد فرع "main". إذا تم تعيين revision وكان فرعاً، يُفتح طلب السحب ضد هذا الفرع. إذا تم تعيين revision ولم يكن اسم فرع (مثال: معرف التزام)، يُرجع الخادم RevisionNotFoundError.
  • parent_commit (str, اختياري) — معرّف OID / SHA للالتزام الأب، كنص سداسي عشري. يتم دعم الاختصارات (الأحرف السبعة الأولى) أيضًا. إذا تم تحديده وكان create_pr هو False، فسيفشل الالتزام إذا لم يشير revision إلى parent_commit. إذا تم تحديده وكان create_pr هو True، فسيتم إنشاء طلب السحب من parent_commit. يضمن تحديد parent_commit أن المستودع لم يتغير قبل الالتزام بالتغييرات، ويمكن أن يكون مفيدًا بشكل خاص إذا تم تحديث المستودع / الالتزام به بشكل متزامن.

يحذف ملفًا في المستودع المحدد.

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • RevisionNotFoundError إذا تعذّر العثور على المراجعة التي يجب التحميل منها.
  • EntryNotFoundError إذا تعذّر العثور على الملف المطلوب تنزيله.

delete_files

< >

( repo_id: strdelete_patterns: list[str]token: bool | str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )

المعاملات

  • repo_id (str) — المستودع الذي سيتم حذف المجلد منه، على سبيل المثال: "username/custom_transformers"
  • delete_patterns (list[str]) — قائمة من الملفات أو المجلدات التي يجب حذفها. يمكن أن يكون كل نص مسار ملف، أو مسار مجلد، أو نمط كروي. الأنماط هي أنماط كروية قياسية (أنماط globbing) كما هو موثق هنا. يعتمد مطابقة الأنماط على fnmatch. لاحظ أن fnmatch يطابق * عبر حدود المسار، على عكس أنماط globbing التقليدية في Unix shell. مثال: ["file.txt", "folder/", "data/*.parquet"]
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرر False. إلى الرمز المخزن.
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم حذف الملفات منه. يمكن أن يكون "model" أو "dataset" أو "space". القيمة الافتراضية هي "model".
  • revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".
  • commit_message (str, اختياري) — ملخص (السطر الأول) للالتزام المولّد. القيمة الافتراضية هي f"Delete files using huggingface_hub".
  • commit_description (str، اختياري) — وصف الالتزام المُولَّد.
  • create_pr (boolean, اختياري) — ما إذا كان سيتم إنشاء طلب سحب (Pull Request) بهذا الالتزام أم لا. القيمة الافتراضية هي False. إذا لم يتم تعيين revision، يُفتح طلب السحب ضد فرع "main". إذا تم تعيين revision وكان فرعاً، يُفتح طلب السحب ضد هذا الفرع. إذا تم تعيين revision ولم يكن اسم فرع (مثال: معرف التزام)، يُرجع الخادم RevisionNotFoundError.
  • parent_commit (str, اختياري) — معرّف OID / SHA للالتزام الأب، كنص سداسي عشري. يتم دعم الاختصارات (الأحرف السبعة الأولى) أيضًا. إذا تم تحديده وكان create_pr هو False، فسيفشل الالتزام إذا لم يشير revision إلى parent_commit. إذا تم تحديده وكان create_pr هو True، فسيتم إنشاء طلب السحب من parent_commit. يضمن تحديد parent_commit أن المستودع لم يتغير قبل الالتزام بالتغييرات، ويمكن أن يكون مفيدًا بشكل خاص إذا تم تحديث المستودع / الالتزام به بشكل متزامن.

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

إذا تم توفير مسار مجلد، يتم حذف المجلد بأكمله إلى جانب جميع الملفات التي يحتويها.

delete_folder

< >

( path_in_repo: strrepo_id: strtoken: bool | str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )

المعاملات

  • path_in_repo (str) — مسار المجلد النسبي داخل المستودع، على سبيل المثال: "checkpoints/1fec34a".
  • repo_id (str) — المستودع الذي سيتم حذف المجلد منه، على سبيل المثال: "username/custom_transformers"
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرر False. إلى الرمز المخزن.
  • repo_type (str، اختياري) — يُضبط على "dataset" أو "space" إذا كان المجلد ضمن مجموعة بيانات أو مساحة، أو None أو "model" إذا كان ضمن نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".
  • commit_message (str، اختياري) — ملخص / عنوان / السطر الأول للالتزام المولّد. القيمة الافتراضية هي f"Delete folder {path_in_repo} with huggingface_hub".
  • commit_description (str، اختياري) — وصف الالتزام المُولَّد.
  • create_pr (boolean, اختياري) — ما إذا كان سيتم إنشاء طلب سحب (Pull Request) بهذا الالتزام أم لا. القيمة الافتراضية هي False. إذا لم يتم تعيين revision، يُفتح طلب السحب ضد فرع "main". إذا تم تعيين revision وكان فرعاً، يُفتح طلب السحب ضد هذا الفرع. إذا تم تعيين revision ولم يكن اسم فرع (مثال: معرف التزام)، يُرجع الخادم RevisionNotFoundError.
  • parent_commit (str, اختياري) — معرّف OID / SHA للالتزام الأب، كنص سداسي عشري. يتم دعم الاختصارات (الأحرف السبعة الأولى) أيضًا. إذا تم تحديده وكان create_pr هو False، فسيفشل الالتزام إذا لم يشير revision إلى parent_commit. إذا تم تحديده وكان create_pr هو True، فسيتم إنشاء طلب السحب من parent_commit. يضمن تحديد parent_commit أن المستودع لم يتغير قبل الالتزام بالتغييرات، ويمكن أن يكون مفيدًا بشكل خاص إذا تم تحديث المستودع / الالتزام به بشكل متزامن.

يحذف مجلدًا في المستودع المحدد.

غلاف بسيط حول طريقة create_commit().

delete_inference_endpoint

< >

( name: strnamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • name (str) — اسم نقطة الاستدلال (Inference Endpoint) المراد حذفها.
  • namespace (str، اختياري) — المجال الذي يقع فيه Inference Endpoint. الافتراضي هو المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

حذف نقطة استنتاج.

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

للسهولة، يمكنك أيضاً حذف نقطة استنتاج باستخدام InferenceEndpoint.delete().

delete_repo

< >

( repo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonemissing_ok: bool = False )

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج.
  • missing_ok (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فلا يتم رفع خطأ إذا لم يكن المستودع موجودًا.

يرفع

RepositoryNotFoundError

  • RepositoryNotFoundError — إذا تعذّر العثور على المستودع الذي يجب الحذف منه وكان missing_ok مضبوطًا على False (الافتراضي).

احذف مستودعًا من HuggingFace Hub. تحذير: هذا الإجراء لا يمكن التراجع عنه.

delete_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • scheduled_job_id (str) — معرّف المهمة المجدولة.
  • namespace (str، اختياري) — المجال (namespace) الذي يوجد فيه Job المجدول. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

حذف مهمة حساب مجدولة على بنية Hugging Face التحتية.

delete_space_secret

< >

( repo_id: strkey: strtoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم تحديثه. مثال: "bigcode/in-the-stack".
  • key (str) — المفتاح السري. مثال: "GITHUB_API_KEY".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يحذف سراً من مساحة.

تتيح لك المفاتيح السرية تعيين مفاتيح أو رموز سرية لمساحة دون الحاجة إلى تضمينها في الكود. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

delete_space_variable

< >

( repo_id: strkey: strtoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم تحديثه. مثال: "bigcode/in-the-stack".
  • key (str) — مفتاح المتغير. مثال: "MODEL_REPO_ID"
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يحذف متغيّرًا من مساحة.

تتيح المتغيرات تعيين متغيرات البيئة لمساحة دون الحاجة إلى ترميزها بشكل ثابت. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

delete_space_volumes

< >

( repo_id: strtoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المساحة (Space) التي سيتم تحديثها. مثال: "username/my-space".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

BadRequestError

  • BadRequestError — إذا لم يكن لدى المساحة أي أحجام مرفقة.

إزالة جميع الأحجام من مساحة.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.delete_space_volumes("username/my-space")

delete_tag

< >

( repo_id: strtag: strtoken: bool | str | None = Nonerepo_type: str | None = None )

المعاملات

  • repo_id (str) — المستودع الذي سيتم حذف وسم منه. مثال: "user/my-cool-model".
  • tag (str) — اسم الوسم المراد حذفه.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنت تضيف وسمًا إلى مجموعة بيانات أو مساحة، أو None أو "model" إذا كنت تضيف وسمًا إلى نموذج. القيمة الافتراضية هي None.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type غير صحيح، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • RevisionNotFoundError — إذا لم يتم العثور على الوسم.

حذف وسم من مستودع على Hub.

delete_webhook

< >

( webhook_id: strtoken: bool | str | None = None ) → None

المعاملات

  • webhook_id (str) — المعرّف الفريد لخطاف الويب الذي سيتم حذفه.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

None

حذف خطاف ويب.

مثال:

>>> from huggingface_hub import delete_webhook
>>> delete_webhook("654bbbc16f2ec14d77f109cc")

disable_space_dev_mode

< >

( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime

المعاملات

  • repo_id (str) — معرّف المساحة (Space) التي تريد تعطيل وضع التطوير فيها. مثال: "Salesforce/BLIP2".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

SpaceRuntime

معلومات وقت التشغيل الخاصة بمساحتك.

يرفع

RepositoryNotFoundError أو HfHubHTTPError أو BadRequestError

  • RepositoryNotFoundError — إذا لم يتم العثور على مساحتك (خطأ 404). على الأرجح أن معرف المستودع repo_id خاطئ، أو أن مساحتك خاصة وأنت غير مصادق.
  • HfHubHTTPError — 403 Forbidden: لا يمكن إلا لمالك مساحة (Space) تحديد وضع التطوير. إذا كنت ترغب في التعامل مع مساحة لا تملكها، فاطلب من المالك ذلك من خلال فتح نقاش (Discussion) أو انسخ المساحة.
  • BadRequestError — إذا كان مساحتك مساحة ثابتة. المساحات الثابتة تعمل دائمًا ولا تُفرض عليها أي رسوم. إذا كنت ترغب في إخفاء مساحة ثابتة، يمكنك تعيينها كخاصة.

تعطيل وضع التطوير على مساحة.

يسهّل وضع التطوير في Spaces عملية تصحيح أخطاء تطبيقك ويجعل تكرار العمل على Spaces أسرع من خلال السماح لك بإعادة تشغيل تطبيقك دون إيقاف حاوية Space نفسها. يتطلب تفعيل وضع التطوير اشتراكًا بخطة PRO أو Team & Enterprise، لكن تعطيله مسموح دائمًا (مثلًا بعد انتهاء صلاحية الاشتراك). راجع https://huggingface.co/docs/hub/spaces-dev-mode لمزيد من التفاصيل.

تعطيل_webhook

< >

( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo

المعاملات

  • webhook_id (str) — المعرّف الفريد لخطاف الويب الذي سيتم تعطيله.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

WebhookInfo

معلومات حول خطاف الويب المعطّل.

تعطيل خطاف ويب (يجعله “معطلاً”).

مثال:

>>> from huggingface_hub import disable_webhook
>>> disabled_webhook = disable_webhook("654bbbc16f2ec14d77f109cc")
>>> disabled_webhook
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    jon=None,
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=True,
)

download_bucket_files

< >

( bucket_id: strfiles: list[tuple[str | BucketFile, str | Path]]raise_on_missing_files: bool = Falsetoken: str | bool | None = None )

المعاملات

  • bucket_id (str) — معرّف الدلو (مثلًا "username/my-bucket").
  • files (list[tuple[Union[str, BucketFile], Union[str, Path]]]) — الملفات التي سيتم تنزيلها كقائمة من الأزواج (المصدر، الوجهة). راجع الوصف أعلاه لمعرفة تفاصيل التنسيق.
  • raise_on_missing_files (bool, اختياري) — إذا كان True، فسيتم رفع EntryNotFoundError عندما لا يوجد الملف المطلوب في الدلو. إذا كان False (الافتراضي)، يتم تجاوز الملفات المفقودة مع تحذير.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

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

Files input is a list of (remote file, local file) tuples where remote file is either the path of the file in the bucket or a BucketFile object, and local file is the destination path on the local filesystem. When passing a BucketFile object (obtained from list_bucket_tree()), the method will skip the metadata fetching step and directly download the files.

مثال:

>>> from huggingface_hub import download_bucket_files

>>> download_bucket_files(
...     bucket_id="username/my-bucket",
...     files=[
...         ("models/model.safetensors", "./local/model.safetensors"),
...         ("config.json", "./local/config.json"),
...     ],
... )
>>> from huggingface_hub import download_bucket_files

>>> parquet_files = [file for file in list_bucket_tree(bucket_id="username/my-bucket") if file.path.endswith(".parquet")]
>>> download_bucket_files(
...     bucket_id="username/my-bucket",
...     files=[(file, f"./local/{file.path}") for file in parquet_files],
... )

duplicate_repo

< >

( from_id: strto_id: str | None = Nonerepo_type: str | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonetoken: bool | str | None = Noneexist_ok: bool = Falseresource_group_id: str | None = Nonespace_hardware: SpaceHardware | None = Nonespace_sleep_time: int | None = Nonespace_secrets: list[dict[str, str]] | None = Nonespace_variables: list[dict[str, str]] | None = Nonespace_volumes: list[Volume] | None = None ) → DuplicatedRepoUrl

المعاملات

  • from_id (str) — معرّف المستودع الذي سيتم نسخه. مثال: "openai/gdpval".
  • to_id (str، اختياري) — معرّف المستودع الجديد. مثال: "myorg/my-gdpval". إذا لم يُقدَّم، فسيحمل المستودع الجديد نفس اسم المستودع الأصلي، لكن ضمن حسابك.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنت تنسخ مجموعة بيانات أو مساحة، أو None أو "model" إذا كنت تنسخ نموذجًا. القيمة الافتراضية هي None.
  • private (bool، اختياري) — ما إذا كان يجب أن يكون المستودع الجديد خاصًا أم لا. الافتراضي هو نفس مستوى الخصوصية للمستودع الأصلي. لا يمكن تمريره مع visibility.
  • visibility (Literal["public", "private", "protected"], اختياري) — رؤية المستودع الجديد. يمكن أن تكون "public" أو "private"، أو "protected" لـ Spaces. القيمة الافتراضية هي نفس رؤية المستودع الأصلي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • exist_ok (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فلا يتم رفع خطأ إذا كان المستودع موجودًا مسبقًا.
  • resource_group_id (str, اختياري) — مجموعة الموارد التي سيتم إنشاء المستودع الجديد فيها. مجموعات الموارد متاحة فقط لمنظمات Enterprise Hub، وتتيح تحديد أعضاء المنظمة الذين يمكنهم الوصول إلى المورد. يمكن العثور على معرّف مجموعة الموارد في عنوان URL لصفحة المورد على Hub (مثل "66670e5163145ca562cb1988"). لمعرفة المزيد حول مجموعات الموارد، راجع https://huggingface.co/docs/hub/en/security-resource-groups.
  • space_hardware (SpaceHardware أو str، اختياري) — اختيار العتاد إذا كان repo_type هو “space”. مثال: "t4-medium". راجع SpaceHardware للحصول على قائمة كاملة.
  • space_sleep_time (int, اختياري) — عدد ثوانٍ من عدم النشاط التي يجب انتظارها قبل وضع Space في وضع السكون. اضبطه على -1 إذا لم ترغب في أن يدخل Space الخاص بك في وضع السكون (وهو السلوك الافتراضي للأجهزة المُحدَّثة). أما بالنسبة للأجهزة المجانية، فلا يمكنك ضبط وقت السكون (القيمة ثابتة عند 48 ساعة من عدم النشاط). ينطبق هذا فقط إذا كان repo_type هو “space”. راجع https://huggingface.co/docs/hub/spaces-gpus#sleep-time لمزيد من التفاصيل.
  • space_secrets (list[dict[str, str]]، اختياري) — قائمة بمفاتيح الأسرار التي يجب ضبطها في مساحتك. كل عنصر يكون على الشكل {"key": ..., "value": ..., "description": ...} حيث أن الوصف اختياري. لا ينطبق إلا إذا كان repo_type هو “space”. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets.
  • space_variables (list[dict[str, str]]، اختياري) — قائمة متغيرات البيئة العامة التي سيتم ضبطها في مساحتك. كل عنصر يكون على شكل {"key": ..., "value": ..., "description": ...} حيث يكون الوصف اختياريًا. ينطبق فقط إذا كان repo_type هو “space”. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables.
  • space_volumes (list[Volume], اختياري) — قائمة من كائنات Volume تُثبَّت في المساحة عند وقت التكرار. يحتوي كل حجم على type ("bucket"، "model"، "dataset"، أو "space")، وsource (معرّف المستودع أو الدلو)، وmount_path (المسار داخل الحاوية)، وحقول اختيارية revision، read_only، وpath. لا ينطبق إلا إذا كان repo_type هو “space”.

يعيد

DuplicatedRepoUrl

رابط المستودع الذي تم إنشاؤه حديثاً. القيمة هي فئة فرعية من RepoUrl (ومن str) تحتوي على سمات مثل endpoint، repo_type، repo_id وfiles_copy_pending.

يرفع

RepositoryNotFoundError أو HfHubHTTPError

  • RepositoryNotFoundError — إذا تعذّر العثور على أحد from_id أو to_id. قد يكون السبب عدم وجوده، أو لأنه مُعيّن على private ولا تملك صلاحية الوصول إليه.
  • HfHubHTTPError — إذا أعادت واجهة HuggingFace البرمجية خطأ

نسخ مستودع على الهاب (نموذج، مجموعة بيانات، أو مساحة).

يؤدي هذا إلى نسخ على جانب الخادم يحافظ على سجل git الكامل وكائنات LFS دون الحاجة إلى دورة تنزيل/رفع محلية.

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

مثال:

>>> from huggingface_hub import duplicate_repo

# Duplicate a model to your account
>>> repo_url = duplicate_repo("google/gemma-7b")
>>> repo_url
RepoUrl('https://huggingface.co/nateraw/gemma-7b',...)
>>> repo_url.files_copy_pending
True

# Duplicate a dataset with a custom name
>>> duplicate_repo("openai/gdpval", to_id="myorg/my-gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/myorg/my-gdpval',...)

# Duplicate a Space with custom hardware
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", space_hardware="t4-medium")
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

تعديل تعليق المناقشة

< >

( repo_id: strdiscussion_num: intcomment_id: strnew_content: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • discussion_num (int) — رقم المناقشة أو طلب السحب. يجب أن يكون عددًا صحيحًا موجبًا تمامًا.
  • comment_id (str) — معرّف التعليق الذي تريد تحريره.
  • new_content (str) — المحتوى الجديد للتعليق. تدعم التعليقات تنسيق Markdown.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

تعليق المناقشة

التعليق المُعدَّل

يُحرّر تعليقًا على نقاش / طلب سحب.

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

enable_space_dev_mode

< >

( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime

المعاملات

  • repo_id (str) — معرّف المساحة (Space) التي سيتم تفعيل وضع التطوير لها. مثال: "Salesforce/BLIP2".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

SpaceRuntime

معلومات وقت التشغيل الخاصة بمساحتك.

يرفع

RepositoryNotFoundError أو HfHubHTTPError أو BadRequestError

  • RepositoryNotFoundError — إذا لم يتم العثور على مساحتك (خطأ 404). على الأرجح أن معرف المستودع repo_id خاطئ، أو أن مساحتك خاصة وأنت غير مصادق.
  • HfHubHTTPError — 403 Forbidden: لا يمكن إلا لمالك مساحة (Space) تحديد وضع التطوير. إذا كنت ترغب في التعامل مع مساحة لا تملكها، فاطلب من المالك ذلك من خلال فتح نقاش (Discussion) أو انسخ المساحة.
  • BadRequestError — إذا كان مساحتك مساحة ثابتة. المساحات الثابتة تعمل دائمًا ولا تُفرض عليها أي رسوم. إذا كنت ترغب في إخفاء مساحة ثابتة، يمكنك تعيينها كخاصة.

تفعيل وضع التطوير على مساحة.

يسهّل وضع التطوير في Spaces عملية تصحيح أخطاء تطبيقك ويجعل التكرار على Spaces أسرع من خلال السماح لك بإعادة تشغيل تطبيقك دون إيقاف حاوية Space نفسها. يتوفر هذا الميزة كجزء من خطة PRO أو Team & Enterprise. راجع https://huggingface.co/docs/hub/spaces-dev-mode لمزيد من التفاصيل.

enable_webhook

< >

( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo

المعاملات

  • webhook_id (str) — المعرّف الفريد لخطاف الويب الذي سيتم تفعيله.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

WebhookInfo

معلومات حول خطاف الويب المُفعّل.

تفعيل خطاف ويب (يجعله “نشطاً”).

مثال:

>>> from huggingface_hub import enable_webhook
>>> enabled_webhook = enable_webhook("654bbbc16f2ec14d77f109cc")
>>> enabled_webhook
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    job=None,
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=False,
)

fetch_job_logs

< >

( job_id: strnamespace: str | None = Nonefollow: bool = Falsetail: int | None = Nonetoken: bool | str | None = None )

المعاملات

  • job_id (str) — معرّف المهمة.
  • namespace (str، اختياري) — المجال (namespace) الذي يعمل فيه Job. القيمة الافتراضية هي مجال المستخدم الحالي.
  • follow (bool، اختياري) — إذا كان True، يتم بث السجلات في الوقت الفعلي حتى اكتمال المهمة (مع حجب). إذا كان False (الافتراضي)، يتم جلب السجلات المتاحة حاليًا فقط والعودة فورًا (بدون حجب).
  • tail (int, اختياري) — الحد الأقصى لعدد الأسطر التي تُعاد من السجلات. عند دمجه مع follow=True، يبدأ من آخر N أسطر ويستمر في بث السجلات الجديدة. عند follow=False، يعيد فقط آخر N أسطر من السجلات المتاحة حاليًا.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

جلب جميع السجلات من مهمة حوسبة على بنية Hugging Face التحتية.

مثال:

>>> from huggingface_hub import fetch_job_logs, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])
>>> for log in fetch_job_logs(job_id=job.id):
...     print(log)
Hello from HF compute!

>>> # Non-blocking: fetch only currently available logs
>>> for log in fetch_job_logs(job_id=job.id, follow=False):
...     print(log)

>>> # Stream logs starting from the last 100 lines
>>> for log in fetch_job_logs(job_id=job.id, follow=True, tail=100):
...     print(log)

fetch_job_metrics

< >

( job_id: strnamespace: str | None = Nonefollow: bool = Falsetoken: bool | str | None = None )

المعاملات

  • job_id (str) — معرّف المهمة.
  • namespace (str، اختياري) — المجال (namespace) الذي يعمل فيه Job. القيمة الافتراضية هي مجال المستخدم الحالي.
  • follow (bool، اختياري) — إذا كان True، يتم بث المقاييس في الوقت الفعلي حتى اكتمال المهمة (مع حجب). إذا كان False (الافتراضي)، يتم جلب المقاييس الحالية فقط والعودة (بدون حجب).
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

جلب المقاييس الحية من مهمة حساب على بنية Hugging Face التحتية.

مثال:

>>> from huggingface_hub import fetch_job_metrics, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"], flavor="a10g-small")
>>> for metrics in fetch_job_metrics(job_id=job.id):
...     print(metrics)
{
    "cpu_usage_pct": 0,
    "cpu_millicores": 3500,
    "memory_used_bytes": 1306624,
    "memory_total_bytes": 15032385536,
    "rx_bps": 0,
    "tx_bps": 0,
    "gpus": {
        "882fa930": {
            "utilization": 0,
            "memory_used_bytes": 0,
            "memory_total_bytes": 22836000000
        }
    },
    "replica": "57vr7"
}

>>> # Stream metrics until the job completes
>>> for metrics in fetch_job_metrics(job_id=job.id, follow=True):
...     print(metrics)

fetch_space_logs

< >

( repo_id: strbuild: bool = Falsefollow: bool = Falsetoken: bool | str | None = None ) → Iterable[str]

المعاملات

  • repo_id (str) — معرّف المساحة. مثال: "bigcode/in-the-stack".
  • build (bool، اختياري، الافتراضي False) — إذا كان True، يتم جلب سجلات بناء الحاوية (مفيد عندما يكون المساحة عالقة في BUILD_ERROR). إذا كان False (الافتراضي)، يتم جلب سجلات التشغيل، أي stdout/stderr للتطبيق قيد التشغيل.
  • follow (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، يتم بث السجلات في الوقت الفعلي (مع الحجب) حتى يغلق الخادم البث أو يتم رفع KeyboardInterrupt. إذا كانت False (الافتراضي)، يتم جلب السجلات المخزنة مؤقتًا حاليًا فقط والعودة فورًا (بدون حجب، مثل docker logs).
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. الافتراضي هو الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

Iterable[str]

مولّد يُنتج أسطر السجلات (log lines) كلما أصبحت متاحة.

جلب سجلات التشغيل أو البناء لمساحة على Hub.

يُفيد في تصحيح أخطاء مساحة (Space) تفشل في البناء أو تنهار أثناء التشغيل، لا سيما عند العمل من خلال سكربت أو سير عمل وكيلي (agentic workflow) حيث لا يكون الاطلاع على السجلات عبر المتصفح خيارًا متاحًا.

مثال:

>>> from huggingface_hub import fetch_space_logs
>>> # Non-blocking: print currently available run logs and exit.
>>> for line in fetch_space_logs("username/my-space"):
...     print(line, end="")

>>> # Debug a build failure:
>>> for line in fetch_space_logs("username/my-space", build=True):
...     print(line, end="")

>>> # Stream run logs until the server closes the stream.
>>> for line in fetch_space_logs("username/my-space", follow=True):
...     print(line, end="")

file_exists

< >

( repo_id: strfilename: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: str | bool | None = None )

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • filename (str) — اسم الملف الذي سيتم فحصه، على سبيل المثال: "config.json"
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنت تستخرج معلومات المستودع من مجموعة بيانات أو مساحة، أو None أو "model" إذا كنت تستخرج معلومات المستودع من نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — إصدار المستودع الذي سيتم منه جلب المعلومات. الافتراضي هو الفرع "main".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يتحقق من وجود ملف في مستودع على Hugging Face Hub.

أمثلة:

>>> from huggingface_hub import file_exists
>>> file_exists("bigcode/starcoder", "config.json")
True
>>> file_exists("bigcode/starcoder", "not-a-file")
False
>>> file_exists("bigcode/not-a-repo", "config.json")
False

get_bucket_file_metadata

< >

( bucket_id: strremote_path: strtoken: str | bool | None = None ) → BucketFileMetadata

المعاملات

  • bucket_id (str) — معرّف الدلو (مثلًا "username/my-bucket").
  • remote_path (str) — مسار الملف داخل الدلو.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

BucketFileMetadata

ملف البيانات الوصفية الذي يحتوي على حجم المعلومات وxet.

جلب بيانات الوصف الخاصة بملف في دلو.

مثال:

>>> from huggingface_hub import get_bucket_file_metadata
>>> metadata = get_bucket_file_metadata(
...     bucket_id="username/my-bucket",
...     remote_path="models/model.safetensors",
... )
>>> metadata.size
42000

get_bucket_paths_info

< >

( bucket_id: strpaths: Iterable[str]token: str | bool | None = None ) → Iterable[BucketFile]

المعاملات

  • bucket_id (str) — معرّف الدلو (مثلًا "username/my-bucket").
  • paths (Iterable[str]) — المسارات التي سيتم الحصول على معلومات عنها. إذا لم يكن المسار موجودًا، يتم تجاهله دون رفع استثناء. يتم دعم مسارات الملفات فقط.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[BucketFile]

معلومات حول المسارات، كقابلة للتكرار من كائنات BucketFile.

احصل على معلومات حول مسارات الدلو.

تتم الاستدعاءات على دفعات من 1000 مسار. وتُقدَّم النتائج فور استلامها.

مثال:

>>> from huggingface_hub import get_bucket_paths_info
>>> paths_info = get_bucket_paths_info("username/my-bucket", ["file.txt", "checkpoints/model.safetensors"])
>>> for info in paths_info:
...     print(info)
BucketFile(type='file', path='file.txt', size=2379, xet_hash='96e637d9665bd35477b1908a23f2e254edfba0618dbd2d62f90a6baee7d139cf', mtime=datetime.datetime(2024, 9, 25, 15, 31, 2, 346000, tzinfo=datetime.timezone.utc))
BucketFile(type='file', path='checkpoints/model.safetensors', size=2408828, xet_hash='3ed0e9fefe788ddd61d1e26eba67057e9740a064b009256fbafadf6bb95785ca', mtime=datetime.datetime(2024, 9, 25, 15, 31, 2, 346000, tzinfo=datetime.timezone.utc))

get_collection

< >

( collection_slug: strtoken: bool | str | None = None )

المعاملات

  • collection_slug (str) — اسم الرابط (Slug) الخاص بالمجموعة في Hub. مثال: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يحصل على معلومات حول مجموعة على Hub.

يعيد: Collection

مثال:

>>> from huggingface_hub import get_collection
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
>>> collection.title
'Recent models'
>>> len(collection.items)
37
>>> collection.items[0]
CollectionItem(
    item_object_id='651446103cd773a050bf64c2',
    item_id='TheBloke/U-Amethyst-20B-AWQ',
    item_type='model',
    position=88,
    note=None
)

get_dataset_leaderboard

< >

( repo_id: strbase_model_only: bool | None = Nonetoken: bool | str | None = Nonetimeout: float | None = None ) → list[DatasetLeaderboardEntry]

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /. على سبيل المثال: "allenai/olmOCR-bench".
  • base_model_only (bool أو None، اختياري) — بشكل افتراضي، تتضمن لوحة المتصدرين فقط النماذج التي لا تملك علاقة base_model معلنة (أي المستودعات الأصلية/الجذرية)، بما يتوافق مع عرض لوحة المتصدرين الافتراضي في Hub. تُستبعد المستودعات المُحسَّنة أو المشتقة التي تعلن عن نموذج أب. مرّر base_model_only=False لتعطيل هذا المرشّح وتضمين كل نتيجة مُرسَلة، بغضّ النظر عما إذا كان النموذج يعلن عن علاقة نموذج أساسي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • timeout (float، اختياري) — ما إذا كان يجب تعيين مهلة زمنية للطلب الموجّه إلى Hub.

يعيد

list[DatasetLeaderboardEntry]

قائمة من كائنات DatasetLeaderboardEntry تمثل إدخالات لوحة الصدارة، مرتبة حسب الترتيب.

احصل على لوحة الصدارة لمجموعة بيانات على Hub.

ترتّب لوحة الصدارة النماذج بناءً على درجات تقييمها على مجموعة البيانات المرجعية المعطاة. لا تتوفر لوحات صدارة لجميع مجموعات البيانات — بل فقط لمجموعات البيانات المرجعية التي تم إرسال نتائج تقييم إليها. وهذا يمنح منظوراً يركّز على مجموعة البيانات للدرجات؛ أما للحصول على منظور يركّز على النموذج، فاستخدم model_info() مع expand=["evalResults"].

يرفع الأخطاء التالية:

  • RepositoryNotFoundError إذا تعذّر العثور على المستودع. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • HfHubHTTPError إذا لم يكن للمجموعة بيانات لوحة صدارة.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> leaderboard = api.get_dataset_leaderboard("allenai/olmOCR-bench")
>>> leaderboard[0].model_id
'datalab-to/chandra-ocr-2'
>>> leaderboard[0].rank
1

# Include fine-tuned / derivative models too
>>> full_leaderboard = api.get_dataset_leaderboard("allenai/olmOCR-bench", base_model_only=False)

get_dataset_tags

< >

( )

قائمة جميع وسوم البيانات الصالحة ككائن مساحة أسماء متداخلة.

get_discussion_details

< >

( repo_id: strdiscussion_num: intrepo_type: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • discussion_num (int) — رقم المناقشة أو طلب السحب. يجب أن يكون عددًا صحيحًا موجبًا تمامًا.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يجلب تفاصيل المناقشة / طلب الدمج من Hub.

يعيد: DiscussionWithDetails

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

get_full_repo_name

< >

( model_id: strorganization: str | None = Nonetoken: bool | str | None = None ) → str

المعاملات

  • model_id (str) — اسم النموذج.
  • organization (str، اختياري) — إذا تم تمريره، فسيكون اسم المستودع ضمن نطاق المنظمة بدلاً من نطاق المستخدم.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

str

اسم المستودع في مساحة اسم المستخدم ({username}/{model_id}) إذا لم يتم تمرير منظمة، وفي مساحة اسم المنظمة ({organization}/{model_id}) في حال العكس.

يعيد اسم المستودع لمعرّف نموذج معيّن ومنظمة اختيارية.

get_hf_file_metadata

< >

( url: strtoken: bool | str | None = Nonetimeout: float | None = 10 )

المعاملات

  • url (str) — عنوان ملف، مثل ما يُعاد بواسطة hf_hub_url().
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • timeout (float، اختياري، القيمة الافتراضية 10) — عدد الثواني التي يجب انتظارها حتى يرسل الخادم البيانات الوصفية قبل التوقف عن المحاولة.

جلب بيانات الوصف (metadata) لملف مُنظَّم بالإصدارات على Hub لعنوان URL معيّن.

get_inference_endpoint

< >

( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

المعاملات

  • name (str) — اسم نقطة الاستدلال (Inference Endpoint) التي تريد استرداد معلومات عنها.
  • namespace (str، اختياري) — المجال الذي يقع فيه Inference Endpoint. الافتراضي هو المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

InferenceEndpoint

معلومات حول نقطة الاستدلال المطلوبة.

احصل على معلومات حول نقطة استنتاج.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.get_inference_endpoint("my-text-to-image")
>>> endpoint
InferenceEndpoint(name='my-text-to-image', ...)

# Get status
>>> endpoint.status
'running'
>>> endpoint.url
'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud'

# Run inference
>>> endpoint.client.text_to_image(...)

get_model_tags

< >

( )

قائمة جميع علامات النموذج الصالحة ككائن مساحة أسماء متداخلة

get_organization_overview

< >

( organization: strtoken: bool | str | None = None ) → Organization

المعاملات

  • organization (str) — اسم المنظمة التي تريد الحصول على نظرة عامة عنها.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للتوثيق (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء التوثيق، مرّر False.

يعيد

Organization

كائن Organization يحتوي على نظرة عامة على المنظمة.

يرفع

HTTPError

  • HTTPError — HTTP 404 إذا لم يكن التنظيم موجودًا على Hub.

احصل على نظرة عامة على منظمة في Hub.

get_paths_info

< >

( repo_id: strpaths: list[str] | strexpand: bool = Falserevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → list[Union[RepoFile, RepoFolder]]

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • paths (Union[list[str], str]، اختياري) — المسارات التي سيتم الحصول على معلومات عنها. إذا لم يكن المسار موجودًا، يتم تجاهله دون رفع استثناء.
  • expand (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب جلب مزيد من المعلومات حول المسارات (مثل آخر التزامن ونتائج فحص أمان الملفات). هذه العملية أكثر تكلفة على الخادم، لذا تُعاد 50 نتيجة فقط لكل صفحة (بدلاً من 1000). بما أن ترقيم الصفحات مُنفَّذ في huggingface_hub، فإن الأمر شفاف بالنسبة لك باستثناء الوقت الذي يستغرقه الحصول على النتائج.
  • revision (str، اختياري) — إصدار المستودع الذي سيتم منه جلب المعلومات. الافتراضي هو الفرع "main".
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم منه جلب المعلومات ("model" أو "dataset" أو "space"). الافتراضي هو "model".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

list[Union[RepoFile, RepoFolder]]

معلومات حول المسارات، كقائمة من كائنات RepoFile وRepoFolder.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type خاطئ، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • RevisionNotFoundError — إذا لم يتم العثور على المراجعة (خطأ 404) في المستودع.

احصل على معلومات حول مسارات المستودع.

مثال:

>>> from huggingface_hub import get_paths_info
>>> paths_info = get_paths_info("allenai/c4", ["README.md", "en"], repo_type="dataset")
>>> paths_info
[
    RepoFile(path='README.md', size=2379, blob_id='f84cb4c97182890fc1dbdeaf1a6a468fd27b4fff', lfs=None, last_commit=None, security=None),
    RepoFolder(path='en', tree_id='dc943c4c40f53d02b31ced1defa7e5f438d5862e', last_commit=None)
]

get_repo_discussions

< >

( repo_id: strauthor: str | None = Nonediscussion_type: constants.DiscussionTypeFilter | None = Nonediscussion_status: constants.DiscussionStatusFilter | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterator[Discussion]

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • author (str، اختياري) — مرر قيمةً لتصفية حسب مؤلف النقاش. تعني None عدم وجود تصفية. الافتراضي هو None.
  • discussion_type (str، اختياري) — اضبطه على "pull_request" لجلب طلبات الدمج فقط، وعلى "discussion" لجلب المناقشات فقط. اضبطه على "all" أو None لجلب كلا النوعين. القيمة الافتراضية هي None.
  • discussion_status (str, اختياري) — اضبطه على "open" (أو "closed") لجلب المناقشات المفتوحة فقط (أو المغلقة فقط). اضبطه على "all" أو None لجلب كلا النوعين. القيمة الافتراضية هي None.
  • repo_type (str، اختياري) — يُضبط على "dataset" أو "space" عند الجلب من مجموعة بيانات أو مساحة، أو None أو "model" عند الجلب من نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterator[Discussion]

مُتكرِّر (iterator) من كائنات Discussion.

يجلب النقاشات وطلبات الدمج للمستودع المحدد.

مثال:

جمع جميع مناقشات المستودع في قائمة:

>>> from huggingface_hub import get_repo_discussions
>>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased"))

التكرار على مناقشات مستودع:

>>> from huggingface_hub import get_repo_discussions
>>> for discussion in get_repo_discussions(repo_id="bert-base-uncased"):
...     print(discussion.num, discussion.title)

get_safetensors_metadata

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsRepoMetadata

المعاملات

  • repo_id (str) — اسم مستخدم أو منظمة واسم مستودع مفصولان بـ /.
  • repo_type (str، اختياري) — يُضبط على "dataset" أو "space" إذا كان الملف في مجموعة بيانات أو مساحة، أو None أو "model" إذا كان في نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — مراجعة git لجلب الملف منها. يمكن أن تكون اسم فرع، أو وسم، أو تجزئة commit. الافتراضي هو رأس فرع "main".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • timeout (float، اختياري، القيمة الافتراضية 10) — عدد الثواني التي يجب انتظارها حتى يرسل الخادم البيانات قبل التوقف، وتُمرَّر إلى كل طلب يجلب ترويسة ملف safetensors. اضبطها على None لتعطيل مهلة الانتظار (غير موصى به، إذ قد يؤدي توقف الاتصال إلى تعليق الاستدعاء بشكل غير محدود).

يعيد

SafetensorsRepoMetadata

معلومات تتعلق بمستودع safetensors.

يرفع

NotASafetensorsRepoError أو SafetensorsParsingError

  • NotASafetensorsRepoError — إذا لم يكن المستودع مستودع safetensors، أي أنه لا يحتوي على ملف model.safetensors أو ملف model.safetensors.index.json.
  • SafetensorsParsingError — إذا تعذّر تحليل ترويسة ملف safetensors بشكل صحيح.

تحليل البيانات الوصفية لمستودع safetensors على Hub.

نبدأ أولاً بالتحقق مما إذا كان المستودع يحتوي على ملف safetensors واحد أو مستودع safetensors مقسّم إلى أجزاء. إذا كان الملف safetensors واحداً، فإننا نحلل البيانات الوصفية من هذا الملف. أما إذا كان المستودع safetensors مقسّماً إلى أجزاء، فإننا نحلل البيانات الوصفية من ملف الفهرس ثم نحلل البيانات الوصفية من كل جزء.

لتحليل البيانات الوصفية من ملف safetensors واحد، استخدم parse_safetensors_file_metadata(). للحصول على ترويسة كل شريحة من نموذج مقسّم على main في طلب واحد، استخدم get_sharded_safetensors_metadata().

لمزيد من التفاصيل حول صيغة safetensors، راجع https://huggingface.co/docs/safetensors/index#format.

مثال:

# Parse repo with single weights file
>>> metadata = get_safetensors_metadata("bigscience/bloomz-560m")
>>> metadata
SafetensorsRepoMetadata(
    metadata=None,
    sharded=False,
    weight_map={'h.0.input_layernorm.bias': 'model.safetensors', ...},
    files_metadata={'model.safetensors': SafetensorsFileMetadata(...)}
)
>>> metadata.files_metadata["model.safetensors"].metadata
{'format': 'pt'}

# Parse repo with sharded model
>>> metadata = get_safetensors_metadata("bigscience/bloom")
Parse safetensors files: 100%|██████████████████████████████████████████| 72/72 [00:12<00:00,  5.78it/s]
>>> metadata
SafetensorsRepoMetadata(metadata={'total_size': 352494542848}, sharded=True, weight_map={...}, files_metadata={...})
>>> len(metadata.files_metadata)
72  # All safetensors files have been fetched

# Parse repo with sharded model
>>> get_safetensors_metadata("runwayml/stable-diffusion-v1-5")
NotASafetensorsRepoError: 'runwayml/stable-diffusion-v1-5' is not a safetensors repo. Couldn't find 'model.safetensors.index.json' or 'model.safetensors' files.

get_sharded_safetensors_metadata

< >

( repo_id: strfilename: str = 'model.safetensors.index.json'token: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsRepoMetadata

المعاملات

  • repo_id (str) — اسم مستخدم أو منظمة واسم مستودع مفصولان بـ /.
  • filename (str, اختياري) — مسار ملف فهرس safetensors في المستودع. القيمة الافتراضية هي "model.safetensors.index.json".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • timeout (float، اختياري، القيمة الافتراضية 10) — عدد الثواني التي يجب انتظارها حتى يرسل الخادم البيانات قبل التوقف. اضبطها على None لتعطيل مهلة الانتهاء (غير موصى به، إذ قد يؤدي اتصال متوقف إلى تعليق الاستدعاء بشكل غير محدود).

يعيد

SafetensorsRepoMetadata

نفس البيانات الوصفية الموجودة في get_safetensors_metadata().

احصل على بيانات الوصف لكل شريحة من نموذج safetensors المقسّم على main من Hugging Face Hub في طلب واحد، بدلاً من أن يقوم get_safetensors_metadata() بتحليل ترويسة كل شريحة على حدة. متوفر على Hugging Face Hub فقط.

مثال:

>>> metadata = get_sharded_safetensors_metadata("HuggingFaceH4/zephyr-7b-beta")
>>> len(metadata.files_metadata)
8

get_space_runtime

< >

( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم تحديثه. مثال: "bigcode/in-the-stack".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

SpaceRuntime

معلومات وقت التشغيل حول مساحة (Space) تتضمن مرحلة المساحة (Space stage) والأجهزة (hardware).

يحصل على معلومات وقت التشغيل الخاصة بمساحة.

get_space_secrets

< >

( repo_id: strtoken: bool | str | None = None ) → dict[str, SpaceSecret]

المعاملات

  • repo_id (str) — معرّف المستودع المطلوب الاستعلام عنه. مثال: "bigcode/in-the-stack".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

dict[str, SpaceSecret]

قاموس من كائنات SpaceSecret مفهرس باسم السر.

يحصل على جميع الأسرار من مساحة.

القيم السرية قابلة للكتابة فقط ولا يمكن قراءتها مرة أخرى. يتم إرجاع المفتاح والوصف ووقت آخر تحديث فقط.

تتيح لك المفاتيح السرية تعيين مفاتيح أو رموز سرية لمساحة دون الحاجة إلى تضمينها في الكود. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.get_space_secrets("username/my-space")
{'HF_TOKEN': SpaceSecret(key='HF_TOKEN', description='...', updated_at=datetime.datetime(...))}

get_space_variables

< >

( repo_id: strtoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع المطلوب الاستعلام عنه. مثال: "bigcode/in-the-stack".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يحصل على جميع المتغيرات من مساحة.

تتيح المتغيرات تعيين متغيرات البيئة لمساحة دون الحاجة إلى ترميزها بشكل ثابت. لمزيد من التفاصيل، راجع https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

get_user_overview

< >

( username: strtoken: bool | str | None = None ) → User

المعاملات

  • username (str) — اسم المستخدم الخاص بالمستخدم الذي تريد الحصول على نظرة عامة عنه.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

User

كائن User يحتوي على نظرة عامة على المستخدم.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 إذا لم يكن المستخدم موجودًا على Hub.

احصل على نظرة عامة على مستخدم في Hub.

get_webhook

< >

( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo

المعاملات

  • webhook_id (str) — المعرّف الفريد للـ webhook المطلوب.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

WebhookInfo

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

احصل على webhook باستخدام المعرّف الخاص به.

مثال:

>>> from huggingface_hub import get_webhook
>>> webhook = get_webhook("654bbbc16f2ec14d77f109cc")
>>> print(webhook)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    job=None,
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    secret="my-secret",
    domains=["repo", "discussion"],
    disabled=False,
)

get_zero_gpu_quota

< >

( token: bool | str | None = None ) → ZeroGpuQuota

المعاملات

  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). يجب أن يكون الرمز الدقيق (fine-grained) مُنحًا إذن “Billing > Read billing usage and payment method status” وأن يكون رمز OAuth مُنحًا نطاق read-billing.

يعيد

ZeroGpuQuota

حصة ZeroGPU للمستخدم الموثّق.

احصل على حصة ZeroGPU للمستخدم الموثّق.

يُفيد في تتبع استخدام ZeroGPU عند استدعاء مساحات ZeroGPU برمجياً (على سبيل المثال، من تطبيق أو وكيل أو خادم MCP). راجع https://huggingface.co/docs/hub/spaces-zerogpu لمزيد من التفاصيل.

مثال:

>>> from huggingface_hub import get_zero_gpu_quota
>>> quota = get_zero_gpu_quota()
>>> quota
ZeroGpuQuota(base=2400, remaining=1810, resets_at=datetime.datetime(2026, 9, 30, 9, 12, 3, tzinfo=datetime.timezone.utc), overquota_used=0)
>>> print(f"{quota.remaining / 60:.1f} minutes left")
30.2 minutes left

grant_access

< >

( repo_id: struser: strrepo_type: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم منح الوصول إليه.
  • user (str) — اسم المستخدم الخاص بالمستخدم الذي سيتم منحُه الوصول.
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم منح الوصول إليه. يجب أن يكون أحد model أو dataset أو space. الافتراضي هو model.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 إذا لم يكن المستودع محميًا.
  • HfHubHTTPError — HTTP 400 إذا كان لدى المستخدم بالفعل وصول إلى المستودع.
  • HfHubHTTPError — HTTP 403 إذا كان لديك وصول للقراءة فقط إلى المستودع. قد يحدث ذلك إذا لم تكن لديك دور write أو admin في المنظمة التي ينتمي إليها المستودع، أو إذا قمت بتمرير رمز read.
  • HfHubHTTPError — خطأ HTTP 404 إذا لم يكن المستخدم موجودًا على Hub.

منح الوصول إلى مستخدمٍ مستودعٍ محكومٍ محدد.

لا يتطلب منح الوصول أن يرسل المستخدم طلب وصول بنفسه. يُضاف المستخدم تلقائيًا إلى قائمة المقبولين، مما يعني أنه يمكنه تنزيل الملفات. يمكنك إلغاء الوصول الممنوح في أي وقت باستخدام cancel_access_request() أو reject_access_request().

لمزيد من المعلومات حول المستودعات المُقيَّدة، راجع https://huggingface.co/docs/hub/models-gated.

hf_hub_download

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_dir: str | Path | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falsetqdm_class: type[base_tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo

المعاملات

  • repo_id (str) — اسم مستخدم أو منظمة واسم مستودع مفصولان بـ /.
  • filename (str) — اسم الملف في المستودع.
  • subfolder (str، اختياري) — قيمة اختيارية تتوافق مع مجلد داخل المستودع.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنتَ تقوم بتنزيل من مجموعة بيانات أو مساحة، أو None أو "model" إذا كنتَ تقوم بتنزيل من نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — معرّف اختيارية لمراجعة Git يمكن أن يكون اسم فرع، أو وسم، أو تجزئة التزام.
  • cache_dir (str، Path، اختياري) — المسار إلى المجلد الذي تُخزَّن فيه الملفات المؤقتة.
  • local_dir (str أو Path، اختياري) — إذا تم تقديمه، فسيتم وضع الملف المُحمَّل تحت هذا المجلد.
  • force_download (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب تنزيل الملف حتى لو كان موجودًا مسبقًا في ذاكرة التخزين المؤقت المحلية.
  • etag_timeout (float، اختياري، القيمة الافتراضية 10) — عند جلب ETag، عدد الثواني التي يجب انتظارها حتى يرسل الخادم البيانات قبل التوقف، وهي القيمة التي تُمرَّر إلى httpx2.request.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • local_files_only (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فتجنّب تنزيل الملف وعُدّ مسار الملف المخزّن محليًا إذا كان موجودًا.
  • tqdm_class (tqdm، اختياري) — إذا تم توفيره، يُغني عن السلوك الافتراضي لشريط التقدم. يجب أن يرث الحُجج المُمرَّرة من tqdm.auto.tqdm أو يحاكي سلوكه على الأقل. الافتراضي هو شريط تقدم HF المخصص، والذي يمكن تعطيله عن طريق تعيين متغير البيئة HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، يتم تنفيذ تشغيل تجريبي دون تنزيل الملف فعليًا. تُرجع كائنًا من نوع DryRunFileInfo يحتوي على معلومات حول ما كان سيُتنزَّل.

يعيد

str أو DryRunFileInfo

  • إذا كان dry_run=False: المسار المحلي للملف أو، إذا كانت الشبكة معطلة، آخر نسخة من الملف المخزنة مؤقتًا على القرص.
  • إذا كان dry_run=True: كائن DryRunFileInfo يحتوي على معلومات التحميل.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError أو ~utils.RemoteEntryNotFoundError أو LocalEntryNotFoundError أو EnvironmentError أو OSError أو ValueError

  • RepositoryNotFoundError — إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • RevisionNotFoundError — إذا تعذّر العثور على المراجعة التي يجب التحميل منها.
  • ~utils.RemoteEntryNotFoundError — إذا تعذر العثور على الملف المطلوب تنزيله.
  • LocalEntryNotFoundError — إذا كان الاتصال بالشبكة معطلاً أو غير متاح ولم يتم العثور على الملف في ذاكرة التخزين المؤقت.
  • EnvironmentError — إذا كان token=True لكن تعذّر العثور على الرمز.
  • OSError — إذا تعذّر تحديد ETag.
  • ValueError — إذا كانت قيمة بعض المعاملات غير صالحة.

تنزيل ملف محدد إذا لم يكن موجودًا مسبقًا في ذاكرة التخزين المؤقت المحلية.

يبدو تخطيط ملف الكاش الجديد على النحو التالي:

  • تحتوي مجلد التخزين المؤقت على مجلد فرعي واحد لكل repo_id (مُقسَّم حسب نوع المستودع)
  • داخل كل مجلد مستودع:
    • refs هو قائمة بأحدث أزواج المراجعة المعروفة => commit_hash
    • يحتوي blobs على ملفات blobs الفعلية (المُعرَّفة بـ git-sha أو sha256، اعتمادًا على ما إذا كانت ملفات LFS أم لا)
    • تحتوي snapshots على مجلد فرعي واحد لكل commit، ويحتوي كل “commit” على مجموعة فرعية من الملفات التي تم حلّها عند ذلك commit بالتحديد. كل اسم ملف هو رابط رمزي إلى blob عند ذلك commit بالتحديد.
[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

إذا تم توفير local_dir، فسيتم تكرار هيكل الملفات من المستودع في هذا الموقع. عند استخدام هذا الخيار، لن يتم استخدام cache_dir وسيتم إنشاء مجلد .cache/huggingface/ في جذر local_dir لتخزين بعض البيانات الوصفية المتعلقة بالملفات التي تم تنزيلها. على الرغم من أن هذا الآلية ليست قوية مثل نظام التخزين المؤقت الرئيسي، إلا أنها مُحسّنة لسحب أحدث إصدار من المستودع بانتظام.

إخفاء تعليق النقاش

< >

( repo_id: strdiscussion_num: intcomment_id: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • discussion_num (int) — رقم المناقشة أو طلب السحب. يجب أن يكون عددًا صحيحًا موجبًا تمامًا.
  • comment_id (str) — معرّف التعليق الذي تريد تحريره.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

تعليق المناقشة

التعليق المخفي

يخفي تعليقًا على نقاش / طلب سحب.

لا يمكن استرجاع محتوى التعليقات المخفية بعد الآن. إخفاء التعليق إجراء غير قابل للتراجع.

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

inspect_job

< >

( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • job_id (str) — معرّف المهمة.
  • namespace (str، اختياري) — المجال (namespace) الذي يعمل فيه Job. القيمة الافتراضية هي مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

فحص مهمة حساب على بنية Hugging Face التحتية.

مثال:

>>> from huggingface_hub import inspect_job, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])
>>> inspect_job(job_id=job.id)
JobInfo(
    id='68780d00bbe36d38803f645f',
    created_at=datetime.datetime(2025, 7, 16, 20, 35, 12, 808000, tzinfo=datetime.timezone.utc),
    docker_image='python:3.12',
    space_id=None,
    command=['python', '-c', "print('Hello from HF compute!')"],
    arguments=[],
    environment={},
    secrets={},
    flavor='cpu-basic',
    status=JobStatus(stage='RUNNING', message=None)
)

inspect_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • scheduled_job_id (str) — معرّف المهمة المجدولة.
  • namespace (str، اختياري) — المجال (namespace) الذي يوجد فيه Job المجدول. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

فحص مهمة حساب مجدولة على بنية Hugging Face التحتية.

مثال:

>>> from huggingface_hub import inspect_scheduled_job, create_scheduled_job
>>> scheduled_job = create_scheduled_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"], schedule="@hourly")
>>> inspect_scheduled_job(scheduled_job_id=scheduled_job.id)

معلومات_النواة

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonetoken: bool | str | None = None ) → ModelInfo

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • revision (str، اختياري) — إصدار مستودع النواة الذي سيتم منه الحصول على المعلومات.
  • timeout (float، اختياري) — ما إذا كان يجب تعيين مهلة زمنية للطلب الموجّه إلى Hub.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

ModelInfo

معلومات مستودع النواة.

احصل على معلومات حول نواة محددة على huggingface.co.

list_accepted_access_requests

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]

المعاملات

  • repo_id (str) — معرّف المستودع الذي تريد الحصول على طلبات الوصول إليه.
  • repo_type (str، اختياري) — نوع المستودع الذي تريد الحصول على طلبات الوصول له. يجب أن يكون أحد model أو dataset أو space. القيمة الافتراضية هي model.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[AccessRequest]

قابلة للتكرار من كائنات AccessRequest. يحتوي كل عنصر على سمات username، request_id، email، status وtimestamp. إذا كان المستودع المحمي يحتوي على نموذج مخصص، فسيتم ملء سمة fields بإجابات المستخدم.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 إذا لم يكن المستودع محميًا.
  • HfHubHTTPError — HTTP 403 إذا كان لديك وصول للقراءة فقط إلى المستودع. قد يحدث ذلك إذا لم تكن لديك دور write أو admin في المنظمة التي ينتمي إليها المستودع، أو إذا قمت بتمرير رمز read.

احصل على طلبات الوصول المقبولة لمستودع محكوم الوصول محدد.

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

لمزيد من المعلومات حول المستودعات المُقيَّدة، راجع https://huggingface.co/docs/hub/models-gated.

مثال:

>>> from huggingface_hub import list_accepted_access_requests

>>> requests = list(list_accepted_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        request_id='655f3a1c9e6b2d4f8a7c1e05',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='accepted',
        fields=None,
    ),
    ...
]

list_bucket_tree

< >

( bucket_id: strprefix: str | None = Nonerecursive: bool | None = Nonetoken: str | bool | None = None ) → Iterable[Union[BucketFile, BucketFolder]]

المعاملات

  • bucket_id (str) — معرّف الدلو (مثلًا "username/my-bucket").
  • prefix (str، اختياري) — تصفية النتائج إلى الملفات التي يبدأ مسارها بهذا البادئة.
  • recursive (bool، اختياري) — إذا كان True، يتم سرد الملفات بشكل متكرر. إذا كان False (الافتراضي)، يتم سرد الملفات والمجلدات في الجذر فقط.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[Union[BucketFile, BucketFolder]]

قابلة للتكرار من كائنات BucketFile وBucketFolder تحتوي على معلومات الملفات والمجلدات (المسار، وما إلى ذلك).

قائمة الملفات في الدلو.

مثال:

>>> from huggingface_hub import list_bucket_tree
>>> for file_info in list_bucket_tree(bucket_id="username/my-bucket"):
...     print(file_info.path)

>>> # Filter by prefix
>>> for file_info in list_bucket_tree(bucket_id="username/my-bucket", prefix="models/"):
...     print(file_info.path)

list_buckets

< >

( namespace: str | None = Nonesearch: str | None = Nonetoken: bool | str | None = None ) → Iterable[BucketInfo]

المعاملات

  • namespace (str، اختياري) — قائمة بالحاويات (buckets) الموجودة تحت هذا namespace (مستخدم أو منظمة). الافتراضي هو عرض حاويات المستخدم.
  • search (str, اختياري) — نص بحثي لتصفية أسماء الدلاء.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[BucketInfo]

قابلة للتكرار من كائنات BucketInfo.

قائمة الدلاء على Hub ضمن مساحة أسماء معينة.

مثال:

>>> from huggingface_hub import list_buckets
>>> for bucket in list_buckets(): # lists buckets in the user's namespace
...     print(bucket)

>>> for bucket in list_buckets(namespace="huggingface"): # lists buckets in the "huggingface" organization
...     print(bucket)

>>> for bucket in list_buckets(search="my-prefix"): # filter buckets by name
...     print(bucket)

list_collections

< >

( owner: list[str] | str | None = Noneitem: list[str] | str | None = Nonesort: CollectionSort_T | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → Iterable[Collection]

المعاملات

  • owner (list[str] أو str، اختياري) — تصفية حسب اسم مستخدم المالك.
  • item (list[str] أو str، اختياري) — تصفية المجموعات التي تحتوي على عناصر محددة. مثال: "models/teknium/OpenHermes-2.5-Mistral-7B"، "datasets/squad" أو "papers/2311.12983".
  • sort (Literal["lastModified", "trending", "upvotes"], اختياري) — ترتيب المجموعات حسب آخر تعديل، أو الاتجاهات الرائجة، أو الأصوات الإيجابية.
  • limit (int، اختياري) — الحد الأقصى لعدد المجموعات التي سيتم إرجاعها.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[Collection]

قابلة للتكرار من كائنات Collection.

قائمة المجموعات على Huggingface Hub، مع مراعاة بعض عوامل التصفية.

عند سرد المجموعات، يتم اقتصاص قائمة العناصر لكل مجموعة إلى 4 عناصر كحد أقصى. لاسترجاع جميع العناصر من مجموعة، يجب عليك استخدام get_collection().

list_daily_papers

< >

( date: str | None = Nonetoken: bool | str | None = Noneweek: str | None = Nonemonth: str | None = Nonesubmitter: str | None = Nonesort: DailyPapersSort_T | None = Nonep: int | None = Nonelimit: int | None = None ) → Iterable[PaperInfo]

المعاملات

  • date (str، اختياري) — التاريخ بتنسيق ISO (YYYY-MM-DD) الذي سيتم جلب الأوراق اليومية الخاصة به. الافتراضي هو أحدث الأوراق.
  • token (Union[bool, str, None], اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا. لتعطيل المصادقة، مرّر False.
  • week (str، اختياري) — الأسبوع بصيغة ISO (YYYY-Www) الذي سيتم جلب الأوراق اليومية له. مثال: 2025-W09.
  • month (str، اختياري) — الشهر بتنسيق ISO (YYYY-MM) الذي سيتم جلب الأوراق اليومية له. مثال: 2025-02.
  • submitter (str، اختياري) — اسم المستخدم الخاص بالمُقدِّم الذي تُستخدمه لتصفية الأوراق اليومية.
  • sort (Literal["publishedAt", "trending"], اختياري) — ترتيب الفرز للأوراق اليومية. يمكن أن يكون إما حسب publishedAt أو حسب trending. الافتراضي هو "publishedAt"
  • p (int، اختياري) — رقم الصفحة للتقسيم إلى صفحات. القيمة الافتراضية هي 0.
  • limit (int، اختياري) — الحد الأقصى لعدد الأوراق التي سيتم جلبها. القيمة الافتراضية هي 50.

يعيد

Iterable[PaperInfo]

قابلة للتكرار من كائنات huggingface_hub.hf_api.PaperInfo.

قائمة الأوراق اليومية المنشورة في تاريخ معيّن على Hugging Face Hub.

مثال:

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> list(api.list_daily_papers(date="2025-10-29"))

list_dataset_parquet_files

< >

( repo_id: strconfig: str | None = Nonetoken: bool | str | None = None ) → list[DatasetParquetEntry]

المعاملات

  • repo_id (str) — معرّف مستودع مجموعة البيانات (مثل "username/dataset-name").
  • config (str، اختياري) — تصفية حسب اسم الإعداد/المجموعة الفرعية المحددة. عند تقديمه، تُعاد ملفات parquet الخاصة بذلك الإعداد فقط.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

list[DatasetParquetEntry]

قائمة من كائنات DatasetParquetEntry تحتوي على الإعداد (config) والجزء (split) والرابط (url) والحجم (size) لكل ملف parquet.

قائمة ملفات parquet المتاحة لمجموعة بيانات على Hub.

تُحوَّل جميع مجموعات البيانات المستضافة على Hub تلقائيًا إلى Parquet بواسطة Dataset Viewer. تعيد هذه الطريقة قائمة ملفات parquet مع عناوينها (URLs) وإعداداتها (configs) وقسماتها (splits) وأحجامها.

مثال:

>>> from huggingface_hub import list_dataset_parquet_files
>>> list_dataset_parquet_files("lhoestq/demo1")
>>> entries[0]
DatasetParquetEntry(config='default', split='train', url='https://huggingface.co/...', size=5038)

list_datasets

< >

( filter: str | Iterable[str] | None = Noneauthor: str | None = Nonebenchmark: Literal[True] | Literal['official'] | str | None = Nonedataset_name: str | None = Nonegated: bool | None = Nonelanguage_creators: str | list[str] | None = Nonelanguage: str | list[str] | None = Nonemultilinguality: str | list[str] | None = Nonesize_categories: str | list[str] | None = Nonetask_categories: str | list[str] | None = Nonetask_ids: str | list[str] | None = Nonesearch: str | None = Nonesort: DatasetSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandDatasetProperty_T] | None = Nonefull: bool | None = Nonetoken: bool | str | None = None ) → Iterable[DatasetInfo]

المعاملات

  • filter (str أو Iterable[str]، اختياري) — نص أو قائمة من النصوص لتصفية مجموعات البيانات على الحاضنة.
  • author (str، اختياري) — نص يحدد مؤلف مجموعات البيانات المُعاد إرجاعها.
  • benchmark (True، "official"، str، اختياري) — تصفية مجموعات البيانات حسب المعيار. يمكن أن يكون True أو "official" لإرجاع مجموعات بيانات المعايير الرسمية. لضمان التوافق مع الإصدارات المستقبلية، يمكن أن يكون أيضًا نصًا يمثل اسم المعيار (حاليًا، يُدعم “official” فقط).
  • dataset_name (str, اختياري) — نص أو قائمة نصوص يمكن استخدامها لتحديد مجموعات البيانات على الـ Hub باسمها، مثل SQAC أو wikineural
  • gated (bool، اختياري) — قيمة منطقية لتصفية مجموعات البيانات على Hub التي تكون محمية أو غير محمية. افتراضيًا، تُعاد جميع مجموعات البيانات. إذا تم تمرير gated=True، تُعاد فقط مجموعات البيانات المحمية. إذا تم تمرير gated=False، تُعاد فقط مجموعات البيانات غير المحمية.
  • language_creators (str أو List، اختياري) — نص أو قائمة نصوص يمكن استخدامه لتحديد مجموعات البيانات على الـ Hub بطريقة تجميع البيانات، مثل crowdsourced أو machine_generated.
  • language (str أو List، اختياري) — نص أو قائمة نصوص تمثل لغة من حرفين لتصفية مجموعات البيانات على Hub.
  • multilinguality (str أو List، اختياري) — نص أو قائمة نصوص تمثل مرشحًا للمجموعات التي تحتوي على لغات متعددة.
  • size_categories (str أو List، اختياري) — نص أو قائمة نصوص يمكن استخدامها لتحديد مجموعات البيانات على الـ Hub حسب حجم مجموعة البيانات مثل 100K<n<1M أو 1M<n<10M.
  • task_categories (str أو List، اختياري) — نص أو قائمة نصوص يمكن استخدامه لتحديد مجموعات البيانات على الـ Hub حسب المهمة المصممة، مثل audio_classification أو named_entity_recognition.
  • task_ids (str أو List، اختياري) — نص أو قائمة نصوص يمكن استخدامها لتحديد مجموعات البيانات على الـ Hub بناءً على المهمة المحددة مثل speech_emotion_recognition أو paraphrase.
  • search (str، اختياري) — نص ستحتويه مجموعات البيانات المُعادَة.
  • sort (DatasetSort_T, اختياري) — المفتاح الذي يُستخدم لفرز مجموعات البيانات الناتجة. القيم الممكنة هي “created_at” و”downloads” و”last_modified” و”likes” و”trending_score”.
  • limit (int، اختياري) — الحد الأقصى لعدد مجموعات البيانات التي يتم جلبها. إذا تُركت هذه الخانة بقيمة None، فسيتم جلب جميع مجموعات البيانات.
  • expand (list[ExpandDatasetProperty_T], اختياري) — قائمة بالخصائص التي يجب إرجاعها في الاستجابة. عند استخدامه، لن تُرجع إلا الخصائص الموجودة في القائمة. لا يمكن استخدام هذا المعامل إذا تم تمرير full. القيم الممكنة هي "author"، "cardData"، "citation"، "createdAt"، "disabled"، "description"، "downloads"، "downloadsAllTime"، "gated"، "lastModified"، "likes"، "mainSize"، "paperswithcode_id"، "private"، "siblings"، "sha"، "tags"، "trendingScore"، "usedStorage"، و"resourceGroup".
  • full (bool، اختياري) — ما إذا كان سيتم جلب جميع بيانات المجموعة، بما في ذلك last_modified، وcard_data والملفات. قد تحتوي على معلومات مفيدة مثل معرّف PapersWithCode.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[DatasetInfo]

قابلة للتكرار من كائنات huggingface_hub.hf_api.DatasetInfo.

قائمة مجموعات البيانات المستضافة على Huggingface Hub، مع مراعاة بعض عوامل التصفية.

مثال على الاستخدام مع الحجة filter:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all datasets
>>> api.list_datasets()


# List only the text classification datasets
>>> api.list_datasets(filter="task_categories:text-classification")


# List only the datasets in russian for language modeling
>>> api.list_datasets(
...     filter=("language:ru", "task_ids:language-modeling")
... )

# List FiftyOne datasets (identified by the tag "fiftyone" in dataset card)
>>> api.list_datasets(filter="fiftyone")

مثال على الاستخدام مع الحجة search:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all datasets with "text" in their name
>>> api.list_datasets(search="text")

# List all datasets with "text" in their name made by google
>>> api.list_datasets(search="text", author="google")

list_inference_catalog

< >

( accelerator: Literal['cpu', 'gpu', 'neuron'] | str | None = Noneengine: Literal['llamacpp', 'sglang', 'tei', 'vllm'] | str | None = Nonelicense: str | None = Nonetask: str | None = Nonesearch: str | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → list[InferenceCatalogModel]

المعاملات

  • accelerator (str، اختياري) — إرجاع النماذج التي لديها وصفة لهذا المعالج ("cpu" أو "gpu" أو "neuron") فقط.
  • engine (str، اختياري) — إرجاع النماذج التي لديها وصفة لهذا محرك الاستدلال فقط (مثل "vllm"، "llamacpp"، "tei"، "sglang").
  • license (str، اختياري) — إرجاع النماذج المرخّصة بموجب هذا الترخيص فقط (مثل "Apache 2.0").
  • task (str، اختياري) — إرجاع النماذج الخاصة بهذه المهمة فقط (مثل "text-generation").
  • search (str، اختياري) — إرجاع النماذج المطابقة لهذا الاستعلام فقط.
  • limit (int، اختياري) — الحد الأقصى لعدد النماذج التي يجب إرجاعها.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication).

يعيد

list[InferenceCatalogModel]

النماذج المتاحة في الكتالوج، كلٌّ منها مع وصفاته المُختبَرة.

قائمة النماذج المتاحة في كتالوج الاستدلال الخاص بـ Hugging Face.

تتمثل غاية كتالوج الاستدلال في توفير قائمة مُنتقاة من النماذج المُحسَّنة للاستدلال والتي تم اختبار الإعدادات الافتراضية لها. راجع https://huggingface.co/proxy/endpoints.huggingface.co/catalog للاطلاع على قائمة النماذج المتاحة في الكتالوج.

استخدم create_inference_endpoint_from_catalog() لنشر نموذج أو وصفة من الكتالوج.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> catalog = api.list_inference_catalog(task="text-generation", accelerator="neuron")
>>> [(model.repo_id, [recipe.id for recipe in model.recipes]) for model in catalog]
[('meta-llama/Llama-3.1-8B-Instruct', ['sizzling-biryani-g4xsi1ac', 'artisanal-quinoa-yz9ynamx']), ...]

list_inference_catalog تجريبي. قد تتغير واجهة برمجته (API) في المستقبل. يرجى تقديم ملاحظاتك إذا كان لديك أي اقتراحات أو طلبات.

list_inference_endpoints

< >

( namespace: str | None = Nonetoken: bool | str | None = None ) → listInferenceEndpoint

المعاملات

  • namespace (str، اختياري) — المجال (namespace) الذي تُستعرض نقاط النهاية الخاصة به. الافتراضي هو المستخدم الحالي. اضبطه على "*" لعرض جميع نقاط النهاية من جميع المجالات (أي المجال الشخصي وجميع المنظمات التي ينتمي إليها المستخدم).
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

قائمةInferenceEndpoint

قائمة بجميع نقاط الاستدلال (inference endpoints) للمساحة الاسم (namespace) المحددة.

يُدرج جميع نقاط الاستدلال (inference endpoints) للمساحة الاسم (namespace) المحددة.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.list_inference_endpoints()
[InferenceEndpoint(name='my-endpoint', ...), ...]

list_inference_endpoints_hardware

< >

( namespace: str | None = Nonetoken: bool | str | None = None ) → list[InferenceEndpointHardware]

المعاملات

  • namespace (str، اختياري) — المجال الذي تُستعرض منه العتاد المتاح وحصة المعالج. الافتراضي هو المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication).

يعيد

list[InferenceEndpointHardware]

الأجهزة المتوفرة لدى كل مزوّد ومنطقة، بما في ذلك الأجهزة غير المتوفرة حاليًا أو المتوقفة عن الدعم.

list_hardware

تحتوي كل سجل على القيم الدقيقة لـvendor وregion وaccelerator وinstance_type وinstance_size المتوقعة من create_inference_endpoint()، إلى جانب سعر المسار السريع وحصة المسار السريع الخاصة بالمجال.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> hardware = api.list_inference_endpoints_hardware()
>>> [hw.id for hw in hardware if hw.accelerator == "gpu" and hw.status == "available"]
['aws-us-east-1-nvidia-l4-x1', 'aws-us-east-1-nvidia-l4-x4', ...]

list_jobs

< >

( status: list[JobStage | str] | JobStage | str | None = Nonelabels: dict[str, str] | None = Nonetimeout: int | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → Iterable[JobInfo]

المعاملات

  • status (JobStage أو str أو list، اختياري) — لا تُرجِع سوى المهام التي تحمل الحالة المحددة، مثل "RUNNING" أو [JobStage.RUNNING, JobStage.SCHEDULING]. راجع JobStage لمعرفة القيم الممكنة.
  • labels (dict[str, str]، اختياري) — إرجاع المهام التي تحمل جميع التسميات المحددة بالصيغة key=value فقط، على سبيل المثال {"env": "prod", "team": "ml"}.
  • timeout (float، اختياري) — ما إذا كان يجب تعيين مهلة زمنية للطلب الموجّه إلى Hub.
  • namespace (str، اختياري) — المجال الذي تُستخرج منه قائمة المهام. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

Iterable[JobInfo]

قابلة للتكرار من كائنات JobInfo.

قائمة مهام الحساب على بنية Hugging Face التحتية.

list_jobs_hardware

< >

( token: bool | str | None = None ) → list[JobHardwareInfo]

يعيد

list[JobHardwareInfo]

قائمة بتكوينات الأجهزة المتاحة.

قائمة خيارات الأجهزة المتاحة للمهام على بنية Hugging Face التحتية.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> hardware_list = api.list_jobs_hardware()
>>> hardware_list[0]
JobHardwareInfo(name='cpu-basic', pretty_name='CPU Basic', cpu='2 vCPU', ram='16 GB', ephemeral_storage='20 GB', accelerator=None, unit_cost_micro_usd=167, unit_cost_usd=0.000167, unit_label='minute')
>>> hardware_list[0].name
'cpu-basic'

# Filter GPU options
>>> gpu_hardware = [hw for hw in hardware_list if hw.accelerator is not None]
>>> gpu_hardware[0].accelerator.model
'T4'

list_lfs_files

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[LFSFileInfo]

المعاملات

  • repo_id (str) — المستودع الذي تريد عرض ملفات LFS الخاصة به.
  • repo_type (str، اختياري) — نوع المستودع. اضبطه على "dataset" أو "space" عند التعداد من مجموعة بيانات أو مساحة، أو None أو "model" عند التعداد من نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[LFSFileInfo]

مُتكرِّر (iterator) من كائنات LFSFileInfo.

List all LFS files in a repo on the Hub.

يكون هذا مفيدًا بشكل رئيسي لقياس مقدار التخزين الذي تستخدمه المستودع، ولتنظيف الملفات الكبيرة في النهاية باستخدام permanently_delete_lfs_files(). لاحظ أن هذا إجراء دائم سيؤثر على جميع الالتزامات التي تشير إلى هذه الملفات المحذوفة، ولا يمكن التراجع عنه.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

list_liked_repos

< >

( user: str | None = Nonetoken: bool | str | None = None ) → UserLikes

المعاملات

  • user (str، اختياري) — اسم المستخدم الذي تريد جلب الإعجابات الخاصة به.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

UserLikes

كائن يحتوي على اسم المستخدم وقوائم معرفات المستودعات الثلاث (قائمة واحدة للنماذج، وقائمة واحدة للمجموعات البيانات، وقائمة واحدة للمساحات).

يرفع

ValueError

  • ValueError — إذا لم يُمرَّر user ولم يُعثر على رمز (سواءً من الحجة أو من الجهاز).

list_public_repos

هذا القوائم عامة، لذا فإن الرمز اختياري. إذا لم يُمرَّر user، فسيُستخدم المستخدم المسجَّل حاليًا افتراضيًا.

انظر أيضًا إلى unlike().

مثال:

>>> from huggingface_hub import list_liked_repos

>>> likes = list_liked_repos("julien-c")

>>> likes.user
"julien-c"

>>> likes.models
["osanseviero/streamlit_1.15", "Xhaheen/ChatGPT_HF", ...]

list_models

< >

( filter: str | Iterable[str] | None = Noneauthor: str | None = Noneapps: str | list[str] | None = Nonegated: bool | None = Noneinference: Literal['warm'] | None = Noneinference_provider: Literal['all'] | PROVIDER_T | list[PROVIDER_T] | None = Nonetrained_dataset: str | list[str] | None = Nonesearch: str | None = Nonepipeline_tag: str | None = Nonenum_parameters: str | None = Noneemissions_thresholds: tuple[float, float] | None = Nonesort: ModelSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandModelProperty_T] | None = Nonefull: bool | None = NonecardData: bool = Falsefetch_config: bool = Falsetoken: bool | str | None = None ) → Iterable[ModelInfo]

المعاملات

  • filter (str أو Iterable[str]، اختياري) — نص أو قائمة نصوص لتصفية النماذج على Hub. يمكن تصفية النماذج حسب المكتبة، واللغة، والمهمة، والوسوم، وغيرها.
  • author (str، اختياري) — نص يحدد مؤلف (المستخدم أو المؤسسة) للنماذج المُعاد إرجاعها.
  • apps (str أو List، اختياري) — نص أو قائمة نصوص لتصفية النماذج على Hub التي تدعم التطبيقات المحددة. تتضمن القيم النموذجية "ollama" أو ["ollama", "vllm"].
  • gated (bool، اختياري) — قيمة منطقية لتصفية النماذج على Hub التي تكون محمية أو غير محمية. افتراضيًا، تُعاد جميع النماذج. إذا تم تمرير gated=True، تُعاد النماذج المحمية فقط. إذا تم تمرير gated=False، تُعاد النماذج غير المحمية فقط.
  • inference (Literal["warm"], اختياري) — إذا كانت القيمة "warm"، فسيتم تصفية النماذج الموجودة على Hub والتي يقدّمها مزوّد واحد على الأقل حاليًا.
  • inference_provider (Literal["all"] أو str، اختياري) — نصٌ لتصفية النماذج على Hub التي تُقدَّم بواسطة مزوّد معيّن. مرّر "all" للحصول على جميع النماذج التي تُقدَّم بواسطة مزوّد واحد على الأقل.
  • trained_dataset (str أو List، اختياري) — وسم نصي أو قائمة من الوسوم النصية للبيانات المُدرَّب عليها لنموذج على Hub.
  • search (str, اختياري) — نص سيُحتوى في معرّفات النماذج المُعادَة.
  • pipeline_tag (str، اختياري) — وسم خط أنابيب نصي لتصفية النماذج على Hub بناءً عليه، مثل summarization.
  • num_parameters (str، اختياري) — تصفية النماذج حسب عدد المعاملات. يقبل نفس صيغة النطاق كما في واجهة Hub وواجهة API، على سبيل المثال "min:6B,max:128B"، "min:6B" أو "max:128B".
  • emissions_thresholds (Tuple, اختياري) — مجموعة مرتبة من عددين صحيحين أو عشريين تمثل الحد الأدنى والحد الأقصى للبصمة الكربونية، بوحدة الغرام، لاستخدامها في تصفية النماذج الناتجة.
  • sort (ModelSort_T, اختياري) — المفتاح الذي يُستخدم لترتيب النماذج الناتجة. القيم الممكنة هي “created_at” و”downloads” و”last_modified” و”likes” و”trending_score”.
  • limit (int، اختياري) — الحد الأقصى لعدد النماذج التي يتم جلبها. إذا تُركت هذه الخانة None، فسيتم جلب جميع النماذج.
  • expand (list[ExpandModelProperty_T], اختياري) — قائمة بالخصائص التي يجب إرجاعها في الاستجابة. عند الاستخدام، لن تُرجع إلا الخصائص الموجودة في القائمة. لا يمكن استخدام هذا المعامل إذا تم تمرير full أو cardData أو fetch_config. القيم الممكنة هي "author"، "cardData"، "config"، "createdAt"، "disabled"، "downloads"، "downloadsAllTime"، "evalResults"، "gated"، "gguf"، "inference"، "inferenceProviderMapping"، "lastModified"، "library_name"، "likes"، "mask_token"، "model-index"، "pipeline_tag"، "private"، "safetensors"، "sha"، "siblings"، "spaces"، "tags"، "transformersInfo"، "trendingScore"، "widgetData"، و"resourceGroup".
  • full (bool، اختياري) — ما إذا كان سيتم جلب جميع بيانات النموذج، بما في ذلك last_modified، وsha، والملفات وtags. يتم تعيينه إلى True افتراضيًا عند استخدام عامل تصفية.
  • cardData (bool، اختياري) — ما إذا كان يجب جلب بيانات الوصف الخاصة بالنموذج أيضًا. يمكن أن تحتوي على معلومات مفيدة مثل انبعاثات الكربون، والمقاييس، ومجموعات البيانات التي تم التدريب عليها.
  • fetch_config (bool, اختياري) — ما إذا كان سيتم جلب إعدادات النموذج أيضًا. هذا غير مضمن في full بسبب حجمه.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[ModelInfo]

قابلة للتكرار من كائنات huggingface_hub.hf_api.ModelInfo.

قائمة النماذج المستضافة على Huggingface Hub، مع مراعاة بعض عوامل التصفية.

مثال:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all models
>>> api.list_models()

# List text classification models
>>> api.list_models(filter="text-classification")

# List models from the KerasHub library
>>> api.list_models(filter="keras-hub")

# List models served by Cohere
>>> api.list_models(inference_provider="cohere")

# List models with "bert" in their name
>>> api.list_models(search="bert")

# List models with "bert" in their name and pushed by google
>>> api.list_models(search="bert", author="google")

# List models with 6B to 128B parameters
>>> api.list_models(num_parameters="min:6B,max:128B", sort="likes")

list_organization_followers

< >

( organization: strtoken: bool | str | None = None ) → Iterable[User]

المعاملات

  • organization (str) — اسم المنظمة التي تريد الحصول على متابعيها.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[User]

قائمة من كائنات User تتضمن متابعي المنظمة.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 إذا لم تكن المنظمة موجودة على Hub.

قائمة متابعي منظمة على Hub.

list_organization_members

< >

( organization: strtoken: bool | str | None = None ) → Iterable[User]

المعاملات

  • organization (str) — اسم المنظمة التي تريد الحصول على أعضائها.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[User]

قائمة من كائنات User بأعضاء المنظمة.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 إذا لم تكن المنظمة موجودة على Hub.

قائمة بأعضاء منظمة على الـ Hub.

list_papers

< >

( query: str | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → Iterable[PaperInfo]

المعاملات

  • query (str، اختياري) — نص استعلام للبحث عن الأوراق البحثية. إذا تم تقديمه، تُعاد الأوراق البحثية المطابقة للاستعلام.
  • limit (int، اختياري) — الحد الأقصى لعدد الأوراق التي يجب إرجاعها.
  • token (Union[bool, str, None], اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[PaperInfo]

قابلة للتكرار من كائنات huggingface_hub.hf_api.PaperInfo.

قائمة الأوراق اليومية على Hugging Face Hub بناءً على استعلام بحث.

مثال:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all papers with "attention" in their title
>>> api.list_papers(query="attention")

list_pending_access_requests

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]

المعاملات

  • repo_id (str) — معرّف المستودع الذي تريد الحصول على طلبات الوصول إليه.
  • repo_type (str، اختياري) — نوع المستودع الذي تريد الحصول على طلبات الوصول له. يجب أن يكون أحد model أو dataset أو space. القيمة الافتراضية هي model.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[AccessRequest]

قابلة للتكرار من كائنات AccessRequest. يحتوي كل عنصر على سمات username، request_id، email، status وtimestamp. إذا كان المستودع المحمي يحتوي على نموذج مخصص، فسيتم ملء سمة fields بإجابات المستخدم.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 إذا لم يكن المستودع محميًا.
  • HfHubHTTPError — HTTP 403 إذا كان لديك وصول للقراءة فقط إلى المستودع. قد يحدث ذلك إذا لم تكن لديك دور write أو admin في المنظمة التي ينتمي إليها المستودع، أو إذا قمت بتمرير رمز read.

احصل على طلبات الوصول المعلّقة لمستودع محكوم الوصول معيّن.

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

لمزيد من المعلومات حول المستودعات المُقيَّدة، راجع https://huggingface.co/docs/hub/models-gated.

مثال:

>>> from huggingface_hub import list_pending_access_requests, accept_access_request

# List pending requests
>>> requests = list(list_pending_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        request_id='655f3a1c9e6b2d4f8a7c1e05',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='pending',
        fields=None,
    ),
    ...
]

# Accept Clem's request
>>> accept_access_request("meta-llama/Llama-2-7b", "clem")

list_rejected_access_requests

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]

المعاملات

  • repo_id (str) — معرّف المستودع الذي تريد الحصول على طلبات الوصول إليه.
  • repo_type (str، اختياري) — نوع المستودع الذي تريد الحصول على طلبات الوصول له. يجب أن يكون أحد model أو dataset أو space. القيمة الافتراضية هي model.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[AccessRequest]

قابلة للتكرار من كائنات AccessRequest. يحتوي كل عنصر على سمات username، request_id، email، status وtimestamp. إذا كان المستودع المحمي يحتوي على نموذج مخصص، فسيتم ملء سمة fields بإجابات المستخدم.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 إذا لم يكن المستودع محميًا.
  • HfHubHTTPError — HTTP 403 إذا كان لديك وصول للقراءة فقط إلى المستودع. قد يحدث ذلك إذا لم تكن لديك دور write أو admin في المنظمة التي ينتمي إليها المستودع، أو إذا قمت بتمرير رمز read.

احصل على طلبات الوصول المرفوضة المستلمة لمتخزن محدد محمي.

تعني الطلب المرفوض أن المستخدم قد طلب الوصول إلى المستودع وتم رفض الطلب صراحةً من قِبل مالك المستودع (سواء كنتَ أنت أو مستخدمًا آخر من مؤسستك). لا يمكن للمستخدم تنزيل أي ملف من المستودع. يمكن قبول الطلبات المرفوضة أو إلغاؤها في أي وقت باستخدام accept_access_request() و cancel_access_request(). سيعود الطلب الملغى إلى قائمة الطلبات المعلّقة بينما سينتقل الطلب المقبول إلى قائمة الطلبات المقبولة.

لمزيد من المعلومات حول المستودعات المُقيَّدة، راجع https://huggingface.co/docs/hub/models-gated.

مثال:

>>> from huggingface_hub import list_rejected_access_requests

>>> requests = list(list_rejected_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        request_id='655f3a1c9e6b2d4f8a7c1e05',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='rejected',
        fields=None,
    ),
    ...
]

list_repo_commits

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = Nonerevision: str | None = Noneformatted: bool = False ) → list[GitCommitInfo]

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند سرد الالتزامات من مجموعة بيانات أو مساحة، أو None أو "model" عند السرد من نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".
  • formatted (bool) — ما إذا كان يجب إرجاع العنوان والوصف بتنسيق HTML للالتزامات. القيمة الافتراضية هي False.

يعيد

list[GitCommitInfo]

قائمة من الكائنات تحتوي على معلومات حول التسميات (commits) لمستودع على Hub.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type خاطئ، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • RevisionNotFoundError — إذا لم يتم العثور على المراجعة (خطأ 404) في المستودع.

احصل على قائمة التزامات (commits) لإصدار (revision) معين في مستودع على Hub.

تُرتَّب الالتزامات حسب التاريخ (أحدث التزام أولاً).

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Commits are sorted by date (last commit first)
>>> initial_commit = api.list_repo_commits("gpt2")[-1]

# Initial commit is always a system commit containing the `.gitattributes` file.
>>> initial_commit
GitCommitInfo(
    commit_id='9b865efde13a30c13e0a33e536cf3e4a5a9d71d8',
    authors=['system'],
    created_at=datetime.datetime(2019, 2, 18, 10, 36, 15, tzinfo=datetime.timezone.utc),
    title='initial commit',
    message='',
    formatted_title=None,
    formatted_message=None
)

# Create an empty branch by deriving from initial commit
>>> api.create_branch("gpt2", branch="new_empty_branch", revision=initial_commit.commit_id)

list_repo_files

< >

( repo_id: strrevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → list[str]

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • revision (str، اختياري) — إصدار المستودع الذي سيتم منه جلب المعلومات.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

list[str]

قائمة الملفات في مستودع معيّن.

احصل على قائمة الملفات في مستودع معيّن.

list_repo_likers

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[User]

المعاملات

  • repo_id (str) — المستودع الذي سيتم الاسترداد منه. مثال: "user/my-cool-model".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.

يعيد

Iterable[User]

قابلة للتكرار من كائنات huggingface_hub.hf_api.User.

قائمة بجميع المستخدمين الذين أعجبوا بمستودع معين على hugging Face Hub.

انظر أيضًا إلى list_liked_repos().

list_repo_refs

< >

( repo_id: strrepo_type: str | None = Noneinclude_pull_requests: bool = Falsetoken: str | bool | None = None ) → GitRefs

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" أو "kernel" عند سرد مراجع من مجموعة بيانات أو مساحة أو نواة، أو None أو "model" عند السرد من نموذج. القيمة الافتراضية هي None.
  • include_pull_requests (bool، اختياري) — ما إذا كان يجب تضمين مراجع من طلبات السحب في القائمة. القيمة الافتراضية هي False.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

GitRefs

كائن يحتوي على جميع المعلومات المتعلقة بالفروع والوسوم الخاصة بمستودع على Hub.

احصل على قائمة مراجع مستودع معيّن (الوسوم والفروع معًا).

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.list_repo_refs("gpt2")
GitRefs(branches=[GitRefInfo(name='main', ref='refs/heads/main', target_commit='e7da7f221d5bf496a48136c0cd264e630fe9fcc8')], converts=[], tags=[])

>>> api.list_repo_refs("bigcode/the-stack", repo_type='dataset')
GitRefs(
    branches=[
        GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
        GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
    ],
    converts=[],
    tags=[
        GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
    ]
)

list_repo_tree

< >

( repo_id: strpath_in_repo: str | None = Nonerecursive: bool = Falseexpand: bool = Falserevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → Iterable[Union[RepoFile, RepoFolder]]

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • path_in_repo (str، اختياري) — المسار النسبي للشجرة (المجلد) في المستودع، على سبيل المثال: "checkpoints/1fec34a/results". سيُستخدم الشجرة (المجلد) الجذرية للمستودع افتراضيًا.
  • recursive (bool، اختياري، الافتراضي False) — ما إذا كان سيتم سرد ملفات ومجلدات الشجرة بشكل تكراري.
  • expand (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب جلب مزيد من المعلومات حول ملفات ومجلدات الشجرة (مثل آخر التزامن ونتائج فحص الأمان للملفات). هذه العملية أكثر تكلفة على الخادم، لذا تُعاد 50 نتيجة فقط لكل صفحة (بدلاً من 1000). بما أن ترقيم الصفحات مُنفَّذ في huggingface_hub، فإن الأمر شفاف بالنسبة لك باستثناء الوقت الذي يستغرقه الحصول على النتائج.
  • revision (str، اختياري) — المراجعة (revision) للمستودع الذي سيتم منه جلب الشجرة. القيمة الافتراضية هي الفرع "main".
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم منه جلب الشجرة ("model"، "dataset"، "space" أو "kernel"). القيمة الافتراضية هي "model".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[Union[RepoFile, RepoFolder]]

معلومات حول ملفات ومجلدات الشجرة، على شكل قابل للتكرار من كائنات RepoFile وRepoFolder. لا يُكفَل ترتيب الملفات والمجلدات.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError أو ~utils.RemoteEntryNotFoundError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type خاطئ، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • RevisionNotFoundError — إذا لم يتم العثور على المراجعة (خطأ 404) في المستودع.
  • ~utils.RemoteEntryNotFoundError — إذا لم يكن الشجرة (المجلد) موجودًا (خطأ 404) في المستودع.

list الملفات والمجلدات في شجرة المستودع والحصول على معلومات عنها.

أمثلة:

احصل على معلومات عن شجرة المستودع.

>>> from huggingface_hub import list_repo_tree
>>> repo_tree = list_repo_tree("lysandre/arxiv-nlp")
>>> repo_tree
<generator object HfApi.list_repo_tree at 0x7fa4088e1ac0>
>>> list(repo_tree)
[
    RepoFile(path='.gitattributes', size=391, blob_id='ae8c63daedbd4206d7d40126955d4e6ab1c80f8f', lfs=None, last_commit=None, security=None),
    RepoFile(path='README.md', size=391, blob_id='43bd404b159de6fba7c2f4d3264347668d43af25', lfs=None, last_commit=None, security=None),
    RepoFile(path='config.json', size=554, blob_id='2f9618c3a19b9a61add74f70bfb121335aeef666', lfs=None, last_commit=None, security=None),
    RepoFile(
        path='flax_model.msgpack', size=497764107, blob_id='8095a62ccb4d806da7666fcda07467e2d150218e',
        lfs={'size': 497764107, 'sha256': 'd88b0d6a6ff9c3f8151f9d3228f57092aaea997f09af009eefd7373a77b5abb9', 'pointer_size': 134}, last_commit=None, security=None
    ),
    RepoFile(path='merges.txt', size=456318, blob_id='226b0752cac7789c48f0cb3ec53eda48b7be36cc', lfs=None, last_commit=None, security=None),
    RepoFile(
        path='pytorch_model.bin', size=548123560, blob_id='64eaa9c526867e404b68f2c5d66fd78e27026523',
        lfs={'size': 548123560, 'sha256': '9be78edb5b928eba33aa88f431551348f7466ba9f5ef3daf1d552398722a5436', 'pointer_size': 134}, last_commit=None, security=None
    ),
    RepoFile(path='vocab.json', size=898669, blob_id='b00361fece0387ca34b4b8b8539ed830d644dbeb', lfs=None, last_commit=None, security=None)]
]

احصل على مزيد من المعلومات حول شجرة المستودع (آخر التزام ونتائج فحص أمان الملفات)

>>> from huggingface_hub import list_repo_tree
>>> repo_tree = list_repo_tree("prompthero/openjourney-v4", expand=True)
>>> list(repo_tree)
[
    RepoFolder(
        path='feature_extractor',
        tree_id='aa536c4ea18073388b5b0bc791057a7296a00398',
        last_commit={
            'oid': '47b62b20b20e06b9de610e840282b7e6c3d51190',
            'title': 'Upload diffusers weights (#48)',
            'date': datetime.datetime(2023, 3, 21, 9, 5, 27, tzinfo=datetime.timezone.utc)
        }
    ),
    RepoFolder(
        path='safety_checker',
        tree_id='65aef9d787e5557373fdf714d6c34d4fcdd70440',
        last_commit={
            'oid': '47b62b20b20e06b9de610e840282b7e6c3d51190',
            'title': 'Upload diffusers weights (#48)',
            'date': datetime.datetime(2023, 3, 21, 9, 5, 27, tzinfo=datetime.timezone.utc)
        }
    ),
    RepoFile(
        path='model_index.json',
        size=582,
        blob_id='d3d7c1e8c3e78eeb1640b8e2041ee256e24c9ee1',
        lfs=None,
        last_commit={
            'oid': 'b195ed2d503f3eb29637050a886d77bd81d35f0e',
            'title': 'Fix deprecation warning by changing `CLIPFeatureExtractor` to `CLIPImageProcessor`. (#54)',
            'date': datetime.datetime(2023, 5, 15, 21, 41, 59, tzinfo=datetime.timezone.utc)
        },
        security={
            'safe': True,
            'av_scan': {'virusFound': False, 'virusNames': None},
            'pickle_import_scan': None
        }
    )
    ...
]

list_scheduled_jobs

< >

( labels: dict[str, str] | None = Nonetimeout: int | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → list[ScheduledJobInfo]

المعاملات

  • labels (dict[str, str]، اختياري) — إرجاع المهام المجدولة فقط التي تحمل جميع التسميات المحددة بالصيغة key=value، على سبيل المثال {"env": "prod", "team": "ml"}.
  • timeout (float، اختياري) — ما إذا كان يجب تعيين مهلة زمنية للطلب الموجّه إلى Hub.
  • namespace (str، اختياري) — المجال الذي تُستخرج منه قائمة المهام. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

list[ScheduledJobInfo]

قائمة من كائنات ScheduledJobInfo.

قائمة مهام الحوسبة المجدولة على بنية Hugging Face التحتية.

list_space_templates

< >

( token: str | bool | None = None ) → list[SpaceTemplate]

المعاملات

يعيد

list[SpaceTemplate]

قالبات Space المتاحة.

قائمة قوالب Space الرسمية المتاحة على Hub.

يمكن تمرير repo_id للقالب المُعاد (أو name المختصر الخاص به) كـspace_template إلى HfApi.create_repo() لإنشاء مساحة جديدة من ذلك القالب.

مثال:

>>> from huggingface_hub import list_space_templates
>>> templates = list_space_templates()
>>> templates[0]
SpaceTemplate(name='Streamlit', repo_id='streamlit/streamlit-template-space', sdk='docker', preferred_private=False)

list_spaces

< >

( filter: str | Iterable[str] | None = Noneauthor: str | None = Nonesearch: str | None = Nonedatasets: str | Iterable[str] | None = Nonemodels: str | Iterable[str] | None = Nonelinked: bool = Falsesort: SpaceSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandSpaceProperty_T] | None = Nonefull: bool | None = Nonetoken: bool | str | None = None ) → Iterable[SpaceInfo]

المعاملات

  • filter (str أو Iterable، اختياري) — وسم نصي أو قائمة من الوسوم التي يمكن استخدامها لتحديد المساحات (Spaces) على الـ Hub.
  • author (str، اختياري) — نص يحدد مؤلف المساحات المُعاد إرجاعها.
  • search (str، اختياري) — نص سيُحتوى في المساحات المُعادَة.
  • datasets (str أو Iterable، اختياري) — ما إذا كان يجب إرجاع مساحات (Spaces) تستخدم مجموعة بيانات. يمكن تمرير اسم مجموعة بيانات محددة كسلسلة نصية.
  • models (str أو Iterable، اختياري) — ما إذا كان يجب إرجاع مساحات (Spaces) تستخدم نموذجًا. يمكن تمرير اسم نموذج محدد كسلسلة نصية.
  • linked (bool، اختياري) — ما إذا كان سيتم إرجاع Spaces التي تستخدم نموذجًا أو مجموعة بيانات.
  • sort (SpaceSort_T, اختياري) — المفتاح الذي يُستخدم لفرز المساحات الناتجة. القيم الممكنة هي “created_at” و”last_modified” و”likes” و”trending_score”.
  • limit (int, اختياري) — الحد الأقصى لعدد مساحات العمل (Spaces) التي يتم جلبها. إذا تُركت هذه الخانة بقيمة None، فسيتم جلب جميع مساحات العمل.
  • expand (list[ExpandSpaceProperty_T], اختياري) — قائمة بالخصائص التي يجب إرجاعها في الاستجابة. عند استخدامه، لن تُرجع إلا الخصائص الموجودة في القائمة. لا يمكن استخدام هذا المعامل إذا تم تمرير full. القيم الممكنة هي "author"، "cardData"، "datasets"، "disabled"، "lastModified"، "createdAt"، "likes"، "models"، "private"، "region"، "runtime"، "sdk"، "siblings"، "sha"، "subdomain"، "tags"، "trendingScore"، "usedStorage"، و"resourceGroup".
  • full (bool، اختياري) — ما إذا كان سيتم جلب جميع بيانات Spaces، بما في ذلك حقول last_modified وsiblings وcard_data.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[SpaceInfo]

قابلة للتكرار من كائنات huggingface_hub.hf_api.SpaceInfo.

قائمة المساحات المستضافة على Huggingface Hub، مع مراعاة بعض عوامل التصفية.

list_spaces_hardware

< >

( token: bool | str | None = None ) → list[JobHardwareInfo]

يعيد

list[JobHardwareInfo]

قائمة بتكوينات الأجهزة المتاحة.

قائمة خيارات الأجهزة المتاحة للمساحات.

مثال:

>>> from huggingface_hub import list_spaces_hardware
>>> hardware_list = list_spaces_hardware()
>>> hardware_list[0]
JobHardwareInfo(name='cpu-basic', pretty_name='CPU Basic', cpu='2 vCPU', ram='16 GB', ...)
>>> hardware_list[0].name
'cpu-basic'

list_user_followers

< >

( username: strtoken: bool | str | None = None ) → Iterable[User]

المعاملات

  • username (str) — اسم المستخدم الخاص بالمستخدم الذي تريد الحصول على متابعيه.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[User]

قائمة من كائنات User تمثل متابعي المستخدم.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 إذا لم يكن المستخدم موجودًا على Hub.

احصل على قائمة متابعي مستخدم على Hub.

list_user_following

< >

( username: strtoken: bool | str | None = None ) → Iterable[User]

المعاملات

  • username (str) — اسم المستخدم الخاص بالمستخدم الذي تريد معرفة المستخدمين الذين يتابعهم.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[User]

قائمة من كائنات User تمثل المستخدمين الذين يتابعهم المستخدم.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 إذا لم يكن المستخدم موجودًا على Hub.

احصل على قائمة المستخدمين الذين يتابعهم مستخدم على Hub.

list_user_repos

< >

( namespace: str | None = Nonetoken: bool | str | None = None ) → Iterable[RepoStorageInfo]

المعاملات

  • namespace (str، اختياري) — اسم المنظمة. إذا لم يُقدَّم، تُعرض مستودعات المستخدم المصادَق.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. الافتراضي هو الرمز المحفوظ محليًا.

يعيد

Iterable[RepoStorageInfo]

قائمة قابلة للتكرار من كائنات RepoStorageInfo.

list جميع المستودعات (النماذج، مجموعات البيانات، المساحات، الدلاء) لمستخدم أو منظمة مع معلومات التخزين.

يستخدم نقطة النهاية /api/settings/repositories للمستخدم المصادَق أو /api/organizations/{namespace}/settings/repositories لمنظمة.

مثال:

>>> from huggingface_hub import list_user_repos

>>> repos = list(list_user_repos())
>>> repos[0]
RepoStorageInfo(id='username/my-model', type='model', ...)

>>> # List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

list_webhooks

< >

( token: bool | str | None = None ) → list[WebhookInfo]

المعاملات

يعيد

list[WebhookInfo]

قائمة كائنات معلومات خطاف الويب.

list_webhooks

مثال:

>>> from huggingface_hub import list_webhooks
>>> webhooks = list_webhooks()
>>> len(webhooks)
2
>>> webhooks[0]
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    secret="my-secret",
    domains=["repo", "discussion"],
    disabled=False,
)

merge_pull_request

< >

( repo_id: strdiscussion_num: inttoken: bool | str | None = Nonecomment: str | None = Nonerepo_type: str | None = None ) → DiscussionStatusChange

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • discussion_num (int) — رقم المناقشة أو طلب السحب. يجب أن يكون عددًا صحيحًا موجبًا تمامًا.
  • comment (str، اختياري) — تعليق اختياري يُنشر مع تغيير الحالة.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

DiscussionStatusChange

حدث تغيير الحالة

يدمج طلب سحب.

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

معلومات النموذج

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = NonesecurityStatus: bool | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandModelProperty_T] | None = Nonetoken: bool | str | None = None ) → huggingface_hub.hf_api.ModelInfo

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • revision (str، اختياري) — إصدار مستودع النموذج الذي سيتم منه جلب المعلومات.
  • timeout (float، اختياري) — ما إذا كان يجب تعيين مهلة زمنية للطلب الموجّه إلى Hub.
  • securityStatus (bool، اختياري) — ما إذا كان سيتم استرجاع حالة الأمان من مستودع النموذج أيضًا. ستُعاد حالة الأمان في حقل security_repo_status.
  • files_metadata (bool، اختياري) — ما إذا كان سيتم استرداد البيانات الوصفية للملفات في المستودع (الحجم، بيانات LFS الوصفية، إلخ). القيمة الافتراضية هي False.
  • expand (list[ExpandModelProperty_T], اختياري) — قائمة بالخصائص التي يجب إرجاعها في الاستجابة. عند الاستخدام، لن تُرجع إلا الخصائص المدرجة في القائمة. لا يمكن استخدام هذا المعامل إذا تم تمرير securityStatus أو files_metadata. القيم الممكنة هي "author"، "baseModels"، "cardData"، "childrenModelCount"، "config"، "createdAt"، "disabled"، "downloads"، "downloadsAllTime"، "evalResults"، "gated"، "gguf"، "inference"، "inferenceProviderMapping"، "lastModified"، "library_name"، "likes"، "mask_token"، "model-index"، "pipeline_tag"، "private"، "safetensors"، "sha"، "siblings"، "spaces"، "tags"، "transformersInfo"، "trendingScore"، "widgetData"، "usedStorage"، و"resourceGroup".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

huggingface_hub.hf_api.ModelInfo

معلومات مستودع النموذج.

احصل على معلومات حول نموذج محدد على huggingface.co

يمكن أن يكون النموذج خاصًا إذا مررت برمز مقبول أو كنت مسجّل الدخول.

يرفع الأخطاء التالية:

  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • RevisionNotFoundError إذا تعذّر العثور على المراجعة التي يجب التحميل منها.

move_bucket

< >

( from_id: strto_id: strtoken: bool | str | None = None )

المعاملات

  • from_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم دلو مفصولان بـ /. معرّف الدلو الأصلي (مثل "username/my-bucket").
  • to_id (str) — اسم نطاق (مستخدم أو منظمة) واسم دلو مفصولان بـ /. المعرّف النهائي للدلو (مثل "username/new-bucket-name" أو "organization/my-bucket").
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

BucketNotFoundError

  • BucketNotFoundError — إذا تعذّر العثور على الدلو المصدر. قد يكون ذلك بسبب عدم وجوده، أو لأنّه مُعيّن على private ولا تملك صلاحية الوصول إليه.

نقل دلو من namespace1/repo_name1 إلى namespace2/repo_name2

لاحظ أن هناك قيودًا معينة. لمزيد من المعلومات حول نقل المستودعات، يرجى الاطلاع على https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo.

مثال:

>>> from huggingface_hub import move_bucket

>>> # Rename a bucket within the same namespace
>>> move_bucket(from_id="username/old-name", to_id="username/new-name")

>>> # Transfer a bucket to an organization
>>> move_bucket(from_id="username/my-bucket", to_id="my-org/my-bucket")

move_repo

< >

( from_id: strto_id: strrepo_type: str | None = Nonetoken: str | bool | None = None )

المعاملات

  • from_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /. معرّف المستودع الأصلي.
  • to_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /. المعرّف النهائي للمستودع.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

نقل مستودع من namespace1/repo_name1 إلى namespace2/repo_name2

لاحظ أن هناك قيودًا معينة. لمزيد من المعلومات حول نقل المستودعات، يرجى الاطلاع على https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo.

يرفع الأخطاء التالية:

  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

paper_info

< >

( id: str ) → PaperInfo

المعاملات

  • id (str، اختياري) — معرّف ArXiv للورقة.

يعيد

PaperInfo

كائن PaperInfo.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 إذا لم يكن البحث موجودًا على Hub.

احصل على معلومات عن ورقة بحثية على الـ Hub.

parse_safetensors_file_metadata

< >

( repo_id: strfilename: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsFileMetadata

المعاملات

  • repo_id (str) — اسم مستخدم أو منظمة واسم مستودع مفصولان بـ /.
  • filename (str) — اسم الملف في المستودع.
  • repo_type (str، اختياري) — يُضبط على "dataset" أو "space" إذا كان الملف في مجموعة بيانات أو مساحة، أو None أو "model" إذا كان في نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — مراجعة git لجلب الملف منها. يمكن أن تكون اسم فرع، أو وسم، أو تجزئة commit. الافتراضي هو رأس فرع "main".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • timeout (float، اختياري، القيمة الافتراضية 10) — عدد الثواني التي يجب انتظارها حتى يرسل الخادم البيانات قبل التوقف. اضبطها على None لتعطيل مهلة الانتهاء (غير موصى به، إذ قد يؤدي اتصال متوقف إلى تعليق الاستدعاء بشكل غير محدود).

يعيد

SafetensorsFileMetadata

معلومات متعلقة بملف safetensors.

يرفع

NotASafetensorsRepoError أو SafetensorsParsingError

  • NotASafetensorsRepoError — إذا لم يكن المستودع مستودع safetensors، أي أنه لا يحتوي على ملف model.safetensors أو ملف model.safetensors.index.json.
  • SafetensorsParsingError — إذا تعذّر تحليل ترويسة ملف safetensors بشكل صحيح.

تحليل البيانات الوصفية من ملف safetensors على Hub.

لحل بيانات الوصف من جميع ملفات safetensors في المستودع دفعة واحدة، استخدم get_safetensors_metadata().

لمزيد من التفاصيل حول صيغة safetensors، راجع https://huggingface.co/docs/safetensors/index#format.

pause_inference_endpoint

< >

( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

المعاملات

  • name (str) — اسم نقطة الاستدلال (Inference Endpoint) التي سيتم إيقافها مؤقتًا.
  • namespace (str، اختياري) — المجال الذي يقع فيه Inference Endpoint. الافتراضي هو المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

InferenceEndpoint

معلومات حول نقطة النهاية للاستدلال المتوقفة مؤقتًا.

إيقاف نقطة استنتاج مؤقتًا.

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

للسهولة، يمكنك أيضاً إيقاف نقطة استنتاج مؤقتاً باستخدام pause_inference_endpoint().

pause_space

< >

( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime

المعاملات

  • repo_id (str) — معرّف المساحة (Space) التي سيتم إيقافها مؤقتًا. مثال: "Salesforce/BLIP2".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

SpaceRuntime

معلومات وقت التشغيل الخاصة بمساحتك بما في ذلك stage=PAUSED والأجهزة المطلوبة.

يرفع

RepositoryNotFoundError أو HfHubHTTPError أو BadRequestError

  • RepositoryNotFoundError — إذا لم يتم العثور على مساحتك (خطأ 404). على الأرجح أن معرف المستودع repo_id خاطئ، أو أن مساحتك خاصة وأنت غير مصادق.
  • HfHubHTTPError — 403 Forbidden: لا يمكن إيقاف مساحة مؤقتًا إلا من قِبل مالكها. إذا كنت ترغب في إدارة مساحة لا تملكها، فاطلب من المالك ذلك من خلال فتح نقاش، أو انسخ المساحة.
  • BadRequestError — إذا كان مساحتك مساحة ثابتة. المساحات الثابتة تعمل دائمًا ولا تُفرض عليها أي رسوم. إذا كنت ترغب في إخفاء مساحة ثابتة، يمكنك تعيينها كخاصة.

أوقف مساحة عملك مؤقتًا.

يتوقف المساحة الموقوفة عن التنفيذ حتى يعيد مالكها تشغيلها يدويًا. وهذا يختلف عن حالة السكون التي تدخل فيها المساحات المجانية بعد 48 ساعة من عدم النشاط. لا تُحتسب مدة الإيقاف في حسابك بغض النظر عن العتاد الذي اخترته. لإعادة تشغيل مساحتك، استخدم restart_space() وانتقل إلى صفحة إعدادات مساحتك.

لمزيد من التفاصيل، يرجى زيارة التوثيق.

permanently_delete_lfs_files

< >

( repo_id: strlfs_files: Iterable[LFSFileInfo]rewrite_history: bool = Truerepo_type: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • repo_id (str) — المستودع الذي تريد عرض ملفات LFS الخاصة به.
  • lfs_files (Iterable[LFSFileInfo]) — قائمة قابلة للتكرار من عناصر LFSFileInfo لحذفها نهائيًا من المستودع. استخدم list_lfs_files() لعرض جميع ملفات LFS في المستودع.
  • rewrite_history (bool، اختياري، الافتراضي True) — ما إذا كان يجب إعادة كتابة سجل المستودع لإزالة مؤشرات الملفات التي تشير إلى ملفات LFS المحذوفة (يُنصح بذلك).
  • repo_type (str، اختياري) — نوع المستودع. اضبطه على "dataset" أو "space" عند التعداد من مجموعة بيانات أو مساحة، أو None أو "model" عند التعداد من نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

احذف ملفات LFS بشكل دائم من مستودع على Hub.

هذا إجراء دائم سيؤثر على جميع الالتزامات التي تشير إلى الملفات المحذوفة وقد يُتلف مستودعك. هذه عملية غير قابلة للتراجع. استخدمها فقط إذا كنت تعرف ما تفعله.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

preupload_lfs_files

< >

( repo_id: stradditions: Iterable[CommitOperationAdd]token: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Nonenum_threads: int = 5free_memory: bool = Truegitignore_content: str | None = None )

المعاملات

  • repo_id (str) — المستودع الذي ستُحدِّث فيه الملفات، على سبيل المثال: "username/custom_transformers".
  • additions (Iterable من CommitOperationAdd) — قائمة الملفات التي سيتم رفعها. تحذير: سيتم تعديل الكائنات الموجودة في هذه القائمة لإدراج معلومات تتعلق بالرفع. لا تعِد استخدام الكائنات نفسها لعمليات التزامن المتعددة.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم الرفع إليه (مثلًا "model" -الافتراضي-، "dataset"، "space" أو "kernel").
  • revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".
  • create_pr (boolean، اختياري) — ما إذا كنت تخطط لإنشاء طلب سحب (Pull Request) بهذا الالتزام. القيمة الافتراضية هي False.
  • num_threads (int، اختياري) — عدد الخيوط المتزامنة لرفع الملفات. القيمة الافتراضية هي 5. إعدادها على 2 يعني أن أقصى عدد من الملفات التي يمكن رفعها بالتزامن هو 2.
  • free_memory (bool، اختياري، القيمة الافتراضية True) — إذا كانت True، يتم استبدال خاصية path_or_fileobj لكل CommitOperationAdd بكائن bytes فارغ بعد الرفع لتوفير الذاكرة. اضبطها على False إذا كنت بحاجة إلى إعادة استخدام كائنات العملية خارج استدعاء create_commit() اللاحق.
  • gitignore_content (str، اختياري) — محتوى ملف .gitignore لمعرفة الملفات التي يجب تجاهلها. ترتيب الأولوية هو أولاً التحقق مما إذا تم تمرير gitignore_content، ثم التحقق مما إذا كان ملف .gitignore موجوداً في قائمة الملفات المراد التثبيت، وأخيراً افتراض استخدام ملف .gitignore المضيف مسبقاً على Hub (إن وُجد).

ارفع ملفات LFS إلى S3 مسبقًا استعدادًا لالتزام مستقبلي.

تُعدّ هذه الطريقة مفيدة إذا كنتَ تولّد الملفات للرفع بشكلٍ فوري ولا ترغب في تخزينها في الذاكرة قبل رفعها دفعةً واحدة.

هذه طريقة مخصصة للمستخدمين المتقدمين. لا ينبغي أن تحتاج إلى استدعائها مباشرةً لإنشاء التزام (commit) عادي. استخدم create_commit() مباشرةً بدلاً من ذلك.

ستتغير عمليات الالتزام أثناء العملية. على وجه الخصوص، سيتم حذف path_or_fileobj المرفق بعد الرفع لتوفير الذاكرة (وتمثيله بكائن bytes فارغ). لا تعِد استخدام نفس الكائنات إلا لتسليمها إلى create_commit(). إذا كنت لا تريد إزالة المحتوى المرفق من كائن عملية الالتزام، فمرر free_memory=False.

مثال:

>>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo

>>> repo_id = create_repo("test_preupload").repo_id

# Generate and preupload LFS files one by one
>>> operations = [] # List of all `CommitOperationAdd` objects that will be generated
>>> for i in range(5):
...     content = ... # generate binary content
...     addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content)
...     preupload_lfs_files(repo_id, additions=[addition]) # upload + free memory
...     operations.append(addition)

# Create commit
>>> create_commit(repo_id, operations=operations, commit_message="Commit all shards")

read_paper

< >

( id: str ) → str

المعاملات

  • id (str) — معرّف ArXiv للورقة.

يعيد

str

محتوى صفحة الورقة البحثية بصيغة Markdown.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 إذا لم يكن البحث موجودًا على Hub.

احصل على محتوى صفحة ورقة بحثية بصيغة Markdown على Hub.

رفض طلب الوصول

< >

( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonerejection_reason: str | Nonetoken: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي تريد رفض طلب الوصول إليه.
  • user (str، اختياري) — اسم المستخدم الذي يجب رفض طلب الوصول الخاص به. يجب تقديم واحد فقط من user أو request_id.
  • request_id (str, اختياري) — معرّف طلب الوصول الذي سيتم رفضه (انظر AccessRequest). مطلوب عندما يتم تكوين المستودع بحيث لا يُشارك أسماء مستخدمي مقدمي الطلبات. يجب تقديم واحد فقط من user أو request_id.
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم رفض طلب الوصول إليه. يجب أن يكون أحد model أو dataset أو space. القيمة الافتراضية هي model.
  • rejection_reason (str, اختياري) — سبب رفض اختياري سيظهر للمستخدم (بحد أقصى 200 حرف).
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 إذا لم يكن المستودع محميًا.
  • HfHubHTTPError — HTTP 403 إذا كان لديك وصول للقراءة فقط إلى المستودع. قد يحدث ذلك إذا لم تكن لديك دور write أو admin في المنظمة التي ينتمي إليها المستودع، أو إذا قمت بتمرير رمز read.
  • HfHubHTTPError — خطأ HTTP 404 إذا لم يكن المستخدم موجودًا على Hub.
  • HfHubHTTPError — HTTP 404 إذا تعذّر العثور على طلب وصول المستخدم.
  • HfHubHTTPError — HTTP 404 إذا كان طلب وصول المستخدم موجودًا بالفعل في قائمة المرفوضين.

رفض طلب وصول من مستخدم لمتخزن محكوم محدد.

تُحوَّل أي طلب مرفوض إلى قائمة المرفوضين. ولا يستطيع المستخدم تنزيل أي ملف من المستودع. يمكن قبول الطلبات المرفوضة أو إلغاؤها في أي وقت باستخدام accept_access_request() و cancel_access_request(). يعود الطلب الملغى إلى قائمة قيد الانتظار، بينما ينتقل الطلب المقبول إلى قائمة المقبولين.

لمزيد من المعلومات حول المستودعات المُقيَّدة، راجع https://huggingface.co/docs/hub/models-gated.

rename_discussion

< >

( repo_id: strdiscussion_num: intnew_title: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionTitleChange

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • discussion_num (int) — رقم المناقشة أو طلب السحب. يجب أن يكون عددًا صحيحًا موجبًا تمامًا.
  • new_title (str) — العنوان الجديد للنقاش
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند الرفع إلى مجموعة بيانات أو مساحة، أو None أو "model" عند الرفع إلى نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

DiscussionTitleChange

حدث تغيير العنوان

يُعيد تسمية نقاش.

أمثلة:

>>> new_title = "New title, fixing a typo"
>>> HfApi().rename_discussion(
...     repo_id="username/repo_name",
...     discussion_num=34,
...     new_title=new_title
... )
# DiscussionTitleChange(id='deadbeef0000000', type='title-change', ...)

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

repo_exists

< >

( repo_id: strrepo_type: str | None = Nonetoken: str | bool | None = None )

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنت تستخرج معلومات المستودع من مجموعة بيانات أو مساحة، أو None أو "model" إذا كنت تستخرج معلومات المستودع من نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يتحقق من وجود مستودع على Hugging Face Hub.

أمثلة:

>>> from huggingface_hub import repo_exists
>>> repo_exists("google/gemma-7b")
True
>>> repo_exists("google/not-a-repo")
False

repo_info

< >

( repo_id: strrevision: str | None = Nonerepo_type: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: ExpandModelProperty_T | ExpandDatasetProperty_T | ExpandSpaceProperty_T | None = Nonetoken: bool | str | None = None ) → Union[SpaceInfo, DatasetInfo, ModelInfo]

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • revision (str، اختياري) — إصدار المستودع الذي سيتم منه جلب المعلومات.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنت تستخرج معلومات المستودع من مجموعة بيانات أو مساحة، أو None أو "model" إذا كنت تستخرج معلومات المستودع من نموذج. القيمة الافتراضية هي None.
  • timeout (float، اختياري) — ما إذا كان يجب تعيين مهلة زمنية للطلب الموجّه إلى Hub.
  • expand (ExpandModelProperty_T أو ExpandDatasetProperty_T أو ExpandSpaceProperty_T، اختياري) — قائمة بالخصائص التي يجب إرجاعها في الاستجابة. عند استخدامه، لن تُرجع إلا الخصائص المدرجة في القائمة. لا يمكن استخدام هذا المعامل إذا تم تمرير files_metadata. لاستعراض قائمة شاملة بالخصائص المتاحة، راجع model_info() أو dataset_info() أو space_info().
  • files_metadata (bool، اختياري) — ما إذا كان سيتم استرداد البيانات الوصفية للملفات في المستودع (الحجم، بيانات LFS الوصفية، إلخ). القيمة الافتراضية هي False.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Union[SpaceInfo, DatasetInfo, ModelInfo]

معلومات المستودع، كائن من نوع huggingface_hub.hf_api.DatasetInfo أو huggingface_hub.hf_api.ModelInfo أو huggingface_hub.hf_api.SpaceInfo.

احصل على كائن المعلومات لمستودع معيّن من نوع معيّن.

يرفع الأخطاء التالية:

  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • RevisionNotFoundError إذا تعذّر العثور على المراجعة التي يجب التحميل منها.

request_space_hardware

< >

( repo_id: strhardware: SpaceHardwaretoken: bool | str | None = Nonesleep_time: int | None = None ) → SpaceRuntime

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم تحديثه. مثال: "bigcode/in-the-stack".
  • hardware (str أو SpaceHardware) — العتاد الذي سيتم تشغيل المساحة عليه. مثال: "t4-medium".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • sleep_time (int, اختياري) — عدد ثوانٍ من عدم النشاط التي يجب انتظارها قبل وضع مساحة في وضع السكون. اضبط القيمة على -1 إذا كنت لا تريد لمساحتك أن تدخل في وضع السكون (وهو السلوك الافتراضي للأجهزة المُحدَّثة). أما في الأجهزة المجانية، فلا يمكنك ضبط وقت السكون (القيمة ثابتة عند 48 ساعة من عدم النشاط). راجع https://huggingface.co/docs/hub/spaces-gpus#sleep-time لمزيد من التفاصيل.

يعيد

SpaceRuntime

معلومات وقت التشغيل حول مساحة (Space) تتضمن مرحلة المساحة (Space stage) والأجهزة (hardware).

طلب أجهزة جديدة لمساحة.

كما يمكن طلب العتاد مباشرةً عند إنشاء مستودع Space! راجع create_repo() للتفاصيل.

rerun_job

< >

( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

المعاملات

  • job_id (str) — معرّف المهمة التي سيتم إعادة تشغيلها.
  • namespace (str، اختياري) — المجال (Namespace) الخاص بالمهمة. القيمة الافتراضية هي مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول المستخدم. الافتراضي هو الرمز المحفوظ محليًا.

يعيد

JobInfo

المهمة التي تم تشغيلها حديثاً.

شغّل مهمة جديدة باستخدام مواصفات المهمة الحالية، بما في ذلك إعدادات إعادة المحاولة والموارد.

resolve_revision

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falsetoken: bool | str | None = None ) → ResolvedRevision

المعاملات

  • repo_id (str) — اسم مستخدم أو منظمة واسم مستودع مفصولان بـ /.
  • repo_type (str، اختياري) — يُعيَّن إلى "dataset" أو "space" أو "kernel" إذا كان المستودع مستودع بيانات أو مساحة أو نواة، وإلى None أو "model" إذا كان نموذجًا. القيمة الافتراضية هي None.
  • revision (str، اختياري) — المراجعة التي يجب حلها. يمكن أن تكون اسم فرع، أو وسم، أو مرجع طلب دمج، أو تجزئة التزام. الافتراضي هو الفرع الافتراضي. إذا تم تمرير ResolvedRevision، يُعاد كما هو - ما لم يتم حله مقابل مستودع آخر، وفي هذه الحالة يتم حل المراجعة التي طُلبت في البداية مرة أخرى.
  • cache_dir (str، Path، اختياري) — المسار إلى المجلد الذي تُخزَّن فيه الملفات المؤقتة. القيمة الافتراضية هي قيمة HF_HUB_CACHE.
  • local_files_only (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، يتم تحديد المراجعة من ذاكرة التخزين المؤقت المحلية فقط، دون الاتصال بـ Hub.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

ResolvedRevision

فئة فرعية من str تحتفظ بكل من المراجعة المطلوبة والتجزئة (hash) للالتزام التي تُحلّ إليها.

يرفع

RevisionResolutionError أو RevisionNotFoundError أو RepositoryNotFoundError

  • RevisionResolutionError — إذا تعذّر تحديد المراجعة: تعذّر الوصول إلى Hub ولا يوجد أي شيء مخزّن محليًا.
  • RevisionNotFoundError — إذا لم يكن الإصدار موجودًا على Hub.
  • RepositoryNotFoundError — إذا تعذّر العثور على المستودع. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على وضع private ولا تملك صلاحية الوصول إليه.

حلّ نسخة (فرع، وسم، مرجع طلب دمج) إلى تجزئة التزام.

يُعدّ هذا الأمر مخصصًا للمكتبات التي تقوم بتنزيل وتحميل عدة مكوّنات من مستودع بشكل منفصل (الإعدادات، الأوزان، المُرمّز، ...). إن حلّ المراجعة مرة واحدة وتحويل ResolvedRevision المُعاد إلى الأمام يضمن أن كل استدعاء تالٍ يستهدف نفس الالتزام (commit) بالضبط، حتى لو تم تحديث المستودع في غضون ذلك. كما أنه يوفر استدعاءات HTTP، إذ يمكن تقديم التنزيلات التي تتم باستخدام تجزئة الالتزام (commit hash) من ذاكرة التخزين المؤقت المحلية دون الحاجة إلى التواصل مع Hub.

يتم تخزين تعيين revision -> commit hash على القرص (في مجلد refs/ ضمن المجلد المؤقت) على أساس أفضل جهد ممكن. إذا تعذّر الوصول إلى Hub لاحقًا (وضع عدم الاتصال، خطأ في الاتصال، انتهاء المهلة، توقف Hub، …)، يُستخدم القيمة المخزّنة مؤقتًا كبديل احتياطي.

إذا كنت بحاجة فقط إلى تنزيل لقطة كاملة للمستودع، فإن استدعاءً واحدًا لـ snapshot_download() يكفي وهو بالفعل يقوم بالعمل الصحيح. resolve_revision مفيد فقط عند تنزيل الملفات بشكل منفصل.

مثال:

>>> from huggingface_hub import hf_hub_download, resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')

# Pass it around: every download is pinned to the same commit
>>> config = hf_hub_download("openai-community/gpt2", "config.json", revision=revision)
>>> weights = hf_hub_download("openai-community/gpt2", "model.safetensors", revision=revision)

restart_space

< >

( repo_id: strtoken: bool | str | None = Nonefactory_reboot: bool = False ) → SpaceRuntime

المعاملات

  • repo_id (str) — معرّف المساحة (Space) التي تريد إعادة تشغيلها. مثال: "Salesforce/BLIP2".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • factory_reboot (bool، اختياري) — إذا كان True، فسيتم إعادة بناء المساحة من الصفر دون تخزين أي متطلبات مؤقتًا.

يعيد

SpaceRuntime

معلومات وقت التشغيل الخاصة بمساحتك.

يرفع

RepositoryNotFoundError أو HfHubHTTPError أو BadRequestError

  • RepositoryNotFoundError — إذا لم يتم العثور على مساحتك (خطأ 404). على الأرجح أن معرف المستودع repo_id خاطئ، أو أن مساحتك خاصة وأنت غير مصادق.
  • HfHubHTTPError — 403 Forbidden: لا يمكن إعادة تشغيل مساحة إلا من قِبل مالكها. إذا كنت ترغب في إعادة تشغيل مساحة لا تملكها، فاطلب من المالك ذلك من خلال فتح نقاش، أو انسخ مساحة جديدة.
  • BadRequestError — إذا كان مساحتك مساحة ثابتة. المساحات الثابتة تعمل دائمًا ولا تُفرض عليها أي رسوم. إذا كنت ترغب في إخفاء مساحة ثابتة، يمكنك تعيينها كخاصة.

أعد تشغيل مساحة عملك.

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

لمزيد من التفاصيل، يرجى زيارة التوثيق.

resume_inference_endpoint

< >

( name: strnamespace: str | None = Nonerunning_ok: bool = Truetoken: bool | str | None = None ) → InferenceEndpoint

المعاملات

  • name (str) — اسم نقطة الاستدلال (Inference Endpoint) التي سيتم استئنافها.
  • namespace (str، اختياري) — المجال الذي يقع فيه Inference Endpoint. الافتراضي هو المستخدم الحالي.
  • running_ok (bool، اختياري) — إذا كان True، فلن تطلق الطريقة خطأً إذا كان نقطة الاستدلال قيد التشغيل بالفعل. القيمة الافتراضية هي True.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

InferenceEndpoint

معلومات حول نقطة الاستدلال (Inference Endpoint) المُستأنفة.

استئناف نقطة نهاية الاستدلال.

للسهولة، يمكنك أيضًا استئناف نقطة استنتاج باستخدام InferenceEndpoint.resume().

resume_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • scheduled_job_id (str) — معرّف المهمة المجدولة.
  • namespace (str، اختياري) — المجال (namespace) الذي يوجد فيه Job المجدول. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

استئناف (إلغاء إيقاف مؤقت) مهمة حساب مجدولة على بنية Hugging Face التحتية.

revision_exists

< >

( repo_id: strrevision: strrepo_type: str | None = Nonetoken: str | bool | None = None )

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • revision (str) — إصدار المستودع الذي يجب التحقق منه.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنت تستخرج معلومات المستودع من مجموعة بيانات أو مساحة، أو None أو "model" إذا كنت تستخرج معلومات المستودع من نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يتحقق مما إذا كان هناك إصدار محدد موجود في مستودع على Hugging Face Hub.

أمثلة:

>>> from huggingface_hub import revision_exists
>>> revision_exists("google/gemma-7b", "float16")
True
>>> revision_exists("google/gemma-7b", "not-a-revision")
False

run_as_future

< >

( fn: Callable[..., R]*args**kwargs ) → Future

المعاملات

  • fn (Callable) — الطريقة التي سيتم تشغيلها في الخلفية.
  • *args, **kwargs — الحُجَج التي سيتم استدعاء الطريقة بها.

يعيد

Future

a Future instance للحصول على نتيجة المهمة.

تشغيل طريقة في الخلفية وإرجاع كائن Future.

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

ملاحظة: تتضمن الطرق الأكثر استخدامًا مثل upload_file() وupload_folder() وcreate_commit() معاملًا باسم run_as_future: bool يتيح استدعاءها مباشرةً في الخلفية. وهذا يعادل استدعاء api.run_as_future(...) عليها لكنه أقل حشوًا.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> future = api.run_as_future(api.whoami) # instant
>>> future.done()
False
>>> future.result() # wait until complete and return result
(...)
>>> future.done()
True

run_job

< >

( image: strcommand: list[str]env: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonessh: bool = Falsenetwork_group: str | None = Nonenetwork_aliases: list[str] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • image (str) — صورة Docker التي سيتم استخدامها. أمثلة: "ubuntu"، "python:3.12"، "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel". مثال على صورة من Space: "hf.co/spaces/lhoestq/duckdb".
  • command (list[str]) — الأمر الذي سيتم تنفيذه. مثال: ["echo", "hello"].
  • env (dict[str, Any]، اختياري) — يحدد متغيرات البيئة الخاصة بالمهمة.
  • secrets (dict[str, Any]، اختياري) — يحدد متغيرات البيئة السرية للعمل.
  • flavor (str، اختياري) — النوع الخاص بالعتاد. راجع JobHardware لمعرفة القيم الممكنة. القيمة الافتراضية هي "cpu-basic".
  • timeout (Union[int, float, str], اختياري) — المدة القصوى للـ Job: int مع s (ثوانٍ، الافتراضي)، m (دقائق)، h (ساعات) أو d (أيام). مثال: 300 أو "5m" لمدة 5 دقائق.
  • attempts (int، اختياري) — الحد الأقصى لعدد المحاولات، بما في ذلك التشغيل الأولي. القيمة الافتراضية هي 1. على سبيل المثال، يعيد 3 محاولة تشغيل مهمة (Job) فاشلة حتى مرتين.
  • name (str، اختياري) — اسم للمهمة. يُخزَّن كوسم name. لا يمكن تمريره مع مفتاح name في labels. لا يجب أن تكون الأسماء فريدة. القيمة الافتراضية هي اسم مشتق من الصورة والأمر (مع لاحقة تجزئة قصيرة).
  • labels (dict[str, str]، اختياري) — التسميات التي سيتم إرفاقها بالمهمة (أزواج مفتاح-قيمة).
  • volumes (list[Volume]، اختياري) — حاويات Hugging Face Buckets أو مستودعات Repos تُركَّب كحجميات داخل حاوية المهمة. كل حجمية هي Volume تحتوي على type ("bucket"، "model"، "dataset"، أو "space")، وsource (مثل "username/my-bucket")، وmount_path (مثل "/data").
  • expose (list[int]، اختياري) — منافذ الحاوية التي يجب كشفها عبر وكيل المهام. كل منفذ مدرج يكون متاحًا على نطاق المهام العام (مثل https://<job_id>--8000.hf.jobs). يتطلب الوصول دائمًا رمز HF مع صلاحية القراءة في مساحة أسماء المهمة. استخدم expose_public للوصول غير الموثق.
  • expose_public (list[int], اختياري) — منافذ يجب كشفها عبر وكيل Jobs دون مصادقة. لا يلزم إدراجها في expose.
  • ssh (bool، اختياري) — إذا كانت القيمة True، فيمكن الوصول إلى حاوية المهمة عبر SSH على العنوان المحدد بواسطة job.status.ssh_url (مثل ssh <job_id>@ssh.hf.jobs، أو hf jobs ssh <job_id> من سطر الأوامر). يتطلب الاتصال صلاحيات الكتابة في مساحة أسماء المهمة ومفتاح SSH عام مسجّل على Hub (https://huggingface.co/settings/keys). القيمة الافتراضية هي False.
  • network_group (str, اختياري) — اسم مجموعة الشبكة التي سيتم الانضمام إليها. تُجمع المهام الموجودة في نفس مساحة الاسم ومجموعة الموارد والتي تتشارك المجموعة نفسها معًا، ويمكنها الوصول إلى بعضها البعض على كل منفذ. داخل كل عضو، يُحل HF_NETWORK_GROUP_HOSTNAME إلى كل عضو من أعضاء المجموعة. أحرف صغيرة وأرقام وشرطات، بحد أقصى 46 حرفًا.
  • network_aliases (list[str]، اختياري) — الأسماء المستعارة التي يطالب بها هذا العمل ضمن مجموعته الشبكية. تصل الأعضاء إلى الأعمال التي تطالب باسم مستعار عبر ${HF_NETWORK_GROUP_PREFIX}<alias>. قد تطالب عدة أعمال بنفس الاسم المستعار. أحرف أبجدية رقمية صغيرة وشرطات، بحد أقصى 34 حرفاً، فريدة ضمن العمل. يتطلب network_group.
  • resource_group_id (str, اختياري) — معرّف مجموعة الموارد التي سيتم إنشاء المهمة (Job) فيها. يُستخدم للتحكم في الوصول إلى الموارد داخل المنظمة وللميزات المتعلقة بتخصيص التكاليف وحدود الإنفاق. إذا لم يُقدَّم، تُنشأ المهمة خارج أي مجموعة موارد.
  • namespace (str، اختياري) — المجال الذي سيتم فيه إنشاء المهمة. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

شغّل مهام الحساب على بنية Hugging Face التحتية.

مثال:

شغّل أول مهمة لك:

>>> from huggingface_hub import run_job
>>> run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])

تشغيل مهمة وحدة معالجة رسومية:

>>> from huggingface_hub import run_job
>>> image = "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"
>>> command = ["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"]
>>> run_job(image=image, command=command, flavor="a10g-small")

تشغيل مهمة مع أحجام:

>>> from huggingface_hub import Volume, run_job
>>> dataset_volume = Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")
>>> output_bucket_volume = Volume(type="bucket", source="username/my-bucket", mount_path="/output")
>>> image = "duckdb/duckdb"
>>> command = ["duckdb", "-c", "COPY (SELECT * FROM '/data/**/*.parquet' LIMIT 5) TO '/output/first-rows.parquet'"]
>>> run_job(image=image, command=command, volumes=[dataset_volume, output_bucket_volume])

run_uv_job

< >

( script: strscript_args: list[str] | None = Nonedependencies: list[str] | None = Nonepython: str | None = Noneimage: str | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonessh: bool = Falsenetwork_group: str | None = Nonenetwork_aliases: list[str] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • script (str) — مسار أو عنوان URL لسكربت UV، أو أمر.
  • script_args (list[str]، اختياري) — الحجج المراد تمريرها إلى السكربت أو الأمر.
  • dependencies (list[str]، اختياري) — التبعيات المستخدمة لتشغيل سكريبت UV.
  • python (str، اختياري) — استخدم إصدارًا محددًا من Python. الافتراضي هو 3.12.
  • image (str، اختياري، القيمة الافتراضية هي “ghcr.io/astral-sh/uv —python3.12-bookworm”): استخدم صورة Docker مخصصة مع تثبيت uv.
  • env (dict[str, Any]، اختياري) — يحدد متغيرات البيئة الخاصة بالمهمة.
  • secrets (dict[str, Any]، اختياري) — يحدد متغيرات البيئة السرية للعمل.
  • flavor (str، اختياري) — النوع الخاص بالعتاد. راجع JobHardware لمعرفة القيم الممكنة. القيمة الافتراضية هي "cpu-basic".
  • timeout (Union[int, float, str], اختياري) — المدة القصوى للـ Job: int مع s (ثوانٍ، الافتراضي)، m (دقائق)، h (ساعات) أو d (أيام). مثال: 300 أو "5m" لمدة 5 دقائق.
  • attempts (int، اختياري) — الحد الأقصى لعدد المحاولات، بما في ذلك التشغيل الأولي. القيمة الافتراضية هي 1.
  • name (str، اختياري) — اسم للوظيفة. يُخزَّن كوسم name. لا يمكن تمريره مع مفتاح name في labels. لا يجب أن تكون الأسماء فريدة. القيمة الافتراضية هي اسم مشتق من السكربت وحوامله (مع لاحقة تجزئة قصيرة).
  • labels (dict[str, str]، اختياري) — التسميات التي سيتم إرفاقها بالمهمة (أزواج مفتاح-قيمة).
  • volumes (list[Volume]، اختياري) — حاويات Hugging Face Buckets أو مستودعات Repos تُركَّب كحجميات داخل حاوية المهمة. كل حجمية هي Volume تحتوي على type ("bucket"، "model"، "dataset"، أو "space")، وsource (مثل "username/my-bucket")، وmount_path (مثل "/data").
  • expose (list[int]، اختياري) — منافذ الحاوية التي يجب كشفها عبر وكيل المهام. كل منفذ مدرج يكون متاحًا على نطاق المهام العام (مثل https://<job_id>--8000.hf.jobs). يتطلب الوصول دائمًا رمز HF مع صلاحية القراءة في مساحة أسماء المهمة. استخدم expose_public للوصول غير الموثق.
  • expose_public (list[int], اختياري) — منافذ يجب كشفها عبر وكيل Jobs دون مصادقة. لا يلزم إدراجها في expose.
  • ssh (bool، اختياري) — إذا كانت القيمة True، فيمكن الوصول إلى حاوية المهمة عبر SSH على العنوان المحدد بواسطة job.status.ssh_url (مثل ssh <job_id>@ssh.hf.jobs، أو hf jobs ssh <job_id> من سطر الأوامر). يتطلب الاتصال صلاحيات الكتابة في مساحة أسماء المهمة ومفتاح SSH عام مسجّل على Hub (https://huggingface.co/settings/keys). القيمة الافتراضية هي False.
  • network_group (str, اختياري) — اسم مجموعة الشبكة التي سيتم الانضمام إليها. تُجمع المهام الموجودة في نفس مساحة الاسم ومجموعة الموارد والتي تتشارك المجموعة نفسها معًا، ويمكنها الوصول إلى بعضها البعض على كل منفذ. داخل كل عضو، يُحل HF_NETWORK_GROUP_HOSTNAME إلى كل عضو من أعضاء المجموعة. أحرف صغيرة وأرقام وشرطات، بحد أقصى 46 حرفًا.
  • network_aliases (list[str]، اختياري) — الأسماء المستعارة التي يطالب بها هذا العمل ضمن مجموعته الشبكية. تصل الأعضاء إلى الأعمال التي تطالب باسم مستعار عبر ${HF_NETWORK_GROUP_PREFIX}<alias>. قد تطالب عدة أعمال بنفس الاسم المستعار. أحرف أبجدية رقمية صغيرة وشرطات، بحد أقصى 34 حرفاً، فريدة ضمن العمل. يتطلب network_group.
  • resource_group_id (str, اختياري) — معرّف مجموعة الموارد التي سيتم إنشاء المهمة (Job) فيها. يُستخدم للتحكم في الوصول إلى الموارد داخل المنظمة وللميزات المتعلقة بتخصيص التكاليف وحدود الإنفاق. إذا لم يُقدَّم، تُنشأ المهمة خارج أي مجموعة موارد.
  • namespace (str، اختياري) — المجال الذي سيتم فيه إنشاء المهمة. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

شغّل مهمة سكربت UV على بنية Hugging Face التحتية.

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

مثال:

تشغيل سكربت من عنوان URL:

>>> from huggingface_hub import run_uv_job
>>> script = "https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> run_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small")

تشغيل سكربت محلي:

>>> from huggingface_hub import run_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> run_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small")

نفّذ أمرًا:

>>> from huggingface_hub import run_uv_job
>>> script = "lighteval"
>>> script_args= ["endpoint", "inference-providers", "model_name=openai/gpt-oss-20b,provider=auto", "lighteval|gsm8k|0|0"]
>>> run_uv_job(script, script_args=script_args, dependencies=["lighteval"], flavor="a10g-small")

قم بتركيب أحجام التخزين، على سبيل المثال لحفظ نقاط التفتيش للنموذج أثناء التدريب:

>>> from huggingface_hub import Volume, run_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--output_dir", "/training-outputs/training-v3-final", ...]
>>> checkpoints_bucket = Volume(type="bucket", source="username/my-bucket", mount_path="/training-outputs")
>>> run_uv_job(script, script_args=script_args, volumes=[checkpoints_bucket])

scale_to_zero_inference_endpoint

< >

( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

المعاملات

  • name (str) — اسم نقطة الاستدلال (Inference Endpoint) التي سيتم تصفير مقياسها.
  • namespace (str، اختياري) — المجال الذي يقع فيه Inference Endpoint. الافتراضي هو المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

InferenceEndpoint

معلومات حول نقطة النهاية للاستدلال التي تم تصفير مقياسها.

قم بتقليص نقطة نهاية الاستدلال إلى صفر.

لن يتم فرض أي رسوم على نقطة استنتاج (Inference Endpoint) تم ضبط مقياسها عند الصفر. ستُستأنف عند الطلب التالي الموجّه إليها، مع تأخير ناتج عن بدء تشغيل بارد (cold start). وهذا يختلف عن إيقاف نقطة الاستنتاج مؤقتًا باستخدام pause_inference_endpoint()، حيث يتطلب ذلك استئنافًا يدويًا باستخدام resume_inference_endpoint().

للسهولة، يمكنك أيضًا تصفير نقطة الاستدلال باستخدام InferenceEndpoint.scale_to_zero().

search_spaces

< >

( query: strfilter: str | Iterable[str] | None = Nonesdk: str | list[str] | None = Noneinclude_non_running: bool = Falsetoken: bool | str | None = None ) → Iterable[SpaceSearchResult]

المعاملات

  • query (str) — نص استعلام البحث.
  • filter (str أو Iterable[str]، اختياري) — وسم نصي أو قائمة وسوم للترشيح بناءً عليها.
  • sdk (str أو list[str]، اختياري) — تصفية حسب SDK (مثل "gradio"، "docker"، "static").
  • include_non_running (bool، اختياري) — ما إذا كان يجب تضمين مساحات Spaces غير العاملة في النتائج. القيمة الافتراضية هي False.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

Iterable[SpaceSearchResult]

قابلة للتكرار من كائنات SpaceSearchResult.

استكشف المساحات على الهاب باستخدام البحث الدلالي.

تستخدم هذه النقطة النهائية البحث الدلالي (المبني على التضمينات) للاستعلامات متعددة الكلمات، والبحث النصي الكامل للاستعلامات أحادية الكلمة.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> results = list(api.search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'
>>> results[0].ai_category
'Image Generation'

set_space_sleep_time

< >

( repo_id: strsleep_time: inttoken: bool | str | None = None ) → SpaceRuntime

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم تحديثه. مثال: "bigcode/in-the-stack".
  • sleep_time (int, اختياري) — عدد ثوانٍ من عدم النشاط التي يجب انتظارها قبل وضع مساحة في وضع السكون. اضبط القيمة على -1 إذا كنت لا تريد إيقاف مساحة مؤقتًا (السلوك الافتراضي للأجهزة المُحدَّثة). أما بالنسبة للأجهزة المجانية، فلا يمكنك ضبط وقت السكون (القيمة ثابتة عند 48 ساعة من عدم النشاط). راجع https://huggingface.co/docs/hub/spaces-gpus#sleep-time لمزيد من التفاصيل.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

SpaceRuntime

معلومات وقت التشغيل حول مساحة (Space) تتضمن مرحلة المساحة (Space stage) والأجهزة (hardware).

اضبط وقت نوم مخصصًا لمساحة تعمل على أجهزة محسّنة.

ستدخل مساحةُك في وضع السكون بعد X ثانية من عدم النشاط. لن يتم احتساب أي رسوم عليك عندما تكون مساحتك في وضع «السكون». إذا وصل زائر جديد إلى مساحتك، فسيتم «إيقاظها». يمكن فقط للأجهزة المُطوَّرة أن تمتلك وقت سكون قابلًا للضبط. لمعرفة المزيد حول مرحلة السكون، يُرجى الرجوع إلى https://huggingface.co/docs/hub/spaces-gpus#sleep-time.

من الممكن أيضًا تعيين وقت نوم مخصص عند طلب العتاد باستخدام request_space_hardware().

set_space_volumes

< >

( repo_id: strvolumes: list[Volume]token: bool | str | None = None )

المعاملات

  • repo_id (str) — معرّف المساحة (Space) التي سيتم تحديثها. مثال: "username/my-space".
  • volumes (list[Volume]) — قائمة من كائنات Volume للتثبيت. يحتوي كل حجم على type ("bucket"، "model"، "dataset"، أو "space")، وsource (معرّف المستودع أو الدلو)، وmount_path (المسار داخل الحاوية)، وحقول اختيارية revision، read_only، وpath.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

BadRequestError

  • BadRequestError — إذا كان المساحة مساحة ثابتة (لا يتم دعم الأحجام في المساحات الثابتة).

اضبط الأحجام لمساحة.

تُعيّن (أو تستبدل) قائمة الأحجام (volumes) المرفقة في المساحة (Space). يمنح كل حجم حاوية المساحة إمكانية الوصول إلى مورد في Hub (نموذج، مجموعة بيانات، أو دلو تخزين).

مثال:

>>> from huggingface_hub import HfApi, Volume
>>> api = HfApi()
>>> api.set_space_volumes(
...     "username/my-space",
...     volumes=[
...         Volume(type="model", source="username/my-model", mount_path="/models", read_only=True),
...         Volume(type="bucket", source="username/my-bucket", mount_path="/data"),
...     ],
... )

snapshot_download

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_dir: str | Path | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[base_tqdm] | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo

المعاملات

  • repo_id (str) — اسم مستخدم أو منظمة واسم مستودع مفصولان بـ /.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنتَ تقوم بتنزيل من مجموعة بيانات أو مساحة، أو None أو "model" إذا كنتَ تقوم بتنزيل من نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — معرّف اختيارية لمراجعة Git يمكن أن يكون اسم فرع، أو وسم، أو تجزئة التزام.
  • cache_dir (str، Path، اختياري) — المسار إلى المجلد الذي تُخزَّن فيه الملفات المؤقتة.
  • local_dir (str أو Path، اختياري) — إذا تم تقديمه، فسيتم وضع الملفات المُحمَّلة تحت هذا المجلد.
  • etag_timeout (float، اختياري، القيمة الافتراضية 10) — عند جلب ETag، عدد الثواني التي يجب انتظارها حتى يرسل الخادم البيانات قبل التوقف، وهي القيمة التي تُمرَّر إلى httpx2.request.
  • force_download (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب تنزيل الملف حتى لو كان موجودًا مسبقًا في ذاكرة التخزين المؤقت المحلية.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • local_files_only (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فتجنّب تنزيل الملف وعُدّ مسار الملف المخزّن محليًا إذا كان موجودًا.
  • allow_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، يتم تنزيل الملفات التي تطابق نمطًا واحدًا على الأقل فقط.
  • ignore_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، فلن يتم تنزيل الملفات المطابقة لأي من الأنماط.
  • max_workers (int، اختياري) — عدد الخيوط المتزامنة لتنزيل الملفات (خيط واحد = تنزيل ملف واحد). القيمة الافتراضية هي 8.
  • tqdm_class (tqdm, اختياري) — إذا تم توفيره، يُغني عن السلوك الافتراضي لشريط التقدم. يجب أن يرث الحُجج المُمرَّرة من tqdm.auto.tqdm أو يحاكي سلوكه على الأقل. لاحظ أن tqdm_class لا يُمرَّر إلى كل عملية تنزيل على حدة. الافتراضي هو شريط تقدم مخصص من HF يمكن تعطيله عن طريق تعيين متغير البيئة HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، يتم تنفيذ تشغيل تجريبي دون تنزيل الملفات فعليًا. تُرجع قائمة من كائنات DryRunFileInfo تحتوي على معلومات حول ما كان سيُتنزَّل.

يعيد

str أو قائمة من DryRunFileInfo

  • إذا كان dry_run=False: مسار مجلد لقطة المستودع.
  • إذا كان dry_run=True: قائمة من كائنات DryRunFileInfo تحتوي على معلومات التحميل.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError أو EnvironmentError أو OSError أو ValueError

  • RepositoryNotFoundError — إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • RevisionNotFoundError — إذا تعذّر العثور على المراجعة التي يجب التحميل منها.
  • EnvironmentError — إذا كان token=True ولم يتم العثور على الرمز.
  • OSError — إذا تعذّر تحديد ETag.
  • ValueError — إذا كانت قيمة بعض المعاملات غير صالحة.

تنزيل ملفات المستودع.

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

إذا تم توفير local_dir، فسيتم تكرار هيكل الملفات من المستودع في هذا الموقع. عند استخدام هذا الخيار، لن يتم استخدام cache_dir وسيتم إنشاء مجلد .cache/huggingface/ في جذر local_dir لتخزين بعض البيانات الوصفية المتعلقة بالملفات التي تم تنزيلها. وعلى الرغم من أن هذا الآلية ليست قوية مثل نظام التخزين المؤقت الرئيسي، إلا أنها مُحسّنة لسحب أحدث إصدار من المستودع بانتظام.

بديل آخر هو استنساخ المستودع، لكن هذا يتطلب تثبيت git و git-lfs وتكوينهما بشكل صحيح. كما أنه لا يمكن تصفية الملفات المراد تنزيلها عند استنساخ مستودع باستخدام git.

space_info

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandSpaceProperty_T] | None = Nonetoken: bool | str | None = None ) → SpaceInfo

المعاملات

  • repo_id (str) — مساحة أسماء (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • revision (str، اختياري) — إصدار مستودع المساحة الذي سيتم منه جلب المعلومات.
  • timeout (float، اختياري) — ما إذا كان يجب تعيين مهلة زمنية للطلب الموجّه إلى Hub.
  • files_metadata (bool، اختياري) — ما إذا كان سيتم استرداد البيانات الوصفية للملفات في المستودع (الحجم، بيانات LFS الوصفية، إلخ). القيمة الافتراضية هي False.
  • expand (list[ExpandSpaceProperty_T], اختياري) — قائمة بالخصائص التي يجب إرجاعها في الاستجابة. عند الاستخدام، لن تُرجع إلا الخصائص الموجودة في القائمة. لا يمكن استخدام هذا المعامل إذا تم تمرير full. القيم الممكنة هي "author"، "cardData"، "createdAt"، "datasets"، "disabled"، "lastModified"، "likes"، "models"، "private"، "region"، "runtime"، "sdk"، "siblings"، "sha"، "subdomain"، "tags"، "trendingScore"، "usedStorage"، و"resourceGroup".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

SpaceInfo

معلومات مستودع المساحة.

احصل على معلومات حول مساحة محددة على huggingface.co.

يمكن أن يكون المساحة خاصة إذا قمت بتمرير رمز مقبول.

يرفع الأخطاء التالية:

  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • RevisionNotFoundError إذا تعذّر العثور على المراجعة التي يجب التحميل منها.

super_squash_history

< >

( repo_id: strbranch: str | None = Nonecommit_message: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None )

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • branch (str، اختياري) — الفرع الذي سيتم دمج تغييراته. القيمة الافتراضية هي رأس فرع "main".
  • commit_message (str، اختياري) — رسالة الالتزام (commit message) المستخدمة للالتزام المدمج (squashed commit).
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" عند سرد الالتزامات من مجموعة بيانات أو مساحة، أو None أو "model" عند السرد من نموذج. القيمة الافتراضية هي None.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError أو BadRequestError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type خاطئ، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • RevisionNotFoundError — إذا تعذّر العثور على الفرع الذي يجب دمجه.
  • BadRequestError — إذا كان المرجع غير صالح لفرع. لا يمكنك ضغط السجل على الوسوم.

دمج سجلّ الالتزامات على فرعٍ في مستودعٍ على Hub.

يُعدّ دمج سجل المستودع مفيدًا عندما تعلم أنك ستقوم بمئات من عمليات الإضافة ولا تريد إرباك السجل. لا يمكن تنفيذ دمج عمليات الإضافة إلا من رأس الفرع.

بمجرد دمج التغيرات، لا يمكن استعادة سجل التغيرات. هذه عملية لا يمكن التراجع عنها.

بمجرد ضغط سجل فرع، لم يعد من الممكن دمجه مرة أخرى في فرع آخر لأن سجلاتهما ستكون قد تباعدت.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Create repo
>>> repo_id = api.create_repo("test-squash").repo_id

# Make a lot of commits.
>>> api.upload_file(repo_id=repo_id, path_in_repo="file.txt", path_or_fileobj=b"content")
>>> api.upload_file(repo_id=repo_id, path_in_repo="lfs.bin", path_or_fileobj=b"content")
>>> api.upload_file(repo_id=repo_id, path_in_repo="file.txt", path_or_fileobj=b"another_content")

# Squash history
>>> api.super_squash_history(repo_id=repo_id)

suspend_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • scheduled_job_id (str) — معرّف المهمة المجدولة.
  • namespace (str، اختياري) — المجال (namespace) الذي يوجد فيه Job المجدول. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

إيقاف (تعليق) مهمة حساب مجدولة على بنية Hugging Face التحتية.

sync_bucket

< >

( source: str | None = Nonedest: str | None = Nonedelete: bool = Falseignore_times: bool = Falseignore_sizes: bool = Falseexisting: bool = Falseignore_existing: bool = Falseinclude: list[str] | None = Noneexclude: list[str] | None = Nonefilter_from: str | None = Noneplan: str | None = Noneapply: str | None = Nonedry_run: bool = Falseverbose: bool = Falsequiet: bool = Falsetoken: bool | str | None = None ) → [SyncPlan]

المعاملات

  • source (str، اختياري) — مسار المصدر: مجلد محلي أو hf://buckets/namespace/bucket_name(/prefix). مطلوب ما لم يتم استخدام apply.
  • dest (str، اختياري) — مسار الوجهة: مجلد محلي أو hf://buckets/namespace/bucket_name(/prefix). مطلوب ما لم يتم استخدام apply.
  • delete (bool، اختياري، القيمة الافتراضية False) — حذف الملفات الموجودة في الوجهة وغير الموجودة في المصدر.
  • ignore_times (bool، اختياري، القيمة الافتراضية False) — تخطي الملفات بناءً على الحجم فقط، مع تجاهل أوقات التعديل.
  • ignore_sizes (bool، اختياري، القيمة الافتراضية False) — تخطي الملفات بناءً على أوقات التعديل فقط، مع تجاهل الأحجام.
  • existing (bool، اختياري، القيمة الافتراضية False) — تخطي إنشاء ملفات جديدة على المستقبل (تحديث الملفات الموجودة فقط).
  • ignore_existing (bool، اختياري، القيمة الافتراضية False) — تخطي تحديث الملفات الموجودة لدى المستقبل (إنشاء الملفات الجديدة فقط).
  • include (list[str]، اختياري) — تضمين الملفات المطابقة للنمط (بأسلوب fnmatch).
  • exclude (list[str]، اختياري) — استبعاد الملفات المطابقة لأنماط (بأسلوب fnmatch).
  • filter_from (str، اختياري) — مسار إلى ملف تصفية يحتوي على قواعد تضمين/استبعاد.
  • plan (str، اختياري) — احفظ مخطط المزامنة في هذا الملف بصيغة JSONL بدلاً من التنفيذ.
  • apply (str, optional) — تطبيق ملف خطة محفوظ مسبقًا. عند ضبطه، لا حاجة إلى source وdest.
  • dry_run (bool، اختياري، القيمة الافتراضية False) — يطبع خطة المزامنة إلى stdout بصيغة JSONL دون تنفيذها.
  • verbose (bool، اختياري، القيمة الافتراضية False) — عرض عمليات مفصّلة لكل ملف.
  • quiet (bool، اختياري، الافتراضي False) — كبت جميع المخرجات وأشرطة التقدم.
  • token (Union[bool, str, None], اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا.

يعيد

[SyncPlan]

خطة المزامنة المحسوبة (أو المحمّلة).

مزامنة الملفات بين مجلد محلي ودلو.

يعادل هذا الأمر أمر hf buckets sync في سطر الأوامر. يجب أن يكون أحدهما من source أو dest مسار دلو (hf://buckets/...) والآخر مسار مجلد محلي.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Upload local directory to bucket
>>> api.sync_bucket("./data", "hf://buckets/username/my-bucket")

# Download bucket to local directory
>>> api.sync_bucket("hf://buckets/username/my-bucket", "./data")

# Sync with delete and filtering
>>> api.sync_bucket(
...     "./data",
...     "hf://buckets/username/my-bucket",
...     delete=True,
...     include=["*.safetensors"],
... )

# Dry run: preview what would be synced
>>> plan = api.sync_bucket("./data", "hf://buckets/username/my-bucket", dry_run=True)
>>> plan.summary()
{'uploads': 3, 'downloads': 0, 'deletes': 0, 'skips': 1, 'total_size': 4096}

# Save plan for review, then apply
>>> api.sync_bucket("./data", "hf://buckets/username/my-bucket", plan="sync-plan.jsonl")
>>> api.sync_bucket(apply="sync-plan.jsonl")

sync_job_volume

< >

( source: str | Pathmount_path: strremote_name: str | None = Noneread_only: bool = Truenamespace: str | None = Nonetoken: bool | str | None = None ) → Volume

المعاملات

  • source (str أو Path) — المسار إلى مجلد محلي للمزامنة.
  • mount_path (str) — مسار التركيب داخل حاوية المهمة، مثل "/inputs". يجب أن يبدأ بـ /.
  • remote_name (str، اختياري) — اسم مجلد الفرع في الدلو (bucket) الذي سيتم المزامنة معه. الافتراضي هو اسم {dirname}-{hash} مشتق من مسار المصدر واسم مضيف الجهاز.
  • read_only (bool، اختياري، القيمة الافتراضية True) — تثبيت وحدة التخزين للقراءة فقط في المهمة. مرّر False للسماح للمهمة بالكتابة مرة أخرى إلى مجلد الدلو (على سبيل المثال لاستخراج المخرجات باستخدام sync_bucket() لاحقًا).
  • namespace (str، اختياري) — المجال الذي يملك دلو jobs-artifacts. الافتراضي هو مجال المستخدم الحالي. استخدم نفس المجال الخاص بالمهمة التي ستثبّت الوحدة.
  • token (Union[bool, str, None]، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيُستخدم الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

الحجم

حجم دلو (Bucket volume) مُقيّد النطاق بالملف الفرعي المتزامن، ليتم تمريره في قائمة volumes الخاصة بـ run_job() أو run_uv_job() أو create_scheduled_job() أو create_scheduled_uv_job().

مزامنة مجلد محلي مع دلو وإرجاع Volume جاهز للتثبيت في مهمة.

تُحمَّل الملفات إلى مجلد فرعي داخل حاوية {namespace}/jobs-artifacts (يتم إنشاؤه تلقائيًا كخاص؛ ويُصدر تحذيرًا إذا كان موجودًا مسبقًا وعامًا) باستخدام نفس منطق المزامنة المستخدم في sync_bucket(): فإعادة مزامنة نفس المجلد لا ترفع سوى الملفات الجديدة أو المعدَّلة. افتراضيًا، يُشتق اسم المجلد الفرعي من مسار المجلد واسم مضيف الجهاز، بحيث تعيد الاستدعاءات المتكررة من نفس المجلد استخدام نفس المجلد البعيد. مرِّر remote_name لاستخدام اسم ثابت بدلاً من ذلك.

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

مثال:

>>> from huggingface_hub import run_uv_job, sync_job_volume

# Upload ./training-data once, then run multiple jobs against it
>>> volume = sync_job_volume("./training-data", "/data")
>>> run_uv_job("train.py", script_args=["--learning-rate", "0.01"], volumes=[volume])
>>> run_uv_job("train.py", script_args=["--learning-rate", "0.05"], volumes=[volume])

# Read-write volume to retrieve outputs after the job completes
>>> volume = sync_job_volume("./outputs", "/outputs", read_only=False)
>>> job = run_uv_job("process.py", volumes=[volume])

trigger_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

المعاملات

  • scheduled_job_id (str) — معرّف المهمة المجدولة.
  • namespace (str، اختياري) — المجال (namespace) الذي يوجد فيه Job المجدول. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

JobInfo

معلومات حول التشغيل المُفعّل.

يرفع

HfHubHTTPError

  • HfHubHTTPError — خطأ HTTP 409 إذا كان هناك مثيل آخر قيد التشغيل بالفعل ومعطّل concurrency في المهمة المجدولة.

تشغيل مهمة مجدولة فوراً.

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

على عكس

< >

( repo_id: strtoken: bool | str | None = Nonerepo_type: str | None = None )

المعاملات

  • repo_id (str) — المستودع الذي تريد إلغاء إعجابه. مثال: "user/my-cool-model".
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" إذا كنت تزيل الإعجاب عن مجموعة بيانات أو مساحة، أو None أو "model" إذا كنت تزيل الإعجاب عن نموذج. القيمة الافتراضية هي None.

يرفع

RepositoryNotFoundError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type غير صحيح، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.

على عكس مستودع معين على Hub (مثلًا، إزالة من قائمة المفضلة).

للمنع من الاستخدام غير المشروع، لا يمكن like مستودعًا من سكربت.

انظر أيضًا إلى list_liked_repos().

مثال:

>>> from huggingface_hub import list_liked_repos, unlike
>>> "gpt2" in list_liked_repos().models # we assume you have already liked gpt2
True
>>> unlike("gpt2")
>>> "gpt2" in list_liked_repos().models
False

update_bucket_settings

< >

( bucket_id: strprivate: booltoken: bool | str | None = None )

المعاملات

  • bucket_id (str) — معرّف الدلو (مثلًا "username/my-bucket").
  • private (bool) — ما إذا كان سيتم جعل الدلو خاصًا.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يرفع

BucketNotFoundError أو or

  • BucketNotFoundError — إذا تعذّر العثور على الدلو. قد يكون السبب عدم وجوده،
  • or — لأنه مُعيَّن على private ولا تملك صلاحية الوصول إليه.

تحديث إعدادات دلو على Hub.

حاليًا، الإعداد المدعوم الوحيد هو مستوى ظهور الدلو.

مثال:

>>> from huggingface_hub import update_bucket_settings

>>> # Make a bucket public
>>> update_bucket_settings(bucket_id="Wauplin/first-bucket", private=False)

>>> # Make it private again
>>> update_bucket_settings(bucket_id="Wauplin/first-bucket", private=True)

update_collection_item

< >

( collection_slug: stritem_object_id: strnote: str | None = Noneposition: int | None = Nonetoken: bool | str | None = None )

المعاملات

  • collection_slug (str) — اسم الرابط (Slug) للمجموعة المراد تحديثها. مثال: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_object_id (str) — معرّف العنصر في المجموعة. هذا ليس معرّف العنصر على Hub (repo_id أو paper id). يجب استرداده من كائن CollectionItem. مثال: collection.items[0].item_object_id.
  • note (str، اختياري) — ملاحظة تُرفق بالعنصر في المجموعة. الحد الأقصى لحجم الملاحظة هو 500 حرف.
  • position (int، اختياري) — الموقع الجديد للعنصر في المجموعة.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

تحديث عنصر في مجموعة.

مثال:

>>> from huggingface_hub import get_collection, update_collection_item

# Get collection first
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")

# Update item based on its ID (add note + update position)
>>> update_collection_item(
...     collection_slug="TheBloke/recent-models-64f9a55bb3115b4f513ec026",
...     item_object_id=collection.items[-1].item_object_id,
...     note="Newly updated model!",
...     position=0,
... )

update_collection_metadata

< >

( collection_slug: strtitle: str | None = Nonedescription: str | None = Noneposition: int | None = Noneprivate: bool | None = Nonetheme: str | None = Nonetoken: bool | str | None = None )

المعاملات

  • collection_slug (str) — اسم الرابط (Slug) للمجموعة المراد تحديثها. مثال: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • title (str) — عنوان المجموعة المراد تحديثها.
  • description (str، اختياري) — وصف المجموعة التي سيتم تحديثها. الحد الأقصى لحجم الوصف هو 150 حرفًا.
  • position (int، اختياري) — الموقع الجديد للمجموعة في قائمة مجموعات المستخدم.
  • private (bool، اختياري) — ما إذا كان يجب أن تكون المجموعة خاصة أم لا.
  • theme (str، اختياري) — موضوع المجموعة على Hub.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

تحديث بيانات الوصف الخاصة بمجموعة على Hub.

جميع الحُجج اختيارية. لن يتم تحديث سوى البيانات الوصفية المُقدَّمة.

يعيد: Collection

مثال:

>>> from huggingface_hub import update_collection_metadata
>>> collection = update_collection_metadata(
...     collection_slug="username/iccv-2023-64f9a55bb3115b4f513ec026",
...     title="ICCV Oct. 2023",
...     description="Portfolio of models, datasets, papers and demos I presented at ICCV Oct. 2023",
...     private=False,
...     theme="pink",
... )
>>> collection.slug
"username/iccv-oct-2023-64f9a55bb3115b4f513ec026"
# ^collection slug got updated but not the trailing ID

update_collection_resource_group

< >

( collection_slug: strresource_group_id: str | Nonetoken: bool | str | None = None )

المعاملات

  • collection_slug (str) — اسم الرابط (Slug) للمجموعة المراد تحديثها. مثال: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • resource_group_id (str or None) — مجموعة الموارد التي سيتم إسناد المجموعة إليها، كسلسلة سداسية عشرية بطول 24 حرفًا. إذا كانت None، فسيتم إزالة المجموعة من أي مجموعة موارد.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

اسند مجموعة إلى مجموعة موارد، أو أزلها من أي مجموعة موارد.

صالح فقط لمجموعات مملوكة للمنظمة.

مثال:

>>> from huggingface_hub import update_collection_resource_group
>>> update_collection_resource_group(
...     collection_slug="my-org/iccv-2023-64f9a55bb3115b4f513ec026",
...     resource_group_id="66980ecfc1e12a49c8f0e42d",
... )

update_inference_endpoint

< >

( name: straccelerator: str | None = Noneinstance_size: str | None = Noneinstance_type: str | None = Nonemin_replica: int | None = Nonemax_replica: int | None = Nonescale_to_zero_timeout: int | None = Nonescaling_metric: InferenceEndpointScalingMetric | None = Nonescaling_threshold: float | None = Nonerepository: str | None = Noneframework: str | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Nonetensor_parallel_size: int | None = Nonedata_parallel_size: int | None = Noneenv: dict[str, str] | None = Nonesecrets: dict[str, str] | None = Nonedomain: str | None = Nonepath: str | None = Nonecache_http_responses: bool | None = Nonetags: list[str] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

المعاملات

  • name (str) — اسم نقطة الاستدلال (Inference Endpoint) المراد تحديثها.
  • accelerator (str، اختياري) — مُسرِّع العتاد الذي سيُستخدم للاستدلال (مثل "cpu").
  • instance_size (str، اختياري) — الحجم أو النوع للمثال الذي سيُستخدم لاستضافة النموذج (مثل "x4").
  • instance_type (str، اختياري) — نوع مثيل السحابة الذي سيتم نشر نقطة الاستدلال (Inference Endpoint) عليه (مثل "intel-icl").
  • min_replica (int، اختياري) — الحد الأدنى لعدد النسخ (المهام) التي يجب إبقاؤها قيد التشغيل لنقطة الاستدلال.
  • max_replica (int، اختياري) — الحد الأقصى لعدد النسخ (المهام) التي يمكن التوسع إليها لنقطة الاستدلال.
  • scale_to_zero_timeout (int, اختياري) — المدة بالدقائق قبل أن يُقلَّص حجم نقطة النهاية غير النشطة إلى صفر.
  • scaling_metric (str أو InferenceEndpointScalingMetric ، اختياري) — مرجع المقياس للتوسيع. إما “pendingRequests” أو “hardwareUsage” عند تقديمه. الافتراضي هو None.
  • scaling_threshold (float, اختياري) — حدّ مقياس التوسيع المستخدم لتفعيل التوسيع. يتم تجاهله عندما لا يُوفَّر مقياس التوسيع. القيمة الافتراضية هي None.
  • repository (str، اختياري) — اسم مستودع النموذج المرتبط بنقطة الاستدلال (Inference Endpoint) (مثل "gpt2").
  • framework (str، اختياري) — إطار التعلم الآلي المستخدم للنموذج (مثل "custom").
  • revision (str، اختياري) — المراجعة المحددة للنموذج التي سيتم نشرها على نقطة الاستدلال (Inference Endpoint) (مثل "6c0e6080953db56375760c0471a8c5f2929baf11").
  • task (str، اختياري) — المهمة التي سيتم نشر النموذج عليها (مثل "text-classification").
  • custom_image (dict، اختياري) — صورة الحاوية التي سيتم تشغيلها. إما قاموس مفاتيحه هي نسخ الصور (مثل {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}، وكذلك sGLang، tgi، tei، llamacpp، hfServe، …)، والذي يُمرَّر كما هو، أو قاموس مسطّح يصف حاوية مخصصة (مثل {"url": ..., "port": ...})، والذي يُرسل على شكل {"custom": ...}.
  • container_command (list[str], اختياري) — تجاوز أمر نقطة الدخول للحاوية (يتوافق مع model.command في حمولة الواجهة البرمجية). يعمل مع صور محركات مُدارة (مثل vLLM وSGLang) والصور المخصصة.
  • container_args (list[str]، اختياري) — الحُجج المُلحَقة بنقطة دخول الحاوية (تتوافق مع model.args في حمولة الواجهة البرمجية). تعمل مع صور المحركات المُدارة (مثل vLLM وSGLang) والصور المخصصة.
  • tensor_parallel_size (int, اختياري) — عدد المعالِجات التي تُقسَّم عليها نسخة واحدة من النموذج (صور vLLM و SGLang). يُكتب داخل إعدادات صورة المحرك. تتطلب الواجهة البرمجية model.image ككل، لذا عند عدم تقديم custom_image يتم جلب الصورة المُعدّة حاليًا على نقطة النهاية وتحديثها في مكانها.
  • data_parallel_size (int، اختياري) — عدد نسخ النموذج التي سيتم تشغيلها، نسخة واحدة لكل معجّل (صور vLLM). نفس المعالجة المطبّقة على tensor_parallel_size.
  • env (dict[str, str]، اختياري) — متغيرات بيئة غير سرية تُحقن في بيئة الحاوية
  • secrets (dict[str, str]، اختياري) — قيم سرية تُحقن في بيئة الحاوية.
  • domain (str، اختياري) — النطاق المخصص لنشر نقطة الاستدلال (Inference Endpoint)، فإذا تم ضبطه ستكون نقطة الاستدلال متاحة عبر هذا النطاق (مثلًا "my-new-domain.cool-website.woof").
  • path (str، اختياري) — المسار المخصص للنموذج المُنفَّذ، يجب أن يبدأ بـ / (مثل "/models/google-bert/bert-base-uncased").
  • cache_http_responses (bool، اختياري) — ما إذا كان سيتم تخزين استجابات HTTP من نقطة الاستدلال (Inference Endpoint) مؤقتًا.
  • tags (list[str]، اختياري) — قائمة من الوسوم التي سيتم ربطها بنقطة الاستدلال (Inference Endpoint).
  • namespace (str، اختياري) — المجال الذي سيتم فيه تحديث نقطة الاستدلال. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

InferenceEndpoint

معلومات حول نقطة الاستدلال المحدّثة.

تحديث نقطة نهاية الاستدلال.

تتيح هذه الطريقة تحديث إعدادات الحساب، أو النموذج المُنفَّذ، أو المسار، أو أي تركيبة من ذلك. جميع الحجج اختيارية، لكن يجب تقديم واحدة على الأقل.

للسهولة، يمكنك أيضًا تحديث نقطة استنتاج باستخدام InferenceEndpoint.update().

update_job_expose

< >

( job_id: strexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

المعاملات

  • job_id (str) — معرّف المهمة قيد التشغيل.
  • expose (list[int]، اختياري) — المنافذ التي يجب كشفها عبر وكيل Jobs. يتطلب الوصول رمز HF مع صلاحية القراءة في نطاق Job.
  • expose_public (list[int], اختياري) — منافذ يجب كشفها عبر وكيل Jobs دون مصادقة. لا يلزم إدراجها في expose.
  • namespace (str، اختياري) — المجال (Namespace) الخاص بالمهمة. القيمة الافتراضية هي مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول المستخدم. الافتراضي هو الرمز المحفوظ محليًا.

يعيد

JobInfo

المهمة المحدّثة.

استبدال المنافذ المكشوفة لوظيفة قيد التشغيل دون إعادة تشغيلها.

expose وexpose_public معًا تشكّلان إعداد المنفذ الكامل: المنافذ التي لا توجد في أيٍّ من القائمتين تكون مغلقة. مرّر أيًّا منهما لإغلاق جميع المنافذ المكشوفة.

update_job_labels

< >

( job_id: strlabels: dict[str, str]namespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

المعاملات

  • job_id (str) — معرّف المهمة.
  • labels (dict[str, str]) — تسميات جديدة تُعيَّن على المهمة. تحل محل جميع التسميات الموجودة مسبقًا. يجب ألا يتجاوز طول كل من المفاتيح والقيم 100 حرف، وأن تحتوي على أحرف وأرقام وشرطات وشرطات سفلية فقط.
  • namespace (str، اختياري) — المجال (namespace) الذي يعمل فيه Job. القيمة الافتراضية هي مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

JobInfo

معلومات المهمة المحدّثة.

تحديث تسميات مهمة موجودة مسبقًا.

يستبدل جميع التسميات التي قدمها المستخدم سابقًا بالتسميات الجديدة.

update_repo_settings

< >

( repo_id: strgated: Literal['auto', 'manual', False] | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = None )

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • gated (Literal["auto", "manual", False], اختياري) — حالة التقييد (gated) للمستودع. إذا تم تعيينها إلى None (الافتراضي)، فلن يتم تحديث إعداد gated للمستودع.
    • “auto”: المستودع محمي، وتُقبل طلبات الوصول أو تُرفض تلقائيًا بناءً على معايير محددة مسبقًا.
    • “manual”: المستودع محمي، وتتطلب طلبات الوصول موافقة يدوية.
    • False : المستودع غير محمي، ويمكن لأي شخص الوصول إليه.
  • private (bool، اختياري) — ما إذا كان يجب أن يكون المستودع خاصًا. لا يمكن تمريره مع visibility.
  • visibility (Literal["public", "private", "protected"], اختياري) — رؤية المستودع. يمكن أن تكون "public" أو "private"، أو "protected" لـ Spaces.
  • token (Union[str, bool, None], اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرر False.
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم تحديث الإعدادات منه ("model" أو "dataset" أو "space"). الافتراضي هو "model".

يرفع

ValueError أو HfHubHTTPError أو RepositoryNotFoundError

  • ValueError — إذا لم يكن gated أحد القيم التالية: “auto” أو “manual” أو False.
  • ValueError — إذا لم يكن repo_type أحد القيم الموجودة في constants.REPO_TYPES.
  • HfHubHTTPError — إذا فشل الطلب إلى واجهة Hugging Face Hub البرمجية.
  • RepositoryNotFoundError — إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.

تحديث إعدادات المستودع، بما في ذلك الوصول المُقيَّد والإظهار.

من أجل منح مزيد من التحكم في طريقة استخدام المستودعات، يتيح لك مركز Hugging Face لمطوّري المستودعات تفعيل طلبات الوصول إلى مستودعاتهم، كما يتيح لهم تغيير مستوى ظهور المستودع.

update_scheduled_job_labels

< >

( scheduled_job_id: strlabels: dict[str, str]namespace: str | None = Nonetoken: bool | str | None = None ) → ScheduledJobInfo

المعاملات

  • scheduled_job_id (str) — معرّف المهمة المجدولة.
  • labels (dict[str, str]) — تسميات جديدة تُعيَّن على المهمة المجدولة. تحل محل جميع التسميات الموجودة مسبقًا. يجب ألا يتجاوز طول كل من المفاتيح والقيم 100 حرف، وأن تحتوي على أحرف وأرقام وشرطات وعلامات شرطة سفلية فقط.
  • namespace (str، اختياري) — المجال (namespace) الذي يوجد فيه Job المجدول. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

ScheduledJobInfo

معلومات المهمة المجدولة المحدّثة.

تحديث تسميات مهمة مجدولة موجودة مسبقًا.

يستبدل جميع التسميات التي قدمها المستخدم سابقًا بالتسميات الجديدة.

update_scheduled_job_schedule

< >

( scheduled_job_id: strschedule: strnamespace: str | None = Nonetoken: bool | str | None = None ) → ScheduledJobInfo

المعاملات

  • scheduled_job_id (str) — معرّف المهمة المجدولة.
  • schedule (str) — إحدى القيم التالية: “@annually” أو “@yearly” أو “@monthly” أو “@weekly” أو “@daily” أو “@hourly”، أو تعبير جدولة CRON (مثل ‘0 9 * * 1’ للساعة 9 صباحًا كل يوم اثنين).
  • namespace (str، اختياري) — المجال (namespace) الذي يوجد فيه Job المجدول. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

ScheduledJobInfo

معلومات المهمة المجدولة المحدّثة.

تغيير وقت تشغيل مهمة مجدولة موجودة مسبقًا.

يتم تحديث الجدولة فقط: حيث تُحفظ مواصفات المهمة (Job) والوسوم وحالة الإيقاف المؤقت. لتشغيل المهمة المجدولة مرة واحدة الآن دون تغيير جدولتها، استخدم trigger_scheduled_job() بدلاً من ذلك.

مثال:

>>> from huggingface_hub import update_scheduled_job_schedule
>>> scheduled_job = update_scheduled_job_schedule(scheduled_job_id="6abb8dc9c617607c354d45f4", schedule="@daily")
>>> scheduled_job.schedule
'@daily'

update_webhook

< >

( webhook_id: strurl: str | None = Nonejob_id: str | None = Nonewatched: list[dict | WebhookWatchedItem] | None = Nonedomains: list[constants.WEBHOOK_DOMAIN_T] | None = Nonesecret: str | None = Nonesecrets: dict[str, str] | None = Nonetoken: bool | str | None = None ) → WebhookInfo

المعاملات

  • webhook_id (str) — المعرّف الفريد للـ webhook الذي سيتم تحديثه.
  • url (str, اختياري) — عنوان URL الذي سيتم إرسال الحمولة إليه.
  • job_id (str, اختياري) — معرّف مهمة المصدر التي سيتم تشغيلها عبر حمولة webhook. مطلوب عند تعيين secrets.
  • watched (list[WebhookWatchedItem], اختياري) — قائمة العناصر المراد مراقبتها. يمكن أن تكون هذه العناصر مستخدمين أو منظمات أو نماذج أو مجموعات بيانات أو مساحات. راجع WebhookWatchedItem لمزيد من التفاصيل. يمكن أيضًا تقديم العناصر المرصودة كمعاجم بسيطة.
  • domains (list[Literal["repo", "discussion"]], اختياري) — المجالات المراد مراقبتها. يمكن أن يتضمن ذلك “repo” أو “discussion” أو كلاهما.
  • secret (str, اختياري) — سرّ يُستخدم لتوقيع الحمولة، مما يوفر طبقة أمان إضافية.
  • secrets (dict[str, str], اختياري) — متغيرات البيئة السرية الخاصة بالمهمة (Job) التي يُطلقها خطاف الويب (webhook). تُستبدل القيم المخزنة بالمفاتيح المدرجة، ويُحذف ذلك السر إذا كان النص فارغاً، وتحتفظ المفاتيح غير المدرجة بقيمها المخزنة. يتطلب job_id.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

WebhookInfo

معلومات حول خطاف الويب المحدّث.

تحديث خطاف ويب (webhook) موجود مسبقًا.

مثال:

>>> from huggingface_hub import update_webhook
>>> updated_payload = update_webhook(
...     webhook_id="654bbbc16f2ec14d77f109cc",
...     url="https://new.webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
...     watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
...     domains=["repo"],
...     secret="my-secret",
... )
>>> print(updated_payload)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    job=None,
    url="https://new.webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo"],
    secret="my-secret",
    disabled=False,

upload_attachment

< >

( path: str | Pathtoken: bool | str | None = None ) → str

المعاملات

  • path (str أو Path) — المسار إلى الملف المراد رفعه. الصيغ المدعومة هي PNG وJPEG وGIF وWebP وMP4 وMOV وWebM وMP3 وWAV. يجب أن تكون الملفات أصغر من 10 ميغابايت (50 ميغابايت للفيديوهات).
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). يحتاج الرمز إلى إذن discussion.write. للرفع بشكل مجهول، مرر False.

يعيد

str

عنوان URL للملف المرفوع.

يرفع

ValueError

  • ValueError — إذا لم يكن تنسيق الملف مدعومًا.

يرفع صورة أو ملف فيديو أو صوت إلى Hub ويعيد عنوان URL الخاص به.

هذا ما يقوم به محرر الويب الخاص بـ Hub عند سحب ملف إلى مربع تعليق في نقاش أو طلب سحب. قم بتضمين الرابط المُعاد في وصف أو تعليق: ![alt text](url) لصورة، والرابط الصريح لفيديو، و<audio controls src="url"></audio> لملف صوتي.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> url = api.upload_attachment("screenshot.png")
>>> api.create_discussion("username/my-model", title="Rendering bug", description=f"![screenshot]({url})")

upload_file

< >

( path_or_fileobj: str | Path | bytes | BinaryIOpath_in_repo: strrepo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = Nonerun_as_future: bool = False_hot_reload: bool | None = None ) → CommitInfo or Future

المعاملات

  • path_or_fileobj (str، Path، bytes، أو IO) — مسار إلى ملف على الجهاز المحلي أو تدفق بيانات ثنائية / fileobj / buffer.
  • path_in_repo (str) — مسار الملف النسبي داخل المستودع، على سبيل المثال: "checkpoints/1fec34a/weights.bin"
  • repo_id (str) — المستودع الذي سيتم رفع الملف إليه، على سبيل المثال: "username/custom_transformers"
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" أو "kernel" إذا كنت ترفع إلى مستودع مجموعة بيانات أو مساحة أو نواة، أو على None أو "model" إذا كنت ترفع إلى نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".
  • commit_message (str، اختياري) — ملخص / عنوان / السطر الأول للالتزام المولّد
  • commit_description (str، اختياري) — وصف الالتزام المُولَّد
  • create_pr (boolean, اختياري) — ما إذا كان سيتم إنشاء طلب سحب (Pull Request) بهذا الالتزام أم لا. القيمة الافتراضية هي False. إذا لم يتم تعيين revision، يُفتح طلب السحب ضد فرع "main". إذا تم تعيين revision وكان فرعاً، يُفتح طلب السحب ضد هذا الفرع. إذا تم تعيين revision ولم يكن اسم فرع (مثال: معرف التزام)، يُرجع الخادم RevisionNotFoundError.
  • parent_commit (str, اختياري) — معرّف OID / SHA للالتزام الأب، كنص سداسي عشري. يتم دعم الاختصارات (الأحرف السبعة الأولى) أيضًا. إذا تم تحديده وكان create_pr هو False، فسيفشل الالتزام إذا لم يشير revision إلى parent_commit. إذا تم تحديده وكان create_pr هو True، فسيتم إنشاء طلب السحب من parent_commit. يضمن تحديد parent_commit أن المستودع لم يتغير قبل الالتزام بالتغييرات، ويمكن أن يكون مفيدًا بشكل خاص إذا تم تحديث المستودع / الالتزام به بشكل متزامن.
  • run_as_future (bool, اختياري) — ما إذا كان سيتم تنفيذ هذه الطريقة في الخلفية أم لا. تُنفَّذ مهام الخلفية بشكل تسلسلي دون إعاقة الخيط الرئيسي. تمرير run_as_future=True سيعيد كائن Future. القيمة الافتراضية هي False.

يعيد

CommitInfo أو Future

مثال من CommitInfo يحتوي على معلومات حول الالتزام الجديد الذي تم إنشاؤه (تجزئة الالتزام، رابط الالتزام، رابط طلب الدمج، رسالة الالتزام، ...). إذا تم تمرير run_as_future=True، تُرجع كائن Future الذي سيحتوي على النتيجة عند التنفيذ.

ارفع ملفًا محليًا (حتى 50 جيجابايت) إلى المستودع المحدد. يتم الرفع من خلال طلب HTTP post، ولا يتطلب تثبيت git أو git-lfs.

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة
  • RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب عدم وجوده، أو كونه مضبوطًا على private ولا تملك صلاحية الوصول إليه.
  • RevisionNotFoundError إذا تعذّر العثور على المراجعة التي يجب التحميل منها.

upload_file يفترض أن المستودع موجود مسبقًا على Hub. إذا واجهت خطأ Client 404، فتأكد من أنك مسجّل الدخول، وأن رمزك (token) يحمل الصلاحيات المطلوبة، وأن repo_id وrepo_type مضبوطة بشكل صحيح. إذا لم يكن المستودع موجودًا، أنشئه أولًا باستخدام create_repo().

مثال:

>>> from huggingface_hub import upload_file

>>> with open("./local/filepath", "rb") as fobj:
...     upload_file(
...         path_or_fileobj=fileobj,
...         path_in_repo="remote/file/path.h5",
...         repo_id="username/my-dataset",
...         repo_type="dataset",
...         token="my_token",
...     )

>>> upload_file(
...     path_or_fileobj=".\\local\\file\\path",
...     path_in_repo="remote/file/path.h5",
...     repo_id="username/my-model",
...     token="my_token",
... )

>>> upload_file(
...     path_or_fileobj=".\\local\\file\\path",
...     path_in_repo="remote/file/path.h5",
...     repo_id="username/my-model",
...     token="my_token",
...     create_pr=True,
... )

upload_folder

< >

( repo_id: strfolder_path: str | Pathpath_in_repo: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonedelete_patterns: list[str] | str | None = Nonerun_as_future: bool = False ) → CommitInfo or Future

المعاملات

  • repo_id (str) — المستودع الذي سيتم رفع الملف إليه، على سبيل المثال: "username/custom_transformers"
  • folder_path (str أو Path) — المسار إلى المجلد الذي سيتم رفعه على نظام الملفات المحلي
  • path_in_repo (str، اختياري) — المسار النسبي للمجلد في المستودع، على سبيل المثال: "checkpoints/1fec34a/results". سيُستخدم المجلد الجذري للمستودع افتراضيًا.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • repo_type (str، اختياري) — اضبطه على "dataset" أو "space" أو "kernel" إذا كنت ترفع إلى مستودع مجموعة بيانات أو مساحة أو نواة، أو على None أو "model" إذا كنت ترفع إلى نموذج. القيمة الافتراضية هي None.
  • revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".
  • commit_message (str, اختياري) — ملخص / عنوان / السطر الأول للالتزام المولّد. الافتراضي هو: f"Upload {path_in_repo} with huggingface_hub"
  • commit_description (str اختياري) — وصف الالتزام المُولَّد
  • create_pr (boolean, اختياري) — ما إذا كان سيتم إنشاء طلب سحب (Pull Request) بتلك النسخة. القيمة الافتراضية هي False. يُفتح طلب السحب دائمًا مقابل الفرع الافتراضي: فإعداد كل من create_pr=True وrevision يثير ValueError. لاحظ أن كل استدعاء مع create_pr=True يفتح طلب سحب جديدًا: لاستئناف رفعٍ مُقاطَع إلى طلب السحب الموجود، أعد التشغيل مع revision="refs/pr/N" بدلاً من ذلك.
  • parent_commit (str, اختياري) — معرّف OID / SHA للالتزام الأب، كسلسلة سداسية عشرية. يتم دعم الاختصارات (الأحرف السبعة الأولى) أيضًا. إذا تم تحديده وكان create_pr هو False، فسيفشل الالتزام إذا لم يُشير revision إلى parent_commit. يضمن تحديد parent_commit عدم تغيّر المستودع قبل الالتزام بالتغييرات، ويمكن أن يكون مفيدًا بشكل خاص إذا تم تحديث المستودع / الالتزام به بشكل متزامن. إذا تم تقسيم الرفع إلى عدة التزامات (مجلدات كبيرة)، فإن parent_commit ينطبق على الأول فقط.
  • allow_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، يتم رفع الملفات التي تطابق نمطًا واحدًا على الأقل فقط.
  • ignore_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، فلن يتم رفع الملفات التي تطابق أيًا من الأنماط.
  • delete_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، فسيتم حذف الملفات البعيدة التي تطابق أيًا من الأنماط من المستودع أثناء الالتزام بالملفات الجديدة. هذا مفيد إذا كنت لا تعرف أي الملفات تم رفعها بالفعل. ملاحظة: لتجنب الاختلافات، لن يتم حذف ملف .gitattributes حتى لو كان يطابق النمط.
  • run_as_future (bool, اختياري) — ما إذا كان سيتم تنفيذ هذه الطريقة في الخلفية أم لا. تُنفَّذ مهام الخلفية بشكل تسلسلي دون إعاقة الخيط الرئيسي. تمرير run_as_future=True سيعيد كائن Future. القيمة الافتراضية هي False.

يعيد

CommitInfo أو Future

مثال من CommitInfo يحتوي على معلومات حول الالتزام الجديد الذي تم إنشاؤه (تجزئة الالتزام، رابط الالتزام، رابط طلب الدمج، رسالة الالتزام، ...). إذا تم تمرير run_as_future=True، تُرجع كائن Future الذي سيحتوي على النتيجة عند التنفيذ.

ارفع مجلدًا محليًا إلى المستودع المحدد. يتم الرفع من خلال طلبات HTTP، ولا يتطلب تثبيت git أو git-lfs.

سيتم الحفاظ على هيكل المجلد. سيتم استبدال الملفات الموجودة مسبقًا في المستودع والتي تحمل نفس الاسم. أما الملفات الأخرى فستُترك دون تغيير.

استخدم الحججين allow_patterns وignore_patterns لتحديد الملفات المراد رفعها. تقبل هذه المعاملات نمطًا واحدًا أو قائمة بأنماط. الأنماط هي برتقالات قياسية (أنماط globbing) كما هو موثق هنا. إذا تم تقديم كل من allow_patterns وignore_patterns، فإن كلا القيدين يسريان. افتراضيًا، يتم رفع جميع الملفات من المجلد.

استخدم الحجة delete_patterns لتحديد الملفات البعيدة التي تريد حذفها. نوع الإدخال هو نفسه الخاص بـ allow_patterns (انظر أعلاه). إذا تم تقديم path_in_repo أيضًا، فإن الأنماط تُطابق المسارات النسبية لهذا المجلد. على سبيل المثال، upload_folder(..., path_in_repo="experiment", delete_patterns="logs/*") سيحذف أي ملف بعيد تحت ./experiment/logs/. لاحظ أن ملف .gitattributes لن يُحذف حتى لو تطابق مع الأنماط.

سيتم تجاهل أي مجلد .git/ موجود في أي مجلد فرعي. ومع ذلك، يرجى الانتباه إلى أن ملف .gitignore لا يُؤخذ في الاعتبار.

عند تثبيت hf_xet (وهو الإعداد الافتراضي)، يتم رفع الملفات عبر خط أنابيب متدفق: تبدأ عمليات الرفع بينما لا يزال يتم فحص المجلد مقابل Hub، وتُحسب تجزئة الملفات أثناء تقسيمها للرفع (مرور قراءة واحد)، وتُلتزم المجلدات الكبيرة تلقائيًا في عدة دفعات للبقاء ضمن حدود الخادم (تحصل الالتزامات اللاحقة على لاحقة (part N) في رسالة الالتزام). إذا انقطع الرفع، فإن إعادة تشغيل نفس الاستدعاء يستأنفه: يتم تخطي الملفات التي تم الالتزام بها مسبقًا، ويتم إزالة التكرار من البيانات التي تم رفعها مسبقًا. عند عدم تثبيت hf_xet، يتم الرجوع إلى التزام واحد يُنشأ باستخدام create_commit().

يرفع الأخطاء التالية:

  • HTTPError إذا أعادت واجهة HuggingFace البرمجية خطأ
  • ValueError إذا كانت قيمة بعض المعاملات غير صالحة

upload_folder يفترض أن المستودع موجود مسبقًا على Hub. إذا واجهت خطأ Client 404، فتأكد من أنك مسجّل الدخول، وأن رمزك (token) يحمل الصلاحيات المطلوبة، وأن repo_id وrepo_type مضبوطة بشكل صحيح. إذا لم يكن المستودع موجودًا، أنشئه أولًا باستخدام create_repo().

مثال:

# Upload checkpoints folder except the log files
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     ignore_patterns="**/logs/*.txt",
... )

# Upload checkpoints folder including logs while deleting existing logs from the repo
# Useful if you don't know exactly which log files have already being pushed
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     delete_patterns="**/logs/*.txt",
... )

# Upload checkpoints folder while creating a PR
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     create_pr=True,
... )

verify_repo_checksums

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonelocal_dir: str | Path | None = Nonecache_dir: str | Path | None = Nonetoken: str | bool | None = None ) → FolderVerification

المعاملات

  • repo_id (str) — مساحة اسم (مستخدم أو منظمة) واسم مستودع مفصولان بـ /.
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم منه جلب الشجرة ("model" أو "dataset" أو "space"). الافتراضي هو "model".
  • revision (str، اختياري) — المراجعة (revision) للمستودع الذي سيتم منه جلب الشجرة. القيمة الافتراضية هي الفرع "main".
  • local_dir (str أو Path، اختياري) — المجلد المحلي الذي سيتم التحقق منه.
  • cache_dir (str أو Path، اختياري) — مجلد التخزين المؤقت الذي يجب التحقق منه.
  • token (Union[bool, str, None], optional) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.

يعيد

FolderVerification

نتيجة منظمة تحتوي على تفاصيل التحقق.

يرفع

RepositoryNotFoundError أو RevisionNotFoundError

  • RepositoryNotFoundError — إذا لم يتم العثور على المستودع (خطأ 404): معرف المستودع repo_id/repo_type خاطئ، أو المستودع خاص وغير مصادق عليه، أو المستودع غير موجود.
  • RevisionNotFoundError — إذا لم يتم العثور على المراجعة (خطأ 404) في المستودع.

تحقق من الملفات المحلية لمستودع مقابل قيم التجزئة (Checksums) الخاصة بالمستودع على Hugging Face Hub.

wait_for_job

< >

( job_id: str | list[str]timeout: float | None = Nonepoll_interval: float = 1.0stages: list[JobStage] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo or list[JobInfo]

المعاملات

  • job_id (str أو list[str]) — معرّف المهمة (Job)، أو قائمة بمعرّفات المهام التي يجب الانتظار لها. إذا تم تمرير قائمة، يُعاد قائمة من JobInfo (بنفس الترتيب).
  • timeout (float, اختياري) — الحد الأقصى للوقت الذي يجب انتظاره حتى تنتهي المهمة (المهام)، بالثواني. إذا كان None، فسيتم الانتظار إلى ما لا نهاية.
  • poll_interval (float، اختياري) — المدة التي يجب الانتظار بينها وبين كل فحص للحالة، بالثواني. القيمة الافتراضية هي 1 ثانية.
  • stages (list[JobStage]، اختياري) — المراحل التي يجب الانتظار حتى بلوغها. الافتراضي هو المراحل النهائية ("COMPLETED"، "CANCELED"، "ERROR"، "DELETED"). مرّر على سبيل المثال [JobStage.RUNNING] للانتظار حتى يبدأ تشغيل المهمة. توقف المراحل النهائية الانتظار دائمًا بغض النظر عن هذه القيمة.
  • namespace (str، اختياري) — المجال الذي تعمل فيه المهمة أو المهام. الافتراضي هو مجال المستخدم الحالي.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. إذا لم يُقدَّم، فسيتم استخدام الرمز المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

JobInfo أو list[JobInfo]

معلومات Job النهائية.

يرفع

TimeoutError

  • TimeoutError — إذا لم يصل أي Job واحد على الأقل إلى إحدى المراحل المستهدفة بعد timeout ثانية.

انتظر حتى تصل مهمة أو أكثر من مهام الحوسبة على بنية Hugging Face التحتية إلى مرحلة محددة.

Each Job status is polled (with inspect_job()) every poll_interval seconds until its stage is one of stages (terminal stages by default: "COMPLETED", "CANCELED", "ERROR" or "DELETED"). The final JobInfo is returned in all cases: a failed or canceled Job does not raise an exception — check job.status.stage to act on the outcome.

توقف المراحل النهائية دائمًا انتظارًا، حتى لو لم تُذكر في stages. وهذا يتجنّب الانتظار إلى الأبد لمرحلة لن يصل إليها Job أبدًا (مثل انتظار "RUNNING" لـ Job يفشل أثناء الجدولة).

مثال:

>>> from huggingface_hub import run_job, wait_for_job
>>> job = run_job(image="python:3.12", command=["python", "-c", "print('Hello from HF compute!')"])
>>> wait_for_job(job_id=job.id).status.stage
'COMPLETED'

wait_for_space

< >

( repo_id: strtimeout: float | None = Nonepoll_interval: float = 1.0token: bool | str | None = None ) → SpaceRuntime

المعاملات

  • repo_id (str) — معرّف المساحة (Space) التي سيتم الانتظار لها. مثال: "username/my-space".
  • timeout (float، اختياري) — الحد الأقصى للوقت الذي يجب الانتظار به بالثواني. إذا كان None، فسيتم الانتظار إلى ما لا نهاية.
  • poll_interval (float، اختياري) — عدد الثواني بين فحوصات الحالة. القيمة الافتراضية هي 1 ثانية.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح. الافتراضي هو رمز الوصول المحفوظ محليًا، وهو طريقة المصادقة الموصى بها. اضبطه على False لتعطيل المصادقة. راجع https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

يعيد

SpaceRuntime

معلومات وقت التشغيل النهائية عندما يصل المساحة إلى مرحلة نهائية.

يرفع

TimeoutError

  • TimeoutError — إذا لم يصل المساحة إلى مرحلة نهائية بعد timeout ثانية.

انتظر حتى يصل Space إلى مرحلة نهائية (غير قيد البناء/البدء).

تستطلع get_space_runtime() كل poll_interval ثانية حتى لم يعد مرحلة الـ Space وسيطة (BUILDING، RUNNING_BUILDING، APP_STARTING، RUNNING_APP_STARTING). تُرجع SpaceRuntime النهائية في جميع الحالات — تحقق من runtime.stage للتعامل مع النتيجة (مثل RUNNING مقابل BUILD_ERROR).

مثال:

>>> from huggingface_hub import restart_space, wait_for_space
>>> restart_space("username/my-space")
>>> runtime = wait_for_space("username/my-space")
>>> runtime.stage
'RUNNING'

whoami

< >

( token: bool | str | None = Nonecache: bool = False )

المعاملات

  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • cache (bool، اختياري) — ما إذا كان سيتم تخزين نتيجة استدعاء whoami للاستخدام في الاستدعاءات اللاحقة. إذا حدث خطأ أثناء الاستدعاء الأول، فلن يتم تخزينه. القيمة الافتراضية هي False.

استدعاء واجهة HF البرمجية لمعرفة “من أنا”.

إذا مررت cache=True، فسيتم تخزين النتيجة مؤقتًا للاستدعاءات اللاحقة طوال مدة عملية بايثون. وهذا مفيد إذا كنت تخطط لاستدعاء whoami عدة مرات، إذ إن هذا الطرفي (endpoint) يخضع لقيود معدل صارمة لأسباب أمنية.

بيانات واجهة برمجة التطبيقات

AccessRequest

فئة huggingface_hub.hf_api.AccessRequest

< >

( username: str | Nonerequest_id: strfullname: str | Noneemail: str | Nonetimestamp: datetimestatus: Literal['pending', 'accepted', 'rejected']fields: dict[str, Any] | None = None )

المعاملات

  • username (str, اختياري) — اسم المستخدم الخاص بالمستخدم الذي طلب الوصول. None إذا كان المستودع مُهيأً بحيث لا يشارك أسماء المستخدمين الذين يقدمون الطلبات. في هذه الحالة، استخدم request_id لقبول الطلب أو رفضه أو إلغائه.
  • request_id (str) — معرّف طلب الوصول. يُعيَّن دائمًا، حتى إذا لم يتم مشاركة اسم المستخدم.
  • fullname (str، اختياري) — الاسم الكامل للمستخدم الذي طلب الوصول. None إذا كان المستودع مُهيأً بحيث لا يشارك أسماء المستخدمين الذين يقدمون الطلبات.
  • email (str، اختياري) — بريد المستخدم الذي طلب الوصول. None إذا تم منح المستخدم الوصول يدويًا أو إذا كان المستودع مُهيأً بحيث لا يُشارك بريدات طالبي الوصول.
  • timestamp (datetime) — طابع زمني للطلب.
  • status (Literal["pending", "accepted", "rejected"]) — حالة الطلب. يمكن أن تكون واحدة من ["pending", "accepted", "rejected"].
  • fields (dict[str, Any]، اختياري) — حقول إضافية يملؤها المستخدم في نموذج البوابة.

هيكل بيانات يحتوي على معلومات حول طلب وصول مستخدم.

BucketFile

فئة huggingface_hub.BucketFile

< >

( **kwargs )

تحتوي على معلومات حول ملف في دلو على Hub. يُعاد هذا الكائن بواسطة list_bucket_tree().

مشابه لـ RepoFile ولكن للملفات الموجودة في الدلاء.

BucketFileMetadata

فئة huggingface_hub.BucketFileMetadata

< >

( size: intxet_file_data: XetFileData )

المعاملات

  • size (int) — حجم الملف بالبايت.
  • xet_file_data (XetFileData) — معلومات Xet الخاصة بالملف (التجزئة ومسار التحديث).

هيكل بيانات يحتوي على معلومات حول ملف في دلو.

تُعاد بواسطة get_bucket_file_metadata().

BucketInfo

فئة huggingface_hub.BucketInfo

< >

( **kwargs )

المعاملات

  • id (str) — معرّف الدلو.
  • private (bool) — هل الدلو خاص.
  • created_at (datetime) — تاريخ إنشاء الدلو على Hub.
  • size (int) — حجم الدلو بالبايت.
  • total_files (int) — إجمالي عدد الملفات في الدلو.

تحتوي على معلومات حول دلو في Hub. يُعاد هذا الكائن بواسطة bucket_info() و list_buckets().

BucketUrl

فئة huggingface_hub.BucketUrl

< >

( url: strendpoint: str = '' )

المعاملات

  • url (str) — قيمة نصية لعنوان url للبرميل.
  • endpoint (str، اختياري) — نقطة النهاية الخاصة بـ Hub. القيمة الافتراضية هي https://huggingface.co.

يصف رابط دلو على Hub.

BucketUrl هو ما يُعاد بواسطة create_bucket(). عند التهيئة، يتم تحليل الرابط (URL) لملء الخصائص:

  • نقطة النهاية (str)
  • المجال (str)
  • bucket_id (str)
  • url (str)
  • uri (HfUri)

DatasetLeaderboardEntry

فئة huggingface_hub.DatasetLeaderboardEntry

< >

( **kwargs )

المعاملات

  • rank (int) — ترتيب النموذج في لوحة الصدارة (مفهرس من 1).
  • model_id (str) — معرّف النموذج (مثل "meta-llama/Llama-3-8b").
  • value (float) — قيمة درجة التقييم.
  • filename (str) — اسم ملف النتائج الذي يحتوي على بيانات التقييم.
  • verified (bool) — ما إذا كان قد تم التحقق من النتيجة.
  • source (dict[str, Any]، اختياري) — معلومات حول مصدر نتيجة التقييم. يحتوي على مفاتيح مثل "url"، "name"، و"isExternal". لا تحتوي جميع الإدخالات على مصدر.
  • author (User أو Organization) — مؤلف النموذج، يُحلَّل بناءً على حقل "type" في استجابة الواجهة البرمجية.
  • pull_request (int، اختياري) — رقم طلب الدمج المرتبط بإدراج لوحة الصدارة، إن وُجد.
  • notes (str، اختياري) — ملاحظات مرتبطة بدخول لوحة الصدارة، إن وُجدت.

تحتوي على معلومات عن إدخال واحد في لوحة صدارة مجموعة بيانات على Hub.

ترتّب لوحة الصدارة النماذج بناءً على درجات تقييمها على مجموعة بيانات مرجعية محددة. يُعاد هذا الكائن بواسطة get_dataset_leaderboard(). للحصول على نتائج التقييم لنموذج معين عبر مجموعات البيانات المرجعية، راجع ModelInfo.eval_results (عبر model_info() مع expand=["evalResults"]) و EvalResultEntry.

EvalResultEntry

فئة huggingface_hub.EvalResultEntry

< >

( dataset_id: strtask_id: strvalue: typing.Anydataset_revision: str | None = Noneverify_token: str | None = Nonedate: str | None = Nonesource_url: str | None = Nonesource_name: str | None = Nonesource_user: str | None = Nonesource_org: str | None = Nonenotes: str | None = None )

المعاملات

  • dataset_id (str) — معرّف مجموعة بيانات الاختبار من Hub. مثال: “cais/hle”، “Idavidrein/gpqa”.
  • task_id (str) — معرّف المهمة ضمن مجموعة الاختبار. مثال: “gpqa_diamond”.
  • value (Any) — قيمة المقياس. مثال: 20.90.
  • dataset_revision (str, اختياري) — SHA الخاص بـ Git لمجموعة بيانات المعيار.
  • verify_token (str، اختياري) — توقيع يمكن استخدامه لإثبات أن التقييم قابل للتدقيق والتكرار بشكل قاطع.
  • date (str، اختياري) — وقت تشغيل التقييم (تاريخ ووقت بصيغة ISO-8601). القيمة الافتراضية هي وقت التزامن (commit) في git.
  • source_url (str، اختياري) — رابط إلى مصدر التقييم (مثل https://huggingface.co/spaces/SaylorTwift/smollm3-mmlu-pro). مطلوب إذا تم تقديم source_name أو source_user أو source_org.
  • source_name (str، اختياري) — الاسم المعروض للمصدر. مثال: “Eval Logs”.
  • source_user (str، اختياري) — اسم مستخدم HF للنسبة. مثال: “celinah”.
  • source_org (str، اختياري) — اسم منظمة HF للنسبة. مثال: “cais”.
  • notes (str، اختياري) — تفاصيل حول إعداد التقييم. مثال: “أدوات” و “بدون أدوات” و “سلسلة التفكير”.

عنصر نتيجة التقييم لتنسيق .eval_results/*.yaml.

يمثل درجات التقييم المخزنة في مستودعات النماذج والتي تظهر تلقائيًا على صفحة النموذج ولوحة صدارة مجموعة بيانات المعيار.

بالنسبة إلى تنسيق model-index القديم في README.md، استخدم EvalResult بدلاً من ذلك.

راجع https://huggingface.co/docs/hub/eval-results لمزيد من التفاصيل.

مثال:

>>> from huggingface_hub import EvalResultEntry
>>> # Minimal example with required fields only
>>> result = EvalResultEntry(
...     dataset_id="Idavidrein/gpqa",
...     task_id="gpqa_diamond",
...     value=0.412,
... )
>>> # Full example with all fields
>>> result = EvalResultEntry(
...     dataset_id="cais/hle",
...     task_id="default",
...     value=20.90,
...     dataset_revision="5503434ddd753f426f4b38109466949a1217c2bb",
...     verify_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
...     date="2025-01-15T10:30:00Z",
...     source_url="https://huggingface.co/datasets/cais/hle",
...     source_name="CAIS HLE",
...     source_org="cais",
...     notes="no-tools",
... )

SyncOperation

فئة huggingface_hub.SyncOperation

< >

( action: typing.Literal['upload', 'download', 'delete', 'skip']path: strsize: int | None = Nonereason: str = ''local_mtime: str | None = Noneremote_mtime: str | None = Nonebucket_file: huggingface_hub._buckets.BucketFile | None = None )

يمثل عملية مزامنة يجب تنفيذها.

SyncPlan

فئة huggingface_hub.SyncPlan

< >

( source: strdest: strtimestamp: stroperations: list = <factory> )

يمثل خطة مزامنة كاملة.

CommitInfo

فئة huggingface_hub.CommitInfo

< >

( commit_url: str*args**kwargs )

المعاملات

  • commit_url (str) — رابط موقع العثور على الالتزام.
  • commit_message (str) — ملخص (السطر الأول) للالتزام الذي تم إنشاؤه.
  • commit_description (str) — وصف للالتزام الذي تم إنشاؤه. يمكن أن يكون فارغًا.
  • oid (str) — معرّف تجزئة الالتزام. مثال: "91c54ad1727ee830252e457677f467be0bfd8a57".
  • pr_url (str, اختياري) — رابط إلى طلب الإرسال (PR) الذي تم إنشاؤه، إن وُجد. يُعبأ عند تمرير create_pr=True.
  • pr_revision (str, اختياري) — إصدار طلب الإرسال الذي تم إنشاؤه، إن وُجد. يُعبأ عند تمرير create_pr=True. مثال: "refs/pr/1".
  • pr_num (int, اختياري) — رقم نقاش طلب الإرسال الذي تم إنشاؤه، إن وُجد. يُعبأ عند تمرير create_pr=True. يمكن تمريره كـ discussion_num في get_discussion_details(). مثال: 1.
  • repo_url (RepoUrl) — رابط المستودع الخاص بالالتزام الذي يحتوي على معلومات مثل repo_id وrepo_type وغيرها.

هيكل بيانات يحتوي على معلومات حول التزامن الجديد الذي تم إنشاؤه.

تُعاد بواسطة أي طريقة تنشئ التزامًا على Hub: create_commit()، upload_file()، upload_folder()، delete_file()، delete_folder(). ترث من str من أجل التوافق مع الإصدارات السابقة، لكن استخدام طرق خاصة بـ str أصبح غير موصى به.

DatasetInfo

فئة huggingface_hub.DatasetInfo

< >

( **kwargs )

المعاملات

  • id (str) — معرّف مجموعة البيانات.
  • author (str) — مؤلف مجموعة البيانات.
  • card_data (DatasetCardData، اختياري) — بيانات وصف بطاقة مجموعة البيانات (Dataset Card Metadata) كائن من نوع huggingface_hub.repocard_data.DatasetCardData.
  • citation (str، اختياري) — معلومات الاستشهاد للمجموعة.
  • created_at (datetime، اختياري) — تاريخ إنشاء المستودع على Hub. لاحظ أن أدنى قيمة هي 2022-03-02T23:29:04.000Z، والتي تتوافق مع التاريخ الذي بدأنا فيه بتخزين تواريخ الإنشاء.
  • description (str، اختياري) — وصف مجموعة البيانات.
  • disabled (bool، اختياري) — هل المستودع معطّل.
  • downloads (int) — عدد مرات تنزيل مجموعة البيانات خلال آخر 30 يومًا.
  • downloads_all_time (int) — إجمالي عدد مرات تنزيل مجموعة البيانات منذ إنشائها.
  • gated (Literal["auto", "manual", False]، اختياري) — هل المستودع محمي. إذا كان كذلك، ما إذا كان الاعتماد يدويًا أو تلقائيًا.
  • last_modified (datetime، اختياري) — تاريخ آخر التزامن (commit) في المستودع.
  • likes (int) — عدد الإعجابات بالمجموعة.
  • main_size (int، اختياري) — الحجم بالبايتات للفرع الرئيسي للمجموعة البيانات.
  • paperswithcode_id (str، اختياري) — معرّف Papers with code الخاص بالبيانات.
  • private (bool) — هل المستودع خاص.
  • resource_group (dict، اختياري) — معلومات مجموعة الموارد الخاصة بالبيانات.
  • sha (str) — SHA المستودع في هذا المراجعة المحددة.
  • siblings (list[RepoSibling]) — قائمة من كائنات huggingface_hub.hf_api.RepoSibling التي تُشكّل مجموعة البيانات.
  • tags (list[str]) — قائمة بوسوم مجموعة البيانات.
  • trending_score (int، اختياري) — درجة الترند الخاصة بالبيانات.
  • used_storage (int، اختياري) — حجم مجموعة البيانات على Hub بالبايت.

تحتوي على معلومات حول مجموعة بيانات على Hub. يُعاد هذا الكائن بواسطة dataset_info() و list_datasets().

معظم خصائص هذه الفئة اختيارية. وذلك لأن البيانات التي يعيدها Hub تعتمد على الاستعلام المُدخل. بشكل عام، كلما كان الاستعلام أكثر تحديدًا، زادت المعلومات المُعادَة. على العكس من ذلك، عند سرد مجموعات البيانات باستخدام list_datasets() لا تُعاد سوى مجموعة فرعية من الخصائص.

DryRunFileInfo

فئة huggingface_hub.DryRunFileInfo

< >

( commit_hash: strfile_size: int | Nonefilename: strlocal_path: stris_cached: boolwill_download: bool )

المعاملات

  • commit_hash (str) — الـ commit_hash المرتبط بالملف.
  • file_size (int، اختياري) — حجم الملف، إذا كان معروفًا. في حالة ملف LFS، يحتوي على حجم ملف LFS الفعلي، وليس حجم المؤشر.
  • filename (str) — اسم الملف في المستودع.
  • is_cached (bool) — ما إذا كان الملف مخزّنًا محليًا مسبقًا.
  • will_download (bool) — ما إذا كان الملف سيُحمَّل عند استدعاء hf_hub_download مع dry_run=False. عملياً، تكون قيمة will_download هي True إذا لم يكن الملف مخزّناً مؤقتاً أو إذا كان force_download=True.

المعلومات المُعاد عند إجراء تجربة جافة لتنزيل ملف.

تُعاد بواسطة hf_hub_download() عندما يكون dry_run=True.

DuplicatedRepoUrl

فئة huggingface_hub.DuplicatedRepoUrl

< >

( url: Anyendpoint: str | None = None )

المعاملات

  • files_copy_pending (bool) — True إذا كانت ملفات LFS/Xet في المستودع الجديد لا تزال قيد النسخ في الخلفية. حتى اكتمال عملية النسخ، قد يفشل تنزيل هذه الملفات.

RepoUrl الذي يُرجعه duplicate_repo().

GitRefInfo

فئة huggingface_hub.GitRefInfo

< >

( name: strref: strtarget_commit: str )

المعاملات

  • name (str) — اسم المرجع (مثل اسم وسم أو اسم فرع).
  • ref (str) — مرجع git كامل على Hub (مثل "refs/heads/main" أو "refs/tags/v1.0").
  • target_commit (str) — معرّف OID للالتزام المستهدف للإحالة (e.g. "e7da7f221d5bf496a48136c0cd264e630fe9fcc8")

تحتوي على معلومات حول مرجع git لمستودع على Hub.

GitCommitInfo

فئة huggingface_hub.GitCommitInfo

< >

( commit_id: strauthors: list[str]created_at: datetimetitle: strmessage: strformatted_title: str | Noneformatted_message: str | None )

المعاملات

  • commit_id (str) — المعرّف (OID) للالتزام (على سبيل المثال "e7da7f221d5bf496a48136c0cd264e630fe9fcc8")
  • authors (list[str]) — قائمة بمؤلفي هذا الالتزام.
  • created_at (datetime) — تاريخ ووقت إنشاء الالتزام.
  • title (str) — عنوان الالتزام. هذه قيمة نص حر يُدخلها المؤلفون.
  • message (str) — وصف للالتزام. هذه قيمة نص حر يُدخلها المؤلفون.
  • formatted_title (str) — عنوان الالتزام منسّقًا بصيغة HTML. يُعاد فقط إذا تم تعيين formatted=True.
  • formatted_message (str) — وصف للالتزام منسّق بصيغة HTML. يُعاد فقط إذا تم تعيين formatted=True.

تحتوي على معلومات حول التزامن (commit) في مستودع على Hub. راجع list_repo_commits() لمزيد من التفاصيل.

GitRefs

class huggingface_hub.GitRefs

< >

( branches: list[GitRefInfo]converts: list[GitRefInfo]tags: list[GitRefInfo]pull_requests: list[GitRefInfo] | None = None )

المعاملات

  • branches (list[GitRefInfo]) — قائمة من GitRefInfo تحتوي على معلومات حول الفروع في المستودع.
  • converts (list[GitRefInfo]) — قائمة من GitRefInfo تحتوي على معلومات حول مراجع “convert” في المستودع. تُستخدم مراجع Converts (داخليًا) لدفع البيانات المُعالجة مسبقًا في مستودعات Dataset.
  • tags (list[GitRefInfo]) — قائمة من GitRefInfo تحتوي على معلومات حول الوسوم في المستودع.
  • pull_requests (list[GitRefInfo]، اختياري) — قائمة من GitRefInfo تحتوي على معلومات حول طلبات الدمج في المستودع. يتم إرجاعها فقط إذا تم تعيين include_prs=True.

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

يُعاد الكائن بواسطة list_repo_refs().

InferenceProviderMapping

فئة huggingface_hub.hf_api.InferenceProviderMapping

< >

( **kwargs )

KernelInfo

فئة huggingface_hub.KernelInfo

< >

( **kwargs )

المعاملات

  • id (str) — معرّف مستودع النواة.
  • author (str، اختياري) — مؤلف مستودع النواة.
  • downloads (int, اختياري) — عدد تنزيلات مستودع النواة خلال آخر 30 يومًا.
  • gated (Literal["auto", "manual", False]، اختياري) — هل المستودع محمي. وإذا كان كذلك، ما إذا كانت الموافقة يدوية أو تلقائية.
  • last_modified (datetime، اختياري) — تاريخ آخر التزامن (commit) في المستودع.
  • likes (int، اختياري) — عدد الإعجابات بمستودع النواة.
  • private (bool، اختياري) — هل المستودع خاص.
  • sha (str، اختياري) — SHA المستودع في هذا المراجعة المحددة.

تحتوي على معلومات حول مستودع نواة على Hub. يُعاد هذا الكائن بواسطة kernel_info().

LFSFileInfo

فئة huggingface_hub.hf_api.LFSFileInfo

< >

( **kwargs )

المعاملات

  • file_oid (str) — معرّف SHA-256 الخاص بالمقطع. هذا هو المعرّف الذي يجب تمريره عند حذف الملف بشكل دائم.
  • filename (str) — اسم الملف المحتمل لكائن LFS. راجع الملاحظة أعلاه لمزيد من المعلومات.
  • oid (str) — معرّف OID لكائن LFS.
  • pushed_at (datetime) — التاريخ الذي تم فيه دفع كائن LFS إلى المستودع.
  • ref (str، اختياري) — المرجع الذي تم دفع كائن LFS إليه (إن وُجد).
  • size (int) — حجم كائن LFS.

تحتوي على معلومات حول ملف مخزّن بصيغة LFS في مستودع على Hub.

يُستخدم في سياق سرد ملفات LFS من مستودع وحذفها بشكل دائم لتحرير المساحة. راجع list_lfs_files() و permanently_delete_lfs_files() لمزيد من التفاصيل.

تُتتبع ملفات Git LFS باستخدام معرّفات كائنات SHA-256 بدلاً من مسارات الملفات، وذلك لتحسين الأداء. يعد هذا النهج ضرورياً لأن كائناً واحداً يمكن أن يُشار إليه عبر مسارات متعددة في التزامات المختلفة، مما يجعل البحث عن هذه الروابط وحلّها أمراً غير عملي. اطّلع على توثيقنا لمعرفة كيفية تحديد اسم الملف أو أسماء الملفات المرتبطة بكل SHA.

مثال:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

ModelInfo

فئة huggingface_hub.ModelInfo

< >

( **kwargs )

المعاملات

  • id (str) — معرّف النموذج.
  • author (str، اختياري) — مؤلف النموذج.
  • base_models (list[str]، اختياري) — قائمة بنماذج الأساس التي اشتُقت منها هذه النموذج.
  • card_data (ModelCardData، اختياري) — بيانات وصف بطاقة النموذج (Model Card Metadata) ككائن huggingface_hub.repocard_data.ModelCardData.
  • children_model_count (int، اختياري) — عدد النماذج الفرعية المشتقة من هذا النموذج.
  • config (dict، اختياري) — إعدادات النموذج.
  • created_at (datetime، اختياري) — تاريخ إنشاء المستودع على Hub. لاحظ أن أدنى قيمة هي 2022-03-02T23:29:04.000Z، والتي تتوافق مع التاريخ الذي بدأنا فيه بتخزين تواريخ الإنشاء.
  • disabled (bool، اختياري) — هل المستودع معطّل.
  • downloads (int) — عدد تنزيلات النموذج خلال آخر 30 يومًا.
  • downloads_all_time (int) — إجمالي عدد مرات تنزيل النموذج منذ إنشائه.
  • eval_results (list[EvalResultEntry]، اختياري) — نتائج تقييم النموذج.
  • gated (Literal["auto", "manual", False]، اختياري) — هل المستودع محمي. إذا كان كذلك، ما إذا كان الاعتماد يدويًا أو تلقائيًا.
  • gguf (dict، اختياري) — معلومات GGUF الخاصة بالنموذج.
  • inference (Literal["warm"], اختياري) — حالة النموذج لدى مزوّدي الاستدلال. تكون الحالة "دافئة" إذا كان النموذج مقدَّمًا من قِبل مزوّد واحد على الأقل.
  • inference_provider_mapping (list[InferenceProviderMapping]، اختياري) — قائمة من InferenceProviderMapping مرتبة وفقًا لترتيب مزود المستخدم.
  • last_modified (datetime، اختياري) — تاريخ آخر التزامن (commit) في المستودع.
  • library_name (str، اختياري) — المكتبة المرتبطة بالنموذج.
  • likes (int) — عدد الإعجابات بالنموذج.
  • mask_token (str، اختياري) — رمز القناع الذي يستخدمه النموذج.
  • model_index (dict، اختياري) — فهرس النموذج للتقييم.
  • pipeline_tag (str، اختياري) — وسم خط الأنابيب المرتبط بالنموذج.
  • private (bool) — هل المستودع خاص.
  • resource_group (dict، اختياري) — معلومات مجموعة الموارد الخاصة بالنموذج.
  • safetensors (SafeTensorsInfo، اختياري) — معلومات safetensors الخاصة بالنموذج.
  • security_repo_status (dict, اختياري) — حالة فحص الأمان للنموذج.
  • sha (str، اختياري) — SHA المستودع في هذا المراجعة المحددة.
  • siblings (list[RepoSibling]) — قائمة من كائنات huggingface_hub.hf_api.RepoSibling التي تُشكّل النموذج.
  • spaces (list[str]، اختياري) — قائمة بالمساحات التي تستخدم النموذج.
  • tags (list[str]) — قائمة بوسوم النموذج. مقارنةً بـ card_data.tags، تحتوي على وسوم إضافية محسوبة بواسطة Hub (مثل المكتبات المدعومة، وورقة arXiv الخاصة بالنموذج).
  • transformers_info (TransformersInfo، اختياري) — معلومات خاصة بـ Transformers (فئة تلقائية، معالج، إلخ) المرتبطة بالنموذج.
  • trending_score (int، اختياري) — درجة الترند للنموذج.
  • used_storage (int، اختياري) — حجم النموذج على Hub بالبايت.
  • widget_data (Any, اختياري) — بيانات الودجة المرتبطة بالنموذج.

تحتوي على معلومات حول نموذج على Hub. يُعاد هذا الكائن بواسطة model_info() و list_models().

معظم خصائص هذه الفئة اختيارية. وذلك لأن البيانات التي يعيدها Hub تعتمد على الاستعلام المُدخل. بشكل عام، كلما كان الاستعلام أكثر تحديدًا، زادت المعلومات المُعادَة. على العكس من ذلك، عند سرد النماذج باستخدام list_models() لا تُعاد سوى مجموعة فرعية من الخصائص.

RepoSibling

فئة huggingface_hub.hf_api.RepoSibling

< >

( rfilename: strsize: int | None = Noneblob_id: str | None = Nonelfs: BlobLfsInfo | None = None )

المعاملات

  • rfilename (str) — اسم الملف، نسبيًا إلى جذر المستودع.
  • size (int, اختياري) — حجم الملف، بالبايت. يُعرَّف هذا السمة عندما يُضبط معامل files_metadata في repo_info() على True. وإلا فهو None.
  • blob_id (str, اختياري) — معرف git OID للملف. يُعرَّف هذا السمة عندما يُضبط معامل files_metadata في repo_info() على True. وإلا فهو None.
  • lfs (BlobLfsInfo، اختياري) — بيانات LFS الوصفية للملف. يُعرَّف هذا السمة عندما يكون الحجة files_metadata في repo_info() مضبوطًا على True ويُخزَّن الملف باستخدام Git LFS. وإلا فهو None.

تحتوي على معلومات أساسية حول ملف مستودع داخل مستودع على Hub.

جميع خصائص هذه الفئة اختيارية باستثناء rfilename. والسبب في ذلك هو أن أسماء الملفات فقط هي ما يُعاد عند عرض المستودعات على Hub (باستخدام list_models() أو list_datasets() أو list_spaces()). إذا كنت بحاجة إلى مزيد من المعلومات مثل حجم الملف أو معرّف blob أو تفاصيل lfs، فيجب عليك طلبها بشكل محدد من مستودع واحد في كل مرة (باستخدام model_info() أو dataset_info() أو space_info()) لأن ذلك يفرض قيوداً إضافية على خادم الخلفية لاسترجاع هذه البيانات.

RepoFile

فئة huggingface_hub.RepoFile

< >

( **kwargs )

المعاملات

  • path (str) — مسار الملف النسبي لجذر المستودع.
  • size (int) — حجم الملف، بالبايت.
  • blob_id (str) — معرّف git الخاص بالملف.
  • lfs (BlobLfsInfo، اختياري) — بيانات LFS الوصفية للملف.
  • xet_hash (str, اختياري) — تجزئة Xet الخاصة بالملف.
  • last_commit (LastCommitInfo، اختياري) — بيانات الوصف الخاصة بآخر التزام لهذا الملف. يُعرَّف فقط إذا تم استدعاء list_repo_tree() و get_paths_info() مع expand=True.
  • security (BlobSecurityInfo، اختياري) — بيانات وصفية لمسح الأمان الخاص بالملف. يُعرَّف فقط إذا تم استدعاء list_repo_tree() و get_paths_info() مع expand=True.

تحتوي على معلومات حول ملف على Hub.

RepoUrl

فئة huggingface_hub.RepoUrl

< >

( url: Anyendpoint: str | None = None )

المعاملات

  • url (Any) — قيمة نصية لعنوان المستودع.
  • endpoint (str، اختياري) — نقطة النهاية الخاصة بـ Hub. القيمة الافتراضية هي https://huggingface.co.

يرفع

HfUriError

  • HfUriError — إذا تعذّر تحليل عنوان URL (مثل مستودع قياسي من مقطع واحد، أو repo_type غير معروف).

فئة فرعية من str تصف عنوان URL مستودع على Hub.

RepoUrl يُعاد بواسطة HfApi.create_repo. وهو يرث من str من أجل التوافق مع الإصدارات السابقة. عند التهيئة، يتم تحليل الرابط لتعبئة الخصائص:

  • نقطة النهاية (str)
  • المجال (str)
  • repo_name (str)
  • repo_id (str)
  • repo_type (Literal["model", "dataset", "space"])
  • url (str)

مثال:

>>> RepoUrl('https://huggingface.co/openai-community/gpt2')
RepoUrl('https://huggingface.co/openai-community/gpt2', endpoint='https://huggingface.co', repo_type='model', repo_id='openai-community/gpt2')

>>> RepoUrl('https://huggingface.co/proxy/hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://huggingface.co/proxy/hub-ci.huggingface.co')
RepoUrl('https://huggingface.co/proxy/hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://huggingface.co/proxy/hub-ci.huggingface.co', repo_type='dataset', repo_id='dummy_user/dummy_dataset')

>>> RepoUrl('hf://datasets/my-user/my-dataset')
RepoUrl('hf://datasets/my-user/my-dataset', endpoint='https://huggingface.co', repo_type='dataset', repo_id='user/dataset')

>>> HfApi.create_repo("dummy_model")
RepoUrl('https://huggingface.co/Wauplin/dummy_model', endpoint='https://huggingface.co', repo_type='model', repo_id='Wauplin/dummy_model')

SafetensorsRepoMetadata

فئة huggingface_hub.utils.SafetensorsRepoMetadata

< >

( metadata: dict | Nonesharded: boolweight_map: dictfiles_metadata: dict )

المعاملات

  • metadata (dict, اختياري) — الميتاداتا الموجودة في ملف ‘model.safetensors.index.json’، إذا كان موجودًا. يُعبأ هذا الحقل فقط للنماذج المجزأة.
  • sharded (bool) — ما إذا كان المستودع يحتوي على نموذج مجزأ أم لا.
  • weight_map (dict[str, str]) — خريطة لجميع الأوزان. المفاتيح هي أسماء المصفوفات (tensors) والقيم هي أسماء الملفات التي تحتوي على هذه المصفوفات.
  • files_metadata (dict[str, SafetensorsFileMetadata]) — خريطة لجميع بيانات الوصف الخاصة بالملفات. المفاتيح هي أسماء الملفات والقيم هي بيانات الوصف للملف المقابل، ككائن SafetensorsFileMetadata.
  • parameter_count (dict[str, int]) — خريطة لعدد المعاملات لكل نوع بيانات. المفاتيح هي أنواع البيانات والقيم هي عدد المعاملات من ذلك النوع.

بيانات وصفية لخزّان Safetensors.

يُعتبر المستودع مستودع Safetensors إذا احتوى على ملف الأوزان ‘model.safetensors’ (نموذج غير مشترك) أو ملف الفهرس ‘model.safetensors.index.json’ (نموذج مقسّم) في جذره.

تُعاد هذه الفئة بواسطة get_safetensors_metadata().

لمزيد من التفاصيل حول صيغة safetensors، راجع https://huggingface.co/docs/safetensors/index#format.

SafetensorsFileMetadata

فئة huggingface_hub.utils.SafetensorsFileMetadata

< >

( metadata: dicttensors: dict )

المعاملات

  • metadata (dict) — الميتاداتا الموجودة في الملف.
  • tensors (dict[str, TensorInfo]) — خريطة لجميع المتجهات. المفاتيح هي أسماء المتجهات والقيم هي معلومات عن المتجه المقابل، ككائن TensorInfo.
  • parameter_count (dict[str, int]) — خريطة لعدد المعاملات لكل نوع بيانات. المفاتيح هي أنواع البيانات والقيم هي عدد المعاملات من ذلك النوع.

بيانات وصفية لملف Safetensors مستضاف على Hub.

تُعاد هذه الفئة بواسطة parse_safetensors_file_metadata().

لمزيد من التفاصيل حول صيغة safetensors، راجع https://huggingface.co/docs/safetensors/index#format.

SpaceInfo

فئة huggingface_hub.SpaceInfo

< >

( **kwargs )

المعاملات

  • id (str) — معرّف المساحة.
  • author (str، اختياري) — مؤلف المساحة.
  • card_data (SpaceCardData، اختياري) — بيانات وصفية لبطاقة المساحة (Space Card Metadata) على شكل كائن huggingface_hub.repocard_data.SpaceCardData.
  • created_at (datetime، اختياري) — تاريخ إنشاء المستودع على Hub. لاحظ أن أدنى قيمة هي 2022-03-02T23:29:04.000Z، والتي تتوافق مع التاريخ الذي بدأنا فيه بتخزين تواريخ الإنشاء.
  • datasets (list[str]، اختياري) — قائمة بمجموعات البيانات التي يستخدمها المساحة.
  • disabled (bool، اختياري) — هل المساحة معطّلة.
  • gated (Literal["auto", "manual", False]، اختياري) — هل المستودع محمي. إذا كان كذلك، ما إذا كان الاعتماد يدويًا أو تلقائيًا.
  • host (str، اختياري) — رابط URL الخاص بالمساحة.
  • last_modified (datetime، اختياري) — تاريخ آخر التزامن (commit) في المستودع.
  • likes (int) — عدد الإعجابات بالمساحة.
  • models (list[str]، اختياري) — قائمة بالنماذج المستخدمة في المساحة.
  • private (bool) — هل المستودع خاص.
  • region (Literal["us", "eu"]، اختياري) — منطقة السحابة التي يُخزَّن فيها المساحة.
  • resource_group (dict، اختياري) — معلومات مجموعة الموارد الخاصة بالمساحة.
  • runtime (SpaceRuntime، اختياري) — معلومات وقت التشغيل الخاصة بالمساحة ككائن huggingface_hub.hf_api.SpaceRuntime.
  • sdk (str، اختياري) — SDK المستخدم في المساحة.
  • sha (str، اختياري) — SHA المستودع في هذا المراجعة المحددة.
  • siblings (list[RepoSibling]) — قائمة من كائنات huggingface_hub.hf_api.RepoSibling التي تُشكّل المساحة (Space).
  • subdomain (str، اختياري) — النطاق الفرعي للمساحة.
  • tags (list[str]) — قائمة بوسوم المساحة.
  • trending_score (int، اختياري) — درجة الترند الخاصة بالمساحة.
  • used_storage (int، اختياري) — حجم المساحة على Hub بالبايت.

تحتوي على معلومات حول مساحة على Hub. يُعاد هذا الكائن بواسطة space_info() و list_spaces().

معظم خصائص هذه الفئة اختيارية. وذلك لأن البيانات التي يعيدها Hub تعتمد على الاستعلام المُدخل. بشكل عام، كلما كان الاستعلام أكثر تحديدًا، زادت المعلومات المُعادَة. على العكس من ذلك، عند سرد المساحات باستخدام list_spaces() لا تُعاد سوى مجموعة فرعية من الخصائص.

SpaceSearchResult

فئة huggingface_hub.SpaceSearchResult

< >

( data: dict )

المعاملات

  • id (str) — معرّف المساحة (مثال: "username/repo-name").
  • author (str) — مؤلف المساحة.
  • title (str) — عنوان العرض الخاص بالمساحة.
  • emoji (str أو None) — أيقونة الإيموجي الخاصة بالمساحة.
  • sdk (str أو None) — SDK المستخدم في المساحة (مثل "gradio"، "docker"، "static").
  • likes (int) — عدد الإعجابات.
  • private (bool) — ما إذا كان المساحة (Space) خاصة.
  • tags (list[str] أو None) — قائمة من الوسوم.
  • runtime (SpaceRuntime أو None) — معلومات وقت التشغيل (المرحلة، العتاد، إلخ).
  • ai_short_description (str أو None) — وصف قصير مولّد بواسطة الذكاء الاصطناعي.
  • ai_category (str أو None) — الفئة المولّدة بواسطة الذكاء الاصطناعي (مثل "Image Generation").
  • semantic_relevancy_score (float أو None) — درجة الأهمية الدلالية (0-1) نسبةً إلى استعلام البحث.
  • trending_score (int أو None) — درجة الترند.

نتيجة واحدة من واجهة برمجة التطبيقات (API) للبحث الدلالي في Spaces.

تُعاد بواسطة HfApi.search_spaces().

TensorInfo

فئة huggingface_hub.utils.TensorInfo

< >

( dtype: typing.Literal['F64', 'F32', 'F16', 'BF16', 'I64', 'I32', 'I16', 'I8', 'U8', 'U3', 'BOOL']shape: listdata_offsets: tuple )

المعاملات

  • dtype (str) — نوع البيانات الخاص بالمصفوفة (“F64”، “F32”، “F16”، “BF16”، “I64”، “I32”، “I16”، “I8”، “U8”، “U3”، “BOOL”).
  • shape (list[int]) — شكل المصفوفة.
  • data_offsets (tuple[int, int]) — إزاحات البيانات في الملف على شكل مجموعة مرتبة [BEGIN, END].
  • parameter_count (int) — عدد المعاملات في المصفوفة.

معلومات حول متجه (Tensor).

لمزيد من التفاصيل حول صيغة safetensors، راجع https://huggingface.co/docs/safetensors/index#format.

المستخدم

فئة huggingface_hub.User

< >

( **kwargs )

المعاملات

  • username (str) — اسم المستخدم على Hub (فريد).
  • fullname (str) — الاسم الكامل للمستخدم.
  • avatar_url (str) — رابط صورة المستخدم الرمزية.
  • details (str، اختياري) — تفاصيل المستخدم.
  • is_following (bool، اختياري) — ما إذا كان المستخدم الموثّق يتابع هذا المستخدم.
  • is_pro (bool، اختياري) — ما إذا كان المستخدم مستخدماً محترفاً.
  • num_models (int، اختياري) — عدد النماذج التي أنشأها المستخدم.
  • num_datasets (int، اختياري) — عدد مجموعات البيانات التي أنشأها المستخدم.
  • num_spaces (int، اختياري) — عدد المساحات التي أنشأها المستخدم.
  • num_discussions (int، اختياري) — عدد المناقشات التي بدأها المستخدم.
  • num_papers (int، اختياري) — عدد الأوراق البحثية التي كتبها المستخدم.
  • num_upvotes (int، اختياري) — عدد الأصوات الإيجابية التي حصل عليها المستخدم.
  • num_likes (int، اختياري) — عدد الإعجابات التي منحها المستخدم.
  • num_following (int, اختياري) — عدد المستخدمين الذين يتابعهم هذا المستخدم.
  • num_followers (int، اختياري) — عدد المستخدمين الذين يتابعون هذا المستخدم.
  • orgs (قائمة من Organization) — قائمة بالمنظمات التي ينتمي إليها المستخدم.

تحتوي على معلومات حول مستخدم على Hub.

UserLikes

فئة huggingface_hub.UserLikes

< >

( user: strtotal: intdatasets: list[str]kernels: list[str]models: list[str]spaces: list[str] )

المعاملات

  • user (str) — اسم المستخدم الذي تم جلب الإعجابات له.
  • total (int) — إجمالي عدد الإعجابات.
  • datasets (list[str]) — قائمة مجموعات البيانات التي أعجب بها المستخدم (بصيغة repo_ids).
  • kernels (list[str]) — قائمة بالنواة التي أعجب بها المستخدم (بصيغة repo_ids).
  • models (list[str]) — قائمة بالنماذج التي أعجب بها المستخدم (بصيغة repo_ids).
  • spaces (list[str]) — قائمة بالمساحات التي أعجب بها المستخدم (بصيغة repo_ids).

تحتوي على معلومات حول الإعجابات التي يضيفها المستخدم على المنصة.

WebhookInfo

فئة huggingface_hub.WebhookInfo

< >

( id: strurl: str | Nonejob: JobSpec | Nonewatched: list[WebhookWatchedItem]domains: list[constants.WEBHOOK_DOMAIN_T]secret: str | Nonedisabled: bool )

المعاملات

  • id (str) — معرّف خطاف الويب.
  • url (str، اختياري) — رابط webhook.
  • job (JobSpec، اختياري) — مواصفات المهمة التي سيتم تشغيلها.
  • watched (list[WebhookWatchedItem]) — قائمة العناصر التي يراقبها خطاف الويب، راجع WebhookWatchedItem.
  • domains (list[WEBHOOK_DOMAIN_T]) — قائمة بالمجالات التي يراقبها خطاف الويب. يمكن أن تكون أحد ["repo", "discussion"].
  • secret (str، اختياري) — سرّ خطّ الويب.
  • disabled (bool) — ما إذا كان خطاف الويب معطلاً أم لا.

هيكل بيانات يحتوي على معلومات حول خطاف ويب.

يتم تحديد أحد url أو job، وليس كلاهما معًا.

WebhookWatchedItem

فئة huggingface_hub.WebhookWatchedItem

< >

( type: Literal['bucket', 'dataset', 'model', 'org', 'space', 'user']name: str )

المعاملات

  • type (Literal["bucket", "dataset", "model", "org", "space", "user"]) — نوع العنصر المراد مراقبته. يمكن أن يكون أحد ["bucket", "dataset", "model", "org", "space", "user"].
  • name (str) — اسم العنصر المراد مراقبته. يمكن أن يكون اسم المستخدم، أو اسم المؤسسة، أو اسم النموذج، أو اسم مجموعة البيانات، أو اسم المساحة، أو اسم الدلو.

هيكل بيانات يحتوي على معلومات حول العناصر التي راقبها خطاف الويب.

CommitOperation

فيما يلي القيم المدعومة لـ CommitOperation():

فئة huggingface_hub.CommitOperationAdd

< >

( path_in_repo: strpath_or_fileobj: str | pathlib.Path | bytes | typing.BinaryIO )

المعاملات

  • path_in_repo (str) — مسار الملف النسبي داخل المستودع، على سبيل المثال: "checkpoints/1fec34a/weights.bin"
  • path_or_fileobj (str, Path, bytes, أو BinaryIO) — إما:
    • مسار إلى ملف محلي (بصيغة str أو pathlib.Path) للرفع
    • مخزن من البايتات (bytes) يحتوي على محتوى الملف المرقي
    • «كائن ملف» (فئة فرعية من io.BufferedIOBase)، يُحصل عليه عادةً باستخدام open(path, "rb"). يجب أن يدعم طريقتي seek() وtell().

يرفع

ValueError

  • ValueError — إذا لم يكن path_or_fileobj من نوع str أو Path أو bytes أو io.BufferedIOBase.
  • ValueError — إذا كان path_or_fileobj من نوع str أو Path لكنه ليس مسارًا إلى ملف موجود.
  • ValueError — إذا كان path_or_fileobj من نوع io.BufferedIOBase لكنه لا يدعم كلًا من seek() وtell().

هيكل بيانات يحتوي على المعلومات اللازمة لرفع ملف إلى مستودع على Hub.

as_file

< >

( with_tqdm: bool = False )

المعاملات

  • with_tqdm (bool، اختياري، القيمة الافتراضية False) — إذا كانت القيمة True، فسيتم عرض شريط تقدم عند التكرار على كائن الملف. يعمل هذا فقط إذا كان الكائن المشابه للملف مسارًا إلى ملف. لا يتم دعم البايتات النقية والمخازن المؤقتة.

مدير سياق يُنتج كائناً يشبه ملفاً يتيح قراءة البيانات الأساسية خلف path_or_fileobj.

مثال:

>>> operation = CommitOperationAdd(
...        path_in_repo="remote/dir/weights.h5",
...        path_or_fileobj="./local/weights.h5",
... )
CommitOperationAdd(path_in_repo='remote/dir/weights.h5', path_or_fileobj='./local/weights.h5')

>>> with operation.as_file() as file:
...     content = file.read()

>>> with operation.as_file(with_tqdm=True) as file:
...     while True:
...         data = file.read(1024)
...         if not data:
...              break
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]

>>> with operation.as_file(with_tqdm=True) as file:
...     httpx2.put(..., data=file)
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]

b64content

< >

( )

المحتوى المُرمّز بصيغة base64 الخاص بـpath_or_fileobj

يعيد: bytes

فئة huggingface_hub.CommitOperationDelete

< >

( path_in_repo: stris_folder: typing.Union[bool, typing.Literal['auto']] = 'auto' )

المعاملات

  • path_in_repo (str) — مسار الملف النسبي داخل المستودع، على سبيل المثال: "checkpoints/1fec34a/weights.bin" لملف أو "checkpoints/1fec34a/" لملف.
  • is_folder (bool أو Literal["auto"]، اختياري) — ما إذا كانت عملية الحذف تنطبق على مجلد أم لا. إذا كانت القيمة “auto”， يتم تخمين نوع المسار (ملف أو مجلد) تلقائيًا من خلال التحقق مما إذا كان المسار ينتهي بـ ”/” (مجلد) أم لا (ملف). لضبط نوع المسار بشكل صريح، يمكنك تعيين is_folder=True أو is_folder=False.

هيكل بيانات يحتوي على المعلومات اللازمة لحذف ملف أو مجلد من مستودع على Hub.

فئة huggingface_hub.CommitOperationCopy

< >

( src_path_in_repo: strpath_in_repo: strsrc_revision: str | None = Nonesrc_repo_id: str | None = Nonesrc_repo_type: str | None = None_src_oid: str | None = None_dest_oid: str | None = None_is_duplicated: bool = False )

المعاملات

  • src_path_in_repo (str) — مسار الملف النسبي داخل المستودع للملف الذي سيتم نسخه، على سبيل المثال "checkpoints/1fec34a/weights.bin".
  • path_in_repo (str) — مسار الملف النسبي داخل المستودع الذي سيتم نسخ الملف إليه، على سبيل المثال "checkpoints/1fec34a/weights_copy.bin".
  • src_revision (str, اختياري) — مراجعة git للملف الذي سيتم نسخه. يمكن أن تكون أي مراجعة git صالحة. الافتراضي هو مراجعة الالتزام الهدف.
  • src_repo_id (str، اختياري) — المستودع المصدر الذي سيتم النسخ منه (مثل "username/source-model"). الافتراضي هو المستودع الوجهة (نسخ داخل المستودع نفسه).
  • src_repo_type (str، اختياري) — نوع المستودع المصدر ("model" أو "dataset" أو "space"). مطلوب عند تعيين src_repo_id.

هيكل بيانات يحتوي على المعلومات اللازمة لنسخ ملف في مستودع على Hub.

تُؤيَّد كلٌّ من ملفات LFS والملفات العادية. تُنسخ ملفات LFS على جانب الخادم، بينما تُحمَّل الملفات العادية وتُعاد رفعها كجزء من عملية الالتزام.

تُؤمَّن النسخ بين المستودعات من خلال تعيين src_repo_id وsrc_repo_type. وفي حالة النسخ بين المستودعات باستخدام LFS، تُستنسخ كائنات LFS إلى المستودع الوجهة قبل إنشاء الالتزام. ويتم ذلك تلقائيًا بواسطة create_commit(). تجدر الإشارة إلى أن النسخ بين المستودعات يعمل فقط ضمن منطقة التخزين نفسها؛ إذ لا يُدعم النسخ عبر مناطق مختلفة.

ملاحظة: يمكنك دمج CommitOperationCopy و CommitOperationDelete لإعادة تسمية ملف LFS على Hub.

CommitScheduler

فئة huggingface_hub.CommitScheduler

< >

( repo_id: strfolder_path: str | pathlib.Pathevery: int | float = 5path_in_repo: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneprivate: bool | None = Nonetoken: str | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonesquash_history: bool = Falsehf_api: typing.Optional[ForwardRef('HfApi')] = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم الالتزام فيه.
  • folder_path (str أو Path) — المسار إلى المجلد المحلي الذي سيتم رفعه بانتظام.
  • every (int أو float، اختياري) — عدد الدقائق بين كل عملية تثبيت. القيمة الافتراضية هي 5 دقائق.
  • path_in_repo (str، اختياري) — المسار النسبي للمجلد في المستودع، على سبيل المثال: "checkpoints/". القيمة الافتراضية هي المجلد الجذري للمستودع.
  • repo_type (str، اختياري) — نوع المستودع الذي سيتم الالتزام به. القيمة الافتراضية هي model.
  • revision (str، اختياري) — المراجعة (revision) المستودع التي سيتم الالتزام بها. الافتراضي هو main.
  • private (bool، اختياري) — ما إذا كان سيتم جعل المستودع خاصًا. إذا كان None (الافتراضي)، فسيكون المستودع عامًا ما لم يكن الافتراضي للمنظمة هو الخاص. يتم تجاهل هذه القيمة إذا كان المستودع موجودًا بالفعل.
  • token (str، اختياري) — الرمز الذي يُستخدم للالتزام بالمستودع. الافتراضي هو الرمز المحفوظ على الجهاز.
  • allow_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، يتم رفع الملفات التي تطابق نمطًا واحدًا على الأقل فقط.
  • ignore_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، فلن يتم رفع الملفات التي تطابق أيًا من الأنماط.
  • squash_history (bool, اختياري) — ما إذا كان يجب دمج سجل المستودع بعد كل التزام. القيمة الافتراضية هي False. يُعد دمج الالتزامات مفيدًا لتجنب تدهور الأداء على المستودع عندما يكبر حجمه بشكل مفرط.
  • hf_api (HfApi، اختياري) — عميل HfApi الذي يُستخدم للالتزام على Hub. يمكن ضبطه بإعدادات مخصصة (وكيل المستخدم، الرمز المميز، …).

مجدول لرفع مجلد محلي إلى المستودع (Hub) على فترات منتظمة (مثل الدفع إلى المستودع كل 5 دقائق).

الطريقة الموصى بها لاستخدام المجدول هي استخدامه كمدير سياق. يضمن ذلك إيقاف المجدول بشكل صحيح وتحفيز آخر التزام عند انتهاء السكربت. يمكن أيضًا إيقاف المجدول يدويًا باستخدام طريقة stop. راجع دليل الرفع لمعرفة المزيد حول كيفية استخدامه.

مثال:

>>> from pathlib import Path
>>> from huggingface_hub import CommitScheduler

# Scheduler uploads every 10 minutes
>>> csv_path = Path("watched_folder/data.csv")
>>> CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path=csv_path.parent, every=10)

>>> with csv_path.open("a") as f:
...     f.write("first line")

# Some time later (...)
>>> with csv_path.open("a") as f:
...     f.write("second line")

مثال على استخدام مدير سياق:

>>> from pathlib import Path
>>> from huggingface_hub import CommitScheduler

>>> with CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path="watched_folder", every=10) as scheduler:
...     csv_path = Path("watched_folder/data.csv")
...     with csv_path.open("a") as f:
...         f.write("first line")
...     (...)
...     with csv_path.open("a") as f:
...         f.write("second line")

# Scheduler is now stopped and last commit have been triggered

push_to_hub

< >

( )

ادفع المجلد إلى Hub وعُد بمعلومات الالتزام.

لا يُقصد استدعاء هذه الطريقة مباشرةً. يتم تشغيلها في الخلفية بواسطة المجدول، مع الالتزام بآلية طابور لتجنب الالتزامات المتزامنة. قد يؤدي الاستدعاء المباشر للطريقة إلى مشاكل في التزامن.

السلوك الافتراضي لـ push_to_hub هو افتراض أن المجلد مخصص للإضافة فقط. يقوم该方法 بسرد جميع الملفات في المجلد ورفع الملفات التي تم تغييرها فقط. إذا لم يتم العثور على أي تغييرات، فإن الدالة تعيد دون الالتزام بأي شيء. إذا كنت ترغب في تغيير هذا السلوك، يمكنك الوراثة من CommitScheduler وإعادة تعريف هذه الدالة. يمكن أن يكون هذا مفيدًا، على سبيل المثال، لضغط البيانات معًا في ملف واحد قبل الالتزام. لمزيد من التفاصيل والأمثلة، راجع دليل التكامل الخاص بنا.

إيقاف

< >

( )

أوقف المجدول.

لا يمكن إعادة تشغيل مجدول متوقف. يُستخدم هذا الغرض بشكل رئيسي لأغراض الاختبارات.

مُحفِّز

< >

( )

استدعاء push_to_hub وإرجاع مستقبلي.

يتم استدعاء هذه الطريقة تلقائيًا كل every دقائق. يمكنك أيضًا استدعاؤها يدويًا لتفعيل التزامن فورًا، دون الانتظار حتى التزامن المجدول التالي.

Update on GitHub

←متغيرات البيئة CLI→