Kompatibilitas S3

Storage Buckets dapat diakses melalui API yang kompatibel dengan S3, sehingga Anda dapat menggunakan alat S3 yang sudah ada — AWS CLI, boto3, s5cmd, dan sebagian besar SDK S3 lainnya — untuk bucket Anda tanpa mengubah kode Anda. Permintaan melewati layanan gateway di https://s3.hf.co.

API S3 adalah salah satu dari beberapa cara untuk mengakses data bucket — untuk akses native Hugging Face (CLI hf, path hf://, dan mount filesystem) tanpa kredensial S3 terpisah, lihat Access Patterns.

API S3 hanya berfungsi dengan Storage Buckets. API ini tidak mengekspos tipe repositori Hugging Face lainnya (model, dataset, Spaces).

Membuat Kredensial S3

Gateway melakukan autentikasi dengan kunci akses bergaya AWS yang diturunkan dari User Access Token Hugging Face.

1. Buka pengaturan Access Tokens Anda. Buat token dengan tombol Create new token jika Anda belum memilikinya. Izin token menjadi izin kredensial S3 — pilih Read untuk akses hanya-baca ke bucket Anda, atau Write untuk akses baca dan tulis.

2. Cari token dalam daftar, buka menu drop-down-nya, dan pilih Generate S3 credentials.

   

3. Salin access key ID yang dihasilkan (dengan awalan HFAK…) dan secret access key ke tempat yang aman — secret hanya ditampilkan sekali.

Kredensial S3 mewarisi izin dari token akses yang mendasarinya. Untuk token bergranularitas halus, batasi cakupannya hanya pada namespace dan bucket yang Anda rencanakan untuk digunakan.

Untuk alur kerja otomatis yang mengakses bucket organisasi, Anda juga dapat membuat kredensial S3 dari token service account alih-alih User Access Token.

Mengonfigurasi Klien

Arahkan klien S3 Anda ke endpoint gateway dan atur beberapa opsi yang diperlukan. Gunakan namespace Hugging Face Anda (nama pengguna atau nama organisasi) di URL endpoint — lihat Penanganan bucket di bawah.

Dua pengaturan checksum ini penting untuk klien terbaru: AWS CLI ≥ 2.23 dan versi boto3 terbaru mengirim checksum CRC32 di akhir (melalui framing aws-chunked) secara default, yang tidak diurai oleh gateway. Pengaturan ini memberi tahu klien untuk mengirim checksum hanya ketika suatu operasi benar-benar membutuhkannya.

Berikut adalah opsional tetapi direkomendasikan agar unggahan besar menggunakan bagian multipart seminimal mungkin:

Contoh: profil AWS CLI

Tambahkan profil ke ~/.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

Catatan: ganti <namespace> di atas dengan nama pengguna atau organisasi tempat bucket Anda disimpan.

Tambahkan kredensial yang sesuai untuk profil ke ~/.aws/credentials:

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

Lalu gunakan perintah S3 apa pun dengan profil:

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

Mengatasi Bucket

AWS S3 menggunakan ruang nama bucket tunggal yang datar dan unik secara global, dan SDK mengharapkan nama bucket berupa string polos tanpa /. Bucket Hugging Face diidentifikasi sebagai namespace/bucket, di mana namespace adalah nama pengguna atau organisasi Anda. Tingkat tambahan ini menimbulkan ketidakcocokan dengan klien S3 — banyak yang tidak menerima / dalam nama bucket, atau akan melakukan URL-escape secara tidak benar. Ada dua cara untuk mengatasinya:

1. Masukkan namespace ke dalam URL endpoint (disarankan untuk sebagian besar kasus). Ini membatasi setiap operasi pada namespace tersebut, sehingga nama bucket yang diteruskan ke klien hanyalah nama bucket HF. Metode ini berfungsi dengan baik untuk bucket Anda sendiri atau bucket dalam satu org, tetapi tidak berfungsi melintasi namespace — misalnya, salinan sisi server dari bucket pribadi ke bucket org.

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

2. Perlakukan namespace sebagai bucket dan tambahkan nama bucket HF di depan kunci objek. Ini berfungsi untuk operasi tingkat objek (unggah, unduh) tetapi memiliki masalah dengan operasi tingkat bucket seperti membuat atau menghapus bucket.

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

Batasan dan Perbedaan dari AWS S3

Karena Storage Buckets tidak memodelkan setiap konsep S3, beberapa perilaku berbeda atau tidak didukung.

Unduhan objek

Gateway saat ini bersifat single-region. Untuk meningkatkan kinerja unduhan, GetObject biasanya merespons dengan HTTP 302 redirect ke edge CDN Hugging Face terdekat, alih-alih menyajikan byte secara langsung.

Beberapa SDK tidak mengikuti redirect dari endpoint S3, sehingga gateway mendeteksi klien yang mengidentifikasi diri sebagai aws-cli, botocore (yang mencakup boto3), atau aws-sdk-rust dan memproksikan data melalui dirinya sendiri untuk mereka. Semua klien lain (rclone, s5cmd, curl, AWS Go SDK, dll.) menerima 302 dan mengikutinya secara native, menjaga gateway tetap di luar jalur data untuk unduhan yang lebih cepat.

Penamaan kunci objek

Kunci objek Bucket lebih dibatasi daripada S3. Sebuah kunci tidak boleh:

• dimulai atau diakhiri dengan /
• mengandung garis miring berurutan (//)
• mengandung urutan ../
• mulai dengan ./
• berakhir dengan ..
• mengandung backslash (\) atau null byte (\0)

ListObjects

• ListObjectsV1 tidak didukung — gunakan ListObjectsV2. Perhatikan bahwa beberapa klien (seperti rclone) mungkin perlu dikonfigurasi untuk menggunakan ListObjectsV2 secara eksklusif.
• Hanya / yang diizinkan sebagai pemisah.

Perbedaan API lainnya

• Metadata objek: metadata pengguna arbitrer (x-amz-meta-*) tidak disimpan atau dikembalikan. Content-Type didukung.
• Fitur yang tidak didukung: ACL, kebijakan bucket, penandaan objek, versioning objek, aturan siklus hidup, enkripsi sisi server (SSE), dan notifikasi bucket tidak didukung. Objek selalu dilaporkan dengan kelas penyimpanan STANDARD. Header dan parameter permintaan terkait diterima tetapi diabaikan.
• CopyObject: salin sisi server hanya berfungsi dalam satu namespace. Salin lintas namespace dan UploadPartCopy (menyalin bagian dari objek yang ada ke dalam unggahan multipart) tidak didukung.
• Permintaan kondisional: prasyarat If-Match / If-None-Match dihormati pada PutObject dan pada sumber salinan dari CopyObject, tetapi tidak pada GetObject.
• Masa kedaluwarsa unggahan multipart: unggahan multipart yang sedang berlangsung tetapi tidak pernah diselesaikan atau dibatalkan akan kedaluwarsa dan dibersihkan secara otomatis setelah 7 hari.

Contoh

Resep dunia nyata untuk tugas-tugas umum. Masing-masing dibangun di atas konfigurasi klien di atas.

Baca dan tulis dengan boto3

boto3 berfungsi terhadap gateway dengan pengaturan klien di atas. Ganti <namespace> dengan nama pengguna atau organisasi Anda:

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

Kueri bucket dengan DuckDB

Pada DuckDB 2.0 atau lebih baru, ekstensi httpfs membaca jalur hf://buckets/ secara langsung, dan dengan ekstensi hf ia juga dapat menulis ke Buckets. Lihat Query with DuckDB.

Untuk versi DuckDB yang lebih awal, atau untuk menulis kembali hasil query ke bucket dengan COPY ... TO tanpa ekstensi, gunakan gateway 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' wajib diisi. Tanpa ini, DuckDB menggunakan penindasan bergaya virtual-hosted (my-bucket.s3.hf.co), yang tidak dilayani oleh gateway — Anda akan melihat error “Could not resolve hostname”.

Mengimpor data menggunakan rclone

rclone adalah cara yang praktis untuk menyalin data antara dua penyimpanan yang kompatibel dengan S3, sehingga cocok untuk memindahkan bucket AWS S3 yang sudah ada (atau sumber apa pun yang kompatibel dengan S3) ke Storage Bucket.

Idenya adalah mendeklarasikan dua remote — bucket sumber Anda dan gerbang Hugging Face — lalu membiarkan rclone mengalirkan objek di antara keduanya. Tambahkan kedua remote ke ~/.config/rclone/rclone.conf. Yang pertama menunjuk ke bucket S3 Anda yang sudah ada; sesuaikan agar cocok dengan sumber Anda (di sini, AWS S3 biasa):

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

Poin kedua mengarah ke gateway Hugging Face. Seperti klien lainnya, batasi endpoint ke namespace Anda, gunakan penunjukan alamat path, paksa ListObjectsV2 (satu-satunya versi listing yang didukung gateway), dan atur ukuran multipart besar agar unggahan menggunakan bagian sesedikit mungkin:

[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

Catatan: ganti <namespace> di atas dengan nama pengguna atau organisasi tempat bucket Anda disimpan, dan gunakan kredensial S3 yang dihasilkan dari token akses Anda. Bucket tujuan harus sudah ada di bawah namespace tersebut.

Sekarang salin bucket sumber ke dalam Storage Bucket Anda:

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

rclone copy hanya mentransfer objek yang hilang atau berubah di tujuan, sehingga aman untuk dijalankan ulang guna melanjutkan impor yang terputus atau mengambil objek baru. Untuk menjadikan tujuan sebagai cermin persis dari sumber — menghapus objek di tujuan yang tidak lagi ada di sumber — gunakan rclone sync sebagai gantinya:

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

Untuk impor besar, tambahkan --transfers dan --checkers untuk meningkatkan konkurensi (mis. --transfers 16 --checkers 16), lalu jalankan rclone check aws:my-source-bucket hf:my-bucket setelahnya untuk memastikan setiap objek berhasil dipindahkan.

Versi data dengan DVC

DVC memversikan dataset dan model di git dengan menyimpan file pointer kecil di repository dan mendorong data sebenarnya ke remote. Sebuah bucket berfungsi sebagai remote DVC melalui gateway, sehingga kode Anda dan pointer .dvc tetap berada di git sementara data tersimpan di bucket Anda. Instal DVC dengan dukungan S3 (pip install 'dvc[s3]'), lalu tambahkan remote menggunakan pengaturan klien di atas:

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

Lewatkan kredensial S3 melalui lingkungan, atau dengan dvc remote modify --local agar tidak masuk ke git:

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

Lalu lacak, dorong, dan tarik seperti biasa — dvc push mengunggah ke bucket, dan dvc pull pada clone baru mengunduhnya kembali:

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

Gunakan namespace Anda di endpointurl dan nama bucket polos di URL s3://.