# Coleções

Uma coleção é um grupo de itens relacionados no Hub (modelos, conjuntos de dados, Spaces, papers, coleções, buckets) que são organizados juntos na mesma página. Coleções são úteis para criar seu próprio portfólio, marcar conteúdo em categorias ou apresentar uma lista curada de itens que você deseja compartilhar. Confira este [guia](https://huggingface.co/docs/hub/collections) para entender em mais detalhes o que são coleções e como elas aparecem no Hub.

Você pode gerenciar coleções diretamente no navegador, mas, neste guia, focaremos em como gerenciá-las programaticamente.

## Obter uma coleção

Use [get_collection()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.get_collection) para buscar suas coleções ou qualquer uma pública. Você deve ter o *slug* da coleção para recuperá-la. Um slug é um identificador para uma coleção baseado no título e em um ID único. Você pode encontrar o slug na URL da página da coleção.

    

Vamos buscar a coleção com `"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`:

```py
>>> 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
)
```

O objeto [Collection](/docs/huggingface_hub/main/pt/package_reference/collections#huggingface_hub.Collection) retornado por [get_collection()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.get_collection) contém:
- metadados de alto nível: `slug`, `owner`, `title`, `description`, etc.
- uma lista de objetos [CollectionItem](/docs/huggingface_hub/main/pt/package_reference/collections#huggingface_hub.CollectionItem); cada item representa um modelo, um conjunto de dados, um Space, um artigo, uma coleção ou um bucket.

Todos os itens da coleção são garantidos a ter:
- um `item_object_id` único: este é o id do item da coleção no banco de dados
- um `item_id`: este é o id no Hub do item subjacente (modelo, dataset, Space, paper, collection, bucket); ele não é necessariamente único, e apenas o par `item_id`/`item_type` é único
- um `item_type`: modelo, conjunto de dados, Space, artigo, coleção, bucket
- a `position` do item na coleção, que pode ser atualizada para reorganizar sua coleção (veja [update_collection_item()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item) abaixo)

Uma `note` também pode ser anexada ao item. Isso é útil para adicionar informações adicionais sobre o item (um comentário, um link para um post de blog, etc.). O atributo ainda tem um valor `None` se o item não tiver uma nota.

Além desses atributos básicos, os itens retornados podem ter atributos adicionais dependendo do seu tipo: `author`, `private`, `lastModified`, `gated`, `title`, `likes`, `upvotes`, etc. Nenhum desses atributos é garantido a ser retornado.

## Listar coleções

Também podemos recuperar coleções usando [list_collections()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.list_collections). As coleções podem ser filtradas usando alguns parâmetros. Vamos listar todas as coleções do usuário [`teknium`](https://huggingface.co/teknium).
```py
>>> from huggingface_hub import list_collections

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

Isso retorna um iterável de objetos `Collection`. Podemos iterar sobre eles para imprimir, por exemplo, o número de votos positivos de cada coleção.

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

> [!WARNING]
> Ao listar coleções, a lista de itens por coleção é truncada para no máximo 4 itens. Para recuperar todos os itens de uma coleção, você deve usar [get_collection()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.get_collection).

É possível realizar filtragens mais avançadas. Vamos obter todas as coleções que contêm o modelo [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF), ordenadas por tendência, e limitar a contagem para 5.
```py
>>> 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
```

O parâmetro `sort` deve ser um de `"last_modified"`, `"trending"` ou `"upvotes"`. O parâmetro `item` aceita qualquer item específico. Por exemplo:
* `"models/teknium/OpenHermes-2.5-Mistral-7B"`
* `"spaces/julien-c/open-gpt-rhyming-robot"`
* `"datasets/squad"`
* `"papers/2311.12983"`
* `"buckets/namespace/bucket-name"`

Para mais detalhes, consulte a referência de [list_collections()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.list_collections).

## Criar uma nova coleção

Agora que sabemos como obter uma [Collection](/docs/huggingface_hub/main/pt/package_reference/collections#huggingface_hub.Collection), vamos criar a nossa! Use [create_collection()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.create_collection) com um título e uma descrição. Para criar uma coleção em uma página de organização, passe `namespace="my-cool-org"` ao criar a coleção. Por fim, você também pode criar coleções privadas passando `private=True`.

```py
>>> from huggingface_hub import create_collection

>>> collection = create_collection(
...     title="ICCV 2023",
...     description="Portfolio of models, papers and demos I presented at ICCV 2023",
... )
```

Ele retornará um objeto [Collection](/docs/huggingface_hub/main/pt/package_reference/collections#huggingface_hub.Collection) com os metadados de alto nível (título, descrição, proprietário, etc.) e uma lista de itens vazia. Agora você poderá se referir a essa coleção usando seu `slug`.

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

## Gerenciar itens em uma coleção

Agora que temos uma [Collection](/docs/huggingface_hub/main/pt/package_reference/collections#huggingface_hub.Collection), queremos adicionar itens a ela e organizá-los.

### Adicionar itens

Os itens devem ser adicionados um a um usando [add_collection_item()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.add_collection_item). Você só precisa conhecer o `collection_slug`, `item_id` e `item_type`. Opcionalmente, você também pode adicionar uma `note` ao item (máximo de 500 caracteres).

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

Se um item já existir em uma coleção (mesmo par `item_id`/`item_type`), um erro HTTP 409 será lançado. Você pode escolher ignorar esse erro definindo `exists_ok=True`.

### Adicionar uma nota a um item existente

Você pode modificar um item existente para adicionar ou modificar a nota anexada a ele usando [update_collection_item()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item). Vamos reutilizar o exemplo acima:

```py
>>> 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 itens

Os itens de uma coleção são ordenados. A ordem é determinada pelo atributo `position` de cada item. Por padrão, os itens são ordenados ao adicionar novos itens no final da coleção. Você pode atualizar a ordem usando [update_collection_item()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item) da mesma forma que adicionaria uma nota.

Vamos reutilizar nosso exemplo acima:

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

### Remover itens

Por fim, você também pode remover um item usando [delete_collection_item()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.delete_collection_item).

```py
>>> 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)
```

## Excluir coleção

Uma coleção pode ser excluída usando [delete_collection()](/docs/huggingface_hub/main/pt/package_reference/hf_api#huggingface_hub.HfApi.delete_collection).

> [!WARNING]
> Esta é uma ação irreversível. Uma coleção excluída não pode ser restaurada.

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