Raf payı endeksi

AI Shelf Endeksi — Metodoloji

Sürüm 1.1.0 · 28 Ağustos 2026

Bu belge, "Specialty Coffee AI Shelf Report" başlığıyla yayımlanan endeksin nasıl üretildiğini anlatır. Amaç tek bir soruyu ölçmektir: bir alışverişçi yapay zekâ asistanına kahve sorduğunda hangi markalar öneriliyor?

Endeksteki her sayı, arşivlenmiş ham cevaplardan yeniden üretilebilir. Üretemediğimiz hiçbir sayı ekrana çıkmaz.

---

1. Sorgu seti

350 alışverişçi sorgusu — 175 İngilizce, 175 Türkçe — yedi niyet başlığına dağıtılmıştır:

Sorgular pazarlama diliyle değil, gerçek alışverişçi diliyle yazılmıştır. Tam liste data/queries.json içindedir ve sürümlenir.

2. Koşum

Her sorgu, her motorda 5 kez sorulur. Tek çekim geçersizdir: aynı soru aynı motorda farklı cevaplar üretir, tek bir çekimle ölçüm yapılamaz.

Ham cevabın tamamı arşivlenir. Marka çıkarımını ucuz bir ayrıştırıcı model yapar; çıktısı {brands[], products[], citations[], first_position_brand, price_mentions[], confidence} biçimindedir ve ayrıştırıcı istemi prompts/parser.md içinde sürümlenir.

3. Veri kalite kapısı

Rapor üretilmeden önce dört kapı işletilir. Hiçbiri isteğe bağlı değildir.

(a) Tamamlanmış hücre kuralı. Bir (motor, sorgu) çifti ancak 5 tekrarı da başarıyla tamamlandıysa hesaba girer. Eksik hücreler hesaptan çıkarılır ama gizlenmez: sayıları ve örnekleri raporun kapsam bölümünde "yetersiz örnek" etiketiyle listelenir.

(b) Marka normalizasyonu. Aynı markanın farklı yazımları tek isimde toplanır. Eşleme elle tutulur ve data/marka-esleme.json içinde sürümlenir. Kurallar:

• Karşılaştırma küçük/büyük harf duyarsızdır.
• Kıvrık kesme işaretleri düz kesmeye çevrilir; yalnızca noktalama, boşluk veya

harf büyüklüğü farkıyla ayrılan yazımlar kendiliğinden birleşir (Peet's = Peet’s).

• Anlamlı fark taşıyan adlar (Counter Culture Coffee → Counter Culture)

yalnızca eşleme dosyasında açıkça yazılıysa birleşir. Otomatik ek kırpma yoktur, çünkü "X Coffee" gerçekten ayrı bir marka olabilir.

• Marka ile ürün karıştırılmaz: ayrıştırıcının products alanı endekse girmez.

Kahve markası olmayan adlar endeks dışında tutulur ve sebebiyle birlikte raporda görünür: ekipman (değirmen, demleme aleti, tartı), ambalaj, pazaryeri (Amazon gibi satış kanalları), ayristirma-artigi.

(c) Güven eşiği. Ayrıştırıcı güveni 0,7'nin altındaki marka anımları hesaba katılmaz. Kaç anımın bu yüzden atıldığı raporda yazar.

(d) Yayın eşiği. Aşağıdakilerin üçü birden sağlanmadıkça endeks TASLAK damgasıyla kalır, halka açık yayımlanamaz:

Eşik karşılanmadığında rapor yine üretilir — ama TASLAK olarak, eksiklerin listesiyle birlikte. Eksik veri saklanmaz.

4. Metrikler

Share of AI Shelf. Markanın adının geçtiği geçerli cevapların oranı. Payda, kalite kapısından geçen tüm cevaplardır. Bir cevapta marka birden çok kez geçse de bir kez sayılır.

Her orana %95 Wilson güven aralığı eşlik eder. Wilson, küçük örneklemde ve uçlara yakın oranlarda normal yaklaşımdan sağlamdır:

merkez = (p + z²/2N) / (1 + z²/N)
marj   = z·√(p(1−p)/N + z²/4N²) / (1 + z²/N)

Aralıkları çakışan iki marka arasında "biri önde" denemez. Tablodaki sıralama noktasal orana göredir; fark iddiası aralıklara bakılarak kurulur.

Motor kırılımı. Aynı oran her motor için ayrı hesaplanır, kendi güven aralığıyla. Motorlar arası fark endeksin en çok işe yarayan çıktısıdır: bir marka bir motorda görünüp diğerinde görünmeyebilir.

Niyet kırılımı. Aynı oran yedi niyet başlığı için ayrı hesaplanır. "Hediye" sorgularında öne çıkan marka ile "bütçe" sorgularında öne çıkan marka aynı değildir.

İlk sırada anılma. Ayrı bir metriktir, Share of AI Shelf'in bir parçası değildir. Cevapta ilk anılan marka sayılır. Payı düşük ama ilk sırası yüksek bir marka, az sayıda soruda ama güçlü biçimde önerilen markadır.

Bölge kırılımı — Türkiye ve Avrupa. Her sorgu bir pazara etiketlenir (data/queries.json → bolge):

Bölge oranı yalnızca o bölgenin cevapları üzerinden hesaplanır; paydası farklı olduğu için genel tabloyla doğrudan karşılaştırılmaz. Bir bölgenin cevap sayısı 100'ün altındaysa kırılım "yetersiz örnek" damgasıyla gösterilir: sayı gerçektir ama aralık geniştir, sıralama iddiası kurulmaz.

Bu sürümdeki dürüst sınır: İngilizce set Avrupa pazarı için yazılmadı. 350 sorgunun yalnızca 3'ü Avrupa'ya açık işaret taşıyor. "Avrupa" kırılımı, Avrupa'ya yönelen sorgular yazılana kadar dar kalır ve öyle etiketlenir.

Atıf kaynakları. Cevaplarda verilen bağlantıların alan adları, en çok linklenen 20 tanesi. Bir alan adı, aynı cevapta kaç kez geçerse geçsin bir kez sayılır. Bağlantı veren cevap sayısı ayrıca yazılır — motorların çoğu kaynak göstermez, bu metrik ancak o oranla birlikte okunur.

4b. Ölçüm hatası kalibrasyonu (Rogan–Gladen)

Ayrıştırıcı kusursuz değil. Bazı markaları uyduruyor ya da yanlış eşliyor (yanlış pozitif), bazılarını kaçırıyor (yanlış negatif). Gözlenen pay bu iki hatanın bileşimiyle gerçek paydan sapar.

İnsan etiketli bir altkümeden iki büyüklük ölçülür:

• Duyarlılık (Se) = TP / (TP + FN) — gerçekten geçen markaların kaçını buluyor
• Özgüllük (Sp) = TN / (TN + FP) — geçmeyenleri kaça doğru eliyor

Düzeltme:

p_kalibre = (p_gözlenen + Sp − 1) / (Se + Sp − 1)

Hücre tanımı: (tam incelenen cevap × izlenen marka). Doğru negatif ancak insanın cevabın *tamamını* incelediğini işaretlemesiyle sayılabilir — aksi halde "eklemedi" ile "görmedi" ayırt edilemez.

Kilitler:

Se+Sp−1 (Youden J) 0,5'in altındayken düzeltme gürültüyü büyütür: paydası küçüldükçe küçük hatalar patlar. O yüzden düzeltmemek, yanlış düzeltmekten iyidir.

Şu anki durum: Se/Sp değerleri ve etiket sayısı /makine/saglik ekranında canlı. Etiket 100'ün altındayken yayımlanan bütün paylar ham paydır ve öyle etiketlenir.

5. Ölçmediklerimiz

• Tıklama, satış, trafik. Endeks yalnızca öneride görünmeyi ölçer.
• Cevabın doğruluğu. Model bir markayı yanlış tarif ediyorsa bunu ölçmüyoruz.
• Kişiselleştirme. Sorgular oturum geçmişi olmadan sorulur. Gerçek

kullanıcının geçmişi sonucu değiştirebilir.

• Zaman içindeki oynaklık. Bu sürüm tek bir ölçüm penceresidir; eğilim

iddiası için en az iki pencere gerekir.

6. Yeniden üretilebilirlik

node runner/endeks.mjs        # kalite kapısı + hesaplar → data/endeks/kahve.json
node runner/endeks.mjs --kapi # yalnızca kapı raporu

Ham cevaplar data/raw/ altında ve koşum veritabanında saklanır. Endeksteki her satır, o satırı üreten cevaplara kadar geri izlenebilir.

7. Sürüm geçmişi