Menggunakan Penyimpanan Xet

Python

Untuk mengakses versi huggingface_hub yang mendukung Xet, cukup instal versi terbaru:

pip install -U huggingface_hub

Sejak huggingface_hub 0.32.0, ini juga akan menginstal hf_xet. Paket hf_xet mengintegrasikan huggingface_hub dengan xet-core, klien Rust untuk backend Xet.

Jika Anda menggunakan pustaka transformers atau datasets, pustaka tersebut sudah menggunakan huggingface_hub. Selama versi huggingface_hub >= 0.32.0, tidak perlu dilakukan tindakan lebih lanjut.

Jika versi huggingface_hub >= 0.30.0 dan < 0.32.0 terpasang, hf_xet harus dipasang secara eksplisit:

pip install -U hf-xet

Dan selesai! Anda kini mendapatkan manfaat deduplikasi Xet untuk kedua unggahan dan unduhan. Anggota tim yang menggunakan versi huggingface_hub < 0.30.0 masih akan dapat mengunggah dan mengunduh repositori melalui kemampuan kompatibilitas mundur yang disediakan oleh jembatan LFS.

Untuk melihat dokumentasi penggunaan yang lebih detail, lihat dokumentasi huggingface_hub untuk:

• Unggah
• Unduh
• Mengelola cache hf_xet

Git

Pengguna Git dapat mengakses manfaat Xet dengan mengunduh dan menginstal ekstensi Git Xet. Setelah terinstal, cukup gunakan alur kerja standar untuk mengelola repositori Hub dengan Git - tidak diperlukan perubahan tambahan.

Prasyarat

Instal Git dan Git LFS.

Instal di macOS atau Linux (amd64 atau aarch64)

Instal menggunakan skrip instalasi dengan perintah berikut di terminal Anda (memerlukan curl dan unzip):

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

Atau, instal menggunakan Homebrew:

brew install git-xet
git xet install

Untuk memverifikasi instalasi, jalankan:

git xet --version

Windows (amd64)

Menggunakan winget:

winget install git-xet

Menggunakan program instalasi:

• Unduh git-xet-windows-installer-x86_64.zip (tersedia di sini) dan ekstrak.
• Jalankan file installer msi dan ikuti instruksi yang muncul.

Instalasi manual:

• Unduh git-xet-windows-x86_64.zip (tersedia di sini) dan ekstrak.
• Letakkan git-xet.exe yang telah diekstrak di bawah direktori PATH.
• Jalankan git xet install di terminal.

Untuk memverifikasi instalasi, jalankan:

git xet --version

Menggunakan Git Xet

Setelah diinstal di platform Anda, penggunaan Git Xet sama mudahnya dengan mengikuti alur kerja Git standar Hub.

Pastikan semua prasyarat terpasang dan dikonfigurasi, ikuti instruksi pengaturan untuk bekerja dengan repositori di Hub, lalu commit perubahan Anda, dan push ke Hub:

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

Di balik layar, protokol Xet dipanggil untuk mengunggah file besar langsung ke penyimpanan Xet, meningkatkan kecepatan unggahan melalui kekuatan deduplikasi tingkat chunk.

Membatalkan pemasangan di macOS atau Linux

Menggunakan Homebrew:

git xet uninstall
brew uninstall git-xet

Jika Anda menggunakan skrip instalasi (untuk MacOS atau Linux), jalankan perintah berikut di terminal Anda:

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

Membatalkan pemasangan di Windows

Jika Anda menggunakan winget:

winget uninstall git-xet

Jika Anda menggunakan installer:

• Buka Settings -> Apps -> Installed apps
• Cari “Git-Xet”.
• Pilih opsi “Uninstall” yang tersedia di menu konteks.

Jika Anda menginstal secara manual:

• Jalankan git xet uninstall di terminal.
• Hapus file git-xet.exe dari lokasi tempat file tersebut awalnya ditempatkan.

Rekomendasi

Xet terintegrasi dengan mulus ke semua alur kerja Hub. Namun, ada beberapa langkah yang mungkin perlu Anda pertimbangkan untuk mendapatkan manfaat maksimal dari penyimpanan Xet.

Saat mengunggah atau mengunduh dengan Python:

• Pastikan hf_xet terpasang: Meskipun Xet tetap kompatibel mundur dengan klien lama yang dioptimalkan untuk Git LFS, integrasi hf_xet dengan huggingface_hub memberikan performa berbasis chunk yang optimal dan iterasi yang lebih cepat pada file besar.
• Konkurensi adaptif aktif secara bawaan: hf_xet secara otomatis menyesuaikan jumlah stream transfer paralel berdasarkan kondisi jaringan secara real-time — tanpa perlu konfigurasi. Pengaturan bawaan akan memaksimalkan sebagian besar jalur jaringan tanpa penyetelan apa pun.
• Buffer unduhan berskala dengan memori sistem: Mulai dari hf_xet 1.7.0, ukuran buffer unduhan ditentukan dari memori yang tersedia untuk hf_xet, termasuk batas memori container. Container kecil menggunakan memori lebih sedikit untuk unduhan dan mesin besar menggunakan lebih banyak, tanpa perlu pengaturan. Lihat Buffer Unduhan.
• Penyetelan lanjutan: Untuk kontrol yang lebih rinci, HF_XET_FIXED_DOWNLOAD_CONCURRENCY dan HF_XET_FIXED_UPLOAD_CONCURRENCY memungkinkan Anda menetapkan konkurensi ke nilai tetap, melewati pengendali adaptif. Lihat variabel lingkungan dari hf_xet untuk daftar lengkap opsi.

Saat mengunggah atau mengunduh di Git atau Python:

• Memanfaatkan commit yang sering dan bertahap: Deduplikasi pada tingkat chunk dari Xet memungkinkan Anda melakukan pembaruan bertahap pada model atau dataset dengan aman. Hanya chunk yang berubah yang diunggah, sehingga commit yang sering dilakukan menjadi cepat dan efisien dalam penyimpanan.
• Jadilah Spesifik di .gitattributes: Saat mendefinisikan pola untuk Xet atau LFS, gunakan ekstensi file yang presisi (misalnya, *.safetensors, *.bin) untuk menghindari pengalihan file yang lebih kecil ke penyimpanan file besar secara tidak perlu.
• Prioritaskan akses komunitas: Xet secara signifikan meningkatkan efisiensi dan skala transfer file besar. Alih-alih menyusun repositori Anda untuk mengurangi ukuran totalnya (atau ukuran file individual), susunlah repositori tersebut untuk kolaborator dan pengguna komunitas agar mereka dapat dengan mudah menavigasi dan mengambil konten yang mereka butuhkan.

Mengunggah di balik proxy atau firewall

Mulai dari hf_xet 1.8.0, unggahan dapat mengirim data langsung ke Amazon S3, bukan hanya melalui layanan penyimpanan Xet. Hub memutuskan untuk setiap unggahan apakah akan menggunakan unggahan langsung, dan fitur ini diaktifkan secara bertahap. Unduhan tidak berubah.

Jika jaringan Anda membatasi lalu lintas keluar, izinkan hostname-hostname ini (HTTPS, port 443) di samping yang tercantum dalam Unduhan di balik proxy atau firewall:

Hostname-hostname ini tidak berada di bawah hf.co atau huggingface.co, sehingga mengizinkan sufiks-sufiks tersebut tidak mencakup mereka.

Jika hf_xet tidak dapat mencapai S3, ia akan mengulang pengunggahan langsung dan kemudian mengirim data tersebut melalui layanan penyimpanan Xet. Pengunggahan tetap selesai, tetapi bisa jauh lebih lambat, karena setiap blok harus menunggu proses pengulangan terlebih dahulu. Log hf_xet menampilkan Upload grant URL unreachable, falling back to legacy xorb upload path (may be slower) ketika hal ini terjadi. Jika Anda tidak dapat mengizinkan hostname S3, atur HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOAD=1 untuk menonaktifkan pengunggahan langsung.

Variabel Lingkungan

Kedua hf_xet dan Git Xet didukung oleh xet-core, yang dapat dikonfigurasi melalui variabel lingkungan. Tabel di bawah ini merinci variabel individual untuk kontrol yang lebih detail. Sebagian besar pengguna tidak perlu mengubah salah satu dari ini — nilai bawaan telah disetel untuk secara otomatis memaksimalkan jalur jaringan.

HF_XET_HIGH_PERFORMANCE=1 adalah bendera kenyamanan yang menyesuaikan beberapa pengaturan sekaligus (batas konkurensi, ukuran buffer, dan batas file paralel). Bendera ini ditujukan untuk mesin dengan pita lebar tinggi dan disk cepat. Mulai dari hf_xet 1.7.0, ukuran buffer yang disetel berdasarkan memori yang tersedia untuk hf_xet (lihat Buffer Unduhan), sehingga tidak lagi membutuhkan 64 GB RAM, dan variabel apa pun yang Anda setel sendiri memiliki prioritas lebih tinggi daripada bendera ini. Pada versi sebelumnya, gunakan hanya pada mesin dengan minimal 64 GB RAM.

Umum

Flag tingkat tinggi yang paling sering digunakan oleh pengguna.

Konektivitas Adaptif

Secara default, xet-core menggunakan konkurensi adaptif — menyesuaikan paralelisme secara dinamis berdasarkan kondisi jaringan secara real-time. Pengaturan ini bersifat lanjutan dan kemungkinan besar tidak diperlukan dalam kebanyakan kasus. Variabel di bawah ini mengontrol perilaku pengontrol adaptif:

Untuk mengunci konkurensi ke nilai tetap (melewati pengendali adaptif), gunakan alias kenyamanan HF_XET_FIXED_UPLOAD_CONCURRENCY dan HF_XET_FIXED_DOWNLOAD_CONCURRENCY. Ini mengatur konkurensi awal, minimum, dan maksimum ke nilai yang sama.

Jaringan dan Ulang

Transfer Data

Unduh Buffer

Ini mengontrol penggunaan memori selama unduhan.

Mulai dari hf_xet 1.7.0, nilai default untuk tiga variabel DOWNLOAD_BUFFER didasarkan pada jumlah memori yang dapat digunakan oleh hf_xet. Ini adalah RAM mesin, atau batas memori container jika nilainya lebih rendah. Setiap nilai default adalah fraksi dari memori tersebut, dijaga di antara nilai minimum dan maksimum yang ditunjukkan dalam tabel. Mode HP menggunakan dua kali fraksi, dengan nilai minimum dan maksimum yang sama. Sebagai contoh, container dengan batas 4 GB akan mendapatkan buffer sekitar 256 MB dengan batas 1 GB, dan mesin dengan 32 GB akan mendapatkan buffer sekitar 2 GB dan batas 8 GB yang sama seperti versi sebelumnya.

Versi sebelumnya, atau versi mana pun yang tidak dapat menentukan berapa banyak memori yang tersedia, menggunakan nilai default tetap 2gb, 512mb, dan 8gb (16gb, 2gb, dan 64gb dalam mode HP). Nilai yang digunakan ditulis ke file log hf_xet saat file tersebut dimulai (lihat Logging).

Cache Shard

shard cache menyimpan indeks deduplikasi (yaitu “shards” yang menggambarkan chunk yang sudah diunggah) di disk, di bawah direktori cache Xet. Cache yang lebih besar memungkinkan klien melakukan deduplikasi terhadap lebih banyak data yang pernah dilihat sebelumnya, sehingga lebih sedikit byte yang diunggah ulang.

Cache Chunk

hf_xet tidak lagi menggunakan cache chunk lokal untuk unduhan. File yang diunduh tetap disimpan di cache berbasis file huggingface_hub.

Pencatatan

Telemetri

hf_xet mengirim laporan singkat setelah setiap unggahan dan unduhan. Lihat Telemetri untuk melihat isinya. Untuk mematikannya, atur HF_HUB_DISABLE_TELEMETRY=1.

Batasan Saat Ini

Meskipun Xet membawa deduplikasi bergranularitas halus dan peningkatan kinerja ke penyimpanan berbasis Git, beberapa fitur dan kompatibilitas platform masih dalam pengembangan. Oleh karena itu, perhatikan batasan berikut saat bekerja dengan repositori yang mendukung Xet:

• Hanya sistem 64-bit: Baik hf_xet maupun Git Xet saat ini memerlukan arsitektur 64-bit; sistem 32-bit tidak didukung.