Integrasikan pustaka Anda dengan Hub

Hugging Face Hub bertujuan untuk memfasilitasi berbagi model machine learning, checkpoint, dan artefak. Upaya ini mencakup integrasi Hub ke dalam banyak pustaka pihak ketiga yang luar biasa di komunitas. Beberapa yang sudah terintegrasi termasuk spaCy, Sentence Transformers, OpenCLIP, dan timm, di antara banyak lainnya. Integrasi berarti pengguna dapat mengunduh dan mengunggah file ke Hub langsung dari pustaka Anda. Kami berharap Anda akan mengintegrasikan pustaka Anda dan bergabung dengan kami dalam mendemokratiskan kecerdasan buatan untuk semua orang.

Integrasi Hub dengan pustaka Anda memberikan banyak manfaat, termasuk:

• Hosting model gratis untuk Anda dan pengguna Anda.
• Versi file bawaan - bahkan untuk file berukuran besar - yang dimungkinkan oleh Git-Xet.
• Fitur komunitas (diskusi, pull request, suka).
• Metrik penggunaan untuk semua model yang dijalankan dengan pustaka Anda.

Tutorial ini akan membantu Anda mengintegrasikan Hub ke dalam pustaka Anda sehingga pengguna Anda dapat memanfaatkan semua fitur yang ditawarkan oleh Hub.

Sebelum memulai, kami merekomendasikan Anda untuk membuat akun Hugging Face yang dapat Anda gunakan untuk mengelola repositori dan file Anda.

Jika Anda membutuhkan bantuan dengan integrasi, silakan buka issue, dan kami akan dengan senang hati membantu Anda.

Implementasi

Menerapkan integrasi sebuah pustaka dengan Hub sering kali berarti menyediakan metode bawaan untuk memuat model dari Hub dan memungkinkan pengguna mendorong model baru ke Hub. Bagian ini akan membahas dasar-dasar cara melakukannya menggunakan pustaka huggingface_hub. Untuk panduan yang lebih mendalam, lihat panduan ini.

Instalasi

Untuk mengintegrasikan pustaka Anda dengan Hub, Anda perlu menambahkan pustaka huggingface_hub sebagai dependensi:

pip install huggingface_hub

Untuk detail lebih lanjut tentang instalasi huggingface_hub, lihat panduan ini.

Dalam panduan ini, kami akan berfokus pada pustaka Python. Jika Anda telah mengimplementasikan pustaka Anda dalam JavaScript, Anda dapat menggunakan @huggingface/hub sebagai gantinya. Logika lainnya (yaitu hosting file, cuplikan kode, dll.) tidak bergantung pada bahasa kode.

Disalin

npm add @huggingface/hub

Pengguna perlu melakukan autentikasi setelah berhasil menginstal pustaka huggingface_hub. Cara termudah untuk melakukan autentikasi adalah dengan menyimpan token di mesin. Pengguna dapat melakukannya dari terminal menggunakan perintah login():

hf auth login

Perintah tersebut memberi tahu mereka apakah sudah masuk dan meminta token mereka. Token kemudian divalidasi dan disimpan di direktori HF_HOME (default ke ~/.cache/huggingface/token). Setiap skrip atau pustaka yang berinteraksi dengan Hub akan menggunakan token ini saat mengirim permintaan.

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

from huggingface_hub import login
login()

Autentikasi bersifat opsional saat mengunduh file dari repositori publik di Hub.

Unduh file dari Hub

Integrations memungkinkan pengguna untuk mengunduh model dari Hub dan menginstansiasikannya langsung dari pustaka Anda. Hal ini biasanya dimungkinkan dengan menyediakan metode (biasanya bernama from_pretrained atau load_from_hf) yang harus spesifik untuk pustaka Anda. Untuk menginstansiasikan model dari Hub, pustaka Anda harus:

• mengunduh file dari Hub. Inilah yang akan kita bahas sekarang.
• instansiasi model Python dari file-file ini.

Gunakan metode hf_hub_download untuk mengunduh file dari repositori di Hub. File yang diunduh disimpan di cache: ~/.cache/huggingface/hub. Pengguna tidak perlu mengunduh ulang file tersebut saat menggunakannya lagi, yang menghemat banyak waktu untuk file berukuran besar. Selain itu, jika repositori diperbarui dengan versi baru dari file tersebut, huggingface_hub akan secara otomatis mengunduh versi terbaru dan menyimpannya di cache. Pengguna tidak perlu khawatir untuk memperbarui file mereka secara manual.

Sebagai contoh, unduh file config.json dari repositori lysandre/arxiv-nlp:

>>> 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 sekarang berisi path ke file yang diunduh. Anda dijamin bahwa file tersebut ada dan sudah diperbarui.

Jika pustaka Anda perlu mengunduh seluruh repositori, gunakan snapshot_download. Fungsi ini akan menangani pengunduhan semua file secara paralel. Nilai yang dikembalikan adalah path ke direktori yang berisi file-file yang diunduh.

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

Banyak opsi tersedia untuk mengunduh file dari revisi tertentu, memfilter file mana yang akan diunduh, menyediakan direktori cache kustom, mengunduh ke direktori lokal, dan sebagainya. Lihat panduan unduhan untuk detail lebih lanjut.

Unggah file ke Hub

Anda mungkin juga ingin menyediakan metode agar pengguna dapat mendorong model mereka sendiri ke Hub. Hal ini memungkinkan komunitas untuk membangun ekosistem model yang kompatibel dengan pustaka Anda. Pustaka huggingface_hub menawarkan metode untuk membuat repositori dan mengunggah file:

• create_repo membuat repositori di Hub.
• upload_file dan upload_folder mengunggah file ke repositori di Hub.

Metode create_repo membuat repositori di Hub. Gunakan parameter repo_id untuk memberikan nama pada repositori Anda:

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

Saat Anda memeriksa akun Hugging Face Anda, Anda seharusnya sekarang dapat melihat repositori test-model di bawah namespace Anda.

Metode upload_file mengunggah file ke Hub. Metode ini membutuhkan hal-hal berikut:

• Path ke file yang akan diunggah.
• Jalur terakhir dalam repositori.
• Repositori tempat Anda ingin mendorong file.

Sebagai contoh:

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

Jika Anda memeriksa akun Hugging Face Anda, Anda seharusnya dapat melihat file di dalam repositori Anda.

Biasanya, sebuah pustaka akan menserialisasi model ke direktori lokal dan kemudian mengunggah seluruh folder sekaligus ke Hub. Hal ini dapat dilakukan menggunakan upload_folder:

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

Untuk detail lebih lanjut tentang cara mengunggah file, lihat panduan pengunggahan.

Kartu model

Model cards adalah file yang menyertai model dan menyediakan informasi yang berguna. Di balik layar, model cards adalah file Markdown sederhana dengan metadata tambahan. Model cards sangat penting untuk kemudahan penemuan, reproduktibilitas, dan berbagi! Anda dapat menemukan model card sebagai file README.md di repo model mana pun. Lihat panduan model cards untuk detail lebih lanjut tentang cara membuat model card yang baik.

Jika pustaka Anda memungkinkan pendorongan model ke Hub, disarankan untuk menghasilkan kartu model minimal dengan metadata yang telah diisi sebelumnya (biasanya library_name, pipeline_tag atau tags) dan informasi tentang bagaimana model tersebut dilatih. Hal ini akan membantu memiliki deskripsi yang terstandarisasi untuk semua model yang dibuat dengan pustaka Anda.

Daftarkan pustaka Anda

Bagus! Anda sekarang seharusnya memiliki pustaka yang mampu memuat model dari Hub dan pada akhirnya mendorong model baru. Langkah selanjutnya adalah memastikan bahwa model Anda di Hub terdokumentasi dengan baik dan terintegrasi dengan platform. Untuk melakukannya, pustaka dapat didaftarkan di Hub, yang membawa beberapa manfaat bagi pengguna:

• label yang menarik dapat ditampilkan di halaman model (misalnya KerasNLP alih-alih keras-nlp)
• tautan ke repositori pustaka dan dokumentasi Anda ditambahkan ke setiap halaman model
• aturan jumlah unduhan khusus dapat didefinisikan
• code snippets dapat dibuat untuk menunjukkan cara memuat model menggunakan pustaka Anda

Untuk mendaftarkan pustaka baru, silakan buka Pull Request di sini mengikuti instruksi di bawah ini:

• ID pustaka harus menggunakan huruf kecil dan dipisahkan dengan tanda hubung (contoh: "adapter-transformers"). Pastikan untuk mempertahankan urutan alfabetis saat membuka PR.
• Set repoName dan prettyLabel dengan casing yang ramah pengguna (contoh: DeepForest).
• Setel repoUrl dengan tautan ke kode sumber pustaka (biasanya repositori GitHub).
• (opsional) set docsUrl dengan tautan ke dokumentasi library. Jika dokumentasinya ada di repo GitHub yang dirujuk di atas, tidak perlu diset dua kali.
• set filter ke false.
• (opsional) definisikan bagaimana unduhan harus dihitung dengan mengatur countDownload. Unduhan dapat dilacak berdasarkan ekstensi file atau nama file. Pastikan untuk tidak menduplikasi penghitungan. Misalnya, jika memuat model memerlukan 3 file, aturan penghitungan unduhan harus hanya menghitung unduhan pada 1 dari 3 file tersebut. Jika tidak, jumlah unduhan akan terlalu tinggi. Catatan: jika pustaka menggunakan salah satu file konfigurasi default (config.json, config.yaml, hyperparams.yaml, params.json, dan meta.yaml, lihat di sini), tidak perlu mendefinisikan aturan penghitungan unduhan secara manual.
• (opsional) definisikan snippets agar pengguna tahu cara menginstansiasi model dengan cepat. Detail lebih lanjut di bawah.

Sebelum membuka PR, pastikan bahwa setidaknya satu model dirujuk di https://huggingface.co/models?other=my-library-name. Jika tidak, metadata kartu model dari model-model terkait harus diperbarui dengan library_name: my-library-name (lihat contoh). Jika Anda bukan pemilik model-model di Hub, silakan buka PR (lihat contoh).

Berikut adalah contoh minimal untuk menambahkan integrasi VFIMamba.

Potongan kode

Kami merekomendasikan untuk menambahkan potongan kode guna menjelaskan cara menggunakan model di pustaka hilir Anda.

Untuk menambahkan potongan kode, Anda harus memperbarui file model-libraries-snippets.ts dengan instruksi untuk model Anda. Sebagai contoh, integrasi Asteroid mencakup potongan kode singkat tentang cara memuat dan menggunakan model Asteroid:

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

Melakukan hal tersebut juga akan menambahkan tag ke model Anda sehingga pengguna dapat dengan cepat mengidentifikasi model dari pustaka Anda.

Setelah snippet Anda ditambahkan ke model-libraries-snippets.ts, Anda dapat merujuknya di model-libraries.ts seperti yang dijelaskan di atas.

Dokumentasikan pustaka Anda

Terakhir, Anda dapat menambahkan pustaka Anda ke dokumentasi Hub. Periksa misalnya PR Setfit yang menambahkan SetFit ke dokumentasi.