集合

集合是 Hub 上相關專案（模型、資料集、Space、論文）的 agrupation，它們在同一頁面上進行組織。集合對於建立自己的作品集、按類別新增書籤或展示您想共享的專案列表非常有用。請檢視此指南，以更詳細地瞭解集合是什麼以及它們在 Hub 上的樣子。

您可以直接在瀏覽器中管理集合，但在本指南中，我們將重點介紹如何以程式設計方式管理它們。

獲取一個集合

使用 get_collection() 來獲取你的集合或任何公開的集合。你必須知道集合的slug才能檢索集合。Slug 是一個基於標題和唯一 ID 的集合識別符號。你可以在集合頁面的 URL 中找到 slug。

讓我們獲取 slug 為 "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
)

由 get_collection() 返回的 Collection 物件包含

高階元資料：slug、owner、title、description 等。
一個 CollectionItem 物件列表；每個專案代表一個模型、一個數據集、一個 Space 或一篇論文。

所有集合專案都保證擁有

一個唯一的 item_object_id：這是資料庫中集合專案的 ID
一個 item_id：這是底層專案（模型、資料集、Space、論文）在 Hub 上的 ID；它不一定是唯一的，只有 item_id/item_type 對才是唯一的
一個 item_type：model、dataset、Space、paper
專案在集合中的 position，可以更新以重新組織你的集合（參見下面的 update_collection_item()）

還可以為專案附加一個 note。這對於新增有關專案的附加資訊（評論、部落格文章連結等）很有用。如果專案沒有 note，該屬性仍為 None 值。

除了這些基本屬性外，返回的專案還可以根據其型別擁有附加屬性：author、private、lastModified、gated、title、likes、upvotes 等。不保證返回這些屬性。

列出集合

我們也可以使用 list_collections() 來獲取集合。集合可以使用一些引數進行過濾。讓我們列出使用者 teknium 的所有集合。

>>> from huggingface_hub import list_collections

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

這將返回一個 Collection 物件的可迭代物件。我們可以迭代它們來列印，例如，每個集合的獲贊數量。

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

在列出集合時，每個集合的專案列表將被截斷為最多 4 項。要檢索集合中的所有專案，您必須使用 get_collection()。

可以進行更高階的過濾。讓我們獲取所有包含模型 TheBloke/OpenHermes-2.5-Mistral-7B-GGUF 的集合，按熱門程度排序，並將計數限制為 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

引數 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"

更多詳情，請查閱 list_collections() 參考。

建立一個新集合

既然我們知道如何獲取 Collection，讓我們建立自己的！使用 create_collection() 配合標題和描述。要在組織頁面上建立集合，在建立集合時傳遞 namespace="my-cool-org"。最後，您還可以透過傳遞 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",
... )

它將返回一個具有高階元資料（標題、描述、所有者等）和空專案列表的 Collection 物件。您現在可以使用其 slug 來引用此集合。

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

管理集合中的專案

現在我們有了一個 Collection，我們想往裡面新增專案並進行組織。

新增專案

專案必須一個一個地使用 add_collection_item() 新增。你只需要知道 collection_slug、item_id 和 item_type。可選地，你也可以為專案新增一個 note（最多 500 個字元）。

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

如果一個專案已存在於集合中（相同的 item_id/item_type 對），將引發 HTTP 409 錯誤。你可以透過設定 exists_ok=True 來選擇忽略此錯誤。

為現有專案新增備註

您可以使用 update_collection_item() 修改現有專案以新增或修改附加到它的備註。讓我們重用上面的例子

>>> 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() 以與新增備註相同的方式更新順序。

讓我們重用上面的例子

>>> 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() 刪除一個專案。

>>> 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() 刪除一個集合。

這是一個不可逆的操作。刪除的集合無法恢復。

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

在 GitHub 上更新

Hub Python 庫

集合