Transformers documentation
Çekme isteği denetimleri
Çekme isteği denetimleri
Bir pull request açtığınızda, Hugging Face CI, PR'ınızın birleştirilebilmesi için geçmesi gereken birkaç kontrolü çalıştırır.
- CI'yi düzeltme, kontrolleri geçmek için yerel olarak çalıştırılacak komutları listeler.
- Sonraki bölümler, kod kalitesi ve depo tutarlılığı gibi her bir denetimin neyi doğruladığını açıklar.
- Testler, hangi testlerin çalıştırıldığını, test kategorilerini ve yavaş testleri açıklar.
CI'yi Düzeltme
Çoğu durumda, en yaygın hata olan kod kalite kontrolünü geçmek için make style komutu yeterlidir.
make style
Depo tutarlılığı, kopyalar veya otomatik oluşturulan dosyalardaki hatalar için make fix-repo komutunu çalıştırın. Bu komut, stil, kopyalar, docstring'ler ve otomatik oluşturulan dosyaları tek bir geçişte düzeltir.
make fix-repo
Daha kapsamlı bir değişiklik için aşağıdaki üç komutluk dizi tüm kontrolleri kapsar. Bu yöntem daha ağır olsa da, kodu göndermeden önce her şeyi yakalar.
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 remainsmake typing, manuel olarak düzelttiğiniz tip hatalarını ve model yapısı ihlallerini yakalar. make check-repo, her şeyin hazır olduğunu doğrulayabilmeniz için son bir salt okunur geçiş yapar.
CI zaman zaman kararsız çalışabilir. Bir kontrol, değişikliklerinizle ilgisi olmayan bir nedenle başarısız olursa, yeniden çalıştırması için bir bakımcıya (maintainer) bildirim gönderin.
Kod kalitesi
Kod kalitesi denetimi biçimlendirme, içe aktarmalar, tip denetimi ve model yapısı kurallarını kapsar. Bu denetim make fix-repo ve make typing komutlarına karşılık gelir.
make style (make fix-repo içinde) Ruff lint ve biçimlendirme sorunlarını, __init__.py içe aktarma sıralamasını ve otomatik eşleme tutarlılığını otomatik olarak düzeltir.
make typing, ty ile tip denetimi yapar ve config sınıfı adlandırma kuralları ile forward() imzalarını kapsayan TRansFormers (TRF) kurallarını doğrular. Tip hataları ve TRF ihlalleri, belirli bir kural numarası bildirir ve manuel olarak düzeltilmelidir. Kurallar mlinter deposunda yer alır. Tüm TRF kurallarını görmek için python -m utils.mlinter --list-rules komutunu, belirli bir kuralın tam belgesini görüntülemek için ise python -m utils.mlinter --rule TRFXXX komutunu çalıştırın.
Bir TRF kuralı için istisna gerekiyorsa, bu seçeneklerden birini seçin (daha fazla ayrıntı için İhlalleri bastırma bölümüne bakın).
- İlgili kural için
utils/mlinter/rules.tomldosyasındakiallowlist_modelslistesine model adınızı ekleyin. Model dosyasının tamamının bir istisna gerektirmesi durumunda bunu kullanın. # trf-ignore: TRFXXXsatırını, işaretlenen yapıyla aynı satıra veya hemen üstündeki satıra ekleyin. Yalnızca tek bir işaretlenen yapının istisna gerektirdiği durumlarda bunu kullanın.
Depo tutarlılığı
Depo tutarlılık denetimi, make check-repo komutuna benzer; ancak ilk hata durumunda durur. Depoyu aşağıdaki kategoriler arasında iç tutarlılıkta tutar: herkese açık nesneler içe aktarılabilir kalır, kopyalanmış kod kaynaklarıyla senkronize kalır ve otomatik oluşturulan dosyalar (dummies, doctests, metadata) kodun güncel durumunu yansıtır. Yeni modeller için, her yeni model sınıfının auto-mappings içinde kayıtlı olduğunu da doğrular.
| Kategori | Ne doğruladığı | Otomatik olarak düzeltildi mi? |
|---|---|---|
| Başlangıç dosyaları | src/transformers/models/ içindeki __init__.py dosyaları güncel | make fix-repo |
| Kopyalar ve modüler | # Copied from blokları kaynaklarıyla eşleşiyor ve modüler olarak oluşturulan dosyalar güncel | make fix-repo |
| Docstring'ler ve belgeler | Argüman docstring'leri, fonksiyon imzalarıyla ve belgelerin içeriğiyle eşleşir | make fix-repo |
| Otomatik oluşturulan dosyalar | Dummies, pipeline tipleme, doctest listesi, meta veriler, bağımlılık tablosu | make fix-repo |
| Yapılandırma doğrulama | Config sınıflarının docstring'lerinde geçerli checkpoint'ler bulunur ve config öznitelikleri modelleme dosyasıyla eşleşir | El Kitabı |
| Değerlendirici ataması | Her model dizini ve gözden geçirme dosyasındaki her kural, bir gözden geçirmene ulaşır | El Kitabı |
Değerlendirici ataması
.github/scripts/codeowners_for_review_action, hangi dosyaların kim tarafından incelendiğini kaydeder.
Sahiplik, dosya bazında ve en özelden başlayarak çözümlenir.
| Nerede | Görünüşe göre | Bunun için kullanın |
|---|---|---|
| Model dosyası | # Reviewers: @login satırını modular_<model>.py veya modeling_<model>.py dosyasının başındaki yorum bloğuna ekleyin | modality sahibi dışında birine ihtiyaç duyan bir model. Modüler dönüştürücü, başlığı üretilen modeling dosyasına kopyalar, böylece etiket yeniden üretim sırasında korunur |
| Bir yol kuralı | .github/scripts/codeowners_for_review_action içindeki /src/transformers/<area>/ @login | model olmayan her şey |
| Modallite tablosu | Aynı dosyada @@modality/vision @login | docs/source/en/_toctree.yml dosyasının ilgili bölümünde yer alan doküman sayfasına sahip her model |
| Kapsayan | * @Rocketknight1 @ArthurZucker | diğer hiçbir şey iddia etmez |
Yeni bir model için herhangi bir yerde giriş yapılmasına gerek yoktur: _toctree.yml dosyasına eklenmesi, zaten dokümantasyon içeriği tablosu denetimi tarafından zorunlu tutulmaktadır ve bu sayede model bir modaliteye yerleştirilir; modalite tablosu da bundan sonra onu kapsar.
make check-repository-consistency, utils/check_reviewers.py dosyasını çalıştırır. Bu dosya; bir modelin yalnızca genel kapsayıcıya (catch-all) atandığında, bir kuralın artık hiçbir dosyayla eşleşmediğinde veya modalite tablosunun içerik tablosuyla uyuşmadığında hata verir. Çözümleyici (resolver), transformers kütüphanesinin bir bağımlılığı değildir; bunun yerine utils/checkers-requirements.txt dosyasında listelenir ve denetleyici çalıştırıcısı (checker runner), bir ortamda ilk çalıştırmasında bu dosyayı yükler. Yükleme yapılamazsa (örneğin çevrimdışıyken), denetim bunu raporlar ve sizi engellemek yerine geçer.
src/transformers/models dışında, sahibi olmayan yollar bir not olarak raporlanır; bunları listelemek için:
python utils/check_reviewers.py --strict
Testler
CI, PR'nizin ne değiştirdiğine bağlı olarak testlerin hedeflenmiş bir alt kümesini çalıştırır. CI, birbirine bağlı testleri yakalamak için pytest-random-order ile testleri hafifçe rastgele bir sırayla çalıştırır. Çalıştırma, başlangıçta rastgele tohumu (seed) yazdırır; böylece --random-order-seed=<seed> ile aynı sırayı yeniden oynatabilirsiniz.
Bir test GPU'da yerelde geçiyor ancak CI'da başarısız oluyorsa, hatanın CPU'da da yeniden üretilebilir olup olmadığını kontrol etmek için TRANSFORMERS_TEST_DEVICE="cpu" değerini ayarlayın.
TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -vAşağıdaki bölümler, test seçiminin nasıl çalıştığını, hangi işlerin çalıştırıldığını ve yavaş testlerin nasıl ele alınacağını açıklar.
Test seçimi
CI, her PR'de tam test paketini çalıştırmaz. CI, her PR'de @slow ile işaretlenmiş testleri atlar ve bir bakıcı, PR incelemeye alındığında GPU üzerinde bunları tetikler.
utils/tests_fetcher.py, değiştirilen dosyalarınızdan import bağımlılıklarını izleyerek etkilenen testleri belirler ve yalnızca bunları çalıştırır. Ortak yardımcılarla (utilities) çalıştığınızda diğer modellerdeki regresyonları da yakalar. Fetcher, hangi dosyaların değiştiğini ve hangi testlerin etkilendiğini yazdırır, ardından bu listeyi tests_torch_test_list.txt dosyasına yazar.
CI'nin çalıştırdığı işlemleri birebir yeniden oluşturmak için fetcher'ı kullanın.
python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)
modeling_utils.pyveyageneration/utils.pygibi çekirdek dosyaları değiştirmek, yalnızca etkilenen alt küme değil, tüm model testlerini tetikler.
Modeliniz için tüm testleri koşulsuz olarak da çalıştırabilirsiniz. Doğrudan çalışma, daha hızlı bir yerel sağlamlık kontrolü sağlar ancak paylaşılan kodda yaptığınız değişikliklerin diğer modellerde neden olabileceği regresyonları yakalayamaz.
pytest tests/models/my_model/ -v
Test işi kategorileri
Testler paralel CI işleri arasında bölünür ve her iş, dosyaları yol desenine göre seçer. Bir model PR'si için ilgili işler şunlardır:
tests_torch: modelleme testleri (tests/models/*/test_modeling_*.py)tests_tokenization: tokenizer testleri (tests/models/*/test_tokenization_*.py)tests_processors: işlemci ve özellik çıkarıcı testleri (tests/models/*/test_(processing|image_processing|feature_extractor)_*.py)tests_generate: üretim testleripipelines_torch: pipeline testleritests_training_ci: eğitim döngüsü testleritests_tensor_parallel_ci: tensor paralelliği testleritests_fsdp_ci: FSDP testleri
Yavaş testler
Düzenli CI çalıştırmaları, @slow ile işaretlenmiş testleri atlar. Bu testler gerçek checkpoint'leri indirir veya önemli ölçüde hesaplama gücü gerektirdiğinden GPU örneklerinde çalıştırılır ve PR'ınız inceleme altına alındığında bakım sorumluları tarafından tetiklenir.
Yavaş testler bir NVIDIA A10 üzerinde çalıştırılır ve sayısal sonuçlar CI donanımı ile yerel makineniz arasında hafif farklılıklar gösterebilir. Bakımcılar, yeni bir model eklenirken gerekirse testlerdeki bu değerleri genellikle ayarlar.
Yavaş testleri aşağıdaki komutla yerel olarak çalıştırın.
RUN_SLOW=1 python -m pytest tests/models/my_model/ -v
Belgeleme derlemesi
build_pr_documentation işi, belgeleri derler ve bir önizleme oluşturur. Bir bot, PR'ınızda bir önizleme bağlantısı paylaşır ve birleştirme işleminden önce bu denetimin geçmesi gerekir. Çoğu hata, toctree'de eksik bir girişten kaynaklanır. Belgeleri yerel olarak derlemek için docs klasöründeki README.md dosyasına bakın.
# Sözdiziminden kopyalandı
Yeni modeller için,
# Copied fromyerine her zaman modüler iş akışını (modular_*.py) tercih edin. Mümkün olduğunca# Copied fromkullanmaktan kaçının.
# Copied from mekanizması, kopyalanan kodun kaynağıyla senkron kalmasını sağlar. make fix-repo çalıştırıldığında, her bir # Copied from bloğunu kontrol eder ve orijinalle eşleşecek şekilde günceller; bu nedenle # Copied from bloğu içinde yapılan düzenlemeler üzerine yazılır. Bunun yerine kaynağı düzenleyin ve değişikliğin make fix-repo tarafından yayılmasını sağlayın.
# Copied from ifadesinin temel formları şunlardır.
# 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-casingwith model->newModel sözdizimi, kopyalama işleminden sonra metin ikamelerini uygular. Birden fazla ikameyi virgülle ayırın; bunlar soldan sağa doğru uygulanır. all-casing seçeneği, tüm büyük/küçük harf varyantlarını tek seferde değiştirir (Bert, bert, BERT sırasıyla MobileBert, mobilebert, MOBILEBERT olur).