Hub Python Library documentation
Dosyaları indirme
Dosyaları indirme
Tek bir dosya indirin
hf_hub_download
huggingface_hub.hf_hub_download
< source >( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Noneuser_agent: dict | str | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falseheaders: dict[str, str] | None = Noneendpoint: str | None = Nonetqdm_class: type[tqdm.std.tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo
Parametreler
- repo_id (
str) — Bir kullanıcı veya kuruluş adı ile/ile ayrılmış bir depo adı. - filename (
str) — Depodaki dosyanın adı. - subfolder (
str, isteğe bağlı) — Model deposunun içindeki bir klasöre karşılık gelen isteğe bağlı bir değer. - repo_type (
str, isteğe bağlı) — Bir veri seti, space veya kernel deposundan indiriliyorsa"dataset","space"veya"kernel"olarak ayarlayın, bir modelden indiriliyorsaNoneveya"model". Varsayılan değerNone'dir. - revision (
str, isteğe bağlı) — Bir dal adı, etiket veya commit hash olabilecek isteğe bağlı bir Git revizyon kimliği. - library_name (
str, isteğe bağlı) — Nesnenin karşılık geldiği kütüphanenin adı. - library_version (
str, isteğe bağlı) — Kütüphanenin sürümü. - cache_dir (
str,Path, isteğe bağlı) — Önbelleğe alınan dosyaların saklandığı klasörün yolu. - local_dir (
strveyaPath, isteğe bağlı) — Verilirse, indirilen dosya bu dizinin altına yerleştirilir. - user_agent (
dict,str, isteğe bağlı) — Sözlük veya dize biçimindeki kullanıcı-ajanı bilgisi. - force_download (
bool, isteğe bağlı, varsayılanFalse) — Dosya, yerel önbellekte zaten mevcut olsa bile indirilip indirilmeyeceği. - etag_timeout (
float, isteğe bağlı, varsayılan10) — ETAG alınırken,httpx2.request'e iletilen, sunucunun veri göndermesini bekleme süresi (saniye). - token (
str,bool, isteğe bağlı) — İndirme için kullanılacak bir jeton.Trueise, token HuggingFace config klasöründen okunur.- Bir dize ise, kimlik doğrulama jetonu olarak kullanılır.
- local_files_only (
bool, isteğe bağlı, varsayılanFalse) —Trueise, dosyanın indirilmesini engeller ve varsa yerel önbellekteki dosyanın yolunu döndürür. - headers (
dict, isteğe bağlı) — İstekle birlikte gönderilecek ek başlıklar. - endpoint (
str, isteğe bağlı) — İsteklerin gönderileceği Hub uç noktası. Varsayılan olarakHF_ENDPOINTdeğerini kullanır. - tqdm_class (
tqdm, isteğe bağlı) — Verilirse, ilerleme çubuğu için varsayılan davranışı yazar. Geçirilen argümantqdm.auto.tqdmsınıfından türetmeli veya en azından davranışını taklit etmelidir. Varsayılan olarak,HF_HUB_DISABLE_PROGRESS_BARSortam değişkenini ayarlayarak devre dışı bırakılabilen özel HF ilerleme çubuğu kullanılır. - dry_run (
bool, isteğe bağlı, varsayılanFalse) —Trueise, dosyayı gerçekten indirmeden kuru bir çalışma (dry run) gerçekleştirir. İndirilecek olanlarla ilgili bilgileri içeren bir DryRunFileInfo nesnesi döndürür.
Dönüş değeri
str veya DryRunFileInfo
dry_run=Falseise: Dosyanın yerel yolu veya ağ kapalıysa, diskte önbelleğe alınmış dosyanın son sürümü.dry_run=Trueise: İndirme bilgilerini içeren bir DryRunFileInfo nesnesi.
Yükseltilen
RepositoryNotFoundError veya RevisionNotFoundError veya ~utils.RemoteEntryNotFoundError veya LocalEntryNotFoundError veya EnvironmentError veya OSError veya ValueError
- RepositoryNotFoundError —
İndirilecek depo bulunamadığında. Bunun nedeni, deponun var olmaması veya
privateolarak ayarlanmış olması ve erişiminizin bulunmaması olabilir. - RevisionNotFoundError — İndirilecek revizyon bulunamadığında.
~utils.RemoteEntryNotFoundError— İndirilecek dosya bulunamadığında.- LocalEntryNotFoundError — Ağ devre dışı bırakıldı veya kullanılamıyor ve dosya önbellekte bulunamıyorsa.
EnvironmentError—token=Trueise ancak token bulunamazsa.OSError— ETTag belirlenemezse.ValueError— Bazı parametre değeri geçersizse.
Yerel önbellekte henüz yoksa verilen dosyayı indirir.
Yeni önbellek dosya düzeni şu şekildedir:
- Önbellek dizini, repo_id başına bir alt klasör içerir (repo türüne göre ad alanılandırılmıştır)
- her depo klasörünün içinde:
- refs, bilinen en son revizyon => commit_hash çiftlerinin bir listesidir
- blobs, LFS dosyaları olup olmadığına bağlı olarak git-sha veya sha256 ile tanımlanan) gerçek dosya bloblarını içerir
- snapshots, her commit için bir alt klasör içerir; her “commit”, o belirli commit’te çözümlenmiş dosyaların alt kümesini barındırır. Her dosya adı, o belirli commit’teki blob’a giden bir sembolik bağlantıdır.
[ 96] .
└── [ 160] models--julien-c--EsperBERTo-small
├── [ 160] blobs
│ ├── [321M] 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
│ ├── [ 398] 7cb18dc9bafbfcf74629a4b760af1b160957a83e
│ └── [1.4K] d7edf6bd2a681fb0175f7735299831ee1b22b812
├── [ 96] refs
│ └── [ 40] main
└── [ 128] snapshots
├── [ 128] 2439f60ef33a0d46d85da5001d52aeda5b00ce9f
│ ├── [ 52] README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
│ └── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
└── [ 128] bbc77c8132af1cc5cf678da3f1ddf2de43606d48
├── [ 52] README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
└── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bdlocal_dir sağlanırsa, depodaki dosya yapısı bu konumda yeniden oluşturulur. Bu seçeneği kullanırken cache_dir kullanılmaz ve indirilen dosyalarla ilgili bazı meta verileri depolamak için local_dir kökünde bir .cache/huggingface/ klasörü oluşturulur. Bu mekanizma ana önbellek sistemi kadar sağlam olmasa da, bir deponun en son sürümünü düzenli olarak çekmek için optimize edilmiştir.
hf_hub_url
huggingface_hub.hf_hub_url
< source >( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )
Parametreler
- repo_id (
str) — Bir/ile ayrılmış bir ad alanı (kullanıcı veya kuruluş) adı ve bir depo adı. - filename (
str) — Depodaki dosyanın adı. - subfolder (
str, isteğe bağlı) — Depo içindeki bir klasöre karşılık gelen isteğe bağlı bir değer. - repo_type (
str, isteğe bağlı) — Bir veri seti, space veya kernel deposundan indiriliyorsa"dataset","space"veya"kernel"olarak ayarlayın, bir modelden indiriliyorsaNoneveya"model". Varsayılan değerNone'dir. - revision (
str, isteğe bağlı) — Bir dal adı, etiket veya commit hash olabilecek isteğe bağlı bir Git revizyon kimliği. - endpoint (
str, isteğe bağlı) — İsteklerin gönderileceği Hub uç noktası. Varsayılan olarakHF_ENDPOINTdeğerini kullanır.
Verilen bilgilerden bir dosyanın URL'sini oluşturun.
Çözümlenen adres, huggingface.co üzerinden barındırılan bir URL veya birkaç MB'dan büyük dosyalar için Cloudfront'a (bir İçerik Dağıtım Ağı, yani CDN) giden bir bağlantı olabilir.
Örnek:
>>> from huggingface_hub import hf_hub_url
>>> hf_hub_url(
... repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'Notlar:
Cloudfront küresel olarak çoğaltılmıştır, bu da nihai kullanıcı için indirmelerin çok daha hızlı olmasını sağlar (aynı zamanda bant genişliği maliyetlerimizi de düşürür).
Cloudfront varsayılan olarak dosyaları agresif bir şekilde önbelleğe alır (varsayılan TTL 24 saattir), ancak bu burada bir sorun değildir çünkü huggingface.co üzerinde git tabanlı bir sürümleme sistemi uygularız. Bu da dosyaların S3/Cloudfront üzerinde içerik adreslenebilir bir şekilde (yani dosya adı, dosyanın hash'idir) saklandığı anlamına gelir. İçerik adreslenebilir dosya adları kullanmak, önbelleğin asla bayatlamayacağı anlamına gelir.
Bu kütüphanenin istemci tarafı önbellekleme açısından, önbellekleme sistemimizi nesnelerin varlık etiketine (
ETag) dayandırıyoruz; bu, bir kaynağın belirli bir sürümünün tanımlayıcısıdır [1]_. Bir nesnenin ETag değeri, git'te saklanıyorsa git-sha1, git-lfs'te saklanıyorsa sha256 değeridir.
Referanslar:
Deponun bir anlık görüntüsünü indirin
huggingface_hub.snapshot_download
< source >( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[tqdm.asyncio.tqdm_asyncio] | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo
Parametreler
- repo_id (
str) — Bir kullanıcı veya kuruluş adı ile/ile ayrılmış bir depo adı. - repo_type (
str, isteğe bağlı) — Bir veri seti, space veya kernel deposundan indiriliyorsa"dataset","space"veya"kernel"olarak ayarlayın, bir modelden indiriliyorsaNoneveya"model". Varsayılan değerNone'dir. - revision (
str, isteğe bağlı) — İsteğe bağlı bir Git revizyon kimliği; bir dal adı, etiket veya commit hash olabilir. - cache_dir (
str,Path, isteğe bağlı) — Önbelleğe alınan dosyaların saklandığı klasörün yolu. - local_dir (
strveyaPath, isteğe bağlı) — Verilirse, indirilen dosyalar bu dizinin altına yerleştirilir. - library_name (
str, isteğe bağlı) — Nesnenin karşılık geldiği kütüphanenin adı. - library_version (
str, isteğe bağlı) — Kütüphanenin sürümü. - user_agent (
str,dict, isteğe bağlı) — Sözlük veya dize biçimindeki kullanıcı-ajanı bilgisi. - etag_timeout (
float, isteğe bağlı, varsayılan10) — ETAG alınırken,httpx2.request'e iletilen, sunucunun veri göndermesini bekleme süresi (saniye). - force_download (
bool, isteğe bağlı, varsayılanFalse) — Dosya, yerel önbellekte zaten mevcut olsa bile indirilip indirilmeyeceğini belirtir. - token (
str,bool, isteğe bağlı) — İndirme için kullanılacak bir jeton.Trueise, token HuggingFace config klasöründen okunur.- Bir dize ise, kimlik doğrulama jetonu olarak kullanılır.
- headers (
dict, isteğe bağlı) — İsteğe eklenmesi gereken ek başlıklar. Bu başlıklar diğerlerine önceliklidir. - endpoint (
str, isteğe bağlı) — İsteklerin gönderileceği Hub uç noktası. Varsayılan olarakHF_ENDPOINTdeğerini kullanır. - local_files_only (
bool, isteğe bağlı, varsayılanFalse) —Trueise, dosyalarcache_dirveyalocal_diriçinde olmasa bile hiçbir dosya indirilmez. - allow_patterns (
list[str]veyastr, isteğe bağlı) — Verilirse, en az bir desenle eşleşen dosyalar indirilir. - ignore_patterns (
list[str]veyastr, isteğe bağlı) — Verilirse, desenlerden herhangi biriyle eşleşen dosyalar indirilmez. - max_workers (
int, isteğe bağlı) — Dosyaları indirmek için kullanılacak eşzamanlı iş parçacığı sayısı (1 iş parçacığı = 1 dosya indirme). Varsayılan değer 8'dir. - tqdm_class (
tqdm, isteğe bağlı) — Verilirse, ilerleme çubuğu için varsayılan davranışı yazar. Geçirilen argüman,tqdm.auto.tqdmsınıfından türemeli veya en azından davranışını taklit etmelidir.tqdm_class'in her bireysel indirmeye geçirilmediğine dikkat edin. Varsayılan olarak,HF_HUB_DISABLE_PROGRESS_BARSortam değişkeni ayarlanarak devre dışı bırakılabilen özel HF ilerleme çubuğudur. - dry_run (
bool, isteğe bağlı, varsayılanFalse) —Trueise, dosyaları gerçekten indirmeden kuru bir çalışma (dry run) gerçekleştirir. İndirilecekler hakkında bilgi içeren DryRunFileInfo nesnelerinden oluşan bir liste döndürür.
Dönüş değeri
str veya DryRunFileInfo listesi
dry_run=Falseise: Yerel anlık görüntü yolu.dry_run=Trueise: İndirme bilgilerini içeren DryRunFileInfo nesnelerinden oluşan bir liste.
Yükseltilen
RepositoryNotFoundError veya RevisionNotFoundError veya IncompleteSnapshotError veya EnvironmentError veya OSError veya ValueError
- RepositoryNotFoundError —
İndirilecek depo bulunamadığında. Bunun nedeni, deponun var olmaması veya
privateolarak ayarlanmış olması ve erişiminizin bulunmaması olabilir. - RevisionNotFoundError — İndirilecek revizyon bulunamadığında.
- IncompleteSnapshotError —
Hub'a ulaşılamıyorsa (çevrimdışı, bağlantı sorunu veya
local_files_only=True) ve önbellekteki anlık görüntüde istenen dosyaların bazıları eksikse. EnvironmentError—token=Trueise ve token bulunamazsa.OSError— ETag belirlenemezse.ValueError— Bazı parametre değeri geçersizse.
Depo dosyalarını indirin.
Belirtilen revizyonda bir depodaki dosyaların tamamını içeren bir anlık görüntüyü indirir. Hangi dosyaların gerekeceğini önceden bilmediğiniz durumlarda, bir depodaki tüm dosyalara ihtiyacınız olduğunda bu işe yarar. Tüm dosyalar, o klasöre göre göreli yol ve dosya adlarını korumak için bir klasörün içine yerleştirilir. allow_patterns ve ignore_patterns kullanarak indirilecek dosyaları filtreleyebilirsiniz.
local_dir sağlanırsa, depodaki dosya yapısı bu konumda yeniden oluşturulur. Bu seçeneği kullanırken cache_dir kullanılmaz ve indirilen dosyalarla ilgili bazı meta verileri depolamak için local_dir kökünde bir .cache/huggingface/ klasörü oluşturulur. Bu mekanizma ana önbellek sistemi kadar sağlam olmasa da, bir deponun en son sürümünü düzenli olarak çekmek için optimize edilmiştir.
Alternatif olarak depoyu klonlamak mümkündür, ancak bunun için git ve git-lfs'in yüklü ve doğru şekilde yapılandırılmış olması gerekir. Ayrıca git kullanarak bir depoyu klonlarken indirilecek dosyaları filtrelemek mümkün değildir.
Önbelleğe alınmış depo ağacını oku
huggingface_hub.get_cached_repo_tree
< source >( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = None ) → list[RepoFile]
Parametreler
- repo_id (
str) — Bir kullanıcı veya kuruluş adı ile/ile ayrılmış bir depo adı. - repo_type (
str, isteğe bağlı) — Liste bir veri seti, space veya kernel deposundan alınıyorsa"dataset","space"veya"kernel"olarak ayarlayın, liste bir modelden alınıyorsaNoneveya"model". Varsayılan değerNone'dir. - revision (
str, isteğe bağlı) — İsteğe bağlı bir Git revizyon kimliği; bir dal adı, etiket veya commit hash olabilir. Varsayılan olarak varsayılan dal kullanılır. Dal/etiket adları, yerel önbellek (refs/) kullanılarak bir commit hash olarak çözümlenir. - cache_dir (
str,Path, isteğe bağlı) — Önbelleğe alınan dosyaların saklandığı klasörün yolu. Varsayılan olarakHF_HUB_CACHEdeğerini kullanır. - local_dir (
strveyaPath, isteğe bağlı) — Verilirse, ana önbellek yerinelocal_dirindirmesi tarafından önbelleğe alınan ağaç listesi (local_dir/.cache/huggingface/) okunur. Branch/tag revizyonları yine de ana önbellek (cache_dir) kullanılarak bir commit hash'ine çözümlenir.
Dönüş değeri
list[RepoFile]
Bu revizyon için önbelleğe alınan RepoFile nesnelerinin listesi.
Yükseltilen
- CachedRepoTreeNotFoundError — İstenen revizyon için önbelleğe alınmış bir ağaç listesi yoksa (ör. depo bu revizyonda hiç indirilmediyse).
Belirli bir revizyondaki bir repoyu ağ çağrısı yapmadan, önbelleğe alınmış ağaç listesini döndürür.
Ağaç listesi, bir commit'teki bir repodaki dosyaların (indirme meta verileriyle birlikte) kümesidir. snapshot_download() işlevinin bir yan etkisi olarak diske yazılır (bkz. trees/<commit_hash>.json önbellek dosyaları) ve sonraki indirmelerde ağ çağrılarını atlamak için kullanılır. Bu işlev, o önbelleği doğrudan açığa çıkarır.
Hub'daki bir repoyun güncel ağaç listesine ihtiyacınız varsa, bunun yerine list_repo_tree() kullanın.
Bir revizyonu çöz
Bir dal/etiket adını bir kez commit hash'ine çözümlen ve her indirmeyi aynı commit'e sabitlemek için sonucu iletin. HfApi.resolve_revision() ve cache-system kılavuzu bkz.
ÇözülenRevizyon
sınıf huggingface_hub.ResolvedRevision
< source >( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )
Zaten bir commit hash'ine çözümlenmiş bir git revizyonu.
ResolvedRevision, bir str alt sınıfıdır; bu nedenle, revision argümanı alan herhangi bir huggingface_hub yöntemine iletilebilir. Dize değeri, kullanıcının başlangıçta istediği revizyondur (ör. "main", "refs/pr/4"); bu sayede URL'ler ve hata mesajları okunabilir kalırken, .resolved alanı bu revizyonun işaret ettiği commit hash değerini barındırır.
Örnekler, revision -> commit hash eşlemesini de yerel önbellekte (refs/ klasörü) önbelleğe alan HfApi.resolve_revision() tarafından oluşturulur.
Bir commit hash, yalnızca çözümlendiği depo için bir anlam taşır; bu nedenle bir örnek, o depoyu da hatırlar. Farklı bir depo için yeniden çözmek bir hata değildir: başlangıçta istenen revizyon yeniden çözümlenir (bkz. HfApi.resolve_revision()).
Örnek:
>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main" # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'Bir dosya hakkında meta verileri alın
get_hf_file_metadata
huggingface_hub.get_hf_file_metadata
< source >( url: strtoken: bool | str | None = Nonetimeout: float | None = 10library_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Noneretry_on_errors: bool = False )
Parametreler
- url (
str) — Dosya url'si, örneğin hf_hub_url() tarafından döndürülen. - token (
strveyabool, isteğe bağlı) — İndirme için kullanılacak bir token. True ise, token HuggingFace yapılandırma klasöründen okunur. False veya None ise, token sağlanmaz. Bir dize ise, kimlik doğrulama token'ı olarak kullanılır.Trueise, token HuggingFace config klasöründen okunur.FalseveyaNoneise, hiçbir token sağlanmaz.- Bir dize ise, kimlik doğrulama jetonu olarak kullanılır.
- timeout (
float, isteğe bağlı, varsayılan 10) — Sunucunun metadata göndermesi için kaç saniye beklenir. - library_name (
str, isteğe bağlı) — Nesnenin karşılık geldiği kütüphanenin adı. - library_version (
str, isteğe bağlı) — Kütüphanenin sürümü. - user_agent (
dict,str, isteğe bağlı) — Sözlük veya dize biçimindeki kullanıcı-ajanı bilgisi. - headers (
dict, isteğe bağlı) — İstekle birlikte gönderilecek ek başlıklar. - endpoint (
str, isteğe bağlı) — Hub uç noktası. Varsayılan olarak https://huggingface.co. - retry_on_errors (
bool, isteğe bağlı, varsayılanFalse) — Hatalarda (429, 5xx, zaman aşımı, ağ hataları) yeniden deneme yapılıp yapılmayacağı. False ise, yerel önbelleğe hızlı geri dönüş için yeniden deneme yapılmaz.
Belirtilen bir URL için Hub'da sürüm kontrolü yapılan bir dosyanın meta verilerini getirir.
HfFileMetadata
sınıf huggingface_hub.HfFileMetadata
< source >( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )
Parametreler
- commit_hash (
str, isteğe bağlı) — Dosyayla ilgili commit_hash. - etag (
str, isteğe bağlı) — Sunucudaki dosyanın etag değeri. - location (
str) — Dosyanın indirileceği konum. Bir Hub URL'si olabilir veya olmayabilir (CDN). - size (
size) — Dosyanın boyutu. LFS dosyası durumunda, işaretçinin değil, gerçek LFS dosyasının boyutunu içerir. - xet_file_data (
XetFileData, isteğe bağlı) — Dosya için Xet bilgisi. Bu, dosya yalnızca Xet depolaması kullanılarak saklanıyorsa ayarlanır.
Hub üzerinde sürüm kontrolü yapılan bir dosya hakkında bilgi içeren veri yapısı.
Bir URL'ye dayalı olarak get_hf_file_metadata() tarafından döndürülür.
Önbelleğe Alma
Yukarıda gösterilen yöntemler, dosyaların yeniden indirilmesini önleyen bir önbellekleme sistemiyle çalışacak şekilde tasarlanmıştır. Önbellekleme sistemi, Hub'a bağımlı kütüphaneler arasında paylaşılan merkezi önbellek sistemi haline gelmesi için v0.8.0 sürümünde güncellenmiştir.
HF'de önbellekleme hakkında ayrıntılı bir sunum için cache-system kılavuzunu okuyun.
Update on GitHub