# الخسائر

تحتوي هذه الصفحة على توثيق مرجع واجهة برمجة التطبيقات (API) لخسائر التصنيف المضمنة في `timm`، بالإضافة إلى نظرة عامة على كيفية إنشائها وإعدادها من خلال مصنع الخسائر.

## الاستخدام

تُنشأ دوال الخسارة بالاسم باستخدام [`create_classification_loss`](#timm.loss.create_classification_loss). يحدد `multi_label` بين أهداف التسمية المفردة (فهارس الفئات، أو التوزيعات الناعمة الكثيفة من Mixup/CutMix) وأهداف التسمية المتعددة (تسميات ثنائية مستقلة كثيفة بشكل `(B, C)`)، ومع `loss_type=None` يختار المصنع `ce` أو `bce` وفقاً لذلك. تُسبق الحُجج الخاصة بكل دالة خسارة باسم الدالة (`asl_*`، `poly_*`، `db_*`، ...) وتُتجاهل من قِبل دوال الخسارة الأخرى. يرمي المصنع استثناءً عند التوليفات التي لا تدعمها دالة الخسارة، على سبيل المثال أوزان الفئات لدوال خسارة غير `bce` / `asl` متعددة التسميات، أو حُجج `bce_*` أو `class_counts` لدوال خسارة أخرى، أو دالة خسارة مخصصة للتسمية المتعددة فقط دون `multi_label` (أو دالة خسارة مخصصة للتسمية المفردة فقط مع وجوده).

```python
import torch
import timm
from timm.data import Mixup
from timm.loss import PolyCrossEntropy, create_classification_loss

# Single-label, class index targets. Label smoothing selects LabelSmoothingCrossEntropy.
criterion = create_classification_loss(smoothing=0.1)
loss = criterion(torch.randn(8, 1000), torch.randint(0, 1000, (8,)))

# Mixup/CutMix output dense soft targets with the smoothing already applied, SoftTargetCrossEntropy.
mixup_fn = Mixup(mixup_alpha=0.8, cutmix_alpha=1.0, label_smoothing=0.1, num_classes=1000)
criterion = create_classification_loss(smoothing=0.1, soft_targets=True)
images, target = mixup_fn(torch.randn(8, 3, 224, 224), torch.randint(0, 1000, (8,)))
loss = criterion(torch.randn(8, 1000), target)

# Multi-label, dense (B, C) binary targets. BCE by default, other losses by name.
criterion = create_classification_loss(multi_label=True)
criterion = create_classification_loss('asl', multi_label=True, asl_gamma_neg=4., asl_gamma_pos=1., asl_clip=0.05)
loss = criterion(torch.randn(8, 6), torch.randint(0, 2, (8, 6)).float())

# The training tasks create their criterion with the factory, multi_label is set by the task.
from timm.task import MultiLabelClassificationTask
model = timm.create_model('resnet18', num_classes=6)
task = MultiLabelClassificationTask(model, criterion_kwargs=dict(loss_type='zlpr'))

# Losses can also be constructed directly, note the class defaults can differ from the factory's (below).
criterion = PolyCrossEntropy(epsilon=2.)
```

يُخضع سكربت التدريب (`train.py`) خياراته إلى مصنع الخسارة على النحو التالي:

| خيار سطر الأوامر أو الشرط | حجة المصنع أو الأثر |
|---|---|
| `--loss` | `loss_type` |
| `--task multilabel` | `multi_label=True` |
| `--smoothing` | `smoothing`، القيمة الافتراضية 0.1 للتدريب على تسمية واحدة و0 للتدريب على تسميات متعددة |
| تمكين Mixup أو CutMix | `soft_targets=True` |
| `--asl-*` | الحجج `asl_*` المقابلة |
| `--poly-*` | الحجج `poly_*` المقابلة |
| `--twoway-*` | الحجج `twoway_*` المقابلة |
| `--db-*` | الحجج `db_*` المقابلة |
| `--bce-sum` | `bce_sum` |
| `--bce-target-thresh` | `bce_target_thresh` |
| `--aug-splits` | `jsd_splits` |
| `--class-stats` | عدّادات الفئات لدوال أوزان الفئات أدناه، و`class_counts` / `num_samples` لـ`db` |
| `--loss-pos-weight` | `pos_weight`، الذي يُحدَّد بواسطة دوال أوزان الفئات أدناه |
| `--loss-class-weight` | `class_weight`، يتم حلّه بواسطة دوال أوزان الفئات أدناه |
| `--loss-weight-*` | خيارات لدوال وزن الفئة أدناه |

راجع [وثائق التدريب](../training_script#multi-label-classification) لاستخدام سطر الأوامر.

### أنواع الدالة

يحتوي `LOSS_TYPES` على الأسماء المقبولة من المصنع، بينما يحتوي `MULTI_LABEL_LOSS_TYPES` على الأسماء التي يمكن استخدامها مع `multi_label=True`.

| `loss_type` | فئة | الأهداف | ملاحظات |
|---|---|---|---|
| `ce` | `nn.CrossEntropyLoss`, [`LabelSmoothingCrossEntropy`](#timm.loss.cross_entropy.LabelSmoothingCrossEntropy), [`SoftTargetCrossEntropy`](#timm.loss.cross_entropy.SoftTargetCrossEntropy) | تصنيف بوسم واحد | دالة Softmax cross-entropy، تعتمد الفئة على `smoothing` و`soft_targets`. الافتراضي هو فئة واحدة |
| `bce` | [`BinaryCrossEntropy`](#timm.loss.binary_cross_entropy.BinaryCrossEntropy) | كلاهما | Sigmoid BCE، الافتراضي للتصنيف متعدد الوسوم. أهداف فهارس الفئات مشفّرة بتشفير واحد-ساخن (one-hot)، `bce_target_thresh` يحوّل الأهداف الناعمة إلى قيم ثنائية، `bce_sum` يجمع عبر الفئات قبل أخذ المتوسط عبر الدفعة |
| `asl` | [`AsymmetricLossMultiLabel`](#timm.loss.asymmetric_loss.AsymmetricLossMultiLabel), [`AsymmetricLossSingleLabel`](#timm.loss.asymmetric_loss.AsymmetricLossSingleLabel) | كلاهما | [خسارة غير متماثلة](https://arxiv.org/abs/2009.14119)، تركيز منفصل للإيجابيات (`asl_gamma_pos`) والسلبيات (`asl_gamma_neg`)، هامش احتمال على السلبيات (`asl_clip`، متعدد التسميات فقط). يتطلب المتغير أحادي التسمية (softmax) أهدافًا بمؤشر الفئة، ولا يدعم Mixup/CutMix |
| `poly` | [`PolyBinaryCrossEntropy`](#timm.loss.poly_loss.PolyBinaryCrossEntropy), [`PolyCrossEntropy`](#timm.loss.poly_loss.PolyCrossEntropy) | كلاهما | [Poly-1](https://arxiv.org/abs/2204.12511)، يضيف `poly_epsilon * (1 - p_t)` إلى BCE / CE، وقيمة `0` تعيد الأمر إلى BCE / CE. يتضمن مصطلحات اختيارية للتركيز (`poly_gamma`) والتوازن (`poly_alpha`) للتسميات المتعددة |
| `jsd` | [`JsdCrossEntropy`](#timm.loss.jsd.JsdCrossEntropy) | تصنيف بوسم واحد | CE على الجزء النظيف + تباعد جينسن-شونان عبر `jsd_splits` من أجزاء المعالجة ([AugMix](https://arxiv.org/abs/1912.02781)) |
| `twoway` | [`TwoWayLoss`](#timm.loss.two_way_loss.TwoWayLoss) | تصنيف متعدد الوسوم | [دالة خسارة متعددة التسميات ثنائية الاتجاه](https://staff.aist.go.jp/takumi.kobayashi/publication/2023/CVPR2023.pdf)، درجات الحرارة `twoway_tp` / `twoway_tn`، الأهداف الثنائية فقط |
| `zlpr` | [`ZlprLoss`](#timm.loss.zlpr_loss.ZlprLoss) | تصنيف متعدد الوسوم | [ZLPR](https://arxiv.org/abs/2208.02955)، امتداد متعدد التسميات لـ softmax CE دون معاملات فائقة، للأهداف الثنائية فقط |
| `db` | [`DistributionBalancedLoss`](#timm.loss.distribution_balanced_loss.DistributionBalancedLoss) | تصنيف متعدد الوسوم | [دالة خسارة متوازنة التوزيع](https://arxiv.org/abs/2007.09654) للبيانات ذات الذيل الطويل، وتتطلب `class_counts` و`num_samples` |

### تنعيم التسميات والأهداف الناعمة

`smoothing` افتراضيًا 0 في المصنع. بالنسبة لأهداف التصنيف أحادية التسمية، تحصل فئة الهدف على `1 - s + s / C` بينما تحصل الفئات الأخرى على `s / C` (`LabelSmoothingCrossEntropy` مكافئ لـ `nn.CrossEntropyLoss(label_smoothing=s)`)، بينما يستخدم `bce` نفس تنعيم one-hot لأهداف فهارس الفئات. أما بالنسبة لأهداف التصنيف متعددة التسميات، فيتم تحريك كل تسمية ثنائية نحو 0.5، أي `y * (1 - s) + 0.5 * s`.

يطبّق `timm.data.Mixup` خاصية `label_smoothing` أثناء الخلط ويخرج أهدافاً كثيفة (مع `multi_label=True` يخلط وينعّم الأهداف الكثيفة متعددة التسميات). أنشئ الدالة الخاسرة مع `soft_targets=True` في هذه الحالة:

- يصبح **`ce`** `SoftTargetCrossEntropy`.
- لا تُنعّم **`bce`، `asl` متعدد التسميات، `poly` و`db`** الأهداف مرة أخرى.
- يُطلق **التصنيف أحادي التسمية `asl`** استثناءً عند استخدام `soft_targets`.
- **`twoway` / `zlpr`** ترفع خطأً عند استخدام `soft_targets` أو `smoothing` لأنها تُحوّل الأهداف إلى قيم ثنائية عند 0.5.

تتمتع الفئات بقيم افتراضية خاصة بها عند إنشائها مباشرة، حيث تعتمد `BinaryCrossEntropy` و`LabelSmoothingCrossEntropy` و`JsdCrossEntropy` على `smoothing=0.1` بينما تعتمد `AsymmetricLossSingleLabel` على `eps=0.1` (وهو تنعيم التسميات الخاص بها).

### وزن الفئات

يضرب `pos_weight` الحد الموجب لكل فئة، مما يحقق التوازن بين القيم الموجبة والسالبة داخل الفئة الواحدة. بينما يضرب `class_weight` إجمالي دالة الخسارة لكل فئة، مما يحقق التوازن بين الفئات فيما بينها. وكلاهما يقبل قيمة واحدة أو قيمة واحدة لكل فئة، ويدعمه كل من `bce` و`asl` متعدد الوسوم. يمكن تقديمها بشكل صريح أو اشتقاقها من عدد القيم الموجبة لكل فئة باستخدام [`compute_class_weights`](#timm.loss.compute_class_weights)، الذي يعيد حجة الدالة الخسارة التي تخصها الأوزان، بالإضافة إلى الأوزان نفسها. تُحتسب الفئات التي لا تحتوي على قيم موجبة على أنها تحتوي على قيمة واحدة، ويحدد `max_weight` الحد الأقصى للأوزان النهائية.

| `method` | الحُجّة | الأوزان لفئة تحتوي على `n` إيجابيات |
|---|---|---|
| `neg_pos` | `pos_weight` | `((num_samples - n) / n) ** power` |
| `inv_freq` | `class_weight` | `(num_samples / n) ** power`، مُعايَرةً إلى متوسط يساوي 1 |
| `effective_num` | `class_weight` | `(1 - beta) / (1 - beta ** n)` ([class-balanced](https://arxiv.org/abs/1901.05555))، مُطبَّعة بحيث يكون متوسطها 1 |

توجد الطرق في `CLASS_WEIGHT_METHODS`، ويربط `CLASS_WEIGHT_METHOD_KINDS` كل طريقة بحجتها الخاصة بالخسارة.

- [`load_class_stats`](#timm.loss.load_class_stats) يقرأ العدّات من ملف JSON يحتوي على مدخلات `pos_counts` و`num_samples`، كما كُتبت بواسطة `class_weights.py` في جذر المستودع.
- يقوم [`load_class_weights`](#timm.loss.load_class_weights) بتحليل الأوزان الصريحة (رقم، أو نص مفصول بفواصل، أو قائمة، أو ملف JSON / نص).
- يقبل [`resolve_class_weights`](#timm.loss.resolve_class_weights) إما اسم طريقة أو أوزانًا صريحة، كما تفعل `train.py` مع أعلامها.

تأخذ خسارة `db` التعدادات مباشرةً.

```python
import torch
from timm.loss import compute_class_weights, create_classification_loss, resolve_class_weights

pos_counts = [120, 3400, 560, 45, 980, 2100]  # positives per class
num_samples = 5000

kind, weights = compute_class_weights(pos_counts, num_samples, method='neg_pos', power=0.5)  # kind == 'pos_weight'
criterion = create_classification_loss(multi_label=True, pos_weight=weights)

# Method names (w/ class stats) or explicit weights, class_stats can be loaded w/ load_class_stats('stats.json')
class_stats = (torch.tensor(pos_counts), num_samples)
class_weight = resolve_class_weights('effective_num', 'class_weight', class_stats=class_stats, beta=0.999)
pos_weight = resolve_class_weights('2.0', 'pos_weight')
criterion = create_classification_loss('asl', multi_label=True, class_weight=class_weight, pos_weight=pos_weight)

criterion = create_classification_loss('db', multi_label=True, class_counts=pos_counts, num_samples=num_samples)
```

### ملاحظات حول الخسارة

- **الدقة.** تُحسب دوال الخسارة متعددة التسميات ASL وPoly-1 وDB وTwo-way وZLPR بدقة `float32` بغض النظر عن نوع بيانات اللوجيت، إذ إن احتمالات ASL منخفضة الدقة (`float16`) ستؤدي إلى انخفاض قيمة قفل اللوغاريتم.
- **الاختزال.** يدعم ASL متعدد التسميات قيم `asl_reduction` التالية:

  | القيمة | فوق الفئات | عبر الدفعة | ملاحظات |
  |---|---|---|---|
  | `batchmean` | المجموع | المتوسط | افتراضي |
  | `sum` | المجموع | المجموع | خفض ASL الأصلي؛ الخسارة تتناسب مع حجم الدفعة |
  | `mean` | المتوسط | المتوسط | مثل BCE |

  يجمع ASL ذو التسمية الواحدة على الفئات ويحسب المتوسط على الدفعة، ولا يقبل المصنع سوى `batchmean` له. أما `bce` و`poly` متعدد التسميات و`db` فتحسب المتوسط على الدفعة والفئات (بينما `bce_sum` يجمع على الفئات في حالة `bce`).

- يقارن **Two-way** بين أصعب قيمة سالبة (logit) وأصعب قيمة موجبة (logit) عبر فئات كل عينة وعبر العينات لكل فئة، حيث تساهم فقط العينات/الفئات التي تحتوي على قيمة موجبة. قيم الـ logits هنا هي درجات ترتيب وليست احتمالات مُعايرة عبر دالة sigmoid، لذا فإن المقاييس المعتمدة على عتبة (مثل F1) لا معنى لها، ويُفضَّل استخدام mAP.
- يدفع **ZLPR** كل قيمة لوغيت إيجابية فوق كل قيمة لوغيت سالبة مع اعتبار 0 عتبة القرار، بحيث تتنبأ القيم التي لوغيتها > 0 (سيجمويد > 0.5) بالإيجابيات.
- تضرب **DB** كل حد (عينة، فئة) بنسبة احتمال أخذ العينة على مستوى الفئة إلى احتمال أخذ العينة على مستوى الحالة، مع مراعاة التواجد المشترك للتسميات، وتُزاح القيم اللوجستية (logits) بواسطة مسبق الفئة (`db_init_bias`) وتُضبط القيم اللوجستية السالبة (`db_neg_scale`). وتُثبَّت العدّادات ضمن المدى `[1, num_samples - 1]`. ومعاملات خريطة إعادة التوازن والتوازن البؤري (focal balance) هي حُجج للفئة، ولا تُعرَض عبر المصنع (factory).
- يتوقع **JSD** الدفعة على شكل `jsd_splits` أقسام متساوية، حيث تكون الصور النظيفة أولاً (كما يرتب `fast_collate` عينات `AugMixDataset`)، بينما يستخدم حد CE القسم النظيف فقط. وزن JSD (`alpha=12`) هو معامل للفئة.

## واجهة برمجة التطبيقات

### دوال المصنع[[timm.loss.create_classification_loss]]

#### timm.loss.create_classification_loss[[timm.loss.create_classification_loss]]

```python
timm.loss.create_classification_loss(loss_type: typing.Optional[str] = None, multi_label: bool = False, smoothing: float = 0.0, soft_targets: bool = False, class_weight: typing.Union[torch.Tensor, float, typing.Sequence[float], NoneType] = None, pos_weight: typing.Union[torch.Tensor, float, typing.Sequence[float], NoneType] = None, bce_target_thresh: typing.Optional[float] = None, bce_sum: bool = False, asl_gamma_pos: float = 1.0, asl_gamma_neg: float = 4.0, asl_clip: typing.Optional[float] = 0.05, asl_reduction: str = 'batchmean', poly_epsilon: float = 2.0, poly_gamma: float = 0.0, poly_alpha: typing.Optional[float] = None, jsd_splits: int = 0, twoway_tp: float = 4.0, twoway_tn: float = 1.0, class_counts: typing.Union[torch.Tensor, typing.Sequence[float], NoneType] = None, num_samples: typing.Optional[int] = None, db_neg_scale: float = 2.0, db_init_bias: float = 0.05, db_focal_gamma: float = 2.0)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/_loss_factory.py#L31)

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

loss_type : أحد LOSS_TYPES، حيث تختار القيمة None نوع 'bce' للأهداف متعددة التسميات و 'ce' للأهداف أحادية التسمية. 'ce': إنتروبيا التقاطع مع softmax (مع تنويعات تنعيم التسمية / الأهداف الناعمة عند الحاجة)، 'bce': إنتروبيا التقاطع الثنائية (حجج bce_*)، 'asl': خسارة غير متماثلة، AsymmetricLossMultiLabel للأهداف متعددة التسميات، وإلا softmax AsymmetricLossSingleLabel، أهداف فهارس الفئات فقط، بدون Mixup/CutMix (حجج asl_*)، 'poly': خسارة Poly-1، PolyBinaryCrossEntropy (sigmoid) للأهداف متعددة التسميات، وإلا softmax PolyCrossEntropy (حجج poly_*)، 'jsd': تباعد Jensen-Shannon + إنتروبيا تقاطع على تقسيمات المعالجة، أحادي التسمية (jsd_splits)، 'twoway': خسارة ثنائية الاتجاه، أهداف متعددة التسميات ثنائية فقط (حجج twoway_*)، 'zlpr': خسارة ZLPR، أهداف متعددة التسميات ثنائية فقط، 'db': خسارة متوازنة التوزيع، متعددة التسميات (class_counts، num_samples، حجج db_*).

multi_label : الأهداف هي تسميات ثنائية مستقلة كثيفة ذات شكل (B, C).

smoothing : معامل تنعيم التسميات. يتم تجاهله عند تعيين soft_targets، لأن Mixup/CutMix يطبقانه بالفعل أثناء إنتاج التسميات الناعمة.

soft_targets : تصل الأهداف كتوزيعات ناعمة كثيفة من Mixup/CutMix بدلاً من فئات الفهارس.

class_weight : وزن خسارة لكل فئة، قيمة واحدة أو قيمة لكل فئة ('bce' و 'asl' متعددة التسميات).

pos_weight : وزن الحد الإيجابي، قيمة واحدة أو قيمة لكل فئة ('bce' و 'asl' متعددة التسميات).

bce_target_thresh : تحويل الأهداف الناعمة إلى قيم ثنائية إذا تجاوزت هذه القيمة (لخيار 'bce' فقط).

bce_sum : جمع الخسارة عبر الفئات قبل أخذ المتوسط على الدفعة ('bce' فقط).

asl_gamma_pos : معامل التركيز للأهداف الإيجابية ('asl' فقط).

asl_gamma_neg : معامل التركيز للأهداف السلبية ('asl' فقط).

asl_clip : هامش الاحتمال المُزاح نحو القيم السالبة، حيث يُعطَّل باستخدام None أو 0 (لوسم متعدد التسميات 'asl' فقط).

asl_reduction : 'batchmean' (المجموع عبر الفئات، والمتوسط عبر الدفعة)، أو 'sum' (ASL الأصلي)، أو 'mean' (لـ 'asl' متعدد التسميات فقط، بينما يستخدم ASL أحادي التسمية دائمًا 'batchmean').

poly_epsilon : معامل Poly-1، حيث يُقلل 0 إلى CE / BCE ('poly' فقط).

poly_gamma : معامل التركيز، القيمة 0 تعطّل الحدّ البؤري (لوضع 'poly' متعدد التسميات فقط).

poly_alpha : وزن التوازن الإيجابي / السلبي، تعطيله عند تعيينه إلى None (لوسم متعدد التسميات 'poly' فقط).

jsd_splits : عدد تقسيمات المعالجة، يجب أن يكون > 1 (لـ 'jsd' فقط).

twoway_tp : درجة حرارة اللوجيت الإيجابي (لوضع 'twoway' فقط).

twoway_tn : درجة حرارة اللوجيت السالبة (لوضع 'twoway' فقط).

class_counts : عدد عينات التدريب الإيجابية لكل فئة (لـ 'db' فقط).

num_samples : عدد عينات التدريب التي تم أخذ class_counts عليها (لـ'db' فقط).

db_neg_scale : مقياس اللوجيت المتسامح مع القيم السالبة، تعطّل القيمة 1 ('db' فقط).

db_init_bias : معامل إزاحة اللوجيت السابق للفئة، حيث يُعطَّل عند القيمة 0 (لنمط 'db' فقط).

db_focal_gamma : معامل التركيز، القيمة 0 تعطّل الحدّ البؤري (لنوع 'db' فقط).

أنشئ معيار التدريب لمهمة تصنيف.

### دوال وزن الفئات[[timm.loss.compute_class_weights]]

#### timm.loss.compute_class_weights[[timm.loss.compute_class_weights]]

```python
timm.loss.compute_class_weights(pos_counts: typing.Union[torch.Tensor, typing.Sequence[float]], num_samples: int, method: str = 'neg_pos', power: float = 1.0, beta: float = 0.999, max_weight: typing.Optional[float] = None)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/class_weights.py#L19)

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

pos_counts : عدد العينات الإيجابية لكل فئة (تكرار الفئة في حالات الأهداف أحادية التسمية).

num_samples : عدد العينات التي تم أخذ العدّ عليها.

method : أحد خيارات 'neg_pos': pos_weight = (negatives / positives) ** power، يوازن بين المصطلحات الموجبة والسالبة لكل فئة، 'inv_freq': class_weight تتناسب مع (num_samples / positives) ** power، بمتوسط 1، 'effective_num': class_weight متوازنة للفئات مشتقة من العدد الفعلي للعينات (1 - beta ** n) / (1 - beta)، https://arxiv.org/abs/1901.05555، بمتوسط 1.

power : أُسّ 'neg_pos' و 'inv_freq'، القيمة 0.5 تعطي إعادة وزنٍ أكثر نعومةً (جذر تربيعي).

beta : معامل الضبط الفعّال لعدد effective_num.

max_weight : الحد الأقصى المطبَّق على الأوزان النهائية.

**يعيد:**

حجة الخسارة التي تخص الأوزان ('pos_weight' أو 'class_weight') والأوزان من نوع float32.

احسب أوزان الخسارة لكل فئة من أعداد التسميات الإيجابية.

تُعامل الفئات التي لا تحتوي على أي قيم إيجابية على أنها تحتوي على قيمة واحدة، وتُحدَّد كل قيمة وزن بـ max_weight إذا تم ضبطها.

#### timm.loss.load_class_stats[[timm.loss.load_class_stats]]

```python
timm.loss.load_class_stats(path: typing.Optional[str])
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/class_weights.py#L71)

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

path : ملف JSON يحتوي على مدخلات 'pos_counts' و 'num_samples'. إذا كانت القيمة None أو سلسلة فارغة، تُعاد None.

**يعيد:**

عدّادات float32 وعدد العينات التي تم أخذها عليها.

حمّل عدد العينات الإيجابية لكل فئة وعدد العينات من ملف الإحصاءات class_weights.py.

#### timm.loss.load_class_weights[[timm.loss.load_class_weights]]

```python
timm.loss.load_class_weights(value: typing.Union[str, float, typing.Sequence[float], torch.Tensor, NoneType], key: str = 'class_weight')
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/class_weights.py#L94)

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

value : قيمة الوزن، قائمة، أو مسار. القيمة None أو سلسلة فارغة تعيد None.

key : مدخل لقراءة من كائنات JSON، مثل 'pos_weight' أو 'class_weight'.

**يعيد:**

عدد عشري (float) لقيمة واحدة (يُوزَّع على الفئات)، وإلا فمتجه أحادي البُعد من نوع float32.

تحليل أوزان الخسارة من رقم، أو قائمة مفصولة بفواصل، أو من ملف.

الملفات بصيغة JSON (قائمة، أو كائن يحتوي على القائمة تحت `key`، كما يكتبها class_weights.py) أو نص بأرقام مفصولة بفواصل أو مسافات بيضاء.

#### timm.loss.resolve_class_weights[[timm.loss.resolve_class_weights]]

```python
timm.loss.resolve_class_weights(value: typing.Union[str, float, typing.Sequence[float], torch.Tensor, NoneType], kind: str = 'class_weight', class_stats: typing.Optional[typing.Tuple[torch.Tensor, int]] = None, power: float = 1.0, beta: float = 0.999, max_weight: typing.Optional[float] = None)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/class_weights.py#L140)

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

value : طريقة موجودة في CLASS_WEIGHT_METHODS، أو أوزان صريحة لـ load_class_weights().

kind : حُجّة الخسارة المُحدَّدة، إما 'pos_weight' أو 'class_weight'.

class_stats : (counts, num_samples) من load_class_stats()، مطلوبة لأسماء الدوال.

power : راجع compute_class_weights().

beta : راجع compute_class_weights().

max_weight : راجع compute_class_weights().

حلّ أوزان الخسارة المُعطاة باسم دالة (تُحسب من إحصاءات الفئة) أو كأوزان صريحة.

### فئات دالة الخسارة للتصنيف أحادي التسمية[[timm.loss.LabelSmoothingCrossEntropy]]

#### timm.loss.LabelSmoothingCrossEntropy[[timm.loss.LabelSmoothingCrossEntropy]]

```python
timm.loss.LabelSmoothingCrossEntropy(smoothing = 0.1)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/cross_entropy.py#L11)

فقدان NLL مع تنعيم التسميات.

#### timm.loss.SoftTargetCrossEntropy[[timm.loss.SoftTargetCrossEntropy]]

```python
timm.loss.SoftTargetCrossEntropy()
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/cross_entropy.py#L29)

#### timm.loss.AsymmetricLossSingleLabel[[timm.loss.AsymmetricLossSingleLabel]]

```python
timm.loss.AsymmetricLossSingleLabel(gamma_pos = 1, gamma_neg = 4, eps: float = 0.1, reduction = 'mean')
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/asymmetric_loss.py#L102)

#### forward[[timm.loss.AsymmetricLossSingleLabel.forward]]

```python
forward(inputs, target, reduction = None)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/asymmetric_loss.py#L113)

" المعاملات ---------- x: مدخلات اللوجيتات y: الأهداف (متجه أحادي الترميز)

#### timm.loss.JsdCrossEntropy[[timm.loss.JsdCrossEntropy]]

```python
timm.loss.JsdCrossEntropy(num_splits = 3, alpha = 12, smoothing = 0.1)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/jsd.py#L8)

انحراف جينسن-شونسن + خسارة الانتروبيا المتقاطعة

بناءً على التنفيذ هنا: https://github.com/google-research/augmix/blob/master/imagenet.py من الورقة البحثية: 'AugMix: A Simple Data Processing Method to Improve Robustness and Uncertainty - https://arxiv.org/abs/1912.02781

تم بناؤه بواسطة / حقوق النشر 2020 روس وايتمان

#### timm.loss.PolyCrossEntropy[[timm.loss.PolyCrossEntropy]]

```python
timm.loss.PolyCrossEntropy(epsilon: float = 2.0, smoothing: float = 0.0, reduction: str = 'mean')
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/poly_loss.py#L19)

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

epsilon : معامل Poly-1، حيث 0 تعني إجهاد تقاطعي بسيط.

smoothing : تنعيم التسميات المطبّق على أهداف فهارس الفئات. يُفترض أن تكون الأهداف الكثيفة قد تم تنعيمها مسبقاً (على سبيل المثال، بواسطة Mixup/CutMix).

reduction : 'mean' أو 'sum' على مستوى الدفعة (batch)، أو 'none' لخسائر كل عينة على حدة.

تقاطع الإنتروبيا المتقاطعة لـ softmax متعدد العناصر، CE + epsilon * (1 - p_t)، لتصنيف التسمية المفردة.

هو مجموع احتمالات softmax المرجّحة بالأهداف sum_c(t_c * p_c)، لذا فإن تنعيم التسميات والأهداف الناعمة (Mixup/CutMix) تنطبق على كلا الحدين، كما في المرجع.

#### forward[[timm.loss.PolyCrossEntropy.forward]]

```python
forward(x: Tensor, target: Tensor)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/poly_loss.py#L41)

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

x : مدخلات اللوجيت (batch_size, num_classes).

target : فهارس الفئات (batch_size,) أو توزيعات الأهداف الكثيفة (batch_size, num_classes).

### فئات خسارة التصنيف متعدد الوسوم[[timm.loss.BinaryCrossEntropy]]

#### timm.loss.BinaryCrossEntropy[[timm.loss.BinaryCrossEntropy]]

```python
timm.loss.BinaryCrossEntropy(smoothing = 0.1, target_threshold: typing.Optional[float] = None, weight: typing.Optional[torch.Tensor] = None, reduction: str = 'mean', sum_classes: bool = False, pos_weight: typing.Union[torch.Tensor, float, NoneType] = None, smooth_dense: bool = False)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/binary_cross_entropy.py#L12)

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

smoothing : تنعيم التسميات المطبّق أثناء ترميز الأهداف ذات الفهرس بطريقة one-hot. يُفترض أن الأهداف الكثيفة قد تم تنعيمها مسبقاً (على سبيل المثال، بواسطة Mixup/CutMix) ما لم يتم تعيين smooth_dense.

target_threshold : تحويل (ناعم) الأهداف التي تتجاوز هذه القيمة إلى ثنائية.

weight : وزن إعادة التحجيم لكل فئة.

reduction : تقليل الخسارة.

sum_classes : اجمع الخسارة عبر الفئات قبل أخذ المتوسط عبر الدفعة.

pos_weight : وزن الفئة الإيجابية.

smooth_dense : كما يُطبَّق التنعيم على الأهداف التي تطابق بالفعل شكل القيم اللوجستية (التصنيف متعدد الوسوم)، بحيث يُحرَّك كل هدف ثنائي نحو القيمة 0.5.

BCE مع خيار one-hot من الأهداف الكثيفة، تنعيم التسميات، تحديد العتبة ملاحظة للتجارب التي تقارن بين CE وBCE مع تنعيم التسميات، قد يُحذف

#### timm.loss.AsymmetricLossMultiLabel[[timm.loss.AsymmetricLossMultiLabel]]

```python
timm.loss.AsymmetricLossMultiLabel(gamma_neg: float = 4, gamma_pos: float = 1, clip: typing.Optional[float] = 0.05, eps: float = 1e-08, disable_torch_grad_focal_loss: bool = False, smoothing: float = 0.0, reduction: str = 'batchmean', weight: typing.Optional[torch.Tensor] = None, pos_weight: typing.Union[torch.Tensor, float, NoneType] = None)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/asymmetric_loss.py#L7)

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

gamma_neg : معامل التركيز للأهداف السلبية.

gamma_pos : معامل التركيز للأهداف الإيجابية.

clip : هامش الاحتمال المُزاح نحو القيم السالبة (قص غير متماثل)، يُعطَّل إذا كان None أو 0.

eps : الحد الأدنى للاحتمال المقيد قبل اللوغاريتم.

disable_torch_grad_focal_loss : لا تقم بنشر الخلف (backpropagation) عبر أوزان التركيز.

smoothing : تنعيم التسميات، يُقرّب كل هدف (كثيف، ثنائي مستقل) نحو 0.5.

reduction : 'batchmean' يجمع عبر الفئات ويحسب المتوسط عبر الدفعة، 'sum' يجمع عبر الدفعة والفئات (اختزال ASL الأصلي، يتناسب مع حجم الدفعة)، 'mean' يحسب المتوسط عبر الدفعة والفئات، 'none' يحافظ على خسارة العنصر الواحد.

weight : وزن إعادة التحجيم لكل فئة.

pos_weight : وزن الحد الإيجابي، قيمة واحدة أو قيمة لكل فئة.

دالة الخسارة غير المتماثلة (ASL) لتصنيف التسميات المتعددة، https://arxiv.org/abs/2009.14119

#### forward[[timm.loss.AsymmetricLossMultiLabel.forward]]

```python
forward(x: Tensor, y: Tensor)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/asymmetric_loss.py#L52)

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

x : مدخلات اللوجيت (batch_size, num_classes).

y : أهداف كثيفة (متعددة الترميز أو ناعمة) (batch_size, num_classes).

#### timm.loss.PolyBinaryCrossEntropy[[timm.loss.PolyBinaryCrossEntropy]]

```python
timm.loss.PolyBinaryCrossEntropy(epsilon: float = 2.0, gamma: float = 0.0, alpha: typing.Optional[float] = None, smoothing: float = 0.0, reduction: str = 'mean')
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/poly_loss.py#L64)

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

epsilon : معامل Poly-1، حيث 0 يعني BCE العادي (أو خسارة focal).

gamma : معامل التركيز، حيث يؤدي تعيين القيمة 0 إلى تعطيل الحد البؤري.

alpha : وزن التوازن الإيجابي/السالب، تعطيله عند تعيينه على None.

smoothing : تنعيم التسميات، يُقرّب كل هدف (كثيف، ثنائي مستقل) نحو 0.5.

reduction : 'mean' يحسب المتوسط عبر الدفعة والفئات (كما في BCE)، و'batchmean' يجمع عبر الفئات ويحسب المتوسط عبر الدفعة، و'sum' يجمع عبر كليهما، و'none' يحافظ على خسارة العنصر الواحد.

خسارة Poly-1 sigmoid (focal)، FL + epsilon * (1 - p_t) ** (gamma + 1)، لتصنيف متعدد التسميات.

عندما يكون gamma = 0، تكون هذه الدالة هي BCE + epsilon * (1 - p_t) لكل فئة. عند تعيين alpha، تُوزَّن الحالات الإيجابية بـ alpha والحالات السلبية بـ 1 - alpha في كلا الحدين، كما في المرجع.

#### forward[[timm.loss.PolyBinaryCrossEntropy.forward]]

```python
forward(x: Tensor, target: Tensor)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/poly_loss.py#L98)

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

x : مدخلات اللوجيت (batch_size, num_classes).

target : أهداف كثيفة (متعددة الترميز أو ناعمة) (batch_size, num_classes).

#### timm.loss.DistributionBalancedLoss[[timm.loss.DistributionBalancedLoss]]

```python
timm.loss.DistributionBalancedLoss(class_counts: typing.Union[torch.Tensor, typing.Sequence[float]], num_samples: int, map_alpha: float = 0.1, map_beta: float = 10.0, map_mu: float = 0.2, neg_scale: float = 2.0, init_bias: float = 0.05, focal_gamma: float = 2.0, focal_balance: float = 2.0, smoothing: float = 0.0, reduction: str = 'mean')
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/distribution_balanced_loss.py#L16)

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

class_counts : عدد العينات الإيجابية لكل فئة على مجموعة التدريب.

num_samples : عدد عينات التدريب التي تم أخذ العدّ عليها.

map_alpha : الحد الأدنى لوزن خريطة إعادة التوازن.

map_beta : مقياس خريطة إعادة التوازن.

map_mu : عتبة خريطة إعادة التوازن.

neg_scale : مقياس اللوجيتات السالبة (lambda)، القيمة 1 تعطل التوسيع المتسامح مع السالب.

init_bias : معامل إزاحة اللوجيت المسبق للفئة (كيبا)، حيث يُعطَّل عند القيمة 0.

focal_gamma : معامل التركيز، حيث يؤدي تعيين القيمة 0 إلى تعطيل الحد البؤري (وfocal_balance).

focal_balance : مقياس ثابت لخسارة التركيز.

smoothing : تنعيم التسميات، يُقرّب كل هدف نحو 0.5.

reduction : 'mean' يحسب المتوسط عبر الدفعة والفئات (وهو المقياس المرجعي)، و'batchmean' يجمع عبر الفئات ويحسب المتوسط عبر الدفعة، و'sum' يجمع عبر كليهما، و'none' يحافظ على خسارة العنصر الواحد.

دالة الخسارة المتوازنة التوزيع (DB) لتصنيف التسميات المتعددة ذي الذيل الطويل.

دالة BCE مع دالة Sigmoid مع إضافتين:
* إعادة موازنة الأوزان: يُوزَّن كل حد (عينة، فئة) بنسبة احتمال أخذ العينة على مستوى الفئة 1 / n_i إلى احتمالها على مستوى المثال sum_j(y_j / n_j)، وهو ما يأخذ في الاعتبار تزامن ظهور التسميات لكل عينة، مع تنعيمه على النحو alpha + sigmoid(beta * (r - mu)).
* تنظيم متسامح مع القيم السالبة: تُزاح القيم غير المعيارية (logits) بواسطة انحياز مسبق للفئة، وتستخدم الحدود السالبة قيمة غير معيارية مُقيّمة، softplus(neg_scale * z) / neg_scale، حتى لا تُكبح القيم السالبة الكثيرة للفئات النادرة بشكل مفرط.
يتبع الحد البؤري الاختياري (1 - p_t) ** gamma إعداد مرجع DB.

تُوزّن الأهداف الناعمة (Mixup/CutMix) الحدود الموجبة والسالبة، بينما تستخدم أوزان إعادة التوازن الأهداف كما هي. يتطابق كلاهما مع المرجع للأهداف الثنائية.

#### forward[[timm.loss.DistributionBalancedLoss.forward]]

```python
forward(x: Tensor, target: Tensor)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/distribution_balanced_loss.py#L84)

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

x : مدخلات اللوجيت (batch_size, num_classes).

target : أهداف كثيفة (متعددة الترميز أو ناعمة) (batch_size, num_classes).

#### timm.loss.TwoWayLoss[[timm.loss.TwoWayLoss]]

```python
timm.loss.TwoWayLoss(tp: float = 4.0, tn: float = 1.0)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/two_way_loss.py#L17)

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

tp : درجة حرارة عملية soft-min على القيم الموجبة (positive logits).

tn : درجة الحرارة الخاصة بـ soft-max فوق القيم المنطقية السالبة.

خسارة متعددة التسميات ثنائية الاتجاه.

يقارن أصعب (soft-max) قيمة logit السالبة بأصعب (soft-min) قيمة logit الموجبة في اتجاهين، عبر فئات كل عينة وعبر العينات لكل فئة في الدفعة. تساهم فقط العينات/الفئات التي تحتوي على إيجابي واحد على الأقل في الاتجاه المعني.

تُحوَّل الأهداف إلى قيم ثنائية، حيث تُعدّ القيم التي تتجاوز 0.5 إيجابية. أما القيم غير المعالجة (Logits) فهي درجات ترتيب، وليست مُعايرة كاحتمالات سيجمويد مستقلة.

#### forward[[timm.loss.TwoWayLoss.forward]]

```python
forward(x: Tensor, target: Tensor)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/two_way_loss.py#L38)

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

x : مدخلات اللوجيت (batch_size, num_classes).

target : أهداف ثنائية كثيفة (batch_size, num_classes).

#### timm.loss.ZlprLoss[[timm.loss.ZlprLoss]]

```python
timm.loss.ZlprLoss(*args, **kwargs)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/zlpr_loss.py#L9)

خسارة ZLPR، وهي التوسعة متعددة التسميات لخسارة الانتروبيا المتقاطعة لـ softmax.

لكل عينة، log(1 + sum_neg exp(s_j)) + log(1 + sum_pos exp(-s_i)). يتم دفع كل لوجيت إيجابي فوق كل لوجيت سلبي، ويعمل الصفر كعتبة قرار، لذا فإن اللوجيتات > 0 (سيجمويد > 0.5) تتنبأ بالإيجابيات. لا توجد معاملات فائقة، ولا ينمو الخسارة مع عدد الفئات السلبية كما هو الحال في BCE لكل فئة.

تُحوَّل الأهداف إلى قيم ثنائية، حيث تُعدّ القيم التي تتجاوز 0.5 إيجابية.

#### forward[[timm.loss.ZlprLoss.forward]]

```python
forward(x: Tensor, target: Tensor)
```

[المصدر](https://github.com/huggingface/pytorch-image-models/blob/v1.0.31/timm/loss/zlpr_loss.py#L19)

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

x : مدخلات اللوجيت (batch_size, num_classes).

target : أهداف ثنائية كثيفة (batch_size, num_classes).