berkbirkan/turkish-seo-reasoning

Turkish SEO Reasoning

Bu veri seti, küçük parametreli bir dil modeline Türkçe SEO vakalarında kanıta dayalı karar verme becerisi kazandırmak ve aynı senaryoda özel bir benchmark oluşturmak için hazırlanmıştır.

Projenin kapsamı

Bu sürümde tool-call eğitimi yoktur. Modelden araç seçmesi veya araç çağrısı üretmesi beklenmez.

Hedeflenen davranış şudur:

1. 1.Verilen SEO kanıtını okumak
2. 2.İlgili Google Search Central ilkesini uygulamak
3. 3.Kısa ve denetlenebilir bir gerekçe sunmak
4. 4.Bir karar vermek
5. 5.Uygulanabilir öneriler üretmek

reasoning_summary alanı gizli düşünce zinciri değildir. Yalnızca cevabın denetlenebilmesi için gerekli kısa, kullanıcıya gösterilebilir gerekçeyi içerir.

Proje, küçük bir dil modeline temel SEO muhakemesi kazandırmayı araştırır; büyük modeller seviyesinde genel amaçlı reasoning veya otonom ajan performansı iddiasında bulunmaz.

Split politikası

Ödev kuralına uygun olarak test verisi eğitimden önce ayrılmıştır.

Test split'i ayrı rastgele seed, ayrı kimlik alanı ve ayrı bağlam numaralarıyla önce oluşturulup kilitlenmiştir. Test kayıtları fine-tune eğitiminde, eğitim prompt'u geliştirmede veya checkpoint seçiminde kullanılmamalıdır.

Test kümesindeki 120 sorunun 12'si tamamen elle ve dikkatlice hazırlanmıştır. Kalan 108 soru kontrollü senaryolardan türetilmiştir.

Kategoriler

Test split'inde her kategoriden 10 soru vardır:

• —Robots ve indeksleme
• —Canonical
• —Yönlendirmeler
• —Sitemap
• —Title links
• —Snippets ve meta description
• —Structured data
• —Helpful/people-first content
• —Hreflang
• —İç bağlantılar
• —JavaScript SEO
• —SEO mitleri ve yanlış garantiler

Kayıt yapısı

Her kayıt şu temel bileşenleri içerir:

• —question: SEO sorusu
• —evidence: karar için verilen kanıt
• —reasoning_summary: kısa ve denetlenebilir gerekçe
• —expected_decision: beklenen ana karar
• —expected_recommendations: kabul edilen eylemler
• —messages: supervised fine-tuning için konuşma biçimi
• —source_url: dayanak Google Search Central sayfası
• —manual: sorunun tamamen elle hazırlanıp hazırlanmadığı

Benchmark kullanımı

Fine-tune sırasında yalnızca train split'i kullanılmalıdır. test split'i nihai model dondurulduktan sonra en az beş farklı model/checkpoint üzerinde aynı üretim ayarlarıyla çalıştırılmalıdır.

Benchmark dosyaları birbirinden ayrılmıştır:

• —benchmark/questions.jsonl: modele verilecek 120 soru
• —benchmark/reference.jsonl: puanlayıcının kullanacağı cevap anahtarı
• —data/test.jsonl: Hugging Face test split'inin tam kayıtları
• —benchmark/PROTOCOL.md: sabit deney ve puanlama protokolü
• —benchmark/models.json: beş temel model ve fine-tuned model listesi
• —benchmark/LEADERBOARD.md: sonuç tablosu
• —scripts/score_benchmark.py: tekrarlanabilir otomatik puanlayıcı

Model çalıştırılırken yalnızca questions.jsonl okunmalıdır. reference.jsonl inference prompt'una veya model bağlamına kesinlikle eklenmemelidir.

Tamamlanmış altı-model benchmark sonuçları:

https://huggingface.co/datasets/berkbirkan/turkish-seo-reasoning-benchmark-results

Önerilen puan bileşenleri:

• —Karar doğruluğu
• —Gerekçenin kanıtla uyumu
• —Önerilerin doğruluğu ve uygulanabilirliği
• —Kanıtsız iddiadan kaçınma
• —Yapılandırılmış cevap biçimine uyum

Veri üretimi

Veri seti Google Search Central belgelerindeki kurallardan türetilmiş özgün Türkçe senaryolardan oluşur. Google belgelerinin uzun metinleri kopyalanmamış; ilkeler kısa vaka, gerekçe ve önerilere dönüştürülmüştür.

Üretim betiği benchmark'ı önce, eğitim verisini sonra ve farklı seed değerleriyle oluşturur:

scripts/build_dataset.py

Gemma 3 / Unsloth notebook uyumluluğu

Veri seti Gemma3_(4B)_ipynb_x_replies_dataset_finetuning.ipynb akışıyla kullanılacak şekilde düzenlenmiştir:

• —Notebook'un beklediği ana kolonun adı messages değeridir.
• —Her konuşma yalnızca user ve assistant rollerinden oluşur.
• —Gemma 3 sürümleri arasındaki system rolü uyumsuzluğunu önlemek için sistem talimatı ilk user mesajına eklenmiştir.
• —Mesaj içerikleri multimodal olmayan düz metindir.
• —Assistant cevabı JSON metni yerine Gerekçe, Karar ve Öneriler başlıklı doğal metindir.
• —Notebook'taki standardize_data_formats, apply_chat_template ve train_on_responses_only adımlarıyla uyumludur.
• —Notebook yalnızca split="train" yüklediği sürece benchmark eğitime karışmaz.

Notebook çalıştırılırken dataset satırı şu depoyu ve yalnızca train split'ini göstermelidir:

load_dataset("berkbirkan/turkish-seo-reasoning", split="train")

Benchmark için aynı notebook'un eğitim hücresinde test split'i kesinlikle birleştirilmemeli veya kullanılmamalıdır.

Temel kaynaklar

• —https://developers.google.com/search/docs/fundamentals/seo-starter-guide
• —https://developers.google.com/search/docs/fundamentals/creating-helpful-content
• —https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag
• —https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls
• —https://developers.google.com/search/docs/crawling-indexing/301-redirects
• —https://developers.google.com/search/docs/crawling-indexing/sitemaps/overview
• —https://developers.google.com/search/docs/appearance/title-link
• —https://developers.google.com/search/docs/appearance/snippet
• —https://developers.google.com/search/docs/appearance/structured-data/sd-policies
• —https://developers.google.com/search/docs/specialty/international/localized-versions
• —https://developers.google.com/search/docs/crawling-indexing/links-crawlable
• —https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics

Kaynak erişim tarihi: 2026-07-28.

Sınırlamalar

• —Veri gerçek sıralama sonucu tahmini yapmaz.
• —Hiçbir öneri Google'da indekslenme veya sıralama garantisi değildir.
• —Sentetik şablonlardan gelen dilsel tekrarlar bulunabilir.
• —Google belgeleri değişebileceği için veri seti sürümlenmelidir.
• —Test split'inin açık yayımlanması gelecekte benchmark kontaminasyonu riski taşır.

Lisans notu

Veri setindeki senaryolar özgün olarak oluşturulmuştur ve CC BY 4.0 ile yayımlanması planlanmıştır. Kaynak Google belgeleri kendi site politikalarına ve sayfalarında belirtilen lisans koşullarına tabidir.