Kontribusi untuk PEFT

Kami dengan senang hati menerima kontribusi untuk PEFT. Jika Anda berencana untuk berkontribusi, silakan baca ini agar prosesnya berjalan semulus mungkin.

Diskusikan dan dapatkan persetujuan sebelum membuka PR

Sebelum membuka pull request (termasuk draft), buka atau cari issue di huggingface/peft dan diskusikan kontribusi yang Anda usulkan. Jika sudah ada issue yang ada dan seseorang sudah sedang mengerjakannya, telah menyatakan niat untuk mengerjakannya, atau memiliki PR yang terbuka, Anda tidak boleh mengirimkan PR terpisah. Tunggu hingga maintainer PEFT atau anggota Hugging Face secara eksplisit menyetujui proposal tersebut. Jika Anda membuka issue, pertahankan panjang dan kompleksitas deskripsi agar sebanding dengan kompleksitas issue tersebut. Sering kali, deskripsi singkat dengan reproducer lebih bernilai daripada deskripsi panjang.

Komentar persetujuan berisi pesan /peft-triage approved. Komentar ini juga dapat mencantumkan nama kontributor yang ditugaskan, misalnya /peft-triage approved username atau /peft-triage approved @username. Membuka PR untuk isu yang tidak Anda tugaskan akan menyebabkan PR tersebut ditutup.

Hubungkan masalah terbuka yang telah disetujui dalam deskripsi PR Anda menggunakan #123, huggingface/peft#123, atau https://github.com/huggingface/peft/issues/123. Sebagai pengecualian, maintainer dapat menetapkan diskusi jangka panjang tertentu yang dapat dirujuk melalui URL GitHub lengkapnya tanpa komentar persetujuan terpisah. Jika Anda merujuk beberapa masalah atau diskusi, satu rujukan yang valid sudah cukup.

Alur kerja otomatis memeriksa PR untuk masalah terbuka atau diskusi yang disetujui. PR tanpa referensi yang valid akan ditutup secara otomatis beserta penjelasannya. Anda dapat memperoleh persetujuan masalah, memperbarui deskripsi PR, dan membuka kembali PR yang sama; mohon jangan membuat pengganti. Jika Anda merasa PR Anda ditutup secara keliru, hubungi para maintainer di PR tersebut.

Bot stale independen masih dapat menutup item yang tidak aktif, bahkan jika diberi label triaged. Jika Anda merasa kontribusinya terlewat oleh para maintainer, Anda dapat memberi tahu mereka, tetapi tidak lebih awal dari dua minggu setelah tidak ada aktivitas.

Instalasi

Ikuti langkah-langkah berikut untuk mulai berkontribusi:

Fork repository dengan mengklik tombol ‘Fork’ di halaman repository. Hal ini membuat salinan kode di bawah akun pengguna GitHub Anda.
Klon fork Anda ke disk lokal, lalu tambahkan repositori dasar sebagai remote. Perintah berikut mengasumsikan Anda telah mengunggah kunci SSH publik Anda ke GitHub. Lihat panduan berikut untuk informasi lebih lanjut.
```
git clone git@github.com:<your Github handle>/peft.git
cd peft
git remote add upstream https://github.com/huggingface/peft.git
```
Buat cabang baru untuk menyimpan perubahan pengembangan Anda, dan lakukan ini untuk setiap PR baru yang Anda kerjakan.

Mulai dengan menyinkronkan cabang main Anda dengan cabang upstream/main (detail lebih lanjut ada di Dokumentasi GitHub):
```
git checkout main
git fetch upstream
git merge upstream/main
```
Setelah cabang main Anda tersinkronkan, buat cabang baru darinya:
```
git checkout -b a-descriptive-name-for-my-changes
```
Jangan bekerja di cabang main.
Siapkan lingkungan pengembangan dengan menjalankan perintah berikut di lingkungan conda atau lingkungan virtual yang telah Anda buat untuk bekerja pada pustaka ini:
```
pip install -e ".[test]"
```
(Jika PEFT sudah terinstal di lingkungan virtual, hapus dengan pip uninstall peft sebelum menginstalnya kembali.)

Jika Anda baru dalam membuat pull request, ikuti panduan Membuat pull request dari GitHub.

Uji dan pemeriksaan kualitas kode

Terlepas dari jenis kontribusi (kecuali hanya tentang dokumentasi), Anda harus menjalankan pengujian dan pemeriksaan kualitas kode sebelum membuat PR untuk memastikan kontribusi Anda tidak merusak apa pun dan mematuhi standar proyek.

Menjalankan pengujian dan pemeriksaan

Kami menyediakan Makefile untuk menjalankan tes yang diperlukan. Jalankan kode di bawah ini untuk unit test:

make test

Jalankan salah satu dari berikut ini untuk hanya memeriksa atau memeriksa dan memperbaiki kualitas dan gaya kode:

make quality  # just check
make style  # check and fix

Menjalankan make quality juga akan memeriksa apakah semua method/class dari API publik PEFT (yaitu semua yang disebutkan dalam peft.__all__) disebutkan dalam dokumentasi. Error ini tidak dapat diperbaiki dengan make style; Anda perlu memastikan untuk mendokumentasikan item baru dalam API publik di dokumentasi untuk memperbaiki error ini.

Anda juga dapat mengatur pre-commit untuk menjalankan perbaikan ini secara otomatis sebagai Git commit hooks.

$ pip install pre-commit
$ pre-commit install

Menjalankan semua tes dapat memakan waktu lama, sehingga selama pengembangan, lebih efisien untuk hanya menjalankan tes yang spesifik untuk perubahan Anda, misalnya melalui:

pytest tests/<test-file-name> -k <name-of-test>

Ini seharusnya selesai jauh lebih cepat dan memungkinkan iterasi yang lebih cepat.

Menambahkan pengujian

Untuk panduan umum tentang menambahkan tes baru, lihat tests/README.md.

Jika perubahan Anda spesifik untuk pengaturan perangkat keras (misalnya, membutuhkan CUDA), lihat tests/test_gpu_examples.py dan tests/test_common_gpu.py untuk melihat apakah masuk akal untuk menambahkan tes di sana. Jika perubahan Anda dapat memengaruhi penyimpanan dan pemuatan model, silakan jalankan tes dengan flag --regression untuk memicu tes regresi.

PR yang kedaluwarsa

Dapat terjadi bahwa saat Anda mengerjakan PR, basis kode yang mendasarinya berubah karena perubahan lain yang digabungkan. Jika hal itu terjadi – terutama ketika ada konflik penggabungan – silakan perbarui cabang Anda dengan perubahan terbaru. Ini bisa berupa merge atau rebase, dan kami akan melakukan squash and merge pada PR tersebut setelah siap. Hindari force push untuk memudahkan proses review.

Deskripsi PR

Saat membuka PR, silakan berikan deskripsi yang baik mengenai perubahan yang Anda usulkan dan merujuk pada isu yang telah disetujui seperti yang dijelaskan di atas. Jika terkait dengan isu atau PR lain, silakan rujuk juga. Memberikan deskripsi yang baik tidak hanya membantu para reviewer meninjau kode Anda dengan lebih baik dan cepat, tetapi juga dapat digunakan kemudian (sebagai dasar) untuk pesan commit yang membantu pemeliharaan jangka panjang proyek.

Jaga agar panjang dan kompleksitas deskripsi PR sesuai dengan perubahan yang dilakukan. Kami tidak membutuhkan sepuluh paragraf penjelasan untuk perubahan satu baris yang sepele. Jangan mengulang hal yang sudah jelas terlihat dari diff (misalnya “Memperbaiki typo di ‘foobaar’”).

Jika kode Anda melakukan beberapa perubahan yang tidak sepele, mungkin juga merupakan ide yang baik untuk menambahkan komentar ke kode guna menjelaskan perubahan tersebut. Misalnya, jika Anda harus mengulang implementasi Anda beberapa kali karena cara yang paling jelas tidak berhasil, itu merupakan indikasi yang baik bahwa komentar kode diperlukan.

Jika relevan, tunjukkan bagaimana Anda menguji perubahan tersebut, misalnya dengan menampilkan perintah pengujian pytest atau kode reproduksi.

Umpan balik peninjau

Setelah Anda mengirim PR, seorang maintainer biasanya akan memberikan umpan balik dalam beberapa hari. Jika Anda tidak menerima umpan balik dalam dua minggu, PR Anda mungkin terlewat dari perhatian mereka; silakan hubungi para maintainer saat itu, tetapi tidak lebih awal.

Jika reviewer memberikan komentar di dalam teks, jangan tandai sebagai terselesaikan jika Anda sudah menanganinya. Biarkan komentar tersebut tetap terbuka, karena membantu reviewer untuk melanjutkan pekerjaan mereka.

Setelah menyelesaikan umpan balik dari peninjau, beri tahu peninjau tersebut agar mereka mengetahui bahwa PR sudah siap untuk ditinjau.

Perbaikan bug

Silakan berikan deskripsi tentang situasi yang menyebabkan bug tersebut. Jika sudah ada masalah yang ada sebelumnya, silakan tautkan ke masalah tersebut (misalnya, “Resolves #12345”).

Idealnya, ketika perbaikan bug disediakan, perbaikan tersebut harus disertai dengan pengujian untuk bug tersebut. Pengujian harus gagal dengan kode saat ini dan berhasil dengan perbaikan bug. Tambahkan komentar pada pengujian yang merujuk pada masalah atau PR. Tanpa pengujian, akan lebih sulit untuk mencegah regresi di masa depan.

Perbaikan dokumentasi

Kami senang menerima perbaikan untuk tautan yang rusak serta dokumentasi yang hilang atau tidak jelas. Perhatian terhadap contoh, dengan memastikan bahwa contoh tersebut selalu mutakhir dan berjalan dengan baik di lingkungan yang bergerak cepat ini, juga sangat dihargai.

Mohon untuk tidak mengirim pull request yang hanya memperbaiki kesalahan ketik, karena perubahan semacam itu umumnya menciptakan lebih banyak pekerjaan daripada yang dihemat. Perubahan seperti ini lebih baik digabungkan dengan perbaikan yang lebih substansial (seperti memperbaiki tautan yang rusak atau memperluas/memperbarui dokumentasi).

Tambahkan metode fine-tuning PEFT baru

Metode fine-tuning yang efisien parameter baru terus dikembangkan. Jika Anda ingin menambahkan metode baru yang menjanjikan ke PEFT, silakan ikuti langkah-langkah berikut.

Jika Anda bukan penulis dari paper asli, periksa implementasi yang sudah ada dan pastikan kembali dengan para penulis bahwa mereka tidak berencana untuk mengirimkan PR sendiri.
Buka masalah proposal dan tunggu persetujuan eksplisit seperti yang dijelaskan di atas, sebelum memulai pekerjaan integrasi inti yang tercantum di bawah ini.
Periksa commit terbaru untuk metode PEFT baru yang ditambahkan sebagai inspirasi.
Setelah proposal disetujui, dapat berguna untuk membuka PR draf lebih awal begitu metode pada dasarnya berfungsi dan tes pertama lulus, lalu meminta umpan balik. Rujuk masalah yang disetujui dalam deskripsi PR draf.

Integrasi inti metode PEFT baru

PR lengkap untuk menambahkan metode PEFT baru

Pastikan argumen konfigurasi yang spesifik untuk metode tersebut diberi nama dan dijelaskan dengan baik, jangan asumsikan bahwa pengguna memahami isi makalahnya secara mendalam.
Ikuti konvensi penamaan dan penulisan kode PEFT.
Pastikan Anda tidak secara tidak sengaja memeriksa perubahan yang tidak terkait, misalnya formatter kode yang mengubah file yang tidak terkait.
Jika beberapa pilihan implementasi tidak trivial, dokumentasikan dengan komentar kode.
Lengkapi seluruh suite pengujian (test_config.py, test_decoder_models.py, dll.) dengan menambahkan metode PEFT ke matriks pengujian. Pastikan pengujian tersebut lulus.
Tambahkan dokumentasi di docs/source/package_reference/ dengan penjelasan singkat, tautan paper, cuplikan penggunaan, dan blok autodoc. Jelaskan kelebihan dan kekurangan dibandingkan metode lain seperti LoRA. Daftarkan halaman dokumentasi tersebut di docs/source/_toctree.yml.
Tambahkan contoh yang dapat dijalankan di bawah examples/ (bisa berupa salinan dari contoh yang sudah ada), dengan README.md singkat.
Periksa benchmark di method_comparison/ dan tambahkan pengaturan eksperimen untuk metode baru Anda. Ini adalah tempat yang baik untuk melakukan pemeriksaan kewarasan bahwa metode PEFT dilatih sesuai harapan. Sertakan satu atau dua konfigurasi benchmark yang masuk akal (satu default, satu yang dioptimalkan untuk benchmark).
Disarankan: Tambahkan dukungan kuantisasi generik. Daripada harus menambahkan tipe lapisan kuantisasi secara eksplisit untuk setiap metode kuantisasi, dukung kuantisasi generik. Sebagai contoh, periksa bagaimana hal itu diimplementasikan di BOFT. Perluas https://github.com/huggingface/peft/blob/main/tests/test_quantization.py dengan menambahkan metode PEFT Anda di sana. Minta bantuan dari maintainer jika diperlukan.

Membuat perubahan pada metode PEFT yang ada

Jika Anda melakukan perubahan pada metode PEFT yang berpotensi mengubah output-nya, sehingga membatalkan checkpoint yang sudah dilatih, kita perlu mengambil langkah pencegahan ekstra. Silakan periksa deskripsi di https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md untuk detailnya. Instruksi di sana ditujukan untuk manusia maupun AI.

Tambahkan fitur lain

Pertama, buka sebuah issue di GitHub dengan usulan untuk menambahkan fitur baru dan tunggu persetujuan eksplisit seperti yang dijelaskan di atas. Dengan cara ini, Anda dapat berdiskusi dengan para maintainer apakah masuk akal untuk menambahkan fitur tersebut sebelum menghabiskan terlalu banyak waktu untuk mengimplementasikannya.

Fitur baru umumnya harus disertai dengan pengujian dan dokumentasi atau contoh. Tanpa yang terakhir, pengguna akan kesulitan menemukan fitur baru yang keren yang Anda buat.

Perubahan pada kode harus diimplementasikan dengan cara yang kompatibel mundur. Sebagai contoh, kode yang sudah ada harus tetap berfungsi dengan cara yang sama setelah fitur tersebut digabungkan.

Update on GitHub