---
language:
  - tr
license: apache-2.0
library_name: transformers
pipeline_tag: automatic-speech-recognition
base_model: openai/whisper-large-v3
base_model_relation: finetune
tags:
  - whisper
  - asr
  - speech-recognition
  - turkish
  - lora
metrics:
  - wer
  - cer
model-index:
  - name: whisper-large-v3-turkish-general
    results:
      - task:
          type: automatic-speech-recognition
        dataset:
          name: General Turkish real-speech evaluation
          type: general-turkish
        metrics:
          - type: wer
            value: 0.0792
            name: General Turkish WER
          - type: cer
            value: 0.0226
            name: General Turkish CER
---

# Whisper Large V3 - Türkçe Genel ASR (M1)

OpenAI `whisper-large-v3` modelinin yaklaşık 140 saatlik dengeli genel Türkçe konuşma
verisiyle LoRA üzerinden uyarlanmış, ardından temel modele birleştirilmiş sürümüdür.
Bu repo tam `transformers` modelini ve işlemci dosyalarını içerir.

M1, TurkMedSTT kontrollü ablasyonunun yalnız genel Türkçe verisiyle eğitilen koludur.
Medikal veri içeren M2 modeli:
`turkmedstt/whisper-large-v3-turkish-medical`.

## Model ailesi

| Kısaltma | Model | Eğitim farkı | Kullanım amacı |
|---|---|---|---|
| M0 | `openai/whisper-large-v3` | Ek uyarlama yok | Temel karşılaştırma modeli |
| M1 | Bu repo | Genel Türkçe konuşma ile LoRA | Genel Türkçe ASR |
| M2 | `turkmedstt/whisper-large-v3-turkish-medical` | Genel Türkçe + sentetik medikal konuşma | Tıbbi terminoloji araştırması |

Bu ayrım kontrollü ablasyon içindir: M1 ve M2 aynı temel model ve benzer eğitim
yapısını kullanır; temel deneysel fark M2 eğitimine medikal verinin eklenmesidir.

## Eğitim

- Temel model: `openai/whisper-large-v3`
- Yöntem: LoRA, hedef modüller `q_proj,v_proj`
- LoRA: `r=64`, `alpha=128`, dropout `0.05`
- Öğrenme oranı: `1e-4`
- Eğitim: 1 epoch
- Veri: yaklaşık 140 saat dengeli Türkçe konuşma
  (Common Voice, ISSAI ve OpenSLR kaynakları)
- Veri hazırlama reçetesi (kaynaklar, lisanslar, temizleme kuralları, sayılar ve yeniden üretim): https://github.com/muhammedkumcu/turkmedstt/blob/main/docs/DATA_PIPELINE.md

## Sonuçlar

320 gerçek, medikal olmayan Türkçe klipte:

| Model | WER | CER |
|---|---:|---:|
| M0 `whisper-large-v3` | 0.1213 | 0.0546 |
| M1 genel Türkçe | **0.0792** | **0.0226** |
| M2 genel + medikal | 0.0795 | 0.0228 |

Bu sonuç M1'in genel Türkçe başarımını iyileştirdiğini, M2'nin ise bu kazanımı büyük
ölçüde koruduğunu gösterir.

### Metrikler nasıl okunmalı?

| Metrik | Tanım | Yorum |
|---|---|---|
| WER | `(değiştirme + silme + ekleme) / referans kelime sayısı` | Düşük değer daha iyidir. `0.0792`, yaklaşık %7,92 kelime hatası anlamına gelir. |
| CER | Aynı hata hesabının karakter düzeyinde uygulanması | Türkçedeki ekler ve yazım farklılıkları için WER'i tamamlar. Düşük değer daha iyidir. |

Tablodaki değerler 320 gerçek ve medikal olmayan Türkçe klibin klip-bazlı makro
ortalamasıdır. Bu sonuçlar her kayıt ortamında aynı başarımın garanti edildiği anlamına
gelmez; mikrofon, aksan, konuşma hızı ve arka plan gürültüsü dağılımı değiştirebilir.

20 model ve 1.060 genel Türkçe klibi kapsayan geniş benchmark:
[`turkmedstt/turkish-asr-benchmark`](https://huggingface.co/datasets/turkmedstt/turkish-asr-benchmark).

## Önerilen kullanım alanları

- Türkçe ses kayıtlarının araştırma amaçlı çevrimdışı transkripsiyonu
- Türkçe ASR model karşılaştırmaları ve hata analizi
- Alan-özel modeller için başlangıç noktası veya kontrollü temel model
- İnsan denetimli altyazı ve metin hazırlama iş akışları

## Sınırlamalar

- Klinik kullanım veya otomatik karar verme için tasarlanmamıştır.
- Aksan, gürültü, örtüşen konuşma ve alan dışı terminoloji başarımı düşürebilir.
- Eğitim kaynaklarının tamamı bu repo içinde yeniden dağıtılmaz.
- Konuşmacı kimliği, zaman damgası, diarization veya noktalama doğruluğu ayrıca
  değerlendirilmemiştir.
- WER ve CER dilsel doğruluğu ölçer; metnin olgusal veya klinik olarak doğru olduğunu
  garanti etmez.

## Kullanım

```python
import torch
from transformers import pipeline

model_id = "turkmedstt/whisper-large-v3-turkish-general"
device = 0 if torch.cuda.is_available() else -1
dtype = torch.float16 if torch.cuda.is_available() else torch.float32

transcriber = pipeline(
    "automatic-speech-recognition",
    model=model_id,
    torch_dtype=dtype,
    device=device,
)

result = transcriber(
    "ornek.wav",
    generate_kwargs={"language": "tr", "task": "transcribe"},
)
print(result["text"])
```

Model birleştirilmiş tam ağırlıkları içerdiği için ayrıca LoRA adaptörü yüklenmez.
GPU kullanımı önerilir; CPU üzerinde çıkarım mümkündür ancak `large-v3` boyutu nedeniyle
yavaş olabilir. Girdi sesi kod tarafından Whisper işlemcisine uygun örnekleme oranına
dönüştürülmelidir.

## Repo içeriği

- `model.safetensors`: birleştirilmiş model ağırlıkları
- `config.json`, `generation_config.json`: model ve üretim ayarları
- tokenizer ve feature extractor dosyaları: ses/metin ön ve son işleme bileşenleri
- `training_metadata.json`: yayın için saklanan eğitim özeti

## Lisans ve kaynaklar

Birleştirilmiş model Apache-2.0 altında yayımlanır. Temel `whisper-large-v3` modeli
MIT lisanslıdır. Eğitim veri kaynaklarının kendi lisansları ve kullanım koşulları
geçerlidir; bu repo ham eğitim seslerini içermez.

## Atıf

TurkMedSTT bitirme projesi, 2026.

## Katkı verenler

- [Muhammed Kumcu](https://huggingface.co/muhammedkumcu)
- [Yağmur Tuncer](https://huggingface.co/yagmurtuncer)

Muhammed Kumcu ve Yağmur Tuncer; proje tasarımı, veri hazırlama, model eğitimi,
yazılım geliştirme, değerlendirme, dokümantasyon ve yayın çalışmalarını birlikte
yürütmüştür.

## Teşekkür

Gerçek-ses değerlendirme kayıtlarına gönüllü katkıları için Zeynep Zehra Kumcu ve Yusuf Uysal'a
teşekkür ederiz. Bu kayıtlar yayımlanmamış, yalnız anonim ve toplu sonuçlar raporlanmıştır.