Transformers documentation
Kontribusi ke 🤗 Transformers
Kontribusi ke 🤗 Transformers
Aturan kontribusi
Ada dua cara untuk membuka PR: memperbaiki issue yang terbuka untuk kontribusi, atau membuka PR mandiri yang membawa bukti tersendiri. Model baru juga dapat ditambahkan melalui PR mandiri, lihat Menambahkan model baru. Staf Hugging Face, maintainer, dan beberapa kontributor lama dikecualikan dari aturan ini.
Memperbaiki masalah. Hubungkan masalah tersebut dengan kata kunci penutupan seperti Fixes #123 dalam deskripsi PR. Anda dapat mengerjakan:
- isu yang Anda buka, setelah seorang maintainer memberinya label
triaged - isu berlabel
contributions-welcome - sebuah masalah berlabel
New model, lihat Menambahkan model baru
Isu milik orang lain tidak terbuka untuk PR kecuali seorang maintainer telah mengatakannya. PR yang mengaitkan isu yang tidak dapat Anda kerjakan akan ditutup.
Anda tidak perlu meminta izin sebelum mengerjakan isu yang memenuhi syarat, dan kami tidak mengalokasikan isu kepada orang tertentu. Komentar seperti “bolehkah saya mengerjakan ini?” atau “tolong alokasikan ini kepada saya” hanya menambah kebisingan, jadi lewati saja dan buka PR Anda. PR pertama untuk suatu isu mendapat prioritas.
Sebelum mengerjakan isu contributions-welcome atau New model, periksa apakah sudah ada yang membuka PR untuknya. Jika ada, jangan buka PR lain. Jika Anda menemukan kesalahan, tinggalkan saran pada PR yang sudah ada. Hanya buka PR yang bersaing jika PR yang ada memiliki cacat mendasar, atau sudah usang: penulisnya tidak merespons komentar ulasan atau mendorong perubahan selama dua minggu. PR yang menunggu ulasan maintainer tidak dianggap usang. Dalam hal apa pun, jelaskan alasannya pada isu tersebut sebelum membuka PR Anda.
PR mandiri. Jika belum ada yang melaporkan masalahnya, Anda dapat membuka PR tanpa issue. PR mandiri ditujukan untuk perubahan singkat yang berdampak nyata, seperti perbaikan bug, peningkatan kinerja, atau perbaikan contoh yang rusak di dokumentasi. Deskripsi PR memerlukan bukti yang sama seperti pada issue:
- untuk bug, skrip singkat yang gagal di
maindan berhasil dengan perbaikan Anda, menggunakan checkpoint yang dipublikasikan, konfigurasi default, atau alur kerja yang terdokumentasi - untuk peningkatan performa, angka sebelum dan sesudah pada beban kerja yang realistis, seperti checkpoint yang dipublikasikan atau konfigurasi default, serta perangkat keras yang Anda gunakan. Microbenchmark yang lebih cepat untuk fungsi yang tidak berada di jalur panas tidak dihitung.
Jika masalah yang sama sudah ada, PR Anda akan diproses melalui masalah tersebut, terlepas dari apakah Anda menyambungkannya atau tidak. PR mandiri yang memperbaiki masalah yang sudah ada, atau yang datang tanpa bukti, akan ditutup. Persyaratan ini tidak berlaku untuk model baru.
Perubahan yang memerlukan issue terlebih dahulu. Pembersihan mekanis yang tidak memengaruhi kebenaran atau kinerja, serta perbaikan massal terhadap kesalahan ketik atau perumusan dalam dokumentasi, memerlukan issue sebelum PR. Usulkan perubahan tersebut, bagaimana Anda akan melakukannya, dan berapa banyak file yang akan diubah. Perbaikan satu kesalahan ketik terlalu kecil untuk PR di jalur mana pun.
Meninjau PR orang lain. Ulasan dari komunitas sangat dihargai jika memberikan informasi baru, tetapi para maintainer membaca setiap komentar di PR, dan kami sudah menjalankan alat review kami sendiri. Sebelum berkomentar di PR yang tidak Anda buat, pastikan Anda memiliki hal spesifik untuk disampaikan:
- Jika Anda menemukan masalah atau memiliki perubahan konkret untuk diusulkan, tinggalkan komentar inline pada baris yang relevan, idealnya sebagai saran GitHub yang dapat langsung diterapkan oleh penulis. Reproducer sangat membantu jika Anda melaporkan bug.
- Jika Anda melaporkan masalah yang diperbaiki oleh PR tersebut, catatan singkat tentang apakah PR itu memperbaiki kasus Anda akan sangat berguna.
- Mohon jangan memposting ringkasan umum atau laporan “saya menguji ini dan berhasil”. Persetujuan dari non-maintainer tidak memengaruhi apakah PR akan digabungkan, dan komentar panjang yang mengulang isi PR hanya membuang waktu tanpa mengubah hasil.
Cara Anda menulis kode sepenuhnya terserah Anda, tetapi Anda bertanggung jawab atas semua yang Anda kirimkan, dan kami dapat memblokir akun yang berulang kali membuka masalah atau PR berkualitas rendah. Silakan juga hormati code of conduct kami.
What we look for in issues and PRs
- Diagnosis bug yang jelas. Solusi cepat sering kali menyebabkan pembengkakan kode atau ketidakkompatibelan dengan model lain. Meluangkan waktu untuk menelusuri penyebab pasti dari suatu masalah, dan khususnya menemukan commit pertama di mana masalah tersebut muncul (misalnya dengan git bisect) sangat berharga.
- Minimalkan diff. Periksa PR Anda untuk menghilangkan perubahan yang tidak perlu. Pastikan Anda tidak meng-commit skrip pengujian atau file yang tidak terkait. Tambahkan komentar hanya jika benar-benar diperlukan. Jika PR Anda bisa berupa perbaikan 1 baris, buatlah menjadi perbaikan 1 baris. Hal ini membuat PR jauh lebih mudah ditinjau dan meningkatkan peluang untuk diterima.
- Luangkan waktu untuk mereproduksi masalah. Sangat sering ketika pengguna melaporkan suatu masalah, masalah tersebut sebenarnya disebabkan oleh masalah lingkungan di mesin mereka, atau mereka salah mendiagnosis masalah dan menyarankan solusi yang tidak valid. Terlalu mempercayai laporan tersebut dapat menghasilkan solusi yang buruk, terkadang untuk masalah yang bahkan tidak ada! Menulis skrip reproduser sederhana dan menjalankannya untuk memastikan Anda melihat masalahnya sangat berharga.
- Bandingkan dengan model lain. Repo Transformers sangat besar, dan banyak model yang melakukan hal serupa. Saat memperbaiki bug, sangat berguna untuk melihat apakah bug tersebut juga ada di model lain. Jika PR Anda menyatakan “diperbaiki dengan menggunakan pendekatan yang sama seperti (model lain)”, disertai tautan ke kode yang relevan, hal itu sangat membantu bagi para maintainer, karena memberi tahu kami bahwa perbaikan tersebut kemungkinan besar benar dan kompatibel dengan bagian lain dari codebase.
- Hindari PR “busywork”. Kami tidak memiliki waktu untuk perubahan gaya kecil atau perbaikan typo di komentar, dan kami tidak menerima perbaikan untuk “bug teoretis” yang ditemukan oleh analisis kode yang jarang, jika ada, menyebabkan masalah dalam praktik, kecuali jika dapat dieksploitasi oleh penyerang.
- Verifikasi tes secara lokal dan di CI. Sebelum membuka PR, jalankan
make fix-repodan gunakanutils/tests_fetcher.pyuntuk melihat daftar tes yang mencakup file yang telah Anda ubah di cabang PR Anda. Jalankan tes-tes tersebut secara lokal, dan pastikan mereka lulus sebelum Anda membuka PR. Setelah Anda membuka PR, silakan verifikasi bahwa CI berwarna hijau dan perbaiki semua masalah sebelum meminta siapa pun untuk meninjau! Hal ini sangat mengurangi spam notifikasi, yang menjaga para maintainer tetap waras.
Persiapan
Fork Transformers dengan tombol Fork di GitHub untuk mendapatkan salinan di akun Anda, lalu clone secara lokal.
git clone git@github.com:<your Github handle>/transformers.git cd transformersTambahkan repositori Transformers sebagai remote bernama
upstream.originmenunjuk ke fork Anda danupstreammenunjuk ke sumber kebenaran. Hal ini memungkinkan Anda untuk menyinkronkanmainlokal Anda sebelum mendorong keorigindan membuka PR.git remote add upstream https://github.com/huggingface/transformers.git git remote -v # origin git@github.com:<your Github handle>/transformers.git (fetch) # origin git@github.com:<your Github handle>/transformers.git (push) # upstream https://github.com/huggingface/transformers.git (fetch) # upstream https://github.com/huggingface/transformers.git (push)Jaga agar fork Anda tetap terkini dan mulai sebuah branch untuk bekerja. Anda juga dapat menyinkronkan fork Anda dari antarmuka GitHub dengan tombol Sync fork.
git checkout main && git pull upstream main && git push origin main git switch -c a-descriptive-name-for-my-branch
Instal pustaka dalam mode dapat diedit. Gunakan
[dev]untuk sebagian besar kontribusi karena mencakup alat pengembangan yang diperlukan untuk pemeriksaan gaya dan kualitas. Gunakan[torch,testing]untuk kontribusi model, atau[quality]untuk perubahan hanya pada dokumentasi dan perbaikan kecil ketika set dependensi pengembangan lengkap tidak diperlukan.pip install -e ".[dev]" # for model contributions pip install -e ".[torch,testing]" # for docs-only changes and small fixes pip install -e ".[quality]"
Windows
Pada Windows, kecuali Anda menggunakan WSL, konfigurasikan git untuk mengkonversi akhir baris CRLF menjadi LF.
git config core.autocrlf input
Salah satu cara untuk menjalankan perintah make di Windows adalah dengan MSYS2.
- Unduh MSYS2 (kami asumsikan terinstal di
C:\msys64). - Buka baris perintah
C:\msys64\msys2.exe(seharusnya tersedia dari menu Start). - Jalankan di shell:
pacman -Syudan instalmakedenganpacman -S make. - Tambahkan
C:\msys64\usr\binke variabel lingkungan PATH Anda.
Anda sekarang dapat menggunakan make dari terminal mana pun (PowerShell, cmd.exe, dll.).
Membuka isu
Gunakan template issue, dan pastikan issue tersebut belum dilaporkan sebelumnya (gunakan bilah pencarian di GitHub di bawah Issues). Laporan bug harus mengenai bug pada Transformers, bukan pada kode Anda sendiri, dan harus memengaruhi penggunaan nyata serta checkpoint nyata; “bug teoretis” yang ditemukan dengan membaca kode dan memerlukan konfigurasi yang sangat tidak standar untuk dipicu tidak akan ditriase kecuali itu adalah masalah keamanan. Sertakan skrip pendek yang mandiri dan mereproduksi bug pada rilis terbaru atau main, menggunakan checkpoint yang dipublikasikan atau konfigurasi default. Laporan bug tanpa reproduser yang dapat dijalankan tidak akan ditriase.
Jika Anda tidak yakin apakah bug tersebut ada di kode Anda atau di pustaka, tanyakan terlebih dahulu di forum atau di Discord. Hal ini membantu menjaga agar GitHub tetap berfokus pada masalah pustaka yang dapat ditindaklanjuti.
Menambahkan model baru
Menambahkan model ke Transformers membuatnya dapat dimuat, dihaluskan, atau dijalankan inferensinya oleh siapa pun. Sebelum memulai implementasi, identifikasi perbedaan antara arsitektur Anda dan model state-of-the-art terbaru yang sudah ada di Transformers. Jelaskan perbedaan tersebut dalam issue atau PR agar reviewer dapat dengan cepat memahami tantangan apa yang dibawa oleh model tersebut, bagian mana yang dapat menggunakan kembali pola yang ada, dan apa yang harus distandardisasi di antara model-model.
Ikuti panduan di bawah ini.
- Menambahkan model dengan Transformers modular — implementasikan model menggunakan file modular dan menghasilkan file modeling mandiri.
- Generate docstring secara otomatis — gunakan dekorator
@auto_docstringuntuk menghasilkan docstring yang konsisten tanpa boilerplate. - Testing — tulis dan jalankan pengujian model untuk memverifikasi kebenaran serta menjaga kontribusi tetap dapat dipelihara. Untuk model bahasa kausal, warisi dari pengujian LM kausal jika memungkinkan. Prioritaskan pengujian integrasi karena pengujian ini memverifikasi jalur prosesor, tokenizer, dan model secara utuh terhadap checkpoint asli.
- Aturan struktur model — periksa apakah file Anda lolos aturan struktur model statis yang diterapkan oleh
make typing.
Beberapa penambahan model memerlukan pekerjaan integrasi tambahan.
- Tambahkan komponen pemrosesan visi jika model Anda memerlukan input gambar atau video.
- Pemuatan bobot dinamis jika nama parameter checkpoint yang dipublikasikan tidak cocok dengan implementasi Transformers.
Linimasa penambahan model
Terdapat empat lini waktu untuk penambahan model, tergantung pada kontributor model dan permintaan komunitas terhadap suatu arsitektur.
Integrasi sejak hari pertama: membuat model tersedia di Transformers pada hari rilis dengan versi rilis baru. Kami menyediakan bantuan untuk mendukung fitur inti yang paling penting (kuantisasi, FlashAttention, KV-cache, dll.), meninjau draf awal, dan juga dapat menangani implementasi model tergantung pada tenggat waktu.
Kirim email ke transformers@huggingface.co beberapa minggu sebelumnya, terutama untuk arsitektur baru. Kami akan beriterasi dengan Anda pada fork privat hingga checkpoint dan rilis Anda siap.
Integrasi dalam minggu yang sama: model dengan permintaan tinggi biasanya tersedia dalam waktu satu minggu, bahkan jika pengembangnya tidak menghubungi.
Buka issue dengan template model baru untuk memintanya. Issue dengan lebih banyak aktivitas akan naik lebih cepat dalam antrean.
Integrasi pasca-rilis: model tanpa permintaan yang kuat, atau yang tidak memiliki bandwidth untuk kami tangani, akan dirilis setelah rilis upstream.
Kontributor eksternal dapat membuka PR untuk model baru secara langsung, dengan atau tanpa issue. Sebelum memulai, periksa issue “New model” yang terbuka dan PR yang terbuka untuk memastikan tidak ada yang sedang menambahkan model tersebut. Kami akan meninjau dan memandu Anda melalui prosesnya.
Rilis berbasis Hub: kirim model Anda langsung di Hub melalui dukungan remote-code Transformers, tanpa perlu PR upstream.
Model-model Hub-first yang populer sering kali diintegrasikan ke dalam Transformers kemudian, yang membuka akses ke dokumentasi kelas satu, pemeliharaan, dan optimasi. Hub-first adalah cara dengan hambatan terendah untuk menambahkan model. Namun, pendekatan ini bisa lebih rentan jika model memerlukan konversi bobot atau memiliki masalah kompatibilitas mundur lainnya.
Dokumentasi
Untuk referensi API yang dihasilkan dari file sumber, gunakan dekorator @auto_docstring ketika berlaku. Lihat README dokumentasi untuk detail lebih lanjut tentang cara mengedit dokumentasi dan sintaks yang kami gunakan.