Tekrarlanabilir model paketleme

Teori: tekrarlanabilirliğin iki seviyesi#

Bit düzeyinde aynı çıktıyı üretmek ile istatistiksel olarak eşdeğer bir model üretmek farklı hedeflerdir. Birincisi rastgelelik tohumunu, iş parçacığı sayısını, kayan nokta toplama sırasını ve donanım kütüphanesi sürümünü sabitlemeyi ister; çoğu ekip için maliyeti getirisini aşar. İkincisi genelde yeterlidir: aynı veri kesimi, aynı kod ve aynı bağımlılıklarla eğitim metriği kabul edilebilir bir bant içinde tekrar ediyorsa iş görür. Hangisini hedeflediğinizi baştan yazın, çünkü bu karar tüm hattın maliyetini belirler.

Veri ekseninde sürümleme çoğu zaman kopyalamak değil, sorguyu ve kesim noktasını sabitlemektir: hangi tablo, hangi filtre, hangi zaman aralığı, hangi kayıt sürümü. Sonradan güncellenebilen bir kaynaktan "son hali" okumak eğitimi tekrarlanamaz kılar, çünkü geçmişteki bir koşuyu tekrar ettiğinizde veri artık o veri değildir. Ekleme yapılan, geçmişi değiştirmeyen bir kaynak ile kesim tarihi birleşince kopyalamadan sürümleme mümkün olur.

Paketin içinde ne var#

Eğitim-servis sapması#

Üretimdeki en yaygın sessiz hata modelin kendisi değil, ön işlemenin iki kez yazılmış olmasıdır: bir kez eğitim not defterinde, bir kez servis kodunda. İki uygulama zamanla ayrışır ve ayrışma çoğu zaman çökme üretmez, yanlış tahmin üretir. Eksik değerin hangi ortalamayla dolduğu, kategori sıralaması, tarihin hangi saat diliminde yorumlandığı, bir oranın yüzde mi ondalık mı olduğu — hepsi bu sınıfta. Çözüm, dönüşümü tek bir çağrılabilir nesne olarak paketleyip aynı kodu her iki tarafta kullanmaktır.

{
  "model_kimligi": "churn-skoru",
  "surum": "2026.03.1",
  "olusturma": "2026-03-04T09:12:00Z",
  "veri": {
    "kaynak": "analitik.musteri_ozet",
    "kesim_tarihi": "2026-02-28",
    "filtre": "segment in ('kobi','kurumsal')",
    "anlik_goruntu_ozeti": "sha256:9f2c..."
  },
  "kod": {
    "depo": "ml-churn",
    "taahhut": "a1b2c3d",
    "giris": "egitim/calistir.py"
  },
  "ortam": {
    "kilit_dosyasi": "requirements.lock",
    "python": "3.12",
    "temel_imaj": "python:3.12-slim"
  },
  "hiperparametreler": { "derinlik": 6, "ogrenme_orani": 0.05, "tohum": 17 },
  "girdi_semasi": "semalar/churn-girdi-v2.json",
  "onceki_surum": "2026.02.2"
}

Sürüm numarası neyi anlatmalı#

Model sürümü artan bir sayaç değil, değişikliğin türünü bildiren bir işarettir. Pratik bir ayrım üç seviyedir: aynı kod ve aynı özelliklerle yalnızca daha yeni veriyle eğitim (tüketici için uyumlu), özellik seti veya ön işleme değişikliği (girdi sözleşmesi değişir, tüketici güncellenmeli), model ailesi veya çıktının anlamı değişikliği (eşik ve tüm entegrasyonlar yeniden ayarlanır). Sürüm şemanız bu üçünü ayırt edemiyorsa "yeni sürüm çıktı" cümlesi hiçbir şey söylemiyor demektir.

Karar akışı#

1. 1Sınırı çiz

   Ham girdiden tahmine kadar hangi dönüşümler paketin içinde? Dışarıda kalan her adımı ayrıca belgeleyin.

2. 2Girdi sözleşmesini yaz

   Sütun adı, tip, birim, izin verilen aralık ve bilinmeyen kategori davranışı; bunlar makine tarafından kontrol edilebilir olsun.

3. 3Künyeyi otomatikleştir

   Eğitim betiği bitişte künyeyi kendisi yazsın; elle doldurulması beklenen künye doldurulmaz.

4. 4Yükleme testini hatta koy

   Paketi temiz bir ortamda yükleyip sabit örneklerle tahmin alın ve beklenen çıktıyla karşılaştırın.

5. 5Geri dönüş yolunu tanımla

   Önceki sürüm hangi komutla canlıya döner, ne kadar sürede ve kimin onayıyla?

Sık yapılan hata#

Not defterinde eğitilip elle kaydedilen model, aylar sonra çoğu ekipte yeniden üretilemez: hücreler farklı sırada koşmuştur, ara değişkenler yalnızca bellekte yaşamıştır, kullanılan dosya birinin masaüstündedir. İkinci yaygın hata bağımlılıkları sürüm sınırı olmadan yazmaktır; aynı kurulum komutu altı ay sonra farklı sürümler getirir ve ağırlık dosyası ya yüklenmez ya sessizce başka davranır. Üçüncüsü, ön işlemeyi "küçük bir kod parçası" sayıp paketin dışında bırakmaktır.