Depo oluşturma ve yönetme

Hugging Face Hub, git depolarının bir koleksiyonudur. Git, iş birliği içinde çalışırken projeleri kolayca sürümlemek için yazılım geliştirmede yaygın olarak kullanılan bir araçtır. Bu kılavuz, Hub’daki depolarla nasıl etkileşime geçeceğinizi, özellikle de şunları gösterecektir:

• Bir depo oluşturun ve silin.
• Dallar ve etiketleri yönetin.
• Deponuzun adını değiştirin.
• Depo görünürlüğünüzü güncelleyin.
• Deponuzun yerel bir kopyasını yönetin.

GitLab/GitHub/Bitbucket gibi platformlarla çalışmaya alışkınsanız, ilk içgüdünüz depoyu klonlamak için (git clone) git CLI'ını, değişiklikleri taahhüt etmek için (git add, git commit) ve bunları göndermek için (git push) kullanmak olabilir. Bu, Hugging Face Hub kullanırken geçerli bir yaklaşımdır. Ancak yazılım mühendisliği ve makine öğrenimi aynı gereksinimleri ve iş akışlarını paylaşmaz. Model depoları, farklı çerçeveler ve araçlar için büyük model ağırlık dosyalarını barındırabilir; bu nedenle depoyu klonlamak, devasa boyutlarda büyük yerel klasörler oluşturmanıza yol açabilir. Sonuç olarak, özel HTTP yöntemlerimizi kullanmak daha verimli olabilir. Daha fazla ayrıntı için Git ile HTTP paradigması açıklama sayfamızı okuyabilirsiniz.

Hub üzerinde bir depo oluşturmak ve yönetmek istiyorsanız, makinenizin oturum açmış olması gerekir. Değilse, lütfen bu bölüme bakın. Bu kılavuzun geri kalanında, makinenizin oturum açmış olduğunu varsayacağız.

Depolarınızı listeleyin

list_user_repos() kullanarak hesabınıza veya bir organizasyona ait tüm depoları (modeller, veri kümeleri, uzaylar ve variller) listeleyebilirsiniz. Sonuçlar depolama bilgilerini içerir ve depolama kullanımına göre sıralanır.

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

Veya CLI üzerinden (varsayılan olarak 30 depo gösterilir, tümünü listelemek için --limit 0 kullanın):

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

Depo oluşturma ve silme

İlk adım, depoların nasıl oluşturulacağını ve silineceğini bilmektir. Yalnızca sahip olduğunuz depoları (kullanıcı adınızın ad alanı altında) veya yazma izinlerinizin olduğu organizasyonlardaki depoları yönetebilirsiniz.

Depo oluşturun

create_repo() ile boş bir depo oluşturun ve repo_id parametresiyle ona bir ad verin. repo_id, ad alanınızın ardından depo adının gelmesiyle oluşur: username_or_org/repo_name.

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

Veya CLI üzerinden:

>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model

Varsayılan olarak create_repo() bir model deposu oluşturur. Ancak başka bir depo türü belirtmek için repo_type parametresini kullanabilirsiniz. Örneğin, bir veri seti deposu oluşturmak istiyorsanız:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

Veya CLI üzerinden:

>>> hf repos create lysandre/test-dataset --repo-type dataset

Bir depo oluşturduğunuzda, depo görünürlüğünüzü visibility parametresiyle ayarlayabilirsiniz:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

Veya CLI üzerinden:

>>> hf repos create lysandre/test-private --private

Daha sonra depo görünürlüğünü değiştirmek isterseniz, update_repo_settings() işlevini kullanabilirsiniz.

Enterprise plan'a sahip bir organizasyonun parçasıysanız, resource_group_id parametresini create_repo() fonksiyonuna geçirerek belirli bir kaynak grubunda bir depo oluşturabilirsiniz. Kaynak grupları, organizasyonunuzdaki hangi üyelerin belirli bir kaynağa erişebileceğini kontrol etmek için kullanılan bir güvenlik özelliğidir. Kaynak grubu kimliğini, Hub'daki organizasyon ayarlarınız sayfasının URL'sinden kopyalayarak alabilirsiniz (ör. "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). Kaynak grubu hakkında daha fazla ayrıntı için bu kılavuza göz atın.

region parametresini geçirerek belirli bir bulut bölgesinde bir depo da oluşturabilirsiniz:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

Bir depoyu sil

Bir depoyu delete_repo() ile silin. Bu işlem geri alınamaz olduğundan, bir depoyu silmek istediğinizden emin olun!

Silmek istediğiniz depoyun repo_id'sini belirtin:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

Depo yoksa çağrıyı sessizce yoksaymak için missing_ok=True parametresini iletin:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

Veya CLI üzerinden:

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

Bir depoyu çoğalt

Bazı durumlarda, başkasının deposunu kendi kullanım durumunuza uyarlamak için kopyalamak isteyebilirsiniz. Bunu duplicate_repo() yöntemi kullanarak yapabilirsiniz. Bu yöntem, tüm git geçmişini koruyarak deposunun tamamını kopyalar. Bu, modeller, veri kümeleri ve Spaces için geçerlidir. Spaces için kendi ayarlarınızı (donanım, uyku süresi, depolama, değişkenler ve gizli bilgiler) yapılandırmak yine de gerekecektir. Daha fazla ayrıntı için Space'inizi Yönetme kılavuzumuza göz atın.

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

create_repo() gibi, duplicate_repo() de Enterprise organizasyonunuzdaki bir kaynak grubunun içine kopyayı doğrudan oluşturmak için resource_group_id kabul eder (hf repos duplicate ile --resource-group-id).

Git geçmişi hemen kopyalanır, ancak duplicate_repo() döndüğünde LFS/Xet dosyaları arka planda kopyalanmaya devam edebilir. Kopyalama işlemi tamamlanana kadar yeni depodan bu dosyaları indirme işlemi başarısız olabilir. Kopyalama işleminin hâlâ devam edip etmediğini anlamak için döndürülen değerdeki files_copy_pending alanını kontrol edin:

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

Spaces için arama yapın

Hub, Spaces keşfi için anlamsal bir arama API'si sunar. search_spaces() ile doğal dil sorguları kullanarak arama yapabilirsiniz:

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

Daha fazla ayrıntı ve filtreleme seçenekleri için Spaces'lerinizi Yönetme kılavuzuna bakın.

Dosyaları yükleme ve indirme

Deponuzu oluşturduğunuza göre, artık değişiklikleri itmek ve dosyaları indirmekle ilgileneceksiniz.

Bu 2 konu kendi kılavuzlarını hak ediyor. Deponuzu nasıl kullanacağınızı öğrenmek için lütfen yükleme ve indirme kılavuzlarına başvurun.

Dosyaları kopyala

Hub üzerinde zaten barındırılan dosyaları bir depodan diğerine (hatta aynı depo içinde) indirmeden ve yeniden yüklemekten kopyalamak için copy_files() kullanın. Hem bireysel dosyalar hem de tüm klasörler desteklenir; Xet veya LFS ile izlenen dosyalar, hash üzerinden sunucu tarafında kopyalanır.

>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

Veya CLI üzerinden, birleşik hf cp komutuyla (hf repos cp olarak da kullanılabilir):

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

copy_files (ve hf cp) dosyaları bir depodan bir Bucket'e de kopyalayabilir. Bir bucket'tan depoya kopyalama desteklenmez. Daha fazla ayrıntı için Buckets kılavuzuna bakın.

Sunucu tarafı kopyalar yalnızca aynı depolama bölgesi içinde çalışır.

Branchler ve etiketler

Git depoları, aynı depoyun farklı sürümlerini saklamak için genellikle dallardan (branch) yararlanır. Etiketler (tag), örneğin bir sürüm yayınlarken, depoyunuzun belirli bir durumunu işaretlemek için de kullanılabilir. Daha genel olarak, dallar ve etiketler git referansları olarak adlandırılır.

Dallar ve etiketler oluşturun

create_branch() ve create_tag() kullanarak yeni dallar ve etiketler oluşturabilirsiniz:

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

Veya CLI üzerinden:

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

Bir dalı veya etiketi silmek için delete_branch() ve delete_tag() işlevlerini aynı şekilde kullanabilir veya CLI'da sırasıyla hf repos branch delete ve hf repos tag delete komutlarını çalıştırabilirsiniz.

Tüm dalları ve etiketleri listele

Bir depodaki mevcut git referanslarını list_repo_refs() kullanarak da listeleyebilirsiniz:

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

Depo ayarlarını değiştir

Depolar, yapılandırabileceğiniz bazı ayarlarla birlikte gelir. Çoğu durumda, bunu tarayıcınızdaki depo ayarları sayfasında manuel olarak yapmak istersiniz. Bir depoyu yapılandırmak için yazma erişimine sahip olmanız gerekir (deponun sahibi olmak veya bir organizasyonun parçası olmak). Bu bölümde, huggingface_hub kullanarak programatik olarak da yapılandırabileceğiniz ayarları inceleyeceğiz.

Bazı ayarlar Spaces'e özgüdür (donanım, ortam değişkenleri, ...). Bunları yapılandırmak için lütfen Spaces'inizi Yönetme kılavuzumuza başvurun.

Görünürlüğü güncelle

Bir depo herkese açık veya özel olabilir. Özel bir depo, yalnızca size veya deponun bulunduğu organizasyonun üyelerine görünür. Bir depoyu aşağıda gösterildiği gibi özel olarak değiştirin:

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

Veya CLI üzerinden:

>>> hf repos settings lysandre/test-private --private true

Kontrollü erişimi yapılandırma

Depoların kullanımına daha fazla kontrol sağlamak için Hub, depo yazarlarına depoları için erişim isteklerini etkinleştirmelerine olanak tanır. Bu özellik etkinleştirildiğinde, kullanıcının dosyalara erişmek için iletişim bilgilerini (kullanıcı adı ve e-posta adresi) depo yazarlarıyla paylaşmayı kabul etmesi gerekir. Erişim istekleri etkinleştirilmiş bir depoya kısıtlı depo denir.

Bir depoyu update_repo_settings() kullanarak gated olarak ayarlayabilirsiniz:

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

Veya CLI üzerinden:

>>> hf repos settings lysandre/test-private --gated auto

Deponuzun adını değiştirin

Hub'da move_repo() kullanarak depoyu yeniden adlandırabilirsiniz. Bu yöntemi kullanarak depoyu bir kullanıcıdan bir organizasyona da taşıyabilirsiniz. Bunu yaparken, dikkat etmeniz gereken birkaç kısıtlama vardır. Örneğin, depoyu başka bir kullanıcıya aktaramazsınız.

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

Veya CLI üzerinden:

>>> hf repos move Wauplin/cool-model huggingface/cool-model

Çekirdek depoları

Hub, hesaplama çekirdeklerini barındırmak için "kernel" depo türünü destekler. Bu, tamamen uyumlu bir depo türü değildir. Sadece sınırlı bir yöntem seti test edilmiş ve resmi olarak desteklenmektedir:

• kernel_info()
• hf_hub_download()
• snapshot_download()
• list_repo_refs()
• list_repo_files()
• list_repo_tree()

create_repo() ve delete_repo() işlevlerinin de uyumlu olduğunu, ancak Hub'da izin verilen küçük bir kullanıcı ve kuruluş alt kümesine kısıtlandığını unutmayın.

Çekirdek depolarını oluşturmak, yayınlamak ve kullanmak için lütfen bunun yerine özel kernels paketini kullanın. Daha fazla ayrıntı için Kernels belgelerine başvurun.