إنشاء مستودع وإدارته

مستودع Hugging Face Hub هو مجموعة من مستودعات git. Git هو أداة شائعة الاستخدام في تطوير البرمجيات لإدارة إصدارات المشاريع بسهولة عند العمل بشكل تعاوني. ستوضح لك هذه الدليل كيفية التفاعل مع المستودعات على المستودع، لا سيما:

• إنشاء مستودع وحذفه.
• إدارة الفروع والوسوم.
• أعد تسمية مستودعك.
• حدّث مستوى ظهور مستودعك.
• إدارة نسخة محلية من مستودعك.

إذا كنت معتادًا على العمل مع منصات مثل GitLab/GitHub/Bitbucket، فقد يكون غريزتك الأولى استخدام git CLI لاستنساخ مستودعك (git clone)، والتزام التغييرات (git add, git commit)، ودفعها (git push). هذا مقبول عند استخدام Hugging Face Hub. ومع ذلك، لا تتشارك هندسة البرمجيات وتعلم الآلة نفس المتطلبات وسير العمل. فقد تحافظ مستودعات النماذج على ملفات أوزان نماذج كبيرة لإطارات وأدوات مختلفة، لذا فإن استنساخ المستودع قد يؤدي إلى صيانة مجلدات محلية كبيرة ذات أحجام ضخمة. ونتيجةً لذلك، قد يكون من الكفاءة استخدام طرق HTTP المخصصة لدينا. يمكنك قراءة صفحة الشرح الخاصة بنا Git vs HTTP paradigm لمزيد من التفاصيل.

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

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

يمكنك سرد جميع المستودعات (النماذج، مجموعات البيانات، المساحات، والدلاء) الخاصة بحسابك أو منظمة باستخدام list_user_repos(). تتضمن النتائج معلومات التخزين وتُرتَّب حسب استهلاك التخزين.

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

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

أو عبر سطر الأوامر (يعرض 30 مستودعًا افتراضيًا، استخدم --limit 0 لعرض جميعها):

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

إنشاء المستودعات وحذفها

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

إنشاء مستودع

أنشئ مستودعًا فارغًا باستخدام create_repo() وحدد له اسمًا عبر معامل repo_id. يتكوّن repo_id من مساحة الأسماء الخاصة بك متبوعة باسم المستودع: username_or_org/repo_name.

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'

أو عبر سطر الأوامر:

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

بشكل افتراضي، ينشئ create_repo() مستودع نموذج. لكن يمكنك استخدام معامل repo_type لتحديد نوع مستودع آخر. على سبيل المثال، إذا كنت ترغب في إنشاء مستودع مجموعة بيانات:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

أو عبر سطر الأوامر:

>>> hf repos create lysandre/test-dataset --repo-type dataset

عند إنشاء مستودع، يمكنك تحديد مستوى ظهور المستودع باستخدام معامل visibility:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

أو عبر سطر الأوامر:

>>> hf repos create lysandre/test-private --private

إذا كنت ترغب في تغيير مستوى ظهور المستودع في وقت لاحق، يمكنك استخدام دالة update_repo_settings().

إذا كنت جزءًا من منظمة تملك خطة Enterprise، يمكنك إنشاء مستودع في مجموعة موارد محددة عن طريق تمرير resource_group_id كمعامل إلى create_repo(). مجموعات الموارد هي ميزة أمان للتحكم في الأعضاء من منطقتك الذين يمكنهم الوصول إلى مورد معين. يمكنك الحصول على معرّف مجموعة الموارد عن طريق نسخه من عنوان URL لصفحة إعدادات منطقتك على Hub (على سبيل المثال "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). لمزيد من التفاصيل حول مجموعات الموارد، راجع هذا الدليل.

يمكنك أيضًا إنشاء مستودع في منطقة سحابية محددة عن طريق تمرير region كعامل:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

حذف مستودع

احذف مستودعًا باستخدام delete_repo(). تأكد من أنك تريد حذف المستودع لأن هذه عملية لا يمكن التراجع عنها!

حدد repo_id للمستودع الذي تريد حذفه:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

مرّر missing_ok=True لتجاهل الاستدعاء بصمت إذا لم يكن المستودع موجودًا:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

أو عبر سطر الأوامر:

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

نسخ مستودع

في بعض الحالات، قد ترغب في نسخ مستودع شخص آخر لتكييفه مع حالتك الخاصة. يمكنك القيام بذلك باستخدام طريقة duplicate_repo(). ستنسخ هذه الطريقة المستودع بأكمله مع الحفاظ على سجل git الكامل. يعمل هذا مع النماذج ومجموعات البيانات وSpaces. أما بالنسبة لـ Spaces، فستحتاج لا يزال إلى إعداد إعداداتك الخاصة (العتاد، وقت النوم، التخزين، المتغيرات والأسرار). راجع دليل إدارة مساحتك لدينا لمزيد من التفاصيل.

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

كما هو الحال مع create_repo()، يقبل duplicate_repo() معامل resource_group_id لإنشاء النسخة مباشرةً داخل مجموعة موارد في منظمة Enterprise الخاصة بك (--resource-group-id مع hf repos duplicate).

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

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

البحث عن مساحات

توفر المنصة واجهة برمجية للبحث الدلالي لاكتشاف المساحات. يمكنك البحث باستخدام استعلامات بلغة طبيعية باستخدام search_spaces():

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

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

رفع الملفات وتنزيلها

الآن بعد أن أنشأت مستودعك، أنت مهتم بدفع التغييرات إليه وتنزيل الملفات منه.

تستحق هاتان المسألتان دليلين مستقلين. يُرجى الرجوع إلى دليل الرفع ودليل التنزيل لتعلم كيفية استخدام مستودعك.

نسخ الملفات

استخدم copy_files() لنسخ الملفات الموجودة مسبقًا على Hub من مستودع إلى آخر (أو حتى داخل نفس المستودع) دون الحاجة إلى تنزيلها ثم رفعها مرة أخرى. يدعم الأمر الملفات الفردية والمجلدات الكاملة على حد سواء، وتُنسخ الملفات المُتبعة بواسطة Xet أو LFS على جانب الخادم عبر التجزئة (hash).

>>> from huggingface_hub import copy_files

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

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

أو عبر سطر الأوامر، باستخدام الأمر الموحّد hf cp (المتاح أيضاً باسم hf repos cp):

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

يمكن لـ copy_files (و hf cp) أيضًا نسخ الملفات من مستودع إلى Bucket. لا يُدعم النسخ من bucket إلى مستودع. راجع دليل Buckets لمزيد من التفاصيل.

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

الفرع والوسوم

غالبًا ما تستخدم مستودعات Git الفروع لتخزين إصدارات مختلفة من نفس المستودع. يمكن أيضًا استخدام الوسوم (Tags) لتحديد حالة معينة لمستودعك، على سبيل المثال، عند إصدار نسخة. بشكل أكثر عمومية، يُشار إلى الفروع والوسوم باسم git references.

إنشاء الفروع والوسوم

يمكنك إنشاء فرع ووسوم جديدة باستخدام create_branch() و create_tag():

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

أو عبر سطر الأوامر:

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

يمكنك استخدام الدالتين delete_branch() و delete_tag() بنفس الطريقة لحذف فرع أو وسم، أو استخدام hf repos branch delete و hf repos tag delete على التوالي في سطر الأوامر.

عرض جميع الفروع والوسوم

يمكنك أيضًا سرد مراجع git الموجودة في المستودع باستخدام list_repo_refs():

>>> from huggingface_hub import list_repo_refs
>>> 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')
   ]
)

تغيير إعدادات المستودع

تأتي المستودعات مع بعض الإعدادات التي يمكنك تكوينها. في معظم الأحيان، ستريد القيام بذلك يدويًا في صفحة إعدادات المستودع في متصفحك. يجب أن يكون لديك صلاحية الكتابة في المستودع لتكوينه (إما أن تكون مالكه أو أن تكون جزءًا من منظمة). في هذا القسم، سنستعرض الإعدادات التي يمكنك أيضًا تكوينها برمجيًا باستخدام huggingface_hub.

بعض الإعدادات خاصة بـ Spaces (مثل العتاد ومتغيرات البيئة، ...). لضبط تلك الإعدادات، يُرجى الرجوع إلى دليل إدارة مساحاتك.

تحديث مستوى الظهور

يمكن أن يكون المستودع عامًا أو خاصًا. لا يظهر المستودع الخاص إلا لك أو لأعضاء المنظمة التي يقع فيها المستودع. قم بتغيير المستودع إلى خاص كما هو موضح فيما يلي:

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

أو عبر سطر الأوامر:

>>> hf repos settings lysandre/test-private --private true

إعداد الوصول المقيّد

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

يمكنك تعيين مستودع كمستودع محمي باستخدام update_repo_settings():

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

أو عبر سطر الأوامر:

>>> hf repos settings lysandre/test-private --gated auto

إعادة تسمية مستودعك

يمكنك إعادة تسمية مستودعك على Hub باستخدام move_repo(). وباستخدام هذه الطريقة، يمكنك أيضًا نقل المستودع من مستخدم إلى منظمة. عند القيام بذلك، هناك بعض القيود يجب أن تكون على دراية بها. على سبيل المثال، لا يمكنك نقل مستودعك إلى مستخدم آخر.

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

أو عبر سطر الأوامر:

>>> hf repos move Wauplin/cool-model huggingface/cool-model

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

يدعم الـ Hub نوع مستودع "kernel" لاستضافة نوى الحساب. وهذا النوع ليس مستودعًا متوافقًا بالكامل. فقد تم اختبار مجموعة محدودة من الطرق ودعمها رسميًا فقط:

• kernel_info()
• hf_hub_download()
• snapshot_download()
• list_repo_refs()
• list_repo_files()
• list_repo_tree()

لاحظ أن create_repo() و delete_repo() متوافقتان أيضًا، لكنهما مقيدتان بعدد صغير من المستخدمين والمنظمات المسموح بها على Hub.

لإنشاء مستودعات النواة ونشرها واستخدامها، يُرجى استخدام حزمة kernels المخصصة بدلاً من ذلك. راجع توثيق Kernels لمزيد من التفاصيل.