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 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() untuk mengambil koleksi Anda atau koleksi publik mana pun. Anda harus memiliki slug dari koleksi tersebut untuk mengambilnya. Slug adalah pengidentifikasi untuk 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":

>>> 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 yang dikembalikan oleh get_collection() berisi:

• metadata tingkat tinggi: slug, owner, title, description, dll.
• daftar objek 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() 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(). Koleksi dapat difilter menggunakan beberapa parameter. Mari kita daftarkan semua koleksi dari pengguna teknium.

>>> 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.

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

Saat mendaftar koleksi, daftar item per koleksi dipangkas menjadi maksimal 4 item. Untuk mengambil semua item dari sebuah koleksi, Anda harus menggunakan get_collection().

Anda dapat melakukan filtering yang lebih lanjut. Mari kita ambil semua koleksi yang berisi model TheBloke/OpenHermes-2.5-Mistral-7B-GGUF, diurutkan berdasarkan trending, dan batasi jumlahnya menjadi 5.

>>> 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().

Buat koleksi baru

Sekarang setelah kita tahu cara mendapatkan Collection, mari buat milik kita sendiri! Gunakan 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.

>>> 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 dengan metadata tingkat tinggi (judul, deskripsi, pemilik, dll.) dan daftar item yang kosong. Anda kini dapat merujuk ke koleksi ini menggunakan slug-nya.

>>> 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, kita ingin menambahkan item ke dalamnya dan mengorganisasikannya.

Tambahkan item

Item harus ditambahkan satu per satu menggunakan 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).

>>> 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(). Mari kita gunakan kembali contoh di atas:

>>> 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() dengan cara yang sama seperti menambahkan catatan.

Mari kita gunakan kembali contoh di atas:

>>> 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().

>>> 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().

Ini adalah tindakan yang tidak dapat dibatalkan. Koleksi yang dihapus tidak dapat dipulihkan.

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