Migrasi Data ke Storage Buckets

Panduan ini menunjukkan cara memindahkan dataset besar ke Storage Bucket dari lokasi saat ini: disk lokal, cloud lain, atau Hub. Cari sumber Anda di tabel di bawah dan langsung ke bagian tersebut.

Di mana pun memungkinkan, buat data Anda dapat dibaca sebagai sistem berkas dan jalankan hf sync. Alat ini menduplikasi di sisi klien, sehingga Anda mengunggah lebih sedikit byte dibandingkan salinan mentah.

Secara sekilas

Mengapa hf sync menjadi default:

• Anda mengunggah lebih sedikit. hf sync mengunggah melalui klien Xet, yang terlebih dahulu memecah dan menduplikasi data Anda, sehingga hanya chunk yang belum pernah dilihat Hub yang dikirimkan. Salinan mentah (misalnya, rclone melalui gerbang S3) mentransfer setiap byte.
• Kecepatannya setidaknya sama. Dalam migrasi yang telah kami dukung sejauh ini, hf sync melalui sumber yang dimount telah menyamai atau melampaui rclone dalam hal throughput.

Sebelum Anda memulai

Semua perintah dalam panduan ini menggunakan hf, yaitu Hugging Face CLI. Output bantuan dari CLI ini dapat dibaca oleh agen, sehingga agen coding dapat menyusun dan memantau migrasi untuk Anda (lihat CLI untuk AI Agents). Tinjau perintah-perintah tersebut sebelum menjalankannya dalam skala besar.

1. Instal CLI. Klien Xet disertakan di dalamnya.

   Disalin

   curl -LsSf https://hf.co/cli/install.sh | bash
   hf version

2. Masuk dengan token yang memiliki akses Write (buat satu):

   Disalin

   hf auth login
   hf auth whoami

3. Buat bucket tujuan. <namespace> adalah nama pengguna atau organisasi Anda. Tanpa --region, bucket akan ditempatkan di region penyimpanan default namespace, yang selalu di AS di luar paket Team & Enterprise. Pada paket tersebut, gunakan --region us atau --region eu untuk memilih.

   Disalin

   hf buckets create <namespace>/<bucket> --private

Mulai dengan uji coba. Apapun jalur yang Anda gunakan, latihlah pada subset kecil (satu folder, atau pola --include), periksa hasilnya dengan --dry-run dan hf buckets ls, lalu luncurkan migrasi penuh. Setiap jalur dalam panduan ini dapat dilanjutkan, sehingga uji coba tidak menimbulkan biaya apa pun.

Dari disk lokal atau sistem berkas klaster

Gunakan ini ketika data Anda berada di disk lokal, volume yang terpasang, atau cluster scratch: apa pun yang dapat dibaca mesin sebagai file. Ini juga merupakan langkah terakhir dari setiap jalur cloud di bawah, setelah sumber terpasang.

hf sync ./data hf://buckets/<namespace>/<bucket>/data

hf sync membandingkan sumber dan tujuan serta hanya mentransfer perbedaannya, sehingga menjalankan ulang perintah yang sama akan melanjutkan migrasi yang terputus: file yang sudah diunggah akan dilewati. Variasi umum:

# Mirror exactly: also delete destination files that are gone from the source
hf sync ./data hf://buckets/<namespace>/<bucket>/data --delete

# Preview what would transfer, without uploading
hf sync ./data hf://buckets/<namespace>/<bucket>/data --dry-run

# Only some files
hf sync ./data hf://buckets/<namespace>/<bucket>/data --include "*.parquet" --exclude "tmp/*"

Untuk meninjau migrasi besar sebelum dijalankan, tulis rencana ke file, periksa, lalu terapkan. Ini memindai sumber dan tujuan sekali, bukan sekali untuk dry run dan sekali lagi untuk eksekusi sebenarnya.

hf sync ./data hf://buckets/<namespace>/<bucket>/data --plan plan.jsonl   # scan once, write the plan
hf sync --apply plan.jsonl                                                # run exactly that plan

Jalankan --apply dari direktori tempat Anda membuat rencana, karena rencana mencatat jalur sumber persis seperti yang Anda ketik. --apply tidak memeriksa apa yang sudah diunggah, jadi untuk melanjutkan eksekusi yang terputus, jalankan kembali perintah hf sync biasa.

Untuk memverifikasi, periksa bahwa dry run tidak memiliki sisa data untuk ditransfer, dan lakukan pemeriksaan acak terhadap isinya:

hf sync ./data hf://buckets/<namespace>/<bucket>/data --dry-run
hf buckets ls hf://buckets/<namespace>/<bucket>/data

Penyetelan

• Jaga cache di disk yang cepat. Klien Xet menyimpan cache chunk dan indeks deduplikasi (cache shard) di bawah HF_HOME. Arahkan HF_HOME ke NVMe lokal jika direktori home Anda tidak berada di NVMe.
• Aktifkan mode berkinerja tinggi untuk migrasi massal pada mesin dengan sumber daya yang memadai. HF_XET_HIGH_PERFORMANCE=1 meningkatkan konkurensi, ukuran buffer, dan jumlah file yang diproses sekaligus, sehingga klien dapat menggunakan setiap core CPU dan memaksimalkan jaringan. Mode ini ditujukan untuk mesin dengan bandwidth tinggi dan disk cepat; pada versi hf_xet sebelum 1.7.0, gunakan hanya dengan minimal 64 GB RAM (periksa dengan hf env). Lihat Environment Variables.
• Batasi ukuran cache shard. Batas ukurannya bersifat lunak: cache hanya dipangkas di awal sebuah run, sehingga dalam satu run yang panjang, ukurannya dapat melampaui batas dengan signifikan. Pada migrasi berskala besar, terutama dalam mode berkinerja tinggi, cache dapat membesar hingga ratusan GB dan memenuhi disk, sehingga run akan dihentikan. Atur HF_XET_SHARD_CACHE_SIZE_LIMIT dengan nyaman di bawah ruang disk yang tersedia, tetapi jangan lebih rendah dari kebutuhan Anda: cache berukuran X melakukan deduplikasi terhadap sekitar 1000 × X data. Lihat Shard Cache.

Atur ini sebelum memulai sinkronisasi. Ukuran menerima nilai yang dapat dibaca manusia seperti 64gb:

export HF_HOME=/mnt/nvme/hf                 # chunk and shard caches on NVMe
export HF_XET_HIGH_PERFORMANCE=1            # use all cores and the full network
export HF_XET_SHARD_CACHE_SIZE_LIMIT=64gb   # keep the shard cache under free disk space

hf sync ./data hf://buckets/<namespace>/<bucket>/data

Pisahkan berdasarkan subpath (eksperimental)

Untuk dataset yang sangat besar, Anda dapat membagi sumber menjadi subpath dan menjalankan beberapa proses hf sync sekaligus. Pengujian awal menunjukkan bahwa throughput berskala secara linear, tetapi hal ini masih memerlukan validasi lebih lanjut. Dua aturan:

• Pisahkan berdasarkan data terkait, sehingga file dari setiap worker dapat dideduplikasi dengan baik satu sama lain.
• Beri setiap worker HF_HOME miliknya sendiri agar mereka tidak bersaing untuk cache. Setiap cache memakan ruang disk, jadi bagi HF_XET_SHARD_CACHE_SIZE_LIMIT di antara worker.

HF_HOME=/mnt/nvme/hf-a hf sync ./data/groupA hf://buckets/<namespace>/<bucket>/groupA &
HF_HOME=/mnt/nvme/hf-b hf sync ./data/groupB hf://buckets/<namespace>/<bucket>/groupB &
wait

Satu proses berbagi satu cache dan melakukan deduplikasi dengan optimal, sehingga hanya belah proses ketika satu proses tidak mampu memaksimalkan jaringan Anda.

Pemecahan Masalah

Dari AWS S3 atau penyimpanan yang kompatibel dengan S3

hf sync tidak membaca URL s3://, jadi pasang bucket sumber sebagai sistem berkas dengan Mountpoint for Amazon S3, lalu sinkronkan dari mount tersebut. Data Anda tetap melewati klien Xet, sehingga Anda mendapatkan deduplikasi sisi klien.

mount-s3 my-source-bucket /mnt/src
hf sync /mnt/src hf://buckets/<namespace>/<bucket>
umount /mnt/src

Untuk penyimpanan yang kompatibel dengan S3 seperti Cloudflare R2 atau MinIO, tambahkan --endpoint-url <url> ke mount-s3. Untuk bucket publik yang memungkinkan pembacaan anonim, seperti yang ada di registry AWS Open Data, tambahkan --no-sign-request. Verifikasi, penyetelan, dan pemecahan masalah sama seperti untuk data lokal.

Alternatif: rclone melalui gerbang S3

Gunakan ini jika Anda sudah menjalankan rclone dan lebih memilih untuk tidak melakukan mount. Trade-off-nya: rclone mengirim setiap byte melalui S3 gateway tanpa deduplikasi di sisi klien, sehingga mentransfer lebih banyak data daripada hf sync. Anda memerlukan kredensial S3 untuk gateway.

Gunakan rclone 1.70 atau lebih baru (periksa dengan rclone version, perbarui dari rclone downloads). Versi lama dapat kehabisan memori saat membuat daftar bucket yang sangat besar. Saran lama sering merekomendasikan --fast-list; dengan rclone terbaru Anda tidak membutuhkannya, dan pada daftar yang sangat besar opsi ini menyimpan semuanya di memori dan dapat menyebabkan kegagalan yang sama.

Tambahkan gateway sebagai remote di ~/.config/rclone/rclone.conf, di samping remote untuk sumber Anda (aws di bawah):

[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 = 256M
chunk_size = 256M

Gateway hanya mendukung ListObjectsV2, sehingga list_version = 2 diperlukan. Dengan 256M bagian, file besar naik dalam jumlah bagian yang jauh lebih sedikit dibandingkan dengan default 5M rclone. rclone menyimpan 4 bagian per transfer di memori, sehingga --transfers 16 di bawah ini membutuhkan sekitar 16 GB RAM; turunkan nilainya pada mesin yang lebih kecil. Kemudian salin dan periksa:

rclone copy aws:my-source-bucket hf:<bucket> --transfers 16 --checkers 16 --progress
rclone check aws:my-source-bucket hf:<bucket>

rclone copy hanya mentransfer objek yang hilang atau berubah, sehingga aman untuk dijalankan ulang guna melanjutkan. Sebelum impor besar, baca batasan gateway, terutama aturan penamaan kunci objek.

Dari Google Cloud Storage atau Azure Blob Storage

Pendekatan yang sama seperti S3: mount sumber dengan driver cloud-nya sendiri, lalu jalankan hf sync.

Google Cloud Storage: mount dengan gcsfuse.

gcsfuse my-gcs-bucket /mnt/src
hf sync /mnt/src hf://buckets/<namespace>/<bucket>

Azure Blob Storage: mount dengan blobfuse2. File konfigurasi menamai akun penyimpanan dan kontainer Anda.

blobfuse2 mount /mnt/src --config-file=./blobfuse2.yaml
hf sync /mnt/src hf://buckets/<namespace>/<bucket>

Tanpa mount, Anda dapat menggunakan rclone (membaca GCS dan Azure secara native; gunakan ulang remote hf di atas, dengan trade-off tanpa deduplikasi yang sama), atau jalankan migrasi sebagai Job.

Jalankan migrasi di latar belakang dengan Jobs

Jobs menjalankan skrip pada komputasi Hugging Face: Anda memilih perangkat keras, meluncurkannya dari CLI, dan bayar per menit. Gunakan ini ketika Anda ingin migrasi panjang multi-TB berjalan tanpa pengawasan, bukan di laptop Anda atau sesi yang harus tetap terbuka.

1. Tulis skrip migrasi (migrate.py). Contoh ini menyalin setiap objek dalam prefix S3 ke dalam bucket melalui klien Xet, sehingga penulisan dideduplikasi. Ini cocok untuk penyalinan sekali dari prefix berukuran sedang; untuk prefix yang sangat besar, lihat hf-s3ream. Sesuaikan pengaturan di bagian atas:

# /// script
# dependencies = ["huggingface_hub", "boto3", "tqdm"]
# ///
import boto3
from botocore import UNSIGNED
from botocore.config import Config
from huggingface_hub import HfFileSystem
from tqdm.contrib.concurrent import thread_map

# --- adapt these ---
SRC_BUCKET = "my-source-bucket"
SRC_PREFIX = "some/prefix/"
DST = "buckets/<namespace>/<bucket>"
WORKERS = 8   # files copied in parallel
# -------------------

s3 = boto3.client("s3")   # AWS credentials come from the Job's secrets
# For a public bucket (for example from the AWS Open Data registry), read anonymously
# instead, and drop the AWS secrets from the launch command:
# s3 = boto3.client("s3", config=Config(signature_version=UNSIGNED))
fs = HfFileSystem()       # HF token comes from the Job's HF_TOKEN secret

# List the destination once: {path: size} of the files already copied
done = {path: info["size"] for path, info in fs.find(DST, detail=True).items()}

# List the source and keep the objects not copied yet
todo = []
pages = s3.get_paginator("list_objects_v2").paginate(Bucket=SRC_BUCKET, Prefix=SRC_PREFIX)
for page in pages:
    for obj in page.get("Contents", []):
        key = obj["Key"]
        if key.endswith("/"):
            continue  # folder marker: bucket keys can't end with "/"
        if done.get(f"{DST}/{key}") != obj["Size"]:
            todo.append(key)

def copy(key):
    body = s3.get_object(Bucket=SRC_BUCKET, Key=key)["Body"]
    with fs.open(f"{DST}/{key}", "wb") as out:
        for chunk in iter(lambda: body.read(64 << 20), b""):
            out.write(chunk)

# Copy WORKERS files at a time, with a progress bar
thread_map(copy, todo, max_workers=WORKERS)

• Setiap objek diproses di disk Job dan diunggah saat ditutup, sehingga disk harus mampu menampung WORKERS objek terbesar Anda secara bersamaan. Naikkan WORKERS untuk mempercepat banyak objek kecil; turunkan untuk objek yang sangat besar.
• File yang sudah ada di bucket dengan ukuran yang sama akan dilewati, sehingga menjalankan ulang skrip akan melanjutkan salinan yang terputus. Skrip ini tidak akan menyalin ulang file sumber yang berubah tetapi tetap memiliki ukuran yang sama: untuk menjaga bucket tetap selaras dengan sumber yang berubah, pasang sumber dan jalankan hf sync sebagai gantinya.

Untuk GCS atau Azure, ganti boto3 dengan SDK cloud tersebut (google-cloud-storage, azure-storage-blob) dan sesuaikan panggilan listing dan read. Bagian tujuan tetap sama.

2. Jalankan sebagai Job latar belakang, dengan meneruskan kredensial Anda sebagai secrets:

hf jobs uv run --detach --flavor cpu-performance --timeout 24h \
  --secrets HF_TOKEN \
  --secrets AWS_ACCESS_KEY_ID \
  --secrets AWS_SECRET_ACCESS_KEY \
  migrate.py

Setiap --secrets NAME meneruskan nilai variabel tersebut dari lingkungan Anda (untuk HF_TOKEN, token yang sedang login digunakan jika tidak disetel). Job berhenti setelah 30 menit secara default, jadi setel --timeout cukup lama untuk seluruh transfer; jika Job berhenti lebih awal, jalankan lagi dan file yang sudah disalin akan dilewati.

--detach langsung mengembalikan Job ID. Pantau progres dengan hf jobs logs -f <job_id>, lihat daftar run dengan hf jobs ls, dan lihat opsi hardware dengan hf jobs hardware.

Dari repositori Hub atau bucket lain

Jika data sudah ada di Hub, dalam repositori model atau dataset atau bucket lain, salin secara server-side. Untuk file yang dilacak Xet, hanya hash konten yang dipindahkan, sehingga penyalinan hampir seketika dan tidak ada yang diunggah ulang.

# From a dataset repository into a bucket
hf buckets cp hf://datasets/<org>/<dataset>/<path> hf://buckets/<namespace>/<bucket>/<path>

# From one bucket to another
hf buckets cp hf://buckets/<namespace>/<bucket-a>/<path> hf://buckets/<namespace>/<bucket-b>/<path>

• Sumber dan tujuan harus berada di wilayah penyimpanan yang sama.
• Anda memerlukan akses baca ke sumber dan akses tulis ke tujuan.
• File kecil yang tidak dilacak Xet (konfigurasi, README) diunduh dan diunggah ulang secara otomatis.
• Menyalin dari bucket kembali ke repositori belum tersedia; fitur ini sudah masuk dalam roadmap.

Lihat Menyalin file antar repositori dan bucket untuk ekuivalen Python-nya.

Prefiks S3 yang sangat besar dengan hf-s3ream

hf-s3ream adalah alat komunitas tahap awal (alpha), bukan produk Hugging Face yang didukung secara resmi. Uji coba pada prefix kecil sebelum menggunakannya untuk migrasi besar.

hf-s3ream (source di GitHub, Apache-2.0) menjalankan salinan besar dari S3 ke bucket melalui antarmuka web:

1. Masuk dengan Hugging Face.
2. Masukkan prefiks sumber S3, bucket tujuan, dan kredensial AWS Anda. Untuk bucket publik yang memungkinkan pembacaan anonim, aktifkan Public bucket: kredensial AWS tidak diperlukan, dan Jobs membaca S3 tanpa tanda tangan.
3. Analyze menjalankan dry run yang murah untuk memeriksa akses, mendeteksi wilayah sumber, dan merekomendasikan konfigurasi. Bucket tujuan (privat) akan dibuat jika belum ada.
4. Run meluncurkan job planner. Planner membangun rencana salin berbasis rentang, memulai job copier, dan menampilkan progres pada grafik langsung. Proses salin tetap berjalan jika Anda menutup tab, tetapi halaman tidak akan menyambung kembali ke proses tersebut. Untuk menghentikan salinan, klik Stop copy, atau batalkan job planner (hf jobs cancel <planner-job-id>): planner akan membatalkan copier-nya.

hf-s3ream berjalan di Jobs di bawah akun Anda, sehingga tagihan Jobs ditagihkan kepada Anda. S3 bucket yang hanya mengizinkan akses dari jaringan privat (VPC) tidak dapat dijangkau dari Jobs.

Di mana menjalankan migrasi besar

Untuk migrasi multi-TB, Anda biasanya akan menjalankan transfer di VM cloud, bukan di laptop. Jika Anda lebih memilih untuk tidak mengelola VM, jalankan sebagai Job.

• Jalankan di cloud dan region yang sama dengan sumber Anda. Membaca sumber melalui jaringan lokal adalah yang tercepat dan termurah, dan egress dari cloud sumber biasanya merupakan biaya terbesar. Unggahan kemudian dilakukan melalui internet ke Hugging Face (region AS berada di AWS us-east-1).
• Gunakan satu proses dengan banyak thread. Satu hf sync dalam mode berkinerja tinggi berbagi satu cache deduplikasi. Pisahkan berdasarkan subpath hanya jika satu proses tidak dapat memaksimalkan jaringan Anda.
• Jaga agar proses panjang tetap berjalan. Melalui SSH, mulai migrasi di dalam tmux (atau screen, atau nohup) agar tetap berjalan jika sesi terputus: tmux new -s migrate, lepaskan dengan Ctrl-b lalu d, dan hubungkan kembali nanti dengan tmux attach -t migrate.

Titik awal penentuan ukuran, untuk divalidasi pada uji coba:

Langkah selanjutnya

• Gunakan data di tempatnya. Pasang bucket sebagai sistem file lokal dengan hf-mount, atau sebagai volume di Jobs dan Spaces.
• Bacalah dari alat Anda. pandas, Dask, PyArrow, Daft, DuckDB, 🤗 Datasets, dan Spark membaca jalur hf://buckets/... secara langsung. Lihat Integrasi Bucket.

Jangan jalankan ingest massal melalui mount. hf-mount menampung penulisan di cache di disk (/tmp/hf-mount-cache secara default), dan migrasi besar melaluinya dapat memenuhi disk tersebut. Gunakan salah satu jalur di atas untuk memasukkan data ke bucket. Jika Anda harus menulis banyak data melalui mount, arahkan cache ke disk dengan ruang kosong yang cukup: hf-mount start --cache-dir /mnt/big bucket <namespace>/<bucket> /mnt/data (flag ini diletakkan sebelum bucket).