選集 (Collections)

「選集」（Collection）是 Hub 上一組相關項目的集合（包括模型、資料集、Spaces、論文、選集、儲存桶），這些項目被組織在同一個頁面上。選集非常適合用來建立您的個人作品集、將內容按類別加入書籤，或是展示您想要分享的精選列表。請查看此指南，以更詳細地了解選集的定義以及它們在 Hub 上的呈現方式。

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

取得選集 (Fetch a collection)

使用 get_collection() 來取得您的選集或任何公開選集。您必須擁有該選集的 slug 才能擷取它。Slug 是基於標題與唯一 ID 所構成的選集識別碼。您可以在選集頁面的 URL 中找到該 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 物件包含：

高階詮釋資料 (metadata)：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)、選集 (collection)、儲存桶 (bucket)
項目的 position（在選集中的位置），可以透過更新來重新組織您的選集（參閱下方 update_collection_item()）

note（註記）也可以附加到項目上。這對於增加關於項目的額外資訊（如評論、部落格文章連結等）非常有用。如果項目沒有註記，該屬性的值會是 None。

除了這些基礎屬性外，回傳的項目可能根據其類型而擁有額外屬性：author、private、lastModified、gated、title、likes、upvotes 等。但不保證會回傳上述任何屬性。

列出選集 (List collections)

我們也可以使用 list_collections() 來擷取選集。選集可以使用某些參數進行篩選。讓我們列出使用者 teknium 的所有選集。

>>> from huggingface_hub import list_collections

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

這會回傳一個 Collection 物件的可迭代對象。我們可以對它們進行迭代，例如列印出每個選集的按讚數 (upvotes)。

>>> 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 的選集，按熱門程度 (trending) 排序，並將數量限制為 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"
"buckets/namespace/bucket-name"

更多詳細資訊，請查看 list_collections() 的參考文件。

建立新選集 (Create a new collection)

既然我們已經知道如何取得 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'

管理選集中的項目 (Manage items in a collection)

現在我們有了 Collection，我們想要將項目加入其中並進行組織。

新增項目 (Add items)

項目必須使用 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
>>> add_collection_item(collection.slug, item_id="namespace/my-bucket", item_type="bucket")

如果項目已經存在於選集中（相同的 item_id/item_type 組合），將會引發 HTTP 409 錯誤。您可以設定 exists_ok=True 來選擇忽略此錯誤。

為現有項目新增註記 (Add a note to an existing item)

您可以使用 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.",
... )

重新排序項目 (Reorder items)

選集中的項目是有順序的。順序由每個項目的 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,
... )

移除項目 (Remove items)

最後，您也可以使用 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)

可以使用 delete_collection() 刪除選集。

這是一個無法還原的操作。被刪除的選集無法恢復。

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

在 GitHub 上更新

Hub Python 函式庫