Hub Python Library documentation

コレクション

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

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()を使用して1つずつ追加する必要があります。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

←コミュニティタブキャッシュ→