Tương thích S3

Storage Buckets có thể được truy cập thông qua API tương thích S3, cho phép bạn sử dụng các công cụ S3 hiện có — AWS CLI, boto3, s5cmd và hầu hết các SDK S3 khác — cho các bucket của mình mà không cần thay đổi mã. Các yêu cầu được xử lý qua dịch vụ gateway tại https://s3.hf.co.

API S3 là một trong nhiều cách để truy cập dữ liệu bucket — để biết về cách truy cập bản địa của Hugging Face (CLI hf, đường dẫn hf:// và các điểm gắn filesystem) mà không cần thông tin xác thực S3 riêng biệt, hãy xem Các mẫu truy cập.

API S3 chỉ hoạt động với Storage Buckets. Nó không hiển thị các loại kho Hugging Face khác (models, datasets, Spaces).

Tạo thông tin xác thực S3

Gateway xác thực bằng các khóa truy cập theo phong cách AWS được suy ra từ User Access Token của Hugging Face.

1. Chuyển đến cài đặt Access Tokens của bạn. Tạo một token bằng nút Create new token nếu bạn chưa có. Quyền của token sẽ trở thành quyền của thông tin xác thực S3 — chọn Read để truy cập chỉ đọc các bucket của bạn, hoặc Write để truy cập đọc và ghi.

2. Tìm token trong danh sách, mở menu thả xuống của nó và chọn Generate S3 credentials.

   

3. Sao chép access key ID (có tiền tố HFAK…) và secret access key đã tạo vào một nơi an toàn — secret chỉ được hiển thị một lần.

Thông tin xác thực S3 kế thừa các quyền của token truy cập cơ bản. Đối với token chi tiết, hãy giới hạn phạm vi của chúng chỉ cho các namespace và bucket mà bạn dự định sử dụng.

Đối với các quy trình tự động hóa truy cập vào các bucket của tổ chức, bạn cũng có thể tạo thông tin xác thực S3 từ token service account thay vì User Access Token.

Cấu hình một Client

Chỉ định client S3 của bạn đến endpoint gateway và thiết lập một số tùy chọn bắt buộc. Sử dụng namespace của bạn trên Hugging Face (tên người dùng hoặc tên tổ chức) trong URL endpoint — xem Địa chỉ hóa bucket bên dưới.

Hai cài đặt checksum này có ý nghĩa với các client gần đây: AWS CLI ≥ 2.23 và các phiên bản boto3 gần đây gửi checksum CRC32 ở cuối (thông qua khung aws-chunked) theo mặc định, điều mà gateway không phân tích. Các cài đặt này chỉ cho client biết rằng chỉ gửi checksum khi một thao tác thực sự yêu cầu chúng.

Các mục sau là tùy chọn nhưng được khuyến nghị để các tệp tải lên lớn sử dụng càng ít phần multipart càng tốt:

Ví dụ: Hồ sơ AWS CLI

Thêm một hồ sơ vào ~/.aws/config:

[profile hf]
region = us-east-1
endpoint_url = https://s3.hf.co/<namespace>
s3 =
    addressing_style = path
    multipart_threshold = 2GB
    multipart_chunksize = 2GB
request_checksum_calculation = when_required
response_checksum_validation = when_required

Lưu ý: thay <namespace> ở trên bằng tên người dùng hoặc tổ chức chứa các bucket của bạn.

Thêm thông tin xác thực tương ứng cho hồ sơ vào ~/.aws/credentials:

[hf]
aws_access_key_id = HFAK...
aws_secret_access_key = ...

Sau đó, sử dụng bất kỳ lệnh S3 nào với hồ sơ:

aws --profile hf s3 ls
aws --profile hf s3 mb s3://my-bucket
aws --profile hf s3 cp ./model.safetensors s3://my-bucket/models/model.safetensors

Xử lý các Bucket

AWS S3 sử dụng một không gian tên bucket phẳng, duy nhất toàn cục, và các SDK kỳ vọng tên bucket là một chuỗi đơn giản không có /. Các bucket của Hugging Face được xác định bằng namespace/bucket, trong đó namespace là tên người dùng hoặc tổ chức của bạn. Cấp độ bổ sung này gây ra sự không tương thích với các client S3 — nhiều client sẽ không chấp nhận / trong tên bucket, hoặc sẽ URL-escape nó một cách sai lệch. Có hai cách để khắc phục:

1. Đặt namespace trong URL endpoint (khuyến nghị cho hầu hết các trường hợp). Cách này giới hạn mọi thao tác trong phạm vi namespace đó, nên tên bucket truyền vào client chỉ cần là tên bucket HF. Phương pháp này hoạt động tốt với các bucket của bạn hoặc các bucket trong một tổ chức duy nhất, nhưng sẽ gặp sự cố khi vượt qua các namespace — ví dụ như sao chép phía máy chủ từ bucket cá nhân sang bucket của tổ chức.

aws --endpoint-url https://s3.hf.co/my-org s3api get-object \
  --bucket my-bucket --key some/object.txt ./object.txt

2. Xem namespace như bucket và thêm tên bucket HF vào đầu khóa đối tượng. Cách này hoạt động với các thao tác ở cấp độ đối tượng (tải lên, tải xuống) nhưng gặp vấn đề với các thao tác ở cấp độ bucket như tạo hoặc xóa bucket.

aws --endpoint-url https://s3.hf.co s3api get-object \
  --bucket my-org --key my-bucket/some/object.txt ./object.txt

Hạn chế và Sự khác biệt so với AWS S3

Vì Storage Buckets không mô hình hóa mọi khái niệm của S3, một số hành vi sẽ khác biệt hoặc không được hỗ trợ.

Tải xuống đối tượng

Gateway hiện chỉ hoạt động trong một khu vực duy nhất. Để cải thiện hiệu suất tải xuống, GetObject thường phản hồi bằng lệnh chuyển hướng HTTP 302 đến cạnh CDN gần nhất của Hugging Face thay vì cung cấp trực tiếp các byte dữ liệu.

Một số SDK không theo dõi các lệnh chuyển hướng từ endpoint S3, do đó gateway sẽ phát hiện các client tự nhận dạng là aws-cli, botocore (bao gồm cả boto3) hoặc aws-sdk-rust và tự mình proxy dữ liệu cho chúng. Tất cả các client khác (rclone, s5cmd, curl, AWS Go SDK, v.v.) sẽ nhận được mã 302 và tự động theo dõi nó, giúp gateway không nằm trong đường dẫn dữ liệu, từ đó tăng tốc độ tải xuống.

Đặt tên khóa đối tượng

Các khóa đối tượng trong Bucket bị hạn chế hơn so với S3. Một khóa không được:

• bắt đầu hoặc kết thúc bằng /
• chứa các dấu gạch chéo liên tiếp (//)
• chứa các chuỗi ../
• bắt đầu bằng ./
• kết thúc bằng ..
• chứa dấu gạch chéo ngược (\) hoặc byte null (\0)

ListObjects

• ListObjectsV1 không được hỗ trợ — hãy dùng ListObjectsV2. Lưu ý rằng một số client (như rclone) có thể cần được cấu hình để chỉ dùng ListObjectsV2.
• Chỉ / được phép dùng làm ký tự phân cách.

Các khác biệt API khác

• Metadata của đối tượng: metadata tùy ý của người dùng (x-amz-meta-*) không được lưu trữ hoặc trả về. Content-Type được hỗ trợ.
• Các tính năng không được hỗ trợ: ACL, chính sách bucket, gắn thẻ đối tượng, phân bản đối tượng, quy tắc vòng đời, mã hóa phía máy chủ (SSE) và thông báo bucket không được hỗ trợ. Các đối tượng luôn được báo cáo với lớp lưu trữ STANDARD. Các tiêu đề và tham số yêu cầu liên quan được chấp nhận nhưng bị bỏ qua.
• CopyObject: sao chép phía máy chủ chỉ hoạt động trong cùng một namespace. Sao chép giữa các namespace và UploadPartCopy (sao chép một phần từ một đối tượng hiện có vào một tải lên đa phần) không được hỗ trợ.
• Yêu cầu có điều kiện: các điều kiện tiên quyết If-Match / If-None-Match được tuân thủ trên PutObject và trên nguồn sao chép của CopyObject, nhưng không áp dụng cho GetObject.
• Hạn hết thời gian tải lên đa phần: các bản tải lên đa phần đang thực hiện mà không bao giờ được hoàn tất hoặc hủy bỏ sẽ tự động hết hạn và được dọn dẹp sau 7 ngày.

Ví dụ

Công thức thực tế cho các tác vụ phổ biến. Mỗi công thức được xây dựng dựa trên cấu hình client ở trên.

Đọc và ghi với boto3

boto3 hoạt động với gateway bằng cài đặt client ở trên. Thay <namespace> bằng tên người dùng hoặc tổ chức của bạn:

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.hf.co/<namespace>",
    aws_access_key_id="HFAK...",
    aws_secret_access_key="...",
    config=Config(
        region_name="us-east-1",
        s3={"addressing_style": "path"},
        request_checksum_calculation="when_required",
        response_checksum_validation="when_required",
    ),
)

s3.upload_file("model.safetensors", "my-bucket", "models/model.safetensors")
s3.download_file("my-bucket", "models/model.safetensors", "model.safetensors")

Truy vấn một bucket bằng DuckDB

Trên DuckDB 2.0 trở lên, phần mở rộng httpfs đọc trực tiếp các đường dẫn hf://buckets/, và với phần mở rộng hf, nó cũng có thể ghi vào Buckets. Xem Truy vấn bằng DuckDB.

Đối với các phiên bản DuckDB trước đó, hoặc để ghi kết quả truy vấn trở lại bucket bằng COPY ... TO mà không cần phần mở rộng, hãy sử dụng cổng S3:

INSTALL httpfs;
LOAD httpfs;

CREATE SECRET hf (
    TYPE s3,
    KEY_ID 'HFAK...',
    SECRET '...',
    ENDPOINT 's3.hf.co/<namespace>',
    URL_STYLE 'path',
    REGION 'us-east-1'
);

SELECT * FROM read_parquet('s3://my-bucket/data.parquet');

URL_STYLE 'path' là bắt buộc. Nếu không có nó, DuckDB sẽ sử dụng địa chỉ theo kiểu virtual-hosted-style (my-bucket.s3.hf.co), mà gateway không hỗ trợ — bạn sẽ gặp lỗi “Could not resolve hostname”.

Nhập dữ liệu bằng rclone

rclone là một cách tiện lợi để sao chép dữ liệu giữa hai kho lưu trữ tương thích S3, vì vậy đây là lựa chọn phù hợp để di chuyển một bucket AWS S3 hiện có (hoặc bất kỳ nguồn tương thích S3 nào) vào Storage Bucket.

Ý tưởng là khai báo hai remote — bucket nguồn của bạn và cổng Hugging Face — và để rclone truyền trực tiếp các đối tượng giữa chúng. Thêm cả hai remote vào ~/.config/rclone/rclone.conf. Remote đầu tiên trỏ đến bucket S3 hiện có của bạn; điều chỉnh cho phù hợp với nguồn của bạn (ở đây, AWS S3 thuần túy):

[aws]
type = s3
provider = AWS
access_key_id = AKIA...
secret_access_key = ...
region = us-east-1

Điểm thứ hai trỏ đến cổng Hugging Face. Giống như bất kỳ client nào khác, hãy giới hạn phạm vi endpoint cho namespace của bạn, sử dụng địa chỉ path, ép buộc ListObjectsV2 (phiên bản liệt kê duy nhất mà cổng hỗ trợ) và đặt kích thước multipart lớn để các lần tải lên sử dụng càng ít phần càng tốt:

[hf]
type = s3
provider = Other
endpoint = https://s3.hf.co/<namespace>
access_key_id = HFAK...
secret_access_key = ...
region = us-east-1
force_path_style = true
list_version = 2
upload_cutoff = 2G
chunk_size = 2G

Lưu ý: thay <namespace> ở trên bằng tên người dùng hoặc tổ chức chứa các bucket của bạn, và sử dụng thông tin xác thực S3 được tạo từ access token của bạn. Bucket đích phải đã tồn tại dưới namespace đó.

Bây giờ hãy sao chép một bucket nguồn vào Storage Bucket của bạn:

rclone copy aws:my-source-bucket hf:my-bucket --progress

rclone copy chỉ chuyển các đối tượng bị thiếu hoặc đã thay đổi tại đích, do đó bạn có thể chạy lại lệnh này một cách an toàn để tiếp tục quá trình nhập bị gián đoạn hoặc lấy các đối tượng mới. Để biến đích thành bản sao chính xác của nguồn — xóa các đối tượng tại đích không còn tồn tại tại nguồn — hãy dùng rclone sync thay thế:

rclone sync aws:my-source-bucket hf:my-bucket --progress

Đối với các lần nhập lớn, hãy thêm --transfers và --checkers để tăng mức độ song song (ví dụ --transfers 16 --checkers 16), và chạy rclone check aws:my-source-bucket hf:my-bucket sau đó để xác nhận mọi đối tượng đã được chuyển sang.

Dữ liệu phiên bản với DVC

DVC quản lý phiên bản cho dataset và model trong git bằng cách giữ các tệp trỏ nhỏ trong repository và đẩy dữ liệu thực tế lên remote. Một bucket hoạt động như một DVC remote thông qua gateway, do đó code và các trỏ .dvc của bạn vẫn nằm trong git trong khi dữ liệu được lưu trong bucket của bạn. Cài đặt DVC với hỗ trợ S3 (pip install 'dvc[s3]'), sau đó thêm remote bằng cách sử dụng cài đặt client ở trên:

dvc remote add -d hf-bucket s3://my-bucket/dvc-store
dvc remote modify hf-bucket endpointurl https://s3.hf.co/<namespace>
dvc remote modify hf-bucket region us-east-1

Truyền thông tin xác thực S3 thông qua biến môi trường, hoặc dùng dvc remote modify --local để chúng không bị đưa vào git:

export AWS_ACCESS_KEY_ID=HFAK...
export AWS_SECRET_ACCESS_KEY=...

Sau đó, theo dõi, đẩy và kéo như bình thường — dvc push tải lên bucket, và dvc pull trên một bản clone mới sẽ tải nó về:

dvc add data/
git add data.dvc .gitignore .dvc/config && git commit -m "Track data with DVC"
dvc push

Sử dụng namespace của bạn trong endpointurl và tên bucket trần trong URL s3://.