Hızlı Başlangıç

Hugging Face Hub, makine öğrenimi modelleri, demolar, veri setleri ve metriklerin paylaşımı için tercih edilen yerdir. huggingface_hub kütüphanesi, geliştirme ortamınızdan ayrılmadan Hub ile etkileşim kurmanıza yardımcı olur. Depoları kolayca oluşturabilir ve yönetebilir, dosyaları indirebilir ve yükleyebilir, Hub'dan model ve veri setiyle ilgili faydalı meta verileri alabilirsiniz.

Kurulum

Başlamak için huggingface_hub kütüphanesini yükleyin:

pip install --upgrade huggingface_hub

Daha fazla ayrıntı için kurulum kılavuzuna göz atın.

huggingface_hub, Hub ile doğrudan terminalden etkileşim kurmanızı sağlayan bir hf CLI ile birlikte gelir. Yapay zeka ajanları (Claude Code, Codex, Cursor, …) kullanıyorsanız, ajanınızın CLI'yi kullanabilmesi için Skill'i yükleyin:

Kopyalandı

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

Daha fazla ayrıntı için Hugging Face CLI for AI Agents kılavuzuna göz atın.

Dosyaları indir

Hub'daki depolar git sürüm kontrolüne tabidir ve kullanıcılar tek bir dosyayı veya tüm depoyu indirebilir. Dosyaları indirmek için hf_hub_download() işlevini kullanabilirsiniz. Bu işlev, bir dosyayı indirir ve yerel diskinizde önbelleğe alır. Bir sonraki sefer o dosyaya ihtiyacınız olduğunda, önbelleğinizden yükleneceğinden yeniden indirmenize gerek kalmaz.

İndirmek istediğiniz dosyanın deposu kimliğini ve dosya adını bilmeniz gerekir. Örneğin, Pegasus model yapılandırma dosyasını indirmek için:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

Belirli bir dosya sürümünü indirmek için dal adını, etiketini veya commit hash'ini belirtmek üzere revision parametresini kullanın. Commit hash'ini kullanmayı seçerseniz, kısa 7 karakterli commit hash'i yerine tam uzunluktaki hash'i kullanmanız gerekir:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

Daha fazla ayrıntı ve seçenek için hf_hub_download() API referansına bakın.

Kimlik Doğrulama

Birçok durumda, Hub ile etkileşime girmek için (özel depoları indirmek, dosya yüklemek, PR oluşturmak vb.) bir Hugging Face hesabıyla kimlik doğrulamanız gerekir. Henüz hesabınız yoksa hesap oluşturun.

Giriş komutu

Kimlik doğrulamanın en kolay yolu login() komutunu kullanmaktır:

hf auth login

Zaten oturum açtıysanız, komut hemen döner. Yeniden oturum açmayı zorlamak için hf auth login --force kullanın. Oturum açmadıysanız, tarayıcınızla oturum açmanız istenir: yazdırılan URL'yi açın, kısa kodu girin, isteği onaylayın ve bir erişim jetonu alınır ve HF_HOME dizininizde (varsayılan olarak ~/.cache/huggingface/token) saklanır. Jeton bir süre sonra sona erer ancak kullanmaya devam ettikçe otomatik olarak yenilenir. Hub ile etkileşime giren herhangi bir betik veya kitaplık, istek gönderirken bu jetonu kullanır. Alternatif olarak, Ayarlar sayfanızdan oluşturduğunuz bir Kullanıcı Erişim Jetonunu yapıştırabilirsiniz.

User Access Tokens read veya write izinlerine sahip olabilir. Bir depo oluşturmak veya düzenlemek istiyorsanız write erişim token'ına sahip olduğunuzdan emin olun. Aksi takdirde, token'ınızın istenmeden sızdırılması durumunda riski azaltmak için bir read token'ı oluşturmanız en iyisidir.

Alternatif olarak, bir defterde veya betikte login() kullanarak programatik olarak oturum açabilirsiniz:

>>> from huggingface_hub import login
>>> login()

Aynı anda yalnızca bir hesaba giriş yapabilirsiniz. Yeni bir hesaba giriş yaptığınızda, önceki hesaptan otomatik olarak çıkış yapılır. Şu anda etkin olan hesabınızı belirlemek için hf auth whoami komutunu çalıştırmanız yeterlidir.

Giriş yapıldıktan sonra, Hub'a yapılan tüm istekler - kimlik doğrulaması gerektirmeyen yöntemler dahil - varsayılan olarak erişim token'ınızı kullanır. Token'ınızın örtük kullanımını devre dışı bırakmak istiyorsanız, HF_HUB_DISABLE_IMPLICIT_TOKEN=1 değerini bir ortam değişkeni olarak ayarlamalısınız (bkz. referans).

Yerel olarak birden fazla jetonu yönetin

Makinenizde birden fazla token saklamak için her token ile login() komutuyla oturum açmanız yeterlidir. Bu tokenlar arasında yerel olarak geçiş yapmanız gerekiyorsa auth switch komutunu kullanabilirsiniz:

hf auth switch

Bu komut, kayıtlı token listesinden bir token adını seçmeniz için sizden istekte bulunur. Seçim yapıldığında, seçilen token aktif token olur ve Hub ile tüm etkileşimler için kullanılır.

Makinenizdeki tüm kullanılabilir erişim jetonlarını hf auth list ile listeleyebilirsiniz.

Ortam değişkeni

Ortam değişkeni HF_TOKEN da kimlik doğrulama için kullanılabilir. Bu, HF_TOKEN değerini bir Space gizli değeri olarak ayarlayabileceğiniz bir Space ortamında özellikle faydalıdır.

YENİ: Google Colaboratory, defterleriniz için özel anahtarlar tanımlamanıza olanak tanır. Otomatik olarak kimlik doğrulama yapılması için HF_TOKEN gizli anahtarı tanımlayın!

Bir ortam değişkeni veya gizli değer üzerinden kimlik doğrulama, makinenizde saklanan belirteçten önceliklidir.

Yöntem parametreleri

Son olarak, token parametresini kabul eden herhangi bir yönteme belirtecinizi geçirerek de kimlik doğrulaması yapmak mümkündür.

from huggingface_hub import whoami

user = whoami(token=...)

Bu, token'ınızı kalıcı olarak saklamak istemediğiniz veya birden fazla token'ı aynı anda işlemek zorunda kaldığınız ortamlar dışında genellikle önerilmez.

Parametre olarak token geçerken dikkatli olun. Token'ı kod tabanınıza veya defterinize sabit kod olarak yazmak yerine güvenli bir kasadan yüklemek her zaman en iyi uygulamadır. Kodunuzu istemeden paylaşırsanız, sabit kodlanmış token'lar ciddi bir sızıntı riski oluşturur.

Depo oluşturun

Kayıt olup giriş yaptıktan sonra, create_repo() işleviyle bir depo oluşturun:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

Deponuzun özel olmasını istiyorsanız:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

Özel depolar yalnızca size görünür olacaktır.

Bir depo oluşturmak veya Hub'a içerik göndermek için write iznine sahip bir Kullanıcı Erişim Belirteci (User Access Token) sağlamanız gerekir. Belirteci oluştururken Ayarlar sayfanızda izni seçebilirsiniz.

Dosyaları yükle

Yeni oluşturduğunuz depoya bir dosya eklemek için upload_file() işlevini kullanın. Şunları belirtmeniz gerekir:

1. Yüklemek istediğiniz dosyanın yolu.
2. Depodaki dosyanın yolu.
3. Dosyanın eklenmesini istediğiniz depoyu kimliği.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

Birden fazla dosyayı aynı anda yüklemek için, dosyaları (git ile veya git olmadan) yüklemenin çeşitli yöntemlerini tanıtan Upload kılavuzuna göz atın.

Sonraki adımlar

huggingface_hub kütüphanesi, kullanıcıların Python ile Hub ile etkileşime geçmesi için kolay bir yol sunar. Hub üzerindeki dosyalarınızı ve depolarınızı nasıl yönetebileceğinizi öğrenmek için, aşağıdaki konularda nasıl yapılır kılavuzlarımızı okumanızı öneririz:

• Deponuzu yönetin.
• İndir Hub'dan dosyaları.
• Yükle dosyaları Hub'a.
• İstediğiniz model veya veri setini bulmak için Hub'da arama yapın.
• Hugging Face Hub üzerinde barındırılan modeller için birden çok hizmette Çıkarım Çalıştırın.