Colecciones

Una colección es un grupo de elementos relacionados en el Hub (modelos, conjuntos de datos, Spaces, papers, colecciones, buckets) que se organizan juntos en la misma página. Las colecciones son útiles para crear tu propio portafolio, marcar contenido con marcadores en categorías o presentar una lista curada de elementos que deseas compartir. Consulta esta guía para comprender en más detalle qué son las colecciones y cómo se ven en el Hub.

Puedes gestionar colecciones directamente en el navegador, pero en esta guía nos centraremos en cómo gestionarlas de forma programática.

Obtener una colección

Use get_collection() para obtener tus colecciones o cualquier colección pública. Debes tener el slug de la colección para recuperarla. Un slug es un identificador de una colección basado en el título y un ID único. Puedes encontrar el slug en la URL de la página de la colección.

Obtengamos la colección con "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
)

El objeto Collection devuelto por get_collection() contiene:

metadatos de alto nivel: slug, owner, title, description, etc.
una lista de objetos CollectionItem; cada elemento representa un modelo, un conjunto de datos, un Space, un artículo, una colección o un bucket.

Todos los elementos de la colección están garantizados para tener:

un item_object_id único: este es el identificador del elemento de la colección en la base de datos
un item_id: este es el id en el Hub del elemento subyacente (modelo, conjunto de datos, Space, paper, colección, bucket); no es necesariamente único, y solo el par item_id/item_type es único
un item_type: modelo, conjunto de datos, Space, paper, colección, bucket
la position del elemento en la colección, que se puede actualizar para reorganizar tu colección (ver update_collection_item() a continuación)

Se puede adjuntar una note al elemento. Esto es útil para añadir información adicional sobre el elemento (un comentario, un enlace a una publicación de blog, etc.). El atributo sigue teniendo un valor de None si el elemento no tiene una nota.

Además de estos atributos base, los elementos devueltos pueden tener atributos adicionales según su tipo: author, private, lastModified, gated, title, likes, upvotes, etc. No se garantiza que se devuelva ninguno de estos atributos.

Listar colecciones

También podemos recuperar colecciones usando list_collections(). Las colecciones se pueden filtrar usando algunos parámetros. Enumeremos todas las colecciones del usuario teknium.

>>> from huggingface_hub import list_collections

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

Esto devuelve un iterable de objetos Collection. Podemos iterar sobre ellos para imprimir, por ejemplo, el número de votos a favor de cada colección.

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

Al listar colecciones, la lista de elementos por colección se trunca a un máximo de 4 elementos. Para recuperar todos los elementos de una colección, debe usar get_collection().

Es posible realizar un filtrado más avanzado. Obtengamos todas las colecciones que contienen el modelo TheBloke/OpenHermes-2.5-Mistral-7B-GGUF, ordenadas por tendencia, y limitemos la cantidad a 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

El parámetro sort debe ser uno de "last_modified", "trending" o "upvotes". El parámetro item acepta cualquier elemento en particular. Por ejemplo:

"models/teknium/OpenHermes-2.5-Mistral-7B"
"spaces/julien-c/open-gpt-rhyming-robot"
"datasets/squad"
"papers/2311.12983"
"buckets/namespace/bucket-name"

Para más detalles, consulte la referencia de list_collections().

Crear una nueva colección

Ahora que sabemos cómo obtener una Collection, ¡creemos la nuestra! Usa create_collection() con un título y una descripción. Para crear una colección en la página de una organización, pasa namespace="my-cool-org" al crear la colección. Por último, también puedes crear colecciones privadas pasando 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",
... )

Devolverá un objeto Collection con los metadatos de alto nivel (título, descripción, propietario, etc.) y una lista de elementos vacía. Ahora podrás hacer referencia a esta colección usando su slug.

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

Gestionar elementos en una colección

Ahora que tenemos una Collection, queremos añadir elementos y organizarlos.

Agregar elementos

Los elementos deben agregarse uno por uno usando add_collection_item(). Solo necesitas conocer el collection_slug, el item_id y el item_type. Opcionalmente, también puedes agregar una note al elemento (máximo 500 caracteres).

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

Si un elemento ya existe en una colección (mismo par item_id/item_type), se generará un error HTTP 409. Puede elegir ignorar este error estableciendo exists_ok=True.

Añadir una nota a un elemento existente

Puedes modificar un elemento existente para añadir o modificar la nota adjunta a él usando update_collection_item(). Reutilicemos el ejemplo anterior:

>>> 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.",
... )

Reordenar elementos

Los elementos de una colección están ordenados. El orden lo determina el atributo position de cada elemento. De forma predeterminada, los elementos se ordenan añadiendo los nuevos al final de la colección. Puedes actualizar el orden usando update_collection_item() de la misma manera que añadirías una nota.

Volvamos a usar nuestro ejemplo anterior:

>>> 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,
... )

Eliminar elementos

Finalmente, también puedes eliminar un elemento usando 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)

Eliminar colección

Una colección se puede eliminar usando delete_collection().

Esta es una acción irreversible. Una colección eliminada no se puede restaurar.

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

Update on GitHub

Hub Python Library