# Koleksi

Koleksi adalah sekelompok item terkait di Hub (model, dataset, Spaces, paper, koleksi, bucket) yang diorganisasikan bersama di halaman yang sama. Koleksi berguna untuk membuat portofolio Anda sendiri, menandai konten dalam kategori, atau menyajikan daftar item kurasi yang ingin Anda bagikan. Lihat [panduan](https://huggingface.co/docs/hub/collections) ini untuk memahami lebih detail apa itu koleksi dan bagaimana tampilannya di Hub.

Anda dapat mengelola koleksi secara langsung di browser, tetapi dalam panduan ini, kami akan berfokus pada cara mengelolanya secara programatik.

## Ambil koleksi

Gunakan [get_collection()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.get_collection) untuk mengambil koleksi Anda atau koleksi publik mana pun. Anda harus memiliki *slug* dari koleksi tersebut untuk mengambilnya. Slug adalah pengidentifikasi untuk sebuah koleksi yang didasarkan pada judul dan ID unik. Anda dapat menemukan slug di URL halaman koleksi.

    

Mari kita ambil koleksi dengan, `"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
)
```

Objek [Collection](/docs/huggingface_hub/v2.4.0/id/package_reference/collections#huggingface_hub.Collection) yang dikembalikan oleh [get_collection()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.get_collection) berisi:
- metadata tingkat tinggi: `slug`, `owner`, `title`, `description`, dll.
- daftar objek [CollectionItem](/docs/huggingface_hub/v2.4.0/id/package_reference/collections#huggingface_hub.CollectionItem); setiap item mewakili model, dataset, Space, paper, collection, atau bucket.

Semua item koleksi dijamin memiliki:
- `item_object_id` yang unik: ini adalah id dari item koleksi di database
- sebuah `item_id`: ini adalah id dari item mendasar (model, dataset, Space, paper, collection, bucket) di Hub; id ini tidak selalu unik, dan hanya pasangan `item_id`/`item_type` yang unik
- sebuah `item_type`: model, dataset, Space, paper, collection, bucket
- the `position` of the item in the collection, which can be updated to reorganize your collection (see [update_collection_item()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item) below)

Sebuah `note` juga dapat dilampirkan pada item. Hal ini berguna untuk menambahkan informasi tambahan tentang item (komentar, tautan ke artikel blog, dll.). Atribut ini masih memiliki nilai `None` jika item tidak memiliki catatan.

Selain atribut dasar ini, item yang dikembalikan dapat memiliki atribut tambahan tergantung pada jenisnya: `author`, `private`, `lastModified`, `gated`, `title`, `likes`, `upvotes`, dan sebagainya. Tidak ada jaminan bahwa atribut-atribut ini akan dikembalikan.

## Daftarkan koleksi

Kita juga dapat mengambil koleksi menggunakan [list_collections()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.list_collections). Koleksi dapat difilter menggunakan beberapa parameter. Mari kita daftarkan semua koleksi dari pengguna [`teknium`](https://huggingface.co/teknium).
```py
>>> from huggingface_hub import list_collections

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

Ini mengembalikan iterable dari objek `Collection`. Kita dapat mengiterasinya untuk mencetak, misalnya, jumlah upvote untuk setiap koleksi.

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

> [!WARNING]
> Saat mendaftar koleksi, daftar item per koleksi dipangkas menjadi maksimal 4 item. Untuk mengambil semua item dari sebuah koleksi, Anda harus menggunakan [get_collection()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.get_collection).

Anda dapat melakukan filtering yang lebih lanjut. Mari kita ambil semua koleksi yang berisi model [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF), diurutkan berdasarkan trending, dan batasi jumlahnya menjadi 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
```

Parameter `sort` harus salah satu dari `"last_modified"`, `"trending"` atau `"upvotes"`. Parameter `item` menerima item tertentu apa pun. Contoh:
* `"models/teknium/OpenHermes-2.5-Mistral-7B"`
* `"spaces/julien-c/open-gpt-rhyming-robot"`
* `"datasets/squad"`
* `"papers/2311.12983"`
* `"buckets/namespace/bucket-name"`

Untuk detail lebih lanjut, silakan periksa referensi [list_collections()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.list_collections).

## Buat koleksi baru

Sekarang setelah kita tahu cara mendapatkan [Collection](/docs/huggingface_hub/v2.4.0/id/package_reference/collections#huggingface_hub.Collection), mari buat milik kita sendiri! Gunakan [create_collection()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.create_collection) dengan judul dan deskripsi. Untuk membuat koleksi di halaman organisasi, berikan `namespace="my-cool-org"` saat membuat koleksi. Terakhir, Anda juga dapat membuat koleksi privat dengan memberikan `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",
... )
```

Fungsi ini akan mengembalikan objek [Collection](/docs/huggingface_hub/v2.4.0/id/package_reference/collections#huggingface_hub.Collection) dengan metadata tingkat tinggi (judul, deskripsi, pemilik, dll.) dan daftar item yang kosong. Anda kini dapat merujuk ke koleksi ini menggunakan `slug`-nya.

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

## Kelola item dalam koleksi

Sekarang setelah kita memiliki [Collection](/docs/huggingface_hub/v2.4.0/id/package_reference/collections#huggingface_hub.Collection), kita ingin menambahkan item ke dalamnya dan mengorganisasikannya.

### Tambahkan item

Item harus ditambahkan satu per satu menggunakan [add_collection_item()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.add_collection_item). Anda hanya perlu mengetahui `collection_slug`, `item_id`, dan `item_type`. Secara opsional, Anda juga dapat menambahkan `note` pada item (maksimum 500 karakter).

```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")
```

Jika item sudah ada dalam koleksi (pasangan `item_id`/`item_type` yang sama), error HTTP 409 akan dilempar. Anda dapat memilih untuk mengabaikan error ini dengan mengatur `exists_ok=True`.

### Tambahkan catatan ke item yang sudah ada

Anda dapat memodifikasi item yang sudah ada untuk menambahkan atau memodifikasi catatan yang terlampir padanya menggunakan [update_collection_item()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item). Mari kita gunakan kembali contoh di atas:

```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.",
... )
```

### Urutkan ulang item

Item dalam sebuah koleksi memiliki urutan. Urutan ditentukan oleh atribut `position` dari setiap item. Secara default, item diurutkan dengan menambahkan item baru di akhir koleksi. Anda dapat memperbarui urutan menggunakan [update_collection_item()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item) dengan cara yang sama seperti menambahkan catatan.

Mari kita gunakan kembali contoh di atas:

```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,
... )
```

### Hapus item

Terakhir, Anda juga dapat menghapus item menggunakan [delete_collection_item()](/docs/huggingface_hub/v2.4.0/id/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)
```

## Hapus koleksi

Koleksi dapat dihapus menggunakan [delete_collection()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.delete_collection).

> [!WARNING]
> Ini adalah tindakan yang tidak dapat dibatalkan. Koleksi yang dihapus tidak dapat dipulihkan.

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