Hub Python Library documentation

Các nhóm

Hub Python Library

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).

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

Các nhóm

Buckets cung cấp lưu trữ đối tượng kiểu S3 trên Hugging Face, được hỗ trợ bởi backend lưu trữ Xet. Khác với các repository (dựa trên git và theo dõi lịch sử tệp), buckets là các container lưu trữ đối tượng từ xa được thiết kế cho các tệp quy mô lớn với tính năng khử trùng lặp dựa trên địa chỉ nội dung. Chúng được thiết kế cho các trường hợp sử dụng cần lưu trữ đơn giản, nhanh và có thể thay đổi, chẳng hạn như lưu trữ checkpoint huấn luyện, log, các sản phẩm trung gian, hoặc bất kỳ bộ sưu tập tệp lớn nào không cần kiểm soát phiên bản.

Bạn có thể tương tác với bucket bằng API Python (HfApi) hoặc CLI (hf buckets). Trong hướng dẫn này, chúng ta sẽ đi qua tất cả các thao tác khả dụng.

Tất cả các lệnh CLI đều có sẵn dưới hf buckets <command>. Chạy hf buckets --help để tìm hiểu thêm.

Tạo và quản lý các bucket

Tạo một bucket

Tạo một bucket bằng create_bucket(). Bạn cần cung cấp tên bucket. Nếu không chỉ định namespace, bucket sẽ được tạo dưới tên người dùng của bạn.

>>> from huggingface_hub import create_bucket

# Create a bucket under your namespace
>>> url = create_bucket("my-bucket")
>>> url.bucket_id
'username/my-bucket'
>>> url.uri.to_uri()
'hf://buckets/username/my-bucket'

# Create a private bucket
>>> create_bucket("my-private-bucket", private=True)
BucketUrl(...)

# Don't error if bucket already exists
>>> create_bucket("my-bucket", exist_ok=True)
BucketUrl(...)

# Create a bucket in a specific region
>>> create_bucket("my-bucket", region="us")
BucketUrl(...)

Hoặc qua CLI:

>>> hf buckets create my-bucket
✓ Bucket created
  uri: hf://buckets/Wauplin/my-bucket
  url: https://huggingface.co/buckets/Wauplin/my-bucket

# Create a private bucket
>>> hf buckets create my-bucket --private

# Don't error if bucket already exists
>>> hf buckets create my-bucket --exist-ok

# Create a bucket in a specific region
>>> hf buckets create my-bucket --region us

Bạn cũng có thể chỉ định định dạng đầy đủ namespace/bucket_name để tạo một bucket dưới một tổ chức:

>>> from huggingface_hub import create_bucket
>>> create_bucket("my-org/shared-bucket")

Hoặc qua CLI:

>>> hf buckets create my-org/shared-bucket

Lấy thông tin bucket

Sử dụng bucket_info() để lấy thông tin mô tả về một bucket, bao gồm mức độ hiển thị, tổng dung lượng, số lượng tệp và ngày tạo.

>>> from huggingface_hub import bucket_info
>>> bucket_info("username/my-bucket")
BucketInfo(
  id='username/my-bucket',
  private=False,
  created_at=datetime.datetime(2026, 2, 12, 17, 42, 12,
  tzinfo=datetime.timezone.utc),
  size=8411791508,
  total_files=128
)

Hoặc qua CLI:

# JSON output
>>> hf buckets info username/my-bucket
{
  "id": "username/my-bucket",
  "private": false,
  ...
}

Liệt kê các bucket

Sử dụng list_buckets() để liệt kê tất cả các bucket trong một namespace. Mặc định, nó liệt kê các bucket trong namespace của người dùng hiện tại.

>>> from huggingface_hub import list_buckets

# List your own buckets
>>> for bucket in list_buckets():
...     print(bucket.id, bucket.size, bucket.total_files)

# List buckets in an organization
>>> for bucket in list_buckets(namespace="huggingface"):
...     print(bucket.id)

Hoặc qua CLI (hf buckets ls là cách viết tắt của hf buckets list):

# Table format (default)
>>> hf buckets list
ID                   PRIVATE      SIZE TOTAL_FILES CREATED_AT
-------------------- ------- --------- ----------- ----------
username/my-bucket                  32           5 2026-02-16
username/checkpoints         117609095         700 2026-02-13
username/logs                321757477        2000 2026-02-13

# Human-readable sizes
>>> hf buckets list -h
ID                   PRIVATE     SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket               32 B           5 2026-02-16
username/checkpoints         117.6 MB         700 2026-02-13
username/logs                321.8 MB        2000 2026-02-13

# List buckets in a specific namespace
>>> hf buckets ls huggingface

# Filter buckets by name
>>> hf buckets list --search "checkpoint"

Bạn cũng có thể lọc các bucket theo tên bằng cách sử dụng search:

>>> for bucket in list_buckets(search="checkpoint"):
...     print(bucket.id)

Bạn có thể sử dụng các tùy chọn --quiet và --format json để nhận được các định dạng đầu ra khác nhau. Điều này đặc biệt hữu ích nếu bạn muốn chuyển tiếp (pipe) đầu ra sang một công cụ khác như grep hoặc jq.

# Quiet mode: prints one bucket ID per line
>>> hf buckets list --quiet
username/my-bucket
username/checkpoints
username/logs

# JSON format
>>> hf buckets list --format json
[
  {
    "id": "username/my-bucket",
    "private": false,
    "created_at": "2026-02-16T15:28:32+00:00",
    "size": 32,
    "total_files": 5
  },
  ...
]

Thay đổi khả năng hiển thị của bucket

Sử dụng update_bucket_settings() để chuyển đổi một bucket hiện có giữa chế độ riêng tư và công khai.

>>> from huggingface_hub import update_bucket_settings

# Make a bucket private
>>> update_bucket_settings("username/my-bucket", private=True)

# Make it public again
>>> update_bucket_settings("username/my-bucket", private=False)

Hoặc qua CLI:

# Make a bucket private
>>> hf buckets settings username/my-bucket --private
✓ Bucket settings updated
  bucket_id: username/my-bucket
  private: True

# Make it public again
>>> hf buckets settings username/my-bucket --public

Xóa một bucket

Sử dụng delete_bucket() để xóa một bucket. Thao tác này không thể hoàn tác.

>>> from huggingface_hub import delete_bucket
>>> delete_bucket("username/my-bucket")

# Don't error if bucket doesn't exist
>>> delete_bucket("username/my-bucket", missing_ok=True)

Hoặc qua CLI:

# Prompts for confirmation
>>> hf buckets delete username/my-bucket

# Skip confirmation
>>> hf buckets delete username/my-bucket --yes

# Don't error if bucket doesn't exist
>>> hf buckets delete username/my-bucket --yes --missing-ok

Xóa tệp

Sử dụng batch_bucket_files() với tham số delete để xóa các tệp khỏi bucket:

>>> from huggingface_hub import batch_bucket_files

# Delete specific files
>>> batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"])

Hoặc qua CLI bằng hf buckets rm (hoặc hf buckets remove):

# Remove a single file
>>> hf buckets rm username/my-bucket/old-model.bin

# Remove all files under a prefix (requires --recursive)
>>> hf buckets rm username/my-bucket/logs/ --recursive

# Remove only files matching a pattern across the entire bucket
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"

# Exclude specific files from removal
>>> hf buckets rm username/my-bucket/data/ --recursive --exclude "*.safetensors"

# Preview what would be deleted
>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run

Di chuyển một bucket

Sử dụng move_bucket() để di chuyển hoặc đổi tên một bucket. Bạn có thể đổi tên trong cùng một namespace hoặc chuyển sang một namespace khác (người dùng hoặc tổ chức).

>>> from huggingface_hub import move_bucket

# Rename a bucket
>>> move_bucket(from_id="username/old-name", to_id="username/new-name")

# Transfer to an organization
>>> move_bucket(from_id="username/my-bucket", to_id="my-org/my-bucket")

Hoặc qua CLI:

# Rename a bucket
>>> hf buckets move username/old-bucket username/new-bucket

# Transfer to an organization
>>> hf buckets move username/my-bucket my-org/my-bucket

# Using the hf://buckets/ format
>>> hf buckets move hf://buckets/username/old-bucket hf://buckets/username/new-bucket

Để biết thêm thông tin về việc di chuyển kho lưu trữ và bucket, hãy xem tài liệu Hub.

Xem nội dung bucket

Liệt kê tệp

Sử dụng list_bucket_tree() để liệt kê các tệp và thư mục trong một bucket.

>>> from huggingface_hub import list_bucket_tree

# List all files
>>> for item in list_bucket_tree("username/my-bucket"):
...     print(item.path, item.size)
file.txt 5
big.bin 2048
sub/nested.txt 14
sub/deep/file.txt 4

# List top-level entries only
>>> for item in list_bucket_tree("username/my-bucket", recursive=False):
...     print(item.type, item.path)
file file.txt
file big.bin
directory sub

# Filter by prefix
>>> for item in list_bucket_tree("username/my-bucket", prefix="sub"):
...     print(item.path)

Hoặc thông qua CLI, với hỗ trợ cho các định dạng bảng, dễ đọc cho con người và cây ASCII. Mặc định, CLI không đệ quy.

# Default table format (non-recursive, directories shown as entries)
>>> hf buckets list username/my-bucket
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
              2026-01-15 10:30:00  sub/

# Recursive listing (all files, including nested)
>>> hf buckets list username/my-bucket -R
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
          14  2026-01-15 10:30:00  sub/nested.txt
           4  2026-01-15 10:30:00  sub/deep/file.txt

# Human-readable sizes and short dates
>>> hf buckets list username/my-bucket -R -h
      2.0 KB         Jan 15 10:30  big.bin
         5 B         Jan 15 10:30  file.txt
        14 B         Jan 15 10:30  sub/nested.txt
         4 B         Jan 15 10:30  sub/deep/file.txt

# ASCII tree format
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB  Jan 15 10:30  ├── big.bin
   5 B  Jan 15 10:30  ├── file.txt
                      └── sub/
                          ├── deep/
   4 B  Jan 15 10:30  │       └── file.txt
  14 B  Jan 15 10:30  └── nested.txt

# Tree structure only (no sizes/dates)
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
    ├── deep/
    │   └── file.txt
    └── nested.txt

# Quiet mode: one path per line
>>> hf buckets list username/my-bucket -q
big.bin
file.txt
sub/

# Filter by prefix
>>> hf buckets list username/my-bucket/sub -R

Lệnh hf buckets list chấp nhận cả định dạng ngắn (username/my-bucket/sub) và handle đầy đủ (hf://buckets/username/my-bucket/sub) dưới dạng đối số.

Việc liệt kê một bucket bằng HfFileSystem sẽ lưu kết quả vào bộ nhớ đệm. Truyền HfFileSystem(live_follow=True) để các danh sách được làm mới khi các tệp được thêm, cập nhật và xóa trong bucket bởi các peer khác, xem hướng dẫn về hệ thống tệp.

Tải tệp lên

Tải lên bằng Python

Sử dụng batch_bucket_files() để tải tệp lên bucket. Bạn có thể tải lên từ đường dẫn tệp cục bộ hoặc từ các byte thô:

>>> from huggingface_hub import batch_bucket_files

# Upload from local file paths
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         ("./model.safetensors", "models/model.safetensors"),
...         ("./config.json", "models/config.json"),
...     ],
... )

# Upload from raw bytes
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         (b'{"key": "value"}', "config.json"),
...     ],
... )

Bạn cũng có thể sao chép các tệp xet từ một bucket hoặc repository khác bằng cách sử dụng tham số copy. Đây là một thao tác phía máy chủ — không có dữ liệu nào được tải xuống hoặc tải lên lại:

# Copy files by xet hash (source_repo_type, source_repo_id, xet_hash, destination)
>>> batch_bucket_files(
...     "username/my-bucket",
...     copy=[
...         ("bucket", "username/source-bucket", "<xethash_1>", "models/model.safetensors"),
...         ("model", "username/my-model", "<xethash_2>", "models/config.safetensors"),
...     ],
... )

Xet hashes có thể được lấy bằng cách sử dụng list_repo_tree.

Bạn cũng có thể xóa các tệp trong khi đang tải lên các tệp khác.

# Upload and delete in one batch
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[("./new-model.safetensors", "model.safetensors")],
...     delete=["old-model.bin"],
... )

Các lời gọi đến batch_bucket_files() không mang tính giao dịch. Nếu xảy ra lỗi trong quá trình, một số tệp có thể đã được tải lên, sao chép hoặc xóa trong khi các tệp khác thì chưa. Khi máy chủ báo cáo rằng một số thao tác đã thất bại, một BucketBatchError sẽ được ném ra với các đường dẫn thất bại nằm trong thuộc tính failures của nó.

Tải lên một tệp duy nhất bằng CLI

Sử dụng hf buckets cp để tải lên một tệp duy nhất:

hf buckets cp là một alias cho lệnh hf cp thống nhất (cũng được hiển thị dưới dạng hf repos cp). Cả ba đều giống hệt nhau, do đó mọi ví dụ hf buckets cp bên dưới cũng hoạt động với hf cp.

# Upload to bucket root (uses local filename as remote name)
>>> hf buckets cp ./config.json hf://buckets/username/my-bucket

# Upload to a subdirectory
>>> hf buckets cp ./data.csv hf://buckets/username/my-bucket/logs/

# Upload with a different remote filename
>>> hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/v2/model.safetensors

Bạn cũng có thể chuyển kết quả của một lệnh trực tiếp vào một tệp mới bằng cách sử dụng -:

# Upload from stdin
>>> echo "hello" | hf buckets cp - hf://buckets/username/my-bucket/hello.txt
>>> cat model.safetensors | hf buckets cp - hf://buckets/username/my-bucket/model.safetensors

Tải lên một thư mục bằng CLI

Sử dụng hf buckets sync để tải lên toàn bộ một thư mục cục bộ vào một bucket:

# Upload a local directory to a bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket

# Upload to a specific prefix in the bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket/train

Xem phần Đồng bộ hóa thư mục bên dưới để biết đầy đủ các tùy chọn đồng bộ hóa.

Tải xuống các tệp

Tải xuống bằng Python

Sử dụng download_bucket_files() để tải các tệp từ một bucket:

>>> from huggingface_hub import download_bucket_files

# Download specific files by path
>>> download_bucket_files(
...     "username/my-bucket",
...     files=[
...         ("models/model.safetensors", "./local/model.safetensors"),
...         ("config.json", "./local/config.json"),
...     ],
... )

Để đạt hiệu suất tốt hơn, bạn có thể truyền các đối tượng BucketFile nhận được từ list_bucket_tree() thay vì các đường dẫn chuỗi. Điều này bỏ qua bước lấy metadata:

>>> from huggingface_hub import list_bucket_tree, download_bucket_files

# List and filter files, then download
>>> parquet_files = [
...     item for item in list_bucket_tree("username/my-bucket", recursive=True)
...     if item.type == "file" and item.path.endswith(".parquet")
... ]
>>> download_bucket_files(
...     "username/my-bucket",
...     files=[(f, f"./local/{f.path}") for f in parquet_files],
... )

Tải xuống một tệp duy nhất bằng CLI

Sử dụng hf buckets cp để tải xuống một tệp duy nhất:

# Download to a specific file
>>> hf buckets cp hf://buckets/username/my-bucket/config.json ./config.json

# Download to a directory (uses original filename)
>>> hf buckets cp hf://buckets/username/my-bucket/config.json ./data/

# Download to current directory (omit destination)
>>> hf buckets cp hf://buckets/username/my-bucket/config.json

Bạn cũng có thể đưa nội dung của một tệp trực tiếp vào stdout bằng cách sử dụng -:

# Download to stdout and pretty-print with jq
>>> hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .

Tải xuống một thư mục bằng CLI

Sử dụng hf buckets sync để tải xuống tất cả các tệp từ một bucket vào một thư mục cục bộ:

# Download bucket contents to a local directory
>>> hf buckets sync hf://buckets/username/my-bucket ./data

# Download only a specific prefix
>>> hf buckets sync hf://buckets/username/my-bucket/models ./local-models

Xem phần Đồng bộ hóa thư mục bên dưới để biết đầy đủ các tùy chọn đồng bộ hóa.

Sao chép tệp vào Bucket

Sử dụng copy_files() để sao chép các tệp đã được lưu trữ trên Hub sang một Bucket:

>>> from huggingface_hub import copy_files

# Bucket to bucket (same or different bucket)
>>> copy_files(
...     "hf://buckets/username/source-bucket/checkpoints/model.safetensors",
...     "hf://buckets/username/destination-bucket/archive/model.safetensors",
... )

# Repo to bucket
>>> copy_files(
...     "hf://datasets/username/my-dataset/processed/",
...     "hf://buckets/username/my-bucket/datasets/processed/",
... )

Tương tự, bạn có thể thực hiện từ CLI thông qua lệnh thống nhất hf cp (cũng được hiển thị dưới dạng hf buckets cp và hf repos cp — cả ba đều giống hệt nhau):

# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/destination-bucket/logs/

# Repo to bucket
>>> hf cp hf://username/my-model/config.json hf://buckets/username/my-bucket/models/config.json

Khi sao chép thư mục, dấu / ở cuối nguồn sử dụng ngữ nghĩa kiểu rsync — chỉ nội dung của thư mục được sao chép, không lồng ghép chính thư mục đó:

# Without trailing slash: "logs" dir is nested => destination/logs/...
>>> hf cp hf://buckets/username/source-bucket/logs hf://buckets/username/destination-bucket/

# With trailing slash: only contents of "logs" are copied => destination/...
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/destination-bucket/

Ghi chú:

Chưa hỗ trợ sao chép từ bucket sang repo.
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ữ.
Các tệp được theo dõi bằng Xet (trong các bucket hoặc repos) được sao chép phía máy chủ theo hash — không có dữ liệu nào được tải xuống hoặc tải lên lại.
Các tệp văn bản nhỏ không được theo dõi bằng Xet trong nguồn của kho sẽ được tải xuống và tải lên lại lên bucket đích.
copy_files() cũng có thể được sử dụng để sao chép giữa các kho. Xem hướng dẫn kho để biết thêm chi tiết.

Đồng bộ hóa các thư mục

Lệnh hf buckets sync (và tương đương API của nó là sync_bucket()) là cách mạnh mẽ nhất để chuyển tệp giữa một thư mục cục bộ và một bucket. Lệnh này so sánh nguồn và đích, và chỉ chuyển các tệp đã bị thay đổi.

Đồng bộ cơ bản

# Upload: local directory -> bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket

# Download: bucket -> local directory
>>> hf buckets sync hf://buckets/username/my-bucket ./data

hf sync là một alias tiện lợi cho hf buckets sync. Cả hai lệnh đều giống hệt nhau.
>>> hf sync ./data hf://buckets/username/my-bucket

Hoặc thông qua Python:

>>> from huggingface_hub import sync_bucket

# Upload: local directory -> bucket
>>> sync_bucket("./data", "hf://buckets/username/my-bucket")

# Download: bucket -> local directory
>>> sync_bucket("hf://buckets/username/my-bucket", "./data")

Xóa các tệp không cần thiết

Mặc định, sync chỉ thêm hoặc cập nhật các tệp. Sử dụng --delete (hoặc delete=True trong Python) để cũng xóa các tệp ở đích không tồn tại trong nguồn:

# Upload and remove remote files not present locally
>>> hf buckets sync ./data hf://buckets/username/my-bucket --delete

# Download and remove local files not present in bucket
>>> hf buckets sync hf://buckets/username/my-bucket ./data --delete

Hoặc thông qua Python:

>>> sync_bucket("./data", "hf://buckets/username/my-bucket", delete=True)
>>> sync_bucket("hf://buckets/username/my-bucket", "./data", delete=True)

Lọc

Bạn có thể kiểm soát các tệp được đồng bộ hóa bằng cách sử dụng các mẫu bao gồm/loại trừ:

# Only sync .txt files
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.txt"

# Exclude log files
>>> hf buckets sync ./data hf://buckets/username/my-bucket --exclude "*.log"

# Combine include and exclude
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"

Hoặc thông qua Python:

# Only sync .txt files
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", include=["*.txt"])

# Exclude log files
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", exclude=["*.log"])

# Combine include and exclude
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", include=["*.safetensors"], exclude=["*.tmp"])

Để lọc phức tạp hơn, hãy sử dụng tệp lọc với --filter-from (hoặc filter_from trong Python):

>>> hf buckets sync ./data hf://buckets/username/my-bucket --filter-from filters.txt

Tệp bộ lọc sử dụng tiền tố + (bao gồm) và - (loại trừ). Các dòng bắt đầu bằng # là chú thích. Các quy tắc được đánh giá theo thứ tự (quy tắc khớp đầu tiên được ưu tiên):

# filters.txt
- *.log
- *.tmp
+ *.safetensors
+ *.json

Các chế độ so sánh

Mặc định, sync so sánh các tệp bằng cả kích thước và thời gian sửa đổi. Bạn có thể tùy chỉnh hành vi này:

# Only compare sizes (ignore modification times)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-times

# Only compare modification times (ignore sizes)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-sizes

# Only update files that already exist on the receiver (skip new files)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing

# Only create new files (skip files that already exist on the receiver)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existing

Hoặc thông qua Python:

>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_times=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_sizes=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", existing=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_existing=True)

Lập kế hoạch và áp dụng

Đối với các thao tác quan trọng, bạn có thể xem xét kế hoạch đồng bộ hóa trước khi thực thi:

# Step 1: Generate a plan file (nothing is transferred)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
Sync plan: ./data -> hf://buckets/username/my-bucket
  Uploads: 3
  Downloads: 0
  Deletes: 0
  Skips: 1
Plan saved to: sync-plan.jsonl

# Step 2: Review the plan file (JSONL format)
>>> cat sync-plan.jsonl

# Step 3: Apply the plan
>>> hf buckets sync --apply sync-plan.jsonl

Hoặc thông qua Python:

# Step 1: Generate a plan file (nothing is transferred)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", plan="sync-plan.jsonl")

# Step 2: Review the plan file (JSONL format), then apply
>>> sync_bucket(apply="sync-plan.jsonl")

Tệp kế hoạch là một tệp JSONL có một dòng tiêu đề, sau đó là một dòng cho mỗi thao tác. Mỗi thao tác bao gồm hành động (upload, download, delete hoặc skip), đường dẫn tệp và lý do cho hành động đó. Bạn có thể chỉnh sửa tệp này thủ công trước khi áp dụng, nhưng hãy cẩn thận với cú pháp.

Chạy thử

Sử dụng --dry-run (hoặc dry_run=True trong Python) để lấy kế hoạch đồng bộ hóa mà không thực thi bất kỳ thao tác nào:

# Preview what would be synced
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq '.action'

Hoặc thông qua Python:

>>> plan = sync_bucket("./data", "hf://buckets/username/my-bucket", dry_run=True)
>>> plan.summary()
{'uploads': 3, 'downloads': 0, 'deletes': 0, 'skips': 1, 'total_size': 4096}

--dry-run xuất ra cùng định dạng JSONL như --plan nhưng in ra stdout thay vì lưu vào tệp. Chỉ nội dung JSONL được in ra, giúp an toàn khi dùng pipe.

Chế độ chi tiết và im lặng

# Show per-file operations
>>> hf buckets sync ./data hf://buckets/username/my-bucket --verbose

# Suppress all output
>>> hf buckets sync ./data hf://buckets/username/my-bucket --quiet

Hoặc thông qua Python:

>>> sync_bucket("./data", "hf://buckets/username/my-bucket", verbose=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", quiet=True)

Nâng cao

Đối với các trường hợp sử dụng ở cấp độ thấp hơn, các phương thức sau cũng có sẵn:

get_bucket_paths_info(): Lấy thông tin về các đường dẫn cụ thể trong một bucket bằng một yêu cầu batch duy nhất. Hữu ích khi bạn biết chính xác các tệp cần lấy metadata.

>>> from huggingface_hub import get_bucket_paths_info
>>> for info in get_bucket_paths_info("username/my-bucket", ["file.txt", "models/model.safetensors"]):
...     print(info.path, info.size, info.xet_hash)

get_bucket_file_metadata(): Lấy metadata (kích thước và dữ liệu xet) cho một tệp duy nhất. Được sử dụng bên trong bởi download_bucket_files().

>>> from huggingface_hub import get_bucket_file_metadata
>>> metadata = get_bucket_file_metadata("username/my-bucket", "models/model.safetensors")
>>> metadata.size
42000

Update on GitHub

←Tải tệp lên Sử dụng CLI→