Regression gate yazı-tura mı atıyor? Küçük golden set istatistiği
Belgelerin önerdiği sabit eşikli PASS/FAIL gate'i küçük golden setlerde ne kadar güvenilir? Yanlış alarm ve kaçırma oranlarını ölç, eşleştirilmiş (paired) istatistik gate'i ve "kaç soru yeter?" hesaplayıcısını üret. Bu projenin stats.py modülü diğer 19 projenin ortak istatistik araç setidir.
Araştırma sorusu50–300 soruluk sette sabit eşik gate'i gerçek sistem kalitesini ne sıklıkla yanlış sınıflar ve gerçek regresyonları ne sıklıkla kaçırır?
HesapYalnız CPU. LLM, GPU, ücretli API yok.
HF çıktılarıDataset bunyamineymen/rag-gate-stats-results · Static Space bunyamineymen/rag-gate-stats
BağımlılıkYok (ilk proje). Çıktısı olan stats.py 02–20 tarafından kopyalanır.
Okuma anahtarı. Mor KAYNAK kutuları iki HTML belgesinden alıntı veya özettir (G = _RAG_Testing_Best_Practices.html, T = RAG_43_Test_Best_Practices.html). Geri kalan her şey bu spec'in önerisidir. Lisans satırlarında ✓ = 2026-10-14'te kaynağından doğrulandı, ⚠ = uygulama başlamadan doğrulanacak. Bu belgede hiçbir deney sonucu yoktur; sayısal hedefler ön-kayıtlı tahmindir.
G§11 Regression Gate:Recall@5 >= 0.92, Faithfulness >= 0.95, Accuracy >= 0.90, P95 Latency <= 2.5s → PASS / FAIL. "Embedding modeli, chunk size, prompt, reranker, LLM veya vector DB değiştiğinde aynı test suite tekrar çalışmalı." T "Örnek Production Gate": Recall@5 ≥ 0.90, Faithfulness ≥ 0.95, Answer Accuracy ≥ 0.90, Abstention Accuracy ≥ 0.95, Unauthorized Retrieval 0, P95 "Proje SLA'sına göre". "Eşikler örnektir; domain ve risk seviyesine göre kalibre edilmelidir." T43: "P50/P95/P99, concurrency, tokens, cost/query takip et." G§1: "Bu dataset'i CI/CD içinde çalışan kalıcı bir RAG regression suite olarak kullan."
Belgelerdeki boşluk (editör notu). İki belgedeki Recall@5 eşiği farklı (0.92 ve 0.90). Hiçbiri golden set büyüklüğü, güven aralığı, tekrar ölçüm ya da eşiğin neye göre kalibre edileceğini tanımlamıyor. Bu proje bu boşluğu ölçer.
1. Amaç
Sabit eşik gate'inin (G1) karar hata oranını golden set büyüklüğü (n) ve eşiğe uzaklık fonksiyonu olarak ölçmek.
Sistem eşiğin rahatça üstündeyken gerçek regresyonların mutlak eşikten geçip gitmesini ("headroom maskeleme") nicelemek.
Soru bazında eşleştirilmiş non-inferiority gate'inin (G3) aynı yanlış alarm seviyesinde daha yüksek tespit gücü verip vermediğini sınamak.
ANN (HNSW) yeniden inşası ve latency ölçüm gürültüsünün gate kararlarına etkisini ölçmek.
Yeniden kullanılabilir çıktılar: stats.py (bootstrap CI, permütasyon testi, quantile CI, güç/MDE) ve "kaç soru yeter?" hesaplayıcısı.
Sistemler: BM25 + 3 küçük dense model; exact (FAISS Flat) ve HNSW (hnswlib)
No-op değişiklikler, doğal ve kontrollü regresyonlar
3 gate türü + latency gate'i
Generation metrikleri (faithfulness, accuracy): LLM gerektirir. Aynı gate yöntemi 11–20'de uygulanır.
Yük / concurrency testleri: ayrı bir altyapı konusu.
Maliyet/sorgu: CPU-only kurulumda anlamlı değil.
Gerçek CI entegrasyonu: yalnız örnek workflow dosyası verilir.
Embedding modellerinin kalite sıralaması: bu projenin iddiası değil (bkz. 03).
3. Hipotezler (ön-kayıt)
Bağlayıcı metin prereg.md'dir: ilk tam koşudan önce yazıldı ve SHA-256 özeti her koşuda results/env.json'a kaydedilir. Aşağıdaki tablo onun özetidir. Sayısal eşikler tahmindir, sonuç değildir.
v0.2 değişikliği (koşudan önce): H3 yeniden tanımlandı. G2 hata oranını kontrol etmediği için "aynı α'da G3 ile G2" karşılaştırması tanımsızdı. H3 artık eşleştirmenin etkisini ölçüyor: paired G3 ile unpaired G3u. G2 betimsel raporlanıyor. Diğer sapmalar prereg.md §4'te.
#
Hipotez
Gerekçe / tahmin kaynağı
Destek ölçütü
H1
n ≤ 100 iken, popülasyon metriği eşiğe ±0.02 yakın olduğunda mutlak eşik gate'inin (G1) karar hata oranı yüksektir.
Soru başına Recall@5 çoğunlukla 0/1'e yakın; n=100'de standart hata birkaç puan, eşiğe 0.02 uzaklık bunun yarısı kadar.
n=100, |d|=0.02 (iki işaret), dört sistem havuzlanmış G1 hata oranının Wilson %95 alt sınırı ≥ 0.15; en az 2/3 veri setinde.
H2
Baseline eşiğin üstündeyken G1, gerçek regresyonları kaçırır (headroom maskeleme).
G1 değişimi değil, mutlak seviyeyi kontrol eder.
bge → ctl03 (Δ = −0.03), eşik = baseline − 0.05, n=100: G1 PASS oranı ≥ 0.50 ve golden set başına (G1 PASS − G3 PASS, m=0.02) farkının %95 CI alt sınırı > 0; en az 2/3 veri setinde.
H3
Aynı α'da eşleştirme (G3), eşleştirmesiz bootstrap'a (G3u) göre kabul edilebilir değişikliklerde yanlış FAIL'i azaltır.
Aynı sorularda iki sistemin skorları pozitif koreledir; eşleştirme farkın varyansını düşürür.
No-op ailesi (HNSW ekleme sırası, ef 16 ve 128), m=0.02, n ∈ {50, 100}: golden set başına (G3u FAIL − G3 FAIL) farkının %95 CI alt sınırı > 0; her iki n'de, en az 2/3 veri setinde.
H4
HNSW ekleme sırası exact aramada olmayan bir metrik oynaması yaratır ve bu oynama ef_search arttıkça azalır.
HNSW yaklaşık arama; graf yapısı inşa sırasına bağlı.
ef=16'da seed'ler arası ikili |ΔRecall@10| 95. persentili > 0 (bütün veri setlerinde) ve ef ∈ {16, 32, 64, 128} boyunca artmaz (en az 2/3 veri setinde).
H5
P95 tahmini P50'den belirgin şekilde daha belirsizdir.
BM25, exact ve HNSW indeks (FAISS), metrik çapraz kontrolü, istatistik
MIT, MIT, MIT, BSD, Apache-2.0
✓
Doğrulama notu: model/kütüphane lisansları HF API kartı, PyPI metadata ve GitHub LICENSE'tan okundu. BEIR veri setlerinin HF kartındaki CC BY-SA 4.0, BEIR'in "lisans sorumluluğu kullanıcıdadır" notu nedeniyle tek başına yeterli kabul edilmedi. Yayımlanan sonuç Dataset'i korpus metni içermez; yalnız sorgu/belge ID'leri ve skorlar içerir.
Kontrollü regresyon: Run dosyasında soruların p%'sinde ilgili belgeleri top-k dışına it. p ∈ {1, 2, 3, 5, 8}. Etki büyüklüğü tam bilinir.
Popülasyon gerçeği. İki tanım raporlanır:
(a) Sonlu popülasyon: tüm test sorguları.
(b) Genelleme: sorgular seed'li olarak iki yarıya bölünür. Golden set A yarısından çekilir, "gerçek" B yarısında ölçülür. Bu, "golden set → gerçek trafik" senaryosunu temsil eder.
Eşik ızgarası. BEIR'de mutlak metrik seviyeleri belgelerdeki 0.90/0.92'den çok farklı olabilir. Bu yüzden τ, popülasyon değerine göre göreli kurulur: τ = m_pop + d, d ∈ {−0.05, −0.04, …, +0.05}. Belgelerdeki literal eşikler yalnız ek tabloda gösterilir.
Simülasyon. n ∈ {25, 50, 100, 200, 300} (n ≤ N/2), R = 2000 alt örnek, iadesiz örnekleme. Her (senaryo, gate, n, d) için karar matrisi kaydedilir. Bootstrap yeniden örnekleme sayısı B = 2000.
Latency. Yalnız FiQA'da (en büyük korpus). Her sistem için 20 sorgu ısınma, ardından tüm sorgu seti 10 tekrar; sistemler her koşuda sırayla ölçülür. Sorgu başına ms kaydedilir. Her tekrarda P50/P95/P99 ve quantile bootstrap CI hesaplanır.
Güç ve MDE. G3 için güç eğrileri simülasyondan çıkarılır. Analitik yaklaşım MDE ≈ (z1−α + z1−β) · sd(d) / √n simülasyonla karşılaştırılır; hesaplayıcı bu yaklaşımı kullanır ve sapması makalede raporlanır.
Pilot. Önce NFCorpus, n ∈ {50, 100}, R = 200 ile koşulup süre ölçülür. Tam ızgara süresi buna göre planlanır. Pilot sonucu hipotezleri değiştirmek için kullanılmaz.
7. Baseline'lar ve önerilen gate
Gate
Karar kuralı
Rol
G1 Mutlak eşik
PASS ⇔ m̂B ≥ τ
Belgelerdeki yöntem (baseline)
G2 Naif delta
PASS ⇔ m̂B − m̂A ≥ −m
Yaygın pratik (baseline; hata oranı kontrolsüz, betimsel)
G3 Paired non-inferiority
di = metrikB,i − metrikA,i; PASS ⇔ tek yönlü %95 paired bootstrap CI alt sınırı ≥ −m
Öneri
G3u Unpaired
A ve B ayrı bootstrap ağırlıklarıyla; ortalama farkının alt sınırı ≥ −m
H3 karşılaştırması (eşleştirmenin etkisi)
G3′ Sign-flip permütasyon
H0: ortalama(d) ≤ −m; p < 0.05 ise PASS
G3'ün dağılım varsayımsız kontrolü
GL Latency
PASS ⇔ P95 quantile bootstrap CI üst sınırı ≤ SLA
Öneri (G1'in latency karşılığıyla kıyaslanır)
Non-inferiority marjı m ∈ {0.01, 0.02, 0.03}. Ön-kayıtlıdır; sonuç görüldükten sonra değiştirilmez.
8. Metrikler
Metrik
Tanım
Recall@k
|ilgili ∩ top-k| / |ilgili| (BEIR konvansiyonu), soru başına
MRR@10
İlk ilgili belgenin rank'inin tersi; top-10'da yoksa 0
nDCG@10
Graded qrels ile (NFCorpus graded; diğerleri ikili)
Yanlış-FAIL oranı (FFR)
P(FAIL | gerçekte kabul edilebilir), R alt örnek üzerinden, Wilson CI ile
Kaçırma oranı (MR) / Güç
P(PASS | gerçekte regresyon) / 1 − MR
Karar hata oranı
G1 için P(karar ≠ popülasyon gerçeği), d'ye ve n'ye göre
MDE
α = 0.05, güç 0.8'de tespit edilebilir en küçük ortalama fark
Latency
P50/P95/P99 (ms), run-to-run CV, göreli CI genişliği
Birden çok karşılaştırmada (sistem × n × d) Holm düzeltmesi uygulanır. Tüm farklar %95 CI ile raporlanır.
9. Veri sızıntısı kontrolleri
Ön-kayıt: n ızgarası, R, B, m, d ızgarası ve hipotez eşikleri koşudan önce commit edilir. Pilot yalnız süre için kullanılır.
Genelleme ayrımı: Popülasyon gerçeği (b) tanımında golden set ve gerçek, ayrık sorgu yarılarından gelir. Böylece "aynı sorulara bakarak gerçeği tanımlama" yanlılığı ayrıca raporlanır.
Kontrollü bozmalar yalnız run dosyasına uygulanır; qrels hiçbir zaman değiştirilmez.
Eşik seçimi: τ yalnız popülasyon değerine göreli tanımlanır. Alt örnekte gözlenen değere göre ayarlanmaz.
Model eğitim verisi: Dense modellerin eğitiminde BEIR'e yakın veri bulunabilir. Bu projede modeller yalnız "sistem A/B" olarak kullanıldığı için iddiayı etkilemez; makalede not edilir.
Seed izlenebilirliği: Tüm alt örnek indeksleri (seed, n, r)'den türetilir ve Dataset'te yayımlanır.
10. Kabul kriterleri
Mühendislik kabulü (proje "bitti" sayılır)
Temiz ortamda python scripts/run_all.py --config configs/default.yaml uçtan uca çalışır.
Aynı seed ile iki koşu exact search ve BM25 için bit-aynı soru başına metrik üretir.
tests/test_stats.py: bilinen dağılımda bootstrap CI kapsama oranı 1000 simülasyonda nominal %95 ± 2 puan içinde.
Kendi metrik implementasyonu ranx ile üç veri setinde 1e-6 toleransla eşleşir.
Her sonuç dosyası config hash'i ve env.json ile birlikte kaydedilir.
HF Dataset kartı (kaynaklar, lisanslar, metrik tanımları, prereg hash'i) ve Static Space yayında. Space yalnız yayımlanmış Dataset dosyalarından çizer.
Bilimsel iddia kabulü
Her hipotez için Bölüm 3'teki destek ölçütü sonuçlarla birlikte "destekledi / desteklemedi" olarak raporlanır.
Negatif ya da beklenmeyen sonuçlar aynı formatta yayımlanır; hipotez sonradan değiştirilmez.
Hesaplayıcının analitik MDE'si ile simülasyon MDE'si arasındaki sapma raporlanır. Sapma büyükse hesaplayıcı simülasyon tablosuna geçer.
Plan kısıtı (2026-10-14'te HF dokümantasyonundan doğrulandı): Gradio ve Docker Space'leri oluşturmak ücretli plan (kişisel hesapta PRO) gerektiriyor; Static Space'ler herkes için ücretsiz. Ücretsiz kişisel hesaplar ZeroGPU üzerinde en fazla 2 Gradio Space barındırabiliyor. CPU Basic donanımı 2 vCPU / 16 GB. Bu proje canlı Python gerektirmediği için Static Space kullanır.
Config contrasts: golden set başına gate farklarının ortalaması ve CI'ı
Config latency: system, run, qid, ms
Dosyalar: env.json, hypotheses.json
Kararlar özet olarak (k PASS / R) saklanır; alt örnekler seed'den yeniden üretilebilir.
Kartta: kaynak veri setleri ve lisansları, metrik tanımları, seed'ler, prereg hash'i. Korpus metni yok.
bunyamineymen/rag-gate-stats
Static Space (HTML + JS)
Grafikler: hata oranı – eşiğe uzaklık, güç eğrileri, P95 belirsizliği.
"Kaç soru yeter?" hesaplayıcısı: kullanıcı baseline metriğini, soru başına fark std'sini ve hedef δ'yı girer; JS'de MDE / gerekli n hesaplanır.
Veri Dataset'ten indirilen küçük JSON özetleridir.
—
Model
Yok.
13. Makale taslağı
Çalışma başlığı: "Regression gate'iniz yazı-tura mı atıyor? Küçük golden setlerde PASS/FAIL'in istatistiği". Sonuç cümleleri koşudan sonra yazılır; aşağıdaki ⟨ölçülecek⟩ yer tutucuları doldurulmadan yayımlanmaz.
Özet. Problem (eşik var, belirsizlik yok); yöntem (alt örnekleme simülasyonu + kontrollü regresyon); ana bulgular ⟨ölçülecek⟩; reçete; Dataset/Space linkleri.
Giriş. İki playbook'taki gate tanımları ve aralarındaki fark (0.92 / 0.90). "Eşikler örnektir" notunun pratikte neyi eksik bıraktığı.
Üç gürültü kaynağı. Golden set örneklemi, ANN nondeterminizmi, latency ölçüm gürültüsü.