🤗 Transformers'a katkıda bulunun

Katkı kuralları

PR açmanın iki yolu vardır: katkıya açık bir sorunu düzeltmek veya kendi kanıtını taşıyan bağımsız bir PR açmak. Yeni modeller de bağımsız bir PR ile eklenebilir, bkz. Yeni bir model ekleme. Hugging Face personeli, bakımcılar ve bazı uzun süredir katkıda bulunanlar bu kurallardan muaftır.

Bir sorunu düzeltme. PR açıklamasında Fixes #123 gibi bir kapatma anahtar kelimesiyle sorunu ilişkilendirin. Üzerinde çalışabileceğiniz konular:

• Bir bakıcının triaged etiketini eklediği, sizin açtığınız bir sorun
• contributions-welcome etiketli bir sorun
• New model etiketli bir sorun, bkz. Yeni bir model ekleme

Diğer kişilerin sorunları, bir bakıcı aksi takdirde belirtmedikçe PR’lere açık değildir. Üzerinde çalışamayacağınız bir soruna bağlantı veren PR’ler kapatılacaktır.

Bir sorunun uygun koşulları sağladığından emin olduğunuzda, üzerinde çalışmaya başlamadan önce izin almanıza gerek yoktur ve sorunları kişilere atamayız. “Bunu ben yapabilir miyim?” veya “Bunu bana atar mısınız?” gibi yorumlar yalnızca gürültü oluşturur, bu yüzden bunları atlayın ve PR’ınızı açın. Bir sorun için açılan ilk PR önceliklidir.

contributions-welcome veya New model etiketli bir sorun üzerinde çalışmadan önce, bu sorun için birinin zaten PR açıp açmadığını kontrol edin. Açıldıysa, başka bir PR açmayın. Hatalar fark ederseniz, bunları mevcut PR üzerinde öneri olarak bırakın. Yalnızca mevcut PR temelden hatalıysa veya güncelliğini yitirdiyse (yazarı, inceleme yorumlarına yanıt vermediyse veya iki hafta boyunca değişiklik göndermediyse) rakip bir PR açın. Bir yönetici incelemesi bekleyen bir PR güncelliğini yitirmiş sayılmaz. Her durumda, kendi PR'ınızı açmadan önce sorunda nedenini açıklayın.

Bağımsız PR'ler. Henüz kimse sorunu raporlamadıysa, bir issue olmadan PR açabilirsiniz. Bağımsız PR'ler, hata düzeltmesi, performans iyileştirmesi veya belgelerdeki bozuk bir örneğin düzeltilmesi gibi gerçek bir etkiye sahip kısa değişiklikler içindir. PR açıklaması, bir issue'da olduğu gibi aynı kanıtları içermelidir:

• bir hata için, main üzerinde başarısız olup düzeltmenizle geçen, yayımlanmış bir kontrol noktası, varsayılan bir yapılandırma veya belgelenmiş bir iş akışı kullanan kısa bir betik
• performans iyileştirmesi için, yayımlanmış bir checkpoint veya varsayılan yapılandırma gibi gerçekçi bir iş yükünde, çalıştırdığınız donanımda, önce ve sonra sayıları. Sıcak yolda olmayan bir fonksiyonun daha hızlı bir mikro-benchmark’u sayılmaz.

Sorun için zaten bir issue varsa, PR'ınız bu issue üzerinden işlenir; issue'ı bağlayıp bağlamamanız fark etmez. Mevcut bir issue'ı çözen veya kanıt içermeyen bağımsız PR'lar kapatılır. Bu gereksinimler yeni modeller için geçerli değildir.

Önce bir sorun (issue) açılması gereken değişiklikler. Doğruluğu veya performansı etkilemeyen mekanik temizlikler ile belgelerde yazım hatalarına veya ifadelere yönelik toplu düzeltmeler, bir PR açılmadan önce bir sorun gerektirir. Değişikliği, nasıl yapılacağını ve kaç dosyayı etkilediğini önerin. Tek bir yazım hatası düzeltmesi, her iki yolda da bir PR için çok küçüktür.

Diğer kişilerin PR’larını gözden geçirme. Topluluk, bize yeni bir şey söylediğinde gelen yorumlara memnuniyetle bakılır, ancak yöneticiler bir PR’daki her yorumu okur ve kendi gözden geçirme araçlarımızı zaten çalıştırır. Açmadığınız bir PR’a yorum yapmadan önce, söyleyecek belirli bir şeyiniz olduğundan emin olun:

• Bir sorun bulduysanız veya somut bir değişiklik önermek istiyorsanız, ilgili satırlara, ideal olarak yazarın doğrudan uygulayabileceği bir GitHub önerisi olarak, satır içi bir yorum bırakın. Bir hata bildiriyorsanız, bir yeniden üretici (reproducer) yardımcı olur.
• Eğer PR'inin düzelttiği sorunu siz raporladıysanız, durumunuzun düzeltilip düzeltilmediğine dair kısa bir not gerçekten çok faydalıdır.
• Lütfen genel özetler veya “bunu test ettim ve çalışıyor” raporları paylaşmayın. Bakıcı olmayan kişilerden gelen onaylar, bir PR’nin birleştirilip birleştirilmeyeceğini etkilemez ve PR’i yeniden ifade eden uzun bir yorum, sonucu değiştirmeden bize zaman kaybettirir.

Kodunuzu nasıl yazacağınız size kalmıştır, ancak gönderdiğiniz her şeyden siz sorumlusunuz ve düşük kaliteli sorun veya PR'lar açan hesapları engelleme hakkımız saklıdır. Lütfen davranış kurallarımızı da saygıyla karşılayın.

Kurulum

1. GitHub'daki Fork düğmesini kullanarak Transformers projesinin bir kopyasını hesabınıza alın ve ardından yerel olarak klonlayın.

   Kopyalandı

   git clone git@github.com:<your Github handle>/transformers.git
   cd transformers

2. upstream adıyla Transformers deposunu bir uzak (remote) olarak ekleyin. origin sizin fork'unuza, upstream ise doğruluk kaynağına (source of truth) işaret eder. Bu sayede origin'e göndermeden ve bir PR açmadan önce yerel main dalınızı senkronize edebilirsiniz.

   Kopyalandı

   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)

3. Fork'unuzu güncel tutun ve üzerinde çalışmak için bir dal başlatın. Ayrıca fork'unuzu GitHub arayüzünden Sync fork düğmesiyle senkronize edebilirsiniz.

   Kopyalandı

   git checkout main && git pull upstream main && git push origin main
   git switch -c a-descriptive-name-for-my-branch

4. Kütüphaneyi düzenlenebilir modda yükleyin. Çoğu katkı için [dev] kullanın çünkü stil ve kalite denetimleri için gereken geliştirme araçlarını içerir. Model katkıları için [torch,testing] kullanın veya tam geliştirme bağımlılık setine gerek duyulmayan yalnızca doküman değişiklikleri ve küçük düzeltmeler için [quality] kullanın.

   Kopyalandı

   pip install -e ".[dev]"
   
   # for model contributions
   pip install -e ".[torch,testing]"
   
   # for docs-only changes and small fixes
   pip install -e ".[quality]"

Windows

Windows'ta WSL kullanmıyorsanız, git'i CRLF satır sonlarını LF'ye dönüştürmeye yapılandırın.

git config core.autocrlf input

Windows'ta make komutunu çalıştırmak için bir yol MSYS2 kullanmaktır.

1. MSYS2'yi indirin (kurulumun C:\msys64 dizinine yapıldığını varsayıyoruz).
2. Komut satırını C:\msys64\msys2.exe olarak açın (Başlat menüsünden erişilebilir olmalıdır).
3. Kabukta çalıştırın: pacman -Syu ve make paketini pacman -S make ile yükleyin.
4. PATH ortam değişkeninize C:\msys64\usr\bin ekleyin.

Artık make komutunu herhangi bir terminalden (PowerShell, cmd.exe vb.) kullanabilirsiniz.

Sorunlar açma

Sorun şablonlarını kullanın ve sorunun daha önce rapor edilmediğinden emin olun (GitHub'da Issues altında arama çubuğunu kullanın). Bir hata raporu, kendi kodunuzdaki değil Transformers'taki bir hatayla ilgili olmalı ve gerçek kullanım ile gerçek checkpoint'leri etkilemelidir; kodu okuyarak bulunan ve tetiklenmesi için çok standart dışı bir yapılandırma gerektiren “teorik hatalar”, güvenlik sorunu olmadıkça triyaj edilmeyecektir. Hatanın en son sürümde veya main dalında yeniden üretildiğini gösteren kısa, kendi içinde tutarlı bir betik ekleyin; bunu yayımlanmış bir checkpoint veya varsayılan yapılandırma kullanarak yapın. Çalıştırılabilir bir yeniden üretici içermeyen hata raporları triyaj edilmeyecektir.

Hatanın kodunuzda mı yoksa kütüphanede mi olduğunu bilmiyorsanız, lütfen önce forumda veya Discord’da sorun. Bu, GitHub’ın eyleme geçirilebilir kütüphane sorunlarına odaklanmasını sağlar.

Yeni bir model ekleme

Transformers'a bir model eklemek, herkesin bu modeli yükleyip ince ayar yapmasını veya çıkarım (inference) çalıştırmasını mümkün kılar. Uygulamaya başlamadan önce, mimariniz ile Transformers'ta zaten bulunan ve güncel en iyi (state-of-the-art) modeller arasındaki farkları belirleyin. Bu farkları, inceleyicilerin (reviewer) modelin getirdiği zorlukları, mevcut kalıpların hangi kısımlarının yeniden kullanılabilir olduğunu ve modeller arasında standartlaştırılması gereken unsurları hızla anlayabilmesi için issue veya PR'da açıklayın.

Aşağıdaki kılavuzları izleyin.

1. Modüler Transformers ile bir model ekleyin — modeli modüler dosya kullanarak uygulayın ve bağımsız modelleme dosyalarını oluşturun.
2. Docstring'leri otomatik oluştur — boilerplate olmadan tutarlı docstring'ler oluşturmak için @auto_docstring dekoratörünü kullanın.
3. Test — doğruluğu doğrulamak ve katkıyı sürdürülebilir tutmak için model testleri yazın ve çalıştırın. Neden-sonuç dil modelleri için mümkün olduğunca neden-sonuç LM testcisinden devralın. Gerçek kontrol noktalarına karşı tam işlemci, belirteçleyici ve model yolunu doğruladıkları için entegrasyon testlerine öncelik verin.
4. Model yapı kuralları — make typing tarafından uygulanan statik model yapı kurallarına dosyalarınızın uyup uymadığını kontrol edin.

Bazı model eklemeleri ek entegrasyon gerektirir.

• Modeliniz görüntü veya video girdileri gerektiriyorsa görüntü işleme bileşenlerini ekleyin.
• Yayınlanan kontrol noktası parametre adları Transformers uygulamasıyla eşleşmediğinde dinamik ağırlık yükleme.

Model ekleme zaman çizelgesi

Bir mimari için model katkıda bulunan kişiye ve topluluk talebine bağlı olarak model eklemeleri için dört zaman çizelgesi vardır.

• Day-0 entegrasyonu: Modeli, yeni bir sürüm yayınıyla birlikte Transformers'ta yayın gününde kullanılabilir hale getirin. En önemli çekirdek özelliklerin (kuantizasyon, FlashAttention, KV-cache vb.) desteklenmesine yardımcı oluyoruz, erken taslakları inceliyor ve zaman çizelgesine bağlı olarak model uygulamasını da üstlenebiliyoruz.

  Birkaç hafta öncesinden transformers@huggingface.co adresine e-posta gönderin, özellikle de yeni mimariler için. Kontrol noktanız ve yayınınız hazır olana kadar sizinle özel bir çatallama üzerinde çalışacağız.

• Aynı hafta entegrasyonu: Yüksek talep gören modeller, yazar iletşime geçmese bile genellikle bir hafta içinde yayına alınır.

  Bir tane talep etmek için yeni model şablonu ile bir sorun (issue) açın. Daha fazla aktiviteye sahip olan sorunlar kuyrukta daha hızlı ilerler.

• Yayın sonrası entegrasyon: güçlü bir talebi olmayan veya üzerinde çalışacak kapasitemizin bulunmadığı modeller, upstream yayınından sonra eklenir.

  Harici katkıda bulunanlar, bir sorun açsın ya da açmasın, yeni bir model için doğrudan bir PR açabilir. Başlamadan önce, kimsenin zaten eklemeye çalışmadığından emin olmak için açık “New model” sorunlarını ve açık PR’ları kontrol edin. İnceleyip size rehberlik edeceğiz.

• Hub öncelikli yayın: Modelinizi, upstream PR gerektirmeden, doğrudan Hub üzerinde Transformers'ın remote-code desteğiyle yayınlayın.

  Popüler Hub-first modeller genellikle daha sonra Transformers'a entegre edilir; bu da birinci sınıf dokümantasyon, bakım ve optimizasyonun kapısını açar. Hub-first, bir model eklemenin en düşük sürtünmeli yoludur. Ancak, bir modelin ağırlık dönüşümü veya diğer geriye dönük uyumluluk sorunları gerektirmesi durumunda daha kırılgan olabilir.

Belgeler

Kaynak dosyalardan üretilen API referansı için, uygun olduğunda @auto_docstring dekoratörünü kullanın. Belgeleri düzenleme ve kullandığımız sözdizimi hakkında daha fazla ayrıntı için belgelerin README dosyasına bakın.