Hugging Face's logo

Hub Python Library documentation

集合

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

集合

集合是 Hub 上一组相关的条目（模型、数据集、Spaces、论文、集合、存储桶），它们被组织在同一页面上。集合可用于创建自己的作品集、按类别收藏内容，或展示您想要分享的精选条目列表。查看此指南以详细了解集合是什么以及它们在 Hub 上的呈现方式。

您可以直接在浏览器中管理集合，但本指南将重点介绍如何通过编程方式对其进行管理。

获取集合

使用 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 对象包含：

  • 高级元数据：slug、owner、title、description 等。
  • CollectionItem 对象的列表；每个对象代表一个模型、数据集、Space、论文、集合或存储桶。

所有集合项均保证具有以下

  • 唯一的 item_object_id：这是数据库中该收藏项的 id
  • item_id：这是 Hub 上底层条目（模型、数据集、Space、论文、集合、存储桶）的 ID；它不一定唯一，只有 item_id/item_type 组合才是唯一的
  • item_type：模型、数据集、Space、论文、合集、存储桶
  • 集合中该项目的position，可以更新此值以重新组织你的集合（参见下文中的update_collection_item()）

还可以为条目附加一个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"
  • "buckets/namespace/bucket-name"

有关更多详细信息，请参阅 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
>>> add_collection_item(collection.slug, item_id="namespace/my-bucket", item_type="bucket")

如果集合中已存在某个条目（具有相同的 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)
Update on GitHub

←社区选项卡 缓存→