Коллекции

Коллекция — это группа связанных элементов на Hub (модели, наборы данных, Spaces, статьи, коллекции, buckets), объединённых на одной странице. Коллекции полезны для создания собственного портфолио, категоризации закладок или представления отобранного списка элементов, которыми вы хотите поделиться. Ознакомьтесь с этим руководством, чтобы подробнее узнать, что такое коллекции и как они выглядят на Hub.

Вы можете управлять коллекциями непосредственно в браузере, однако в этом руководстве мы сосредоточимся на программном управлении.

Получить коллекцию

Используйте get_collection(), чтобы получить ваши коллекции или любые публичные. Для получения коллекции необходимо знать её slug. Slug — это идентификатор коллекции, основанный на заголовке и уникальном ID. Slug можно найти в URL страницы коллекции.

Получим коллекцию с помощью "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
)

Объект Collection, возвращаемый get_collection(), содержит:

• высокоуровневые метаданные: slug, owner, title, description и т. д.
• список объектов CollectionItem; каждый элемент представляет модель, набор данных, Space, статью, коллекцию или bucket.

Все элементы коллекции гарантированно имеют:

• уникальный item_object_id: это идентификатор элемента коллекции в базе данных
• item_id: это идентификатор базового элемента (модели, набора данных, Space, статьи, коллекции, bucket) на Hub; он не обязательно уникален, и уникальной является только пара item_id/item_type
• an item_type: модель, набор данных, Space, статья, коллекция, bucket
• 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)