Hugging Face’e ilk adım: Yanlış modeli çalıştırmadan önce üç kontrol

Hugging Face Transformers ile güvenli ve tekrarlanabilir bir ilk çıkarım için üç noktayı çalıştırmadan önce kontrol edin: Python ortamı ve paket sürümleri, model deposu ile revision’ı, uzak özel kod izni. Ardından sabitlenen modeli pipeline üzerinden CPU’da çalıştırabilirsiniz.

Bu kontroller yanlış depo veya değişmiş dosya seçimini görünür kılar ve Hub’daki özel Python kodunun kendiliğinden çalışmasını engeller. Çıktıda etiket ve güven puanı görmek ise yalnızca teknik akışın tamamlandığını gösterir; seçilen modelin Türkçe metinlerde doğru ya da amaca uygun olduğunu kanıtlamaz.

1. kontrol: Python ortamını ve paket sürümlerini ayırın

Önce komutun hangi Python yorumlayıcısı ve bağımlılıklarla çalışacağını sınırlandırın. Sistem Python’una doğrudan kurulum, başka projelerin Transformers veya PyTorch gereksinimleriyle çakışabilir. Projeye özel sanal ortam bu bağımlılıkları ayırır; çözümlenen sürümlerin kaydedilmesi de çalışan kurulumu daha sonra inceleyebilmenizi sağlar.

Resmî Transformers kurulum belgesi, uv ile sanal ortam oluşturmayı, PyTorch desteğini içeren paketi kurmayı ve kurulumu basit bir duygu analizi pipeline’ıyla doğrulamayı gösteriyor. Belge ayrıca kaynak koddan kurulumun kararlı sürüm yerine en yeni değişiklikleri getirdiğini ve her zaman kararlı olmayabileceğini belirtiyor.

1. Boş proje klasöründe uv venv .venv komutunu çalıştırın.
2. Linux veya macOS’ta source .venv/bin/activate, Windows PowerShell’de .venv\Scripts\Activate.ps1 komutuyla ortamı etkinleştirin.
3. uv pip install "transformers[torch]" komutuyla paket dizinindeki yayımlanmış sürümü kurun.
4. Kurulumdan sonra uv pip freeze > requirements.txt komutuyla çözümlenen paket sürümlerini kaydedin.

Buradaki sürüm kontrolü yalnızca Transformers numarasını not etmek değildir. Pipeline’ın davranışında PyTorch, tokenizer bileşenleri ve dolaylı bağımlılıklar da rol oynayabilir; bu nedenle tüm çözümün kaydı korunmalıdır. Kaynak kurulumuna gerçekten ihtiyaç yoksa hareketli Git ana dalını başlangıç noktası yapmayın.

2. kontrol: Depoyu ve revision’ı birlikte doğrulayın

model parametresi indirilecek depoyu, revision ise o deponun hangi hâlinin kullanılacağını belirler. Pipeline API’sinde revision verilmediğinde varsayılan değer main dalıdır. Depo daha sonra güncellenirse aynı Python kodu yeni dosyalara çözümleyebileceğinden, tekrarlanabilir bir denemede tam commit kimliği kullanmak daha belirgindir.

Örnekteki cardiffnlp/twitter-xlm-roberta-base-sentiment deposu çok dilli bir XLM-RoBERTa duygu analizi modeli sunuyor. Deponun f2f1202b1bdeb07342385c3f807f9c07cd8f5cf8 anlık görüntüsü model dosyalarını ve pipeline kullanımını birlikte gösteriyor. Model kartındaki ince ayar dilleri Arapça, İngilizce, Fransızca, Almanca, Hintçe, İtalyanca, İspanyolca ve Portekizce; Türkçe bu listede yer almıyor.

Bu yüzden model kimliğini ve tam revision değerini birlikte yazın, fakat sabitlemeyi kalite güvencesi sanmayın. Commit kimliği aynı depo anlık görüntüsünün yeniden istenmesini sağlar; yanlış göreve ait bir modeli, yetersiz model kartını veya hedef dil uyumsuzluğunu düzeltmez. Türkçe cümle bu yazıda yalnızca kurulumun çalıştığını sınayan bir duman testidir.

3. kontrol: Hub’daki özel kodu kapalı tutun

Bazı depolar Transformers’ın yerleşik sınıfları yerine kendi modelleme, yapılandırma, tokenizer veya pipeline koduna ihtiyaç duyabilir. Böyle bir depoda trust_remote_code=True kullanmak basit bir uyumluluk anahtarı değildir; Hub’daki Python kodunun yerel makinede yürütülmesine izin verir.

Resmî pipeline API belgesi, trust_remote_code seçeneğinin varsayılan olarak kapalı olduğunu ve yalnızca güvenilen, kodu okunmuş depolarda açılması gerektiğini belirtiyor. Aynı belge revision değerinin dal, etiket veya commit kimliği olabileceğini ve cihazın cpu olarak seçilebildiğini doğruluyor.

İlk denemede varsayımı görünür kılmak için trust_remote_code=False değerini açıkça geçin. Model bu ayarla yüklenmiyorsa değeri hemen True’ya çevirmeyin: durun; modelleme, yapılandırma, tokenizer ve pipeline dosyalarını inceleyin ve incelemeyi sabit bir revision üzerinde yapın. Bu örnek yerleşik Transformers sınıflarıyla çalışabildiği için uzak özel koda ihtiyaç duymaz.

Sabitlenmiş modeli CPU’da çalıştırın

Üç kontrolün ardından bir Python dosyasında önce from transformers import pipeline satırını kullanın. Ardından model_id = "cardiffnlp/twitter-xlm-roberta-base-sentiment" ve model_revision = "f2f1202b1bdeb07342385c3f807f9c07cd8f5cf8" değerlerini tanımlayın.

Pipeline’ı classifier = pipeline("sentiment-analysis", model=model_id, revision=model_revision, device="cpu", trust_remote_code=False) biçiminde oluşturun. Son olarak result = classifier("Bu kütüphaneyi kurmak beklediğimden kolaydı.") ve print(result) satırlarını çalıştırın.

İlk yükleme model ile tokenizer dosyalarını Hub’dan indirip yerel önbelleğe alır. Başarılı çağrı, model yapılandırmasındaki etiketi ve ona ait skoru içeren bir liste döndürür; etiketin yazımı seçilen modele bağlıdır. Burada doğrulanan sonuç, belirtilen depo revision’ının uzak özel kod çalıştırılmadan CPU’da çıkarım üretebilmesidir.

Çalışan dosyayla birlikte requirements.txt, model kimliği, tam revision ve test girdisini sürüm kontrolünde saklayın. Daha sıkı bir karşılaştırma için Python sürümünü, işletim sistemini ve PyTorch sürümünü de kaydedin. Modeli güncellerken eski commit kimliğinin üzerine sessizce yazmak yerine yeni revision’ı ayrı bir değişiklik olarak deneyin.

Bu teknik duman testini “Türkçe duygu analizi hazır” sonucu olarak yorumlamayın. Gerçek kullanım öncesinde hedef alanı ve Türkçe ifadeleri temsil eden etiketli bir doğrulama kümesiyle performansı, sınıflar arasındaki hataları ve kabul sınırlarını ayrıca değerlendirmek gerekir.