# النماذج

تُنفّذ الفئة الأساسية [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel) الطرق المشتركة لتحميل/حفظ النموذج من ملف أو مجلد محلي، أو من إعدادات نموذج مُدرَّب مسبقًا توفره المكتبة (يتم تنزيله من HuggingFace's Hub).

يُنفّذ [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel) أيضًا بعض الطرق المشتركة بين جميع النماذج من أجل:

- تغيير حجم تضمينات الرموز المدخلة عند إضافة رموز جديدة إلى المفردات

تُعرَّف الطرق الأخرى المشتركة لكل نموذج في [ModuleUtilsMixin](/docs/transformers/main/ar/main_classes/model#transformers.modeling_utils.ModuleUtilsMixin) و[GenerationMixin](/docs/transformers/main/ar/main_classes/text_generation#transformers.GenerationMixin).

## PreTrainedModel[[transformers.PreTrainedModel]]

#### transformers.PreTrainedModel[[transformers.PreTrainedModel]]

```python
transformers.PreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L1068)

الفئة الأساسية لجميع النماذج.

يتولى [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel) مهمة تخزين إعدادات النماذج، ويتعامل مع طرق تحميل النماذج وتنزيلها وحفظها، بالإضافة إلى بعض الطرق المشتركة بين جميع النماذج:

- تغيير حجم التضمينات المدخلة

خصائص الفئة (تُستبدل من قِبل الفئات المشتقة):

- **config_class** ([PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig)) -- فئة فرعية من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) تُستخدم كفئة إعدادات لهذه البنية النموذجية.
- **base_model_prefix** (`str`) -- نص يشير إلى الخاصية المرتبطة بالنموذج الأساسي في الفئات المشتقة ذات البنية نفسها التي تضيف وحدات فوق النموذج الأساسي.
- **main_input_name** (`str`) -- اسم المدخل الرئيسي للنموذج (غالباً `input_ids` لنماذج معالجة اللغة الطبيعية، و`pixel_values` لنماذج الرؤية، و`input_values` لنماذج الكلام).
- **can_record_outputs** (dict):

#### push_to_hub[[transformers.PreTrainedModel.push_to_hub]]

```python
push_to_hub(repo_id: str, commit_message: str | None = None, commit_description: str | None = None, private: bool | None = None, token: bool | str | None = None, revision: str | None = None, create_pr: bool = False, max_shard_size: int | str | None = '50GB', tags: list[str] | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py#L822)

**المعاملات:**

repo_id (`str`) : اسم المستودع الذي تريد دفع نموذجك إليه. يجب أن يحتوي على اسم مؤسستك عند الدفع إلى مؤسسة محددة.

commit_message (`str`، *اختياري*) : الرسالة التي سيتم الالتزام بها أثناء الدفع. ستكون الافتراضية `"Upload model"`.

commit_description (`str`، *اختياري*) : وصف الالتزام الذي سيتم إنشاؤه

private (`bool`، *اختياري*) : ما إذا كان سيتم جعل المستودع خاصًا. إذا كانت القيمة `None` (الافتراضي)، فسيكون المستودع عامًا ما لم يكن الافتراضي الخاص بالمنظمة هو الخاص. يتم تجاهل هذه القيمة إذا كان المستودع موجودًا مسبقًا.

token (`bool` أو `str`، *اختياري*) : الرمز الذي يُستخدم كترخيص HTTP bearer للملفات البعيدة. إذا كان `True` (الافتراضي)، فسيتم استخدام الرمز الذي تم إنشاؤه عند تشغيل `hf auth login` (المخزّن في `~/.huggingface`).

revision (`str`، *اختياري*) : الفرع الذي سيتم دفع الملفات المرفوعة إليه.

create_pr (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم إنشاء طلب دمج (PR) مع الملفات المرفوعة أم الالتزام مباشرة.

max_shard_size (`int` أو `str`، *اختياري*، القيمة الافتراضية `"50GB"`) : ينطبق على النماذج فقط. الحد الأقصى لحجم نقطة التفتيش قبل تقسيمها إلى أجزاء. ستكون نقاط التفتيش المقسمة بعد ذلك أصغر من هذا الحجم. إذا تم التعبير عنها كنص، فيجب أن تتكون من أرقام تليها وحدة (مثل `"5MB"`).

tags (`list[str]`، *اختياري*) : قائمة بالوسوم التي سيتم دفعها إلى Hub.

قم برفع ملف النموذج إلى 🤗 Model Hub.

أمثلة:

```python
from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

# Push the model to your namespace with the name "my-finetuned-bert".
model.push_to_hub("my-finetuned-bert")

# Push the model to an organization with the name "my-finetuned-bert".
model.push_to_hub("huggingface/my-finetuned-bert")
```

#### activation_checkpointing_disable[[transformers.PreTrainedModel.activation_checkpointing_disable]]

```python
activation_checkpointing_disable()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3249)

يعطّل نقطة التفعيل (activation checkpointing) للنموذج الحالي.

#### activation_checkpointing_enable[[transformers.PreTrainedModel.activation_checkpointing_enable]]

```python
activation_checkpointing_enable(activation_checkpointing_kwargs = None, every_n_layers: int = 1, offload: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3110)

**المعاملات:**

every_n_layers (`int`، *اختياري*، القيمة الافتراضية 1) : يُنشئ نقطة استعادة (Checkpoint) فقط لكل طبقة فك ترميز (decoder) رقمها مضاعف لـ `every_n_layers`، مع إبقاء بقية الطبقات تحتفظ بتفعيلاتها (activations). القيمة `1` تنشئ نقطة استعادة لكل طبقة، وهو السلوك المعتاد الشامل أو المنعدم. القيم الأكبر تبادِل بين استعادة الذاكرة والسرعة، وهو أمر يستحق ذلك في كل مرة تكون فيها الذاكرة المحررة من إنشاء نقاط الاستعادة الكاملة غير مستخدمة.

offload (`bool`، *اختياري*، القيمة الافتراضية `False`) : الاحتفاظ بالتفعيلات المحفوظة لإعادة الحساب في ذاكرة مضيف مثبّتة بدلاً من ذلك على المعالج التسارعي. هذا يُحرّر `layers x sequence x hidden` بايت من ذاكرة الجهاز، وهو ما يهيمن عند أطوال التسلسل الطويلة، ويتسبب في نسخ من الجهاز إلى المضيف في الأمامي ونسخ من المضيف إلى الجهاز في الخلفي. كلا النسخين يتمان على تدفق الحساب، مما يجعل الخطوة أبطأ.

activation_checkpointing_kwargs (dict, *اختياري*) : حُجج إضافية تُمرَّر إلى دالة `torch.utils.checkpoint.checkpoint`.

يفعّل نقطة التفعيل (activation checkpointing) للنموذج الحالي.

نمرّر طريقة `__call__` الخاصة بالوحدات بدلاً من `forward` لأن `__call__` تُلحق جميع الخطافات (hooks) الخاصة بالوحدة. https://discuss.pytorch.org/t/any-different-between-model-input-and-model-forward-input/3690/2

#### add_model_tags[[transformers.PreTrainedModel.add_model_tags]]

```python
add_model_tags(tags: list[str] | str)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L1360)

**المعاملات:**

tags (`Union[list[str], str]`) : الوسوم المطلوبة لحقنها في النموذج

أضِف وسمات مخصّصة إلى النموذج الذي يتم دفعه إلى Hugging Face Hub. لن يتم تجاوز الوسمات الموجودة مسبقًا في النموذج.

أمثلة:

```python
from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

model.add_model_tags(["custom", "custom-bert"])

# Push the model to your namespace with the name "my-custom-bert".
model.push_to_hub("my-custom-bert")
```

#### can_generate[[transformers.PreTrainedModel.can_generate]]

```python
can_generate()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L1474)

**يعيد:** `bool`

ما إذا كان بإمكان هذا النموذج توليد تسلسلات باستخدام `.generate()`.

يعيد ما إذا كان بإمكان هذا النموذج توليد تسلسلات باستخدام `.generate()`، من `GenerationMixin` أو من واجهة مشابهة.

في الخلفية، على الفئات التي تُرجع هذه الدالة القيمة True، يتم تفعيل بعض التغييرات الخاصة بالتوليد؛ فعلى سبيل المثال، سيحتوي كائن النموذج على سمة `generation_config` مُعبّأة بالقيم.

#### cuda[[transformers.PreTrainedModel.cuda]]

```python
cuda(*args, **kwargs)
```

قيمة وهمية لمسار منقّط (مثل `torch.float32`): سلاسل الوصول إلى السمات، والاستدعاءات تتصرف كمُزيّنات مُمرِّرة، و`repr` هو المسار المنقّط، وعند استخدامه كصنف أساسي يُستبدل بصنف أساسي من نوع `type` عادي (بموجب `__mro_entries__` في PEP 560)، بحيث تحتفظ الأصناف الفرعية الحقيقية بفئة ميتا عادية، وتقرأ `inspect.signature` دالة `__init__` الحقيقية الخاصة بها بدلاً من تلك الموجودة في القيمة الوهمية.

#### إلغاء التكميم[[transformers.PreTrainedModel.dequantize]]

```python
dequantize(dtype = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L1342)

قد يلزم إلغاء تكميم النموذج في حال كان قد تم تكميمه بطريقة تكميم تدعم إلغاء التكميم.

#### disable_input_require_grads[[transformers.PreTrainedModel.disable_input_require_grads]]

```python
disable_input_require_grads()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2181)

يزيل `_require_grads_hook`.

#### enable_input_require_grads[[transformers.PreTrainedModel.enable_input_require_grads]]

```python
enable_input_require_grads()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2137)

يُفعّل التدرّجات (Gradients) لتضمينات الإدخال. وهذا مفيد عند ضبط أوزان المحوّل (Adapter) مع إبقاء أوزان النموذج ثابتة.

#### from_pretrained[[transformers.PreTrainedModel.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike | None, *model_args, config: transformers.configuration_utils.PreTrainedConfig | str | os.PathLike | None = None, cache_dir: str | os.PathLike | None = None, ignore_mismatched_sizes: bool = False, force_download: bool = False, local_files_only: bool = False, token: str | bool | None = None, revision: str = 'main', use_safetensors: bool | None = None, weights_only: bool = True, fusion_config: dict[str, bool | dict[str, typing.Any]] | None = None, disable_mmap: bool | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3892)

**المعاملات:**

pretrained_model_name_or_path (`str` أو `os.PathLike`، *اختياري*) : يمكن أن يكون أحد ما يلي: - نص، وهو *معرف النموذج* لنموذج مُدرَّب مسبقًا مستضاف داخل مستودع نماذج على huggingface.co. - مسار إلى *مجلد* يحتوي على أوزان النموذج المحفوظة باستخدام [save_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.save_pretrained)، على سبيل المثال `./my_model_directory/`. يتم اكتشاف المجلدات المحفوظة بواسطة `save_pretrained(..., distributed_checkpoint=True)` وتحميلها باستخدام نقاط التفتيش الموزعة (DCP)، مع الحفاظ على الشبكة الحالية للنموذج وتوزيعاته. يتطلب هذا `torch>=2.7` ويحمّل بشكل صارم: يجب أن يكون كل مفتاح من مفاتيح النموذج موجودًا في نقطة التفتيش. - `None` إذا كنت توفر التكوين وقاموس الحالة (باستخدام معاملات الكلمات المفتاحية `config` و`state_dict` على التوالي).

model_args (سلسلة من الحُجج الموضعية، *اختياري*) : سيتم تمرير جميع الحُجج الموضعية المتبقية إلى طريقة `__init__` الخاصة بالنموذج الأساسي.

config (`Union[PreTrainedConfig, str, os.PathLike]`، *اختياري*) : يمكن أن يكون: - مثيلًا لفئة مشتقة من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig)، - أو نصًا أو مسارًا صالحًا كمدخل لـ [from_pretrained()](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig.from_pretrained).  إعدادات النموذج المراد استخدامه بدلاً من الإعدادات المحمّلة تلقائيًا. يمكن تحميل الإعدادات تلقائيًا عندما: - يكون النموذج من النماذج التي توفرها المكتبة (يُحمَّل باستخدام نص *معرف النموذج* لنموذج مُدرَّب مسبقًا). - تم حفظ النموذج باستخدام [save_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.save_pretrained) ويُعاد تحميله بتوفير مجلد الحفظ. - يتم تحميل النموذج بتوفير مجلد محلي كـ `pretrained_model_name_or_path` ويُوجد في المجلد ملف إعدادات بصيغة JSON باسم *config.json*.

state_dict (`dict[str, torch.Tensor]`، *اختياري*) : قاموس حالة يُستخدم بدلاً من قاموس الحالة المحمّل من ملف الأوزان المحفوظ. يمكن استخدام هذا الخيار إذا كنت ترغب في إنشاء نموذج من إعداد مسبق التدريب مع تحميل أوزانك الخاصة. ومع ذلك، في هذه الحالة، يجب عليك التحقق مما إذا كان استخدام [save_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.save_pretrained) و[from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) خياراً أبسط.

cache_dir (`Union[str, os.PathLike]`، *اختياري*) : المسار إلى مجلد يجب فيه تخزين إعدادات النموذج المسبق التدريب المُحمّل مؤقتًا إذا لم يُستخدم التخزين المؤقت القياسي.

ignore_mismatched_sizes (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب رفع خطأ أم لا إذا لم تكن بعض الأوزان من نقطة الحفظ (checkpoint) بنفس حجم أوزان النموذج (على سبيل المثال، إذا كنت تُنشئ نموذجًا بـ 10 تسميات من نقطة حفظ تحتوي على 3 تسميات).

force_download (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب إجبار إعادة تنزيل أوزان النموذج وملفات الإعداد، مع تجاوز النسخ المخزنة مؤقتًا في حال وجودها.

proxies (`dict[str, str]`، *اختياري*) : قاموس لخوادم الوكيل (proxy servers) التي يجب استخدامها حسب البروتوكول أو نقطة النهاية، على سبيل المثال `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. تُستخدم هذه الوكلاء في كل طلب.

output_loading_info(`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب إرجاع قاموس يحتوي على المفاتيح المفقودة والمفاتيح غير المتوقعة ورسائل الأخطاء أم لا.

local_files_only(`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب الاطلاع على الملفات المحلية فقط (أي عدم محاولة تنزيل النموذج).

token (`str` أو `bool`، *اختياري*) : الرمز الذي يُستخدم كرمز تفويض HTTP bearer للملفات البعيدة. إذا كان `True`، أو لم يُحدد، فسيتم استخدام الرمز الذي تم إنشاؤه عند تشغيل `hf auth login` (المخزَّن في `~/.huggingface`).

revision (`str`، *اختياري*، القيمة الافتراضية `"main"`) : إصدار النموذج المحدد الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف التزامن، نظرًا لأننا نستخدم نظامًا قائمًا على git لتخزين النماذج والمخرجات الأخرى على huggingface.co، لذا يمكن أن يكون `revision` أي معرّف يسمح به git.    لاختبار طلب الدمج الذي أنشأته على Hub، يمكنك تمرير `revision="refs/pr/<pr_number>"`.

attn_implementation (`str`، *اختياري*) : طريقة تنفيذ الانتباه المستخدمة في النموذج (إن كان ذلك ذا صلة). يمكن أن تكون أيًا مما يلي - `"eager"` (تنفيذ يدوي للانتباه) - `"sdpa"` (باستخدام [`F.scaled_dot_product_attention`](https://pytorch.org/docs/master/generated/torch.nn.functional.scaled_dot_product_attention.html)) - `"flash_attention_2"` (باستخدام [Dao-AILab/flash-attention](https://github.com/Dao-AILab/flash-attention)) - `"flash_attention_3"` (باستخدام [Dao-AILab/flash-attention/hopper](https://github.com/Dao-AILab/flash-attention/tree/main/hopper)) - `"flash_attention_4"` (باستخدام [Dao-AILab/flash-attention/flash_attn/cute](https://github.com/Dao-AILab/flash-attention/tree/main/flash_attn/cute)). افتراضيًا، إذا كان متاحًا، فسيتم استخدام SDPA. وإلا فإن الافتراضي هو التنفيذ اليدوي `"eager"`.  يقبل مراجع نواة HF بالصيغة: /[@][:]  -  و  تسلسلات غير "/" وغير ":". - "@" اختياري (فرع، وسم، أو commit-ish)، مثل "@main"، "@v1.2.0"، "@abc123". - ":" اختياري ويحدد دالة داخل مستودع النواة. - يمكن أن تظهر الخياريان معًا وبهذا الترتيب فقط: @revision أولًا، ثم :kernel_name. - نسمح عمدًا بادئ "|" (مثل "flash|...") لأن الكود يزيله قبل التحميل؛ '|' غير مستبعد في فئات الأحرف هنا.  أمثلة مطابقة: "org/model" "org/model@main" "org/model:custom_kernel" "org/model@v1.2.3:custom_kernel"

experts_implementation (`str`, *اختياري*) : تنفيذ الخبراء الذي سيتم استخدامه في النموذج (إذا كان ذا صلة). يمكن أن يكون أيًا مما يلي: - `"eager"` (تنفيذ تسلسلي لعمليات ضرب مصفوفات الخبراء). - `"batched_mm"` (باستخدام [`torch.bmm`](https://pytorch.org/docs/stable/generated/torch.bmm.html)). - `"grouped_mm"` (باستخدام [`torch.nn.functional.grouped_mm`](https://docs.pytorch.org/docs/main/generated/torch.nn.functional.grouped_mm.html)).  افتراضيًا، إذا كان النموذج يدعم ذلك، فسيتم استخدام `"grouped_mm"`. وإلا، فإن الافتراضي هو التنفيذ اليدوي `"eager"`.

**المعاملات للاستدلال على النماذج الكبيرة:**

dtype (`str` أو `torch.dtype`، *اختياري*، القيمة الافتراضية `"auto"`) : تجاوز القيمة الافتراضية لـ `torch_dtype` وتحميل النموذج تحت `dtype` محددة. الخيارات المختلفة هي:  1. `torch.float16` أو `torch.bfloat16` أو `torch.float`: التحميل بـ `dtype` محددة، مع تجاهل `config.dtype` للنموذج إذا وُجد. إذا لم يُحدد - فسيتم تحميل النموذج بـ `torch.float` (fp32).  2. `"auto"` - سيُحاول استخدام مدخل `dtype` أو `torch_dtype` في ملف `config.json` الخاص بالنموذج. إذا لم يُعثر على هذا المدخل، فسيتم التحقق من `dtype` لأول وزن في نقطة التفتيش (checkpoint) من نوع نقطة عائمة، واستخدامه كـ `dtype`. سيؤدي هذا إلى تحميل النموذج باستخدام `dtype` التي حُفظ بها في نهاية التدريب. لا يمكن استخدامه كمؤشر على كيفية تدريب النموذج. فقد يكون قد دُرّب بأحد أنواع `dtype` بدقة نصفية، لكن حُفظ بـ fp32.  3. نص صالح كـ `torch.dtype`. على سبيل المثال، "float32" يحمّل النموذج بـ `torch.float32`، و"float16" يحمّله بـ `torch.float16` وهكذا.    بالنسبة لبعض النماذج، `dtype` التي دُرِّبت بها غير معروفة - يمكنك محاولة التحقق من ورقة النموذج أو التواصل مع المؤلفين وطلب إضافة هذه المعلومات إلى بطاقة النموذج وإدراج مدخل `dtype` أو `torch_dtype` في `config.json` على المنصة.

device_map (`str` أو `dict[str, Union[int, str, torch.device]]` أو `int` أو `torch.device`، *اختياري*) : خريطة تحدد المكان الذي يجب أن يذهب إليه كل وحدة فرعية. لا حاجة إلى تفصيلها لكل اسم معامل/مخزن، فبمجرد إدخال اسم وحدة معينة، سيتم إرسال جميع وحداتها الفرعية إلى نفس الجهاز. إذا مررنا الجهاز فقط (*على سبيل المثال*، `"cpu"`، `"cuda:1"`، `"mps"`، أو ترتيب GPU مثل `1`) الذي سيُخصَّص عليه النموذج، فستقوم خريطة الجهاز بتعيين النموذج بأكمله إلى هذا الجهاز. يعني تمرير `device_map = 0` وضع النموذج بأكمله على GPU 0.  لجعل Accelerate يحسب `device_map` الأكثر تحسينًا تلقائيًا، اضبط `device_map="auto"`. لمزيد من المعلومات حول كل خيار، راجع [تصميم خريطة الجهاز](https://hf.co/docs/accelerate/main/en/usage_guides/big_modeling#designing-a-device-map).

max_memory (`Dict`, *اختياري*) : قاموس يحدد المعرّف الخاص بكل جهاز إلى الحد الأقصى للذاكرة عند استخدام `device_map`. إذا لم يتم ضبطه، فسيتم افتراضياً استخدام الحد الأقصى للذاكرة المتاحة لكل وحدة معالجة رسومية (GPU) والذاكرة العشوائية المتاحة في المعالج المركزي (CPU).

distributed_config ([DistributedConfig](/docs/transformers/main/ar/expert_parallelism#transformers.DistributedConfig)، *اختياري*) : إعدادات التحميل الموزّع الأصلي باستخدام توازي الموترات أو FSDP2. مرّر `DistributedConfig(tp_size=N)` لاستخدام خطة توازي الموترات المحدّدة مسبقًا للنموذج، أو `DistributedConfig(tp_plan=...)` لتحديد خطة توازي الموترات، أو `DistributedConfig(fsdp_size=N)` لاستخدام FSDP2. يتطلب الأمر `torchrun` ومجموعة عمليات مُهيّأة عندما يكون `tp_size > 1` أو `fsdp_size > 1`. يتعارض مع `device_map` بشكل متبادل.

device_mesh (`torch.distributed.DeviceMesh`، *اختياري*) : شبكة أجهزة torch. إذا لم يتم تقديمها، فسيتم افتراض حجم العالم. تُستخدم حاليًا فقط للتوازي على مستوى المصفوفات. إذا تم تقديمها، فيجب أن تحتوي على بُعد باسم `"tp"` في حال كان أبعاده أكبر من 1، وسيُستخدم هذا البعد للتوازي على مستوى المصفوفات

offload_folder (`str` أو `os.PathLike`، *اختياري*) : إذا احتوى `device_map` على أي قيمة `"disk"`، فهو المجلد الذي سنُحمّل فيه الأوزان.

offload_buffers (`bool`، *اختياري*) : ما إذا كان سيتم تفريغ المخازن مع معاملات النموذج أم لا.

quantization_config (`Union[QuantizationConfigMixin,Dict]`، *اختياري*) : قاموس لمعلمات الإعداد أو كائن QuantizationConfigMixin للكمّية (مثل bitsandbytes، gptq).

subfolder (`str`، *اختياري*، القيمة الافتراضية `""`) : في حال كانت الملفات ذات الصلة موجودة داخل مجلد فرعي من مستودع النموذج على huggingface.co، يمكنك تحديد اسم المجلد هنا.

variant (`str`، *اختياري*) : إذا تم تحديده، يتم تحميل الأوزان من اسم الملف `variant`، *على سبيل المثال* pytorch_model..bin.

use_safetensors (`bool`، *اختياري*، القيمة الافتراضية `None`) : ما إذا كان سيتم استخدام نقاط التفتيش `safetensors` أم لا. القيمة الافتراضية هي `None`. إذا لم يتم تحديد القيمة ولم يتم تثبيت `safetensors`، فسيتم تعيينها إلى `False`.

weights_only (`bool`، *اختياري*، القيمة الافتراضية `True`) : يحدد ما إذا كان يجب تقييد unpickler لتحميل الموترات (tensors) والأنواع الأساسية والقواميس وأي أنواع أُضيفت عبر torch.serialization.add_safe_globals() فقط. عند ضبطه على False، يمكن تحميل أوزان فئات الموترات الفرعية المغلفة (wrapper tensor subclass weights).

disable_mmap (`bool`، *اختياري*) : ما إذا كان سيتم تعطيل تعيين الذاكرة عند تحميل نقاط التفتيش بصيغة safetensors. عندما تكون القيمة `None` (الافتراضي)، يتم اكتشافها تلقائيًا لتكون `True` عندما تكون نقطة التفتيش على نظام ملفات FUSE من نوع `hf-mount` (المستخدم في HF Spaces/Endpoints)، حيث يمكن أن يؤدي استخدام mmap مع أخطاء الصفحة المتوازية إلى حدوث حالة جمود. عندما تكون القيمة `True`، تُقرأ الملفات بالكامل في الذاكرة وتُحلَّل باستخدام `safetensors.torch.load`. عندما تكون القيمة `False`، يُستخدم دائمًا مُحمِّل تعيين الذاكرة الافتراضي.

fusion_config (`dict[str, bool | dict[str, Any]]`، *اختياري*) : إعدادات الدمج الاختيارية التي تُطبَّق قبل إنشاء النموذج. كل مفتاح يُفعِّل عائلة دمج، ويمكن أن تكون قيمته `True` لتفعيل ذلك الدمج مع الخيارات الافتراضية، أو قاموسًا يحتوي على خيارات محددة لكل عائلة. على سبيل المثال، `{"patch_embeddings": True}` يُفعِّل دمج تضمين البقع. يجب استخدام هذا الخيار فقط كتحسين للاستدلال، لأنه قد يُغيِّر المخرجات بشكل طفيف. إذا حُذف، فإن `from_pretrained()` يعود إلى `config.fusion_config` عند توفره. راجع دليل خرائط الدمج في `docs/source/en/fusion_mapping.md` لمزيد من التفاصيل.

key_mapping (`dict[str, str], *اختياري*) : خرائط محتملة لأسماء الأوزان إذا كان النموذج على Hub متوافقًا مع بنية Transformers، لكنه لم يُحوَّل وفقًا لذلك.

kwargs (باقي قاموس حُجج الكلمات المفتاحية، *اختياري*) : يمكن استخدامه لتحديث كائن الإعداد (بعد تحميله) وبدء تشغيل النموذج (مثل `output_attentions=True`). يختلف سلوكه اعتمادًا على ما إذا كان `config` مُوفَّرًا أو محمَّلًا تلقائيًا:  - إذا تم توفير إعداد مع `config`، فسيتم تمرير `**kwargs` مباشرةً إلى طريقة `__init__` للنموذج الأساسي (بافتراض أن جميع التحديثات ذات الصلة بالإعداد تم إجراؤها بالفعل) - إذا لم يتم توفير إعداد، فسيتم تمرير `kwargs` أولًا إلى دالة تهيئة فئة الإعداد ([from_pretrained()](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig.from_pretrained)). سيتم استخدام كل مفتاح من مفاتيح `kwargs` الذي يتوافق مع خاصية إعداد لتجاوز تلك الخاصية بالقيمة المُقدَّمة في `kwargs`. سيتم تمرير المفاتيح المتبقية التي لا تتوافق مع أي خاصية إعداد إلى دالة `__init__` للنموذج الأساسي.

أنشئ نموذج pytorch مُدرَّب مسبقًا من تكوين نموذج مُدرَّب مسبقًا.

يُضبط النموذج في وضع التقييم افتراضياً باستخدام `model.eval()` (تُعطَّل وحدات Dropout). لتدريب النموذج، يجب عليك أولاً إعادة ضبطه في وضع التدريب باستخدام `model.train()`.

The warning *Weights from XXX not initialized from pretrained model* means that the weights of XXX do not come pretrained with the rest of the model. It is up to you to train those weights with a downstream fine-tuning task.

تعني تحذير *Weights from XXX not used in YYY* أن الطبقة XXX غير مستخدمة بواسطة YYY، وبالتالي يتم تجاهل تلك الأوزان.

فعّل وضع ["offline-mode"](https://huggingface.co/transformers/installation.html#offline-mode) الخاص لاستخدام هذه الطريقة في بيئة محمية بجدار ناري.

أمثلة:

```python
>>> from transformers import BertConfig, BertModel

>>> # Download model and configuration from huggingface.co and cache.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased")
>>> # Model was saved using *save_pretrained('./test/saved_model/')* (for example purposes, not runnable).
>>> model = BertModel.from_pretrained("./test/saved_model/")
>>> # Update configuration during loading.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased", output_attentions=True)
>>> assert model.config.output_attentions == True
```

#### get_compiled_call[[transformers.PreTrainedModel.get_compiled_call]]

```python
get_compiled_call(compile_config: transformers.generation.configuration_utils.CompileConfig | None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L4797)

تُعيد نسخة مُجمَّعة باستخدام `torch.compile` من `self.__call__`. وهذا مفيد لاختيار ديناميكي بين `forward` غير المُجمَّعة والمُجمَّعة أثناء الاستدلال، لا سيما للتبديل بين مرحلة التعبئة (حيث لا نرغب في استخدام النسخة المُجمَّعة لتجنب إعادة حساب الرسم البياني مع أشكال جديدة) ومرحلة فك الترميز التكراري (حيث نرغب في الاستفادة من تسريع النسخة المُجمَّعة مع الأشكال الثابتة).

#### get_decoder[[transformers.PreTrainedModel.get_decoder]]

```python
get_decoder()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2254)

البحث بأقصى جهد ممكن عن وحدة *decoder*.

ترتيب المحاولات (يغطي حوالي 85 % من الاستخدامات الحالية):

1. `self.decoder/self.language_model/self.text_model`
2. `self.base_model`                  (تُخزّن العديد من الطبقات المغلِّفة المُفكِّك هنا)
3. `self.base_model.get_decoder()`    (الغلّافات المتداخلة)
4. fallback: رفع استثناء لعدد قليل من النماذج الغريبة التي تتطلب قاعدة مخصصة

#### get_encoder[[transformers.PreTrainedModel.get_encoder]]

```python
get_encoder(modality: str | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2196)

بحث بأقصى جهد ممكن عن وحدة *encoder*. إذا تم توفير حجة `modality`، يبحث عن مشفّر محدد للوسائط في النماذج متعددة الوسائط (مثل "image_encoder"). افتراضياً، تُرجع الدالة مشفّر النص الخاص بالنموذج إن وُجد، وإلا تُرجع `self`.

القيم الممكنة لـ `modality` هي "image" و"video" و"audio".

#### get_expanded_tied_weights_keys[[transformers.PreTrainedModel.get_expanded_tied_weights_keys]]

```python
get_expanded_tied_weights_keys(all_submodels: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2416)

أعد مفاتيح الأوزان المرتبطة الموسّعة (في حال احتوائها على وحدات أو أنماط مطابقة منتظمة) للنموذج الحالي فقط، أو بشكل تكراري لجميع النماذج الفرعية إذا كان `all_submodels=True` (أي أنه سيعيد فحص قيم الإعدادات لجميع النماذج الفرعية).

بالنسبة لمعظم النماذج، لا نحتاج سوى إلى ربط التضمينات، لذا يحتوي النموذج على خاصية داخلية `_tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}`. في هذه الحالة، يكون الترميز مُوسَّعًا بالفعل، أي أنه يحتوي على المعاملات الكاملة، وستُرجع هذه الدالة ببساطة نسخة من الخاصية. بالنسبة لأنماط أكثر تعقيدًا، مثل `DFineForObjectDetection`، لدينا الخاصية التالية

```
_tied_weights_keys = {
    r"bbox_embed.(?![0])\d+": "bbox_embed.0",
    r"class_embed.(?![0])\d+": "class_embed.0",
    "model.decoder.class_embed": "class_embed",
    "model.decoder.bbox_embed": "bbox_embed",
}
```

في هذه الحالة، تبحث الدالة عن جميع معاملات النموذج وخانات التخزين المؤقت، وتطابق جميع المعاملات،

إرجاع ما يلي:
```
{
    'bbox_embed.1.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'bbox_embed.1.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    'bbox_embed.1.layers.1.bias': 'bbox_embed.0.layers.1.bias',
    'bbox_embed.1.layers.1.weight': 'bbox_embed.0.layers.1.weight',
    'bbox_embed.1.layers.2.bias': 'bbox_embed.0.layers.2.bias',
    'bbox_embed.1.layers.2.weight': 'bbox_embed.0.layers.2.weight',
    'bbox_embed.2.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'bbox_embed.2.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    ...
    'class_embed.1.bias': 'class_embed.0.bias',
    'class_embed.1.weight': 'class_embed.0.weight',
    'class_embed.2.bias': 'class_embed.0.bias',
    'class_embed.2.weight': 'class_embed.0.weight',
    ...
    'model.decoder.class_embed.0.bias': 'class_embed.0.bias',
    'model.decoder.class_embed.0.weight': 'class_embed.0.weight',
    'model.decoder.class_embed.1.bias': 'class_embed.0.bias',
    'model.decoder.class_embed.1.weight': 'class_embed.0.weight',
    ...
    'model.decoder.bbox_embed.0.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'model.decoder.bbox_embed.0.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    'model.decoder.bbox_embed.0.layers.1.bias': 'bbox_embed.0.layers.1.bias',
    'model.decoder.bbox_embed.0.layers.1.weight': 'bbox_embed.0.layers.1.weight',
    ...
}
```

أي أن جميع المعلمات المطابقة لنمط التعبير النمطي (regex) وأنماط الوحدات في `_tied_weights_keys`

#### get_experts_implementation[[transformers.PreTrainedModel.get_experts_implementation]]

```python
get_experts_implementation()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2064)

تُعيد تنفيذ الخبراء لهذا النموذج ونماذجه الفرعية، على شكل `dict` بالصيغة المقبولة بواسطة `set_experts_implementation` (`""` لهذا النموذج، ودخول واحد لكل sub_config). هذا هو المقابل لـ `set_experts_implementation`، على سبيل المثال لالتقاط لقطة من التنفيذ الحالي واستعادته لاحقًا.

#### get_memory_footprint[[transformers.PreTrainedModel.get_memory_footprint]]

```python
get_memory_footprint(return_buffers = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3676)

**المعاملات:**

return_buffers (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع حجم تينسورات المخزن المؤقت (buffer tensors) في حساب البصمة الذاكرة. المخازن المؤقتة هي تينسورات لا تتطلب تدرجات (gradients) وغير مسجلة كمعاملات (parameters). على سبيل المثال، المتوسط والانحراف المعياري في طبقات تطبيع الدفعة (batch norm). يرجى الاطلاع على: https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

احصل على بصمة الذاكرة لنموذج. سيعيد هذا الأمر بصمة الذاكرة للنموذج الحالي بالبايت. وهو مفيد لمعايرة بصمة الذاكرة للنموذج الحالي وتصميم بعض الاختبارات. الحل مستوحى من نقاشات PyTorch: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

#### get_parameter_or_buffer[[transformers.PreTrainedModel.get_parameter_or_buffer]]

```python
get_parameter_or_buffer(target: str)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L4964)

يعيد المعامل أو المخزن المحدد بواسطة `target` إذا كان موجوداً، وإلا يرمي خطأً. يجمع هذا الدالة `get_parameter()` و`get_buffer()` في دالة واحدة مريحة. إذا كان الهدف هو سمة `_extra_state`، فسيُعيد الحالة الإضافية التي يوفرها الوحدة. لاحظ أن هذا يعمل فقط إذا كان `target` ورقة من النموذج.

#### gradient_checkpointing_disable[[transformers.PreTrainedModel.gradient_checkpointing_disable]]

```python
gradient_checkpointing_disable()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3276)

اسم مستعار غير مستحسن لـ [activation_checkpointing_disable()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.activation_checkpointing_disable)، وسيتم إزالته في الإصدار v6.

#### gradient_checkpointing_enable[[transformers.PreTrainedModel.gradient_checkpointing_enable]]

```python
gradient_checkpointing_enable(gradient_checkpointing_kwargs = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3191)

اسم مستعار غير مستخدم لم يعد يُنصح به لـ [activation_checkpointing_enable()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.activation_checkpointing_enable)، وسيتم إزالته في الإصدار v6.

#### init_weights[[transformers.PreTrainedModel.init_weights]]

```python
init_weights()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3098)

قم بتبويب الأوزان وربطها عند الحاجة. إذا كنت تستخدم `PreTrainedModel` مخصصًا، فستحتاج إلى تنفيذ أي منطق للتبويب في `_init_weights`.

#### initialize_weights[[transformers.PreTrainedModel.initialize_weights]]

```python
initialize_weights()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2386)

تُكافئ هذه الدالة استدعاء `self.apply(self._initialize_weights)`، لكنها تتعامل مع النماذج المركبة بشكل صحيح. تقوم هذه الدالة بتوجيه دالة `init_weights` الصحيحة إلى الوحدات ديناميكيًا أثناء تقدمنا في رسم الوحدات عبر التكرار. ويمكنها التعامل مع عدد غير محدود من النماذج الفرعية. وبدونها، كان على كل نموذج مركب أن يتكرر مرة ثانية على جميع النماذج الفرعية صراحةً في `_init_weights` الخارجي، وهو أمر عرضة للأخطاء للغاية وغير فعال.

#### is_custom_code[[transformers.PreTrainedModel.is_custom_code]]

```python
is_custom_code()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L5018)

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

#### is_remote_code[[transformers.PreTrainedModel.is_remote_code]]

```python
is_remote_code()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L5012)

تُرجع ما إذا كان النموذج الحالي هو كود مخصص، أي كود تم تحميله من المستودع، أو فئة تم تسجيلها للتو عبر `register_for_auto_class`.

#### mark_tied_weights_as_initialized[[transformers.PreTrainedModel.mark_tied_weights_as_initialized]]

```python
mark_tied_weights_as_initialized(loading_info)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L4936)

يضيف العلم `_is_hf_initialized` إلى المعاملات التي سيتم ربطها، وذلك لتجنب تهيئتها لاحقًا، إذ سيتم ربطها (وتجاوز قيمتها) على أي حال. وهذا أمر بالغ الأهمية، لأن معظم التضمينات (embeddings) تكون مرتبطة، وهي معاملات ضخمة (حيث تكون أحجام المفردات غالبًا 256k)، لذا فإن تنفيذ عمليات التهيئة عليها مكلف للغاية.

#### named_non_persistent_buffers[[transformers.PreTrainedModel.named_non_persistent_buffers]]

```python
named_non_persistent_buffers(recurse: bool = True, remove_duplicate: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L4988)

يشبه `named_buffers`، لكنه يُنتج فقط تلك غير الدائمة. وهو مفيد لأنه ليس من الواضح تمامًا معرفة ما إذا كانت دائمة أم لا.

#### post_init[[transformers.PreTrainedModel.post_init]]

```python
post_init()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L1289)

طريقة تُنفَّذ في نهاية تهيئة كل نموذج من نماذج Transformers، لتنفيذ الأكواد التي تتطلب تهيئة وحدات النموذج بشكل صحيح (مثل تهيئة الأوزان). كما تُستخدم للحصول على جميع الخصائص الثابتة الصحيحة (خطط التوازي، tied_weights_keys، _keep_in_fp32_modules، إلخ) بشكل صحيح في حالة النماذج المركبة (أي أن النموذج في المستوى الأعلى يجب أن يكون على علم بتلك الخصائص من أبنائه).

#### register_for_auto_class[[transformers.PreTrainedModel.register_for_auto_class]]

```python
register_for_auto_class(auto_class = 'AutoModel')
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L4643)

**المعاملات:**

auto_class (`str` أو `type`، *اختياري*، القيمة الافتراضية `"AutoModel"`) : فئة auto التي سيتم تسجيل هذا النموذج الجديد بها.

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

#### resize_token_embeddings[[transformers.PreTrainedModel.resize_token_embeddings]]

```python
resize_token_embeddings(new_num_tokens: int | None = None, pad_to_multiple_of: int | None = None, mean_resizing: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2633)

**المعاملات:**

new_num_tokens (`int`، *اختياري*) : العدد الجديد للرموز في مصفوفة التضمين. زيادة الحجم ستضيف متجهات مهيأة حديثًا في النهاية. تقليل الحجم سيزيل متجهات من النهاية. إذا لم يُقدَّم أو كان `None`، يُرجع مجرد مؤشر إلى وحدة `torch.nn.Embedding` للرموز المدخلة في النموذج دون القيام بأي شيء.

pad_to_multiple_of (`int`, *اختياري*) : إذا تم تعيينه، سيتم توسيع مصفوفة التضمين إلى مضاعف للقيمة المُقدَّمة. إذا تم تعيين `new_num_tokens` إلى `None`، فسيتم فقط توسيع التضمين إلى مضاعف لـ `pad_to_multiple_of`. وهذا مفيد بشكل خاص لتمكين استخدام نوى المصفوفات (Tensor Cores) على أجهزة NVIDIA التي تتمتع بقابلية حساب `>= 7.5` (Volta)، أو على وحدات TPU التي تستفيد من أن تكون أطوال التسلسلات مضاعفات لـ 128. لمزيد من التفاصيل حول هذا الموضوع، أو للحصول على مساعدة في اختيار القيمة الصحيحة لإعادة التحجيم، يُرجى الرجوع إلى هذا الدليل: https://docs.nvidia.com/deeplearning/performance/dl-performance-matrix-multiplication/index.html#requirements-tc

mean_resizing (`bool`) : ما إذا كان سيتم تهيئة التضمينات المضافة من توزيع طبيعي متعدد المتغيرات يحمل متوسط وتباين التضمينات القديمة، أو تهيئتها بتوزيع طبيعي متوسطه صفر وانحرافه المعياري يساوي `config.initializer_range`. يُعد ضبط `mean_resizing` على `True` مفيدًا عند زيادة حجم التضمينات في نماذج اللغة السببية، حيث لن تتأثر احتمالات الرموز المولّدة بالتضمينات المضافة، لأن تهيئة التضمينات الجديدة بمتوسط التضمينات القديمة تقلل من تباعد كولباك-ليبلر بين احتمالية الرمز التالي قبل وبعد إضافة التضمينات الجديدة. راجع هذا المقال لمزيد من المعلومات: https://nlp.stanford.edu/~johnhew/vocab-expansion.html

**يعيد:** `torch.nn.Embedding`

مؤشر إلى وحدة التضمينات (Embeddings) للرموز المدخلة في النموذج.

يعيد تغيير حجم مصفوفة تضمينات الرموز المدخلة للنموذج إذا كان `new_num_tokens != config.vocab_size`.

يتولى ربط أوزان التضمينات لاحقًا إذا كان لفئة النموذج طريقة `tie_weights()`.

#### save_pretrained[[transformers.PreTrainedModel.save_pretrained]]

```python
save_pretrained(save_directory: str | os.PathLike, is_main_process: bool = True, state_dict: dict | None = None, push_to_hub: bool = False, max_shard_size: int | str = '50GB', variant: str | None = None, token: str | bool | None = None, save_peft_format: bool = True, save_original_format: bool = True, distributed_checkpoint: bool = False, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3310)

**المعاملات:**

save_directory (`str` أو `os.PathLike`) : المجلد الذي سيتم الحفظ فيه. سيتم إنشاؤه إذا لم يكن موجودًا.

is_main_process (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كانت العملية التي تستدعي هذا هي العملية الرئيسية أم لا. مفيد عند التدريب الموزع مثل TPU والحاجة إلى استدعاء هذه الدالة على جميع العمليات. في هذه الحالة، اضبط `is_main_process=True` على العملية الرئيسية فقط لتجنب حالات السباق.

state_dict (قاموس متداخل من `torch.Tensor`) : قاموس الحالة الخاص بالنموذج الذي سيتم حفظه. سيكون الافتراضي `self.state_dict()`، لكن يمكن استخدامه لحفظ أجزاء فقط من النموذج أو إذا كانت هناك حاجة إلى احتياطات خاصة عند استعادة قاموس حالة النموذج (مثل عند استخدام توازٍ للنموذج).

push_to_hub (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم دفع نموذجك إلى مستودع نماذج Hugging Face بعد حفظه. يمكنك تحديد المستودع الذي تريد الدفع إليه باستخدام `repo_id` (سيكون الافتراضي هو اسم `save_directory` ضمن نطاقك).

max_shard_size (`int` أو `str`، *اختياري*، القيمة الافتراضية هي `"50GB"`) : الحد الأقصى لحجم نقطة التفتيش قبل تقسيمها إلى أجزاء. ستكون نقاط التفتيش المقسمة بعد ذلك أصغر من هذا الحجم. إذا تم التعبير عنها كنص، فيجب أن تتكون من أرقام تليها وحدة (مثل `"5MB"`).    إذا كان وزن واحد في النموذج أكبر من `max_shard_size`، فسيكون في جزء نقطة تفتيش خاص به سيكون أكبر من `max_shard_size`.

variant (`str`، *اختياري*) : إذا تم تحديده، تُحفظ الأوزان بالتنسيق model..safetensors.

token (`str` أو `bool`، *اختياري*) : الرمز الذي يُستخدم كرمز تفويض HTTP bearer للملفات البعيدة. إذا كان `True`، أو لم يُحدد، فسيتم استخدام الرمز الذي تم إنشاؤه عند تشغيل `hf auth login` (المخزَّن في `~/.huggingface`).

save_peft_format (`bool`، *اختياري*، القيمة الافتراضية `True`) : من أجل التوافق العكسي مع مكتبة PEFT، في حال كانت أوزان المُكيِّف (adapter) مرفقة بالنموذج، يجب إضافة بادئة `base_model.model` إلى جميع مفاتيح قاموس الحالة (state dict) الخاص بالمُكيِّفات. يمكن للمستخدمين المتقدمين تعطيل هذا السلوك عن طريق تعيين `save_peft_format` إلى `False`.

save_original_format (`bool`، *اختياري*، القيمة الافتراضية `True`) : من أجل التوافق العكسي مع الإصدارات السابقة من `transformers`، يمكنك حفظ نقطة التفتيش مع خريطتها العكسية. يجب أن تكون الخريطة العكسية موجودة حتى لو تم تحميل النموذج من نقطة تفتيش قديمة بقيمة None.

distributed_checkpoint (`bool`، *اختياري*، القيمة الافتراضية `False`) : عند حفظ نموذج مُجزَّأ باستخدام FSDP أو TP، اكتب ملفات safetensors باستخدام نقطة التفتيش الموزعة (DCP) بدلاً من تجميع الأوزان على وحدة المعالجة المركزية أولاً. يجب على كل رتبة استدعاء هذه الطريقة. عند تعيين `False`، يتم تجميع الأوزان على وحدة المعالجة المركزية في الرتبة 0 عبر `gather_full_state_dict` قبل الكتابة. يُقصد بها فقط حفظ التدريب واستئنافه، فعيّنها إلى `False` إذا كنت ترغب في الحصول على جميع ميزات `save_pretrained`. عند استخدام `push_to_hub=True`، تقوم الرتبة 0 بتوحيد نقطة التفتيش في مجلد فرعي باسم `consolidated/` وتُرفع ذلك المجلد. تتطلب `torch>=2.7`.

kwargs (`dict[str, Any]`، *اختياري*) : حُجج إضافية تُمرَّر إلى طريقة [push_to_hub()](/docs/transformers/main/ar/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub).

احفظ النموذج وملف إعداده في مجلد، بحيث يمكن إعادة تحميله باستخدام طريقة الفئة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained).

#### set_attn_implementation[[transformers.PreTrainedModel.set_attn_implementation]]

```python
set_attn_implementation(attn_implementation: str | dict, allow_all_kernels: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L1960)

**المعاملات:**

attn_implementation (`str` أو `dict`) : طريقة تنفيذ الانتباه (attention) التي يجب تعيينها لهذا النموذج. يمكن أن تكون `str`، وفي هذه الحالة سيتم توجيهها إلى جميع النماذج الفرعية إن كان ذلك مناسباً، أو `dict` حيث تكون المفاتيح أسماء sub_configs، وفي هذه الحالة سيقوم كل نموذج فرعي بتوجيه القيمة المقابلة (إلى نفسه وإلى جميع النماذج الفرعية المتداخلة فيه). يمكن أن تكون القيمة نفسها `dict` بنفس التنسيق، لاستهداف sub_configs لذلك النموذج الفرعي (كما عند تهيئة config مع `attn_implementation` متداخلة).

allow_all_kernels (`bool`, اختياري) : ما إذا كان سيتم تحميل الأنوية (kernels) من مستودعات هَب غير مُتحقَّق منها، إذا كان `attn_implementation` نواة مخصصة خارج مستودع `kernels-community` على الهَب.

اضبط `attn_implementation` المطلوب لهذا النموذج.

#### set_decoder[[transformers.PreTrainedModel.set_decoder]]

```python
set_decoder(decoder)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2277)

دالة تعيين متماثلة. تعكس منطق الاستعلام المستخدم في `get_decoder`.

#### set_encoder[[transformers.PreTrainedModel.set_encoder]]

```python
set_encoder(encoder, modality: str | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2228)

دالة تعيين متناظرة. تعكس منطق الاستعلام المستخدم في `get_encoder`.

#### set_experts_implementation[[transformers.PreTrainedModel.set_experts_implementation]]

```python
set_experts_implementation(experts_implementation: str | dict)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2077)

**المعاملات:**

experts_implementation (`str` أو `dict`) : تنفيذ الخبراء الذي يجب تعيينه لهذا النموذج. يمكن أن يكون `str`، وفي هذه الحالة سيتم توجيهه إلى جميع النماذج الفرعية إن كان ذلك مناسباً، أو `dict` حيث تكون المفاتيح أسماء sub_configs، وفي هذه الحالة سيقوم كل نموذج فرعي بتوجيه القيمة المقابلة.

اضبط `experts_implementation` المطلوب لهذا النموذج.

#### set_use_kernels[[transformers.PreTrainedModel.set_use_kernels]]

```python
set_use_kernels(use_kernels, kernel_config: transformers.utils.kernel_config.KernelConfig | None = None, mode: Mode | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L3850)

**المعاملات:**

use_kernels (`bool`) : ما إذا كان سيتم استخدام مكتبة `kernels` لتحويل بعض طبقات النموذج إلى نواة.

kernel_config (`KernelConfig`، *اختياري*) : إعدادات النواة (kernel) المستخدمة لتحويل النموذج إلى صيغة النواة. إذا كانت `None`، فسيتم استخدام تعيين النواة الافتراضي.

mode (`Mode`، *اختياري*) : الوضع الذي يجب تطبيقه أثناء `kernelize`. اختياري، والافتراضي هو وضع التدريب أو وضع الاستدلال بناءً على علم `training` الداخلي.

حدد ما إذا كان سيتم استخدام مكتبة `kernels` لتحويل بعض طبقات النموذج إلى نواة.

#### tie_weights[[transformers.PreTrainedModel.tie_weights]]

```python
tie_weights(missing_keys: set[str] | None = None, recompute_mapping: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L2530)

اربط أوزان النموذج. إذا كان `recompute_mapping=False` (وهو الافتراضي عند الاستدعاء داخلياً)، فسيتم الاعتماد على خاصية `model.all_tied_weights_keys`، التي تحتوي على إسقاط `{target: source}` للمعاملات المرتبطة. أما إذا كان `recompute_mapping=True`، فسيتم إعادة فحص جميع النماذج الفرعية الداخلية وإعداداتها لتحديد المعاملات التي يجب ربطها. وهذا هو الافتراضي عند استدعاء `model.tie_weights()` بشكل مستقل، خارج `__init__` و`from_pretrained`، في حال تم تغيير قيم الإعدادات في مكان ما.

لاحظ أنه أثناء `from_pretrained`، يكون الربط *متماثلًا*: إذا كان الترميز يقول "الهدف المرتبط -> المصدر" لكن `source` غير موجود في نقطة الحفظ بينما `target` موجود، فإننا *نبدّل* المصدر والهدف حتى نتمكن من ربط كل شيء بالباراميتر الموجود فعليًا.

#### إلى[[transformers.PreTrainedModel.to]]

```python
to(*args, **kwargs)
```

قيمة وهمية لمسار منقّط (مثل `torch.float32`): سلاسل الوصول إلى السمات، والاستدعاءات تتصرف كمُزيّنات مُمرِّرة، و`repr` هو المسار المنقّط، وعند استخدامه كصنف أساسي يُستبدل بصنف أساسي من نوع `type` عادي (بموجب `__mro_entries__` في PEP 560)، بحيث تحتفظ الأصناف الفرعية الحقيقية بفئة ميتا عادية، وتقرأ `inspect.signature` دالة `__init__` الحقيقية الخاصة بها بدلاً من تلك الموجودة في القيمة الوهمية.

#### warn_if_padding_and_no_attention_mask[[transformers.PreTrainedModel.warn_if_padding_and_no_attention_mask]]

```python
warn_if_padding_and_no_attention_mask(input_ids, attention_mask)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L4665)

يعرض تحذيراً لمرة واحدة إذا بدا أن input_ids تحتوي على حشو ولم يتم تقديم قناع انتباه.

يجب أن تتضمن النماذج المخصصة أيضًا `_supports_assign_param_buffer`، والتي تحدد ما إذا كان بإمكان تهيئة فائقة السرعة (superfast init) أن تُطبَّق على النموذج المعني. من العلامات الدالة على أن نموذجك يحتاج إلى هذا الأمر هو فشل `test_save_and_load_from_pretrained`. في هذه الحالة، اضبط هذا على `False`.

## ModuleUtilsMixin[[transformers.modeling_utils.ModuleUtilsMixin]]

#### transformers.modeling_utils.ModuleUtilsMixin[[transformers.modeling_utils.ModuleUtilsMixin]]

```python
transformers.modeling_utils.ModuleUtilsMixin()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L894)

بعض الأدوات المساعدة لـ `torch.nn.Modules`، لاستخدامها كخلطة (mixin).

#### num_parameters[[transformers.modeling_utils.ModuleUtilsMixin.num_parameters]]

```python
num_parameters(only_trainable: bool = False, exclude_embeddings: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L914)

**المعاملات:**

only_trainable (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب إرجاع عدد المعاملات القابلة للتدريب فقط

exclude_embeddings (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب إرجاع عدد معاملات غير التضمينات فقط

**يعيد:** `int`

عدد المعاملات.

الحصول على عدد (اختياريًا، القابلة للتدريب أو غير التضمينات) من المعاملات في الوحدة.

## الرفع إلى المستودع[[transformers.utils.PushToHubMixin]]

#### transformers.utils.PushToHubMixin[[transformers.utils.PushToHubMixin]]

```python
transformers.utils.PushToHubMixin()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py#L728)

خلطة (Mixin) تحتوي على الوظائف اللازمة لدفع النموذج أو المُجزِّئ (tokenizer) إلى المستودع (hub).

#### push_to_hub[[transformers.utils.PushToHubMixin.push_to_hub]]

```python
push_to_hub(repo_id: str, commit_message: str | None = None, commit_description: str | None = None, private: bool | None = None, token: bool | str | None = None, revision: str | None = None, create_pr: bool = False, max_shard_size: int | str | None = '50GB', tags: list[str] | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py#L822)

**المعاملات:**

repo_id (`str`) : اسم المستودع الذي تريد دفع {object} إليه. يجب أن يحتوي على اسم مؤسستك عند الدفع إلى مؤسسة محددة.

commit_message (`str`، *اختياري*) : الرسالة التي سيتم الالتزام بها أثناء الدفع. ستكون الافتراضية `"Upload {object}"`.

commit_description (`str`، *اختياري*) : وصف الالتزام الذي سيتم إنشاؤه

private (`bool`، *اختياري*) : ما إذا كان سيتم جعل المستودع خاصًا. إذا كانت القيمة `None` (الافتراضي)، فسيكون المستودع عامًا ما لم يكن الافتراضي الخاص بالمنظمة هو الخاص. يتم تجاهل هذه القيمة إذا كان المستودع موجودًا مسبقًا.

token (`bool` أو `str`، *اختياري*) : الرمز الذي يُستخدم كترخيص HTTP bearer للملفات البعيدة. إذا كان `True` (الافتراضي)، فسيتم استخدام الرمز الذي تم إنشاؤه عند تشغيل `hf auth login` (المخزّن في `~/.huggingface`).

revision (`str`، *اختياري*) : الفرع الذي سيتم دفع الملفات المرفوعة إليه.

create_pr (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم إنشاء طلب دمج (PR) مع الملفات المرفوعة أم الالتزام مباشرة.

max_shard_size (`int` أو `str`، *اختياري*، القيمة الافتراضية `"50GB"`) : ينطبق على النماذج فقط. الحد الأقصى لحجم نقطة التفتيش قبل تقسيمها إلى أجزاء. ستكون نقاط التفتيش المقسمة بعد ذلك أصغر من هذا الحجم. إذا تم التعبير عنها كنص، فيجب أن تتكون من أرقام تليها وحدة (مثل `"5MB"`).

tags (`list[str]`، *اختياري*) : قائمة بالوسوم التي سيتم دفعها إلى Hub.

قم برفع {object_files} إلى 🤗 Model Hub.

أمثلة:

```python
from transformers import {object_class}

{object} = {object_class}.from_pretrained("google-bert/bert-base-cased")

# Push the {object} to your namespace with the name "my-finetuned-bert".
{object}.push_to_hub("my-finetuned-bert")

# Push the {object} to an organization with the name "my-finetuned-bert".
{object}.push_to_hub("huggingface/my-finetuned-bert")
```