Periksa pull request

Saat Anda membuka pull request, CI Hugging Face menjalankan beberapa pemeriksaan yang harus lulus agar PR Anda dapat digabungkan.

• Memperbaiki CI mencantumkan perintah yang harus dijalankan secara lokal untuk lulus pemeriksaan.
• Bagian setelahnya menjelaskan apa yang divalidasi oleh setiap pemeriksaan, seperti kualitas kode dan konsistensi repositori.
• Uji menjelaskan uji yang dijalankan, kategori uji, dan uji lambat.

Memperbaiki CI

Dalam kebanyakan kasus, make style sudah cukup untuk melewati pemeriksaan kualitas kode, yang merupakan kegagalan paling umum.

make style

Untuk kegagalan pada konsistensi repositori, salinan, atau file yang dibuat otomatis, jalankan make fix-repo. Perintah ini memperbaiki gaya, salinan, docstring, dan file yang dibuat otomatis dalam satu langkah.

make fix-repo

Untuk perubahan yang lebih besar, urutan tiga perintah di bawah ini mencakup semua pemeriksaan. Proses ini lebih berat, tetapi menangkap semua masalah sebelum Anda melakukan push.

make fix-repo   # auto-fix everything that can be auto-fixed
make typing     # check types and model structure, fix any errors manually
make check-repo # verify all checks pass, fix anything that remains

make typing mendeteksi kesalahan tipe dan pelanggaran struktur model yang Anda perbaiki secara manual. make check-repo melakukan pemeriksaan akhir yang hanya-baca sehingga Anda dapat memastikan semuanya siap.

CI kadang-kadang tidak stabil. Jika sebuah pemeriksaan gagal karena hal yang tidak terkait dengan perubahan Anda, hubungi maintainer untuk menjalankannya ulang.

Kualitas kode

Pemeriksaan kualitas kode mencakup format, impor, pemeriksaan tipe, dan aturan struktur model. Ini sesuai dengan make fix-repo dan make typing.

make style (termasuk dalam make fix-repo) memperbaiki secara otomatis linting dan formatting Ruff, urutan impor __init__.py, serta konsistensi auto-mapping.

make typing melakukan pemeriksaan tipe dengan ty dan memvalidasi aturan TRansFormers (TRF), yang mencakup konvensi penamaan kelas config dan tanda tangan forward(). Kesalahan tipe dan pelanggaran TRF melaporkan nomor aturan tertentu dan harus diperbaiki secara manual. Aturan-aturan ini terdapat di repositori mlinter. Jalankan python -m utils.mlinter --list-rules untuk melihat semua aturan TRF, atau python -m utils.mlinter --rule TRFXXX untuk melihat dokumentasi lengkap untuk aturan tertentu.

Jika aturan TRF memerlukan pengecualian, pilih salah satu opsi berikut (lihat Menekan pelanggaran untuk detail lebih lanjut).

• Tambahkan nama model Anda ke daftar allowlist_models untuk aturan yang relevan di utils/mlinter/rules.toml. Gunakan ini ketika seluruh file model memerlukan pengecualian.
• Tambahkan # trf-ignore: TRFXXX pada baris yang sama dengan konstruk yang ditandai, atau pada baris tepat di atasnya. Gunakan ini ketika hanya satu konstruk yang ditandai yang memerlukan pengecualian.

Konsistensi repository

Pemeriksaan konsistensi repositori mirip dengan make check-repo, kecuali pemeriksaan ini berhenti pada kegagalan pertama. Pemeriksaan ini menjaga konsistensi internal repositori di antara kategori berikut: objek publik tetap dapat diimpor, kode yang disalin tetap sinkron dengan sumbernya, dan file yang dibuat otomatis (dummies, doctests, metadata) mencerminkan kondisi terkini kode. Untuk model baru, pemeriksaan ini juga memverifikasi bahwa setiap kelas model baru terdaftar di auto-mappings.

Penugasan peninjau

Ketika pull request ditandai siap untuk ditinjau, workflow Assign PR Reviewers meminta hingga dua peninjau, diurutkan berdasarkan jumlah baris yang diubah pull request tersebut pada file yang mereka miliki. Pull request draft tidak mendapat peninjau sampai keluar dari status draft. Workflow itu sendiri berada di huggingface/transformers-ci dan repositori ini memanggilnya; yang tetap ada di sini adalah data kepemilikan yang dibaca oleh workflow tersebut.

Kepemilikan ditentukan per file, dengan prioritas pada yang paling spesifik.

Model baru tidak memerlukan entri di mana pun: menambahkan halaman dokumentasinya ke _toctree.yml, yang sudah diwajibkan oleh pemeriksaan daftar isi dokumentasi, akan menempatkannya dalam sebuah modalitas, dan tabel modalitas akan mencakupnya dari sana.

Permintaan review hanya dapat diajukan dari kolaborator repositori. Workflow meminta setiap reviewer dalam panggilan terpisah dan melewatkan siapa pun yang tidak dapat diminta, sehingga entri yang menyebut seseorang yang telah keluar hanya mengorbankan satu reviewer, bukan semuanya, dan setiap lewati dilaporkan sebagai peringatan pada eksekusi workflow.

Sebuah pull request tidak dapat mengalihkan review miliknya sendiri. .github/scripts/codeowners_for_review_action dibaca dari base branch, bukan dari head pull request, dan gerbang keamanan CI PR memblokir pull request yang bukan berasal dari kolaborator untuk menyentuh apa pun di luar src/, tests/, docs/, dan utils/ — itulah mengapa file tersebut berada di lokasi tersebut. Tag # Reviewers: dibaca dari head, karena model baru tiba bersamanya, sehingga setiap login yang disebutkan tetap melewati pemeriksaan kolaborator sebelum siapa pun diminta.

make check-repository-consistency menjalankan utils/check_reviewers.py, yang akan gagal ketika sebuah model tidak memiliki penanggung jawab selain catch-all, ketika sebuah aturan tidak lagi cocok dengan file mana pun, atau ketika tabel modalitas tidak sesuai dengan daftar isi. Resolver-nya dibagikan dengan workflow penugasan, sehingga keduanya tidak bisa berbeda. Resolver tersebut bukan dependensi dari transformers; ia terdaftar di utils/checkers-requirements.txt, yang diinstal oleh runner checker pada eksekusi pertamanya di suatu environment. Jika instalasi tidak dapat dilakukan — misalnya, saat offline — check akan melaporkannya dan tetap lolos, alih-alih menghalangi Anda. Path di luar src/transformers/models yang tidak memiliki pemilik akan dilaporkan sebagai catatan; daftarkan dengan:

python utils/check_reviewers.py --strict

Uji

CI menjalankan subset tes yang ditargetkan berdasarkan perubahan pada PR Anda. CI menjalankan tes dalam urutan yang sedikit diacak menggunakan pytest-random-order untuk menangkap tes yang saling terkait. Eksekusi mencetak benang acak (random seed) di awal sehingga Anda dapat memutar ulang urutan yang sama dengan --random-order-seed=<seed>.

Jika sebuah test lulus secara lokal di GPU tetapi gagal di CI, setel TRANSFORMERS_TEST_DEVICE="cpu" untuk memeriksa apakah Anda dapat mereproduksi kegagalan tersebut di CPU.

TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -v

Bagian-bagian di bawah ini menjelaskan cara kerja pemilihan tes, job mana yang dijalankan, dan cara menangani tes yang lambat.

Pemilihan pengujian

CI tidak menjalankan seluruh rangkaian pengujian pada setiap PR. CI melewati pengujian yang diberi dekorasi @slow pada setiap PR, dan seorang maintainer akan menjalankannya di GPU setelah PR tersebut masuk tahap review.

utils/tests_fetcher.py menelusuri dependensi impor dari file yang Anda ubah untuk mengidentifikasi test yang terdampak, lalu hanya menjalankan test tersebut. Alat ini juga menangkap regresi pada model lain ketika Anda mengubah utilitas bersama. Fetcher menampilkan file mana yang berubah dan test mana yang terdampak, kemudian menulis daftar tersebut ke tests_torch_test_list.txt.

Gunakan fetcher untuk mereplikasi persis apa yang dijalankan oleh CI.

python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)

Mengubah file inti seperti modeling_utils.py atau generation/utils.py memicu semua pengujian model, bukan hanya subset yang terpengaruh.

Anda juga dapat menjalankan semua tes untuk model Anda secara tidak bersyarat. Eksekusi langsung adalah pemeriksaan kesehatan lokal yang lebih cepat, tetapi tidak akan mendeteksi regresi pada model lain yang disebabkan oleh kode bersama yang Anda ubah.

pytest tests/models/my_model/ -v

Kategori pekerjaan pengujian

Tes dibagi ke dalam beberapa pekerjaan CI paralel, dan setiap pekerjaan mengambil file berdasarkan pola path. Pekerjaan yang relevan untuk PR model adalah:

• tests_torch: pengujian pemodelan (tests/models/*/test_modeling_*.py)
• tests_tokenization: pengujian tokenizer (tests/models/*/test_tokenization_*.py)
• tests_processors: pengujian processor dan feature extractor (tests/models/*/test_(processing|image_processing|feature_extractor)_*.py)
• tests_generate: pengujian generasi
• pipelines_torch: pengujian pipeline
• tests_training_ci: pengujian loop pelatihan
• tests_tensor_parallel_ci: tes paralel tensor
• tests_fsdp_ci: Uji FSDP

Tes lambat

Jalankan CI reguler akan melewati tes yang diberi dekorasi @slow. Tes-tes ini mengunduh checkpoint asli atau membutuhkan komputasi yang signifikan, sehingga dijalankan pada instance GPU, dan maintainer akan menjalankannya sekali PR Anda sedang dalam proses review.

Tes lambat dijalankan pada NVIDIA A10, dan hasil numerik dapat sedikit bervariasi antara perangkat keras CI dan mesin lokal Anda. Maintainer biasanya menyesuaikan nilai-nilai tersebut pada tes jika diperlukan saat menambahkan model baru.

Jalankan tes lambat secara lokal dengan perintah di bawah ini.

RUN_SLOW=1 python -m pytest tests/models/my_model/ -v

Build dokumentasi

Job build_pr_documentation membangun dan menghasilkan pratinjau dokumentasi. Bot akan memposting tautan pratinjau di PR Anda, dan pemeriksaan ini harus lulus sebelum penggabungan. Sebagian besar kegagalan disebabkan oleh entri yang hilang di toctree. Untuk membangun dokumentasi secara lokal, lihat README.md di folder docs.

# Disalin dari sintaks

Untuk model baru, selalu utamakan alur kerja modular (modular_*.py) daripada # Copied from. Hindari # Copied from sebisa mungkin.

Mekanisme # Copied from menjaga agar kode yang disalin tetap sinkron dengan sumbernya. Saat make fix-repo dijalankan, mekanisme ini memeriksa setiap blok # Copied from dan memperbaruinya agar sesuai dengan kode asli, sehingga perubahan di dalam blok # Copied from akan ditimpa. Ubahlah kode sumbernya dan biarkan make fix-repo menyebarkan perubahan tersebut.

Bentuk dasar dari # Copied from mencakup hal-hal berikut.

# Copied from transformers.models.bert.modeling_bert.BertSelfOutput

# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert->Roberta

# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert->MobileBert all-casing

Sintaks with model->newModel menerapkan penggantian string setelah penyalinan. Pisahkan beberapa penggantian dengan koma, yang diterapkan dari kiri ke kanan. Opsi all-casing mengganti setiap varian casing sekaligus (Bert, bert, BERT menjadi MobileBert, mobilebert, MOBILEBERT).