# مقسّمات الرموز

يحوّل مُجزِّئ الرموز النص إلى متجهات، وهي المدخلات إلى النموذج. إنه يُطبّع النص ويقسمه، ويطبّق خوارزمية تجزئة الرموز، ويضيف رموزًا خاصة، ويفكّ ترميز المعرّفات الناتجة مرة أخرى إلى نص.

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

يتناول هذا الدليل التحميل، والترميز، وفك الترميز، ومعالجة الدفعات، والخوادم الخلفية المتاحة لمعالج النص.

## تحميل مُجزِّئ

حمّل مُجزِّئًا (tokenizer) باستخدام فئة [AutoTokenizer](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer) أو فئة مُجزِّئ محددة لنموذج معين.

[AutoTokenizer.from_pretrained()](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer.from_pretrained) reads the model config, resolves the correct tokenizer class, and returns an instance of it. You don't need to know the tokenizer class beforehand. Most tokenizers resolve to a subclass of [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend), a fast Rust-based tokenizer from the [Tokenizers](https://huggingface.co/docs/tokenizers/index) library.

يُعد التحميل باستخدام [AutoTokenizer](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer) الطريقة الموصى بها.

```py
from transformers import AutoTokenizer

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

فئة الترميز الخاصة بنموذج ما هي [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend) مُهيّأ مسبقًا يستخدم إعدادات الترميز الدقيقة (المُطَبِّع، مُقسِّم ما قبل الترميز، اتفاقيات الرموز الخاصة، إلخ) التي تم تدريب النموذج بها.

استخدم فئة خاصة بالنموذج لتهيئة مُجزِّئ فارغ للتدريب أو لتسليم حُجج خاصة بالنموذج مثل `vocab` أو `merges` (راجع دليل [تخصيص المُجزِّئات](./custom_tokenizers) لمعرفة كيفية ذلك). المُجزِّئ الفارغ هو الحد الأدنى ويحتوي فقط على الرموز الخاصة بالنموذج مثل `<pad>`، `<eos>`، أو `<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)
```

## ترميز وفك الترميز

تقوم طريقة [TokenizersBackend.__call__()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) بتشفير النص أو دفعة من النصوص إلى `input_ids` و`attention_mask` ومدخلات النموذج الأخرى. كما تتحكم في عملية الحشو (padding) والقطع (truncation) وإدراج الرموز الخاصة.

```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/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) ذلك، لكنه يعيد `input_ids` فقط.

```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/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) تسلسلًا واحدًا أو دفعة من `input_ids` المُرمّزة إلى نص.

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

يحافظ [TokenizersBackend.decode()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) على مسافات الترميز الدقيقة. اضبط `clean_up_tokenization_spaces` لإزالة المسافات قبل علامات الترقيم، و`skip_special_tokens` لإزالة الرموز الخاصة من المخرجات.

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

## رموز خاصة

تُشير الرموز الخاصة إلى الحدود الهيكلية في تسلسل، مثل موضع بداية التسلسل أو مواضع الحشو. يحدد كل نموذج مجموعته الخاصة من الرموز الخاصة. يضيف المُجزِّئ هذه الرموز عند استدعائه.

```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`. تستخدم النماذج متعددة الوسائط هذه الرموز كعناصر بديلة للصور أو الفيديو أو الصوت.

```py
from transformers import AutoTokenizer

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

## المعالجة الدفعية

يعالج المعالجة الدفعية (Batch processing) تسلسلات متعددة في استدعاء واحد. يتعامل [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend) مع الدفعات الكبيرة بشكل أسرع لأن واجهته الخلفية (backend) المبنية على Rust تُوازٍ العمل عبر عدة خيوط (threads).

```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) والقطع (Truncation) استراتيجيات للتعامل مع التسلسلات ذات الأطوال المتغيرة.

### الحشو

تضيف عملية الحشو رموزًا خاصةً حتى تتطابق التسلسلات الأقصر مع أطول تسلسل في الدفعة. يحدد قناع الانتباه مواضع الحشو على أنها `0` حتى يتجاهلها النموذج. اضبط `padding=True` للحشو حتى أطول تسلسل، أو مرّر `max_length` للحشو حتى حجم ثابت.

```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]
> تقوم نماذج اللغة الكبيرة بتعبئة النص من جهة *اليسار* لتجنب تعطيل عملية التوليد، التي تتنبأ بالرمز التالي من جهة *اليمين*.

### الاقتطاع

يقوم التقصير (Truncation) بقص الرموز (tokens) بحيث تتناسب التسلسلات مع الحد الأقصى للطول. فعّله عن طريق تعيين `truncation=True` وتحديد `max_length`.

يعمل الحشو (Padding) والقطع (Truncation) معًا. حيث تكتسب التسلسلات القصيرة رموز حشو بينما تفقد التسلسلات الطويلة الرموز النهائية. وبمجموعهما، ينتجان متجهًا مستطيلًا مضغوطًا.

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

## واجهات الخلفية

يُعرَّف كل نموذج مُجزِّئ في ملف واحد ويدعم أربعة أنظمة خلفية للتجزئة.

| الواجهة الخلفية                  | التنفيذ                                                | الوصف                                    |
| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------- |
| [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend)    | [مقسّمات الرموز](https://huggingface.co/docs/tokenizers)          | الافتراضي لمعظم النماذج                        |
| [SentencePieceBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.SentencePieceBackend) | [SentencePiece](https://github.com/google/sentencepiece)      | النماذج التي تتطلب SentencePiece                 |
| [PythonBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.PythonBackend)        | Python                                                        | النماذج التي تتطلب مُجزِّئات مخصصة متخصصة |
| [MistralCommonBackend](/docs/transformers/main/ar/model_doc/mistral#transformers.MistralCommonBackend) | [mistral-common](https://mistralai.github.io/mistral-common/) | نماذج Mistral وPixtral                     |

تورث جميع الخوادم الخلفية من [PreTrainedTokenizerBase](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) وتشارك نفس واجهات برمجة التطبيقات (APIs) للتشفير وفك التشفير والتعبئة والتقطيع والحفظ والتحميل. والفرق هو خط أنابيب الترميز الذي يعمل في الخلفية.

يختار [AutoTokenizer](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer) أفضل واجهة خلفية متاحة عند استدعاء [from_pretrained()](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer.from_pretrained).

1. يقوم بقراءة ملف `tokenizer_config.json` من أجل الحقل `tokenizer_class`.
2. يطابق السجل `tokenizer_class` مع اسم فئة. والفئة المُحلَّلة ترث من أحد الخلفيات الأربعة. على سبيل المثال، ترث [GemmaTokenizer](/docs/transformers/main/ar/model_doc/gemma#transformers.GemmaTokenizer) من [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend)، وترث [SiglipTokenizer](/docs/transformers/main/ar/model_doc/siglip#transformers.SiglipTokenizer) من [SentencePieceBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.SentencePieceBackend). بعض النماذج، مثل GLM، تُخاط مباشرة إلى [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend) لأن ملف `tokenizer.json` يصف خط المعالجة بالكامل. وتوجد [GemmaTokenizer](/docs/transformers/main/ar/model_doc/gemma#transformers.GemmaTokenizer) كفئة فرعية لأنها تُعرّف إعدادات إضافية خاصة بالنموذج بلغة Python لا يلتقطها `tokenizer.json`. وعندما لا يكون الخلفية مثل mistral-common مثبّتًا، يلجأ [AutoTokenizer](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer) إلى [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend).

### العودة إلى TokenizersBackend

بعض النماذج لا تملك فئة مخصّصة لمُجزّئ الرموز (tokenizer)، وبعض نقاط التفتيش تحتوي على `tokenizer_class` لا يتطابق مع ملف `tokenizer.json` الفعلي الخاص بها. يتعامل [AutoTokenizer](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer) مع الحالتين من خلال تحميل خط الأنابيب من `tokenizer.json` عبر [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend) العام. ويُعطي الأولوية للمُجزّئ المُسلسَل (serialized) على اسم الفئة من Hub، مما يُصلح مشاكل مثل تلك التي تنشأ عندما يُنتج `tokenizer_class` غير متطابق معرّفات رموز (token ids) غير صحيحة.

يُحلّ نقطة التفتيش إلى `TokenizersBackend` عامّة لأحد ثلاثة أسباب.

| السبب                              | السلوك                                                                                                                                 | أمثلة                                                                       |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| لا توجد فئة مخصّصة لمُقسِّم        | يُطابق نوع النموذج مباشرةً `TokenizersBackend` لأن `tokenizer.json` يصف خط الأنابيب بالكامل.                               | GLM، Granite، OLMo 2، GPT BigCode                                              |
| فئة مُجزِّئ Hub غير الصحيحة المعروفة | `tokenizer_class` المسجّل على Hub غير صحيح لنوع النموذج، لذا يتجاهله `AutoTokenizer` ويحمّل `tokenizer.json` بدلاً منه. | DeepSeek V3، LLaVA، Qwen2، ModernBERT                                          |
| تجاوز نقطة التفتيش المحددة        | يتم مطابقة نقطة تفتيش لا يزال تكوينها في Hub بحاجة إلى إصلاح عبر معرّف النموذج الخاص بها، ثم يُجبر على استخدام الخلفية.                                    | `deepseek-ai/DeepSeek-R1-Distill-*`, `Salesforce/blip2-*`, `google/umt5-small` |

تزداد أنواع النماذج ونقاط التفتيش المتأثرة مع تصحيح الإعدادات على Hub. للاطلاع على المجموعة الحالية، راجع تعريفات `MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS` و`MODEL_IDS_TO_TOKENIZERS_BACKEND` في [tokenization_auto.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/auto/tokenization_auto.py).

تكون آلية الاحتياط تلقائية ولا تُغيّر طريقة استدعاء [from_pretrained()](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer.from_pretrained). يقوم المُرمِّز الناتج بتشفير وفك التشفير تماماً كما يحدده `tokenizer.json`.

تحقق من الخلفية التي يستخدمها مُجزِّئ الرموز (tokenizer) باستخدام خاصية `backend`.

```py
from transformers import AutoTokenizer

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

## فحص بنية مُجزّئ النص

افحص المكونات الداخلية لمُجزّئ الرموز (المُطَبِّع، مُجزّئ الرموز المسبق، النموذج، المُفكِّك) باستخدام الخاصية `_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)
```

## الموارد

- يناقش منشور [التجزئة في Transformers v5](https://huggingface.co/blog/tokenizers) الدوافع وراء واجهات التجزئة الجديدة.
- راجع [دليل الترحيل](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#tokenization) للحصول على نظرة عامة على تغييرات الترميز.