Verileri Depolama Kovalarına Taşıma

Bu kılavuz, büyük veri setlerini şu an bulundukları yerden (yerel disk, başka bir bulut veya Hub) bir Storage Bucket'a nasıl taşıyacağınızı gösterir. Kaynağınızı aşağıdaki tabloda bulun ve ilgili bölüme gidin.

Mümkün olan her yerde verilerinizi bir dosya sistemi olarak okunabilir hale getirin ve hf sync komutunu çalıştırın. Bu komut istemcide yinelenen verileri ayıklar, bu sayede ham bir kopyaya kıyasla daha az bayt yüklersiniz.

Genel Bakış

Neden hf sync varsayılandır:

• Daha az yüklersiniz. hf sync, verilerinizi önce parçalara ayırıp kopyalarını kaldıran Xet istemcisi üzerinden yükleme yapar; bu sayede yalnızca Hub'un daha önce görmediği parçalar gönderilir. Ham bir kopya (örneğin S3 geçidi üzerinden rclone) her baytı aktarır.
• En az onun kadar hızlıdır. Şimdiye kadar desteklediğimiz geçişlerde, bir kaynak üzerinden hf sync kullanımı, veri aktarım hızında rclone ile eşleşmiş veya onu geride bırakmıştır.

Başlamadan önce

Bu kılavuzdaki tüm komutlar, Hugging Face CLI olan hf kullanır. Yardım çıktısı ajanlar tarafından okunabilir olduğundan, bir kodlama ajanı sizin için bir migrasyonu oluşturabilir ve izleyebilir (bkz. CLI for AI Agents). Komutları büyük ölçekte çalıştırmadan önce gözden geçirin.

1. CLI'yi yükleyin. Xet istemcisi bununla birlikte gelir.

   Kopyalandı

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

2. Giriş yapın Yazma erişimine sahip bir jetonla (bir tane oluşturun):

   Kopyalandı

   hf auth login
   hf auth whoami

3. Hedef kovayı oluşturun. <namespace> kullanıcı adınız veya organizasyonunuzdur. --region verilmediğinde kova, varsayılan depolama bölgesine gider; Team & Enterprise planları dışında bu bölge her zaman ABD'dir. Bu planlarda seçim yapmak için --region us veya --region eu parametrelerini iletin.

   Kopyalandı

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

Bir test çalıştırmasıyla başlayın. Hangi yolu kullanırsanız kullanın, bunu küçük bir alt kümede (bir klasör veya --include deseni) prova edin, sonucu --dry-run ve hf buckets ls ile kontrol edin, ardından tam ölçekli geçişi başlatın. Bu kılavuzdaki her yol yeniden başlatılabilir, bu nedenle bir test çalıştırmasının maliyeti yoktur.

Yerel diskten veya bir küme dosya sisteminden

Verileriniz yerel bir diskte, bağlı bir birimde veya küme geçici alanında (scratch) olduğunda bunu kullanın: makinenin dosya olarak okuyabileceği her şey. Aşağıdaki tüm bulut yollarında da kaynak bağlandıktan (mount) sonra son adım budur.

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

hf sync kaynak ve hedefi karşılaştırır ve yalnızca farkı aktarır; bu nedenle aynı komutun yeniden çalıştırılması, yarıda kalmış bir göçü kaldığı yerden devam ettirir: zaten yüklenmiş dosyalar atlanır. Yaygın varyantlar:

# 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/*"

Çalıştırılmadan önce büyük bir geçişi gözden geçirmek için planı bir dosyaya yazın, kontrol edin ve ardından uygulayın. Bu, kuru çalıştırma için bir kez ve gerçek çalıştırma için bir kez olmak üzere iki tarama yerine, kaynak ve hedefi yalnızca bir kez tarar.

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

Planı oluşturduğunuz dizinden --apply komutunu çalıştırın, çünkü plan kaynak yolunu girdiğiniz gibi kaydeder. --apply daha önce yüklenenleri kontrol etmez; bu nedenle yarıda kalan bir çalıştırmayı sürdürmek için düz hf sync komutunu yeniden çalıştırın.

Doğrulamak için, kuru çalışmanın (dry run) aktarılacak hiçbir şeyin kalmadığından emin olun ve içeriği örnek olarak kontrol edin:

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

Ayar

• Önbelleği hızlı diskte tutun. Xet istemcisi, parçaları ve bir yinelenme giderme dizinini (shard önbelleği) HF_HOME altında önbelleğe alır. Ana dizininiz NVMe üzerinde değilse HF_HOME değerini yerel NVMe diskinize yönlendirin.
• Kaynakları yeterli bir makinede toplu taşımalar için yüksek performans modunu etkinleştirin. HF_XET_HIGH_PERFORMANCE=1 eşzamanlılığı, tampon boyutlarını ve aynı anda işlenen dosya sayısını artırır; böylece istemci tüm CPU çekirdeklerini kullanabilir ve ağı doyurabilir. Bu mod, yüksek bant genişliğine ve hızlı diske sahip makineler için tasarlanmıştır; hf_xet sürüm 1.7.0’tan önceki sürümlerde yalnızca en az 64 GB RAM ile kullanın (kendi RAM’inizi hf env ile kontrol edin). Ortam Değişkenleri bölümüne bakın.
• Parça önbelleğini sınırlayın. Boyut sınırı esnektir: önbellek yalnızca bir çalıştırmanın başlangıcında budanır, bu nedenle tek bir uzun çalıştırma sırasında sınırın çok üzerine çıkabilir. Büyük bir göçte, özellikle yüksek performans modunda, yüzlerce GB'a kadar büyüyebilir ve diski doldurarak çalıştırmanın yarıda kesilmesine neden olabilir. HF_XET_SHARD_CACHE_SIZE_LIMIT değerini, boş disk alanınızın rahatça altında ancak ihtiyacınızın altında olmayacak şekilde ayarlayın: boyutu X olan bir önbellek, yaklaşık 1000 × X büyüklüğündeki verilerle çakışma giderme yapar. Parça Önbelleği bölümüne bakın.

Senkronizasyona başlamadan önce bunları ayarlayın. Boyutlar, 64gb gibi insan tarafından okunabilir değerleri kabul eder:

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

Alt yol üzerinden böl (deneysel)

Çok büyük veri kümeleri için, kaynağı alt yollarına bölebilir ve birden fazla hf sync sürecini aynı anda çalıştırabilirsiniz. Erken testler, aktarım hızının yaklaşık doğrusal olarak arttığını göstermektedir ancak bunun daha fazla doğrulanması gerekir. İki kural:

• İlgili verilere göre bölün, böylece her işçinin dosyaları birbirine karşı iyi bir şekilde yinelenmeyi önlesin.
• Her işçiye kendi HF_HOME değerini verin ki önbellek için yarışmasınlar. Her önbellek disk alanı kapladığından, HF_XET_SHARD_CACHE_SIZE_LIMIT değerini işçiler arasında bölüştürün.

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

Tek bir süreç tek bir önbelleği paylaşır ve en iyi şekilde yinelenenleri ayıklar; bu nedenle yalnızca tek bir sürecin ağınızı doyuramadığı durumlarda bölün.

Sorun Giderme

AWS S3 veya S3 uyumlu depolamadan

hf sync, s3:// URL’lerini okumaz; bu nedenle kaynak kovayı Mountpoint for Amazon S3 ile bir dosya sistemi olarak bağlayın ve ardından senkronizasyonu bu bağlantıdan yapın. Verileriniz yine de Xet istemcisi üzerinden geçer, bu sayede istemci tarafında yinelenen veri kaldırma (deduplication) özelliğinden yararlanırsınız.

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

Cloudflare R2 veya MinIO gibi S3 uyumlu depolar için mount-s3 komutuna --endpoint-url <url> ekleyin. AWS Open Data kayıt defterindeki gibi anonim okumalara izin veren herkese açık bir varış noktası için --no-sign-request ekleyin. Doğrulama, ayarlama ve sorun giderme adımları yerel veri için olanlarla aynıdır.

Alternatif: S3 geçidi üzerinden rclone

Zaten rclone çalıştırıyorsanız ve bağlamayı (mount) tercih etmiyorsanız bunu kullanın. Takas: rclone, istemci tarafında kopya azaltma (deduplication) olmadan her baytı S3 gateway üzerinden gönderir, bu nedenle hf sync’ten daha fazla veri aktarır. Gateway için S3 kimlik bilgilerine ihtiyacınız vardır.

rclone 1.70 veya daha yeni bir sürüm kullanın (rclone version ile kontrol edin, rclone downloads adresinden yükseltin). Eski sürümler, çok büyük bucket’ları listelerken bellek yetersizliği yaşayabilir. Eski öneriler genellikle --fast-list bayrağını tavsiye eder; güncel bir rclone sürümünde buna gerek yoktur ve devasa bir listelemede her şeyi bellekte tutarak aynı hataya neden olabilir.

~/.config/rclone/rclone.conf dosyasına, kaynak uzak konumunuzun (aws) yanına gateway'i bir uzak konum olarak ekleyin:

[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 yalnızca ListObjectsV2'yi desteklediğinden list_version = 2 zorunludur. 256M parça ile büyük dosyalar, rclone'ün 5M varsayılanına kıyasla çok daha az parçaya bölünür. rclone, aktarım başına 4 parçayı bellekte tuttuğundan aşağıdaki --transfers 16 yaklaşık 16 GB RAM gerektirir; daha küçük bir makinede bu değeri düşürün. Ardından kopyalayın ve kontrol edin:

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

rclone copy yalnızca eksik veya değişmiş nesneleri aktarır, bu nedenle kaldığı yerden devam etmek için yeniden çalıştırması güvenlidir. Büyük bir içe aktarma işleminden önce, özellikle nesne anahtarı adlandırma kurallarını içeren gateway sınırlamalarını okuyun.

Google Cloud Storage veya Azure Blob Storage'dan

S3 ile aynı yaklaşım: kaynağı, bulutunun kendi sürücüsüyle bağlayın, ardından hf sync komutunu çalıştırın.

Google Cloud Storage: gcsfuse ile bağlayın.

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

Azure Blob Storage: blobfuse2 ile bağlayın. Yapılandırma dosyası depolama hesabınızı ve konteynerinizi belirtir.

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

Mount olmadan, rclone kullanabilirsiniz (GCS ve Azure'u yerel olarak okur; yukarıdaki hf uzak konumunu yukarıdaki aynı şekilde, aynı deduplikasyon olmayan ödünleşimiyle yeniden kullanın) veya migrasyonu bir Job olarak çalıştırın.

Göçü arka planda Jobs ile çalıştırın

Jobs, Hugging Face hesaplama altyapısında bir betik çalıştırır: donanımı seçersiniz, CLI üzerinden başlatırsınız ve dakika başına ödeme yaparsınız. Uzun süreli, çoklu TB ölçeğinde bir geçişin laptopunuzda veya açık tutmanız gereken bir oturumda değil, gözetimsiz olarak çalışmasını istediğinizde kullanın.

1. Göç betiğini yazın (migrate.py). Bu örnek, S3 önekindeki her nesneyi Xet istemcisi aracılığıyla bir kovaya kopyalar; böylece yazmalar ayıklanır. Orta ölçekli bir önek için tek seferlik kopyalama işlemlerine uygundur; çok büyük önekler için hf-s3ream bölümüne bakın. Başlangıçtaki ayarları uyarlayın:

# /// 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)

• Her nesne, Job diskinde hazırlanır ve kapatıldığında yüklenir; bu nedenle disk, en büyük nesnelerinizin WORKERS kadarını aynı anda barındırmalıdır. Birçok küçük nesne için hızlandırmak istiyorsanız WORKERS değerini artırın; çok büyük nesneler için ise düşürün.
• Kova içinde aynı boyuta sahip olan dosyalar atlanır, bu nedenle betiğin yeniden çalıştırılması yarıda kalmış bir kopyalama işlemini kaldığı yerden devam ettirir. Boyutu değişmeden içeriği değişen bir kaynak dosya yeniden kopyalanmaz: Değişen bir kaynakla kovanın senkronize tutulması için bunun yerine kaynağı bağlayıp hf sync komutunu çalıştırın.

GCS veya Azure için boto3 yerine ilgili bulutun SDK’sını (google-cloud-storage, azure-storage-blob) kullanın ve listeleme ile okuma çağrılarını buna göre ayarlayın. Hedef tarafı aynı kalır.

2. Arka plan Job'u olarak başlatın, kimlik bilgilerinizi gizli değerler olarak iletin:

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

Her --secrets NAME, o değişkenin değerini ortamınızdan geçirir (HF_TOKEN için, ayarlanmamışsa oturum açmış olduğunuz token kullanılır). İşler varsayılan olarak 30 dakika sonra durur, bu nedenle tüm aktarım için --timeout değerini yeterince uzun ayarlayın; bir İş erken durursa, onu yeniden başlatın ve zaten kopyalanmış dosyaları atlar.

--detach bir İş ID'si ile hemen döner. İlerlemeyi hf jobs logs -f <job_id> ile takip edin, çalıştırmaları hf jobs ls ile listeleyin ve donanım seçeneklerini hf jobs hardware ile görüntüleyin.

Bir Hub deposundan veya başka bir kovadan

Veri zaten Hub'da, bir model veya veri seti deposunda ya da başka bir kovada ise, kopyalamayı sunucu tarafında yapın. Xet tarafından izlenen dosyalar için yalnızca içerik özetleri taşınır; bu nedenle kopyalama neredeyse anında gerçekleşir ve hiçbir şey yeniden yüklenmez.

# 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>

• Kaynak ve hedef aynı depolama bölgesinde olmalıdır.
• Kaynağa okuma erişimine ve hedefe yazma erişimine ihtiyacınız var.
• Xet tarafından takip edilmeyen küçük dosyalar (yapılandırmalar, README'ler) otomatik olarak indirilir ve yeniden yüklenir.
• Bir depodan bir kovaya kopyalama henüz mevcut değil; yol haritasında yer alıyor.

Python karşılığı için Depolar ve varlıklar arasında dosya kopyalama bölümüne bakın.

hf-s3ream ile çok büyük S3 önekleri

hf-s3ream, resmi olarak desteklenen bir Hugging Face ürünü değil, erken aşamada (alpha) bir topluluk aracıdır. Büyük bir migrasyon için kullanmadan önce küçük bir prefix üzerinde test edin.

hf-s3ream (GitHub'daki kaynak, Apache-2.0) bir web arayüzünden büyük bir S3'den kovaya kopyalama işlemini çalıştırır:

1. Hugging Face ile oturum açın.
2. S3 kaynak önekin, hedef varlık kovası ve AWS kimlik bilgilerinizi girin. Anonim okumalara izin veren herkese açık bir varlık kovası için Herkese açık varlık kovası seçeneğini etkinleştirin: AWS kimlik bilgisi gerekmez ve İşler S3'e imzasız olarak okur.
3. Analyze, erişimi kontrol eden, kaynak bölgeyi tespit eden ve bir yapılandırma öneren ucuz bir kuru çalıştırma (dry run) gerçekleştirir. Var olmayan bir varış noktası kovası (private) oluşturur.
4. Run bir planlayıcı işi başlatır. Planlayıcı, aralık tabanlı bir kopyalama planı oluşturur, kopyalayıcı işlerini başlatır ve ilerlemeyi canlı bir grafik üzerinde gösterir. Sekmeyi kapatsanız bile kopyalama işlemi devam eder, ancak sayfa ona yeniden bağlanmaz. Kopyalamayı durdurmak için Stop copy düğmesine tıklayın veya planlayıcı işini iptal edin (hf jobs cancel <planner-job-id>): planlayıcı, kopyalayıcılarını iptal eder.

hf-s3ream hesabınız altındaki Jobs üzerinde çalıştığından, Jobs faturaları size yansıtılır. Yalnızca özel bir ağdan (VPC) erişime izin veren S3 varlıkları, Jobs üzerinden erişilemez.

Büyük bir migrasyonun nerede çalıştırılacağı

Çoklu TB ölçeğinde bir geçiş için aktarımı genellikle bir dizüstü bilgisayar yerine bulut VM üzerinde çalıştırırsınız. Bir VM yönetmek istemiyorsanız, bir Job olarak çalıştırın.

• Kaynağınızla aynı bulutta ve bölgede çalıştırın. Kaynağı yerel ağ üzerinden okumak en hızlı ve en ucuz yöntemdir ve kaynak buluttan çıkış (egress) genellikle en büyük maliyet kalemidir. Yüklemeler daha sonra internet üzerinden Hugging Face'e gider (ABD bölgesi AWS us-east-1 içindedir).
• Bir süreç ve çok sayıda iş parçacığı kullanın. Yüksek performans modundaki tek bir hf sync komutu, tek bir yinelenen veri önbelleğini paylaşır. Alt yola göre bölme yalnızca tek bir sürecin ağınızı doyuramadığı durumlarda yapılmalıdır.
• Uzun süren çalışmaları ayakta tutun. SSH üzerinden, oturum kesilse bile devam etmesi için migrasyonu tmux (veya screen, ya da nohup) içinde başlatın: tmux new -s migrate, Ctrl-b ardından d ile ayrılın ve daha sonra tmux attach -t migrate ile yeniden bağlanın.

Test çalışmasında doğrulanacak başlangıç noktaları:

Sonraki adımlar

• Verileri yerinde kullanın. hf-mount ile kovayı yerel bir dosya sistemi olarak veya Jobs ve Spaces'te bir birim olarak bağlayın.
• Araçlarınızdan okuyun. pandas, Dask, PyArrow, Daft, DuckDB, 🤗 Datasets ve Spark, hf://buckets/... yollarını doğrudan okur. Kova Entegrasyonları bölümüne bakın.

Toplu veri aktarımını bir mount üzerinden çalıştırmayın. hf-mount, yazma işlemlerini disk üzerindeki bir önbellekte (/tmp/hf-mount-cache varsayılan olarak) bekletir ve bu yol üzerinden yapılacak büyük bir göç, o diski doldurabilir. Verileri bir kovaya almak için yukarıdaki yollardan birini kullanın. Mount üzerinden çok fazla yazma işlemi yapmanız gerekiyorsa, önbelleği bol boş alanı olan bir diske yönlendirin: hf-mount start --cache-dir /mnt/big bucket <namespace>/<bucket> /mnt/data (bayrak, bucket parametresinden önce gelir).