Türkçe Şikâyet Metinlerinde Topic Clustering

English summary

Bu depo, Next4biz Data Science R&D birimindeki bir aylık staj boyunca geliştirdiğim Türkçe konu keşfi çalışmalarının gizlilik odaklı portföy sürümüdür. İlk sürümde yalnızca sentetik bir demonstrasyon vardı; bu sürüm gerçek araştırma akışını gösterecek şekilde baştan düzenlendi:

• 17 adet, doğrudan staj sırasında yazdığım notebook'lardan kürate edilmiş araştırma notebook'u,
• veri kalitesi ve ön işlemeden TopicGPT-esinli pilota uzanan deney zinciri,
• gerçek veri satırı içermeyen ayrıntılı CSV/JSON sonuç tabloları,
• marka adları ve kişisel veri bakımından incelenmiş toplu görseller,
• deneylerin işe yarayan ve yaramayan yanlarını birlikte anlatan kanıt kaydı,
• ayrıca yalnız sentetik veriyle çalışan küçük bir yeniden üretilebilir paket.

Bu kişisel bir araştırma portföyüdür; Next4biz'in resmî ürünü, performans beyanı veya resmî deposu değildir.

Araştırma sorusu

Etiketi bulunmayan, gürültülü Türkçe müşteri geri bildirimlerinde bir kaydın ana ve gerektiğinde ikincil sorun konuları nasıl keşfedilebilir?

Yerel çalışma kesiti 6.459 kayıt ve 10 markadan oluşuyordu. Repo gerçek şikâyetleri, başlıkları veya marka eşleme anahtarını içermez. Marka dağılımı gerekiyorsa eşleme anahtarı saklanmayan ve her exportta yeniden karıştırılan Marka_A–Marka_J takma adları ile yuvarlanmış toplu değerler gösterilir.

Repoda ne var?

1. Gerçek araştırma notebook'ları

Notebook'lar eski çalışma klasöründen körlemesine kopyalanmadı. Benzer dosyalar birleştirildi; kayıtlı çıktılar, execution count'lar, kişisel mutlak yollar, gerçek marka adları, ham metin önizlemeleri ve cloud API çağrıları çıkarıldı.

Başlangıç noktası: notebook rehberi. Notebook bazlı kurulum seçenekleri: ortam rehberi.

Araştırma notebook'ları “private veriyi GitHub'da çalıştır” örneği değildir. Kod akışını korur fakat çıktı içermez; veri yolu açıkça PRIVATE_DATA_PATH benzeri yerel bir yapılandırmaya çevrilmiştir. TopicGPT notebook'u cloud çağrısı yapmaz ve yalnız anonim toplu sonuçlarla çalışır.

2. Ayrıntılı fakat satır içermeyen sonuçlar

results/ altında şunlar bulunur:

• veri seti profili ve yuvarlanmış marka-takma-ad dağılımı,
• güvenli global TF-IDF terimleri,
• KeyBERT KMeans/HDBSCAN grid metrikleri ve noise özeti,
• feature extraction model karşılaştırma özeti,
• NMF topic, coherence, diversity, cardinality ve yakınsama tabloları,
• yakınsamış NMF parametre arama koşuları,
• BERTopic topic/outlier özeti,
• Leiden küme boyutları ve filtrelenmiş c-TF-IDF terimleri,
• zero-shot ile prototip yaklaşımının label bazlı agreement değerleri,
• TopicGPT-esinli taksonomi ve batch–tekil atama farkları,
• kayıtlı çalışma süresi gözlemleri ile doğrulanamayan staj-notu iddialarının ayrı provenance tablosu.

Hiçbir sonuç dosyasında complaint_detail, header, evidence, kişi/iletişim bilgisi, gerçek marka, demografi veya satır bazlı tahmin bulunmaz.

3. Güvenli görseller

Orijinal word cloud eksik marka stoplist'i nedeniyle yayımlanmadı. Repodaki görsel, yalnız gözden geçirilmiş genel sorun terimlerinden yeniden üretildi. Diğer görseller de hover metni, temsilci doküman veya marka içermeyen toplu çıktılardır.

Öne çıkan, doğrulanabilir gözlemler

NMF, bu çalışmada düşük maliyetli ve yorumlanabilir en pratik klasik baseline oldu. Bu, NMF'nin her veri setinde BERTopic veya başka bir yöntemden üstün olduğu anlamına gelmez. Araştırmanın bütün karar zinciri araştırma yolculuğunda, her iddianın dayanağı ise kanıt kaydında açıklanır.

Notebook okuma sırası

Kısa bir tur için:

1. 00_data_quality_audit.ipynb
2. 01_zemberek_preprocessing.ipynb
3. 05_keybert_clustering.ipynb
4. 07_nmf_multilabel.ipynb
5. 08_nmf_parameter_search.ipynb
6. 09_bertopic_experiment.ipynb
7. 10_zero_shot_nli.ipynb
8. 13_local_gemma_mlx_taxonomy.ipynb
9. 14_topicgpt_inspired_offline.ipynb
10. 16_leiden_ctfidf_local_labeling.ipynb

Tüm defterlerin kaynağı, birleştirme kararı ve neden dışarıda bırakılan benzerleri notebooks/README.md içinde listelenir.

Çalıştırılabilir sentetik quickstart

Ham veri paylaşmadan çekirdek akışı yeniden üretmek için:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

topic-cluster examples/synthetic_complaints.csv \
  --text-column text \
  --n-topics 6 \
  --min-df 1 \
  --output-dir artifacts/demo

Bu komut topics.json, üretilmiş kimlikli assignments.csv ve run_summary.json oluşturur. artifacts/ varsayılan olarak git dışında kalır. Sentetik notebook public_demo.ipynb, gerçek araştırma defterlerinin yerine değil, yalnız hızlı çalıştırma kontrolü olarak tutulur.

API ve model bağımlılığı sınırı

• Kürate edilmiş notebook'lar OpenAI, Gemini veya başka bir cloud LLM API'sine çağrı yapmaz.
• TopicGPT-esinli notebook, arşivlenmiş güvenli toplu çıktıyı analiz eder; ham evidence ve provider kodu çıkarılmıştır.
• Transformers, sentence-transformers, BERTopic ve NER modelleri isteğe bağlı olarak yerel makinede çalışır.
• Gemma/MLX notebook'u Apple Silicon'a özgü opsiyonel bir araştırma akışıdır.
• Model ağırlıkları, tokenizer paketleri, Zemberek JAR'ı veya üçüncü taraf repository kopyaları bu depoda bulunmaz.

Gizlilik tasarımı

flowchart LR
    A[Yetkili yerel veri] --> B[Ham satırlar git dışında]
    B --> C[PII + marka azaltma]
    C --> D[Modelleme]
    D --> E[Toplu metrik/terim exportu]
    E --> F[Whitelist + denylist taraması]
    F --> G[Manuel inceleme]
    G --> H[Private GitHub snapshot]

Regex, NER ve marka takma adı anonimlik garantisi vermez. Kısa bir topic n-gram'ı veya nadir toplu değer dahi başka verilerle eşleştirme riski taşıyabilir. Bu yüzden:

• ham ve “cleaned/lemma/safe” adlı satır bazlı türevler yayımlanmaz,
• minimum gerekli toplu sütunlar export edilir,
• gerçek marka → takma ad anahtarı repo dışında kalır,
• topic terimleri kontrollü genel-terim whitelist'inden geçer,
• notebook outputs/attachments/widgets tamamen temizlenir,
• git'e girecek bloblar secret, mutlak yol ve PII biçimleri için taranır.

Ayrıntılar: veri kartı ve veri/mahremiyet politikası.

Yerel kalite ve yayın kapısı

PYTHONPATH=src python -m unittest discover -s tests -v
python -m compileall -q src tests scripts
python scripts/release_check.py .

Release checker, git indexindeki ve untracked adaylardaki dosyaları şu riskler için kontrol eder:

• secret/token biçimleri ve dolu .env,
• macOS/Windows kişisel yolları,
• e-posta, telefon, IBAN ve checksum-doğrulanan TCKN benzeri değerler,
• CSV/JSON'da ham metin/evidence/demografi sütunları,
• notebook output, execution count, attachment ve widget metadata'sı,
• izin verilmeyen veri/model/rapor/binary türleri,
• PNG imzası, boyutları ve metadatası,
• büyük dosya ve beklenmeyen repository yolu.

Otomatik tarama hukuki görüş veya anonimlik ispatı değildir.

Depo yapısı

.
├── docs/                  # Yolculuk, metodoloji, kanıt ve public kontrol listesi
├── examples/              # Yalnız açıkça işaretlenmiş sentetik veri
├── figures/               # İncelenmiş toplu görseller
├── notebooks/
│   ├── research/          # 17 output'suz, API'siz kürate edilmiş staj notebook'u
│   └── public_demo.ipynb  # Sentetik quickstart
├── results/               # Ham satır içermeyen CSV/JSON araştırma sonuçları
├── scripts/               # Güvenli export, notebook kürasyonu ve yayın taraması
├── src/                   # Veri-bağımsız yeniden kullanılabilir çekirdek
└── tests/                 # Sentetik testler ve yayın güvenlik kapısı

Önemli doğruluk notları

• Notebook Markdown'ında ve staj notlarında NMF için birbiriyle uyuşmayan LLM-değerlendirme yüzdeleri bulundu; rubrik ve satır bazlı judge çıktısı olmadığı için hiçbiri accuracy benchmark'ı olarak kullanılmadı.
• İkinci NMF parametre notebook'unda UMass işaret yönü birleşik sıralamayı tersine çevirebiliyordu; düzeltilmemiş “best” sonucu yayımlanmadı.
• Orijinal “few-shot” notebook'u generative prompt few-shot değil, örnek embeddinglerinin prototip merkezlerine benzerlik yöntemidir.
• TopicGPT akışı makaleden esinlenen özel bir uygulamadır; resmî paketin birebir reprodüksiyonu değildir.
• Bir modelin kendi confidence skoru veya başka bir modelle agreement'i accuracy değildir.

Veri, fikrî mülkiyet ve public yayın

Bir şikâyetin internette görülebilir olması onu yeniden dağıtma hakkı vermez. Veri kaynağının kullanım koşulları, veri tabanı/telif hakları, staj sözleşmesi, kod sahipliği, işveren izni ve KVKK ayrı ayrı değerlendirilmelidir.

Bu nedenle açık kaynak lisansı eklenmemiştir. Lisans bulunmaması yeniden kullanım izni vermez. Private repo public yapılmadan önce public yayın kontrol listesi tamamlanmalıdır.

Teknik referanslar

• Maarten Grootendorst, BERTopic: Neural topic modeling with a class-based TF-IDF procedure, 2022.
• Chau Minh Pham ve diğerleri, TopicGPT: A Prompt-based Topic Modeling Framework, 2023.
• Roman Egger ve Joanne Yu, A Topic Modeling Comparison Between LDA, NMF, Top2Vec, and BERTopic, 2022.