Hub Python Library documentation

Kovalar

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Kovalar

Buckets, Hugging Face üzerinde Xet depolama altyapısıyla desteklenen, S3 benzeri nesne depolama sağlar. Depoların (git tabanlı olan ve dosya geçmişini izleyen) aksine, bucket'lar, içerik adreslenebilir kopya azaltma (deduplication) ile büyük ölçekli dosyalar için tasarlanmış uzak nesne depolama konteynerleridir. Sürüm kontrolüne ihtiyaç duymayan eğitim checkpoint'leri, günlükler, ara artefaktlar veya büyük dosya koleksiyonları gibi basit, hızlı ve değiştirilebilir depolama gerektiren kullanım senaryoları için tasarlanmıştır.

Python API (HfApi) veya CLI (hf buckets) kullanarak bucket'larla etkileşime geçebilirsiniz. Bu kılavuzda, kullanılabilir tüm işlemleri adım adım ele alacağız.

Tüm CLI komutları hf buckets <command> altında kullanılabilir. Daha fazla bilgi için hf buckets --help komutunu çalıştırın.

Kovalar oluşturma ve yönetme

Bir varlık oluşturun

create_bucket() ile bir bucket oluşturun. Bir bucket adı belirtmeniz gerekir. Bir namespace belirtmezseniz, bucket kullanıcı adınız altında oluşturulur.

>>> from huggingface_hub import create_bucket

# Create a bucket under your namespace
>>> url = create_bucket("my-bucket")
>>> url.bucket_id
'username/my-bucket'
>>> url.uri.to_uri()
'hf://buckets/username/my-bucket'

# Create a private bucket
>>> create_bucket("my-private-bucket", private=True)
BucketUrl(...)

# Don't error if bucket already exists
>>> create_bucket("my-bucket", exist_ok=True)
BucketUrl(...)

# Create a bucket in a specific region
>>> create_bucket("my-bucket", region="us")
BucketUrl(...)

Veya CLI üzerinden:

>>> hf buckets create my-bucket
✓ Bucket created
  uri: hf://buckets/Wauplin/my-bucket
  url: https://huggingface.co/buckets/Wauplin/my-bucket

# Create a private bucket
>>> hf buckets create my-bucket --private

# Don't error if bucket already exists
>>> hf buckets create my-bucket --exist-ok

# Create a bucket in a specific region
>>> hf buckets create my-bucket --region us

Bir organizasyon altında bir varlık oluşturma için tam namespace/bucket_name biçimini de belirtebilirsiniz:

>>> from huggingface_hub import create_bucket
>>> create_bucket("my-org/shared-bucket")

Veya CLI üzerinden:

>>> hf buckets create my-org/shared-bucket

Kova bilgilerini al

Bir bucket hakkında görünürlüğü, toplam boyutu, dosya sayısı ve oluşturma tarihi dahil olmak üzere meta verileri almak için bucket_info() kullanın.

>>> from huggingface_hub import bucket_info
>>> bucket_info("username/my-bucket")
BucketInfo(
  id='username/my-bucket',
  private=False,
  created_at=datetime.datetime(2026, 2, 12, 17, 42, 12,
  tzinfo=datetime.timezone.utc),
  size=8411791508,
  total_files=128
)

Veya CLI üzerinden:

# JSON output
>>> hf buckets info username/my-bucket
{
  "id": "username/my-bucket",
  "private": false,
  ...
}

Kovaları listele

Bir ad alanındaki tüm varlıkları listelemek için list_buckets() kullanın. Varsayılan olarak, mevcut kullanıcının ad alanındaki varlıkları listeler.

>>> from huggingface_hub import list_buckets

# List your own buckets
>>> for bucket in list_buckets():
...     print(bucket.id, bucket.size, bucket.total_files)

# List buckets in an organization
>>> for bucket in list_buckets(namespace="huggingface"):
...     print(bucket.id)

Veya CLI üzerinden (hf buckets ls, hf buckets list komutunun kısaltmasıdır):

# Table format (default)
>>> hf buckets list
ID                   PRIVATE      SIZE TOTAL_FILES CREATED_AT
-------------------- ------- --------- ----------- ----------
username/my-bucket                  32           5 2026-02-16
username/checkpoints         117609095         700 2026-02-13
username/logs                321757477        2000 2026-02-13

# Human-readable sizes
>>> hf buckets list -h
ID                   PRIVATE     SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket               32 B           5 2026-02-16
username/checkpoints         117.6 MB         700 2026-02-13
username/logs                321.8 MB        2000 2026-02-13

# List buckets in a specific namespace
>>> hf buckets ls huggingface

# Filter buckets by name
>>> hf buckets list --search "checkpoint"

Ayrıca search kullanarak varlıkları adlarına göre filtreleyebilirsiniz:

>>> for bucket in list_buckets(search="checkpoint"):
...     print(bucket.id)

Farklı bir çıktı biçimi almak için --quiet ve --format json seçeneklerini kullanabilirsiniz. Bu, özellikle çıktıyı grep veya jq gibi başka bir araca yönlendirmek istediğinizde ilginçtir.

# Quiet mode: prints one bucket ID per line
>>> hf buckets list --quiet
username/my-bucket
username/checkpoints
username/logs

# JSON format
>>> hf buckets list --format json
[
  {
    "id": "username/my-bucket",
    "private": false,
    "created_at": "2026-02-16T15:28:32+00:00",
    "size": 32,
    "total_files": 5
  },
  ...
]

Kova görünürlüğünü değiştir

Mevcut bir kovayı özel ve herkese açık arasında geçirmek için update_bucket_settings() kullanın.

>>> from huggingface_hub import update_bucket_settings

# Make a bucket private
>>> update_bucket_settings("username/my-bucket", private=True)

# Make it public again
>>> update_bucket_settings("username/my-bucket", private=False)

Veya CLI üzerinden:

# Make a bucket private
>>> hf buckets settings username/my-bucket --private
✓ Bucket settings updated
  bucket_id: username/my-bucket
  private: True

# Make it public again
>>> hf buckets settings username/my-bucket --public

Bir varlık kovasını sil

Bir kovayı silmek için delete_bucket() kullanın. Bu işlem geri alınamaz.

>>> from huggingface_hub import delete_bucket
>>> delete_bucket("username/my-bucket")

# Don't error if bucket doesn't exist
>>> delete_bucket("username/my-bucket", missing_ok=True)

Veya CLI üzerinden:

# Prompts for confirmation
>>> hf buckets delete username/my-bucket

# Skip confirmation
>>> hf buckets delete username/my-bucket --yes

# Don't error if bucket doesn't exist
>>> hf buckets delete username/my-bucket --yes --missing-ok

Dosyaları sil

Bir bucket'tan dosyaları silmek için delete parametresiyle batch_bucket_files() kullanın:

>>> from huggingface_hub import batch_bucket_files

# Delete specific files
>>> batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"])

Veya hf buckets rm (veya hf buckets remove) ile CLI üzerinden:

# Remove a single file
>>> hf buckets rm username/my-bucket/old-model.bin

# Remove all files under a prefix (requires --recursive)
>>> hf buckets rm username/my-bucket/logs/ --recursive

# Remove only files matching a pattern across the entire bucket
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"

# Exclude specific files from removal
>>> hf buckets rm username/my-bucket/data/ --recursive --exclude "*.safetensors"

# Preview what would be deleted
>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run

Bir kovayı taşı

Bir bucket'i taşımak veya yeniden adlandırmak için move_bucket() kullanın. Aynı namespace içinde yeniden adlandırma yapabilir veya farklı bir namespace'e (kullanıcı veya organizasyon) aktarabilirsiniz.

>>> from huggingface_hub import move_bucket

# Rename a bucket
>>> move_bucket(from_id="username/old-name", to_id="username/new-name")

# Transfer to an organization
>>> move_bucket(from_id="username/my-bucket", to_id="my-org/my-bucket")

Veya CLI üzerinden:

# Rename a bucket
>>> hf buckets move username/old-bucket username/new-bucket

# Transfer to an organization
>>> hf buckets move username/my-bucket my-org/my-bucket

# Using the hf://buckets/ format
>>> hf buckets move hf://buckets/username/old-bucket hf://buckets/username/new-bucket

Depoları ve varlık gruplarını taşıma hakkında daha fazla bilgi için Hub belgelerini inceleyin.

Kova içeriğini görüntüle

Dosyaları listele

Bir bucket içindeki dosyaları ve dizinleri listelemek için list_bucket_tree() kullanın.

>>> from huggingface_hub import list_bucket_tree

# List all files
>>> for item in list_bucket_tree("username/my-bucket"):
...     print(item.path, item.size)
file.txt 5
big.bin 2048
sub/nested.txt 14
sub/deep/file.txt 4

# List top-level entries only
>>> for item in list_bucket_tree("username/my-bucket", recursive=False):
...     print(item.type, item.path)
file file.txt
file big.bin
directory sub

# Filter by prefix
>>> for item in list_bucket_tree("username/my-bucket", prefix="sub"):
...     print(item.path)

veya CLI üzerinden, tablo, insan-okunabilir ve ASCII ağaç formatlarını destekler. Varsayılan olarak CLI özyinelemeli değildir.

# Default table format (non-recursive, directories shown as entries)
>>> hf buckets list username/my-bucket
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
              2026-01-15 10:30:00  sub/

# Recursive listing (all files, including nested)
>>> hf buckets list username/my-bucket -R
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
          14  2026-01-15 10:30:00  sub/nested.txt
           4  2026-01-15 10:30:00  sub/deep/file.txt

# Human-readable sizes and short dates
>>> hf buckets list username/my-bucket -R -h
      2.0 KB         Jan 15 10:30  big.bin
         5 B         Jan 15 10:30  file.txt
        14 B         Jan 15 10:30  sub/nested.txt
         4 B         Jan 15 10:30  sub/deep/file.txt

# ASCII tree format
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB  Jan 15 10:30  ├── big.bin
   5 B  Jan 15 10:30  ├── file.txt
                      └── sub/
                          ├── deep/
   4 B  Jan 15 10:30  │       └── file.txt
  14 B  Jan 15 10:30  └── nested.txt

# Tree structure only (no sizes/dates)
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
    ├── deep/
    │   └── file.txt
    └── nested.txt

# Quiet mode: one path per line
>>> hf buckets list username/my-bucket -q
big.bin
file.txt
sub/

# Filter by prefix
>>> hf buckets list username/my-bucket/sub -R

hf buckets list komutu, hem kısa biçimi (username/my-bucket/sub) hem de tam işareti (hf://buckets/username/my-bucket/sub) argüman olarak kabul eder.

HfFileSystem ile bir bucket listelenirken içeriği önbelleğe alınır. Bucket'taki dosyaların diğer akranlar tarafından eklenmesi, güncellenmesi ve silinmesiyle listelemelerin yenilenmesini sağlamak için HfFileSystem(live_follow=True) parametresini iletin, bkz. dosya sistemi kılavuzu.

Dosyaları yükle

Python ile Yükle

Dosyaları bir kovaya yüklemek için batch_bucket_files() kullanın. Yerel dosya yollarından veya ham baytlardan yükleyebilirsiniz:

>>> from huggingface_hub import batch_bucket_files

# Upload from local file paths
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         ("./model.safetensors", "models/model.safetensors"),
...         ("./config.json", "models/config.json"),
...     ],
... )

# Upload from raw bytes
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         (b'{"key": "value"}', "config.json"),
...     ],
... )

Ayrıca copy parametresini kullanarak xet dosyalarını başka bir depodan veya repodan kopyalayabilirsiniz. Bu, sunucu tarafında gerçekleştirilen bir işlemdir — veri indirilmez veya yeniden yüklenmez:

# Copy files by xet hash (source_repo_type, source_repo_id, xet_hash, destination)
>>> batch_bucket_files(
...     "username/my-bucket",
...     copy=[
...         ("bucket", "username/source-bucket", "<xethash_1>", "models/model.safetensors"),
...         ("model", "username/my-model", "<xethash_2>", "models/config.safetensors"),
...     ],
... )

Xet hash'leri list_repo_tree kullanılarak alınabilir.

Diğer dosyaları yüklerken dosyaları da silebilirsiniz.

# Upload and delete in one batch
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[("./new-model.safetensors", "model.safetensors")],
...     delete=["old-model.bin"],
... )

batch_bucket_files() çağrıları işlem dışıdır (non-transactional). İşlem sırasında bir hata oluşursa, bazı dosyalar yüklenmiş, kopyalanmış veya silinmiş olabilirken diğerleri bu işlemlerden geçmemiş olabilir. Sunucu bazı işlemlerin başarısız olduğunu bildirdiğinde, başarısız yollar failures özniteliğinde bulunan bir BucketBatchError yükseltilir.

CLI ile tek bir dosya yükleyin

Tek bir dosya yüklemek için hf buckets cp kullanın:

hf buckets cp, birleşik hf cp komutunun (aynı zamanda hf repos cp olarak da sunulur) bir takma adıdır. Üçü de özdeş olduğundan, aşağıdaki herhangi bir hf buckets cp örneği hf cp ile de çalışır.

# Upload to bucket root (uses local filename as remote name)
>>> hf buckets cp ./config.json hf://buckets/username/my-bucket

# Upload to a subdirectory
>>> hf buckets cp ./data.csv hf://buckets/username/my-bucket/logs/

# Upload with a different remote filename
>>> hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/v2/model.safetensors

Bir komutun sonucunu - kullanarak doğrudan yeni bir dosyaya aktarabilirsiniz:

# Upload from stdin
>>> echo "hello" | hf buckets cp - hf://buckets/username/my-bucket/hello.txt
>>> cat model.safetensors | hf buckets cp - hf://buckets/username/my-bucket/model.safetensors

Bir dizini CLI ile yükleyin

Bir yerel dizinin tamamını bir kovaya yüklemek için hf buckets sync kullanın:

# Upload a local directory to a bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket

# Upload to a specific prefix in the bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket/train

Tüm senkronizasyon seçenekleri için aşağıdaki Dizinleri senkronize et bölümüne bakın.

Dosyaları indir

Python ile indir

Bir bucket'tan dosyaları indirmek için download_bucket_files() kullanın:

>>> from huggingface_hub import download_bucket_files

# Download specific files by path
>>> download_bucket_files(
...     "username/my-bucket",
...     files=[
...         ("models/model.safetensors", "./local/model.safetensors"),
...         ("config.json", "./local/config.json"),
...     ],
... )

Daha iyi performans için, list_bucket_tree() ile elde edilen BucketFile nesnelerini, dize yolları yerine geçirebilirsiniz. Bu, meta veri alma adımını atlar:

>>> from huggingface_hub import list_bucket_tree, download_bucket_files

# List and filter files, then download
>>> parquet_files = [
...     item for item in list_bucket_tree("username/my-bucket", recursive=True)
...     if item.type == "file" and item.path.endswith(".parquet")
... ]
>>> download_bucket_files(
...     "username/my-bucket",
...     files=[(f, f"./local/{f.path}") for f in parquet_files],
... )

CLI ile tek bir dosya indirin

Tek bir dosyayı indirmek için hf buckets cp kullanın:

# Download to a specific file
>>> hf buckets cp hf://buckets/username/my-bucket/config.json ./config.json

# Download to a directory (uses original filename)
>>> hf buckets cp hf://buckets/username/my-bucket/config.json ./data/

# Download to current directory (omit destination)
>>> hf buckets cp hf://buckets/username/my-bucket/config.json

Bir dosyanın içeriğini - kullanarak doğrudan stdout'a da yönlendirebilirsiniz:

# Download to stdout and pretty-print with jq
>>> hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .

CLI ile bir dizin indirin

Bir bucket'taki tüm dosyaları yerel bir dizine indirmek için hf buckets sync kullanın:

# Download bucket contents to a local directory
>>> hf buckets sync hf://buckets/username/my-bucket ./data

# Download only a specific prefix
>>> hf buckets sync hf://buckets/username/my-bucket/models ./local-models

Tüm senkronizasyon seçenekleri için aşağıdaki Dizinleri senkronize et bölümüne bakın.

Dosyaları Bucket'e kopyala

Hub üzerinde zaten barındırılan dosyaları bir Bucket'e kopyalamak için copy_files() kullanın:

>>> from huggingface_hub import copy_files

# Bucket to bucket (same or different bucket)
>>> copy_files(
...     "hf://buckets/username/source-bucket/checkpoints/model.safetensors",
...     "hf://buckets/username/destination-bucket/archive/model.safetensors",
... )

# Repo to bucket
>>> copy_files(
...     "hf://datasets/username/my-dataset/processed/",
...     "hf://buckets/username/my-bucket/datasets/processed/",
... )

Aynı işlem, birleşik hf cp komutu aracılığıyla CLI üzerinden de kullanılabilir (aynı zamanda hf buckets cp ve hf repos cp olarak da sunulur — üçü de özdeş):

# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/destination-bucket/logs/

# Repo to bucket
>>> hf cp hf://username/my-model/config.json hf://buckets/username/my-bucket/models/config.json

Klasörleri kopyalarken, kaynakta sonundaki / rsync tarzı anlamları kullanır — klasörün kendisi iç içe geçirilmeden yalnızca içeriği kopyalanır:

# Without trailing slash: "logs" dir is nested => destination/logs/...
>>> hf cp hf://buckets/username/source-bucket/logs hf://buckets/username/destination-bucket/

# With trailing slash: only contents of "logs" are copied => destination/...
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/destination-bucket/

Notlar:

Bucket-to-repo kopyalama henüz desteklenmiyor.
Sunucu tarafı kopyalar yalnızca aynı depolama bölgesi içinde çalışır.
Xet ile izlenen dosyalar (varlıklarda veya depolarda) hash üzerinden sunucu tarafında kopyalanır — veri indirilmez veya yeniden yüklenmez.
Xet ile kaynaklarda takip edilmeyen küçük metin dosyaları, hedef kovaya indirilir ve yeniden yüklenir.
copy_files() ayrıca depo içi kopyalamalar için de kullanılabilir. Daha fazla ayrıntı için depo kılavuzuna bakın.

Dizinleri senkronize et

hf buckets sync komutu (ve API karşılığı sync_bucket()), bir yerel dizin ile bir bucket arasında dosya aktarmanın en güçlü yoludur. Kaynağı ve hedefi karşılaştırır ve yalnızca değişen dosyaları aktarır.

Temel senkronizasyon

# Upload: local directory -> bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket

# Download: bucket -> local directory
>>> hf buckets sync hf://buckets/username/my-bucket ./data

hf sync, hf buckets sync için kullanışlı bir takma addır. Her iki komut da özdeştir.
>>> hf sync ./data hf://buckets/username/my-bucket

Veya Python ile:

>>> from huggingface_hub import sync_bucket

# Upload: local directory -> bucket
>>> sync_bucket("./data", "hf://buckets/username/my-bucket")

# Download: bucket -> local directory
>>> sync_bucket("hf://buckets/username/my-bucket", "./data")

Gereksiz dosyaları sil

Varsayılan olarak, sync yalnızca dosyaları ekler veya günceller. Kaynakta bulunmayan hedef dosyalarını da kaldırmak için --delete (veya Python'da delete=True) kullanın:

# Upload and remove remote files not present locally
>>> hf buckets sync ./data hf://buckets/username/my-bucket --delete

# Download and remove local files not present in bucket
>>> hf buckets sync hf://buckets/username/my-bucket ./data --delete

Veya Python ile:

>>> sync_bucket("./data", "hf://buckets/username/my-bucket", delete=True)
>>> sync_bucket("hf://buckets/username/my-bucket", "./data", delete=True)

Filtreleme

include/exclude desenlerini kullanarak senkronize edilen dosyaları kontrol edebilirsiniz:

# Only sync .txt files
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.txt"

# Exclude log files
>>> hf buckets sync ./data hf://buckets/username/my-bucket --exclude "*.log"

# Combine include and exclude
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"

Veya Python ile:

# Only sync .txt files
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", include=["*.txt"])

# Exclude log files
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", exclude=["*.log"])

# Combine include and exclude
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", include=["*.safetensors"], exclude=["*.tmp"])

Daha karmaşık filtreleme için --filter-from (veya Python'da filter_from) ile bir filtre dosyası kullanın:

>>> hf buckets sync ./data hf://buckets/username/my-bucket --filter-from filters.txt

Filtre dosyası + (dahil et) ve - (hariç tut) öneklerini kullanır. # ile başlayan satırlar yorumlardır. Kurallar sırayla değerlendirilir (ilk eşleşen kural geçerlidir):

# filters.txt
- *.log
- *.tmp
+ *.safetensors
+ *.json

Karşılaştırma modları

Varsayılan olarak, sync dosyaları hem boyut hem de değiştirme zamanı kullanarak karşılaştırır. Bu davranışı özelleştirebilirsiniz:

# Only compare sizes (ignore modification times)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-times

# Only compare modification times (ignore sizes)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-sizes

# Only update files that already exist on the receiver (skip new files)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing

# Only create new files (skip files that already exist on the receiver)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existing

Veya Python ile:

>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_times=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_sizes=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", existing=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_existing=True)

Planla ve uygula

Kritik işlemler için, senkronizasyon planını uygulamadan önce inceleyebilirsiniz:

# Step 1: Generate a plan file (nothing is transferred)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
Sync plan: ./data -> hf://buckets/username/my-bucket
  Uploads: 3
  Downloads: 0
  Deletes: 0
  Skips: 1
Plan saved to: sync-plan.jsonl

# Step 2: Review the plan file (JSONL format)
>>> cat sync-plan.jsonl

# Step 3: Apply the plan
>>> hf buckets sync --apply sync-plan.jsonl

Veya Python ile:

# Step 1: Generate a plan file (nothing is transferred)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", plan="sync-plan.jsonl")

# Step 2: Review the plan file (JSONL format), then apply
>>> sync_bucket(apply="sync-plan.jsonl")

Plan dosyası, bir başlık satırından sonra her işlem için bir satır içeren bir JSONL dosyasıdır. Her işlem, eylemi (upload, download, delete veya skip), dosya yolunu ve eylemin nedenini içerir. Bu dosyayı uygulamadan önce manuel olarak düzenleyebilirsiniz ancak sözdizimine dikkat edin.

Kuru çalıştırma

Herhangi bir işlemi uygulamadan senkronizasyon planını almak için --dry-run (veya Python'da dry_run=True) kullanın:

# Preview what would be synced
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq '.action'

Veya Python ile:

>>> plan = sync_bucket("./data", "hf://buckets/username/my-bucket", dry_run=True)
>>> plan.summary()
{'uploads': 3, 'downloads': 0, 'deletes': 0, 'skips': 1, 'total_size': 4096}

--dry-run, --plan ile aynı JSONL biçimini üretir ancak dosyaya kaydetmek yerine stdout'a basar. Yalnızca JSONL içeriği basılır, bu da boru (pipe) kullanımı için güvenlidir.

Ayrıntılı ve sessiz modlar

# Show per-file operations
>>> hf buckets sync ./data hf://buckets/username/my-bucket --verbose

# Suppress all output
>>> hf buckets sync ./data hf://buckets/username/my-bucket --quiet

Veya Python ile:

>>> sync_bucket("./data", "hf://buckets/username/my-bucket", verbose=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", quiet=True)

Gelişmiş

Daha düşük seviye kullanım senaryoları için aşağıdaki yöntemler de kullanılabilir:

get_bucket_paths_info(): Bir seferde tek bir toplu istekle bir depodaki belirli yollar hakkında bilgi alır. Hangi dosyaların meta verilerine ihtiyacınız olduğunu tam olarak bildiğinizde kullanışlıdır.

>>> from huggingface_hub import get_bucket_paths_info
>>> for info in get_bucket_paths_info("username/my-bucket", ["file.txt", "models/model.safetensors"]):
...     print(info.path, info.size, info.xet_hash)

get_bucket_file_metadata(): Tek bir dosya için metadata (boyut ve xet verileri) getirir. download_bucket_files() tarafından dahili olarak kullanılır.

>>> from huggingface_hub import get_bucket_file_metadata
>>> metadata = get_bucket_file_metadata("username/my-bucket", "models/model.safetensors")
>>> metadata.size
42000

Update on GitHub

←Dosyaları yükle CLI'yi kullanın→