Proje 01 / 20Faz 1 — Ölçüm temeliCPU · LLM yokSpec v0.2 · 2026-10-17 (uygulamayla güncellendi)

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.

İçindekiler

0. HTML dayanağı

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ç

  1. 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.
  2. Sistem eşiğin rahatça üstündeyken gerçek regresyonların mutlak eşikten geçip gitmesini ("headroom maskeleme") nicelemek.
  3. 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.
  4. ANN (HNSW) yeniden inşası ve latency ölçüm gürültüsünün gate kararlarına etkisini ölçmek.
  5. Yeniden kullanılabilir çıktılar: stats.py (bootstrap CI, permütasyon testi, quantile CI, güç/MDE) ve "kaç soru yeter?" hesaplayıcısı.

2. Kapsam

Kapsam içiKapsam dışı (gerekçe)
  • Retrieval metrikleri: Recall@5, Recall@10, MRR@10, nDCG@10
  • Retrieval latency: P50 / P95 / P99
  • Veri: BEIR NFCorpus, FiQA-2018, SCIDOCS (test sorguları)
  • 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.
#HipotezGerekçe / tahmin kaynağıDestek ölçütü
H1n ≤ 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.
H2Baseline 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.
H3Aynı α'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.
H4HNSW 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).
H5P95 tahmini P50'den belirgin şekilde daha belirsizdir.Kuyruk quantile'larının örneklem varyansı yüksektir.6 sistemin en az 4'ünde: koşu içi göreli CI genişliği oranı (P95 / P50) medyanı ≥ 2 ve koşular arası CV(P95) > CV(P50).

4. Veri ve lisans

KaynakHF / kaynak IDKullanımLisansDurum
NFCorpus (BEIR)BeIR/nfcorpus, BeIR/nfcorpus-qrelsKüçük popülasyon; graded qrels (nDCG)HF kartı CC BY-SA 4.0. BEIR README lisans sorumluluğunu kullanıcıya bırakıyor; orijinal kaynak lisansı ayrıca okunacak.⚠
FiQA-2018 (BEIR)BeIR/fiqa, BeIR/fiqa-qrelsOrta popülasyon, 57,638 belgelik korpusHF kartı CC BY-SA 4.0; orijinal lisans okunacak.⚠
SCIDOCS (BEIR)BeIR/scidocs, BeIR/scidocs-qrels1,000 test sorgusu; alt örnekleme için en büyük popülasyonHF kartı CC BY-SA 4.0; orijinal lisans okunacak.⚠
all-MiniLM-L6-v2sentence-transformers/all-MiniLM-L6-v2Dense sistem (doğal regresyon kaynağı)Apache-2.0✓
bge-small-en-v1.5BAAI/bge-small-en-v1.5Ana dense sistemMIT✓
e5-small-v2intfloat/e5-small-v2Dense sistemMIT✓
Kütüphanelerbm25s, faiss-cpu, ranx, scipy, sentence-transformersBM25, exact ve HNSW indeks (FAISS), metrik çapraz kontrolü, istatistikMIT, 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.

5. Mimari

BEIR (corpus, queries, qrels: test)
   │
   ├─► retrieve.py ─ BM25 (bm25s) · Dense (sentence-transformers, CPU)
   │                    └─► FAISS IndexFlatIP (exact, top-100) · FAISS IndexHNSWFlat (M=16, efC=200,
   │                        ekleme sırası = seed, top-10)
   │
   ├─► metrics.py ── soru başına Recall@5/10, MRR@10, nDCG@10   (ranx ile çapraz kontrol)
   │
   ├─► simulate.py ─ sistem çiftleri: no-op · doğal · kontrollü regresyon
   │                 n ∈ {25,50,100,200,300} × R alt örnek → karar vs "gerçek"
   │
   ├─► gates.py ──── G1 mutlak eşik · G2 naif delta · G3 paired · G3u unpaired · G3′ sign-flip · GL latency
   │
   ├─► latency.py ── FiQA, 2 iş parçacığı, 10 koşu (ayrı süreç)
   │
   └─► report.py ─── hipotez kararları + özet tablolar + space/data/summary.json
                         │
                         └─► export_hf.py ─► hf_dataset/ (HF Dataset) + space/ (Static Space)
ModülSorumlulukNot
stats.pybootstrap_weights, lower_bound/upper_bound, paired_bootstrap_ci, sign_flip_pvalues, quantile_bootstrap_ci, wilson_ci, mean_ci, mde, required_n, noninferiority_pass_prob, holmSaf numpy/scipy. 02–20 bu dosyayı kopyalar; 3. kullanımdan sonra paketleştirme değerlendirilir.
gates.pyGate kararları; YAML'den okunan eşik/marjÖrnek CI workflow'u da bunu çağırır.
simulate.pyAlt örnekleme, popülasyon gerçeği, karar matrisleriTüm alt örnek indeksleri seed'den türetilir ve kaydedilir.

6. Deney protokolü

  1. Ortam. Python 3.12 venv (uv). Bağımlılıklar uv.lock'ta pinli. OMP_NUM_THREADS=2 ve torch.set_num_threads(2) ile HF CPU Basic profili (2 vCPU / 16 GB) taklit edilir. CPU modeli, RAM ve kütüphane sürümleri results/env.json'a yazılır.
  2. Veri. Test qrels'te en az bir ilgili belgesi olan sorgular "popülasyon" olur. Gerçek sorgu sayıları bu adımda hesaplanıp kaydedilir.
  3. Sistemler. S_bm25 = bm25s; S_bge = bge-small + exact; S_minilm = MiniLM + exact; S_e5 = e5-small + exact; S_hnsw(ef, seed) = bge-small + FAISS HNSW, ef_search ∈ {16, 32, 64, 128}, seed ∈ {0..9}. Seed, ekleme sırasının permütasyonudur; inşa tek iş parçacığıyla yapılır. FAISS ef = max(efSearch, k) kullandığı için HNSW koşuları top-10'dur. Dense modellerde max_seq_length = 256.
  4. Soru başına metrikler tüm sistemler için hesaplanır. 20 soruluk alt kümede elle hesaplanan değerler ve ranx ile eşleşme kontrol edilir.
  5. Senaryolar.
    • No-op: HNSW farklı seed; korpus ekleme sırası karıştırma; aynı sistemin tekrar koşusu (yalnız latency).
    • Doğal regresyon: bge-small → MiniLM; ef_search 128 → 16; korpustan rastgele %5 / %10 belge silme.
    • 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. 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

GateKarar kuralıRol
G1 Mutlak eşikPASS ⇔ m̂B ≥ τBelgelerdeki yöntem (baseline)
G2 Naif deltaPASS ⇔ m̂B − m̂A ≥ −mYaygın pratik (baseline; hata oranı kontrolsüz, betimsel)
G3 Paired non-inferioritydi = metrikB,i − metrikA,i; PASS ⇔ tek yönlü %95 paired bootstrap CI alt sınırı ≥ −mÖneri
G3u UnpairedA ve B ayrı bootstrap ağırlıklarıyla; ortalama farkının alt sınırı ≥ −mH3 karşılaştırması (eşleştirmenin etkisi)
G3′ Sign-flip permütasyonH0: ortalama(d) ≤ −m; p < 0.05 ise PASSG3'ün dağılım varsayımsız kontrolü
GL LatencyPASS ⇔ 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

MetrikTanı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@10Graded 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
LatencyP50/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

10. Kabul kriterleri

Mühendislik kabulü (proje "bitti" sayılır)

Bilimsel iddia kabulü

11. Repo yapısı

01-regression-gate-stats/
├── spec.html                 # bu belge
├── README.md                 # kurulum + tek komutla tekrar üretim
├── prereg.md                 # ön-kayıt (SHA-256'sı her koşuda env.json'a yazılır)
├── pyproject.toml, uv.lock   # pinli bağımlılıklar
├── configs/
│   └── default.yaml          # veri setleri, sistemler, n/d ızgarası, R, B, seed listesi
├── src/gatestats/
│   ├── data.py               # BEIR yükleme, popülasyon tanımı
│   ├── retrieve.py           # bm25s, FAISS exact ve HNSW
│   ├── metrics.py            # soru başına metrikler
│   ├── stats.py              # ortak istatistik araç seti (02–20 kopyalar)
│   ├── gates.py              # G1, G2, G3, G3u, G3′, GL + CI komutu
│   └── simulate.py           # senaryolar + alt örnekleme simülasyonu
├── scripts/
│   ├── run_all.py            # veri → run'lar → metrikler → simülasyon
│   ├── latency.py            # 2 iş parçacığıyla latency
│   ├── report.py             # hipotez kararları, özetler, Space verisi
│   └── export_hf.py          # hf_dataset/ klasörü
├── tests/
│   ├── test_stats.py         # bootstrap kapsama, gate'ler, Wilson/Holm/MDE
│   └── test_pipeline.py      # ranx eşleşmesi, determinizm
├── ci/
│   └── rag-gate.example.yml  # G3'ü PR'da çalıştıran örnek workflow
├── cache/, results/          # .gitignore; sonuçlar HF Dataset'e yüklenir
├── space/                    # Static Space: index.html, README.md, data/summary.json
└── article/
    └── draft.md

12. Hugging Face dağıtımı

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.
RepoTürİçerik
bunyamineymen/rag-gate-stats-resultsDataset (Parquet)
  • Config per_query: dataset, system, qid, recall@5, recall@10, mrr@10, ndcg@10
  • Config threshold: G1 kararları (dataset, truth, system, metric, n, d, k_pass, R)
  • Config pairs: senaryo çiftlerinde gate kararları (gate, param, delta_true, sd_d, k_pass, R, analytic_pass)
  • 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-statsStatic 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.
—ModelYok.

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.

  1. Özet. Problem (eşik var, belirsizlik yok); yöntem (alt örnekleme simülasyonu + kontrollü regresyon); ana bulgular ⟨ölçülecek⟩; reçete; Dataset/Space linkleri.
  2. Giriş. İki playbook'taki gate tanımları ve aralarındaki fark (0.92 / 0.90). "Eşikler örnektir" notunun pratikte neyi eksik bıraktığı.
  3. Üç gürültü kaynağı. Golden set örneklemi, ANN nondeterminizmi, latency ölçüm gürültüsü.
  4. Kurulum. Veri, sistemler, senaryolar, gate tanımları, ön-kayıt.
  5. Sonuçlar.
    • 4.1 Mutlak eşik ne sıklıkla yanılır? Şekil 1: hata oranı – d, n eğrileri ⟨ölçülecek⟩.
    • 4.2 Headroom maskeleme. Şekil 2 ⟨ölçülecek⟩.
    • 4.3 Paired gate'in gücü. Şekil 3: güç – n, δ ⟨ölçülecek⟩.
    • 4.4 HNSW seed gürültüsü. Tablo 1 ⟨ölçülecek⟩.
    • 4.5 P95'in belirsizliği. Şekil 4 ⟨ölçülecek⟩.
    • 4.6 Analitik MDE ile simülasyon uyumu ⟨ölçülecek⟩.
  6. Pratik reçete. Örnek gate YAML'ı; golden set büyüklüğü seçimi; marj seçimi.
  7. Sınırlamalar. BEIR, şirket korpusu değildir. Retrieval-only. LLM metriklerine genelleme 11–20'de sınanır.
  8. Tekrar üretim. Komutlar, seed'ler, Dataset/Space linkleri, prereg hash'i.
  9. Kaynakça (yalnız doğrulanmış):
    • Thakur vd. 2021, BEIR, arXiv:2104.08663 ✓
    • Efron & Tibshirani 1993, An Introduction to the Bootstrap (kitap)
    • Kaynak HTML belgeleri G ve T