Koleksiyonlar

Bir koleksiyon, Hub'da (modeller, veri setleri, Spaces, makaleler, koleksiyonlar, depolar) aynı sayfada birlikte organize edilen ilgili öğelerden oluşan bir gruptur. Koleksiyonlar, kendi portföyünüzü oluşturmak, içeriği kategorilere göre yer imi olarak kaydetmek veya paylaşmak istediğiniz seçilmiş bir öğe listesi sunmak için kullanışlıdır. Koleksiyonların ne olduğunu ve Hub'da nasıl göründüğünü daha ayrıntılı anlamak için bu kılavuza göz atın.

Koleksiyonları tarayıcıda doğrudan yönetebilirsiniz ancak bu kılavuzda, bunları programatik olarak nasıl yöneteceğinize odaklanacağız.

Bir koleksiyon getir

Koleksiyonlarınızı veya herkese açık olanları almak için get_collection() kullanın. Bir koleksiyonu almak için koleksiyonun slug değerine sahip olmanız gerekir. Slug, başlığa ve benzersiz bir kimliğe dayalı koleksiyon tanımlayıcısıdır. Slug değerini koleksiyon sayfasının URL'sinde bulabilirsiniz.

Koleksiyonu "TheBloke/recent-models-64f9a55bb3115b4f513ec026" ile alalım:

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

get_collection() tarafından döndürülen Collection nesnesi şunları içerir:

• yüksek düzeyde meta veriler: slug, owner, title, description vb.
• CollectionItem nesnelerinin listesi; her bir öğe bir model, veri seti, Space, makale, koleksiyon veya kovayı temsil eder.

Tüm koleksiyon öğelerinin şunlara sahip olması garanti edilir:

• benzersiz bir item_object_id: bu, veritabanındaki koleksiyon öğesinin kimliğidir
• item_id: bu, alttaki öğenin (model, veri seti, Space, makale, koleksiyon, bucket) Hub'daki kimliğidir; bu kimlik tek başına benzersiz olmak zorunda değildir, yalnızca item_id/item_type çifti benzersizdir
• item_type: model, dataset, Space, paper, collection, bucket
• koleksiyondaki öğenin position değeri, koleksiyonunuzu yeniden düzenlemek için güncellenebilir (aşağıdaki update_collection_item() bölümüne bakın)

note öğeye de eklenebilir. Bu, öğe hakkında ek bilgi (bir yorum, bir blog gönderisine bağlantı vb.) eklemek için kullanışlıdır. Bir öğenin notu yoksa bu öznitelik hâlâ None değerine sahiptir.

Bu temel özniteliklerin yanı sıra, döndürülen öğeler türlerine bağlı olarak author, private, lastModified, gated, title, likes, upvotes gibi ek özniteliklere sahip olabilir. Bu özniteliklerin hiçbirisinin döndürülmesi garanti edilmemektedir.

Koleksiyonları listele

list_collections() ile koleksiyonları da alabiliriz. Koleksiyonlar bazı parametreler kullanılarak filtrelenebilir. teknium kullanıcısının tüm koleksiyonlarını listeleyelim.

>>> from huggingface_hub import list_collections

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

Bu, Collection nesnelerinden oluşan bir yinelebilir (iterable) döndürür. Örneğin, her koleksiyon için oy sayısını yazdırmak üzere bunların üzerinde yineleyebiliriz.

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

Koleksiyonları listelerken, koleksiyon başına öğe listesi en fazla 4 öğeyle sınırlıdır. Bir koleksiyondaki tüm öğeleri almak için get_collection() kullanmanız gerekir.

Daha gelişmiş filtreleme yapmak mümkündür. TheBloke/OpenHermes-2.5-Mistral-7B-GGUF modelini içeren tüm koleksiyonları, trend sırasına göre sıralayarak ve sayıyı 5 ile sınırlayalım.

>>> 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 parametresi "last_modified", "trending" veya "upvotes" değerlerinden biri olmalıdır. item parametresi herhangi bir özel öğeyi kabul eder. Örneğin:

• "models/teknium/OpenHermes-2.5-Mistral-7B"
• "spaces/julien-c/open-gpt-rhyming-robot"
• "datasets/squad"
• "papers/2311.12983"
• "buckets/namespace/bucket-name"

Daha fazla ayrıntı için list_collections() referansına göz atın.

Yeni bir koleksiyon oluşturun

Artık bir Collection nasıl alınacağını bildiğimize göre, kendi koleksiyonumuzu oluşturalım! Başlık ve açıklama ile create_collection() kullanın. Bir organizasyon sayfasında koleksiyon oluşturmak için, koleksiyonu oluştururken namespace="my-cool-org" parametresini iletin. Son olarak, private=True parametresini ileterek özel koleksiyonlar da oluşturabilirsiniz.

>>> from huggingface_hub import create_collection

>>> collection = create_collection(
...     title="ICCV 2023",
...     description="Portfolio of models, papers and demos I presented at ICCV 2023",
... )

Yüksek düzeyde meta verileri (başlık, açıklama, sahip vb.) ve boş bir öğe listesi içeren bir Collection nesnesi döndürülür. Artık bu koleksiyona slug değeriyle başvurabilirsiniz.

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

Bir koleksiyondaki öğeleri yönetme

Artık bir Collection’ımız var ve ona öğeler ekleyip düzenlemek istiyoruz.

Öğeler ekle

Öğeler, add_collection_item() kullanılarak tek tek eklenmelidir. Sadece collection_slug, item_id ve item_type bilgilerine ihtiyacınız vardır. İsteğe bağlı olarak öğeye bir note da ekleyebilirsiniz (en fazla 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")

Bir öğe koleksiyonda zaten varsa (aynı item_id/item_type çifti), bir HTTP 409 hatası oluşturulur. Bu hatayı yok saymayı seçebilirsiniz; bunun için exists_ok=True değerini ayarlayın.

Mevcut bir öğeye not ekleyin

update_collection_item() kullanarak mevcut bir öğeyi düzenleyebilir ve ona ekli olan notu ekleyebilir veya değiştirebilirsiniz. Yukarıdaki örneği yeniden kullanalım:

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

Öğeleri yeniden sırala

Bir koleksiyondaki öğeler sıralıdır. Sıra, her öğenin position özniteliği tarafından belirlenir. Varsayılan olarak, yeni öğeler koleksiyonun sonuna eklenerek sıralama yapılır. Sırayı, bir not eklediğiniz gibi update_collection_item() kullanarak güncelleyebilirsiniz.

Yukarıdaki örneğimizi yeniden kullanalım:

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

Öğeleri kaldır

Son olarak, bir öğeyi delete_collection_item() kullanarak da kaldırabilirsiniz.

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

Koleksiyonu sil

Bir koleksiyon, delete_collection() kullanılarak silinebilir.

Bu geri alınamaz bir eylemdir. Silinen bir koleksiyon geri yüklenemez.

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