Thùng chứa lưu trữ

Storage Buckets là một loại kho trên Hugging Face Hub, cung cấp lưu trữ đối tượng tương tự S3, được vận hành bởi backend lưu trữ Xet. Khác với các kho dựa trên Git (models, datasets, Spaces), buckets là không có phiên bản và khả biến, được thiết kế cho các trường hợp sử dụng cần lưu trữ đơn giản và nhanh chóng, chẳng hạn như 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 các bucket bằng giao diện web của Hub, CLI hf hoặc API Python.

Buckets có sẵn cho tất cả người dùng và tổ chức. Xem hf.co/storage để biết chi tiết về giá.

Xem Mẫu thức truy cập để biết cách truy cập dữ liệu bucket từ các công cụ của bạn (gắn như một hệ thống tệp, đường dẫn hf://, gắn volume trong Jobs/Spaces), API tương thích S3 để sử dụng các công cụ S3 hiện có (AWS CLI, boto3, s5cmd), và Tích hợp Bucket cho các đoạn mã sẵn sàng sử dụng trong các thư viện dữ liệu phổ biến như pandas, Dask và Spark.

Buckets so với Repositories

Hub cung cấp hai loại lưu trữ: các kho dựa trên Git cho công việc cộng tác có kiểm soát phiên bản và các bucket cho lưu trữ đối tượng nhanh, có thể thay đổi.

Sử dụng repositories khi bạn cần lịch sử phiên bản, các tính năng cộng tác (PR, thảo luận) và tích hợp thư viện. Sử dụng buckets khi bạn cần bộ lưu trữ nhanh, có thể thay đổi cho dữ liệu thay đổi thường xuyên — các tệp có thể được ghi đè hoặc xóa tại chỗ.

Tạo một Bucket

Từ giao diện Hub

1. Truy cập huggingface.co/new-bucket:

2. Chỉ định chủ sở hữu của bucket: đây có thể là bạn hoặc bất kỳ tổ chức nào mà bạn đang tham gia.

3. Nhập tên bucket.

4. Chọn xem bucket nên là công khai hay riêng tư.

5. Tùy chọn, hãy chọn trước các khu vực làm nóng CDN để lưu trữ bộ đệm dữ liệu của bạn gần hơn với tài nguyên tính toán ngay từ đầu.

Sau khi tạo bucket, bạn nên thấy trang bucket:

Từ CLI

# Create a bucket under your namespace
hf buckets create my-bucket

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

# Create a bucket under an organization
hf buckets create my-org/shared-bucket

Từ Python

from huggingface_hub import create_bucket

# Create a bucket under your namespace
create_bucket("my-bucket")

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

# Create a bucket under an organization
create_bucket("my-org/shared-bucket")

Thay đổi khả năng hiển thị

Bạn có thể thay đổi mức độ hiển thị của một bucket sau khi tạo:

# Make a bucket private
hf buckets settings username/my-bucket --private

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

from huggingface_hub import update_bucket_settings

update_bucket_settings("username/my-bucket", private=True)
update_bucket_settings("username/my-bucket", private=False)

Để xem tài liệu tham khảo API Python đầy đủ, bao gồm việc xóa, di chuyển và liệt kê các bucket, hãy xem hướng dẫn về Buckets của huggingface_hub.

Duyệt các Bucket trên Hub

Mỗi bucket có một trang trên Hub, nơi bạn có thể duyệt nội dung, điều hướng các thư mục và xem chi tiết tệp. Các trang bucket có sẵn tại https://huggingface.co/buckets/<owner>/<bucket-name>.

Hiển thị README

Nếu một thư mục trong bucket của bạn chứa tệp README.md, Hub sẽ hiển thị nội dung của tệp đó bên dưới danh sách tệp trên trang của thư mục đó. Tính năng này hoạt động cả ở gốc bucket lẫn bên trong bất kỳ thư mục con nào — hữu ích để tài liệu hóa nội dung của bucket, cách dữ liệu được tổ chức, hoặc cách các công cụ downstream nên sử dụng dữ liệu.

Liệt kê từ CLI

Bạn cũng có thể liệt kê nội dung bucket từ CLI:

# List files in a bucket (with human-readable sizes)
hf buckets list julien-c/my-training-bucket -h
                     Feb 17 14:46  art/
                     Feb 17 14:58  arxivqa/
                     Feb 17 15:02  arxivqa2/
                     Feb 17 15:04  arxivqa3/
                     Feb 17 14:47  captcha/
                     Feb 17 14:53  captcha2/
                     Feb 24 17:22  julien/

# Recursive listing
hf buckets list julien-c/my-training-bucket/art -h -R
    423.6 MB         Feb 17 14:29  art/train-00000-of-00011.parquet
    441.0 MB         Feb 17 14:29  art/train-00001-of-00011.parquet
    521.7 MB         Feb 17 14:29  art/train-00002-of-00011.parquet
    481.4 MB         Feb 17 14:29  art/train-00003-of-00011.parquet
    444.6 MB         Feb 17 14:29  art/train-00004-of-00011.parquet
    461.6 MB         Feb 17 14:29  art/train-00005-of-00011.parquet
    466.4 MB         Feb 17 14:29  art/train-00006-of-00011.parquet
    486.3 MB         Feb 17 14:29  art/train-00007-of-00011.parquet
    477.0 MB         Feb 17 14:29  art/train-00008-of-00011.parquet
    454.0 MB         Feb 17 14:29  art/train-00009-of-00011.parquet
    483.1 MB         Feb 17 14:29  art/train-00010-of-00011.parquet

# Tree view
hf buckets list julien-c/my-training-bucket --tree -h -R
                        ├── art/
423.6 MB  Feb 17 14:29  │   ├── train-00000-of-00011.parquet
441.0 MB  Feb 17 14:29  │   ├── train-00001-of-00011.parquet
521.7 MB  Feb 17 14:29  │   ├── train-00002-of-00011.parquet
481.4 MB  Feb 17 14:29  │   ├── train-00003-of-00011.parquet
444.6 MB  Feb 17 14:29  │   ├── train-00004-of-00011.parquet
461.6 MB  Feb 17 14:29  │   ├── train-00005-of-00011.parquet
466.4 MB  Feb 17 14:29  │   ├── train-00006-of-00011.parquet
486.3 MB  Feb 17 14:29  │   ├── train-00007-of-00011.parquet
477.0 MB  Feb 17 14:29  │   ├── train-00008-of-00011.parquet
454.0 MB  Feb 17 14:29  │   ├── train-00009-of-00011.parquet
483.1 MB  Feb 17 14:29  │   └── train-00010-of-00011.parquet
                        ├── arxivqa/
495.9 MB  Feb 17 14:32  │   ├── train-00000-of-00164.parquet
518.3 MB  Feb 17 14:32  │   ├── train-00001-of-00164.parquet
495.5 MB  Feb 17 14:32  │   ├── train-00002-of-00164.parquet
486.6 MB  Feb 17 14:32  │   ├── train-00003-of-00164.parquet
490.4 MB  Feb 17 14:32  │   ├── train-00004-of-00164.parquet
...

Quản lý tệp

Bạn có thể tải lên và tải xuống tệp trực tiếp từ trang bucket trên Hub, hoặc sử dụng CLI và Python API để truy cập theo chương trình. Các tệp trong bucket được tham chiếu bằng đường dẫn hf://buckets/ (ví dụ: hf://buckets/username/my-bucket/path/to/file). Lệnh hf buckets cp xử lý việc chuyển từng tệp riêng lẻ, trong khi hf buckets sync phù hợp hơn cho các thư mục. Tất cả các lệnh đều hoạt động theo cả hai chiều — từ cục bộ đến từ xa và từ từ xa về cục bộ.

Nếu dữ liệu của bạn đã nằm trong một kho lưu trữ model, dataset hoặc Space (hoặc một bucket khác), bạn có thể sao chép nó trên phía server bằng hf buckets cp — không cần tải xuống hoặc tải lên lại. Xem Sao chép tệp giữa các kho và bucket.

Tải tệp lên

Để tải lên nhanh, bạn có thể kéo và thả tệp trực tiếp vào trang bucket trong trình duyệt. Để sử dụng theo chương trình, hf buckets cp sao chép từng tệp vào một bucket. Nguồn là đường dẫn cục bộ và đích là đường dẫn hf://buckets/. Bạn cũng có thể truyền dữ liệu từ stdin, rất tiện lợi cho nội dung được tạo ra theo chương trình.

Giao diện dòng lệnh:

# Upload a single file
hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/models/model.safetensors

# Upload from stdin
cat config.json | hf buckets cp - hf://buckets/username/my-bucket/config.json

Trong Python, hãy dùng batch_bucket_files để tải lên một hoặc nhiều tệp trong một lần gọi. Mỗi mục là một tuple (local_path, remote_path).

Python:

from huggingface_hub import batch_bucket_files

batch_bucket_files(
    "username/my-bucket",
    add=[
        ("./model.safetensors", "models/model.safetensors"),
        ("./config.json", "models/config.json"),
    ],
)

Để biết thêm các tùy chọn tải lên (byte thô, kết hợp tải lên + xóa, v.v.), hãy xem hướng dẫn tải lên của huggingface_hub.

Tải xuống tệp

Bạn có thể tải xuống các tệp riêng lẻ trực tiếp từ trang bucket trên Hub bằng cách nhấp vào chúng. Để truy cập theo chương trình, cú pháp tải xuống phản ánh cú pháp tải lên — hoán đổi nguồn và đích trong hf buckets cp. Bạn cũng có thể stream một tệp ra stdout bằng cách sử dụng - làm đích, cho phép bạn pipe nội dung bucket trực tiếp vào các công cụ khác.

Giao diện dòng lệnh:

# Download a single file
hf buckets cp hf://buckets/username/my-bucket/models/model.safetensors ./model.safetensors

# Download to stdout and pipe
hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .

Trong Python, hãy sử dụng download_bucket_files với một danh sách các bộ (remote_path, local_path).

Python:

from huggingface_hub import download_bucket_files

download_bucket_files(
    "username/my-bucket",
    files=[
        ("models/model.safetensors", "./local/model.safetensors"),
        ("config.json", "./local/config.json"),
    ],
)

Để tải xuống nhanh hơn bằng cách sử dụng metadata đã lấy trước, hãy xem hướng dẫn tải xuống của huggingface_hub.

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

Lệnh sync hoạt động giống như rsync hoặc aws s3 sync — nó so sánh nguồn và đích, chỉ chuyển các tệp đã thay đổi. Đây là cách hiệu quả nhất để đồng bộ hóa một thư mục cục bộ với một bucket. Mặc định, sync chỉ thêm và cập nhật tệp. Truyền --delete để cũng xóa các tệp ở đích không còn tồn tại ở nguồn. Dùng --dry-run để xem trước những gì sẽ xảy ra mà không thực sự chuyển bất kỳ thứ gì.

Giao diện dòng lệnh:

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

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

# Sync with deletion of extraneous files
hf buckets sync ./data hf://buckets/username/my-bucket/data --delete

# Preview what would be synced without executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --dry-run

# Plan and apply: review the sync plan before executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --plan sync-plan.jsonl
# ... review the plan file, then apply it
hf buckets sync --apply sync-plan.jsonl

hf sync là một alias tiện lợi cho hf buckets sync.

Python:

from huggingface_hub import sync_bucket

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

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

Lệnh sync hỗ trợ lọc (--include, --exclude), các chế độ so sánh (--ignore-times, --existing) và quy trình lập kế hoạch và áp dụng để xem xét các thao tác trước khi thực thi. Để biết đầy đủ các tùy chọn, hãy xem huggingface_hub hướng dẫn đồng bộ hóa.

Xóa tệp

Vì các bucket không có phiên bản, việc xóa là tức thời và vĩnh viễn — không có cách nào để khôi phục một tệp đã bị xóa. Hãy sử dụng --dry-run để kiểm tra lại trước khi xóa tệp, đặc biệt khi sử dụng --recursive.

Giao diện dòng lệnh:

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

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

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

Python:

from huggingface_hub import batch_bucket_files

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

Để biết thêm các tùy chọn xóa (lọc theo mẫu, xóa đệ quy, v.v.), hãy xem hướng dẫn xóa của huggingface_hub.

Sao chép tệp giữa các kho và bucket

Bạn có thể sao chép các tệp được theo dõi bởi Xet từ bất kỳ kho lưu trữ nào (mô hình, tập dữ liệu, Space) hoặc bucket vào một bucket đích mà không cần tải lại dữ liệu. Việc sao chép được thực hiện phía máy chủ: chỉ các băm nội dung Xet được di chuyển, do đó ngay cả các tệp rất lớn cũng được sao chép tức thì nhờ loại bỏ trùng lặp ở mức chunk.

Chỉ các tệp được theo dõi bởi Xet mới được sao chép từ máy chủ sang máy chủ. Các tệp nhỏ không thuộc Xet (ví dụ: tệp cấu hình và README) sẽ được tự động tải xuống và tải lên lại. Việc sao chép phía máy chủ cũng yêu cầu nguồn và đích phải nằm trong cùng một khu vực lưu trữ.

Giao diện dòng lệnh:

hf buckets cp \
  hf://datasets/HuggingFaceFW/fineweb/data \
  hf://buckets/username/fineweb-data

Python:

from huggingface_hub import HfApi

api = HfApi()

api.copy_files(
    "hf://datasets/HuggingFaceFW/fineweb/data",
    "hf://buckets/username/fineweb-data",
)

Bạn cần quyền đọc đối với kho lưu trữ hoặc bucket nguồn và quyền ghi đối với bucket đích.

Lưu ý rằng việc chuyển dữ liệu theo chiều ngược lại từ một bucket sang một kho (mô hình, tập dữ liệu, Space) mà không cần tải lên lại hiện chưa khả dụng, nhưng đã được đưa vào lộ trình phát triển.

Theo dõi các thay đổi

Buckets có thể thay đổi, vì vậy các công cụ giữ một góc nhìn về bucket — các điểm gắn (mounts), các lớp hệ thống tệp, các tiến trình đồng bộ (sync daemons), các bảng điều khiển (dashboards) — cần biết khi nào các tệp bị thay đổi. Có hai cơ chế khả dụng:

• Webhooks: các callback HTTP đến một máy chủ do bạn kiểm soát, hoặc một Job được khởi tạo cho mỗi thay đổi — xem Xử lý các tệp mới trong một bucket bằng Jobs.
• Theo dõi trực tiếp: một luồng sự kiện do máy chủ gửi mà client của bạn đăng ký.

Theo dõi trực tiếp

GET https://huggingface.co/api/buckets/<owner>/<bucket-name>/events phát trực tiếp các thay đổi tệp của bucket dưới dạng server-sent events. Yêu cầu phải chứa Accept: text/event-stream (nếu không sẽ trả về 400), và cần quyền đọc tương tự như khi liệt kê bucket — không cần token cho bucket công khai. Xem OpenAPI spec để biết sơ đồ tham số và phản hồi đầy đủ.

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/buckets/username/my-bucket/events"

Trong Python, bạn không cần phải tự tiêu thụ luồng. HfFileSystem sẽ theo dõi nó cho bạn với live_follow=True, nhờ đó các danh sách được lưu trong bộ nhớ đệm của nó luôn được cập nhật khi một tiến trình khác thay đổi bucket:

Đã sao chép

from huggingface_hub import HfFileSystem

hffs = HfFileSystem(live_follow=True)
hffs.ls("buckets/username/my-bucket/data")  # starts following the bucket

Các thư viện nhận storage_options của fsspec (pandas, PyArrow, …) cũng chấp nhận nó.

Dòng phát ra bốn loại sự kiện:

Mỗi mục trong changes có một path và một op (add, update hoặc delete). Một add hoặc update cũng chứa các trường đã thay đổi — size, xetHash, uploadedAt, mtime, mtimeNanos — do đó một update có thể chỉ nhỏ bằng một uploadedAt mới khi tệp được tải lên lại y hệt. Các trường không thay đổi sẽ bị lược bỏ; mtime/mtimeNanos cũng có thể là null nếu một lần tải lên đã xóa chúng, vì vậy hãy coi trường vắng mặt và null là như nhau.

event: ready
data: {"cursor":"..."}

event: changes
data: {"cursor":"...","changes":[{"path":"data/train.txt","op":"add","size":20,"uploadedAt":"2026-09-16T09:21:45.000Z"},{"path":"data/old.txt","op":"delete"}]}

Tiếp tục. Một luồng mới bắt đầu từ thời điểm bạn kết nối. Để nhận cả những thay đổi bạn đã bỏ lỡ, hãy truyền cursor cuối cùng bạn nhận được (mỗi sự kiện ready và changes đều chứa một con trỏ) dưới dạng ?cursor=<cursor>, hoặc một mốc thời gian dưới dạng ?since=<ISO timestamp> (bao gồm, ví dụ 2026-09-16T09:21:45Z).

Chỉ ~15 phút cuối của các thay đổi có thể được phát lại. Nếu cursor hoặc since của bạn cũ hơn thời điểm đó, bạn sẽ nhận được reset thay vì phát lại: hãy liệt kê bucket một lần để xây dựng lại quan điểm của bạn, sau đó tiếp tục theo dõi từ cursor của sự kiện ready của luồng mới. Việc tiếp tục được thiết kế để lấp đầy các khoảng trống ngắn như kết nối bị ngắt hoặc khởi động lại; một client đã vắng mặt lâu hơn nên dự kiến sẽ liệt kê lại.

Đang kết nối lại. Các kết nối dài hạn được tái sử dụng: cứ khoảng 20 phút (và trong các lần triển khai), máy chủ sẽ gửi reconnect rồi kết thúc luồng. Hãy xử lý mọi sự kết thúc của luồng theo cách tương tự — kết nối lại với con trỏ cuối cùng bạn đã nhận được. Một chú thích : ping được gửi mỗi 30 giây để giữ kết nối hoạt động, do đó một luồng hoàn toàn im lặng có thể được coi là đã chết.

Phản hồi 503 có nghĩa là tính năng theo dõi trực tiếp tạm thời không khả dụng — hãy thử lại sau khoảng thời gian được chỉ định trong tiêu đề Retry-After.

Làm nóng trước và CDN

Buckets được lưu trữ trên bộ nhớ toàn cục của Hub theo mặc định. Đối với các tác vụ mà vị trí lưu trữ ảnh hưởng trực tiếp đến thông lượng, bạn có thể pre-warm dữ liệu bucket để đưa nó đến gần hơn với tài nguyên tính toán của bạn.

Pre-warming lưu trữ các tệp trong bộ nhớ đệm tại các vị trí biên gần các nhà cung cấp đám mây và khu vực cụ thể, nhờ đó việc đọc dữ liệu của các tác vụ được thực hiện cục thay vì phải kéo dữ liệu từ xa qua các khu vực. Tính năng này đặc biệt hữu ích cho:

• Các cụm huấn luyện cần truy cập nhanh vào các bộ dữ liệu hoặc điểm kiểm tra lớn
• Các cấu hình đa khu vực, trong đó các phần khác nhau của một pipeline được chạy trên các đám mây khác nhau
• Phân phối các sản phẩm lớn đến nhiều người dùng trên toàn thế giới

Xem hf.co/storage để biết các khu vực khả dụng và chi tiết về cách bật làm nóng trước.

Các trường hợp sử dụng

Điểm kiểm tra và nhật ký huấn luyện

Khi chạy các tác vụ huấn luyện (ví dụ: thông qua Jobs), hãy lưu checkpoint và log vào một bucket. Khác với kho Git, bạn có thể ghi đè checkpoint mới nhất mà không cần tích lũy lịch sử phiên bản, và sync đảm bảo chỉ dữ liệu đã thay đổi mới được truyền đi.

# After each evaluation step, sync checkpoints to a bucket
hf sync ./checkpoints hf://buckets/my-org/training-run-42/checkpoints

Vì các bucket được xây dựng trên Xet, các checkpoint liên tiếp trong đó phần lớn mô hình bị đóng băng sẽ hưởng lợi từ việc khử trùng lặp ở cấp độ chunk. Chỉ các chunk bị thay đổi mới được tải lên.

Đường ống xử lý dữ liệu

Buckets đóng vai trò là khu vực trung gian cho các luồng xử lý dữ liệu. Xử lý dữ liệu thô, ghi các đầu ra trung gian vào bucket, sau đó nâng cấp sản phẩm cuối cùng lên kho Dataset có phiên bản khi pipeline hoàn tất. Cách này giúp kho có phiên bản của bạn luôn sạch sẽ trong khi cung cấp cho pipeline bộ lưu trữ biến đổi nhanh.

Lưu ý rằng việc chuyển dữ liệu từ một Bucket sang một repository mà không cần tải lên lại hiện chưa khả dụng, nhưng đã được đưa vào lộ trình phát triển.

Lưu trữ Agentic

AI agents cần bộ nhớ tạm cho các kết quả trung gian, đầu ra của công cụ, vết theo dõi và bộ nhớ làm việc. Buckets cung cấp một vị trí bản địa trên Hub cho dữ liệu này: truy cập thay đổi nhanh chóng mà không có chi phí Git, quyền hạn chuẩn của Hugging Face, và có thể định địa chỉ qua các đường dẫn hf://buckets/ trên khắp hệ sinh thái Hub.

Sao lưu luân phiên

Buckets rất phù hợp để duy trì các bản sao lưu theo kiểu lăn (rolling backups). Với kho lưu trữ Dataset dựa trên Git, việc xóa các tệp cũ không giải phóng dung lượng lưu trữ — lịch sử Git giữ lại mọi phiên bản trước đó, nên bạn sẽ cần nén các commit hoặc viết lại lịch sử để thực sự thu hồi không gian. Với buckets, các tệp cũ thực sự biến mất khi bị xóa, và bạn chỉ phải trả tiền cho những gì đang được lưu trữ.

# Sync today's backup, removing files that no longer exist locally
hf sync ./daily-backup hf://buckets/my-user/backups/latest --delete

Liên kết các mô hình với các bucket

Bạn có thể tạo liên kết hai chiều giữa một model và một bucket bằng cách thêm trường buckets vào metadata của model card. Các model được liên kết sẽ hiển thị trên trang bucket, và bucket sẽ xuất hiện dưới dạng tag trên trang model.

# In the model card YAML frontmatter
buckets:
- my-org/my-bucket

Xem Chỉ định một bucket trong tài liệu model cards để biết thêm chi tiết.

Bảng giá

Storage Buckets được tính phí dựa trên lượng dữ liệu được lưu trữ, với mức giá đơn giản theo mỗi TB. Các gói Enterprise được hưởng lợi từ cơ chế tính phí dựa trên khử trùng lặp (deduplication), trong đó các khối dữ liệu (chunks) được chia sẻ giữa các tệp sẽ trực tiếp làm giảm dung lượng bị tính phí.

Đối với các kho lưu trữ khác, việc tạo bucket là miễn phí và có mức dung lượng lưu trữ miễn phí. Đối với mức sử dụng vượt quá gói miễn phí, hãy xem hf.co/storage. Để biết thông tin thanh toán chung, hãy xem tài liệu Thanh toán.