# Table Transformer

## Aperçu

Le modèle Table Transformer a été proposé dans [PubTables-1M: Towards comprehensive table extraction from unstructured documents](https://huggingface.co/papers/2110.00061) par Brandon Smock, Rohith Pesala et Robin Abraham. Les auteurs introduisent un nouveau jeu de données, PubTables-1M, afin d'évaluer les progrès en extraction de tableaux à partir de documents non structurés, ainsi que la reconnaissance de structure de tableaux et l'analyse fonctionnelle. Ils entraînent deux modèles [DETR](detr), l'un pour la détection de tableaux et l'autre pour la reconnaissance de structure de tableaux, appelés Table Transformers.

L'abstract de l'article est le suivant :

*Récemment, des progrès considérables ont été réalisés dans l'application de l'apprentissage automatique au problème de l'inférence et de l'extraction de la structure des tableaux à partir de documents non structurés. Cependant, l'un des plus grands défis reste la création de jeux de données à grande échelle disposant d'une vérité terrain complète et non ambiguë. Pour y remédier, nous développons un nouveau jeu de données plus complet pour l'extraction de tableaux, appelé PubTables-1M. PubTables-1M contient près d'un million de tableaux issus d'articles scientifiques, prend en charge plusieurs modalités d'entrée et inclut des informations détaillées sur les en-têtes et les positions des structures de tableaux, ce qui le rend utile pour une grande variété d'approches de modélisation. Il traite également une source importante d'incohérence de la vérité terrain observée dans les jeux de données antérieurs, appelée sur-segmentation, en utilisant une procédure de normalisation novatrice. Nous démontrons que ces améliorations entraînent une augmentation significative des performances d'entraînement et une estimation plus fiable des performances du modèle lors de l'évaluation pour la reconnaissance de la structure des tableaux. De plus, nous montrons que les modèles de détection d'objets basés sur des transformers, entraînés sur PubTables-1M, produisent d'excellents résultats pour les trois tâches de détection, de reconnaissance de structure et d'analyse fonctionnelle, sans nécessiter de personnalisation particulière pour ces tâches.*

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

 Détection de tableaux et reconnaissance de la structure des tableaux, clarifiées. Extrait de l'article original.

Les auteurs ont publié 2 modèles, l'un pour la [détection de tableaux](https://huggingface.co/microsoft/table-transformer-detection) dans les documents, l'autre pour la [reconnaissance de la structure des tableaux](https://huggingface.co/microsoft/table-transformer-structure-recognition) (la tâche consistant à reconnaître les lignes, les colonnes, etc. d'un tableau).

Ce modèle a été contribué par [nielsr](https://huggingface.co/nielsr). Le code d'origine peut être trouvé [ici](https://github.com/microsoft/table-transformer).

> [!TIP]
> Définissez `use_kernels=True` dans [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour remplacer les couches prises en charge par des noyaux optimisés du Hub. Consultez [Chargement des noyaux](../kernel_doc/loading_kernels) pour en savoir plus.

## Ressources

- Un notebook de démonstration pour Table Transformer est disponible [ici](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/Table%20Transformer).
- Il s'avère que le bourrage des images est assez important pour la détection. Un fil GitHub intéressant, avec des réponses des auteurs, peut être trouvé [ici](https://github.com/microsoft/table-transformer/issues/68).

## TableTransformerConfig[[transformers.TableTransformerConfig]]

#### transformers.TableTransformerConfig[[transformers.TableTransformerConfig]]

```python
transformers.TableTransformerConfig(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, 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, is_encoder_decoder: bool = True, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, num_channels: int = 3, num_queries: int = 100, encoder_layers: int = 6, encoder_ffn_dim: int = 2048, encoder_attention_heads: int = 8, decoder_layers: int = 6, decoder_ffn_dim: int = 2048, decoder_attention_heads: int = 8, encoder_layerdrop: float | int = 0.0, decoder_layerdrop: float | int = 0.0, activation_function: str = 'relu', d_model: int = 256, dropout: float | int = 0.1, attention_dropout: float | int = 0.0, activation_dropout: float | int = 0.0, init_std: float = 0.02, init_xavier_std: float = 1.0, auxiliary_loss: bool = False, position_embedding_type: str = 'sine', dilation: bool = False, class_cost: int = 1, bbox_cost: int = 5, giou_cost: int = 2, mask_loss_coefficient: int = 1, dice_loss_coefficient: int = 1, bbox_loss_coefficient: int = 5, giou_loss_coefficient: int = 2, eos_coefficient: float = 0.1)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/configuration_table_transformer.py#L25)

**Paramètres :**

is_encoder_decoder (`bool`, *facultatif*, valeur par défaut `True`) : Indique si le modèle est utilisé comme encodeur/décodeur ou non.

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *facultatif*) : La configuration du modèle de base.

num_channels (`int`, *facultatif*, par défaut `3`) : Le nombre de canaux d'entrée.

num_queries (`int`, *facultatif*, valeur par défaut : 100) : Nombre de requêtes d'objets, c'est-à-dire de fentes de détection. Il s'agit du nombre maximal d'objets que [TableTransformerModel](/docs/transformers/v5.23.0/fr/model_doc/table-transformer#transformers.TableTransformerModel) peut détecter dans une seule image. Pour COCO, nous recommandons 100 requêtes.

encoder_layers (`int`, *facultatif*, valeur par défaut `6`) : Nombre de couches cachées dans l'encodeur Transformer. Utilise la même valeur que `num_layers` si non défini.

encoder_ffn_dim (`int`, *facultatif*, valeur par défaut `2048`) : Dimension de la couche « intermédiaire » (souvent appelée couche feed-forward) dans l'encodeur.

encoder_attention_heads (`int`, *facultatif*, valeur par défaut `8`) : Nombre de têtes d'attention pour chaque couche d'attention dans l'encodeur Transformer.

decoder_layers (`int`, *facultatif*, valeur par défaut `6`) : Nombre de couches cachées dans le décodeur Transformer. Utilise la même valeur que `num_layers` si non défini.

decoder_ffn_dim (`int`, *facultatif*, valeur par défaut `2048`) : Dimension de la couche « intermédiaire » (souvent appelée couche feed-forward) du décodeur.

decoder_attention_heads (`int`, *facultatif*, valeur par défaut `8`) : Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.

encoder_layerdrop (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : Probabilité de LayerDrop pour l'encodeur. Consultez l'article [LayerDrop](see https://huggingface.co/papers/1909.11556) pour plus de détails.

decoder_layerdrop (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : Probabilité de LayerDrop pour le décodeur. Consultez l'article [LayerDrop](see https://huggingface.co/papers/1909.11556) pour plus de détails.

activation_function (`str`, *facultatif*, par défaut `relu`) : Fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

d_model (`int`, *facultatif*, par défaut `256`) : Taille des couches d'encodeur et de la couche pooler.

dropout (`Union[float, int]`, *facultatif*, valeur par défaut `0.1`) : Le ratio pour toutes les couches de dropout.

attention_dropout (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : Le taux de dropout appliqué aux probabilités d'attention.

activation_dropout (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : Le taux de dropout pour les activations à l'intérieur de la couche entièrement connectée.

init_std (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids.

init_xavier_std (`float`, *facultatif*, par défaut `1.0`) : Le facteur d'échelle utilisé pour l'initialisation de Xavier des poids de l'attention croisée.

auxiliary_loss (`bool`, *facultatif*, par défaut `False`) : Indique si les pertes de décodage auxiliaires (perte à chaque couche du décodeur) doivent être utilisées.

position_embedding_type (`str`, *facultatif*, par défaut `"sine"`) : Type d'embeddings de position à utiliser sur les caractéristiques de l'image. Soit `"sine"` ou `"learned"`.

dilation (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut remplacer le pas (stride) par la dilatation dans le dernier bloc convolutif (DC5). Pris en charge uniquement lorsque `use_timm_backbone` = `True`.

class_cost (`int`, *facultatif*, valeur par défaut `1`) : Poids relatif de l'erreur de classification dans le coût d'appariement hongrois.

bbox_cost (`int`, *facultatif*, valeur par défaut `5`) : Poids relatif de l'erreur de boîte englobante L1 dans le coût d'appariement hongrois.

giou_cost (`int`, *facultatif*, valeur par défaut `2`) : Poids relatif de la perte d'IoU généralisée dans le coût d'appariement hongrois.

mask_loss_coefficient (`int`, *facultatif*, valeur par défaut `1`) : Poids relatif de la focal loss dans la perte de segmentation panoptique.

dice_loss_coefficient (`int`, *facultatif*, valeur par défaut `1`) : Poids relatif de la perte dice dans la perte de segmentation panoptique.

bbox_loss_coefficient (`int`, *facultatif*, valeur par défaut `5`) : Poids relatif de la perte de boîte englobante L1 dans la perte de segmentation panoptique.

giou_loss_coefficient (`int`, *facultatif*, valeur par défaut `2`) : Poids relatif de la perte IoU généralisée dans la perte de segmentation panoptique.

eos_coefficient (`float`, *facultatif*, valeur par défaut `0.1`) : Poids de classification relatif de la classe « no-object » dans la fonction de perte de détection d'objets.

Ceci est la classe de configuration destinée à stocker la configuration d'un modèle Table Transformer. Elle est utilisée pour instancier un modèle Table Transformer en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [microsoft/table-transformer-detection](https://huggingface.co/microsoft/table-transformer-detection)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemples :

```python
>>> from transformers import TableTransformerModel, TableTransformerConfig

>>> # Initializing a Table Transformer microsoft/table-transformer-detection style configuration
>>> configuration = TableTransformerConfig()

>>> # Initializing a model from the microsoft/table-transformer-detection style configuration
>>> model = TableTransformerModel(configuration)

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

## TableTransformerModel[[transformers.TableTransformerModel]]

#### transformers.TableTransformerModel[[transformers.TableTransformerModel]]

```python
transformers.TableTransformerModel(config: TableTransformerConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/modeling_table_transformer.py#L967)

**Paramètres :**

config ([TableTransformerConfig](/docs/transformers/v5.23.0/fr/model_doc/table-transformer#transformers.TableTransformerConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle Table Transformer brut (composé d'un backbone et d'un Transformer encodeur-décodeur) qui produit des états cachés bruts, sans aucune tête spécifique au sommet.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

#### forward[[transformers.TableTransformerModel.forward]]

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

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/modeling_table_transformer.py#L996)

**Paramètres :**

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`) : Les tenseurs correspondant aux images d’entrée. Les valeurs des pixels peuvent être obtenues à l’aide de [DetrImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/detr#transformers.DetrImageProcessor). Voir [DetrImageProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails (`processor_class` utilise [DetrImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/detr#transformers.DetrImageProcessor) pour le traitement des images).

pixel_mask (`torch.Tensor` de forme `(batch_size, height, width)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux valeurs de pixels de bourrage. Les valeurs du masque sont comprises dans `[0, 1]` : - 1 pour les pixels réels (c.-à-d. **non masqués**), - 0 pour les pixels de bourrage (c.-à-d. **masqués**). [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

decoder_attention_mask (`torch.Tensor` de forme `(batch_size, num_queries)`, *facultatif*) : Non utilisé par défaut. Peut être utilisé pour masquer les requêtes d'objets.

encoder_outputs (`torch.Tensor`, *facultatif*) : Tuple composé de (`last_hidden_state`, *facultatif* : `hidden_states`, *facultatif* : `attentions`) `last_hidden_state` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) est une séquence d'états cachés à la sortie de la dernière couche de l'encodeur. Utilisé dans l'attention croisée du décodeur.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer la carte de caractéristiques aplatie (sortie du backbone + couche de projection), vous pouvez choisir de passer directement une représentation aplatie d'une image.

decoder_inputs_embeds (`torch.Tensor` de forme `(batch_size, num_queries, hidden_size)`, *facultatif*) : Facultativement, au lieu d’initialiser les requêtes avec un tenseur de zéros, vous pouvez choisir de passer directement une représentation intégrée.

output_attentions (`bool`, *facultatif*) : Indique s'il faut ou non retourner les tenseurs d'attention de toutes les couches d'attention. Voir `attentions` sous les tenseurs retournés pour plus de détails.

output_hidden_states (`bool`, *facultatif*) : Indique s'il faut retourner les états cachés de toutes les couches. Voir `hidden_states` dans les tenseurs retournés pour plus de détails.

return_dict (`bool`, *facultatif*) : Indique s'il faut retourner un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput) plutôt qu'un simple tuple.

**Retourne :** `TableTransformerModelOutput` ou `tuple(torch.Tensor)`

Un `TableTransformerModelOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([TableTransformerConfig](/docs/transformers/v5.23.0/fr/model_doc/table-transformer#transformers.TableTransformerConfig)) et les entrées.

La méthode forward du modèle [TableTransformerModel](/docs/transformers/v5.23.0/fr/model_doc/table-transformer#transformers.TableTransformerModel) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`) -- Séquence d'états cachés à la sortie de la dernière couche du décodeur du modèle.

  Si `past_key_values` est utilisé, seule la dernière hidden-state des séquences de forme `(batch_size, 1, hidden_size)` est renvoyée.
- **past_key_values** (`EncoderDecoderCache`, *facultatif*, renvoyé lorsque `use_cache=True` est passé ou lorsque `config.use_cache=True`) -- Il s'agit d'une instance de [EncoderDecoderCache](/docs/transformers/v5.23.0/fr/internal/generation_utils#transformers.EncoderDecoderCache). Pour plus de détails, consultez notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contient des états cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés (voir l'entrée `past_key_values`) pour accélérer le décodage séquentiel.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du décodeur à la sortie de chaque couche, plus les sorties d'incorporation initiale facultatives.
- **decoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **cross_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention de la couche d'attention croisée du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'attention croisée.
- **encoder_last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche de l'encodeur du modèle.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés de l'encodeur à la sortie de chaque couche, plus les sorties d'incorporation initiales facultatives.
- **encoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention de l'encodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **intermediate_hidden_states** (`torch.Tensor` de forme `(config.decoder_layers, batch_size, sequence_length, hidden_size)`, *facultatif*, renvoyé lorsque `config.auxiliary_loss=True`) -- Activations intermédiaires du décodeur, c'est-à-dire la sortie de chaque couche du décodeur, chacune ayant passé par une normalisation de couche (layernorm).

Exemples :

```python
>>> from transformers import AutoImageProcessor, TableTransformerModel
>>> from huggingface_hub import hf_hub_download
>>> from PIL import Image

>>> file_path = hf_hub_download(repo_id="nielsr/example-pdf", repo_type="dataset", filename="example_pdf.png")
>>> image = Image.open(file_path).convert("RGB")

>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/table-transformer-detection")
>>> model = TableTransformerModel.from_pretrained("microsoft/table-transformer-detection")

>>> # prepare image for the model
>>> inputs = image_processor(images=image, return_tensors="pt")

>>> # forward pass
>>> outputs = model(**inputs)

>>> # the last hidden states are the final query embeddings of the Transformer decoder
>>> # these are of shape (batch_size, num_queries, hidden_size)
>>> last_hidden_states = outputs.last_hidden_state
>>> list(last_hidden_states.shape)
[1, 15, 256]
```

## TableTransformerForObjectDetection[[transformers.TableTransformerForObjectDetection]]

#### transformers.TableTransformerForObjectDetection[[transformers.TableTransformerForObjectDetection]]

```python
transformers.TableTransformerForObjectDetection(config: TableTransformerConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/modeling_table_transformer.py#L1136)

**Paramètres :**

config ([TableTransformerConfig](/docs/transformers/v5.23.0/fr/model_doc/table-transformer#transformers.TableTransformerConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Modèle Table Transformer (composé d'un backbone et d'un Transformer encodeur-décodeur) avec des têtes de détection d'objets au sommet, pour des tâches telles que la détection COCO.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

#### forward[[transformers.TableTransformerForObjectDetection.forward]]

```python
forward(pixel_values: Tensor, pixel_mask: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.Tensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: list[dict] | None = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/modeling_table_transformer.py#L1155)

**Paramètres :**

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`) : Les tenseurs correspondant aux images d’entrée. Les valeurs des pixels peuvent être obtenues à l’aide de [DetrImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/detr#transformers.DetrImageProcessor). Voir [DetrImageProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails (`processor_class` utilise [DetrImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/detr#transformers.DetrImageProcessor) pour le traitement des images).

pixel_mask (`torch.Tensor` de forme `(batch_size, height, width)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux valeurs de pixels de bourrage. Les valeurs du masque sont comprises dans `[0, 1]` : - 1 pour les pixels réels (c.-à-d. **non masqués**), - 0 pour les pixels de bourrage (c.-à-d. **masqués**). [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

decoder_attention_mask (`torch.Tensor` de forme `(batch_size, num_queries)`, *facultatif*) : Non utilisé par défaut. Peut être utilisé pour masquer les requêtes d'objets.

encoder_outputs (`torch.Tensor`, *facultatif*) : Tuple composé de (`last_hidden_state`, *facultatif* : `hidden_states`, *facultatif* : `attentions`) `last_hidden_state` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) est une séquence d'états cachés à la sortie de la dernière couche de l'encodeur. Utilisé dans l'attention croisée du décodeur.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer la carte de caractéristiques aplatie (sortie du backbone + couche de projection), vous pouvez choisir de passer directement une représentation aplatie d'une image.

decoder_inputs_embeds (`torch.Tensor` de forme `(batch_size, num_queries, hidden_size)`, *facultatif*) : Facultativement, au lieu d’initialiser les requêtes avec un tenseur de zéros, vous pouvez choisir de passer directement une représentation intégrée.

labels (`list[Dict]` de longueur `(batch_size,)`, *facultatif*) : Étiquettes pour le calcul de la perte de correspondance bipartite. Liste de dictionnaires, chaque dictionnaire contenant au moins les 2 clés suivantes : 'class_labels' et 'boxes' (les étiquettes de classes et les boîtes englobantes d'une image du lot, respectivement). Les étiquettes de classes elles-mêmes doivent être un `torch.LongTensor` de longueur `(number of bounding boxes in the image,)` et les boîtes un `torch.Tensor` de forme `(number of bounding boxes in the image, 4)`.

output_attentions (`bool`, *facultatif*) : Indique s'il faut ou non retourner les tenseurs d'attention de toutes les couches d'attention. Voir `attentions` sous les tenseurs retournés pour plus de détails.

output_hidden_states (`bool`, *facultatif*) : Indique s'il faut retourner les états cachés de toutes les couches. Voir `hidden_states` dans les tenseurs retournés pour plus de détails.

return_dict (`bool`, *facultatif*) : Indique s'il faut retourner un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput) plutôt qu'un simple tuple.

**Retourne :** `TableTransformerObjectDetectionOutput` ou `tuple(torch.Tensor)`

Un `TableTransformerObjectDetectionOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([TableTransformerConfig](/docs/transformers/v5.23.0/fr/model_doc/table-transformer#transformers.TableTransformerConfig)) et les entrées.

La méthode forward de [TableTransformerForObjectDetection](/docs/transformers/v5.23.0/fr/model_doc/table-transformer#transformers.TableTransformerForObjectDetection) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **loss** (`torch.Tensor` de forme `(1,)`, *facultatif*, renvoyé lorsque `labels` est fourni)) -- Perte totale en tant que combinaison linéaire d'une négation de la log-vraisemblance (entropie croisée) pour la prédiction de classe et d'une perte de boîte englobante. Cette dernière est définie comme une combinaison linéaire de la perte L1 et de la perte d'IoU généralisée insensible à l'échelle.
- **loss_dict** (`Dict`, *facultatif*) -- Un dictionnaire contenant les pertes individuelles. Utile pour la journalisation.
- **logits** (`torch.Tensor` de forme `(batch_size, num_queries, num_classes + 1)`) -- Logits de classification (y compris no-object) pour toutes les requêtes.
- **pred_boxes** (`torch.Tensor` de forme `(batch_size, num_queries, 4)`) -- Coordonnées normalisées des boîtes pour toutes les requêtes, représentées sous la forme (center_x, center_y, width, height). Ces valeurs sont normalisées dans [0, 1], par rapport à la taille de chaque image individuelle du lot (en ignorant tout padding éventuel). Vous pouvez utiliser `~TableTransformerImageProcessor.post_process_object_detection` pour récupérer les boîtes englobantes non normalisées.
- **auxiliary_outputs** (`list[Dict]`, *facultatif*) -- Facultatif, renvoyé uniquement lorsque les pertes auxiliaires sont activées (c.-à-d. `config.auxiliary_loss` est défini sur `True`) et que des étiquettes sont fournies. C'est une liste de dictionnaires contenant les deux clés ci-dessus (`logits` et `pred_boxes`) pour chaque couche du décodeur.
- **last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche du décodeur du modèle.
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d'embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du décodeur à la sortie de chaque couche, plus les sorties de l'intégration initiale.
- **decoder_attentions** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **cross_attentions** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention de la couche d'attention croisée du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'attention croisée.
- **encoder_last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche de l'encodeur du modèle.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés de l'encodeur à la sortie de chaque couche, plus les sorties des embeddings initiaux.
- **encoder_attentions** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention de l'encodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

Exemples :

```python
>>> from huggingface_hub import hf_hub_download
>>> from transformers import AutoImageProcessor, TableTransformerForObjectDetection
>>> import torch
>>> from PIL import Image

>>> file_path = hf_hub_download(repo_id="nielsr/example-pdf", repo_type="dataset", filename="example_pdf.png")
>>> image = Image.open(file_path).convert("RGB")

>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/table-transformer-detection")
>>> model = TableTransformerForObjectDetection.from_pretrained("microsoft/table-transformer-detection")

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

>>> # convert outputs (bounding boxes and class logits) to Pascal VOC format (xmin, ymin, xmax, ymax)
>>> target_sizes = torch.tensor([image.size[::-1]])
>>> results = image_processor.post_process_object_detection(outputs, threshold=0.9, target_sizes=target_sizes)[
...     0
... ]

>>> for score, label, box in zip(results["scores"], results["labels"], results["boxes"]):
...     box = [round(i, 2) for i in box.tolist()]
...     print(
...         f"Detected {model.config.id2label[label.item()]} with confidence "
...         f"{round(score.item(), 3)} at location {box}"
...     )
Detected table with confidence 1.0 at location [202.1, 210.59, 1119.22, 385.09]
```

