# المجموعات

المجموعة هي مجموعة من العناصر ذات الصلة على المنصة (النماذج، مجموعات البيانات، المساحات، الأوراق البحثية، المجموعات، الدلاء) التي تُنظَّم معًا على نفس الصفحة. المجموعات مفيدة لإنشاء معرض أعمالك الخاص، أو وضع علامات على المحتوى ضمن فئات، أو عرض قائمة منتقاة من العناصر التي ترغب في مشاركتها. اطّلع على هذا [الدليل](https://huggingface.co/docs/hub/collections) لفهم المزيد من التفاصيل حول ما هي المجموعات وكيف تظهر على المنصة.

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

## جلب مجموعة

استخدم [get_collection()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.get_collection) لجلب مجموعاتك أو أي مجموعات عامة. يجب أن تمتلك *slug* الخاص بالمجموعة لاسترجاعها. الـ slug هو معرّف للمجموعة يعتمد على العنوان ومعرّف فريد. يمكنك العثور على الـ slug في عنوان URL لصفحة المجموعة.

    

لنستدعِ المجموعة باستخدام `"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`:

```py
>>> from huggingface_hub import get_collection
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
>>> collection
Collection(
  slug='TheBloke/recent-models-64f9a55bb3115b4f513ec026',
  title='Recent models',
  owner='TheBloke',
  items=[...],
  last_updated=datetime.datetime(2023, 10, 2, 22, 56, 48, 632000, tzinfo=datetime.timezone.utc),
  position=1,
  private=False,
  theme='green',
  upvotes=90,
  description="Models I've recently quantized. Please note that currently this list has to be updated manually, and therefore is not guaranteed to be up-to-date."
)
>>> collection.items[0]
CollectionItem(
  item_object_id='651446103cd773a050bf64c2',
  item_id='TheBloke/U-Amethyst-20B-AWQ',
  item_type='model',
  position=88,
  note=None
)
```

تحتوي كائن [Collection](/docs/huggingface_hub/v2.4.0/ar/package_reference/collections#huggingface_hub.Collection) الذي يُعاد بواسطة [get_collection()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.get_collection) على:
- بيانات وصفية عالية المستوى: `slug`، `owner`، `title`، `description`، وما إلى ذلك.
- قائمة من كائنات [CollectionItem](/docs/huggingface_hub/v2.4.0/ar/package_reference/collections#huggingface_hub.CollectionItem)؛ يمثل كل عنصر نموذجًا أو مجموعة بيانات أو مساحة أو ورقة بحثية أو مجموعة أو حاوية.

يُكفَل لجميع عناصر المجموعة ما يلي:
- معرّف فريد `item_object_id`: وهو معرّف عنصر المجموعة في قاعدة البيانات
- `item_id`: هذا هو المعرّف الخاص بالعنصر الأساسي (نموذج، مجموعة بيانات، مساحة، ورقة بحثية، مجموعة، دلو) على المنصة؛ وليس بالضرورة أن يكون فريدًا، بل الزوج `item_id`/`item_type` هو الفريد
- عنصر من نوع `item_type`: نموذج، مجموعة بيانات، مساحة، ورقة بحثية، مجموعة، دلو
- `position` للعنصر في المجموعة، والذي يمكن تحديثه لإعادة تنظيم مجموعتك (انظر [update_collection_item()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item) أدناه)

يمكن أيضًا إرفاق `note` بالعنصر. وهذا مفيد لإضافة معلومات إضافية حول العنصر (تعليق، رابط إلى منشور مدونة، إلخ). لا يزال للخاصية قيمة `None` إذا لم يكن للعنصر ملاحظة.

بالإضافة إلى هذه السمات الأساسية، يمكن أن تحتوي العناصر المُعادَة على سمات إضافية اعتمادًا على نوعها: `author`، `private`، `lastModified`، `gated`، `title`، `likes`، `upvotes`، وما إلى ذلك. لا يُكفَل إرجاع أيٍّ من هذه السمات.

## قوائم المجموعات

يمكننا أيضًا استرجاع المجموعات باستخدام [list_collections()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.list_collections). يمكن تصفية المجموعات باستخدام بعض المعاملات. لنستعرض جميع المجموعات الخاصة بالمستخدم [`teknium`](https://huggingface.co/teknium).
```py
>>> from huggingface_hub import list_collections

>>> collections = list_collections(owner="teknium")
```

يعيد هذا الأمر قابلًا للتكرار من كائنات `Collection`. يمكننا التكرار عليها لطباعة عدد الأصوات الإيجابية، على سبيل المثال، لكل مجموعة.

```py
>>> for collection in collections:
...   print("Number of upvotes:", collection.upvotes)
Number of upvotes: 1
Number of upvotes: 5
```

> [!WARNING]
> عند سرد المجموعات، يتم اقتصاص قائمة العناصر لكل مجموعة إلى 4 عناصر كحد أقصى. لاسترجاع جميع العناصر من مجموعة، يجب عليك استخدام [get_collection()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.get_collection).

من الممكن إجراء تصفية أكثر تقدماً. لنجلب جميع المجموعات التي تحتوي على النموذج [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF)، مرتبة حسب الاتجاهات، مع تحديد العدد بـ 5.
```py
>>> collections = list_collections(item="models/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF", sort="trending", limit=5):
>>> for collection in collections:
...   print(collection.slug)
teknium/quantized-models-6544690bb978e0b0f7328748
AmeerH/function-calling-65560a2565d7a6ef568527af
PostArchitekt/7bz-65479bb8c194936469697d8c
gnomealone/need-to-test-652007226c6ce4cdacf9c233
Crataco/favorite-7b-models-651944072b4fffcb41f8b568
```

يجب أن يكون المعامل `sort` أحد `"last_modified"` أو `"trending"` أو `"upvotes"`. يقبل المعامل `item` أي عنصر محدد. على سبيل المثال:
* `"models/teknium/OpenHermes-2.5-Mistral-7B"`
* `"spaces/julien-c/open-gpt-rhyming-robot"`
* `"datasets/squad"`
* `"papers/2311.12983"`
* `"buckets/namespace/bucket-name"`

لمزيد من التفاصيل، يرجى الاطلاع على مرجع [list_collections()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.list_collections).

## إنشاء مجموعة جديدة

الآن وبعد أن عرفنا كيفية الحصول على [Collection](/docs/huggingface_hub/v2.4.0/ar/package_reference/collections#huggingface_hub.Collection)، لنقم بإنشاء مجموعتنا الخاصة! استخدم [create_collection()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.create_collection) مع عنوان ووصف. لإنشاء مجموعة على صفحة منظمة، مرر `namespace="my-cool-org"` عند إنشاء المجموعة. أخيرًا، يمكنك أيضًا إنشاء مجموعات خاصة عن طريق تمرير `private=True`.

```py
>>> 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](/docs/huggingface_hub/v2.4.0/ar/package_reference/collections#huggingface_hub.Collection) يحتوي على البيانات الوصفية عالية المستوى (العنوان، الوصف، المالك، إلخ) وقائمة عناصر فارغة. ستتمكن الآن من الإشارة إلى هذه المجموعة باستخدام `slug` الخاص بها.

```py
>>> collection.slug
'owner/iccv-2023-15e23b46cb98efca45'
>>> collection.title
"ICCV 2023"
>>> collection.owner
"username"
>>> collection.url
'https://huggingface.co/collections/owner/iccv-2023-15e23b46cb98efca45'
```

## إدارة العناصر في مجموعة

الآن وبعد أن أصبح لدينا [Collection](/docs/huggingface_hub/v2.4.0/ar/package_reference/collections#huggingface_hub.Collection)، نريد إضافة عناصر إليه وتنظيمها.

### إضافة عناصر

يجب إضافة العناصر واحدًا تلو الآخر باستخدام [add_collection_item()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.add_collection_item). كل ما تحتاج إلى معرفته هو `collection_slug` و`item_id` و`item_type`. بشكل اختياري، يمكنك أيضًا إضافة `note` إلى العنصر (بحد أقصى 500 حرف).

```py
>>> from huggingface_hub import create_collection, add_collection_item

>>> collection = create_collection(title="OS Week Highlights - Sept 18 - 24", namespace="osanseviero")
>>> collection.slug
"osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80"

>>> add_collection_item(collection.slug, item_id="coqui/xtts", item_type="space")
>>> add_collection_item(
...     collection.slug,
...     item_id="warp-ai/wuerstchen",
...     item_type="model",
...     note="Würstchen is a new fast and efficient high resolution text-to-image architecture and model"
... )
>>> add_collection_item(collection.slug, item_id="lmsys/lmsys-chat-1m", item_type="dataset")
>>> add_collection_item(collection.slug, item_id="warp-ai/wuerstchen", item_type="space") # same item_id, different item_type
>>> add_collection_item(collection.slug, item_id="namespace/my-bucket", item_type="bucket")
```

إذا كان العنصر موجودًا مسبقًا في مجموعة (نفس زوج `item_id`/`item_type`)، فسيتم رفع خطأ HTTP 409. يمكنك اختيار تجاهل هذا الخطأ عن طريق تعيين `exists_ok=True`.

### إضافة ملاحظة إلى عنصر موجود

يمكنك تعديل عنصر موجود لإضافة ملاحظة مرفقة به أو تعديلها باستخدام [update_collection_item()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item). دعنا نعيد استخدام المثال أعلاه:

```py
>>> from huggingface_hub import get_collection, update_collection_item

# Fetch collection with newly added items
>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80"
>>> collection = get_collection(collection_slug)

# Add note the `lmsys-chat-1m` dataset
>>> update_collection_item(
...     collection_slug=collection_slug,
...     item_object_id=collection.items[2].item_object_id,
...     note="This dataset contains one million real-world conversations with 25 state-of-the-art LLMs.",
... )
```

### إعادة ترتيب العناصر

العناصر في مجموعة مرتبة. يُحدَّد الترتيب بواسطة خاصية `position` لكل عنصر. افتراضيًا، تُرتَّب العناصر بإضافة العناصر الجديدة في نهاية المجموعة. يمكنك تحديث الترتيب باستخدام [update_collection_item()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item) بالطريقة نفسها التي تضيف بها ملاحظة.

لنعيد استخدام المثال أعلاه:

```py
>>> from huggingface_hub import get_collection, update_collection_item

# Fetch collection
>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80"
>>> collection = get_collection(collection_slug)

# Reorder to place the two `Wuerstchen` items together
>>> update_collection_item(
...     collection_slug=collection_slug,
...     item_object_id=collection.items[3].item_object_id,
...     position=2,
... )
```

### إزالة العناصر

أخيرًا، يمكنك أيضًا حذف عنصر باستخدام [delete_collection_item()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.delete_collection_item).

```py
>>> from huggingface_hub import get_collection, update_collection_item

# Fetch collection
>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80"
>>> collection = get_collection(collection_slug)

# Remove `coqui/xtts` Space from the list
>>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id)
```

## حذف المجموعة

يمكن حذف مجموعة باستخدام [delete_collection()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.delete_collection).

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

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