# طبقات ومساعدات مخصصة

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

لا تُفيد معظم تلك العناصر إلا إذا كنت تدرس كود النماذج الموجودة في المكتبة.

## WeightRenaming[[transformers.GroupWeightRename]]

#### transformers.GroupWeightRename[[transformers.GroupWeightRename]]

```python
transformers.GroupWeightRename(source_patterns: list[str], target_patterns: list[str])
```

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

يطبّق قائمة من تحويلات إعادة التسمية المزدوجة (WeightRenaming)، وتُفعَّل بشكل كسول (lazy) بواسطة نمط المصدر الأول (نمط "الحارس"). استخدم هذا عندما تتشارك إعادة تسمية وسيطة اسمًا مشتركًا (مثل `norm0→norm1` و`norm1→norm2`)، بحيث لا يُعاد تطبيق إعادة التسمية بشكل خاطئ عند تحميل نقطة تفتيش (checkpoint) تم تحويلها مسبقًا (التي تحتوي على `norm1` و`norm2` ولا تحتوي على `norm0`).

ملاحظة: رتّب `source_patterns` بحيث يأتي النمط غير الموجود في نقطة التفتيش المحوّلة مسبقًا في المقدمة. يتم تكرار state dict بترتيب مفاتيح مُرتّبة، لذا يجب أن يكون نمط الحارس أصغر حروفية من الأنماط المعتمدة عليه. وإلا فسيتم تخطي المعتمدين في المرور الأول ولن يُعاد تجربتهم أبدًا.

## WeightConverter[[transformers.WeightConverter]]

#### transformers.WeightConverter[[transformers.WeightConverter]]

```python
transformers.WeightConverter(source_patterns: str | list[str], target_patterns: str | list[str], operations: list[ConversionOps], force_cpu: bool = False)
```

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

### عمليات التحويل[[transformers.ConversionOps]]

#### transformers.ConversionOps[[transformers.ConversionOps]]

```python
transformers.ConversionOps()
```

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

الفئة الأساسية لعمليات تحويل الأوزان.

#### transformers.Chunk[[transformers.Chunk]]

```python
transformers.Chunk(dim: int = 0, num_shards_attribute: str | None = None)
```

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

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

#### transformers.Concatenate[[transformers.Concatenate]]

```python
transformers.Concatenate(dim: int = 0, num_shards_attribute: str | None = None)
```

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

اربط الموترات (tensors) على طول `dim`. بالإضافة إلى ذلك، عند ربط عدد غير محدد من الموترات، يُعدّ `num_shards_attribute` حقل إعدادات يُقرأ لمعرفة عدد الموترات التي يجب إعادة إنشائها عند استخدام العمليات (Ops) المعاكسة.

#### transformers.MergeModulelist[[transformers.MergeModulelist]]

```python
transformers.MergeModulelist(dim: int = 0)
```

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

دمج قائمة من الموترات (tensors) في موتر واحد على طول البُعد الأول. نُعرّف هذا صراحةً لأنك في حالة EP أو TP تريد التأكد من أنك تعرف ما تفعله!

#### transformers.SplitModulelist[[transformers.SplitModulelist]]

```python
transformers.SplitModulelist(dim: int = 0)
```

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

عكس `MergeModulelist` باستخدام أحجام تقسيم صريحة لكل مجموعة.

#### transformers.PermuteForRope[[transformers.PermuteForRope]]

```python
transformers.PermuteForRope(subconfig_key: str | None = None, permute_layer_names: list[str] | None = None, inverse: bool = False)
```

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

يطبّق التباديل المطلوبة لتحويل أوزان RoPE المركبة إلى تنسيق sin/cos المنفصل.

#### transformers.VisionFuseAndPermuteForRope[[transformers.VisionFuseAndPermuteForRope]]

```python
transformers.VisionFuseAndPermuteForRope(dim: int = 0, permute_layer_names: list[str] | None = None, inverse: bool = True)
```

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

يطبّق التبادُل المطلوب لتحويل أوزان RoPE المركّبة إلى صيغة sin/cos المنفصلة على QKV المدمج. وهو ما يعادل استدعاء `PermuteForRope() + Concatenate()` لكنه يتيح لنا استدعاء `Permute` على مجموعة فرعية من الموترات المقسّمة فقط.

ملاحظة: تنطبق هذه العملية على العمود الفقري البصري في النماذج متعددة الوسائط فقط، لأنها تفحص `config.vision_config`

#### transformers.VisionUnfuseAndPermuteForRope[[transformers.VisionUnfuseAndPermuteForRope]]

```python
transformers.VisionUnfuseAndPermuteForRope(dim: int = 0, permute_layer_names: list[str] | None = None, inverse: bool = False)
```

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

يطبّق التباديل المطلوبة لتحويل أوزان RoPE المركبة إلى صيغة sin/cos المنفصلة على QKV المدمج. وهو ما يعادل استدعاء `Chunk() + PermuteForRope()` لكنه يتيح لنا استدعاء `Permute` على مجموعة فرعية من الموترات المقسمة فقط.

ملاحظة: تنطبق هذه العملية على العمود الفقري البصري في النماذج متعددة الوسائط فقط، لأنها تفحص `config.vision_config`

## الطبقات[[transformers.GradientCheckpointingLayer]]

#### transformers.GradientCheckpointingLayer[[transformers.GradientCheckpointingLayer]]

```python
transformers.GradientCheckpointingLayer(*args, **kwargs)
```

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

الفئة الأساسية للطبقات التي تستخدم فحص التدرجات.

تمكّن هذه الفئة من تفعيل خاصية فحص التدرّجات (gradient checkpointing) لطبقة. بشكل افتراضي، تكون خاصية فحص التدرّجات معطّلة (`gradient_checkpointing = False`). عند استدعاء `model.set_gradient_checkpointing()`، يتم تفعيل خاصية فحص التدرّجات من خلال تعيين `gradient_checkpointing = True` وتعيين دالة فحص إلى `_gradient_checkpointing_func`.

مهم:

عند استخدام نقطة التفتيش للتدرجات مع `use_reentrant=True`، يجب تمرير المدخلات التي تتطلب تدرجات (مثل الحالات المخفية) كحجج موضعية (`*args`) بدلاً من الحجج المسماة لضمان انتشار التدرجات بشكل صحيح.

مثال:

```python
>>> # Correct - hidden_states passed as positional arg
>>> out = self.layer(hidden_states, attention_mask=attention_mask)

>>> # Incorrect - hidden_states passed as keyword arg
>>> out = self.layer(hidden_states=hidden_states, attention_mask=attention_mask)
```

## دوال الانتباه[[transformers.AttentionInterface]]

#### transformers.AttentionInterface[[transformers.AttentionInterface]]

```python
transformers.AttentionInterface()
```

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

كائن يشبه القاموس يتتبع دوال الانتباه المسموح بها. يمكنك بسهولة إضافة دالة انتباه جديدة من خلال استدعاء `register()`. إذا احتاج نموذج إلى تجاوز دالة انتباه موجودة محليًا، مثل `sdpa`، فعليه أن يحدد نسخة جديدة من هذه الفئة داخل `modeling_<model>.py`، وأن يحددها على تلك النسخة.

#### تسجيل[[transformers.AttentionInterface.register]]

```python
register(key: str, value: Callable)
```

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

## دوال قناع الانتباه[[transformers.AttentionMaskInterface]]

#### transformers.AttentionMaskInterface[[transformers.AttentionMaskInterface]]

```python
transformers.AttentionMaskInterface()
```

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

#### تسجيل[[transformers.AttentionMaskInterface.register]]

```python
register(key: str, value: Callable)
```

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

## دوال تضمين الموضع الدوّار[[transformers.dynamic_rope_update]]

#### transformers.dynamic_rope_update[[transformers.dynamic_rope_update]]

```python
transformers.dynamic_rope_update(rope_forward)
```

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

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

rope_forward (Callable) : مسار الأمامي لتنفيذ RoPE.

**يعيد:**

مرور الأمامي المُزيَّن.

دالة مُزيِّنة لتحديث معاملات RoPE في مسار الأمامي، إذا كان النموذج يستخدم RoPE ديناميكيًا (أي تطبيق RoPE قد يعيد حساب تردداته في مسار الأمامي).

## وحدات Pytorch المخصصة[[transformers.Conv1D]]

#### transformers.Conv1D[[transformers.Conv1D]]

```python
transformers.Conv1D(nf, nx)
```

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

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

nf (`int`) : عدد ميزات الإخراج.

nx (`int`) : عدد ميزات الإدخال.

طبقة التمرير أحادية البُعد كما عرّفها رادفورد وآخرون لـ OpenAI GPT (والمستخدمة أيضاً في GPT-2).

يعمل بشكل أساسي كطبقة خطية لكن الأوزان تكون منقولة.

## دوال مساعدة في PyTorch[[transformers.apply_chunking_to_forward]]

#### transformers.apply_chunking_to_forward[[transformers.apply_chunking_to_forward]]

```python
transformers.apply_chunking_to_forward(forward_fn: Callable[..., torch.Tensor], chunk_size: int, chunk_dim: int, *input_tensors)
```

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

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

forward_fn (`Callable[..., torch.Tensor]`) : دالة التقدّم الأمامي للنموذج.

chunk_size (`int`) : حجم المقطع لمصفوفة مقسمة إلى مقاطع: `num_chunks = len(input_tensors[0]) / chunk_size`.

chunk_dim (`int`) : البُعد الذي يجب تقطيع `input_tensors` على أساسه.

input_tensors (`tuple[torch.Tensor]`) : تينسورات الإدخال الخاصة بـ `forward_fn` والتي سيتم تقسيمها

**يعيد:** `torch.Tensor`

متجه (Tensor) بنفس الشكل الذي كان سيُنتجه `forward_fn` لو طُبّق`.

يقسم هذا الدالة `input_tensors` إلى أجزاء أصغر من تينسور الإدخال بحجم `chunk_size` على طول البُعد `chunk_dim`. ثم يطبق طبقة `forward_fn` على كل جزء بشكل مستقل لتوفير الذاكرة.

إذا كان `forward_fn` مستقلاً عبر `chunk_dim`، فإن هذه الدالة ستُنتج نفس النتيجة التي تُنتجها عند تطبيق `forward_fn` مباشرةً على `input_tensors`.

أمثلة:

```python
# rename the usual forward() fn to forward_chunk()
def forward_chunk(self, hidden_states):
    hidden_states = self.decoder(hidden_states)
    return hidden_states

# implement a chunked forward function
def forward(self, hidden_states):
    return apply_chunking_to_forward(self.forward_chunk, self.chunk_size_lm_head, self.seq_len_dim, hidden_states)
```

#### transformers.pytorch_utils.prune_linear_layer[[transformers.pytorch_utils.prune_linear_layer]]

```python
transformers.pytorch_utils.prune_linear_layer(layer: nn.Linear, index: torch.LongTensor, dim: int = 0)
```

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

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

layer (`torch.nn.Linear`) : الطبقة التي سيتم تقليمها.

index (`torch.LongTensor`) : الفهارس التي يجب الإبقاء عليها في الطبقة.

dim (`int`، *اختياري*، القيمة الافتراضية 0) : البُعد الذي تُحفظ عليه الفهارس.

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

الطبقة المُقصاة كطبقة جديدة مع `requires_grad=True`.

اقصّ طبقة خطية للاحتفاظ فقط بالقيم الموجودة في index.

يُستخدم لإزالة الرؤوس.