rag-gate-stats-code / spec.html
bunyamineymen's picture
Project 01 code (8e118d5)
668f59a verified
Raw History Blame Contribute Delete
30.8 kB
<!DOCTYPE html>
<html lang="tr">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Spec 01 — Regression Gate İstatistiği</title>
<style>
:root{--bg:#f6f8fb;--card:#fff;--text:#1f2937;--muted:#6b7280;--line:#e5e7eb;--accent:#2563eb;--accent-soft:#eff6ff;--green:#15803d;--green-soft:#f0fdf4;--amber:#b45309;--amber-soft:#fffbeb;--red:#b91c1c;--red-soft:#fef2f2;--violet:#6d28d9;--violet-soft:#f5f3ff;--code:#111827}
*{box-sizing:border-box}
body{margin:0;font-family:Inter,Segoe UI,Arial,sans-serif;background:var(--bg);color:var(--text);line-height:1.65}
.wrap{max-width:1100px;margin:0 auto;padding:32px 20px 80px}
.hero{background:linear-gradient(135deg,#fff,#eef5ff);border:1px solid var(--line);border-radius:20px;padding:32px;box-shadow:0 8px 28px rgba(15,23,42,.06);margin-bottom:22px}
h1{font-size:34px;line-height:1.15;margin:6px 0 12px}
h2{font-size:24px;margin:0 0 12px}
h3{font-size:18px;margin:20px 0 8px}
p{margin:8px 0}
.lead{font-size:17px;color:#374151;max-width:900px}
.badge{display:inline-block;font-size:12px;font-weight:700;letter-spacing:.05em;text-transform:uppercase;background:var(--accent-soft);color:var(--accent);padding:6px 10px;border-radius:999px;margin:0 6px 6px 0}
.badge.cpu{background:var(--green-soft);color:var(--green)}
.badge.llm{background:var(--amber-soft);color:var(--amber)}
.badge.status{background:#f3f4f6;color:#374151}
.meta{display:grid;grid-template-columns:repeat(auto-fit,minmax(230px,1fr));gap:12px;margin-top:16px}
.meta div{background:#fff;border:1px solid var(--line);border-radius:12px;padding:12px 14px;font-size:14px}
.meta b{display:block;font-size:12px;color:var(--muted);text-transform:uppercase;letter-spacing:.04em}
.section{background:#fff;border:1px solid var(--line);border-radius:18px;padding:24px;margin:18px 0}
.toc{columns:3;column-gap:28px}
.toc a{display:block;color:var(--accent);text-decoration:none;font-size:14px;margin:3px 0;break-inside:avoid}
.toc a:hover{text-decoration:underline}
ul,ol{padding-left:22px}
li{margin:5px 0}
code,pre{font-family:Consolas,Monaco,monospace}
code{background:#f1f5f9;padding:1px 5px;border-radius:5px;font-size:.92em}
pre{background:var(--code);color:#f9fafb;padding:16px;border-radius:12px;overflow:auto;font-size:13px;line-height:1.5}
pre code{background:none;padding:0}
table{width:100%;border-collapse:collapse;margin:12px 0 18px;font-size:14px}
th,td{padding:10px 12px;border-bottom:1px solid var(--line);text-align:left;vertical-align:top}
th{background:#f9fafb}
.note,.good,.warn,.bad,.src{border-left:4px solid;padding:12px 14px;border-radius:10px;margin:14px 0}
.note{background:var(--accent-soft);border-color:var(--accent)}
.good{background:var(--green-soft);border-color:var(--green)}
.warn{background:var(--amber-soft);border-color:var(--amber)}
.bad{background:var(--red-soft);border-color:var(--red)}
.src{background:var(--violet-soft);border-color:var(--violet)}
.src::before{content:"KAYNAK (HTML belgeleri)";display:block;font-size:11px;font-weight:800;letter-spacing:.06em;color:var(--violet);margin-bottom:4px}
.ok{color:var(--green);font-weight:700}
.todo{color:var(--amber);font-weight:700}
.checklist li{list-style:"☐ "}
.small{font-size:13px;color:var(--muted)}
footer{margin-top:40px;color:var(--muted);font-size:13px}
@media(max-width:800px){.toc{columns:1}h1{font-size:28px}}
</style>
</head>
<body>
<div class="wrap">
<section class="hero">
<span class="badge">Proje 01 / 20</span><span class="badge">Faz 1 — Ölçüm temeli</span><span class="badge cpu">CPU · LLM yok</span><span class="badge status">Spec v0.2 · 2026-10-17 (uygulamayla güncellendi)</span>
<h1>Regression gate yazı-tura mı atıyor? Küçük golden set istatistiği</h1>
<p class="lead">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 <code>stats.py</code> modülü diğer 19 projenin ortak istatistik araç setidir.</p>
<div class="meta">
<div><b>Araştırma sorusu</b>50–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?</div>
<div><b>Hesap</b>Yalnız CPU. LLM, GPU, ücretli API yok.</div>
<div><b>HF çıktıları</b>Dataset <code>bunyamineymen/rag-gate-stats-results</code> · Static Space <code>bunyamineymen/rag-gate-stats</code></div>
<div><b>Bağımlılık</b>Yok (ilk proje). Çıktısı olan <code>stats.py</code> 02–20 tarafından kopyalanır.</div>
</div>
</section>
<div class="note"><b>Okuma anahtarı.</b> Mor <b>KAYNAK</b> kutuları iki HTML belgesinden alıntı veya özettir (G = <code>_RAG_Testing_Best_Practices.html</code>, T = <code>RAG_43_Test_Best_Practices.html</code>). Geri kalan her şey bu spec'in önerisidir. Lisans satırlarında <span class="ok">✓</span> = 2026-10-14'te kaynağından doğrulandı, <span class="todo">⚠</span> = uygulama başlamadan doğrulanacak. Bu belgede hiçbir deney sonucu yoktur; sayısal hedefler ön-kayıtlı tahmindir.</div>
<section class="section">
<h2>İçindekiler</h2>
<div class="toc">
<a href="#dayanak">0. HTML dayanağı</a><a href="#amac">1. Amaç</a><a href="#kapsam">2. Kapsam</a><a href="#hipotez">3. Hipotezler</a><a href="#veri">4. Veri ve lisans</a><a href="#mimari">5. Mimari</a><a href="#protokol">6. Deney protokolü</a><a href="#baseline">7. Baseline'lar</a><a href="#metrik">8. Metrikler</a><a href="#sizinti">9. Veri sızıntısı kontrolleri</a><a href="#kabul">10. Kabul kriterleri</a><a href="#repo">11. Repo yapısı</a><a href="#hf">12. Hugging Face dağıtımı</a><a href="#makale">13. Makale taslağı</a>
</div>
</section>
<section class="section" id="dayanak">
<h2>0. HTML dayanağı</h2>
<div class="src">
<b>G§11 Regression Gate:</b> <code>Recall@5 &gt;= 0.92</code>, <code>Faithfulness &gt;= 0.95</code>, <code>Accuracy &gt;= 0.90</code>, <code>P95 Latency &lt;= 2.5s</code> → PASS / FAIL. "Embedding modeli, chunk size, prompt, reranker, LLM veya vector DB değiştiğinde aynı test suite tekrar çalışmalı."<br>
<b>T "Örnek Production Gate":</b> 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."<br>
<b>T43:</b> "P50/P95/P99, concurrency, tokens, cost/query takip et."<br>
<b>G§1:</b> "Bu dataset'i CI/CD içinde çalışan kalıcı bir RAG regression suite olarak kullan."
</div>
<div class="warn"><b>Belgelerdeki boşluk (editör notu).</b> İ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.</div>
</section>
<section class="section" id="amac">
<h2>1. Amaç</h2>
<ol>
<li>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.</li>
<li>Sistem eşiğin rahatça üstündeyken gerçek regresyonların mutlak eşikten geçip gitmesini ("headroom maskeleme") nicelemek.</li>
<li>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.</li>
<li>ANN (HNSW) yeniden inşası ve latency ölçüm gürültüsünün gate kararlarına etkisini ölçmek.</li>
<li>Yeniden kullanılabilir çıktılar: <code>stats.py</code> (bootstrap CI, permütasyon testi, quantile CI, güç/MDE) ve "kaç soru yeter?" hesaplayıcısı.</li>
</ol>
</section>
<section class="section" id="kapsam">
<h2>2. Kapsam</h2>
<table>
<tr><th>Kapsam içi</th><th>Kapsam dışı (gerekçe)</th></tr>
<tr><td>
<ul>
<li>Retrieval metrikleri: Recall@5, Recall@10, MRR@10, nDCG@10</li>
<li>Retrieval latency: P50 / P95 / P99</li>
<li>Veri: BEIR NFCorpus, FiQA-2018, SCIDOCS (test sorguları)</li>
<li>Sistemler: BM25 + 3 küçük dense model; exact (FAISS Flat) ve HNSW (hnswlib)</li>
<li>No-op değişiklikler, doğal ve kontrollü regresyonlar</li>
<li>3 gate türü + latency gate'i</li>
</ul>
</td><td>
<ul>
<li>Generation metrikleri (faithfulness, accuracy): LLM gerektirir. Aynı gate yöntemi 11–20'de uygulanır.</li>
<li>Yük / concurrency testleri: ayrı bir altyapı konusu.</li>
<li>Maliyet/sorgu: CPU-only kurulumda anlamlı değil.</li>
<li>Gerçek CI entegrasyonu: yalnız örnek workflow dosyası verilir.</li>
<li>Embedding modellerinin kalite sıralaması: bu projenin iddiası değil (bkz. 03).</li>
</ul>
</td></tr>
</table>
</section>
<section class="section" id="hipotez">
<h2>3. Hipotezler (ön-kayıt)</h2>
<p class="small">Bağlayıcı metin <code>prereg.md</code>'dir: ilk tam koşudan önce yazıldı ve SHA-256 özeti her koşuda <code>results/env.json</code>'a kaydedilir. Aşağıdaki tablo onun özetidir. Sayısal eşikler tahmindir, sonuç değildir.</p>
<div class="warn"><b>v0.2 değişikliği (koşudan önce):</b> 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 <code>prereg.md</code> §4'te.</div>
<table>
<tr><th>#</th><th>Hipotez</th><th>Gerekçe / tahmin kaynağı</th><th>Destek ölçütü</th></tr>
<tr><td>H1</td><td>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.</td><td>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.</td><td>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.</td></tr>
<tr><td>H2</td><td>Baseline eşiğin üstündeyken G1, gerçek regresyonları kaçırır (headroom maskeleme).</td><td>G1 değişimi değil, mutlak seviyeyi kontrol eder.</td><td><code>bge → ctl03</code> (Δ = −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ı &gt; 0; en az 2/3 veri setinde.</td></tr>
<tr><td>H3</td><td>Aynı α'da eşleştirme (G3), eşleştirmesiz bootstrap'a (G3u) göre kabul edilebilir değişikliklerde yanlış FAIL'i azaltır.</td><td>Aynı sorularda iki sistemin skorları pozitif koreledir; eşleştirme farkın varyansını düşürür.</td><td>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ı &gt; 0; her iki n'de, en az 2/3 veri setinde.</td></tr>
<tr><td>H4</td><td>HNSW ekleme sırası exact aramada olmayan bir metrik oynaması yaratır ve bu oynama ef_search arttıkça azalır.</td><td>HNSW yaklaşık arama; graf yapısı inşa sırasına bağlı.</td><td>ef=16'da seed'ler arası ikili |ΔRecall@10| 95. persentili &gt; 0 (bütün veri setlerinde) ve ef ∈ {16, 32, 64, 128} boyunca artmaz (en az 2/3 veri setinde).</td></tr>
<tr><td>H5</td><td>P95 tahmini P50'den belirgin şekilde daha belirsizdir.</td><td>Kuyruk quantile'larının örneklem varyansı yüksektir.</td><td>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) &gt; CV(P50).</td></tr>
</table>
</section>
<section class="section" id="veri">
<h2>4. Veri ve lisans</h2>
<table>
<tr><th>Kaynak</th><th>HF / kaynak ID</th><th>Kullanım</th><th>Lisans</th><th>Durum</th></tr>
<tr><td>NFCorpus (BEIR)</td><td><code>BeIR/nfcorpus</code>, <code>BeIR/nfcorpus-qrels</code></td><td>Küçük popülasyon; graded qrels (nDCG)</td><td>HF kartı CC BY-SA 4.0. BEIR README lisans sorumluluğunu kullanıcıya bırakıyor; orijinal kaynak lisansı ayrıca okunacak.</td><td class="todo">⚠</td></tr>
<tr><td>FiQA-2018 (BEIR)</td><td><code>BeIR/fiqa</code>, <code>BeIR/fiqa-qrels</code></td><td>Orta popülasyon, 57,638 belgelik korpus</td><td>HF kartı CC BY-SA 4.0; orijinal lisans okunacak.</td><td class="todo">⚠</td></tr>
<tr><td>SCIDOCS (BEIR)</td><td><code>BeIR/scidocs</code>, <code>BeIR/scidocs-qrels</code></td><td>1,000 test sorgusu; alt örnekleme için en büyük popülasyon</td><td>HF kartı CC BY-SA 4.0; orijinal lisans okunacak.</td><td class="todo">⚠</td></tr>
<tr><td>all-MiniLM-L6-v2</td><td><code>sentence-transformers/all-MiniLM-L6-v2</code></td><td>Dense sistem (doğal regresyon kaynağı)</td><td>Apache-2.0</td><td class="ok">✓</td></tr>
<tr><td>bge-small-en-v1.5</td><td><code>BAAI/bge-small-en-v1.5</code></td><td>Ana dense sistem</td><td>MIT</td><td class="ok">✓</td></tr>
<tr><td>e5-small-v2</td><td><code>intfloat/e5-small-v2</code></td><td>Dense sistem</td><td>MIT</td><td class="ok">✓</td></tr>
<tr><td>Kütüphaneler</td><td><code>bm25s</code>, <code>faiss-cpu</code>, <code>ranx</code>, <code>scipy</code>, <code>sentence-transformers</code></td><td>BM25, exact ve HNSW indeks (FAISS), metrik çapraz kontrolü, istatistik</td><td>MIT, MIT, MIT, BSD, Apache-2.0</td><td class="ok">✓</td></tr>
</table>
<p class="small">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.</p>
</section>
<section class="section" id="mimari">
<h2>5. Mimari</h2>
<pre><code>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)</code></pre>
<table>
<tr><th>Modül</th><th>Sorumluluk</th><th>Not</th></tr>
<tr><td><code>stats.py</code></td><td><code>bootstrap_weights</code>, <code>lower_bound</code>/<code>upper_bound</code>, <code>paired_bootstrap_ci</code>, <code>sign_flip_pvalues</code>, <code>quantile_bootstrap_ci</code>, <code>wilson_ci</code>, <code>mean_ci</code>, <code>mde</code>, <code>required_n</code>, <code>noninferiority_pass_prob</code>, <code>holm</code></td><td>Saf numpy/scipy. 02–20 bu dosyayı kopyalar; 3. kullanımdan sonra paketleştirme değerlendirilir.</td></tr>
<tr><td><code>gates.py</code></td><td>Gate kararları; YAML'den okunan eşik/marj</td><td>Örnek CI workflow'u da bunu çağırır.</td></tr>
<tr><td><code>simulate.py</code></td><td>Alt örnekleme, popülasyon gerçeği, karar matrisleri</td><td>Tüm alt örnek indeksleri seed'den türetilir ve kaydedilir.</td></tr>
</table>
</section>
<section class="section" id="protokol">
<h2>6. Deney protokolü</h2>
<ol>
<li><b>Ortam.</b> Python 3.12 venv (uv). Bağımlılıklar <code>uv.lock</code>'ta pinli. <code>OMP_NUM_THREADS=2</code> ve <code>torch.set_num_threads(2)</code> ile HF CPU Basic profili (2 vCPU / 16 GB) taklit edilir. CPU modeli, RAM ve kütüphane sürümleri <code>results/env.json</code>'a yazılır.</li>
<li><b>Veri.</b> Test qrels'te en az bir ilgili belgesi olan sorgular "popülasyon" olur. Gerçek sorgu sayıları bu adımda hesaplanıp kaydedilir.</li>
<li><b>Sistemler.</b> 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 <code>ef = max(efSearch, k)</code> kullandığı için HNSW koşuları top-10'dur. Dense modellerde <code>max_seq_length = 256</code>.</li>
<li><b>Soru başına metrikler</b> tüm sistemler için hesaplanır. 20 soruluk alt kümede elle hesaplanan değerler ve ranx ile eşleşme kontrol edilir.</li>
<li><b>Senaryolar.</b>
<ul>
<li><i>No-op:</i> HNSW farklı seed; korpus ekleme sırası karıştırma; aynı sistemin tekrar koşusu (yalnız latency).</li>
<li><i>Doğal regresyon:</i> bge-small → MiniLM; ef_search 128 → 16; korpustan rastgele %5 / %10 belge silme.</li>
<li><i>Kontrollü regresyon:</i> 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.</li>
</ul></li>
<li><b>Popülasyon gerçeği.</b> İki tanım raporlanır:
<ul>
<li>(a) Sonlu popülasyon: tüm test sorguları.</li>
<li>(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.</li>
</ul></li>
<li><b>Eşik ızgarası.</b> 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.</li>
<li><b>Simülasyon.</b> 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.</li>
<li><b>Latency.</b> 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.</li>
<li><b>Güç ve MDE.</b> G3 için güç eğrileri simülasyondan çıkarılır. Analitik yaklaşım MDE ≈ (z<sub>1−α</sub> + z<sub>1−β</sub>) · sd(d) / √n simülasyonla karşılaştırılır; hesaplayıcı bu yaklaşımı kullanır ve sapması makalede raporlanır.</li>
<li><b>Pilot.</b> Ö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.</li>
</ol>
</section>
<section class="section" id="baseline">
<h2>7. Baseline'lar ve önerilen gate</h2>
<table>
<tr><th>Gate</th><th>Karar kuralı</th><th>Rol</th></tr>
<tr><td>G1 Mutlak eşik</td><td>PASS ⇔ m̂<sub>B</sub> ≥ τ</td><td>Belgelerdeki yöntem (baseline)</td></tr>
<tr><td>G2 Naif delta</td><td>PASS ⇔ m̂<sub>B</sub> − m̂<sub>A</sub> ≥ −m</td><td>Yaygın pratik (baseline; hata oranı kontrolsüz, betimsel)</td></tr>
<tr><td>G3 Paired non-inferiority</td><td>d<sub>i</sub> = metrik<sub>B,i</sub> − metrik<sub>A,i</sub>; PASS ⇔ tek yönlü %95 paired bootstrap CI alt sınırı ≥ −m</td><td>Öneri</td></tr>
<tr><td>G3u Unpaired</td><td>A ve B ayrı bootstrap ağırlıklarıyla; ortalama farkının alt sınırı ≥ −m</td><td>H3 karşılaştırması (eşleştirmenin etkisi)</td></tr>
<tr><td>G3′ Sign-flip permütasyon</td><td>H0: ortalama(d) ≤ −m; p &lt; 0.05 ise PASS</td><td>G3'ün dağılım varsayımsız kontrolü</td></tr>
<tr><td>GL Latency</td><td>PASS ⇔ P95 quantile bootstrap CI üst sınırı ≤ SLA</td><td>Öneri (G1'in latency karşılığıyla kıyaslanır)</td></tr>
</table>
<p>Non-inferiority marjı m ∈ {0.01, 0.02, 0.03}. Ön-kayıtlıdır; sonuç görüldükten sonra değiştirilmez.</p>
</section>
<section class="section" id="metrik">
<h2>8. Metrikler</h2>
<table>
<tr><th>Metrik</th><th>Tanım</th></tr>
<tr><td>Recall@k</td><td>|ilgili ∩ top-k| / |ilgili| (BEIR konvansiyonu), soru başına</td></tr>
<tr><td>MRR@10</td><td>İlk ilgili belgenin rank'inin tersi; top-10'da yoksa 0</td></tr>
<tr><td>nDCG@10</td><td>Graded qrels ile (NFCorpus graded; diğerleri ikili)</td></tr>
<tr><td>Yanlış-FAIL oranı (FFR)</td><td>P(FAIL | gerçekte kabul edilebilir), R alt örnek üzerinden, Wilson CI ile</td></tr>
<tr><td>Kaçırma oranı (MR) / Güç</td><td>P(PASS | gerçekte regresyon) / 1 − MR</td></tr>
<tr><td>Karar hata oranı</td><td>G1 için P(karar ≠ popülasyon gerçeği), d'ye ve n'ye göre</td></tr>
<tr><td>MDE</td><td>α = 0.05, güç 0.8'de tespit edilebilir en küçük ortalama fark</td></tr>
<tr><td>Latency</td><td>P50/P95/P99 (ms), run-to-run CV, göreli CI genişliği</td></tr>
</table>
<p>Birden çok karşılaştırmada (sistem × n × d) Holm düzeltmesi uygulanır. Tüm farklar %95 CI ile raporlanır.</p>
</section>
<section class="section" id="sizinti">
<h2>9. Veri sızıntısı kontrolleri</h2>
<ul>
<li><b>Ön-kayıt:</b> 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.</li>
<li><b>Genelleme ayrımı:</b> 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.</li>
<li><b>Kontrollü bozmalar</b> yalnız run dosyasına uygulanır; qrels hiçbir zaman değiştirilmez.</li>
<li><b>Eşik seçimi:</b> τ yalnız popülasyon değerine göreli tanımlanır. Alt örnekte gözlenen değere göre ayarlanmaz.</li>
<li><b>Model eğitim verisi:</b> 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.</li>
<li><b>Seed izlenebilirliği:</b> Tüm alt örnek indeksleri <code>(seed, n, r)</code>'den türetilir ve Dataset'te yayımlanır.</li>
</ul>
</section>
<section class="section" id="kabul">
<h2>10. Kabul kriterleri</h2>
<h3>Mühendislik kabulü (proje "bitti" sayılır)</h3>
<ul class="checklist">
<li>Temiz ortamda <code>python scripts/run_all.py --config configs/default.yaml</code> uçtan uca çalışır.</li>
<li>Aynı seed ile iki koşu exact search ve BM25 için bit-aynı soru başına metrik üretir.</li>
<li><code>tests/test_stats.py</code>: bilinen dağılımda bootstrap CI kapsama oranı 1000 simülasyonda nominal %95 ± 2 puan içinde.</li>
<li>Kendi metrik implementasyonu ranx ile üç veri setinde 1e-6 toleransla eşleşir.</li>
<li>Her sonuç dosyası config hash'i ve <code>env.json</code> ile birlikte kaydedilir.</li>
<li>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.</li>
</ul>
<h3>Bilimsel iddia kabulü</h3>
<ul class="checklist">
<li>Her hipotez için Bölüm 3'teki destek ölçütü sonuçlarla birlikte "destekledi / desteklemedi" olarak raporlanır.</li>
<li>Negatif ya da beklenmeyen sonuçlar aynı formatta yayımlanır; hipotez sonradan değiştirilmez.</li>
<li>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.</li>
</ul>
</section>
<section class="section" id="repo">
<h2>11. Repo yapısı</h2>
<pre><code>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</code></pre>
</section>
<section class="section" id="hf">
<h2>12. Hugging Face dağıtımı</h2>
<div class="warn"><b>Plan kısıtı (2026-10-14'te HF dokümantasyonundan doğrulandı):</b> Gradio ve Docker Space'leri oluşturmak ücretli plan (kişisel hesapta PRO) gerektiriyor; <b>Static Space'ler herkes için ücretsiz</b>. Ü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.</div>
<table>
<tr><th>Repo</th><th>Tür</th><th>İçerik</th></tr>
<tr><td><code>bunyamineymen/rag-gate-stats-results</code></td><td>Dataset (Parquet)</td><td>
<ul>
<li>Config <code>per_query</code>: dataset, system, qid, recall@5, recall@10, mrr@10, ndcg@10</li>
<li>Config <code>threshold</code>: G1 kararları (dataset, truth, system, metric, n, d, k_pass, R)</li>
<li>Config <code>pairs</code>: senaryo çiftlerinde gate kararları (gate, param, delta_true, sd_d, k_pass, R, analytic_pass)</li>
<li>Config <code>contrasts</code>: golden set başına gate farklarının ortalaması ve CI'ı</li>
<li>Config <code>latency</code>: system, run, qid, ms</li>
<li>Dosyalar: <code>env.json</code>, <code>hypotheses.json</code></li>
</ul>
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.</td></tr>
<tr><td><code>bunyamineymen/rag-gate-stats</code></td><td>Static Space (HTML + JS)</td><td>
<ul>
<li>Grafikler: hata oranı – eşiğe uzaklık, güç eğrileri, P95 belirsizliği.</li>
<li>"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.</li>
<li>Veri Dataset'ten indirilen küçük JSON özetleridir.</li>
</ul></td></tr>
<tr><td>—</td><td>Model</td><td>Yok.</td></tr>
</table>
</section>
<section class="section" id="makale">
<h2>13. Makale taslağı</h2>
<p><b>Çalışma başlığı:</b> "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 <code>⟨ölçülecek⟩</code> yer tutucuları doldurulmadan yayımlanmaz.</p>
<ol>
<li><b>Özet.</b> Problem (eşik var, belirsizlik yok); yöntem (alt örnekleme simülasyonu + kontrollü regresyon); ana bulgular ⟨ölçülecek⟩; reçete; Dataset/Space linkleri.</li>
<li><b>Giriş.</b> İki playbook'taki gate tanımları ve aralarındaki fark (0.92 / 0.90). "Eşikler örnektir" notunun pratikte neyi eksik bıraktığı.</li>
<li><b>Üç gürültü kaynağı.</b> Golden set örneklemi, ANN nondeterminizmi, latency ölçüm gürültüsü.</li>
<li><b>Kurulum.</b> Veri, sistemler, senaryolar, gate tanımları, ön-kayıt.</li>
<li><b>Sonuçlar.</b>
<ul>
<li>4.1 Mutlak eşik ne sıklıkla yanılır? Şekil 1: hata oranı – d, n eğrileri ⟨ölçülecek⟩.</li>
<li>4.2 Headroom maskeleme. Şekil 2 ⟨ölçülecek⟩.</li>
<li>4.3 Paired gate'in gücü. Şekil 3: güç – n, δ ⟨ölçülecek⟩.</li>
<li>4.4 HNSW seed gürültüsü. Tablo 1 ⟨ölçülecek⟩.</li>
<li>4.5 P95'in belirsizliği. Şekil 4 ⟨ölçülecek⟩.</li>
<li>4.6 Analitik MDE ile simülasyon uyumu ⟨ölçülecek⟩.</li>
</ul></li>
<li><b>Pratik reçete.</b> Örnek gate YAML'ı; golden set büyüklüğü seçimi; marj seçimi.</li>
<li><b>Sınırlamalar.</b> BEIR, şirket korpusu değildir. Retrieval-only. LLM metriklerine genelleme 11–20'de sınanır.</li>
<li><b>Tekrar üretim.</b> Komutlar, seed'ler, Dataset/Space linkleri, prereg hash'i.</li>
<li><b>Kaynakça</b> (yalnız doğrulanmış):
<ul>
<li>Thakur vd. 2021, BEIR, arXiv:2104.08663 <span class="ok">✓</span></li>
<li>Efron &amp; Tibshirani 1993, <i>An Introduction to the Bootstrap</i> (kitap)</li>
<li>Kaynak HTML belgeleri G ve T</li>
</ul></li>
</ol>
</section>
<footer>Spec 01 / 20 · RAG değerlendirme makale serisi · Bu belge sonuç içermez; tüm sayısal ifadeler ön-kayıtlı tahmin veya doğrulanmış kaynak bilgisidir.</footer>
</div>
</body>
</html>