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 &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>