transformers/main/ro/fast_tokenizers.md

# Tokenizere

Un tokenizer convertește text în tensori, care sunt input-urile unui model. Acesta normalizează și împarte textul, aplică algoritmul de tokenization, adaugă token-uri speciale și decodifică id-urile de output înapoi în text.

```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]])
}
```

Acest ghid acoperă încărcarea, encodarea, decodarea, procesarea în batch și backend-urile disponibile pentru tokenizere.

## Încarcă un tokenizer

Încarcă un tokenizer cu clasa `AutoTokenizer` sau cu o clasă de tokenizer specifică modelului.

`AutoTokenizer.from_pretrained()` citește config-ul modelului, rezolvă clasa corectă de tokenizer și returnează o instanță a ei. Nu trebuie să știi clasa de tokenizer dinainte. Majoritatea tokenizere-lor se rezolvă la o subclasă a `TokenizersBackend`, un tokenizer rapid bazat pe Rust din biblioteca [Tokenizers](https://huggingface.co/docs/tokenizers/index).

Încărcarea cu `AutoTokenizer` este abordarea recomandată.

```py
from transformers import AutoTokenizer

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

O clasă de tokenization specifică modelului este un `TokenizersBackend` pre-configurat care folosește exact configurația de tokenization (normalizator, pre-tokenizator, convenții pentru token-uri speciale etc.) cu care a fost antrenat modelul.

Folosește o clasă specifică modelului ca să inițializezi un tokenizer gol pentru antrenare sau ca să pasezi argumente specifice modelului precum `vocab` sau `merges` (vezi ghidul [Personalizarea tokenizere-lor](./custom_tokenizers) ca să afli cum). Un tokenizer gol este minimal și conține doar token-urile speciale ale modelului, cum ar fi `<pad>`, `<eos>` sau `<bos>`.

```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)
```

## Encodare și decodare

Metoda `TokenizersBackend.__call__()` encodează text sau un batch de text în `input_ids`, `attention_mask` și alte input-uri pentru model. Controlează și padding-ul, trunchierea și inserarea token-urilor speciale.

```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()` este similar, dar returnează doar `input_ids`.

```py
from transformers import AutoTokenizer

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

`TokenizersBackend.decode()` convertește o secvență sau un batch de `input_ids` tokenizate înapoi în text.

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

`TokenizersBackend.decode()` păstrează spațierea exactă a operației de tokenization. Setează `clean_up_tokenization_spaces` ca să elimini spațiile de dinaintea punctuației și `skip_special_tokens` ca să scoți token-urile speciale din output.

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

## Token-uri speciale

Token-urile speciale marchează limitele structurale dintr-o secvență, cum ar fi începutul secvenței sau pozițiile de padding. Fiecare model definește propriul set de token-uri speciale. Tokenizer-ul le adaugă când îl apelezi.

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

Înregistrează token-uri speciale cu nume suplimentare folosind argumentul `extra_special_tokens`. Modelele multimodale le folosesc ca placeholders pentru imagini, video sau audio.

```py
from transformers import AutoTokenizer

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

## Procesare în batch

Procesarea în batch tokenizează mai multe secvențe într-un singur apel. `TokenizersBackend` gestionează batch-uri mari mai rapid pentru că backend-ul său bazat pe Rust paralelizează munca pe thread-uri.

```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"
)
```

Procesarea în batch presupune că toate secvențele au aceeași lungime. Padding-ul și trunchierea sunt strategii ca să gestionezi secvențe de lungimi diferite.

### Padding

Padding-ul adaugă token-uri speciale ca secvențele mai scurte să aibă aceeași lungime cu cea mai lungă din batch. Masca de atenție marchează pozițiile de padding cu `0` pentru ca modelul să le ignore. Setează `padding=True` ca să faci padding până la cea mai lungă secvență sau pasează `max_length` ca să faci padding la o dimensiune fixă.

```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]
> Modelele lingvistice mari fac padding pe partea *stângă* ca să nu perturbe generarea, care prezice token-ul următor din partea *dreaptă*.

### Trunchiere

Trunchierea taie token-uri ca o secvență să se încadreze într-o lungime maximă. Setează `truncation=True` și specifică `max_length` ca să o activezi.

Padding-ul și trunchierea funcționează împreună. Secvențele scurte primesc token-uri de padding, iar cele lungi pierd token-uri de la coadă. Împreună, produc un tensor dreptunghiular compact.

```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]
    ])
}
```

## Backend-uri

Fiecare tokenizer de model este definit într-un singur fișier și suportă patru backend-uri de tokenization.

| backend | implementare | descriere |
|---|---|---|
| `TokenizersBackend` | [Tokenizers](https://huggingface.co/docs/tokenizers) | implicit pentru majoritatea modelelor |
| `SentencePieceBackend` | [SentencePiece](https://github.com/google/sentencepiece) | modele care necesită SentencePiece |
| `PythonBackend` | Python | modele care necesită tokenizere personalizate specializate |
| `MistralCommonBackend` | [mistral-common](https://mistralai.github.io/mistral-common/) | modele Mistral și Pixtral |

Toate backend-urile moștenesc din `PreTrainedTokenizerBase` și împart aceleași API-uri pentru encodare, decodare, padding, trunchiere, salvare și încărcare. Diferența constă în pipeline-ul de tokenization care rulează pe dedesubt.

`AutoTokenizer` selectează cel mai bun backend disponibil când apelezi `from_pretrained()`.

1. Citește fișierul `tokenizer_config.json` pentru câmpul `tokenizer_class`.
2. Registrul potrivește `tokenizer_class` cu un nume de clasă. Clasa rezolvată moștenește din unul din cele patru backend-uri. De exemplu, `GemmaTokenizer` moștenește din `TokenizersBackend`, iar `SiglipTokenizer` moștenește din `SentencePieceBackend`.

    Unele modele, ca GLM, se mapează direct la `TokenizersBackend` pentru că fișierul `tokenizer.json` descrie complet pipeline-ul. `GemmaTokenizer` există ca subclasă deoarece definește setări suplimentare specifice modelului în Python pe care `tokenizer.json` nu le captează.

    ```py
    TOKENIZER_MAPPING_NAMES = OrderedDict([
        ("gemma2", "GemmaTokenizer" if is_tokenizers_available() else None),
        ("glm", "TokenizersBackend" if is_tokenizers_available() else None),
        (
            "mistral",
            "MistralCommonBackend"
            if is_mistral_common_available()
            else ("TokenizersBackend" if is_tokenizers_available() else None),
        ),
        ("siglip", "SiglipTokenizer" if is_sentencepiece_available() else None),
        ...
    ]
    ```
    
    Când un backend ca mistral-common nu este instalat, `AutoTokenizer` revine la `TokenizersBackend`.

Verifică ce backend folosește un tokenizer cu proprietatea `backend`.

```py
from transformers import AutoTokenizer

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

## Inspectează arhitectura tokenizer-ului

Inspectează componentele interne ale unui tokenizer (normalizator, pre-tokenizator, model, decoder) cu atributul `_tokenizer`.

```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)
```

## Resurse

- Postarea [Tokenization in Transformers v5](https://huggingface.co/blog/tokenizers) discută motivația din spatele noilor backend-uri de tokenization.
- Consultă [ghidul de migrare](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#tokenization) pentru o prezentare a schimbărilor de tokenization.