whistle-tr — Whistle ASR'ye Türkçe Desteği

Açık kaynaklı Cactus Whistle konuşma‑tanıma (STT) modeline Türkçe dil desteği kazandıran proje. Whistle, tek bir 16.9 MB .cact dosyası olarak CPU üzerinde, GPU'suz, yerel (on‑device) çalışan bir modeldir. Bu depo, Türkçe için gerekli fine‑tuning (ince ayar) boru hattını ve veri hazırlama araçlarını içerir.

• Motor kaynağı: cactus-compute/needle (bu repo'da engine/ olarak gömülü)
• Taban model: Cactus-Compute/whistle
• Lisans: Apache 2.0

Whistle nedir ve neden Türkçe ekleyebiliyoruz?

Whistle, mobil/giyilebilir/robot/akıllı ev/araç/mikrodenetleyici gibi kısıtlı cihazlarda çalışmak üzere tasarlanmış bir ASR modelidir. Özellikleri:

• 16.9 MB tek dosya, ilk tokene 11.1 ms, saniyede 1.319 token (Apple M4 Pro CPU)
• 7 dil: en, de, fr, es, it, nl, pl
• Deşifre, kelime zaman damgaları, ses embedding'i ve keyword biasing
• needle dil modeli ile aynı C++ motorunu kullanır → ses doğrudan araca (tool call) dönüşür

Kritik nokta: Whistle'ın kendi fine‑tuning altyapısı yeni dilleri yerleşik olarak destekler. Eğitim verisinde "language": "tr" etiketi olan klipler verdiğinizde:

1. Yeni <tr> dil etiketi otomatik türetilir (whistle_finetune.py L275)
2. Tokenizer'a Türkçe karakter/ek parçaları otomatik eklenir (WhistleTokenizer)
3. LoRA + yeni kelime‑haznesi satırları CQ kuantizasyonuyla (W4A8) eğitilir
4. needle whistle build --lora ile Türkçe konuşan bir .cact arşivi üretilir

Yani Türkçe eklemek "aynı tokenizer'a zorlamak" değil, modeli Türkçe veriyle ince ayardan geçirip sözlüğü Türkçe'ye göre genişletmektir.

Kurulum

# Python 3.11 önerilir
python -m venv .venv
.venv/Scripts/activate        # Windows
pip install cactus-needle     # runtime + JAX
pip install -r engine/requirements-train.txt   # eğitim için (jax, optax, sentencepiece...)

Türkçe modele giden yol (3 adım)

1) Türkçe ses‑metin verisi hazırla

Açık kaynaklı Türkçe veri setleri: Common Voice (tr), FLEURS (tr), VoxForge (tr).

Depodaki scripts/fetch_fleurs_tr.py FLEURS Türkçe alt kümesini indirip eğitim için data/tr.jsonl formatında üretir. Her satır:

{"audio": "audio/tr_001.wav", "text": "bugün hava çok güzel", "language": "tr"}

2) Fine‑tune

needle whistle finetune data/tr/tr.jsonl \
  --tokens data/turkce_ekler.txt \
  --epochs 3 --batch-size 4 --lr 3e-4 --lora-rank 16 --lora-alpha 32 \
  --checkpoint-dir out/tr

--tokens, sözlükte bulunmayan Türkçe özel isimler/ekler listesidir (opsiyonel ama kaliteyi artırır).

3) .cact arşivini üret

needle whistle build --lora out/tr/whistle_lora.safetensors --out whistle-tr.cact

Bu, tüm platform motorlarıyla çalışabilen Türkçe konuşan Whistle arşivini üretir: native tr dil etiketi + genişletilmiş Türkçe sözlük.

Doğrulama

needle --model whistle-tr.cact --audio test_tr.wav
# → { "text": "...", "language": "tr", ... }

Eğitim için donanım notu

Whistle yalnızca ~16 MB büyüklüğünde küçük bir model olduğundan LoRA fine‑tune tek bir tüketici GPU'sunda (8–16 GB VRAM) makul sürede biter. CPU'da da çalışır ama yavaştır. JAX GPU kurulumu için jax[cuda] gerekir (GPU sürücünüze göre).

Sorumluluk / durum

Bu depo altyapıyı ve boru hattını sağlar. Nihai Türkçe model kalitesi, kullanılan veri setinin hacmine ve temizliğine bağlıdır (önerilen en az birkaç yüz saat temiz Türkçe konuşma).

Kaynaklar

• Whistle tanıtım yazısı
• Whistle HF modeli
• needle motoru GitHub
• needle3 motor arşivi

WSL2 / Linux GPU eğitimi

JAX‑CUDA native Windows'ta çalışmaz (Windows yerli wheel'i yok, yalnızca Linux). Bu yüzden GPU eğitimi için WSL2/Ubuntu gerekir:

1. Windows'ta (yönetici PowerShell): wsl --install -d Ubuntu → Makineyi yeniden başlat, Ubuntu parola kur.
2. Ubuntu içinde tek komut (proje /mnt/d/... üzerinden erişilir, GPU passthrough otomatik):

   bash /mnt/d/apk.projeleri/whistle-tr/scripts/wsl_gpu_setup.sh

   Script: cactus-needle[gpu,train] kurar → GPU'yu doğrular → data/tr/tr.jsonl ile fine‑tune yürütür → whistle-tr.cact üretir. Özelleştirme env değişkenleriyle: EPOCHS, BATCH, LR, RANK, ALPHA.

Veri (FLEURS tr) depoya girmiyor (.gitignore); WSL /mnt/d/... üzerinden aynı data/tr/ klasörünü okur. GPU sürücünüzün WSL'yi desteklemesi gerekir (RTX 30x için yeterli).