huggingface_hub v1.0 sürümüne geçiş

v1.0 sürümü, huggingface_hub kütüphanesi için önemli bir kilometre taşıdır. API kararlılığına ve kütüphanenin olgunluğuna olan bağlılığımızı simgeler. Kütüphaneyi daha sağlam ve kullanımı daha kolay hale getirmek için çeşitli iyileştirmeler ve kırıcı değişiklikler yaptık.

Bu kılavuz, mevcut kodunuzu yeni sürüme taşımak için size yardımcı olmak üzere hazırlanmıştır. Herhangi bir sorunuz veya geri bildiriminiz varsa, lütfen GitHub'da bir sorun açarak bize bildirin.

Python 3.9+

huggingface_hub artık Python 3.9 veya daha yüksek bir sürüm gerektirir. Python 3.8 artık desteklenmemektedir.

HTTPX geçişi

huggingface_hub kütüphanesi artık HTTP istekleri için requests yerine httpx kullanıyor. Bu değişiklik, performansı iyileştirmek ve senkron ile asenkron istekleri aynı şekilde desteklemek amacıyla yapıldı. Bu nedenle hem requests hem de aiohttp bağımlılıkları kaldırıldı.

Kırıcı değişiklikler

Bu, kütüphanenin tamamını etkileyen önemli bir değişikliktir. Bu değişikliği mümkün olduğunca şeffaf hale getirmeye çalışsak da, bazı durumlarda kodunuzu güncellemeniz gerekebilir. Süreç boyunca getirilen kırıcı değişikliklerin listesi aşağıdadır:

• Proxy yapılandırması: “yönteme göre” proxy'ler artık desteklenmiyor. Proxy'ler, HTTP_PROXY ve HTTPS_PROXY ortam değişkenleri kullanılarak küresel olarak yapılandırılmalıdır.
• Özel HTTP arka ucu: configure_http_backend fonksiyonu kaldırıldı. Artık HTTP istemcilerini yapılandırmak için set_client_factory() ve set_async_client_factory() kullanmalısınız.
• Hata yönetimi: HTTP hataları artık requests.HTTPError sınıfından değil, httpx.HTTPError sınıfından türetilmektedir. from huggingface_hub.utils import HfHubHTTPError ile içe aktarılan HfHubHTTPError sınıfını yakalamayı öneririz; bu sınıf v0.x sürümünde requests.HTTPError sınıfının, v1.x sürümünde ise httpx.HTTPError sınıfının bir alt sınıfıdır. huggingface_hub hatasını yakalamak, kodunuzun kütüphanenin hem eski hem de yeni sürümleriyle uyumlu olmasını sağlar.
• SSLError: httpx'in SSLError kavramı yoktur. Artık genel bir httpx.ConnectError'dır.
• LocalEntryNotFoundError: Bu hata artık HTTPError'dan devralmıyor. Artık EntryNotFoundError (yeni) tanımlıyoruz ve hem LocalEntryNotFoundError (dosya yerel önbellekte bulunamazsa) hem de RemoteEntryNotFoundError (dosya Hub'daki depoda bulunamazsa) bu sınıftan devralıyor. Sadece uzak hata HTTPError'dan devralıyor.
• InferenceClient: InferenceClient artık bir bağlam yöneticisi olarak kullanılabilir. Bu, bir dil modelinden token akışı sırasında bağlantının düzgün şekilde kapatılmasını sağlamak için özellikle faydalıdır.
• AsyncInferenceClient: AsyncInferenceClient yapıcısından trust_env parametresi kaldırıldı. Ortam değişkenleri varsayılan olarak httpx tarafından güvenilirdir. Ortama açıkça güvenmek istemiyorsanız, bunu set_async_client_factory() ile yapılandırmanız gerekir.

Daha fazla ayrıntı için, httpx'i tanıtan PR #3328'i kontrol edebilirsiniz.

Neden httpx?

requests'ten httpx'e geçiş, kütüphanenin performansını, güvenilirliğini ve sürdürülebilirliğini artıran birkaç önemli iyileştirme getirir:

İş Parçacığı Güvenliği ve Bağlantı Yeniden Kullanımı: httpx tasarım gereği iş parçacığı güvenlidir (thread-safe), bu da aynı istemcinin birden fazla iş parçacığı arasında güvenle yeniden kullanılmasına olanak tanır. Bu bağlantı yeniden kullanımı, her HTTP isteği için yeni bağlantılar kurma maliyetini azaltarak özellikle Hub'a sık istekler yapıldığında performansı artırır.

HTTP/2 Desteği: httpx, aynı sunucuya birden fazla istek gönderirken (tam olarak bizim kullanım senaryomuz) daha iyi verimlilik sağlayan yerel HTTP/2 desteği sunar. Bu, HTTP/1.1'e kıyasla daha düşük gecikme süresi ve azaltılmış kaynak tüketimi anlamına gelir.

Birleşik Senkron/Asenkron API: requests (senkron) ve aiohttp (asenkron) bağımlılıklarının ayrı ayrı kullanıldığı önceki kurulumumuzun aksine, httpx hem senkron hem de asenkron istemcileri aynı davranışla sunar. Bu, InferenceClient ve AsyncInferenceClient sınıflarının tutarlı işlevselliğe sahip olmasını sağlar ve bu iki uygulama arasında daha önce var olan ince davranış farklılıklarını ortadan kaldırır.

Yenilenmiş SSL Hata Yönetimi: httpx, SSL hatalarını daha zarif bir şekilde ele alarak bağlantı sorunlarını ayıklamayı daha kolay ve güvenilir hale getirir.

Geleceğe Yönelik Mimari: httpx aktif olarak bakımı yapılan ve modern Python uygulamaları için tasarlanmış bir kütüphanedir. Buna karşılık requests bakım modundadır ve thread-safety iyileştirmeleri veya HTTP/2 desteği gibi önemli güncellemeler almayacaktır.

Daha İyi Ortam Değişkeni İşleme: httpx, hem senkron hem de asenkron bağlamlarda ortam değişkenlerinin daha tutarlı işlenmesini sağlayarak, requests'in varsayılan olarak yerel ortam değişkenlerini okurken aiohttp'in bunu yapmadığı önceki tutarsızlıkları ortadan kaldırır.

httpx'e geçiş, huggingface_hub'ü modern, verimli ve sürdürülebilir bir HTTP altyapısıyla konumlandırır. Çoğu kullanıcı sorunsuz bir deneyim yaşasa da, temel iyileştirmeler tüm Hub etkileşimleri için daha iyi performans ve güvenilirlik sağlar.

hf_transfer

Hub’daki tüm depolar artık Xet destekli olduğundan ve hf_xet dosya indirme/yükleme için varsayılan yöntem haline geldiğinden, hf_transfer isteğe bağlı paketine olan desteği kaldırdık. Bu nedenle HF_HUB_ENABLE_HF_TRANSFER ortam değişkeni yok sayılır. Bunun yerine HF_XET_HIGH_PERFORMANCE kullanın.

Depo sınıfı

Repository sınıfı v1.0 sürümünde kaldırıldı. Bu sınıf, depoları yönetmek için git komut satırı arayüzünün ince bir sarmalayıcısıydı. git aracını terminalde doğrudan kullanmaya devam edebilirsiniz ancak özellikle büyük dosyalarla çalışırken daha akıcı bir deneyim için önerilen yaklaşım, huggingface_hub kütüphanesindeki HTTP tabanlı API'yi kullanmaktır.

İşte eski Repository sınıfından yeni HfApi sınıfına geçiş haritası:

Repository yöntemi	HfApi metodu
repo.clone_from	snapshot_download
repo.git_add + git_commit + git_push	upload_file(), upload_folder(), create_commit()
repo.git_tag	create_tag
repo.git_branch	create_branch

HfFolder sınıfı

HfFolder, kullanıcı erişim jetonunu yönetmek için kullanılıyordu. Yeni bir jeton kaydetmek için login(), silmek için logout() ve mevcut jetonla ilişkili kullanıcıyı kontrol etmek için whoami() kullanın. Son olarak, bir betikte kullanıcının jetonunu almak için get_token() kullanın.

InferenceApi sınıfı

InferenceApi, Inference API ile etkileşime girmek için kullanılan bir sınıftı. Bunun yerine artık InferenceClient sınıfını kullanmanız önerilir.

Diğer kullanımdan kaldırılan özellikler

Bazı yöntemler ve parametreler v1.0 sürümünde kaldırılmıştır. Aşağıda listelenenler, v0.x sürümünde zaten bir uyarı mesajıyla kullanımdan kaldırılmıştı.

• constants.hf_cache_home kaldırıldı. Bunun yerine HF_HOME kullanın.
• use_auth_token parametreleri tüm yöntemlerden kaldırıldı. Bunun yerine token kullanın.
• get_token_permission yöntemi kaldırıldı.
• update_repo_visibility yöntemi kaldırıldı. Bunun yerine update_repo_settings kullanın.
• is_write_action parametresi, build_hf_headers içinden ve write_permission de login içinden kaldırılmıştır. “Yazma izni” kavramı kaldırılmış olup, ince tanecikli tokenler önerilen yaklaşım haline geldiği için artık geçerli değildir.
• login içindeki new_session parametresi, daha iyi açıklık için skip_if_logged_in olarak yeniden adlandırıldı.
• resume_download, force_filename ve local_dir_use_symlinks parametreleri hf_hub_download ve snapshot_download işlevlerinden kaldırıldı.
• library, language, tags ve task parametreleri list_models içinden kaldırıldı.

CLI önbellek komutları

CLI üzerinden önbellek yönetimi, Docker ilhamlı bir iş akışını takip edecek şekilde yeniden tasarlandı. Kullanımı durdurulan huggingface-cli kaldırıldı; bunun yerine hf (v0.34'te tanıtıldı), daha net bir kaynak-aksiyon CLI'ı olarak kullanılıyor. Eski hf cache scan ve hf cache delete komutları da v1.0'da kaldırıldı ve aşağıdaki yeni üçlü ile değiştirildi:

• hf cache ls, önbellek girdilerini kısa bir tablo, JSON veya CSV çıktısıyla listeler. Bireysel revizyonları incelemek için --revisions kullanın, size>1GB veya accessed>30d gibi --filter ifadeleri ekleyin ve yalnızca tanımlayıcılara ihtiyacınız olduğunda bunları --quiet ile birleştirin.
• hf cache rm, seçilen önbellek girdilerini siler. Bir veya daha fazla depo kimliği (örneğin model/bert-base-uncased) veya revizyon özetlerini iletin ve isteğe bağlı olarak önizleme için --dry-run veya onay istemini atlamak için --yes ekleyin. Bu, önceki komuttaki etkileşimli TUI ve --disable-tui iş akışlarının ikisini de değiştirir.
• hf cache prune, referanssız revizyonları tek seferde silme işlemini gerçekleştirir. hf cache rm komutunda olduğu gibi --dry-run veya --yes seçeneklerini ekleyebilirsiniz.

Son olarak, [cli] ek paketi kaldırıldı - CLI artık çekirdek huggingface_hub paketiyle birlikte dağıtılıyor.

TensorFlow ve Keras 2.x desteği

v1.0 sürümünde tüm TensorFlow ile ilgili kod ve bağımlılıklar kaldırılmıştır. Bu, aşağıdaki kırıcı değişiklikleri içerir:

• huggingface_hub[tensorflow] artık desteklenen bir ek bağımlılık değildir
• split_tf_state_dict_into_shards ve get_tf_storage_size yardımcı işlevleri kaldırıldı.
• tensorflow, fastai ve fastcore sürümleri artık yerleşik başlıklarda yer almamaktadır.

Keras 2.x entegrasyonu de kaldırıldı. Bu, KerasModelHubMixin sınıfını ve save_pretrained_keras, from_pretrained_keras ile push_to_hub_keras yardımcı programlarını içerir. Keras 2.x, eski ve bakımı yapılmayan bir kütüphanedir. Önerilen yaklaşım, Hub ile sıkı bir şekilde entegre olan Keras 3.x’ü kullanmaktır (yani Hub’a yükleme/itme için yerleşik yöntemler içerir). Yine de Keras 2.x ile çalışmak istiyorsanız, huggingface_hub paketini v0.x sürümüne geri almanız gerekir.

upload_file ve upload_folder dönüş değerleri

upload_file() ve upload_folder() işlevleri artık Hub'da oluşturulan commit'in URL'sini döndürür. Önceki sürümlerde dosya veya klasörün URL'sini döndürüyorlardı. Bu değişiklik, create_commit(), delete_file() ve delete_folder() işlevlerinin dönüş değerleriyle uyumlu hale gelmek için yapılmıştır.

Update on GitHub