Bộ sưu tập

Bộ sưu tập là một nhóm các mục liên quan trên Hub (mô hình, bộ dữ liệu, Spaces, bài báo, bộ sưu tập, buckets) được tổ chức cùng nhau trên cùng một trang. Bộ sưu tập hữu ích để tạo danh mục của riêng bạn, đánh dấu nội dung theo các danh mục, hoặc trình bày một danh sách các mục đã được chọn lọc mà bạn muốn chia sẻ. Xem hướng dẫn này để hiểu chi tiết hơn về bộ sưu tập là gì và chúng trông như thế nào trên Hub.

Bạn có thể quản lý trực tiếp các bộ sưu tập trong trình duyệt, nhưng trong hướng dẫn này, chúng ta sẽ tập trung vào cách quản lý chúng bằng lập trình.

Lấy một bộ sưu tập

Sử dụng get_collection() để lấy các collection của bạn hoặc bất kỳ collection công khai nào. Bạn phải có slug của collection để truy xuất một collection. Slug là định danh cho một collection dựa trên tiêu đề và một ID duy nhất. Bạn có thể tìm slug trong URL của trang collection.

Hãy lấy bộ sưu tập với "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
)

Đối tượng Collection được trả về bởi get_collection() bao gồm:

• metadata cấp cao: slug, owner, title, description, v.v.
• một danh sách các đối tượng CollectionItem; mỗi mục đại diện cho một model, một dataset, một Space, một bài báo, một collection hoặc một bucket.

Tất cả các mục trong bộ sưu tập được đảm bảo có:

• một item_object_id duy nhất: đây là id của mục sưu tập trong cơ sở dữ liệu
• một item_id: đây là id trên Hub của mục cơ bản (mô hình, tập dữ liệu, Space, bài báo, bộ sưu tập, bucket); nó không nhất thiết là duy nhất, và chỉ cặp item_id/item_type mới là duy nhất
• một item_type: model, dataset, Space, paper, collection, bucket
• position của mục trong bộ sưu tập, có thể được cập nhật để sắp xếp lại bộ sưu tập của bạn (xem update_collection_item() bên dưới)

Một note cũng có thể được gắn vào mục. Điều này hữu ích để thêm thông tin bổ sung về mục (một bình luận, một liên kết đến bài đăng trên blog, v.v.). Thuộc tính này vẫn có giá trị None nếu mục không có ghi chú.

Ngoài các thuộc tính cơ bản này, các mục được trả về có thể có thêm các thuộc tính khác tùy thuộc vào loại của chúng: author, private, lastModified, gated, title, likes, upvotes, v.v. Không có thuộc tính nào trong số này được đảm bảo sẽ được trả về.

Liệt kê các bộ sưu tập

Chúng ta cũng có thể lấy các bộ sưu tập bằng cách sử dụng list_collections(). Các bộ sưu tập có thể được lọc bằng một số tham số. Hãy liệt kê tất cả các bộ sưu tập từ người dùng teknium.

>>> from huggingface_hub import list_collections

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

Điều này trả về một đối tượng lặp được của các đối tượng Collection. Chúng ta có thể lặp qua chúng để in ra, chẳng hạn, số lượt bình chọn tích cực cho mỗi collection.

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

Khi liệt kê các bộ sưu tập, danh sách mục trong mỗi bộ sưu tập bị cắt ngắn tối đa 4 mục. Để lấy tất cả các mục từ một bộ sưu tập, bạn phải sử dụng get_collection().

Bạn có thể thực hiện các bộ lọc nâng cao hơn. Hãy lấy tất cả các bộ sưu tập chứa mô hình TheBloke/OpenHermes-2.5-Mistral-7B-GGUF, sắp xếp theo xu hướng và giới hạn số lượng ở mức 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

Tham số sort phải là một trong "last_modified", "trending" hoặc "upvotes". Tham số item chấp nhận bất kỳ mục cụ thể nào. Ví dụ:

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

Để biết thêm chi tiết, hãy xem tài liệu tham khảo của list_collections().

Tạo một bộ sưu tập mới

Bây giờ khi đã biết cách lấy một Collection, hãy tạo của riêng chúng ta! Sử dụng create_collection() với tiêu đề và mô tả. Để tạo một collection trên trang của tổ chức, hãy truyền namespace="my-cool-org" khi tạo collection. Cuối cùng, bạn cũng có thể tạo các collection riêng tư bằng cách truyền 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",
... )

Nó sẽ trả về một đối tượng Collection chứa các siêu dữ liệu cấp cao (tiêu đề, mô tả, chủ sở hữu, v.v.) và một danh sách mục trống. Bạn sẽ có thể tham chiếu đến bộ sưu tập này bằng slug của nó.

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

Quản lý các mục trong một bộ sưu tập

Bây giờ khi đã có một Collection, chúng ta muốn thêm các mục vào và sắp xếp chúng.

Thêm các mục

Các mục phải được thêm vào lần lượt bằng add_collection_item(). Bạn chỉ cần biết collection_slug, item_id và item_type. Tùy chọn, bạn cũng có thể thêm một note cho mục (tối đa 500 ký tự).

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

Nếu một mục đã tồn tại trong bộ sưu tập (cặp item_id/item_type giống nhau), một lỗi HTTP 409 sẽ được phát sinh. Bạn có thể chọn bỏ qua lỗi này bằng cách đặt exists_ok=True.

Thêm ghi chú vào một mục hiện có

Bạn có thể sửa đổi một mục hiện có để thêm hoặc sửa đổi ghi chú đính kèm bằng cách sử dụng update_collection_item(). Hãy tái sử dụng ví dụ ở trên:

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

Sắp xếp lại các mục

Các mục trong một bộ sưu tập được sắp xếp theo thứ tự. Thứ tự này được xác định bởi thuộc tính position của từng mục. Mặc định, các mục được sắp xếp bằng cách thêm các mục mới vào cuối bộ sưu tập. Bạn có thể cập nhật thứ tự bằng cách sử dụng update_collection_item() theo cách tương tự như khi thêm một ghi chú.

Hãy tái sử dụng ví dụ ở trên:

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

Xóa các mục

Cuối cùng, bạn cũng có thể xóa một mục bằng cách sử dụng 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)

Xóa bộ sưu tập

Một bộ sưu tập có thể bị xóa bằng cách sử dụng delete_collection().

Đây là một thao tác không thể hoàn tác. Một bộ sưu tập đã bị xóa không thể được khôi phục.

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