Xet Depolama Kullanımı

Python

huggingface_hub'un Xet destekli sürümüne erişmek için en son sürümü kurmanız yeterlidir:

pip install -U huggingface_hub

huggingface_hub 0.32.0 sürümünden itibaren bu işlem ayrıca hf_xet paketini de yükler. hf_xet paketi, huggingface_hub’ü Xet altyapısının Rust istemcisi olan xet-core ile entegre eder.

transformers veya datasets kütüphanelerini kullanıyorsanız, zaten huggingface_hub kullanılıyor demektir. huggingface_hub sürümü >= 0.32.0 ise, başka bir işlem yapmanıza gerek yoktur.

huggingface_hub sürümünün >= 0.30.0 ve < 0.32.0 aralığında olduğu durumlarda, hf_xet paketinin açıkça kurulması gerekir:

pip install -U hf-xet

Ve tamam! Artık hem yükleme hem de indirme işlemleri için Xet çakışma giderme avantajlarından yararlanırsınız. huggingface_hub sürümü 0.30.0’tan düşük olan ekip üyeleri, LFS köprüsü tarafından sağlanan geriye dönük uyumluluk sayesinde depoları yine de yükleyebilir ve indirebilir.

Daha ayrıntılı kullanım belgeleri için şunların huggingface_hub belgelerine başvurun:

• Yükle
• İndir
• hf_xet önbelleğini yönetme

Git

Git kullanıcıları, Git Xet eklentisini indirip kurarak Xet'in avantajlarından yararlanabilir. Kurulumdan sonra, Hub depolarını Git ile yönetmek için standart iş akışlarını kullanmanız yeterlidir - ek bir değişiklik gerekmez.

Ön koşullar

Git ve Git LFS kurun.

macOS veya Linux (amd64 veya aarch64) üzerinde kurulum

Terminalde aşağıdaki komutu kullanarak bir kurulum betiğiyle yükleyin (curl ve unzip gerektirir):

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/huggingface/xet-core/refs/heads/main/git_xet/install.sh | sh

Veya Homebrew kullanarak yükleyin:

brew install git-xet
git xet install

Yükleme doğrulamak için şunu çalıştırın:

git xet --version

Windows (amd64)

winget kullanarak:

winget install git-xet

Kurucu kullanma:

• git-xet-windows-installer-x86_64.zip dosyasını indirin (buradan erişilebilir) ve arşivden çıkarın.
• msi kurucu dosyasını çalıştırın ve yönergeleri izleyin.

Manuel kurulum:

• git-xet-windows-x86_64.zip dosyasını indirin (buradan erişilebilir) ve arşivi açın.
• Çıkarılan git-xet.exe dosyasını bir PATH dizinine yerleştirin.
• Bir terminalde git xet install komutunu çalıştırın.

Yükleme doğrulamak için şunu çalıştırın:

git xet --version

Git Xet Kullanımı

Platformunuza kurulduktan sonra, Git Xet'i kullanmak, Hub'ın standart Git iş akışlarını izlemekten ibarettir.

Tüm ön koşulların yüklendiğinden ve yapılandırıldığından emin olun, Hub'daki depolarla çalışmak için kurulum talimatlarını izleyin, ardından değişikliklerinizi commit edin ve Hub'a push yapın:

# Create any files you like! Then...
git add .
git commit -m "Uploading new models"  # You can choose any descriptive message
git push

Arka planda, büyük dosyaları doğrudan Xet depolamasına yüklemek için Xet protokolü çağrılır ve parça düzeyinde kopya azaltma gücü sayesinde yükleme hızları artırılır.

macOS veya Linux'ta kaldırma

Homebrew kullanılarak:

git xet uninstall
brew uninstall git-xet

Eğer kurulum betiğini (MacOS veya Linux için) kullandıysanız, terminalinizde şunu çalıştırın:

git xet uninstall
sudo rm $(which git-xet)

Windows'ta kaldırma

winget kullandıysanız:

winget uninstall git-xet

Kurulum aracını kullandıysanız:

• Ayarlar -> Uygulamalar -> Yüklü uygulamalar bölümüne gidin
• “Git-Xet” öğesini bulun.
• Bağlam menüsünde bulunan “Uninstall” seçeneğini seçin.

Eğer manuel olarak kurduysanız:

• Bir terminalde git xet uninstall komutunu çalıştırın.
• git-xet.exe dosyasını, başlangıçta yerleştirildiği konumdan silin.

Öneriler

Xet, Hub’ın tüm iş akışlarıyla kusursuz bir şekilde bütünleşir. Ancak, Xet depolamasından en iyi şekilde yararlanmak için göz önünde bulundurabileceğiniz birkaç adım vardır.

Python ile yüklerken veya indirirken:

• hf_xet paketinin yüklü olduğundan emin olun: Xet, Git LFS için optimize edilmiş eski istemcilerle geriye dönük uyumlu kalmaya devam etse de, hf_xet ile huggingface_hub entegrasyonu, büyük dosyalarda optimal parça tabanlı performans ve daha hızlı yineleme sağlar.
• Adaptif eşzamanlılık varsayılan olarak açıktır: hf_xet, gerçek zamanlı ağ koşullarına göre paralel aktarım akışlarının sayısını otomatik olarak ayarlar — yapılandırma gerekmez. Varsayılan ayarlar, herhangi bir ince ayar yapılmadan çoğu ağ yolunu doyurur.
• İndirme tamponları sistem belleğiyle ölçeklenir: hf_xet 1.7.0 sürümünden itibaren, indirme tamponları hf_xet için kullanılabilir belleğe göre boyutlandırılır; bu, konteyner bellek sınırlarını da içerir. Küçük konteynerler indirmeler için daha az bellek kullanırken büyük makineler daha fazla bellek kullanır ve bunun için herhangi bir ayar gerekmez. İndirme Tamponları bölümüne bakın.
• Gelişmiş ayarlar: İnce taneli kontrol için, HF_XET_FIXED_DOWNLOAD_CONCURRENCY ve HF_XET_FIXED_UPLOAD_CONCURRENCY eşzamanlılığı sabit bir değere sabitlemenize ve adaptif denetleyiciyi atlamaya izin verir. Tüm seçeneklerin listesi için hf_xet'in ortam değişkenleri bölümüne bakın.

Git veya Python'da yükleme veya indirme sırasında:

• Sık ve artımlı commit'lerden yararlanın: Xet'in parça düzeyindeki kopya kaldırma özelliği sayesinde modelleri veya veri setlerini güvenle artımlı olarak güncelleyebilirsiniz. Yalnızca değişen parçalar yüklendiğinden sık commit'ler hem hızlı hem de depolama açısından verimlidir.
• .gitattributes Dosyasında Spesifik Olun: Xet veya LFS için desenler tanımlarken, küçük dosyaların gereksiz yere büyük dosya depolamasına yönlendirilmesini önlemek için kesin dosya uzantıları (ör. *.safetensors, *.bin) kullanın.
• Topluluk erişimini önceliklendirin: Xet, büyük dosya aktarımlarının verimliliğini ve ölçeğini önemli ölçüde artırır. Deponuzu toplam boyutunu (veya bireysel dosyaların boyutunu) azaltacak şekilde yapılandırmak yerine, işbirlikçilerin ve topluluk kullanıcılarının ihtiyaç duydukları içeriği kolayca bulup alabilmeleri için yapılandırın.

Ortam Değişkenleri

Hem hf_xet hem de Git Xet, xet-core tarafından desteklenir ve ortam değişkenleri aracılığıyla yapılandırılabilir. Aşağıdaki tablolar, ince ayar için bireysel değişkenleri listeler. Çoğu kullanıcının bunlardan herhangi birini değiştirmesi gerekmez — varsayılanlar, çoğu ağ yolunu otomatik olarak doyuracak şekilde ayarlanmıştır.

HF_XET_HIGH_PERFORMANCE=1, birden fazla ayarı tek seferde düzenleyen bir kolaylık bayrağıdır (eşzamanlılık sınırları, tampon boyutları ve paralel dosya limitleri). Yüksek bant genişliğine ve hızlı diske sahip makineler için tasarlanmıştır. hf_xet 1.7.0 sürümünden itibaren, bu bayrağın ayarladığı tampon boyutları hf_xet için kullanılabilir belleğe dayanmaktadır (bkz. İndirme Tamponları), bu nedenle artık 64 GB RAM gerektirmez ve kendiniz ayarladığınız herhangi bir değişken bu bayrağa öncelik kazanır. Önceki sürümlerde, bu bayrağı yalnızca en az 64 GB RAM'e sahip makinelerde kullanın.

Genel

Çoğu kullanıcının ilk başvurduğu yüksek düzey bayraklar.

Adaptif Eşzamanlılık

Varsayılan olarak xet-core adaptif eşzamanlılık kullanır — paralelliği gerçek zamanlı ağ koşullarına göre dinamik olarak ayarlar. Bu, çoğu durumda ihtiyaç duyulması beklenmeyen gelişmiş ayarlardır. Aşağıdaki değişkenler adaptif denetleyicinin davranışını kontrol eder:

Eşzamanlılığı sabit bir değere sabitlemek için (uyarlayıcı denetleyiciyi atlayarak) HF_XET_FIXED_UPLOAD_CONCURRENCY ve HF_XET_FIXED_DOWNLOAD_CONCURRENCY pratik takma adlarını kullanın. Bunlar, başlangıç, minimum ve maksimum eşzamanlılığı aynı değere ayarlar.

Ağ ve Yeniden Deneme

Veri Transferi

Tamponları İndir

Bu ayarlar, indirme sırasında bellek kullanımını kontrol eder.

hf_xet 1.7.0 sürümünden itibaren, üç DOWNLOAD_BUFFER değişkeninin varsayılan değerleri, hf_xet'in kullanabileceği bellek miktarına dayanır. Bu, makinenin RAM'idir; bu değer daha düşükse, konteynerin bellek sınırıdır. Her bir varsayılan değer, bu belleğin bir kesridir ve tabloda gösterilen asgari ile azami değerler arasında tutulur. HP modu, aynı asgari ve azami değerlerle, kesrin iki katını kullanır. Örneğin, 4 GB ile sınırlı bir konteyner, 1 GB sınırıyla yaklaşık 256 MB'lık bir tampon alır; 32 GB'lık bir makine ise önceki sürümlerdeki gibi yaklaşık 2 GB'lık tampon ve 8 GB'lık sınırı alır.

Daha önceki sürümler veya kullanılabilir bellek miktarını tespit edemeyen herhangi bir sürüm, 2gb, 512mb ve 8gb (16gb, 2gb ve 64gb HP modunda) sabit varsayılan değerlerini kullanır. Kullanılan değerler, hf_xet günlük dosyası başlatıldığında bu dosyaya yazılır (bkz. Kayıt Tutma).

Shard Önbelleği

shard cache, disk üzerinde Xet önbellek dizini altında, yinelenen veri indeksini (zaten yüklenmiş parçaları tanımlayan “shard”lar) tutar. Daha büyük bir önbellek, istemcinin daha fazla önceki veriyle yinelenen verileri ayıklamasına olanak tanır; böylece yeniden yüklenen bayt sayısı azalır.

Parça Önbelleği

chunk önbelleği, indirilen bayt aralıklarını (chunk'ları) diskte saklar ve böylece üst üste binen veriler depolamadan yeniden alınmaz. Bu özellik, ilişkili modellerin veya veri setlerinin tekrar tekrar indirilmesi ya da yeni revizyonlarının oluşturulması durumlarında en faydalıdır.

Kayıt Tutma

Telemetri

hf_xet, her yükleme ve indirmeden sonra kısa bir rapor gönderir. İçeriği hakkında bilgi için Telemetri bölümüne bakın. Kapatmak için HF_HUB_DISABLE_TELEMETRY=1 değerini ayarlayın.

Mevcut Kısıtlamalar

Xet, Git tabanlı depolamaya ince taneli kopya azaltma (deduplication) ve geliştirilmiş performans getirirken, bazı özellikler ve platform uyumlulukları hâlâ geliştirme aşamasındadır. Bu nedenle, Xet destekli bir depo ile çalışırken aşağıdaki kısıtlamaları göz önünde bulundurun:

• Sadece 64-bit sistemler: Hem hf_xet hem de Git Xet şu anda 64-bit mimari gerektirir; 32-bit sistemler desteklenmez.