# UPerNet

## نظرة عامة

قُدِّم نموذج UPerNet في [Unified Perceptual Parsing for Scene Understanding](https://huggingface.co/papers/1807.10221) بواسطة Tete Xiao وYingcheng Liu وBolei Zhou وYuning Jiang وJian Sun. يُعد UPerNet إطاراً عاماً لتجزئة مجموعة واسعة من المفاهيم من الصور بفعالية، بالاستفادة من أي عمود فقري بصري مثل [ConvNeXt](convnext) أو [Swin](swin).

المستخلص من الورقة البحثية هو كالتالي:

*يتعرّف البشر على العالم البصري على مستويات متعددة: فنصنّف المشاهد ونكتشف الكائنات بداخلها بسلاسة، مع تحديد فينيتها وأسطحها إلى جانب أجزائها التركيبية المختلفة. في هذه الورقة، ندرس مهمة جديدة تُسمى التحليل الإدراكي الموحّد (Unified Perceptual Parsing)، والتي تتطلب من أنظمة الرؤية الآلية التعرف على أكبر عدد ممكن من المفاهيم البصرية من صورة معيّنة. تم تطوير إطار عمل متعدد المهام يُسمى UPerNet واستراتيجية تدريب للتعلم من تعليقات الصور غير المتجانسة. قمنا باختبار إطار عملنا على التحليل الإدراكي الموحّد وأظهرنا أنه قادر على تجزئة مجموعة واسعة من المفاهيم من الصور بفعالية. تم تطبيق الشبكات المدرَّبة بعد ذلك لاكتشاف المعرفة البصرية في المشاهد الطبيعية.*

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/upernet_architecture.jpg"
alt="drawing" width="600"/>

 إطار عمل UPerNet. مأخوذ من الورقة الأصلية.

تمت مساهمة هذا النموذج من قِبل [nielsr](https://huggingface.co/nielsr). يعتمد الكود الأصلي على mmsegmentation الخاص بـ OpenMMLab [هنا](https://github.com/open-mmlab/mmsegmentation/blob/master/mmseg/models/decode_heads/uper_head.py).

## أمثلة على الاستخدام

UPerNet هو إطار عام للتجزئة الدلالية. يمكن استخدامه مع أي عمود فقري للرؤية، على النحو التالي:

```python
from transformers import SwinConfig, UperNetConfig, UperNetForSemanticSegmentation

backbone_config = SwinConfig(out_features=["stage1", "stage2", "stage3", "stage4"])

config = UperNetConfig(backbone_config=backbone_config)
model = UperNetForSemanticSegmentation(config)
```

لاستخدام عمود رؤية آخر، مثل [ConvNeXt](convnext)، ما عليك سوى إنشاء النموذج مع العمود المناسب:

```python
from transformers import ConvNextConfig, UperNetConfig, UperNetForSemanticSegmentation

backbone_config = ConvNextConfig(out_features=["stage1", "stage2", "stage3", "stage4"])

config = UperNetConfig(backbone_config=backbone_config)
model = UperNetForSemanticSegmentation(config)
```

لاحظ أن هذا سيؤدي إلى تهيئة جميع أوزان النموذج بشكل عشوائي.

## الموارد

قائمة بموارد رسمية من Hugging Face وموارد مجتمعية (مشار إليها بـ 🌎) لمساعدتك على البدء باستخدام UPerNet.

- يمكن العثور على كراسات العرض الخاصة بـ UPerNet [هنا](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UPerNet).
- يُؤمّن هذا [دفتر الملاحظات](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/semantic_segmentation.ipynb) دعمًا لـ [UperNetForSemanticSegmentation](/docs/transformers/v5.23.0/ar/model_doc/upernet#transformers.UperNetForSemanticSegmentation).
- انظر أيضاً: [دليل مهمة التقسيم الدلالي](../tasks/semantic_segmentation)

إذا كنت مهتمًا بتقديم مورد ليُدرج هنا، فلا تتردد في فتح طلب سحب وسنقوم بمراجعته! يُفضَّل أن يُظهر المورد شيئًا جديدًا بدلاً من تكرار مورد موجود مسبقًا.

## UperNetConfig[[transformers.UperNetConfig]]

#### transformers.UperNetConfig[[transformers.UperNetConfig]]

```python
transformers.UperNetConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, hidden_size: int = 512, initializer_range: float = 0.02, pool_scales: list[int] | tuple[int, ...] = (1, 2, 3, 6), use_auxiliary_head: bool = True, auxiliary_loss_weight: float = 0.4, auxiliary_in_channels: int | None = None, auxiliary_channels: int = 256, auxiliary_num_convs: int = 1, auxiliary_concat_input: bool = False, loss_ignore_index: int = 255)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/configuration_upernet.py#L25)

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

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`، *اختياري*) : إعدادات نموذج الهيكل الأساسي.

hidden_size (`int`، *اختياري*، القيمة الافتراضية `512`) : بُعد التمثيلات المخفية.

initializer_range (`float`، *اختياري*، القيمة الافتراضية `0.02`) : الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.

pool_scales (`tuple[int]`, *اختياري*, الافتراضي هو `[1, 2, 3, 6]`) : مقاييس التجميع المستخدمة في وحدة هرم التجميع المطبقة على خريطة الميزات الأخيرة.

use_auxiliary_head (`bool`, *اختياري*, القيمة الافتراضية هي `True`) : ما إذا كان سيتم استخدام رأس مساعد أثناء التدريب.

auxiliary_loss_weight (`float`, *اختياري*, القيمة الافتراضية 0.4) : وزن خسارة الانتروبيا المتقاطعة للرأس المساعد.

auxiliary_in_channels (`int`، *اختياري*، القيمة الافتراضية 256) : عدد قنوات الإدخال في الرأس المساعد.

auxiliary_channels (`int`, *اختياري*, القيمة الافتراضية 256) : عدد القنوات المستخدمة في الرأس المساعد.

auxiliary_num_convs (`int`, *اختياري*, القيمة الافتراضية 1) : عدد طبقات الالتفاف المستخدمة في الرأس المساعد.

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

loss_ignore_index (`int`، *اختياري*، القيمة الافتراضية 255) : الفهرس الذي تتجاهله دالة الخسارة.

هذه فئة الإعدادات المخزنة لإعدادات UpernetModel. تُستخدم لاستحداث نموذج Upernet وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ [openmmlab/upernet-convnext-tiny](https://huggingface.co/openmmlab/upernet-convnext-tiny)

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/v5.23.0/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/v5.23.0/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

أمثلة:

```python
>>> from transformers import UperNetConfig, UperNetForSemanticSegmentation

>>> # Initializing a configuration
>>> configuration = UperNetConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = UperNetForSemanticSegmentation(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## UperNetForSemanticSegmentation[[transformers.UperNetForSemanticSegmentation]]

#### transformers.UperNetForSemanticSegmentation[[transformers.UperNetForSemanticSegmentation]]

```python
transformers.UperNetForSemanticSegmentation(config: UperNetConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/modeling_upernet.py#L278)

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

config ([UperNetConfig](/docs/transformers/v5.23.0/ar/model_doc/upernet#transformers.UperNetConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/v5.23.0/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

إطار عمل UperNet الذي يستفيد من أي عمود فقري بصري، على سبيل المثال، لـ ADE20k وCityScapes.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/v5.23.0/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.UperNetForSemanticSegmentation.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, labels: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/modeling_upernet.py#L293)

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

pixel_values (`torch.Tensor` من الشكل `(batch_size, num_channels, image_size, image_size)`، *اختياري*) : المصفوفات المقابلة للصور المدخلة. يمكن الحصول على قيم البكسل باستخدام [SegformerImageProcessor](/docs/transformers/v5.23.0/ar/model_doc/segformer#transformers.SegformerImageProcessor). راجع [SegformerImageProcessor.__call__()](/docs/transformers/v5.23.0/ar/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) للتفاصيل (`processor_class` يستخدم [SegformerImageProcessor](/docs/transformers/v5.23.0/ar/model_doc/segformer#transformers.SegformerImageProcessor) لمعالجة الصور).

output_attentions (`bool`، *اختياري*) : ما إذا كان سيتم إرجاع مصفوفات الانتباه لجميع طبقات الانتباه. راجع `attentions` ضمن المصفوفات المُرجعة لمزيد من التفاصيل.

output_hidden_states (`bool`, *اختياري*) : ما إذا كان سيتم إرجاع الحالات المخفية لجميع الطبقات. راجع `hidden_states` ضمن الموترات المُرجعة لمزيد من التفاصيل.

labels (`torch.LongTensor` بشكل `(batch_size, height, width)`، *اختياري*) : خرائط التقسيم الدلالي المرجعية لحساب الخسارة. يجب أن تكون الفهارس ضمن `[0, ..., config.num_labels - 1]`. إذا كان `config.num_labels > 1`، يتم حساب خسارة التصنيف (Cross-Entropy).

return_dict (`bool`، *اختياري*) : ما إذا كان سيتم إرجاع [ModelOutput](/docs/transformers/v5.23.0/ar/main_classes/output#transformers.utils.ModelOutput) بدلاً من tuple عادي.

**يعيد:** [SemanticSegmenterOutput](/docs/transformers/v5.23.0/ar/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) أو `tuple(torch.Tensor)`

[SemanticSegmenterOutput](/docs/transformers/v5.23.0/ar/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) أو مجموعة مرتبة من `torch.Tensor` (في حال تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([UperNetConfig](/docs/transformers/v5.23.0/ar/model_doc/upernet#transformers.UperNetConfig)) والمدخلات.

تتجاوز طريقة [UperNetForSemanticSegmentation](/docs/transformers/v5.23.0/ar/model_doc/upernet#transformers.UperNetForSemanticSegmentation) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

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

- **loss** (`torch.Tensor` من الشكل `(1,)`, *اختياري*، يُعاد عند تقديم `labels`) -- خسارة التصنيف (أو الانحدار إذا كان config.num_labels==1).
- **logits** (`torch.Tensor` بأبعاد `(batch_size, config.num_labels, logits_height, logits_width)`) -- درجات التصنيف لكل بكسل.

  

  لا تتطابق بالضرورة أحجام logits المُعادَة مع أحجام `pixel_values` المُمرَّرة كمدخلات. وذلك لتجنّب إجراء عمليتي استيفاء وفقدان بعض الجودة عندما يحتاج المستخدم إلى تغيير حجم logits إلى حجم الصورة الأصلي كخطوة ما بعد المعالجة. يجب عليك دائمًا التحقق من شكل logits وتغيير حجمها حسب الحاجة.

  
- **hidden_states** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, patch_size, hidden_size)`.

  حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.
- **attentions** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة (Tuple) من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, patch_size, sequence_length)`.

  أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

أمثلة:
```python
>>> from transformers import AutoImageProcessor, UperNetForSemanticSegmentation
>>> from PIL import Image
>>> from huggingface_hub import hf_hub_download

>>> image_processor = AutoImageProcessor.from_pretrained("openmmlab/upernet-convnext-tiny")
>>> model = UperNetForSemanticSegmentation.from_pretrained("openmmlab/upernet-convnext-tiny")

>>> filepath = hf_hub_download(
...     repo_id="hf-internal-testing/fixtures_ade20k", filename="ADE_val_00000001.jpg", repo_type="dataset"
... )
>>> image = Image.open(filepath).convert("RGB")

>>> inputs = image_processor(images=image, return_tensors="pt")

>>> outputs = model(**inputs)

>>> logits = outputs.logits  # shape (batch_size, num_labels, height, width)
>>> list(logits.shape)
[1, 150, 512, 512]
```

