Hub Python Library documentation

Tạo và quản lý kho

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Tạo và quản lý kho

Hugging Face Hub là một tập hợp các kho git. Git là công cụ được sử dụng rộng rãi trong phát triển phần mềm để dễ dàng quản lý phiên bản dự án khi làm việc hợp tác. Hướng dẫn này sẽ cho bạn thấy cách tương tác với các kho trên Hub, đặc biệt là:

Tạo và xóa một kho lưu trữ.
Quản lý các nhánh và thẻ.
Đổi tên kho lưu trữ của bạn.
Cập nhật mức độ hiển thị của kho lưu trữ của bạn.
Quản lý một bản sao cục bộ của kho lưu trữ của bạn.

Nếu bạn quen làm việc với các nền tảng như GitLab/GitHub/Bitbucket, phản xạ đầu tiên của bạn có thể là sử dụng CLI git để clone kho (git clone), commit các thay đổi (git add, git commit) và push chúng (git push). Cách này hoàn toàn hợp lệ khi sử dụng Hugging Face Hub. Tuy nhiên, kỹ thuật phần mềm và machine learning không chia sẻ cùng các yêu cầu và quy trình làm việc. Các kho model có thể lưu trữ các tệp trọng số model lớn cho nhiều framework và công cụ khác nhau, do đó việc clone kho có thể khiến bạn phải duy trì các thư mục cục bộ có kích thước rất lớn. Kết quả là, việc sử dụng các phương thức HTTP tùy chỉnh của chúng tôi có thể hiệu quả hơn. Bạn có thể đọc trang giải thích Git vs HTTP paradigm của chúng tôi để biết thêm chi tiết.

Nếu bạn muốn tạo và quản lý một kho lưu trữ trên Hub, máy của bạn phải đã đăng nhập. Nếu chưa, vui lòng tham khảo mục này. Trong phần còn lại của hướng dẫn này, chúng tôi giả định rằng máy của bạn đã đăng nhập.

Danh sách các kho của bạn

Bạn có thể liệt kê tất cả các kho (mô hình, bộ dữ liệu, spaces và buckets) cho tài khoản hoặc tổ chức của mình bằng cách sử dụng list_user_repos(). Kết quả bao gồm thông tin lưu trữ và được sắp xếp theo mức sử dụng lưu trữ.

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

Hoặc qua CLI (hiển thị 30 kho lưu trữ theo mặc định, dùng --limit 0 để liệt kê tất cả):

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

Tạo và xóa kho

Bước đầu tiên là biết cách tạo và xóa kho lưu trữ. Bạn chỉ có thể quản lý các kho lưu trữ do bạn sở hữu (trong không gian tên của tên người dùng của bạn) hoặc từ các tổ chức mà bạn có quyền ghi.

Tạo một kho lưu trữ

Tạo một kho trống bằng create_repo() và đặt tên cho nó bằng tham số repo_id. repo_id là không gian tên của bạn theo sau là tên kho: username_or_org/repo_name.

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'

Hoặc qua CLI:

>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model

Mặc định, create_repo() tạo một kho lưu trữ mô hình. Nhưng bạn có thể sử dụng tham số repo_type để chỉ định một loại kho lưu trữ khác. Ví dụ, nếu bạn muốn tạo một kho lưu trữ bộ dữ liệu:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

Hoặc qua CLI:

>>> hf repos create lysandre/test-dataset --repo-type dataset

Khi bạn tạo một kho lưu trữ, bạn có thể đặt mức độ hiển thị của kho lưu trữ bằng tham số visibility:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

Hoặc qua CLI:

>>> hf repos create lysandre/test-private --private

Nếu bạn muốn thay đổi mức độ hiển thị của kho lưu trữ vào thời điểm sau, bạn có thể sử dụng hàm update_repo_settings().

Nếu bạn thuộc một tổ chức có gói Enterprise, bạn có thể tạo một repo trong một nhóm tài nguyên cụ thể bằng cách truyền resource_group_id làm tham số cho create_repo(). Nhóm tài nguyên là một tính năng bảo mật để kiểm soát thành viên nào trong tổ chức của bạn có thể truy cập một tài nguyên nhất định. Bạn có thể lấy ID của nhóm tài nguyên bằng cách sao chép nó từ URL của trang cài đặt tổ chức trên Hub (ví dụ: "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). Để biết thêm chi tiết về nhóm tài nguyên, hãy xem hướng dẫn này.

Bạn cũng có thể tạo một kho trong một khu vực cloud cụ thể bằng cách truyền region làm tham số:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

Xóa một kho

Xóa một kho bằng delete_repo(). Hãy chắc chắn rằng bạn muốn xóa kho vì đây là một quá trình không thể đảo ngược!

Chỉ định repo_id của kho bạn muốn xóa:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

Truyền missing_ok=True để bỏ qua lệnh gọi một cách im lặng nếu kho lưu trữ không tồn tại:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

Hoặc qua CLI:

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

Nhân bản một kho lưu trữ

Trong một số trường hợp, bạn muốn sao chép repo của người khác để điều chỉnh cho phù hợp với use case của mình. Điều này có thể thực hiện bằng phương thức duplicate_repo(). Phương thức này sẽ sao chép toàn bộ repository, giữ nguyên lịch sử git đầy đủ. Cách này hoạt động với models, datasets và Spaces. Đối với Spaces, bạn vẫn cần cấu hình các cài đặt riêng của mình (hardware, sleep-time, storage, variables và secrets). Xem hướng dẫn Quản lý Space của bạn để biết thêm chi tiết.

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

Tương tự create_repo(), duplicate_repo() nhận một resource_group_id để tạo bản sao trực tiếp bên trong một nhóm tài nguyên của tổ chức Enterprise của bạn (--resource-group-id với hf repos duplicate).

Lịch sử git được sao chép ngay lập tức, nhưng các tệp LFS/Xet có thể vẫn đang được sao chép ở chế độ nền sau khi duplicate_repo() trả về. Cho đến khi quá trình sao chép hoàn tất, việc tải xuống các tệp này từ kho mới có thể thất bại. Kiểm tra files_copy_pending trên giá trị trả về để biết liệu quá trình sao chép có đang diễn ra hay không:

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

Tìm kiếm Spaces

Hub cung cấp API tìm kiếm ngữ nghĩa để khám phá các Spaces. Bạn có thể tìm kiếm bằng các truy vấn ngôn ngữ tự nhiên bằng search_spaces():

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

Để biết thêm chi tiết và các tùy chọn lọc, hãy xem hướng dẫn Quản lý Spaces của bạn.

Tải lên và tải xuống tệp

Bây giờ bạn đã tạo xong kho lưu trữ, bạn sẽ quan tâm đến việc đẩy các thay đổi lên và tải các tệp từ kho đó xuống.

Hai chủ đề này xứng đáng có các hướng dẫn riêng. Vui lòng tham khảo hướng dẫn upload và download để tìm hiểu cách sử dụng kho lưu trữ của bạn.

Sao chép tệp

Sử dụng copy_files() để sao chép các tệp đã được lưu trữ trên Hub từ kho này sang kho khác (hoặc ngay trong cùng một kho) mà không cần tải xuống và tải lên lại. Hỗ trợ cả tệp riêng lẻ và toàn bộ thư mục, và các tệp được theo dõi bằng Xet hoặc LFS sẽ được sao chép phía máy chủ theo hash.

>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

Hoặc qua CLI, với lệnh hf cp thống nhất (cũng có sẵn dưới dạng hf repos cp):

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

copy_files (và hf cp) cũng có thể sao chép tệp từ một kho lưu trữ sang Bucket. Việc sao chép từ bucket sang kho lưu trữ không được hỗ trợ. Xem hướng dẫn Buckets để biết thêm chi tiết.

Các bản sao phía máy chủ chỉ hoạt động trong cùng một khu vực lưu trữ.

Nhánh và thẻ

Các kho Git thường sử dụng các nhánh (branches) để lưu trữ các phiên bản khác nhau của cùng một kho. Các thẻ (tags) cũng có thể được dùng để đánh dấu một trạng thái cụ thể của kho của bạn, chẳng hạn như khi phát hành một phiên bản. Nói chung, các nhánh và thẻ được gọi là git references.

Tạo nhánh và thẻ

Bạn có thể tạo nhánh và thẻ mới bằng cách sử dụng create_branch() và create_tag():

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

Hoặc qua CLI:

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

Bạn có thể sử dụng các hàm delete_branch() và delete_tag() theo cách tương tự để xóa một nhánh hoặc một thẻ, hoặc lần lượt sử dụng hf repos branch delete và hf repos tag delete trong CLI.

Liệt kê tất cả các nhánh và thẻ

Bạn cũng có thể liệt kê các git refs hiện có từ một kho lưu trữ bằng cách sử dụng list_repo_refs():

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

Thay đổi cài đặt kho

Các kho (repository) đi kèm với một số cài đặt mà bạn có thể cấu hình. Phần lớn thời gian, bạn sẽ muốn thực hiện điều đó thủ công trên trang cài đặt của kho trong trình duyệt. Bạn phải có quyền ghi vào kho để cấu hình nó (hoặc sở hữu kho hoặc là thành viên của một tổ chức). Trong phần này, chúng ta sẽ xem xét các cài đặt mà bạn cũng có thể cấu hình bằng cách lập trình sử dụng huggingface_hub.

Một số cài đặt chỉ áp dụng cho Spaces (phần cứng, biến môi trường,…). Để cấu hình những cài đặt này, vui lòng tham khảo hướng dẫn Quản lý Spaces của bạn.

Cập nhật khả năng hiển thị

Một kho lưu trữ có thể là công khai hoặc riêng tư. Kho lưu trữ riêng tư chỉ hiển thị cho bạn hoặc các thành viên của tổ chức mà kho lưu trữ đó nằm trong. Chuyển đổi kho lưu trữ sang riêng tư như minh họa dưới đây:

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

Hoặc qua CLI:

>>> hf repos settings lysandre/test-private --private true

Cài đặt quyền truy cập có kiểm soát

Để cung cấp nhiều quyền kiểm soát hơn về cách các repo được sử dụng, Hub cho phép tác giả repo bật yêu cầu truy cập cho repo của họ. Khi được bật, người dùng phải đồng ý chia sẻ thông tin liên hệ (tên người dùng và địa chỉ email) với tác giả repo để truy cập các tệp. Một repo có bật yêu cầu truy cập được gọi là repo có cổng.

Bạn có thể đặt một kho lưu trữ là có kiểm soát bằng cách sử dụng update_repo_settings():

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

Hoặc qua CLI:

>>> hf repos settings lysandre/test-private --gated auto

Đổi tên kho lưu trữ của bạn

Bạn có thể đổi tên kho của mình trên Hub bằng move_repo(). Sử dụng phương thức này, bạn cũng có thể di chuyển kho từ một người dùng sang một tổ chức. Khi thực hiện, có một vài hạn chế mà bạn nên lưu ý. Ví dụ, bạn không thể chuyển kho của mình sang một người dùng khác.

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

Hoặc qua CLI:

>>> hf repos move Wauplin/cool-model huggingface/cool-model

Các kho lưu trữ Kernel

Hub hỗ trợ loại kho "kernel" để lưu trữ các kernel tính toán. Đây không phải là loại kho tương thích hoàn toàn. Chỉ một tập hợp các phương thức hạn chế đã được kiểm thử và được hỗ trợ chính thức:

Lưu ý rằng create_repo() và delete_repo() cũng tương thích nhưng bị giới hạn trong một tập con nhỏ các người dùng và tổ chức được phép trên Hub.

Để xây dựng, phát hành và sử dụng các kho kernel, vui lòng sử dụng gói kernels chuyên dụng. Tham khảo tài liệu Kernels để biết thêm chi tiết.

Update on GitHub

←HfFileSystem Tìm kiếm→