# 컬렉션

컬렉션은 Hub에서 같은 페이지에 함께 정리된 관련 항목(모델, 데이터셋, Spaces, 논문, 컬렉션, 버킷)의 그룹입니다. 컬렉션은 나만의 포트폴리오를 만들거나, 카테고리로 콘텐츠를 북마크하거나, 공유하려는 항목의 큐레이션된 목록을 제시하는 데 유용합니다. 컬렉션이 무엇인지 그리고 Hub에서 어떻게 보이는지 더 자세히 이해하려면 이 [가이드](https://huggingface.co/docs/hub/collections)를 확인해 보세요.

collections은 브라우저에서 직접 관리할 수 있지만, 이 가이드에서는 프로그래밍 방식으로 관리하는 방법에 초점을 맞춥니다.

## 컬렉션 가져오기

[get_collection()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.get_collection)을 사용하여 내 컬렉션 또는 공개 컬렉션을 가져올 수 있습니다. 컬렉션을 가져오려면 해당 컬렉션의 *slug*가 필요합니다. slug는 제목과 고유 ID를 기반으로 한 컬렉션 식별자입니다. 컬렉션 페이지의 URL에서 slug를 확인할 수 있습니다.

    

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

[get_collection()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.get_collection)이 반환하는 [Collection](/docs/huggingface_hub/v2.4.0/ko/package_reference/collections#huggingface_hub.Collection) 객체는 다음을 포함합니다:
- 고급 메타데이터: `slug`, `owner`, `title`, `description` 등
- [CollectionItem](/docs/huggingface_hub/v2.4.0/ko/package_reference/collections#huggingface_hub.CollectionItem) 객체의 목록; 각 항목은 모델, 데이터셋, Space, 논문, 컬렉션 또는 버킷을 나타냅니다.

모든 컬렉션 항목에는 다음이 보장됩니다:
- 고유한 `item_object_id`: 데이터베이스에서 컬렉션 항목의 id입니다
- `item_id`: Hub의 기본 항목(모델, 데이터셋, Space, 논문, 컬렉션, 버킷)의 ID입니다. 반드시 고유하지 않으며, `item_id`/`item_type` 쌍만 고유합니다.
- `item_type`: 모델, 데이터셋, Space, 논문, 컬렉션, 버킷
- 컬렉션에서 항목의 `position`입니다. 이 값을 업데이트하여 컬렉션을 재구성할 수 있습니다(아래의 [update_collection_item()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item) 참조).

`note`도 항목에 첨부할 수 있습니다. 이는 항목에 대한 추가 정보(댓글, 블로그 게시물 링크 등)를 추가하는 데 유용합니다. 항목에 노트가 없으면 해당 속성은 여전히 `None` 값을 가집니다.

이러한 기본 속성 외에도, 반환된 항목은 유형에 따라 `author`, `private`, `lastModified`, `gated`, `title`, `likes`, `upvotes` 등의 추가 속성을 가질 수 있습니다. 이러한 속성 중 어느 것도 반환이 보장되지 않습니다.

## 컬렉션 나열

[list_collections()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.list_collections)를 사용하여 컬렉션도 가져올 수 있습니다. 컬렉션은 일부 매개변수를 사용하여 필터링할 수 있습니다. 사용자 [`teknium`](https://huggingface.co/teknium)의 모든 컬렉션을 나열해 보겠습니다.
```py
>>> from huggingface_hub import list_collections

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

`Collection` 객체의 반복 가능한 객체를 반환합니다. 이를 반복하여 각 컬렉션의 업보트 수를 출력할 수 있습니다.

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

> [!WARNING]
> 컬렉션을 나열할 때, 컬렉션별 항목 목록은 최대 4개 항목으로 잘립니다. 컬렉션의 모든 항목을 가져오려면 [get_collection()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.get_collection)을 사용해야 합니다.

더 고급스러운 필터링도 가능합니다. [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF) 모델을 포함하는 모든 컬렉션을 trending 순으로 정렬하고, 개수를 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
```

`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()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.list_collections) 참고 문서를 확인하세요.

## 새로운 컬렉션 만들기

이제 [Collection](/docs/huggingface_hub/v2.4.0/ko/package_reference/collections#huggingface_hub.Collection)을 가져오는 방법을 알았으니, 직접 만들어 보겠습니다. 제목과 설명을 지정하여 [create_collection()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_collection)을 사용하세요. 조직 페이지에 컬렉션을 만들려면 컬렉션을 생성할 때 `namespace="my-cool-org"`를 전달하세요. 마지막으로, `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",
... )
```

고급 메타데이터(제목, 설명, 소유자 등)와 빈 항목 목록을 가진 [Collection](/docs/huggingface_hub/v2.4.0/ko/package_reference/collections#huggingface_hub.Collection) 객체를 반환합니다. 이제 이 컬렉션을 `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'
```

## 컬렉션의 항목 관리

이제 [Collection](/docs/huggingface_hub/v2.4.0/ko/package_reference/collections#huggingface_hub.Collection)을 만들었으므로, 항목을 추가하고 정리하고 싶습니다.

### 항목 추가

항목은 [add_collection_item()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.add_collection_item)을 사용하여 하나씩 추가해야 합니다. `collection_slug`, `item_id`, `item_type`만 알면 됩니다. 선택적으로 항목에 `note`를 추가할 수도 있습니다(최대 500자).

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

컬렉션에 이미 항목이 존재하는 경우(동일한 `item_id`/`item_type` 쌍), HTTP 409 오류가 발생합니다. `exists_ok=True`를 설정하여 이 오류를 무시하도록 선택할 수 있습니다.

### 기존 항목에 노트 추가

[update_collection_item()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.update_collection_item)를 사용하여 기존 항목을 수정하여 해당 항목에 첨부된 노트를 추가하거나 수정할 수 있습니다. 위의 예제를 다시 사용하겠습니다:

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

### 항목 순서 변경

컬렉션의 항목은 순서가 있습니다. 순서는 각 항목의 `position` 속성에 의해 결정됩니다. 기본적으로 새 항목을 컬렉션의 끝에 추가하여 순서가 정해집니다. 노트를 추가하는 것과 동일한 방식으로 [update_collection_item()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.update_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)

# 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()](/docs/huggingface_hub/v2.4.0/ko/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)
```

## 컬렉션 삭제

컬렉션은 [delete_collection()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.delete_collection)을 사용하여 삭제할 수 있습니다.

> [!WARNING]
> 이 작업은 되돌릴 수 없습니다. 삭제된 컬렉션은 복원할 수 없습니다.

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