Depolama Kovaları

Storage Buckets, Hugging Face Hub'da Xet depolama altyapısıyla desteklenen, S3 benzeri nesne depolama sunan bir depo türüdür. Git tabanlı depolardan (modeller, veri kümeleri, Spaces) farklı olarak bucket'lar sürüm yönetimi olmayan ve değiştirilebilir olup, eğitim checkpoint'leri, günlükler, ara artefaktlar veya sürüm kontrolüne ihtiyaç duymayan herhangi bir büyük dosya koleksiyonu gibi basit ve hızlı depolama gerektiren kullanım senaryoları için tasarlanmıştır.

Kovalarla Hub web arayüzü, hf CLI veya Python API aracılığıyla etkileşime girebilirsiniz.

Buckets tüm kullanıcılar ve kuruluşlar için kullanılabilir. Fiyatlandırma detayları için hf.co/storage adresine bakın.

Araçlarınızdan bucket verilerine nasıl erişileceğini (dosya sistemi olarak bağlama, hf:// yolları, Jobs/Spaces içindeki volume bağlamaları) görmek için Erişim Desenleri, mevcut S3 araçlarını (AWS CLI, boto3, s5cmd) kullanmak için S3-Uyumlu API ve pandas, Dask, Spark gibi popüler veri kütüphanelerinde kullanıma hazır parçalar için Bucket Entegrasyonları bölümlerine bakın.

Buckets vs Depolar

Hub, sürüm kontrollü ve işbirlikçi çalışmalar için Git tabanlı depolar ve hızlı, değiştirilebilir nesne depolama için kovalar olmak üzere iki tür depolama sunar.

Sürüm geçmişi, iş birliği özellikleri (PR'ler, tartışmalar) ve kütüphane entegrasyonları istediğinizde depolar kullanın. Sık sık değişen veriler için hızlı, değiştirilebilir depolama alanına ihtiyacınız olduğunda kovalar kullanın — dosyalar yerinde üzerine yazılabilir veya silinebilir.

Bir Bucket Oluşturma

Hub arayüzünden

1. huggingface.co/new-bucket adresine gidin:

2. Kova sahibini belirtin: bu, siz veya bağlı olduğunuz kuruluşlardan herhangi biri olabilir.

3. Bir varlık adı girin.

4. Kovanın herkese açık mı yoksa özel mi olacağını seçin.

5. İsteğe bağlı olarak, verilerinizi başlangıçta hesaplama kaynaklarınıza daha yakın önbelleğe almak için CDN ön ısıtma bölgelerini önceden seçebilirsiniz.

Kova oluşturulduktan sonra kova sayfasını görmelisiniz:

CLI'den

# 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

Python'dan

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

Görünürlüğü değiştirme

Bir varlığın görünürlüğünü oluşturma sonrasında değiştirebilirsiniz:

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

Silme, taşıma ve varlık listeleme dahil olmak üzere tam Python API referansı için huggingface_hub Buckets kılavuzuna bakın.

Hub'da Kovaları (Buckets) Göz Atma

Her bucket, içeriğini görüntüleyebileceğiniz, dizinlerde gezinebileceğiniz ve dosya ayrıntılarını görebileceğiniz Hub'da bir sayfaya sahiptir. Bucket sayfaları https://huggingface.co/buckets/<owner>/<bucket-name> adresinde bulunabilir.

README görüntüleme

Kovağınızdaki bir dizinde README.md dosyası varsa, Hub bu dosyayı ilgili dizinin sayfasındaki dosya listesinin altında görüntüler. Bu özellik, hem kovanın kök dizininde hem de herhangi bir alt dizinde çalışır; kovanın içeriğini, verilerin nasıl organize edildiğini veya aşağı akış araçlarının bu verileri nasıl kullanması gerektiğini belgelemek için faydalıdır.

CLI'den listeleme

Ayrıca, varlık (bucket) içeriğini CLI'den de listeleyebilirsiniz:

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

Dosyaları Yönetme

Dosyaları Hub'daki bucket sayfasından doğrudan yükleyebilir ve indirebilir veya programatik erişim için CLI ve Python API'sini kullanabilirsiniz. Bucket dosyaları hf://buckets/ yolları kullanılarak referans alınır (ör. hf://buckets/username/my-bucket/path/to/file). hf buckets cp komutu tekil dosya aktarımlarını ele alırken hf buckets sync dizinler için daha uygundur. Tüm komutlar her iki yönde de çalışır — yerelden uzaktan ve uzaktan yerelde.

Verileriniz zaten bir model, veri seti veya Space deposunda (veya başka bir kovada) bulunuyorsa, hf buckets cp ile sunucu tarafında kopyalayabilirsiniz — indirme veya yeniden yükleme gerekmez. Depolar ve kovalar arasında dosya kopyalama bölümüne bakın.

Dosyaları yükleme

Hızlı yüklemeler için dosyaları tarayıcınızda doğrudan bucket sayfasına sürükleyip bırakabilirsiniz. Programatik kullanım için hf buckets cp, tekil dosyaları bir bucketa kopyalar. Kaynak bir yerel yol, hedef ise bir hf://buckets/ yoludur. Ayrıca stdin'den veri aktarabilirsiniz; bu, programatik olarak üretilen içerikler için kullanışlıdır.

CLI:

# 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

Python'da, tek bir çağrıda bir veya daha fazla dosyayı yüklemek için batch_bucket_files kullanın. Her giriş, (local_path, remote_path) biçiminde bir demettir.

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

Daha fazla yükleme seçeneği (ham baytlar, birleşik yükleme+silme vb.) için huggingface_hub yükleme kılavuzuna bakın.

Dosyaları indirme

Bireysel dosyaları, Hub'daki bucket sayfasında ilgili dosyaya tıklayarak doğrudan indirebilirsiniz. Programatik erişim için indirme, yükleme sözdizimini yansıtır: hf buckets cp komutunda kaynak ve hedefi yer değiştirin. Ayrıca, hedef olarak - kullanarak bir dosyayı stdout'a akış olarak yönlendirebilir ve bucket içeriğini doğrudan diğer araçlara borulayabilirsiniz.

CLI:

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

Python'da, download_bucket_files işlevini (remote_path, local_path) demetlerinden oluşan bir listeyle kullanın.

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

Önceden alınmış meta verilerle daha hızlı indirmeler için huggingface_hub indirme kılavuzuna bakın.

Dizinleri senkronize etme

sync komutu, rsync veya aws s3 sync gibi çalışır — kaynak ve hedefi karşılaştırır ve yalnızca değişen dosyaları aktarır. Bu, yerel bir dizini ve bir kovayı (bucket) senkronize tutmanın en verimli yoludur. Varsayılan olarak sync yalnızca dosyaları ekler ve günceller. Kaynakta artık bulunmayan dosyaları hedeften de kaldırmak için --delete parametresini iletin. Hiçbir şeyi gerçekten aktarmadan nelerin olacağını önizlemek için --dry-run parametresini kullanın.

CLI:

# 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, hf buckets sync için kullanışlı bir takma addır.

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

sync komutu, filtreleme (--include, --exclude), karşılaştırma modları (--ignore-times, --existing) ve işlemleri uygulamadan önce incelemek için planla ve uygula iş akışını destekler. Tüm seçenekler için huggingface_hub senkronizasyon kılavuzuna bakın.

Dosyaları silme

Bucket'ler sürüm yönetimi yapılmadığı için silme işlemleri anında ve kalıcıdır — silinen bir dosyayı geri getirmenin bir yolu yoktur. Dosyaları silmeden önce, özellikle --recursive kullanırken, iki kez kontrol etmek için --dry-run kullanın.

CLI:

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

Daha fazla silme seçeneği (desen tabanlı filtreleme, özyinelemeli kaldırma vb.) için huggingface_hub silme kılavuzuna bakın.

Depolar ve varlıklar arasında dosya kopyalama

Xet tarafından izlenen dosyaları, veriyi yeniden yüklemeye gerek kalmadan herhangi bir depodan (model, veri seti, Space) veya kovadan hedef kovaya kopyalayabilirsiniz. Kopyalama sunucu tarafında gerçekleşir: yalnızca Xet içerik özetleri taşınır, bu sayede parça düzeyinde yinelenen veri kaldırma sayesinde çok büyük dosyalar bile anında kopyalanır.

Yalnızca Xet tarafından izlenen dosyalar sunucu sunucuya kopyalanır. Küçük Xet dışı dosyalar (ör. yapılandırma dosyaları ve README'ler) otomatik olarak indirilir ve yeniden yüklenir. Sunucu tarafında kopyalama, kaynak ve hedefin aynı depolama bölgesinde bulunmasını da gerektirir.

CLI:

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

Kaynak depo veya kovaya okuma erişimine ve hedef kovaya yazma erişimine ihtiyacınız vardır.

Bir depodan (model, veri seti, Space) bir kovaya yeniden yüklemeye gerek kalmadan verinin ters yönde aktarılmasının henüz mümkün olmadığını, ancak bunun yol haritasında yer aldığını unutmayın.

Değişiklikleri İzleme

Buckets değiştirilebilir olduğundan, bir bucket'ın görünümünü tutan araçlar — mount'lar, dosya sistemi katmanları, senkronizasyon daemon'ları, panolar — dosyaların ne zaman değiştiğini bilmelidir. İki mekanizma mevcuttur:

• Webhook'lar: Kontrol ettiğiniz bir sunucuya HTTP geri çağrıları veya her değişiklikte başlatılan bir Job — bkz. Process new files in a bucket with Jobs.
• Canlı takip: istemcinizin abone olduğu sunucu gönderimli olaylar akışı.

Canlı takip

GET https://huggingface.co/api/buckets/<owner>/<bucket-name>/events, bir bucket’ın dosya değişikliklerini server-sent events olarak akışa alır. İstek, Accept: text/event-stream başlığını taşımalıdır (aksi halde 400 döner) ve bucket’ı listelemekle aynı okuma erişimini gerektirir — herkese açık bir bucket için token gerekmez. Tüm parametre ve yanıt şeması için OpenAPI spec belgesine bakın.

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

Python'da akışı kendinizin tüketmenize gerek yoktur. HfFileSystem, live_follow=True ile bunu sizin için takip eder; böylece başka bir süreç kovayı değiştirdiğinde önbellekteki listeleri güncel kalır:

Kopyalandı

from huggingface_hub import HfFileSystem

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

fsspec storage_options alan kütüphaneler (pandas, PyArrow, …) bunu da kabul eder.

Akış dört olay türü yayar:

changes içindeki her girişin bir path ve bir op (add, update veya delete) vardır. Bir add veya update işlemi, değişen alanları da taşır: size, xetHash, uploadedAt, mtime, mtimeNanos. Bu nedenle bir dosya aynı şekilde yeniden yüklendiğinde bir update işlemi, yalnızca yeni bir uploadedAt değeri kadar küçük olabilir. Değişmeyen alanlar atlanır; bir yükleme sırasında bu alanlar temizlendiğinde mtime/mtimeNanos değerleri null da olabilir, bu yüzden eksik değerleri ve null değerlerini aynı şekilde ele alın.

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"}]}

Devam etme. Bağlandığınız andan itibaren yeni bir akış başlar. Kaçırdığınız değişiklikleri de almak için, son aldığınız cursor değerini (her ready ve changes olayı bir tane taşır) ?cursor=<cursor> olarak veya bir zaman damgasını ?since=<ISO timestamp> olarak (dahil, örn. 2026-09-16T09:21:45Z) iletin.

Yalnızca son ~15 dakikalık değişiklikler yeniden oynatılabilir. cursor veya since değeriniz bundan eskiyse, yeniden oynatma yerine reset alırsınız: görünümünüzü yeniden oluşturmak için varili bir kez listeleyin, ardından yeni akışın ready olayındaki cursor değerinden itibaren yeniden takip edin. Devam etme, kopan bir bağlantı veya yeniden başlatma gibi kısa süreli boşlukları kapatmak içindir; daha uzun süre uzakta kalmış bir istemcinin yeniden listeleme yapması beklenir.

Yeniden bağlanılıyor. Uzun ömürlü bağlantılar geri dönüştürülür: yaklaşık her 20 dakikada bir (ve dağıtımlar sırasında) sunucu reconnect gönderir ve ardından akışı sonlandırır. Herhangi bir akış sonunu aynı şekilde ele alın — son aldığınız imleçle yeniden bağlanın. Bağlantının canlı kalmasını sağlamak için her 30 saniyede bir : ping yorumu gönderilir, bu nedenle tamamen sessize düşen bir akış ölü olarak kabul edilebilir.

503 yanıtı, canlı takibin geçici olarak kullanılamadığı anlamına gelir — Retry-After başlığındaki gecikme süresinden sonra yeniden deneyin.

Ön ısıtma ve CDN

Buckets varsayılan olarak Hub’ın küresel depolama alanında bulunur. Depolama konumunun doğrudan bant genişliğini etkilediği iş yüklerinde, veriyi hesaplama kaynağınıza daha yakın getirmek için bucket verilerini önceden ısıtabilirsiniz.

Pre-warming, dosyaları belirli bulut sağlayıcılarına ve bölgelerine yakın kenar konumlarında önbelleğe alır; böylece işleriniz verileri bölgeler arası çekmek yerine yerel olarak okur. Bu özellikle şu durumlarda faydalıdır:

• Büyük veri kümelerine veya denetim noktalarına hızlı erişim gerektiren eğitim kümeleri
• Farklı bulutlarda bir iş akışının farklı bölümlerinin çalıştığı çok bölgeli kurulumlar
• Büyük artefaktların dünya genelindeki birçok tüketiciye dağıtılması

Mevcut bölgeler ve ön ısıtma etkinleştirme ayrıntıları için hf.co/storage adresine bakın.

Kullanım Senaryoları

Eğitim kontrol noktaları ve günlükler

Eğitim işlerini (ör. Jobs üzerinden) çalıştırırken, denetim noktalarını ve günlükleri bir kovaya (bucket) kaydedin. Bir Git deposunun aksine, sürüm geçmişini biriktirmeden en son denetim noktasının üzerine yazabilirsiniz ve sync yalnızca değişen verilerin aktarılmasını sağlar.

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

Kovalar Xet üzerine inşa edildiğinden, modelin büyük kısımlarının dondurulduğu ardışık kontrol noktaları, parça düzeyindeki kopya giderme işleminin avantajından yararlanır. Yalnızca değiştirilen parçalar yüklenir.

Veri işleme hatları

Buckets, veri işleme iş akışları için geçici alanlar olarak görev yapar. Ham verileri işleyin, ara çıktıları bir bucket'a yazın ve iş akışı tamamlandığında nihai ürünü sürümlü bir Dataset deposuna taşıyın. Bu, sürümlü deponuzun temiz kalmasını sağlarken iş akışınıza hızlı ve değiştirilebilir bir depolama alanı sunar.

Bir Bucket'tan bir depoya yeniden yüklemeye gerek kalmadan veri aktarmanın henüz mevcut olmadığını, ancak yol haritasında bulunduğunu unutmayın.

Ajan tabanlı depolama

AI ajanları, ara sonuçlar, araç çıktıları, izler ve çalışma belleği için geçici depolama alanına ihtiyaç duyar. Buckets, bu veriler için Hub yerel bir alan sağlar: Git yükü olmadan hızlı ve değiştirilebilir erişim, standart Hugging Face izinleri ve Hub ekosistemi genelinde hf://buckets/ yolları üzerinden adreslenebilirlik.

Döngesel yedeklemeler

Buckets, dönen yedeklemeleri sürdürmek için uygundur. Git tabanlı bir Dataset deposunda, eski dosyaları silmek depolamayı serbest bırakmaz — Git geçmişi her eski sürümü sakladığından, alanı gerçekten geri kazanmak için commit’leri birleştirmeniz veya geçmişi yeniden yazmanız gerekir. Bucket’larda ise eski dosyalar silindikten sonra gerçekten ortadan kalkar ve yalnızca o anda depolanan veriler için ödeme yaparsınız.

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

Modelleri varlıklara bağlama

Model kartı meta verilerine buckets alanını ekleyerek bir model ile bir bucket arasında çift yönlü bir bağlantı oluşturabilirsiniz. Bağlantılı modeller bucket sayfasında görünecek ve bucket, model sayfasında bir etiket olarak görünecektir.

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

Daha fazla ayrıntı için model kartları belgelerindeki Varlık deposu belirtme bölümüne bakın.

Fiyatlandırma

Storage Buckets, depolanan veri miktarına göre basit TB başına fiyatlandırma ile faturalandırılır. Kurumsal planlar, dosyalar arası paylaşılan parçaların faturalandırılan alanı doğrudan azalttığı dedup tabanlı faturalandırmadan faydalanır.

Diğer depolar için varillerin oluşturulması ücretsizdir ve ücretsiz bir depolama kotası mevcuttur. ücretsiz katman üzerindeki kullanım için hf.co/storage adresine bakın. Genel faturalandırma bilgileri için Faturalandırma belgelerine bakın.