File size: 30,785 Bytes
668f59a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 | <!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 >= 0.92</code>, <code>Faithfulness >= 0.95</code>, <code>Accuracy >= 0.90</code>, <code>P95 Latency <= 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ı > 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ı > 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 > 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) > 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 < 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 & 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>
|