Buat dan kelola repositori

Hugging Face Hub adalah kumpulan repositori git. Git adalah alat yang banyak digunakan dalam pengembangan perangkat lunak untuk dengan mudah mengelola versi proyek saat bekerja secara kolaboratif. Panduan ini akan menunjukkan cara berinteraksi dengan repositori di Hub, khususnya:

• Buat dan hapus repositori.
• Kelola cabang dan tag.
• Ganti nama repositori Anda.
• Perbarui visibilitas repositori Anda.
• Kelola salinan lokal dari repositori Anda.

Jika Anda terbiasa bekerja dengan platform seperti GitLab/GitHub/Bitbucket, insting pertama Anda mungkin adalah menggunakan CLI git untuk mengkloning repo Anda (git clone), meng-commit perubahan (git add, git commit) dan mendorongnya (git push). Ini valid saat menggunakan Hugging Face Hub. Namun, rekayasa perangkat lunak dan machine learning tidak memiliki persyaratan dan alur kerja yang sama. Repositori model mungkin menyimpan file bobot model yang besar untuk berbagai framework dan alat, sehingga mengkloning repositori dapat menyebabkan Anda memelihara folder lokal yang besar dengan ukuran masif. Akibatnya, mungkin lebih efisien untuk menggunakan metode HTTP khusus kami. Anda dapat membaca halaman penjelasan paradigma Git vs HTTP kami untuk detail lebih lanjut.

Jika Anda ingin membuat dan mengelola repositori di Hub, mesin Anda harus dalam keadaan masuk. Jika belum, silakan lihat bagian ini. Dalam sisa panduan ini, kami mengasumsikan bahwa mesin Anda sudah masuk.

Daftarkan repositori Anda

Anda dapat mendaftar semua repositori (model, dataset, spaces, dan buckets) untuk akun atau organisasi Anda menggunakan list_user_repos(). Hasilnya mencakup informasi penyimpanan dan diurutkan berdasarkan penggunaan penyimpanan.

>>> 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"))

Atau via CLI (menampilkan 30 repositori secara default, gunakan --limit 0 untuk mendaftar semuanya):

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

Pembuatan dan penghapusan repo

Langkah pertama adalah mengetahui cara membuat dan menghapus repositori. Anda hanya dapat mengelola repositori yang Anda miliki (di bawah namespace nama pengguna Anda) atau dari organisasi tempat Anda memiliki izin tulis.

Buat repositori

Buat repositori kosong dengan create_repo() dan beri nama menggunakan parameter repo_id. repo_id adalah namespace Anda diikuti oleh nama repositori: username_or_org/repo_name.

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

Atau melalui CLI:

>>> 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

Secara default, create_repo() membuat repositori model. Namun, Anda dapat menggunakan parameter repo_type untuk menentukan jenis repositori lain. Misalnya, jika Anda ingin membuat repositori dataset:

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

Atau melalui CLI:

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

Saat Anda membuat repositori, Anda dapat mengatur visibilitas repositori Anda dengan parameter visibility:

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

Atau melalui CLI:

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

Jika Anda ingin mengubah visibilitas repositori di kemudian hari, Anda dapat menggunakan fungsi update_repo_settings().

Jika Anda merupakan bagian dari organisasi dengan rencana Enterprise, Anda dapat membuat repo di resource group tertentu dengan meneruskan resource_group_id sebagai parameter ke create_repo(). Resource groups adalah fitur keamanan untuk mengontrol anggota organisasi mana yang dapat mengakses sumber daya tertentu. Anda dapat mendapatkan ID resource group dengan menyalinnya dari url halaman pengaturan organisasi Anda di Hub (mis. "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). Untuk detail lebih lanjut tentang resource group, lihat panduan ini.

Anda juga dapat membuat repo di wilayah cloud tertentu dengan meneruskan region sebagai parameter:

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

Hapus repositori

Hapus repositori dengan delete_repo(). Pastikan Anda memang ingin menghapus repositori karena ini adalah proses yang tidak dapat dibatalkan!

Tentukan repo_id dari repositori yang ingin Anda hapus:

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

Lewati missing_ok=True untuk mengabaikan panggilan secara diam-diam jika repositori tidak ada:

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

Atau melalui CLI:

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

Duplikat repositori

Dalam beberapa kasus, Anda ingin menyalin repo orang lain untuk menyesuaikannya dengan use case Anda. Hal ini memungkinkan menggunakan metode duplicate_repo(). Metode ini akan menduplikasi seluruh repository, dengan mempertahankan riwayat git secara lengkap. Ini berlaku untuk model, dataset, dan Spaces. Untuk Spaces, Anda tetap perlu mengonfigurasi pengaturan Anda sendiri (hardware, sleep-time, storage, variables, dan secrets). Lihat panduan Manage your Space kami untuk detail lebih lanjut.

>>> 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',...)

Seperti create_repo(), duplicate_repo() menerima resource_group_id untuk membuat salinan langsung di dalam resource group organisasi Enterprise Anda (--resource-group-id dengan hf repos duplicate).

Riwayat git disalin segera, tetapi file LFS/Xet mungkin masih disalin di latar belakang setelah duplicate_repo() mengembalikan nilai. Hingga penyalinan selesai, pengunduhan file-file ini dari repo baru mungkin gagal. Periksa files_copy_pending pada nilai yang dikembalikan untuk mengetahui apakah penyalinan masih berlangsung:

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

Cari Spaces

Hub menyediakan API pencarian semantik untuk menemukan Spaces. Anda dapat mencari menggunakan kueri bahasa alami dengan search_spaces():

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

Untuk detail dan opsi penyaringan lebih lanjut, lihat panduan Manage your Spaces.

Mengunggah dan mengunduh file

Sekarang setelah Anda membuat repositori, Anda tertarik untuk mendorong perubahan ke repositori tersebut dan mengunduh file darinya.

Kedua topik ini layak memiliki panduan tersendiri. Silakan merujuk pada panduan upload dan download untuk mempelajari cara menggunakan repositori Anda.

Salin file

Gunakan copy_files() untuk menyalin file yang sudah di-hosting di Hub dari satu repositori ke repositori lain (atau bahkan dalam repositori yang sama) tanpa perlu mengunduh dan mengunggah ulang. Baik file individual maupun folder lengkap didukung, dan file yang dilacak dengan Xet atau LFS disalin di sisi server berdasarkan hash.

>>> 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/",
... )

Atau melalui CLI, dengan perintah terpadu hf cp (juga tersedia sebagai hf repos cp):

# 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 (dan hf cp) juga dapat menyalin file dari repositori ke Bucket. Menyalin dari bucket ke repositori tidak didukung. Lihat panduan Buckets untuk detail lebih lanjut.

Salinan sisi server hanya berfungsi di dalam region penyimpanan yang sama.

Cabang dan tag

Repositori Git sering kali memanfaatkan cabang untuk menyimpan versi-versi yang berbeda dari repositori yang sama. Tag juga dapat digunakan untuk menandai keadaan tertentu dari repositori Anda, misalnya, saat merilis sebuah versi. Secara lebih umum, cabang dan tag disebut sebagai git references.

Buat cabang dan tag

Anda dapat membuat branch dan tag baru menggunakan create_branch() dan create_tag():

>>> 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.")

Atau melalui CLI:

>>> 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."

Anda dapat menggunakan fungsi delete_branch() dan delete_tag() dengan cara yang sama untuk menghapus branch atau tag, atau hf repos branch delete dan hf repos tag delete masing-masing di CLI.

Daftarkan semua cabang dan tag

Anda juga dapat merujuk daftar git refs yang ada dari sebuah repositori menggunakan list_repo_refs():

>>> 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')
   ]
)

Ubah pengaturan repositori

Repository dilengkapi dengan beberapa pengaturan yang dapat Anda konfigurasikan. Sebagian besar waktu, Anda akan melakukannya secara manual di halaman pengaturan repo di browser Anda. Anda harus memiliki akses tulis ke repo untuk mengonfigurasinya (baik sebagai pemiliknya maupun sebagai bagian dari organisasi). Pada bagian ini, kita akan melihat pengaturan yang juga dapat dikonfigurasi secara programatik menggunakan huggingface_hub.

Beberapa pengaturan bersifat khusus untuk Spaces (perangkat keras, variabel lingkungan, …). Untuk mengonfigurasi pengaturan tersebut, silakan merujuk pada panduan Manage your Spaces kami.

Perbarui visibilitas

Repository dapat bersifat publik atau privat. Repository privat hanya terlihat oleh Anda atau anggota organisasi tempat repository tersebut berada. Ubah repository menjadi privat seperti yang ditunjukkan berikut ini:

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

Atau melalui CLI:

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

Mengatur akses bergerbang

Untuk memberikan kendali lebih besar atas cara repositori digunakan, Hub memungkinkan penulis repositori untuk mengaktifkan permintaan akses untuk repositori mereka. Pengguna harus menyetujui untuk membagikan informasi kontak mereka (nama pengguna dan alamat email) kepada penulis repositori untuk dapat mengakses file ketika fitur ini diaktifkan. Repositori dengan permintaan akses yang diaktifkan disebut sebagai repositori bergerbang.

Anda dapat mengatur repositori sebagai gated menggunakan update_repo_settings():

>>> from huggingface_hub import HfApi

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

Atau melalui CLI:

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

Ganti nama repositori Anda

Anda dapat mengubah nama repositori Anda di Hub menggunakan move_repo(). Dengan metode ini, Anda juga dapat memindahkan repositori dari pengguna ke organisasi. Saat melakukannya, ada beberapa batasan yang perlu Anda perhatikan. Misalnya, Anda tidak dapat mentransfer repositori Anda ke pengguna lain.

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

Atau melalui CLI:

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

Repositori kernel

Hub mendukung tipe repositori "kernel" untuk menghostel kernel komputasi. Ini bukan tipe repositori yang sepenuhnya kompatibel. Hanya seperangkat metode terbatas yang telah diuji dan didukung secara resmi:

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

Perhatikan bahwa create_repo() dan delete_repo() juga kompatibel tetapi dibatasi untuk subset kecil pengguna dan organisasi yang diizinkan di Hub.

Untuk membangun, menerbitkan, dan menggunakan repositori kernel, silakan gunakan paket kernels yang khusus. Lihat dokumentasi Kernels untuk detail lebih lanjut.