# Tokenizers

Bir tokenizer, metni bir modelin girdileri olan tensörlere dönüştürür. Metni normalize eder ve böler, tokenizasyon algoritmasını uygular, özel token'lar ekler ve çıktı kimliklerini tekrar metne çözer.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt")
{
    'input_ids': tensor([[     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265]]),
    'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])
}
```

Bu kılavuz, yükleme, kodlama, çözümlü kodlama, toplu işleme ve kullanılabilir tokenizer arka uçlarını kapsar.

## Bir tokenizer yükleyin

Bir [AutoTokenizer](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoTokenizer) sınıfı veya modele özgü bir tokenizer sınıfı ile bir tokenizer yükleyin.

[AutoTokenizer.from_pretrained()](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoTokenizer.from_pretrained) model yapılandırmasını okur, doğru tokenizer sınıfını çözer ve bu sınıfın bir örneğini döndürür. Tokenizer sınıfını önceden bilmenize gerek yoktur. Çoğu tokenizer, [Tokenizers](https://huggingface.co/docs/tokenizers/index) kütüphanesinden hızlı, Rust tabanlı bir tokenizer olan [TokenizersBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.TokenizersBackend) alt sınıfına çözümlenir.

[AutoTokenizer](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoTokenizer) ile yükleme önerilen yaklaşımdır.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
```

Model-özel bir tokenizasyon sınıfı, bir modelin eğitildiği tam tokenizasyon yapılandırmasını (normalizör, ön-tokenizör, özel token sözleşmeleri vb.) kullanan önceden yapılandırılmış bir [TokenizersBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.TokenizersBackend)'dir.

Eğitim için boş bir tokenizer başlatmak veya `vocab` ya da `merges` gibi modele özgü argümanları iletmek için modele özgü bir sınıf kullanın (nasıl yapılacağını öğrenmek için [Tokenizer'ları özelleştirme](./custom_tokenizers) kılavuzuna bakın). Boş bir tokenizer minimaldir ve yalnızca `<pad>`, `<eos>` veya `<bos>` gibi bir modelin özel token'larını içerir.

```py
from transformers import GemmaTokenizer

tokenizer = GemmaTokenizer()
corpus = [
    ["Sphinx of black quartz, judge my vow."],
    ["Pack my box with five dozen liquor jugs."],
    ["How vexingly quick daft zebras jump!"],
]
new_tokenizer = tokenizer.train_new_from_iterator(corpus, vocab_size=1000)
```

## Kodlama ve çözümlü

[TokenizersBackend.__call__()](/docs/transformers/v5.23.0/tr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) metodu, metni veya bir metin grubunu `input_ids`, `attention_mask` ve diğer model girdilerine kodlar. Ayrıca dolguyu (padding), kırpma işlemini (truncation) ve özel token eklemeyi kontrol eder.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt")
{
    'input_ids': tensor([[     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265]]),
    'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])
}
```

[TokenizersBackend.encode()](/docs/transformers/v5.23.0/tr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) benzerdir ancak yalnızca `input_ids` döndürür.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.")
[2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]
```

[TokenizersBackend.decode()](/docs/transformers/v5.23.0/tr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode), tek bir diziyi veya `input_ids` olarak tokenize edilmiş bir partiyi metne geri dönüştürür.

```py
tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'
```

[TokenizersBackend.decode()](/docs/transformers/v5.23.0/tr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) tam tokenizasyon boşluklarını korur. Noktalama işaretlerinden önceki boşlukları kaldırmak için `clean_up_tokenization_spaces` değerini ayarlayın ve çıktıdan özel tokenları çıkarmak için `skip_special_tokens` değerini ayarlayın.

```py
tokenizer.decode(input_ids, skip_special_tokens=True)
'Sphinx of black quartz, judge my vow.'
```

## Özel jetonlar

Özel jetonlar, bir dizide yapısal sınırları işaretler; örneğin dizinin başlangıcı veya dolgu konumları. Her model kendi özel jeton kümesini tanımlar. Tokenizer'ı çağırdığınızda bunları ekler.

```py
input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.")
[2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]
tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'
```

`extra_special_tokens` argümanıyla ek adlandırılmış özel jetonlar kaydedin. Çok modlu modeller bunları görsel, video veya ses için yer tutucu olarak kullanır.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained(
    "google/gemma-3-4b-pt",
    extra_special_tokens={"image_token": "<image>"}
)
```

## Toplu işleme

Batch processing, birden fazla diziyi tek bir çağrıda tokenizasyon yapar. [TokenizersBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.TokenizersBackend), Rust tabanlı arka ucu işleri iş parçacıkları arasında paralelleştirdiği için büyük batch'leri daha hızlı işler.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt"
)
```

Toplu işleme, tüm dizilerin aynı uzunlukta olmasını gerektirir. Dolgu ve kırpma, farklı uzunluklardaki dizileri işlemek için kullanılan stratejilerdir.

### Dolgu

Padding, bir batch içindeki en uzun diziyle eşleşmesi için daha kısa dizilere özel token'lar ekler. Dikkat maskesi, modelin bunları yok sayması için padding konumlarını `0` olarak işaretler. En uzun diziye kadar padding yapmak için `padding=True` ayarlayın veya sabit bir boyuta kadar padding yapmak için `max_length` parametresini iletin.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt",
    padding=True,
)
{
    'input_ids': tensor([
        [     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265],
        [     0,      2,   6519,    970,   3741,    675,   4105,  25955,  42184, 225789, 235265],
        [     0,      2,   2299,  73378,  17844,   4320, 224463,   4949,  48977,  9902, 235341]
    ]),
    'attention_mask': tensor([
        [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
        [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
        [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
    ])
}
```

> [!NOTE]
> Büyük dil modelleri, *sağ* taraftan bir sonraki token'ı tahmin eden üretimi bozmamak için *sol* tarafta dolgu yapar.

### Kesme

Truncation, bir dizinin maksimum uzunluğa sığması için jetonları kırpma işlemidir. Bunu etkinleştirmek için `truncation=True` ayarlayın ve `max_length` belirtin.

Doldurma ve kısaltma birlikte çalışır. Kısa dizilere dolgu jetonları eklenirken uzun dizilerin sonundaki jetonlar atılır. Birlikte, paketlenmiş dikdörtgen bir tensör oluştururlar.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt",
    padding=True,
    truncation=True,
    max_length=5
)
{
    'input_ids': tensor([
        [     2, 235277,  82913,    576,   2656],
        [     2,   6519,    970,   3741,    675],
        [     2,   2299,  73378,  17844,   4320]
    ]),
    'attention_mask': tensor([
        [1, 1, 1, 1, 1],
        [1, 1, 1, 1, 1],
        [1, 1, 1, 1, 1]
    ])
}
```

## Arka Uçlar

Her model tokenizer'ı tek bir dosyada tanımlanır ve dört tokenizasyon arka ucunu destekler.

| backend                  | uygulama                                                | açıklama                                    |
| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------- |
| [TokenizersBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.TokenizersBackend)    | [Tokenizers](https://huggingface.co/docs/tokenizers)          | çoğu model için varsayılan                        |
| [SentencePieceBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.SentencePieceBackend) | [SentencePiece](https://github.com/google/sentencepiece)      | SentencePiece gerektiren modeller                 |
| [PythonBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.PythonBackend)        | Python                                                        | özel, özelleştirilmiş tokenizörler gerektiren modeller |
| [MistralCommonBackend](/docs/transformers/v5.23.0/tr/model_doc/mistral#transformers.MistralCommonBackend) | [mistral-common](https://mistralai.github.io/mistral-common/) | Mistral ve Pixtral modelleri                     |

Tüm arka uçlar [PreTrainedTokenizerBase](/docs/transformers/v5.23.0/tr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) sınıfından türetilir ve kodlama, çözümleme, dolgu, kısaltma, kaydetme ve yükleme için aynı API'leri paylaşır. Fark, altta çalışan tokenizasyon hattının hangisi olduğudur.

[AutoTokenizer](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoTokenizer), [from_pretrained()](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoTokenizer.from_pretrained) çağrıldığında kullanılabilir en iyi arka ucu seçer.

1. `tokenizer_class` alanı için `tokenizer_config.json` dosyasını okur.
2. Kayıt, `tokenizer_class` değerini bir sınıf adıyla eşleştirir. Çözümlenen sınıf, dört backend'den birinden türetilir. Örneğin, [GemmaTokenizer](/docs/transformers/v5.23.0/tr/model_doc/gemma#transformers.GemmaTokenizer) [TokenizersBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.TokenizersBackend) sınıfından türetilirken, [SiglipTokenizer](/docs/transformers/v5.23.0/tr/model_doc/siglip#transformers.SiglipTokenizer) [SentencePieceBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.SentencePieceBackend) sınıfından türetilir. GLM gibi bazı modeller, `tokenizer.json` dosyası iş akışını tamamen tanımladığı için doğrudan [TokenizersBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.TokenizersBackend) sınıfına eşlenir. [GemmaTokenizer](/docs/transformers/v5.23.0/tr/model_doc/gemma#transformers.GemmaTokenizer), `tokenizer.json` dosyasının yakalayamadığı ek model özel ayarlarını Python'da tanımladığı için bir alt sınıf olarak varlığını sürdürür. mistral-common gibi bir backend yüklü değilse, [AutoTokenizer](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoTokenizer) [TokenizersBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.TokenizersBackend) sınıfına geri düşer.

### TokenizersBackend'e geri dön

Bazı modellerin ayrı bir tokenizer sınıfı yoktur ve bazı checkpoint'lerde, gerçek `tokenizer.json` dosyalarıyla eşleşmeyen bir `tokenizer_class` bulunur. [AutoTokenizer](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoTokenizer), pipeline'ı genel [TokenizersBackend](/docs/transformers/v5.23.0/tr/main_classes/tokenizer#transformers.TokenizersBackend) üzerinden `tokenizer.json` dosyasından yükleyerek her iki durumu da ele alır. Hub'dan gelen sınıf adından ziyade serileştirilmiş tokenizer'ı önceliklendirir; bu da eşleşmeyen bir `tokenizer_class`'ın hatalı token kimlikleri üretmesi gibi sorunları giderir.

Bir checkpoint, üç nedenden biri için genel bir `TokenizersBackend` olarak çözümlenir.

| Neden                              | Davranış                                                                                                                                 | Örnekler                                                                       |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Özel bir tokenizer sınıfı yok        | Model türü, `tokenizer.json` hattı tamamen tanımladığı için doğrudan `TokenizersBackend`'e eşlenir.                               | GLM, Granite, OLMo 2, GPT BigCode                                              |
| Bilinen hatalı Hub tokenizer sınıfı | Hub'da kayıtlı `tokenizer_class`, model türü için yanlış olduğundan `AutoTokenizer` bunu yoksayar ve bunun yerine `tokenizer.json` dosyasını yükler. | DeepSeek V3, LLaVA, Qwen2, ModernBERT                                          |
| Belirli bir kontrol noktası geçersiz kılma        | Hub yapılandırmasında hâlâ düzeltme gerektiren bir checkpoint, model kimliğiyle eşleştirilir ve arka uca zorlanır.                                    | `deepseek-ai/DeepSeek-R1-Distill-*`, `Salesforce/blip2-*`, `google/umt5-small` |

Etkilenen model türleri ve kontrol noktaları, Hub üzerindeki yapılandırmalar düzeltildikçe artar. Güncel küme için [tokenization_auto.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/auto/tokenization_auto.py) içindeki `MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS` ve `MODEL_IDS_TO_TOKENIZERS_BACKEND` tanımlarına bakın.

Yedekleme otomatik olarak gerçekleşir ve [from_pretrained()](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoTokenizer.from_pretrained) çağrısını nasıl yaptığınızı değiştirmez. Oluşan tokenizer, `tokenizer.json`'in belirttiği şekilde birebir kodlama ve çözümlendirme yapar.

Bir belirteç ayrıştırıcısının hangi arka ucu kullandığını `backend` özelliğiyle kontrol edin.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer.backend
'tokenizers'
```

## Tokenizör mimarisini incele

Bir tokenizer'ın iç bileşenlerini (normalizer, pre-tokenizer, model, decoder) `_tokenizer` özniteliğiyle inceleyin.

```py
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
print(tokenizer._tokenizer.normalizer)
print(tokenizer._tokenizer.pre_tokenizer)
print(tokenizer._tokenizer.model)
print(tokenizer._tokenizer.decoder)
```

## Kaynaklar

- [Transformers v5'te Tokenizasyon](https://huggingface.co/blog/tokenizers) yazısı, yeni tokenizasyon altyapılarının arkasındaki motivasyonu ele alıyor.
- Tokenizasyon değişikliklerinin genel bakışını için [göç kılavuzunu](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#tokenization) inceleyin.

