Hub'dan dosya indir

huggingface_hub kütüphanesi, Hub'da saklanan depolardan dosya indirmek için işlevler sağlar. Bu işlevleri bağımsız olarak kullanabilir veya kendi kütüphanenize entegre ederek kullanıcılarınızın Hub ile etkileşimini daha pratik hale getirebilirsiniz. Bu rehberde şunları göstereceğiz:

• Tek bir dosyayı indirin ve önbelleğe alın.
• Bir depoyu tamamen indirin ve önbelleğe alın.
• Dosyaları yerel bir klasöre indirin.

Tek bir dosya indirin

hf_hub_download() işlevi, Hub'dan dosya indirmek için ana işlevdir. Uzak dosyayı indirir, diskte önbelleğe alır (sürüm farkında bir şekilde) ve yerel dosya yolunu döndürür.

Döndürülen dosya yolu, HF yerel önbelleğine bir işaretçidir. Bu nedenle, bozuk bir önbelleğe sahip olmamak için dosyayı değiştirmemek önemlidir. Dosyaların nasıl önbelleğe alındığı hakkında daha fazla bilgi edinmek isterseniz, lütfen önbelleğe alma kılavuzumuza başvurun.

En son sürümden

repo_id, repo_type ve filename parametrelerini kullanarak indirilecek dosyayı seçin. Varsayılan olarak dosya, bir model deposunun parçası olarak kabul edilir.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

# Download from a dataset
>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset")
'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py'

Belirli sürümden

Varsayılan olarak, main dalından en son sürüm indirilir. Ancak bazı durumlarda belirli bir sürümden (ör. belirli bir daldan, PR'den, etiketten veya commit hash'inden) dosya indirmek isteyebilirsiniz. Bunu yapmak için revision parametresini kullanın:

# Download from the `v1.0` tag
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")

# Download from the `test-branch` branch
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")

# Download from Pull Request #3
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3")

# Download from a specific commit hash
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a")

Not: Commit hash kullanırken, 7 karakterlik commit hash yerine tam uzunluktaki hash kullanılması gerekir.

İndirme URL'si oluşturun

In case you want to construct the URL used to download a file from a repo, you can use hf_hub_url() which returns a URL. Note that it is used internally by hf_hub_download().

Bir depoyu tamamen indirin

snapshot_download(), belirtilen bir revizyondaki tüm bir depoyu indirir. İçeride hf_hub_download() işlevini kullandığı için indirilen tüm dosyalar ayrıca yerel diskinizde önbelleğe alınır. İndirme işlemi, süreci hızlandırmak için eşzamanlı olarak yapılır.

Tüm bir depoyu indirmek için yalnızca repo_id ve repo_type değerlerini iletin:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

# Or from a dataset
>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset")
'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34'

snapshot_download() varsayılan olarak en son revizyonu indirir. Belirli bir depo revizyonunu istiyorsanız revision parametresini kullanın:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")

İndirilecek dosyaları filtrele

snapshot_download() bir depoyu indirmenin kolay bir yolunu sunar. Ancak her zaman bir depodaki tüm içeriği indirmek istemezsiniz. Örneğin, yalnızca .safetensors ağırlıklarını kullanacağınızı biliyorsanız, tüm .bin dosyalarının indirilmesini engellemek isteyebilirsiniz. Bunu allow_patterns ve ignore_patterns parametrelerini kullanarak yapabilirsiniz.

Bu parametreler tek bir desen veya desen listesi kabul eder. Desenler, burada belgelenen Standart Jolly Karakterler (globbing desenleri)dir. Desen eşleştirme fnmatch üzerine kuruludur.

Örneğin, yalnızca JSON yapılandırma dosyalarını indirmek için allow_patterns kullanabilirsiniz:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")

Öte yandan, ignore_patterns belirli dosyaların indirilmesini engelleyebilir. Aşağıdaki örnek, .msgpack ve .h5 dosya uzantılarını yok sayar:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])

Son olarak, indirmenizi hassas bir şekilde filtrelemek için her ikisini birleştirebilirsiniz. Aşağıdaki örnek, vocab.json hariç tüm json ve markdown dosyalarını indirmek için kullanılır.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")

Dosyaları yerel bir klasöre indirin

Varsayılan olarak, Hub'dan dosya indirmek için önbellek sistemini kullanmanızı öneririz. hf_hub_download() ve snapshot_download() içindeki cache_dir parametresini kullanarak veya HF_HOME ortam değişkenini ayarlayarak özel bir önbellek konumu belirleyebilirsiniz.

Ancak dosyaları belirli bir klasöre indirmeniz gerekiyorsa, indirme fonksiyonuna local_dir parametresini iletebilirsiniz. Bu, iş akışını git komutunun sunduğu işleve yaklaştırmak için kullanışlıdır. İndirilen dosyalar, belirtilen klasör içinde orijinal dosya yapılarını korur. Örneğin, filename="data/train.csv" ve local_dir="path/to/folder" ise, sonuç dosya yolu "path/to/folder/data/train.csv" olur.

Yerel dizininizin kökünde, indirilen dosyalarla ilgili meta verileri içeren bir .cache/huggingface/ klasörü oluşturulur. Bu, dosyalar zaten güncelse yeniden indirilmelerini engeller. Meta verilerde bir değişiklik varsa, yeni dosya sürümü indirilir. Bu sayede local_dir, yalnızca en son değişiklikleri çekmek için optimize edilmiş olur.

İndirme tamamlandıktan sonra, bu klasöre artık ihtiyacınız yoksa .cache/huggingface/ klasörünü güvenle silebilirsiniz. Ancak bu klasersiz betiğinizi yeniden çalıştırmanız, metadata kaybı nedeniyle daha uzun kurtarma sürelerine yol açabilir. Yerel verilerinizin sağlam ve etkilenmeden kalacağından emin olabilirsiniz.

Hub'a değişiklikleri gönderirken .cache/huggingface/ klasörünü dert etmeyin! Bu klasör hem git hem de upload_folder() tarafından otomatik olarak yoksayılır.

CLI'den indir

Terminalden hf download komutunu kullanarak Hub'dan dosyaları doğrudan indirebilirsiniz. İçeride, yukarıda açıklanan aynı hf_hub_download() ve snapshot_download() yardımcılarını kullanır ve dönen yolu terminalde yazdırır.

>>> hf download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

Aynı anda birden çok dosya indirebilir ve dosyaların bulunduğu anlık görüntü yolunu döndüren bir ilerleme çubuğu görüntüleyebilirsiniz:

>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

Tek bir hf:// URI'si kullanarak depoya (ve isteğe bağlı olarak bir revizyon ve dosyaya) da işaret edebilirsiniz. URI, hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] dilbilgisini izler (tam sözdizimi için HF URI referansına bakın) ve birlikte ayarlanamayan --repo-type ile --revision seçeneklerinin yerini alır:

# Download a single file from a dataset at a given revision
>>> hf download hf://datasets/google/fleurs@refs/pr/1/fleurs.py

# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/google/fleurs/data/

# Download an entire repo
>>> hf download hf://datasets/google/fleurs

CLI indirme komutu hakkında daha fazla ayrıntı için lütfen CLI kılavuzuna başvurun.

Kuru çalıştırma modu

Bazı durumlarda, dosyaları gerçekten indirmeden önce hangi dosyaların indirileceğini kontrol etmek isteyebilirsiniz. Bunu --dry-run parametresini kullanarak kontrol edebilirsiniz. Bu parametre, depodaki indirilecek tüm dosyaları listeler ve bunların daha önce indirilip indirilmediğini kontrol eder. Bu, kaç dosyanın indirilmesi gerektiği ve boyutları hakkında bir fikir verir.

İşte tek bir dosyada kontrol yapan bir örnek:

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 1 files (out of 1) totalling 655.2M
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx 655.2M

Ve dosya zaten önbelleğe alındıysa:

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 0 files (out of 1) totalling 0.0.
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx -

Tüm bir depo üzerinde kuru çalıştırma (dry-run) da gerçekleştirebilirsiniz:

>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00,  6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File                              Bytes to download
--------------------------------- -----------------
.gitattributes                    -
64-8bits.tflite                   125.2M
64-fp16.tflite                    248.3M
64.tflite                         495.8M
README.md                         -
config.json                       -
flax_model.msgpack                497.8M
generation_config.json            -
merges.txt                        -
model.safetensors                 548.1M
onnx/config.json                  -
onnx/decoder_model.onnx           653.7M
onnx/decoder_model_merged.onnx    655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json       -
onnx/merges.txt                   -
onnx/special_tokens_map.json      -
onnx/tokenizer.json               -
onnx/tokenizer_config.json        -
onnx/vocab.json                   -
pytorch_model.bin                 548.1M
rust_model.ot                     702.5M
tf_model.h5                       497.9M
tokenizer.json                    -
tokenizer_config.json             -
vocab.json                        -

Ve dosya filtreleme ile:

>>> hf download openai-community/gpt2 --include "*.json"  --dry-run
[dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s]
[dry-run] Will download 0 files (out of 11) totalling 0.0.
File                         Bytes to download
---------------------------- -----------------
config.json                  -
generation_config.json       -
onnx/config.json             -
onnx/generation_config.json  -
onnx/special_tokens_map.json -
onnx/tokenizer.json          -
onnx/tokenizer_config.json   -
onnx/vocab.json              -
tokenizer.json               -
tokenizer_config.json        -
vocab.json                   -

Son olarak, hf_hub_download() ve snapshot_download() fonksiyonlarına dry_run=True parametresini geçirerek programatik olarak bir kuru çalıştırma (dry-run) da yapabilirsiniz. Bu işlem, her dosya için commit hash'i, dosya adı ve dosya boyutu, dosyanın önbellekte olup olmadığı ve dosyanın indirilip indirilmeyeceği bilgilerini içeren bir DryRunFileInfo (veya DryRunFileInfo listesini) döndürür. Pratikte, dosya önbellekte değilse veya force_download=True parametresi geçirildiyse dosya indirilir.

Daha hızlı indirmeler

hf_xet sayesinde daha hızlı indirmelerden yararlanın. hf_xet, xet-core kütüphanesinin Python bağlamıdır ve daha hızlı indirme ve yükleme için parça tabanlı kopya azaltma (deduplication) imkânı sağlar. hf_xet, huggingface_hub ile kusursuz bir şekilde bütünleşir ancak LFS yerine Rust xet-core kütüphanesini ve Xet depolamayı kullanır.

hf_xet, dosyaları değişmez parçalara ayıran Xet depolama sistemini kullanır; bu parçaların koleksiyonlarını (bloklar veya xorblar olarak adlandırılır) uzaktan saklar ve istendiğinde dosyayı yeniden oluşturmak için bunları getirir. İndirme sırasında, kullanıcının dosyalara erişim yetkisinin doğrulanmasının ardından hf_xet, bu dosya için LFS SHA256 özetini sorgulayarak Xet içerik-adreslenebilir servisine (CAS) başvurur ve bu dosyaları birleştirmek için yeniden oluşturma metadata’sını (xorblar içindeki aralıklar) alır; xorbları doğrudan indirmek için ön imzalı URL’ler de buna dahildir. Ardından hf_xet, gerekli xorb aralıklarını verimli bir şekilde indirir ve dosyaları diske yazar.

Bunu etkinleştirmek için huggingface_hub'ün en son sürümünü kurmanız yeterlidir:

pip install -U "huggingface_hub"

huggingface_hub 0.32.0 sürümünden itibaren bu, hf_xet paketini de yükleyecektir.

Diğer tüm huggingface_hub API'leri herhangi bir değişiklik yapılmadan çalışmaya devam edecektir. Xet depolamanın ve hf_xet'in avantajları hakkında daha fazla bilgi edinmek için bu bölüme bakın.

Not: hf_transfer daha önce LFS depolama arka ucu ile kullanılıyordu ve artık kullanımdan kaldırıldı; bunun yerine hf_xet kullanın.