# 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 ``, `` sau ``. ```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"]) ['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"]) ['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": ""} ) ``` ## 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 [`~AutoTokenizer.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.