Hugging Face's logo

Hub Python Library documentation

Mulai Cepat

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Mulai Cepat

Hugging Face Hub adalah tempat utama untuk berbagi model machine learning, demo, dataset, dan metrik. Library huggingface_hub membantu Anda berinteraksi dengan Hub tanpa harus meninggalkan lingkungan pengembangan Anda. Anda dapat dengan mudah membuat dan mengelola repositori, mengunduh dan mengunggah file, serta mendapatkan metadata model dan dataset yang berguna dari Hub.

Instalasi

Untuk memulai, instal pustaka huggingface_hub:

pip install --upgrade huggingface_hub

Untuk detail lebih lanjut, lihat panduan instalasi.

huggingface_hub juga dilengkapi dengan CLI hf yang memungkinkan Anda berinteraksi langsung dengan Hub dari terminal. Jika Anda menggunakan agen AI (Claude Code, Codex, Cursor, …), instal Skill agar agen Anda dapat menggunakan CLI:

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

Lihat panduan Hugging Face CLI for AI Agents untuk detail lebih lanjut.

Unduh file

Repository di Hub menggunakan kontrol versi git, dan pengguna dapat mengunduh satu file atau seluruh repository. Anda dapat menggunakan fungsi hf_hub_download() untuk mengunduh file. Fungsi ini akan mengunduh dan menyimpan file ke cache di disk lokal Anda. Kapan pun Anda membutuhkan file tersebut di kemudian hari, ia akan dimuat dari cache, sehingga Anda tidak perlu mengunduhnya lagi.

Anda akan memerlukan id repositori dan nama file dari file yang ingin Anda unduh. Sebagai contoh, untuk mengunduh file konfigurasi model Pegasus:

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

Untuk mengunduh versi tertentu dari file, gunakan parameter revision untuk menentukan nama branch, tag, atau commit hash. Jika Anda memilih untuk menggunakan commit hash, hash tersebut harus berupa hash berpanjang penuh, bukan commit hash pendek 7 karakter:

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

Untuk detail dan opsi lebih lanjut, lihat referensi API untuk hf_hub_download().

Autentikasi

Dalam banyak kasus, Anda harus terautentikasi dengan akun Hugging Face untuk berinteraksi dengan Hub: mengunduh repositori privat, mengunggah file, membuat PR, dan lain-lain. Buat akun jika Anda belum memilikinya.

Perintah login

Cara termudah untuk melakukan autentikasi adalah dengan perintah login():

hf auth login

Jika Anda sudah masuk, perintah akan langsung kembali. Untuk memaksa masuk ulang, gunakan hf auth login --force. Jika Anda belum masuk, Anda akan diminta untuk masuk melalui browser: buka URL yang dicetak, masukkan kode pendek, setujui permintaan, dan token akses akan diambil serta disimpan di direktori HF_HOME Anda (default ke ~/.cache/huggingface/token). Token kedaluwarsa setelah beberapa waktu tetapi diperbarui secara otomatis selama Anda terus menggunakannya. Skrip atau pustaka mana pun yang berinteraksi dengan Hub akan menggunakan token ini saat mengirim permintaan. Sebagai alternatif, Anda dapat menempelkan User Access Token yang dihasilkan dari Settings page Anda.

User Access Tokens dapat memiliki izin read atau write. Pastikan Anda memiliki token akses write jika ingin membuat atau mengedit repositori. Jika tidak, sebaiknya buat token read untuk mengurangi risiko jika token Anda tidak sengaja bocor.

Sebagai alternatif, Anda dapat masuk secara programatik menggunakan login() di notebook atau skrip:

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

Anda hanya dapat masuk ke satu akun pada satu waktu. Masuk ke akun baru akan secara otomatis mengeluarkan Anda dari akun sebelumnya. Untuk menentukan akun aktif Anda saat ini, cukup jalankan perintah hf auth whoami.

Setelah masuk, semua permintaan ke Hub - bahkan metode yang tidak memerlukan autentikasi - akan menggunakan token akses Anda secara default. Jika Anda ingin menonaktifkan penggunaan token secara implisit, Anda harus mengatur HF_HUB_DISABLE_IMPLICIT_TOKEN=1 sebagai variabel lingkungan (lihat referensi).

Kelola beberapa token secara lokal

Anda dapat menyimpan beberapa token di mesin Anda dengan cara masuk menggunakan perintah login() untuk setiap token. Jika Anda perlu berpindah antar token ini secara lokal, Anda dapat menggunakan perintah auth switch:

hf auth switch

Perintah ini akan meminta Anda memilih token berdasarkan namanya dari daftar token yang tersimpan. Setelah dipilih, token yang dipilih menjadi token aktif, dan akan digunakan untuk semua interaksi dengan Hub.

Anda dapat menampilkan semua token akses yang tersedia di mesin Anda dengan hf auth list.

Variabel lingkungan

Variabel lingkungan HF_TOKEN juga dapat digunakan untuk mengautentikasi diri Anda. Ini sangat berguna di Space, di mana Anda dapat mengatur HF_TOKEN sebagai Space secret.

BARU: Google Colaboratory memungkinkan Anda mendefinisikan kunci privat untuk notebook Anda. Definisikan rahasia HF_TOKEN untuk autentikasi otomatis!

Autentikasi melalui variabel lingkungan atau rahasia memiliki prioritas lebih tinggi daripada token yang disimpan di mesin Anda.

Parameter metode

Terakhir, Anda juga dapat melakukan autentikasi dengan meneruskan token Anda ke metode apa pun yang menerima token sebagai parameter.

from huggingface_hub import whoami

user = whoami(token=...)

Hal ini biasanya tidak disarankan, kecuali dalam lingkungan di mana Anda tidak ingin menyimpan token secara permanen atau jika Anda perlu menangani beberapa token sekaligus.

Harap berhati-hati saat meneruskan token sebagai parameter. Praktik terbaik adalah selalu memuat token dari vault yang aman, bukan menuliskannya secara langsung (hardcoding) di basis kode atau notebook Anda. Token yang di-hardcode menimbulkan risiko kebocoran yang besar jika kode Anda dibagikan secara tidak sengaja.

Buat repositori

Setelah Anda mendaftar dan masuk, buat repositori dengan fungsi create_repo():

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

Jika Anda ingin repositori Anda bersifat privat, maka:

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

Repositori privat tidak akan terlihat oleh siapa pun selain Anda.

Untuk membuat repositori atau mendorong konten ke Hub, Anda harus menyediakan User Access Token yang memiliki izin write. Anda dapat memilih izin saat membuat token di halaman Pengaturan Anda.

Unggah file

Gunakan fungsi upload_file() untuk menambahkan file ke repositori yang baru Anda buat. Anda perlu menentukan:

  1. Path file yang akan diunggah.
  2. Path file di dalam repositori.
  3. ID repositori tempat Anda ingin menambahkan file.
>>> 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",
... )

Untuk mengunggah lebih dari satu file sekaligus, lihat panduan Upload yang akan memperkenalkan beberapa metode untuk mengunggah file (dengan atau tanpa git).

Langkah selanjutnya

Perpustakaan huggingface_hub menyediakan cara mudah bagi pengguna untuk berinteraksi dengan Hub menggunakan Python. Untuk mempelajari lebih lanjut tentang cara Anda mengelola file dan repositori di Hub, kami merekomendasikan untuk membaca panduan cara kami untuk:

Update on GitHub

←Beranda Instalasi→