Kütüphanenizi Hub ile entegre edin

Hugging Face Hub, makine öğrenimi modelleri, kontrol noktaları ve artefaktların paylaşılmasını kolaylaştırmayı amaçlar. Bu girişim, Hub'ın topluluktaki birçok harika üçüncü taraf kütüphaneye entegre edilmesini içerir. Zaten entegre edilenlerden bazıları arasında spaCy, Sentence Transformers, OpenCLIP ve timm gibi birçok kütüphane yer alır. Entegrasyon, kullanıcıların dosyaları doğrudan kütüphanenizden Hub'a indirmesini ve yüklemesini sağlar. Kütüphanenizi entegre etmenizi ve yapay zekayı herkes için demokratikleştirme çabamıza katılmanızı umuyoruz.

Kütüphanenizi Hub ile entegre etmek birçok avantaj sağlar, bunlar arasında:

• Siz ve kullanıcılarınız için ücretsiz model barındırma.
• Devasa dosyalar dahil olmak üzere yerleşik dosya sürümleme - Git-Xet sayesinde mümkün.
• Topluluk özellikleri (tartışmalar, çekme istekleri, beğeniler).
• Kütüphanenizle çalıştırılan tüm modellerin kullanım metrikleri.

Bu eğitim, kütüphanenize Hub'ı entegre etmenize ve kullanıcılarınızın Hub'ın sunduğu tüm özelliklerden faydalanmasına yardımcı olacaktır.

Başlamadan önce, depolarınızı ve dosyalarınızı yönetebileceğiniz bir Hugging Face hesabı oluşturmanızı öneririz.

Entegrasyon konusunda yardıma ihtiyacınız varsa, bir issue açmaktan çekinmeyin; size yardımcı olmaktan memnuniyet duyarız.

Uygulama

Bir kütüphanenin Hub ile entegrasyonunu uygulamak, genellikle Hub'dan modelleri yüklemek ve kullanıcıların Hub'a yeni modeller göndermesine izin vermek için yerleşik yöntemler sağlamayı gerektirir. Bu bölüm, huggingface_hub kütüphanesini kullanarak bunu nasıl yapacağınızın temellerini ele alacaktır. Daha ayrıntılı yönlendirme için bu kılavuza göz atın.

Kurulum

Kütüphanenizi Hub ile entegre etmek için huggingface_hub kütüphanesini bir bağımlılık olarak eklemeniz gerekir:

pip install huggingface_hub

huggingface_hub kurulumuyla ilgili daha fazla ayrıntı için bu kılavuza göz atın.

Bu kılavuzda Python kütüphanelerine odaklanacağız. Kütüphanenizi JavaScript ile uyguladıysanız bunun yerine @huggingface/hub kullanabilirsiniz. Mantığın geri kalanı (yani dosya barındırma, kod örnekleri vb.) kod dilinden bağımsızdır.

Kopyalandı

npm add @huggingface/hub

Kullanıcılar, huggingface_hub kütüphanesini başarıyla yükledikten sonra kimlik doğrulaması yapmalıdır. Kimlik doğrulaması için en kolay yol, belirteci makinede kaydetmektir. Kullanıcılar bunu, login() komutunu kullanarak terminalden yapabilir:

hf auth login

Komut, kullanıcının zaten oturum açmış olup olmadığını bildirir ve token'ını ister. Token daha sonra doğrulanır ve HF_HOME dizinine (varsayılan olarak ~/.cache/huggingface/token) kaydedilir. Hub ile etkileşime giren herhangi bir betik veya kütüphane, istek gönderirken bu token'ı kullanır.

Alternatif olarak, kullanıcılar bir defterde veya betikte login() kullanarak programatik olarak oturum açabilir:

from huggingface_hub import login
login()

Hub'daki herkese açık depolardan dosya indirirken kimlik doğrulama isteğe bağlıdır.

Hub'dan dosya indir

Entegrasyonlar, kullanıcıların Hub'dan bir model indirmenize ve onu doğrudan kütüphanenizden örneklemesine olanak tanır. Bu, genellikle kütüphanenize özgü olması gereken bir yöntem (genellikle from_pretrained veya load_from_hf olarak adlandırılır) sağlayarak mümkün hale getirilir. Hub'dan bir model örneklemek için kütüphanenizin şunları yapması gerekir:

• Hub'dan dosyaları indirin. Şimdi bunu ele alacağız.
• bu dosyalardan Python modelini örnekleyin.

Hub'daki bir depodan dosya indirmek için hf_hub_download yöntemini kullanın. İndirilen dosyalar önbellekte saklanır: ~/.cache/huggingface/hub. Kullanıcılar dosyayı bir sonraki kullanımlarında yeniden indirmek zorunda kalmaz, bu da büyük dosyalar için çok zaman tasarrufu sağlar. Ayrıca, depo dosyanın yeni bir sürümüyle güncellenirse, huggingface_hub en son sürümü otomatik olarak indirir ve önbellekte saklar. Kullanıcıların dosyalarını manuel olarak güncellemekle uğraşmasına gerek yoktur.

Örneğin, lysandre/arxiv-nlp deposundan config.json dosyasını indirin:

>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

config_path artık indirilen dosyanın yolunu içerir. Dosyanın mevcut ve güncel olduğu garanti edilir.

Kütüphaneniz tüm bir deposu indirmesi gerekiyorsa snapshot_download kullanın. Bu, dosyaların tümünü paralel olarak indirmeyi halleder. Dönüş değeri, indirilen dosyaları içeren dizinin yoludur.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

Belirli bir revizyondan dosya indirmek, indirilecek dosyaları filtrelemek, özel bir önbellek dizini sağlamak, yerel bir dizine indirmek vb. için birçok seçenek mevcuttur. Daha fazla ayrıntı için indirme kılavuzuna göz atın.

Dosyaları Hub'a yükle

Kullanıcıların kendi modellerini Hub'a yükleyebilmesi için bir yöntem de sunmak isteyebilirsiniz. Bu, topluluğun kütüphanenizle uyumlu modellerden oluşan bir ekosistem oluşturmasına olanak tanır. huggingface_hub kütüphanesi, depolar oluşturma ve dosya yükleme yöntemleri sunar:

• create_repo, Hub üzerinde bir depo oluşturur.
• upload_file ve upload_folder, dosyaları Hub'daki bir depoya yükler.

create_repo yöntemi Hub üzerinde bir depo oluşturur. Deponuz için bir ad sağlamak üzere repo_id parametresini kullanın:

>>> from huggingface_hub import create_repo
>>> create_repo(repo_id="test-model")
'https://huggingface.co/lysandre/test-model'

Hugging Face hesabınızı kontrol ettiğinizde, ad alanınızın altında artık bir test-model deposu görmelisiniz.

upload_file metodu bir dosyayı Hub'a yükler. Bu metodun gerektirdikleri şunlardır:

• Yüklemek için dosyanın yolu.
• Depodaki son yol.
• Dosyaları göndermek istediğiniz depo.

Örneğin:

>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'

Hugging Face hesabınızı kontrol ederseniz, dosyanın depolamanızın içinde olduğunu görmelisiniz.

Genellikle bir kütüphane, modeli yerel bir dizine serileştirir ve ardından tüm klasörü tek seferde Hub'a yükler. Bu işlem upload_folder kullanılarak yapılabilir:

>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )

Dosya yükleme konusunda daha fazla ayrıntı için yükleme kılavuzuna göz atın.

Model kartları

Model kartları, modellerle birlikte gelen ve kullanışlı bilgiler sunan dosyalardır. Arka planda model kartları, ek meta verilere sahip basit Markdown dosyalarıdır. Model kartları keşfedilebilirlik, yeniden üretilebilirlik ve paylaşım için hayati öneme sahiptir! Herhangi bir model deposunda model kartını README.md dosyası olarak bulabilirsiniz. İyi bir model kartı oluşturma konusunda daha fazla ayrıntı için model kartları kılavuzuna göz atın.

Kütüphaneniz bir modeli Hub'a göndermeye izin veriyorsa, önceden doldurulmuş metadata (genellikle library_name, pipeline_tag veya tags) ve modelin nasıl eğitildiğine dair bilgi içeren minimal bir model kartı oluşturmanız önerilir. Bu, kütüphanenizle oluşturulan tüm modeller için standartlaştırılmış bir açıklama sunmanıza yardımcı olacaktır.

Kütüphanenizi kaydedin

Harika! Artık Hub'dan bir model yükleyebilen ve yeni modelleri itebilen bir kütüphaneniz olmalı. Bir sonraki adım, Hub'daki modellerinizin iyi belgelenmiş ve platformla entegre olduğundan emin olmaktır. Bunu yapmak için kütüphaneler Hub'da kaydedilebilir; bu da kullanıcılara birkaç avantaj sağlar:

• model sayfasında daha şık bir etiket gösterilebilir (ör. keras-nlp yerine KerasNLP)
• her model sayfasına kütüphane deposunuza ve dokümantasyonunuza giden bir bağlantı eklenir
• özel bir indirme sayısı kuralı tanımlanabilir
• kod parçacıkları, modelin kütüphanenizle nasıl yükleneceğini göstermek için oluşturulabilir

Yeni bir kütüphane kaydetmek için lütfen aşağıdaki talimatları izleyerek buradan bir Pull Request açın:

• Kütüphane kimliği küçük harf ve tire ile ayrılmış olmalıdır (örnek: "adapter-transformers"). PR'ı açarken alfabetik sıralamayı koruduğunuzdan emin olun.
• repoName ve prettyLabel değerlerini kullanıcı dostu büyük/küçük harf kullanımına göre ayarlayın (örnek: DeepForest).
• Kütüphane kaynak koduna (genellikle bir GitHub deposu) giden bağlantıyla repoUrl değerini ayarlayın.
• (isteğe bağlı) kütüphanenin belgelerine giden bağlantıyla docsUrl değerini ayarlayın. Belgeleme yukarıda atıf yapılan GitHub deposundaysa, bunu iki kez ayarlamanıza gerek yoktur.
• filter parametresini false olarak ayarlayın.
• (isteğe bağlı) countDownload ayarlayarak indirmelerin nasıl sayılacağını tanımlayın. İndirmeler dosya uzantılarına veya dosya adlarına göre izlenebilir. Sayımın tekrarlanmamasına dikkat edin. Örneğin, bir modelin yüklenmesi 3 dosya gerektiriyorsa, indirme sayım kuralı indirmeleri yalnızca bu 3 dosyadan 1'inde saymalıdır. Aksi takdirde indirme sayısı abartılı olacaktır. Not: kütüphane varsayılan yapılandırma dosyalarından birini kullanıyorsa (config.json, config.yaml, hyperparams.yaml, params.json ve meta.yaml, bkz. burası), indirme sayım kuralını manuel olarak tanımlamanıza gerek yoktur.
• (isteğe bağlı) Kullanıcının bir modeli nasıl hızlıca örnekleyebileceğini bilmesi için snippets tanımlayın. Aşağıda daha fazla ayrıntı yer almaktadır.

PR'yi açmadan önce, https://huggingface.co/models?other=my-library-name adresinde en az bir modelin referans alındığından emin olun. Değilse, ilgili modellerin model kartı meta verileri library_name: my-library-name ile güncellenmelidir (bkz. örnek). Hub'daki modellerin sahibi değilseniz, lütfen PR açın (bkz. örnek).

VFIMamba için entegrasyon ekleyen minimal bir örnek aşağıdadır.

Kod parçacıkları

Aşağı akış kütüphanenizde bir modelin nasıl kullanılacağını açıklamak için bir kod parçası eklemenizi öneririz.

Kod parçası eklemek için model-libraries-snippets.ts dosyasını modelinizle ilgili talimatlarla güncellemeniz gerekir. Örneğin, Asteroid entegrasyonu, bir Asteroid modelinin nasıl yükleneceğini ve kullanılacağını gösteren kısa bir kod parçası içerir:

const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;

Bunu yapmak, modelinize bir etiket ekleyerek kullanıcıların kütüphanenizdeki modelleri hızla tanımlamasını da sağlar.

Parçanız model-libraries-snippets.ts dosyasına eklendikten sonra, yukarıda açıklandığı gibi model-libraries.ts dosyasında buna başvurabilirsiniz.

Kütüphanenizi belgeleyin

Son olarak, kütüphanenizi Hub dokümantasyonuna ekleyebilirsiniz. Örneğin, SetFit'i dokümantasyona ekleyen Setfit PR'sına göz atabilirsiniz.