Ortam değişkenleri

huggingface_hub, ortam değişkenleri kullanılarak yapılandırılabilir.

Ortam değişkeniyle (environment variable) aşinalık yoksa, bunlar hakkında genel makaleler macOS ve Linux için ve Windows için mevcuttur.

Bu sayfa, huggingface_hub'e özgü tüm ortam değişkenlerini ve anlamlarını adım adım açıklar.

Tüm ortam değişkenleri, huggingface_hub içe aktarıldığında okunur. Sonrasında yapılan herhangi bir değişiklik dikkate alınmaz. huggingface_hub içe aktarılmadan önce ortam değişkenlerinizi ayarladığınızdan emin olun.

Genel

HF_INFERENCE_ENDPOINT

Çıkarım API'sinin temel URL'sini yapılandırmak için. Organizasyonunuz çıkarım API'sine doğrudan değil, bir API Gateway'ine işaret ediyorsa bu değişkeni ayarlamak isteyebilirsiniz.

Varsayılan olarak "https://huggingface.co/proxy/api-inference.huggingface.co" değerine ayarlanır.

HF_HOME

huggingface_hub'ün verileri yerel olarak nerede saklayacağını yapılandırmak için. Özellikle, token'ınız ve önbellek bu klasörde saklanır.

XDG_CACHE_HOME ayarlanmadıkça varsayılan olarak "~/.cache/huggingface" değerini kullanır.

HF_HUB_CACHE

Hub'dan gelen depoların (modeller, veri kümeleri ve alanlar) yerel olarak nerede önbelleğe alınacağını yapılandırmak için.

Varsayılan olarak "$HF_HOME/hub" (varsayılan olarak "~/.cache/huggingface/hub").

HF_XET_CACHE

Xet'in shard önbelleğini ve yükleme geçici verilerini yerel olarak nerede saklayacağını yapılandırmak için. Daha fazla ayrıntı için Xet önbellekleme bölümüne bakın.

Varsayılan olarak "$HF_HOME/xet" (varsayılan olarak "~/.cache/huggingface/xet").

HF_ASSETS_CACHE

Aşağıdaki kütüphaneler tarafından oluşturulan varlıkların yerel olarak nerede önbelleğe alınacağını yapılandırmak için kullanılır. Bu varlıklar, ön işlenmiş veriler, GitHub'dan indirilen dosyalar, günlükler,… olabilir.

Varsayılan olarak "$HF_HOME/assets" (varsayılan olarak "~/.cache/huggingface/assets").

HF_TOKEN

Hub'a kimlik doğrulama için Kullanıcı Erişim Belirteci'ni yapılandırmak için. Ayarlanırsa, bu değer makinede saklanan belirtecin üzerine yazar (önceki ayarlanmadıysa $HF_TOKEN_PATH veya "$HF_HOME/token").

Kimlik doğrulama hakkında daha fazla ayrıntı için bu bölümü inceleyin.

HF_TOKEN_PATH

huggingface_hub'ün Kullanıcı Erişim Belirteçini (User Access Token) nerede saklayacağını yapılandırmak için. Varsayılan olarak "$HF_HOME/token" (ör. varsayılan olarak ~/.cache/huggingface/token).

HF_HUB_VERBOSITY

huggingface_hub kayıtçısının ayrıntı düzeyini ayarlar. {"debug", "info", "warning", "error", "critical"} değerlerinden biri olmalıdır.

Varsayılan olarak "warning" değerine ayarlanır.

Daha fazla ayrıntı için kayıt referansına bakın.

HF_HUB_ETAG_TIMEOUT

Bir depodan dosya indirmeden önce en güncel meta verileri alırken sunucu yanıtını bekleme süresini saniye cinsinden tanımlamak için tamsayı değer. İstek zaman aşımına uğrarsa, huggingface_hub yerel olarak önbelleğe alınmış dosyalara geçer. Daha düşük bir değer, dosyaları zaten önbelleğe almış ve yavaş bir bağlantıya sahip makineler için iş akışını hızlandırır. Daha yüksek bir değer, meta veri çağrısının daha fazla durumda başarılı olmasını garanti eder. Varsayılan değer 10 sn'dir.

HF_HUB_DOWNLOAD_TIMEOUT

Bir dosya indirilirken sunucu yanıtını bekleme süresini saniye cinsinden tanımlamak için tamsayır değer. İstek zaman aşımına uğrarsa bir TimeoutError oluşturulur. Yavaş bağlantıya sahip makinelerde daha yüksek bir değer ayarlamak faydalıdır. Tam bir ağ kesintisi durumunda daha küçük bir değer, sürecin daha hızlı başarısız olmasını sağlar. Varsayılan değer 10 sn'dir.

Xet

Diğer Xet ortam değişkenleri

• HF_HUB_DISABLE_XET
• HF_XET_CACHE
• HF_XET_HIGH_PERFORMANCE
• HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

HF_XET_CHUNK_CACHE_SIZE_BYTES

Bu değişken artık herhangi bir etkiye sahip değildir. hf_xet indirmeler için yerel bir parça önbelleği kullanmaz ve bu değişkeni ayarlamak bir önbellek etkinleştirmez. Ayrıntılar için xet-core#715 konusuna bakın.

HF_XET_SHARD_CACHE_SIZE_LIMIT

Xet shard önbelleğinin boyutunu yerel olarak ayarlamak için. Bu değeri artırmak, önbelleğe alınmış shard dosyalarında referans verilen parçaların yeniden yüklenmemesi nedeniyle yükleme verimliliğini artırır. Çoğu iş yükü için varsayılan yumuşak sınırın yeterli olabileceğini unutmayın.

Varsayılan olarak 16000000000 (16GB) değerine ayarlıdır.

HF_XET_NUM_CONCURRENT_RANGE_GETS

Bu değişken artık kullanılmamaktadır. hf_xet 1.3.0 sürümünden itibaren indirme eşzamanlılığı uyumlu olarak (adaptif) kontrol edilir.

Boolean değerleri

Aşağıdaki ortam değişkenleri bir boolean değer bekler. Değeri {"1", "ON", "YES", "TRUE"} (büyük/küçük harf duyarsız) değerlerinden biri olan değişken True olarak kabul edilir. Diğer herhangi bir değer (tanımlanmamış dahil) False olarak kabul edilir.

HF_DEBUG

Ayarlanırsa, huggingface_hub kayıtçısının (logger) log seviyesi DEBUG olarak ayarlanır. Ayrıca, HF kütüphaneleri tarafından yapılan tüm istekler, hata ayıklama ve yeniden üretilebilirlik kolaylığı için eşdeğer cURL komutları olarak kaydedilir.

HF_HUB_OFFLINE

Ayarlanırsa, Hugging Face Hub'a HTTP çağrıları yapılmaz. Dosya indirmeye çalışırsanız, yalnızca önbellekteki dosyalara erişilir. Önbellek dosyası algılanmazsa bir hata oluşturulur. Bu, ağınız yavaşsa ve bir dosyanın en son sürümüne sahip olmanız önemli değilse faydalıdır.

HF_HUB_OFFLINE=1 ortam değişkeni olarak ayarlandıysa ve HfApi'nin herhangi bir metodu çağrılırsa, OfflineModeIsEnabled istisnası oluşturulur.

Not: Bir dosyanın en son sürümü önbelleğe alınmış olsa bile, hf_hub_download çağrısı, yeni bir sürümün mevcut olup olmadığını kontrol etmek için yine de bir HTTP isteği tetikler. HF_HUB_OFFLINE=1 ayarını yapmak bu çağrıyı atlar ve yükleme sürenizi hızlandırır.

Çevrimdışı modun etkin olup olmadığını kontrol etmek istiyorsanız is_offline_mode() yardımcısını kullanabilirsiniz.

HF_HUB_DISABLE_IMPLICIT_TOKEN

Hub'a yapılan her istek için kimlik doğrulama zorunlu değildir. Örneğin, "gpt2" modeline ait ayrıntıları istemek için kimlik doğrulanmış olmak gerekmez. Ancak bir kullanıcı giriş yapmışsa, özel veya kısıtlı depolara erişirken kullanıcı deneyimini kolaylaştırmak (asla HTTP 401 Yetkisiz hatası almamak) için varsayılan davranış, token'ı her zaman göndermektir. Gizlilik için bu davranışı HF_HUB_DISABLE_IMPLICIT_TOKEN=1 değerini ayarlayarak devre dışı bırakabilirsiniz. Bu durumda, token yalnızca “yazma erişimi” gerektiren çağrılar için (örnek: bir commit oluşturmak) gönderilir.

Not: token'ın örtük gönderimini devre dışı bırakmak garip yan etkilere yol açabilir. Örneğin, Hub'daki tüm modelleri listelemek istiyorsanız, özel modelleriniz listelenmez. Betik dosyanızda token=True argümanını açıkça geçirmeniz gerekir.

HF_HUB_DISABLE_PROGRESS_BARS

Zaman alıcı görevlerde, huggingface_hub varsayılan olarak bir ilerleme çubuğu görüntüler (tqdm kullanılarak). HF_HUB_DISABLE_PROGRESS_BARS=1 değerini ayarlayarak tüm ilerleme çubuklarını tek seferde devre dışı bırakabilirsiniz.

HF_HUB_DISABLE_SYMLINKS

Ayarlanırsa, huggingface_hub önbellekte asla sembolik bağlantı oluşturmaz. Bunun yerine dosyalar doğrudan görüntü dizinlerine kopyalanır veya taşınır. Bu, önbellek dizininin devasa dosyaların sabit sürücünüzde çoğaltıldığı bir bozulmuş modda çalışmasını sağlayan ileri düzey bir özelliktir.

Örnek bir kullanım senaryosu, farklı işletim sistemlerinde çalışan makinelerde HF_HUB_CACHE olarak paylaşılan bir ağ sürücüsünün (ör. NAS) kullanılmasıdır. Linux'ta oluşturulan sembolik bağlantılar Windows'ta her zaman gezilebilir olmayabilir ve bu durum hatalara yol açabilir. HF_HUB_DISABLE_SYMLINKS=1 ayarını yapmak, disk alanı yinelenme önleme özelliğinden vazgeçilerek bu sorunu önler.

HF_HUB_DISABLE_SYMLINKS_WARNING

Windows makinesinde çalışıyorsanız, geliştirici modunu etkinleştirmeniz veya huggingface_hub paketini yönetici modunda çalıştırmanız önerilir. Aksi takdirde huggingface_hub, önbellek sisteminizde sembolik bağlantılar oluşturamaz. Herhangi bir betiği çalıştırabilirsiniz ancak sabit diskte bazı büyük dosyaların kopyalanması nedeniyle kullanıcı deneyiminiz olumsuz etkilenebilir. Bu davranış hakkında sizi uyarmak için bir uyarı mesajı tetiklenir. Bu uyarıyı devre dışı bırakmak için HF_HUB_DISABLE_SYMLINKS_WARNING=1 değerini ayarlayın.

Daha fazla ayrıntı için önbellek kısıtlamaları bölümüne bakın.

HF_HUB_DISABLE_EXPERIMENTAL_WARNING

huggingface_hub kütüphanesinin bazı özellikleri deneyseldir. Bu, bu özellikleri kullanabileceğiniz ancak gelecekte bunların sürdürüleceğinin garanti edilmediği anlamına gelir. Özellikle, bu tür özelliklerin API’sini veya davranışını herhangi bir aşamalı kaldırma döngüsü olmadan güncelleyebiliriz. Deneysel bir özellik kullanıldığında, sizi bu konuda uyarmak için bir uyarı mesajı tetiklenir. Deneysel bir özellik kullanırken ortaya çıkabilecek olası sorunları hata ayıklamakta sorun yaşamıyorsanız, uyarıyı devre dışı bırakmak için HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 değerini ayarlayabilirsiniz.

Deneysel bir özellik kullanıyorsanız, lütfen bize bildirin! Geri bildirimleriniz, özelliğin tasarımını ve iyileştirilmesini yapmamıza yardımcı olabilir.

HF_HUB_DISABLE_TELEMETRY

Varsayılan olarak, HF kütüphaneleri (transformers, datasets, gradio,..) kullanımını izlemek, sorunları ayıklamak ve özelliklere öncelik vermek için bazı verileri toplar. Her kütüphane kendi politikasını (yani hangi kullanımın izleneceğini) tanımlar ancak çekirdek uygulama huggingface_hub içinde gerçekleşir (bkz. send_telemetry).

Telemetriyi küresel olarak devre dışı bırakmak için HF_HUB_DISABLE_TELEMETRY=1 değerini ortam değişkeni olarak ayarlayabilirsiniz.

HF_HUB_DISABLE_UPDATE_CHECK

Varsayılan olarak hf CLI, başlangıçta (en fazla 24 saatte bir) PyPI'de daha yeni bir sürüm olup olmadığını kontrol eder ve mevcut olduğunda stderr'e, hf update öneren tek satırlık sarı bir uyarı basar. Bu kontrol, geliştirme ve ön sürüm versiyonlarında zaten hiçbir işlem yapmaz.

Ayrıca hf-cli becerisinin yüklü olup olmadığını ve çalıştırılan sürüm tarafından üretilip üretilmediğini (en fazla 24 saatte bir, tamamen yerel olarak) kontrol eder ve değilse hf skills add / hf skills update komutlarını önerir. Bu kontrol yalnızca bir ipucu görüntüler, beceri dizinlerinize asla dokunmaz.

Yüklü bir CLI eklentisi çalıştırılmadan önce, GitHub üzerinde daha yeni bir commit olup olmadığını (eklenti başına en fazla 24 saatte bir) kontrol eder ve varsa hf extensions update <name> komutunu önerir. hf extensions list komutu, LATEST sütunu için aynı kontrolü kullanır.

Bu istekleri atlamak ve tüm bu ipuçlarını sessize almak için HF_HUB_DISABLE_UPDATE_CHECK=1 değerini ayarlayın. Çevrimdışı CI ortamlarında veya daha sakin bir kabuk çıktısı tercih ettiğinizde faydalıdır.

HF_HUB_DISABLE_XET

Python ortamınızda hf-xet mevcut olsa bile onu kullanmayı devre dışı bırakmak için ayarlayın. hf-xet bulunduğunda otomatik olarak kullanılacağından, bu ayar kullanımını açıkça devre dışı bırakmanıza olanak tanır. Xet'i devre dışı bırakıyorsanız, Xet'in neden sizin için çalışmadığını anlamamıza yardımcı olmak için bir sorun bildirip teşhis bilgilerini dahil etmeyi lütfen düşünün.

HF_HUB_ENABLE_HF_TRANSFER

Bu, kullanımdan kaldırılmış bir ortam değişkenidir. Hugging Face Hub artık tamamen Xet depolama altyapısıyla çalıştığından, tüm dosya aktarımları hf-xet ikili paketi üzerinden gerçekleştirilir. Bu paket, parça tabanlı bir kopya azaltma stratejisi kullanarak verimli aktarımlar sağlar ve huggingface_hub ile kusursuz bir şekilde entegre olur. Bu, hf_transfer'in artık kullanılamayacağı anlamına gelir. Daha yüksek performansla ilgileniyorsanız, HF_XET_HIGH_PERFORMANCE bölümüne göz atın.

HF_HUB_DISABLE_SHARED_BLOBS

Önbellek genelinde paylaşılan blob deposunu devre dışı bırakmak için 1 olarak ayarlayın. Varsayılan olarak, başarıyla indirilen Xet dosyaları <CACHE_DIR>/blobs/<prefix>/<xet_hash> konumunda saklanır ve depo önbelleklerine sembolik bağlantılarla eklenir; böylece aynı dosyalar depolar arasında diskte yalnızca bir kez saklanır ve yeniden alınmadan yeniden kullanılabilir. Bu optimizasyon varsayılan olarak etkinleştirilmiştir, ancak Xet kullanılamıyorsa (ör. HF_HUB_DISABLE_XET=1 ayarlanmışsa) veya sembolik bağlantılar yerel olarak desteklenmiyorsa devre dışı bırakılır. Bu durumlarda sessizce standart depo yerel depolamaya geri düşer. Ayrıntılar için önbelleğe alma kılavuzuna bakın.

HF_XET_HIGH_PERFORMANCE

hf-xet'i, makinedeki ağ ve disk kaynaklarını en üst düzeye çıkarmak için artırılmış ayarlarla çalışacak şekilde yapılandırın. Yüksek performans modunu etkinleştirmek, bu makinenin ağ bant genişliğini doyurmayı ve paralel yükleme/indirme etkinliği için tüm CPU çekirdeklerini kullanmayı deneyecektir.

Bunu, hf-xet uygulanan eski HF_HUB_ENABLE_HF_TRANSFER=1 ortam değişkenine benzetin.

Xet depolama ve hf_xet avantajları hakkında daha fazla bilgi için bu bölüme bakın.

HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

Bu değişken artık kullanılmıyor. hf_xet 1.3.0 sürümünden itibaren dosyalar her zaman yerel diske sıralı olarak yazılır (bkz. v1.3.0'daki dosya yazıcısı).

Kullanımı durdurulan ortam değişkenleri

Hugging Face ekosistemindeki tüm ortam değişkenlerini standartlaştırmak amacıyla bazı değişkenler kullanımdan kaldırılmış (deprecated) olarak işaretlenmiştir. Bu değişkenler hâlâ çalışmaya devam etse de, artık yerlerine geçen değişkenlere göre öncelik taşımazlar. Aşağıdaki tablo, kullanımdan kaldırılan değişkenleri ve bunlara karşılık gelen alternatifleri özetlemektedir:

Kullanımdan Kaldırılan Değişken	Değiştirme
HUGGINGFACE_HUB_CACHE	HF_HUB_CACHE
HUGGINGFACE_ASSETS_CACHE	HF_ASSETS_CACHE
HUGGING_FACE_HUB_TOKEN	HF_TOKEN

Dış araçlardan

Bazı ortam değişkenleri huggingface_hub'e özgü olmasa da ayarlandıklarında dikkate alınır.

DO_NOT_TRACK

Boolean değeri. HF_HUB_DISABLE_TELEMETRY ile eşdeğerdir. true olarak ayarlandığında, telemetri Hugging Face Python ekosisteminde (transformers, diffusers, gradio vb.) küresel olarak devre dışı bırakılır. Daha fazla ayrıntı için https://donottrack.sh/ adresine bakın.

NO_COLOR

Boolean değeri. Ayarlandığında, hf CLI hiçbir ANSI rengi yazdırmaz. Bkz. no-color.org.

XDG_CACHE_HOME

Yalnızca HF_HOME ayarlanmadığında kullanılır!

Linux makinelerinde kullanıcıya özel, kritik olmayan (önbelleğe alınmış) verilerin nereye yazılacağı için varsayılan yapılandırma yöntemi budur.

HF_HOME ayarlanmamışsa, varsayılan ana dizin "~/.cache/huggingface" yerine "$XDG_CACHE_HOME/huggingface" olur.

Update on GitHub