# UDOP

## Aperçu

Le modèle UDOP a été proposé dans [Unifying Vision, Text, and Layout for Universal Document Processing](https://huggingface.co/papers/2212.02623) par Zineng Tang, Ziyi Yang, Guoxin Wang, Yuwei Fang, Yang Liu, Chenguang Zhu, Michael Zeng, Cha Zhang et Mohit Bansal. UDOP adopte une architecture Transformer encodeur-décodeur basée sur [T5](t5) pour des tâches de document AI telles que la classification d’images de documents, l’analyse de documents et la question-réponse visuelle sur documents.

L'abstract de l'article est le suivant :

Nous proposons Universal Document Processing (UDOP), un modèle de base en Document AI qui unifie les modalités texte, image et mise en page, ainsi que divers formats de tâches, notamment la compréhension et la génération de documents. UDOP exploite la corrélation spatiale entre le contenu textuel et l'image du document pour modéliser les modalités image, texte et mise en page avec une représentation uniforme. Grâce à un Vision-Text-Layout Transformer novateur, UDOP unifie le pré-entraînement et les tâches en aval multi-domaines dans un schéma de génération de séquences basé sur des prompts. UDOP est pré-entraîné à la fois sur de grands corpus de documents non étiquetés à l'aide d'objectifs auto-supervisés innovants et sur des données étiquetées variées. UDOP apprend également à générer des images de documents à partir des modalités texte et mise en page via la reconstruction d'images masquées. À notre connaissance, c'est la première fois dans le domaine de la Document AI qu'un modèle atteint simultanément une édition neuronale de documents de haute qualité et une personnalisation du contenu. Notre méthode établit l'état de l'art sur 9 tâches de Document AI, par exemple la compréhension de documents et les questions-réponses, sur des domaines de données variés tels que les rapports financiers, les articles académiques et les sites web. UDOP se classe en tête du classement du Document Understanding Benchmark (DUE).*

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

 Architecture UDOP. Issue de l'article original.

## Conseils d'utilisation

- En plus de *input_ids*, [UdopForConditionalGeneration](/docs/transformers/main/fr/model_doc/udop#transformers.UdopForConditionalGeneration) s'attend également à l'entrée `bbox`, qui correspond aux boîtes englobantes (c'est-à-dire les positions 2D) des jetons d'entrée. Celles-ci peuvent être obtenues à l'aide d'un moteur OCR externe tel que [Tesseract](https://github.com/tesseract-ocr/tesseract) de Google (un [enveloppe Python](https://pypi.org/project/pytesseract/) est disponible). Chaque boîte englobante doit être au format (x0, y0, x1, y1), où (x0, y0) correspond à la position du coin supérieur gauche de la boîte englobante, et (x1, y1) représente la position du coin inférieur droit. Notez qu'il faut d'abord normaliser les boîtes englobantes sur une échelle de 0 à 1000. Pour normaliser, vous pouvez utiliser la fonction suivante :

```python
def normalize_bbox(bbox, width, height):
    return [
        int(1000 * (bbox[0] / width)),
        int(1000 * (bbox[1] / height)),
        int(1000 * (bbox[2] / width)),
        int(1000 * (bbox[3] / height)),
    ]
```

Ici, `width` et `height` correspondent à la largeur et à la hauteur du document d'origine dans lequel le jeton apparaît. Ces valeurs peuvent être obtenues à l'aide de la bibliothèque Python Image Library (PIL), par exemple, comme suit :

```python
from PIL import Image

# Document can be a png, jpg, etc. PDFs must be converted to images.
image = Image.open(name_of_your_document).convert("RGB")

width, height = image.size
```

On peut utiliser [UdopProcessor](/docs/transformers/main/fr/model_doc/udop#transformers.UdopProcessor) pour préparer les images et le texte destinés au modèle, ce qui prend en charge l’ensemble de ces tâches. Par défaut, cette classe utilise le moteur Tesseract pour extraire une liste de mots et de boîtes (coordonnées) d’un document donné. Sa fonctionnalité est équivalente à celle de [LayoutLMv3Processor](/docs/transformers/main/fr/model_doc/layoutlmv3#transformers.LayoutLMv3Processor), elle permet donc de passer `apply_ocr=False` si vous préférez utiliser votre propre moteur OCR, ou `apply_ocr=True` si vous souhaitez utiliser le moteur OCR par défaut. Reportez-vous au [guide d’utilisation de LayoutLMv2](layoutlmv2#usage-layoutlmv2processor) pour tous les cas d’usage possibles (la fonctionnalité de `UdopProcessor` est identique).

- Si vous utilisez votre propre moteur OCR, une recommandation est l'[API Read](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/how-to/call-read-api) d'Azure, qui prend en charge les segments de ligne. L'utilisation d'embeddings de position de segment améliore généralement les performances.
- Lors de l'inférence, il est recommandé d'utiliser la méthode `generate` pour générer du texte de manière autorégressive à partir d'une image de document.
- Le modèle a été pré-entraîné sur des objectifs auto-supervisés et supervisés. Il est possible d’utiliser les différents préfixes de tâche (prompts) employés lors du pré-entraînement pour évaluer les capacités du modèle telles qu’elles sont. Par exemple, on peut interroger le modèle avec « Question answering. What is the date? », car « Question answering. » est le préfixe de tâche utilisé lors du pré-entraînement pour DocVQA. Consultez l’[article](https://huggingface.co/papers/2212.02623) (tableau 1) pour la liste complète des préfixes de tâche.
- Il est également possible d’affiner [UdopEncoderModel](/docs/transformers/main/fr/model_doc/udop#transformers.UdopEncoderModel), qui correspond à la partie encodeur-only de UDOP, pouvant être considérée comme un encodeur Transformer de type LayoutLMv3. Pour les tâches discriminatives, il suffit d’ajouter un classifieur linéaire au-dessus et de l’affiner sur un jeu de données étiqueté.

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

## Ressources

Une liste de ressources officielles Hugging Face et de la communauté (indiquées par 🌎) pour vous aider à démarrer avec UDOP. Si vous souhaitez soumettre une ressource pour qu'elle soit incluse ici, n'hésitez pas à ouvrir une Pull Request et nous la examinerons ! La ressource devrait idéalement démontrer quelque chose de nouveau plutôt que de dupliquer une ressource existante.

- Des notebooks de démonstration concernant UDOP sont disponibles [ici](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UDOP) et montrent comment
pour effectuer un fine-tuning de UDOP sur un jeu de données personnalisé, ainsi que pour l'inférence. 🌎
- [Guide de la tâche de réponse à des questions sur des documents](../tasks/document_question_answering)

## UdopConfig[[transformers.UdopConfig]]

#### transformers.UdopConfig[[transformers.UdopConfig]]

```python
transformers.UdopConfig(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, vocab_size: int = 33201, d_model: int = 1024, d_kv: int = 64, d_ff: int = 4096, num_layers: int = 24, num_decoder_layers: int | None = None, num_heads: int = 16, relative_attention_num_buckets: int = 32, relative_attention_max_distance: int = 128, relative_bias_args: list[dict] | None = None, dropout_rate: float | int = 0.1, layer_norm_epsilon: float = 1e-06, initializer_factor: float = 1.0, feed_forward_proj: str = 'relu', use_cache: bool = True, pad_token_id: int | None = 0, eos_token_id: int | list[int] | None = 1, max_2d_position_embeddings: int = 1024, image_size: int | list[int] | tuple[int, int] = 224, patch_size: int | list[int] | tuple[int, int] = 16, num_channels: int = 3, is_decoder: bool = False, add_cross_attention: bool = False, tie_word_embeddings: bool = True)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/configuration_udop.py#L24)

**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.

vocab_size (`int`, *facultatif*, valeur par défaut `33201`) : Taille du vocabulaire du modèle. Définit le nombre de jetons différents qui peuvent être représentés par `input_ids`.

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

d_kv (`int`, *facultatif*, valeur par défaut `64`) : Taille des projections de clé, requête et valeur par tête d'attention. Le `inner_dim` de la couche de projection sera défini comme `num_heads * d_kv`.

d_ff (`int`, *facultatif*, valeur par défaut `4096`) : Dimension des représentations MLP.

num_layers (`int`, *facultatif*, valeur par défaut `24`) : Nombre de couches cachées dans le décodeur Transformer.

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

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

relative_attention_num_buckets (`int`, *facultatif*, valeur par défaut : 32) : Le nombre de buckets à utiliser pour chaque couche d'attention.

relative_attention_max_distance (`int`, *facultatif*, valeur par défaut 128) : La distance maximale des séquences les plus longues pour la séparation des buckets.

relative_bias_args (`list[dict]`, *facultatif*, valeur par défaut `[{'type' : '1d'}, {'type': 'horizontal'}, {'type': 'vertical'}]`) : une liste de dictionnaires contenant les arguments des couches de biais relatif.

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

layer_norm_epsilon (`float`, *facultatif*, par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation par couche.

initializer_factor (`float`, *facultatif*, par défaut `1.0`) : Un facteur pour l'initialisation de toutes les matrices de poids (doit être maintenu à 1, utilisé en interne pour les tests d'initialisation).

feed_forward_proj (`string`, *facultatif*, par défaut `"relu"`) : Type de couche feed forward à utiliser. Doit être l'un des `"relu"` ou `"gated-gelu"`. Udopv1.1 utilise la projection feed forward `"gated-gelu"`. Udop d'origine utilise `"relu"`.

use_cache (`bool`, *facultatif*, valeur par défaut `True`) : Indique si le modèle doit retourner les dernières attentions clés/valeurs (non utilisé par tous les modèles). Pertinent uniquement si `config.is_decoder=True` ou si le modèle est un modèle génératif de type décodeur uniquement.

pad_token_id (`int`, *facultatif*, valeur par défaut `0`) : Identifiant du jeton utilisé pour le bourrage dans le vocabulaire.

eos_token_id (`Union[int, list[int]]`, *facultatif*, valeur par défaut `1`) : Identifiant de jeton utilisé pour la fin de flux dans le vocabulaire.

max_2d_position_embeddings (`int`, *facultatif*, valeur par défaut 1024) : Les embeddings de position absolue maximaux pour l'encodage de position relative.

image_size (`Union[int, list[int], tuple[int, int]]`, *facultatif*, valeur par défaut `224`) : La taille (résolution) de chaque image.

patch_size (`Union[int, list[int], tuple[int, int]]`, *facultatif*, valeur par défaut `16`) : La taille (résolution) de chaque patch.

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

is_decoder (`bool`, *facultatif*, valeur par défaut `False`) : Indique si le modèle est utilisé comme décodeur. Si `False`, le modèle est utilisé comme encodeur.

add_cross_attention (`bool`, *facultatif*, par défaut `False`) : Indique si des couches d'attention croisée doivent être ajoutées au modèle.

tie_word_embeddings (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut lier les embeddings de poids selon la correspondance `tied_weights_keys` du modèle.

Il s'agit de la classe de configuration destinée à stocker la configuration d'un UdopModel. Elle est utilisée pour instancier un modèle Udop 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/udop-large](https://huggingface.co/microsoft/udop-large)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/main/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/main/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

## UdopTokenizer[[transformers.UdopTokenizer]]

#### transformers.UdopTokenizer[[transformers.UdopTokenizer]]

```python
transformers.UdopTokenizer(vocab: str | list[tuple[str, float]] | None = None, eos_token = '</s>', sep_token = '</s>', unk_token = '<unk>', pad_token = '<pad>', sep_token_box = [1000, 1000, 1000, 1000], pad_token_box = [0, 0, 0, 0], pad_token_label = -100, only_label_first_subword = True, extra_special_tokens = None, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/tokenization_udop.py#L139)

**Paramètres :**

eos_token (`str`, *facultatif*, par défaut `"</s>"`) : Jeton de fin de séquence. Lors de la construction d'une séquence à l'aide de jetons spéciaux, ce n'est pas le jeton utilisé pour la fin de séquence. Le jeton utilisé est le `sep_token`.

sep_token (`str`, *facultatif*, valeur par défaut `"</s>"`) : le jeton séparateur, utilisé lors de la construction d'une séquence à partir de plusieurs séquences, par exemple deux séquences pour la classification de séquences ou un texte et une question pour le question answering. Il est également utilisé comme dernier jeton d'une séquence construite avec des jetons spéciaux.

unk_token (`str`, *facultatif*, par défaut `"<unk>"`) : Le jeton inconnu. Un jeton qui n'est pas dans le vocabulaire ne peut pas être converti en identifiant et est remplacé par ce jeton.

pad_token (`str`, *facultatif*, par défaut `"<pad>"`) : le jeton utilisé pour le bourrage, par exemple lors du groupement de séquences de longueurs différentes.

sep_token_box (`list[int]`, *facultatif*, par défaut `[1000, 1000, 1000, 1000]`) : La boîte englobante à utiliser pour le jeton spécial [SEP].

pad_token_box (`list[int]`, *facultatif*, par défaut `[0, 0, 0, 0]`) : La boîte englobante à utiliser pour le jeton spécial [PAD].

pad_token_label (`int`, *facultatif*, valeur par défaut : -100) : L'étiquette à utiliser pour les jetons de bourrage. La valeur par défaut est -100, qui correspond à `ignore_index` de CrossEntropyLoss de PyTorch.

only_label_first_subword (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut étiqueter uniquement le premier sous-mot, lorsque des étiquettes de mots sont fournies.

extra_special_tokens (`list[str]`, *facultatif*, par défaut `["<s>NOTUSED", "</s>NOTUSED"]`) : Jetons spéciaux supplémentaires utilisés par le tokeniseur.

Construit un tokeniseur UDOP « rapide » (basé sur la bibliothèque *tokenizers* de HuggingFace). Adapté de [LayoutXLMTokenizer](/docs/transformers/main/fr/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) et [T5Tokenizer](/docs/transformers/main/fr/model_doc/t5#transformers.T5Tokenizer). Basé sur [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models).

Ce tokenizer hérite de [TokenizersBackend](/docs/transformers/main/fr/main_classes/tokenizer#transformers.TokenizersBackend), qui contient la plupart des méthodes principales. Les utilisateurs doivent se reporter à cette classe mère pour plus d’informations sur ces méthodes.

#### build_inputs_with_special_tokens[[transformers.UdopTokenizer.build_inputs_with_special_tokens]]

```python
build_inputs_with_special_tokens(token_ids_0: list[int], token_ids_1: list[int] | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/tokenization_udop.py#L972)

**Paramètres :**

token_ids_0 (`list[int]`) : Liste d'identifiants auxquels les jetons spéciaux seront ajoutés.

token_ids_1 (`list[int]`, *facultatif*) : Deuxième liste d'identifiants facultative pour les paires de séquences.

**Retourne :** `list[int]`

Liste des [identifiants d'entrée](../glossary#input-ids) avec les jetons spéciaux appropriés.

Construire les entrées du modèle à partir d'une séquence ou d'une paire de séquences pour les tâches de classification de séquences en les concaténant et en ajoutant des jetons spéciaux. Une séquence XLM-RoBERTa a le format suivant :

- séquence unique : `<s> X </s>`
- paire de séquences : `<s> A </s></s> B </s>`

#### get_special_tokens_mask[[transformers.UdopTokenizer.get_special_tokens_mask]]

```python
get_special_tokens_mask(token_ids_0: list[int], token_ids_1: list[int] | None = None, already_has_special_tokens: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_base.py#L1346)

**Paramètres :**

token_ids_0 : Liste des identifiants de la séquence (éventuellement déjà formatée).

token_ids_1 : Non utilisé lorsque `already_has_special_tokens=True`. Doit être None dans ce cas.

already_has_special_tokens : Indique si la séquence est déjà formatée avec des jetons spéciaux.

**Retourne :** une liste d'entiers dans l'intervalle [0, 1]

1 pour un jeton spécial, 0 pour un jeton de séquence.

Récupérer les identifiants de séquences à partir d'une liste de jetons à laquelle aucun jeton spécial n'a été ajouté.

Pour les tokenizers rapides, les data collators appellent cette fonction avec `already_has_special_tokens=True` afin de construire un masque sur une séquence déjà formatée. Dans ce cas, nous calculons le masque en vérifiant l’appartenance à `all_special_ids`.

#### create_token_type_ids_from_sequences[[transformers.UdopTokenizer.create_token_type_ids_from_sequences]]

```python
create_token_type_ids_from_sequences(token_ids_0: list[int], token_ids_1: list[int] | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/tokenization_udop.py#L997)

**Paramètres :**

token_ids_0 (`list[int]`) : Liste d'identifiants.

token_ids_1 (`list[int]`, *facultatif*) : Deuxième liste d'identifiants facultative pour les paires de séquences.

**Retourne :** `list[int]`

Liste de zéros.

Crée un masque à partir des deux séquences passées, destiné à une tâche de classification de paires de séquences. XLM-RoBERTa n'utilise pas d'identifiants de type de jeton, une liste de zéros est donc renvoyée.

#### save_vocabulary[[transformers.UdopTokenizer.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/tokenization_udop.py#L1021)

Enregistrez les fichiers de vocabulaire du tokenizer. Pour TokenizersBackend, le fichier tokenizer.json est enregistré par la classe de base. Cette méthode retourne un tuple vide, car nous n'utilisons que tokenizer.json.

## UdopProcessor[[transformers.UdopProcessor]]

#### transformers.UdopProcessor[[transformers.UdopProcessor]]

```python
transformers.UdopProcessor(image_processor, tokenizer)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/processing_udop.py#L50)

**Paramètres :**

image_processor (`LayoutLMv3ImageProcessor`) : le processeur d’images est une entrée obligatoire.

tokenizer (`UdopTokenizer`) : le tokenizer est une entrée obligatoire.

Construit un UdopProcessor qui encapsule un processeur d’images et un tokenizer en un seul processeur.

[UdopProcessor](/docs/transformers/main/fr/model_doc/udop#transformers.UdopProcessor) propose toutes les fonctionnalités de [LayoutLMv3ImageProcessor](/docs/transformers/main/fr/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) et de [UdopTokenizer](/docs/transformers/main/fr/model_doc/udop#transformers.UdopTokenizer). Consultez [~LayoutLMv3ImageProcessor](/docs/transformers/main/fr/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) et [~UdopTokenizer](/docs/transformers/main/fr/model_doc/udop#transformers.UdopTokenizer) pour plus d’informations.

#### __appel__[[transformers.UdopProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text: str | list[str] | list[list[str]] = None, boxes: list[list[int]] | list[list[list[int]]] | None = None, word_labels: list[int] | list[list[int]] | None = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/processing_udop.py#L73)

**Paramètres :**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *facultatif*) : Image à prétraiter. Attend une image unique ou un lot d'images dont les valeurs de pixels sont comprises entre 0 et 255. Si vous transmettez des images dont les valeurs de pixels sont comprises entre 0 et 1, définissez `do_rescale=False`.

text (`Union[str, list[str], list[list[str]]]`, *facultatif*) : La séquence ou le lot de séquences à encoder. Chaque séquence peut être une chaîne de caractères ou une liste de chaînes (chaîne pré-tokenisée). Si vous transmettez une entrée pré-tokenisée, définissez `is_split_into_words=True` pour éviter toute ambiguïté avec les entrées en lot.

boxes (`list[list[int]]`, `list[list[list[int]]]`, *facultatif*) : Boîtes englobantes au niveau des mots, normalisées dans l'intervalle [0, 1000].

word_labels (`list[int]`, `list[list[int]]`, *facultatif*) : Étiquettes entières au niveau des mots pour les tâches de classification de jetons.

return_mm_token_type_ids (`bool`, *kwargs*) : Indique s'il faut retourner les identifiants de type de jeton multimodal indiquant les positions des jetons de substitution multimodaux.

return_text_replacement_offsets (`bool`, *kwargs*) : Indique s'il faut retourner les décalages de caractères pour chaque emplacement multimodal et son remplacement.

return_tensors (`str` ou [TensorType](/docs/transformers/main/fr/internal/file_utils#transformers.TensorType), *facultatif*) : Si défini, renverra des tenseurs d'un framework particulier. Les valeurs acceptables sont :  - `'pt'` : Renvoie des objets `torch.Tensor` de PyTorch. - `'np'` : Renvoie des objets `np.ndarray` de NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/fr/main_classes/processors#transformers.ProcessingKwargs), *facultatif*) : Options de traitement supplémentaires pour chaque modalité (texte, images, vidéos, audio). Les paramètres spécifiques au modèle sont répertoriés ci-dessus ; consultez la classe TypedDict pour la liste complète des arguments pris en charge.

**Retourne :** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- Dictionnaire de listes/tableaux/tenseurs renvoyé par la méthode __call__ (« pixel_values », etc.).
- **tensor_type** (`Union[None, str, TensorType]`, *facultatif*) -- Vous pouvez spécifier un tensor_type ici pour convertir les listes d'entiers en tenseurs PyTorch/Numpy lors de l'initialisation.

## UdopModel[[transformers.UdopModel]]

#### transformers.UdopModel[[transformers.UdopModel]]

```python
transformers.UdopModel(config: UdopConfig)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/modeling_udop.py#L1254)

**Paramètres :**

config ([UdopConfig](/docs/transformers/main/fr/model_doc/udop#transformers.UdopConfig)) : 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/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle Udop brut, qui produit des états cachés bruts sans aucune tête spécifique au sommet.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/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.UdopModel.forward]]

```python
forward(input_ids: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, bbox: dict[str, typing.Any] | None = None, pixel_values: typing.Optional[torch.Tensor] = None, visual_bbox: dict[str, typing.Any] | None = None, decoder_input_ids: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, cache: transformers.cache_utils.Cache | None = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/modeling_udop.py#L1290)

**Paramètres :**

input_ids (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

bbox (`torch.LongTensor` de forme `({0}, 4)`, *facultatif*) : Boîtes englobantes des jetons de chaque séquence d’entrée. Sélectionnées dans l’intervalle `[0, config.max_2d_position_embeddings-1]`. Chaque boîte englobante doit être une version normalisée au format (x0, y0, x1, y1), où (x0, y0) correspond à la position du coin supérieur gauche de la boîte englobante et (x1, y1) représente la position du coin inférieur droit. Notez que `sequence_length = token_sequence_length + patch_sequence_length + 1`, où `1` correspond au jeton [CLS]. Voir `pixel_values` pour `patch_sequence_length`.

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d'entrée. Les valeurs des pixels peuvent être obtenues à l'aide de `image_processor_class`. Voir `image_processor_class.__call__` pour plus de détails (`processor_class` utilise `image_processor_class` pour le traitement des images).

visual_bbox (`torch.LongTensor` de forme `(batch_size, patch_sequence_length, 4)`, *facultatif*) : Boîtes englobantes de chaque patch dans l'image. Si non fournies, les boîtes englobantes sont créées dans le modèle.

decoder_input_ids (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Indices des jetons de la séquence d’entrée du décodeur dans le vocabulaire. Les indices peuvent être obtenus à l’aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Quels sont les identifiants d’entrée du décodeur ?](../glossary#decoder-input-ids) T5 utilise `pad_token_id` comme jeton de départ pour la génération de `decoder_input_ids`. Si `cache` est utilisé, il est facultatif de n’entrer que les derniers `decoder_input_ids` (voir `cache`). Pour en savoir plus sur la préparation de `decoder_input_ids` pour le pré-entraînement, consultez [Entraînement de T5](./t5#training).

decoder_attention_mask (`torch.BoolTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Comportement par défaut : générer un tenseur qui ignore les jetons de remplissage dans `decoder_input_ids`. Un masque causal sera également utilisé par défaut.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

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.

cache (`~cache_utils.Cache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement du `cache` renvoyé par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`. Seule une instance [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, consultez notre [guide du cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `cache` n'est transmis, [DynamicCache](/docs/transformers/main/fr/internal/generation_utils#transformers.DynamicCache) sera initialisé par défaut. Le modèle renverra le même format de cache que celui fourni en entrée. Si des `cache` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux dont les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`.

decoder_inputs_embeds (`torch.Tensor` de forme `(batch_size, target_sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `decoder_input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Si `cache` est utilisé, il est facultatif de n'entrer que les derniers `decoder_inputs_embeds` (voir `cache`). Cela est utile si vous souhaitez un meilleur contrôle sur la conversion des indices `decoder_input_ids` en vecteurs associés que la matrice de recherche d'intégration interne du modèle. Si `decoder_input_ids` et `decoder_inputs_embeds` sont tous deux non définis, `decoder_inputs_embeds` prend la valeur de `inputs_embeds`.

use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états des valeurs de clé de `cache` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `cache`).

**Retourne :** [Seq2SeqModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) ou `tuple(torch.Tensor)`

Un [Seq2SeqModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) 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 (`None`) et les entrées.

La méthode forward de [UdopModel](/docs/transformers/main/fr/model_doc/udop#transformers.UdopModel) 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 `cache` est utilisé, seule la dernière hidden-state des séquences de forme `(batch_size, 1, hidden_size)` est renvoyée.
- **cache** (`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/main/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 `cache`) 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.

Exemple :

```python
>>> from transformers import AutoProcessor, AutoModel
>>> from datasets import load_dataset
>>> import torch

>>> # load model and processor
>>> # in this case, we already have performed OCR ourselves
>>> # so we initialize the processor with `apply_ocr=False`
>>> processor = AutoProcessor.from_pretrained("microsoft/udop-large", apply_ocr=False)
>>> model = AutoModel.from_pretrained("microsoft/udop-large")

>>> # load an example image, along with the words and coordinates
>>> # which were extracted using an OCR engine
>>> dataset = load_dataset("nielsr/funsd-layoutlmv3", split="train")
>>> example = dataset[0]
>>> image = example["image"]
>>> words = example["tokens"]
>>> boxes = example["bboxes"]
>>> inputs = processor(image, words, boxes=boxes, return_tensors="pt")

>>> decoder_input_ids = torch.tensor([[model.config.decoder_start_token_id]])

>>> # forward pass
>>> outputs = model(**inputs, decoder_input_ids=decoder_input_ids)
>>> last_hidden_states = outputs.last_hidden_state
>>> list(last_hidden_states.shape)
[1, 1, 1024]
```

## UdopForConditionalGeneration[[transformers.UdopForConditionalGeneration]]

#### transformers.UdopForConditionalGeneration[[transformers.UdopForConditionalGeneration]]

```python
transformers.UdopForConditionalGeneration(config: UdopConfig)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/modeling_udop.py#L1409)

**Paramètres :**

config ([UdopConfig](/docs/transformers/main/fr/model_doc/udop#transformers.UdopConfig)) : 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/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le Transformer encodeur-décodeur UDOP avec une tête de modélisation de langage au sommet, permettant de générer du texte à partir d’images de documents et d’un prompt facultatif.

Cette classe est basée sur [T5ForConditionalGeneration](/docs/transformers/main/fr/model_doc/t5#transformers.T5ForConditionalGeneration), étendue pour traiter les images et les données de mise en page (2D).

Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/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.UdopForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, bbox: dict[str, typing.Any] | None = None, pixel_values: typing.Optional[torch.Tensor] = None, visual_bbox: dict[str, typing.Any] | None = None, decoder_input_ids: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, cache: transformers.cache_utils.Cache | None = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, labels: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/modeling_udop.py#L1451)

**Paramètres :**

input_ids (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

bbox (`torch.LongTensor` de forme `({0}, 4)`, *facultatif*) : Boîtes englobantes des jetons de chaque séquence d’entrée. Sélectionnées dans l’intervalle `[0, config.max_2d_position_embeddings-1]`. Chaque boîte englobante doit être une version normalisée au format (x0, y0, x1, y1), où (x0, y0) correspond à la position du coin supérieur gauche de la boîte englobante et (x1, y1) représente la position du coin inférieur droit. Notez que `sequence_length = token_sequence_length + patch_sequence_length + 1`, où `1` correspond au jeton [CLS]. Voir `pixel_values` pour `patch_sequence_length`.

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d'entrée. Les valeurs des pixels peuvent être obtenues à l'aide de `image_processor_class`. Voir `image_processor_class.__call__` pour plus de détails (`processor_class` utilise `image_processor_class` pour le traitement des images).

visual_bbox (`torch.LongTensor` de forme `(batch_size, patch_sequence_length, 4)`, *facultatif*) : Boîtes englobantes de chaque patch dans l'image. Si non fournies, les boîtes englobantes sont créées dans le modèle.

decoder_input_ids (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Indices des jetons de la séquence d’entrée du décodeur dans le vocabulaire. Les indices peuvent être obtenus à l’aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Quels sont les identifiants d’entrée du décodeur ?](../glossary#decoder-input-ids) T5 utilise `pad_token_id` comme jeton de départ pour la génération de `decoder_input_ids`. Si `cache` est utilisé, il est facultatif de n’entrer que les derniers `decoder_input_ids` (voir `cache`). Pour en savoir plus sur la préparation de `decoder_input_ids` pour le pré-entraînement, consultez [Entraînement de T5](./t5#training).

decoder_attention_mask (`torch.BoolTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Comportement par défaut : générer un tenseur qui ignore les jetons de remplissage dans `decoder_input_ids`. Un masque causal sera également utilisé par défaut.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

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.

cache (`~cache_utils.Cache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement du `cache` renvoyé par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`. Seule une instance [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, consultez notre [guide du cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `cache` n'est transmis, [DynamicCache](/docs/transformers/main/fr/internal/generation_utils#transformers.DynamicCache) sera initialisé par défaut. Le modèle renverra le même format de cache que celui fourni en entrée. Si des `cache` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux dont les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`.

decoder_inputs_embeds (`torch.Tensor` de forme `(batch_size, target_sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `decoder_input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Si `cache` est utilisé, il est facultatif de n'entrer que les derniers `decoder_inputs_embeds` (voir `cache`). Cela est utile si vous souhaitez un meilleur contrôle sur la conversion des indices `decoder_input_ids` en vecteurs associés que la matrice de recherche d'intégration interne du modèle. Si `decoder_input_ids` et `decoder_inputs_embeds` sont tous deux non définis, `decoder_inputs_embeds` prend la valeur de `inputs_embeds`.

use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états des valeurs de clé de `cache` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `cache`).

labels (`torch.LongTensor` de forme `(batch_size,)`, *facultatif*) : Étiquettes pour le calcul de la perte de modélisation du langage. Les indices doivent être dans `[-100, 0, ..., config.vocab_size - 1]`. Toutes les étiquettes définies sur `-100` sont ignorées (masquées) ; la perte n'est calculée que pour les étiquettes comprises dans `[0, ..., config.vocab_size]`.

**Retourne :** [Seq2SeqLMOutput](/docs/transformers/main/fr/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) ou `tuple(torch.Tensor)`

Un [Seq2SeqLMOutput](/docs/transformers/main/fr/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 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 (`None`) et les entrées.

La méthode forward de [UdopForConditionalGeneration](/docs/transformers/main/fr/model_doc/udop#transformers.UdopForConditionalGeneration) 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 de modélisation du langage.
- **logits** (`torch.Tensor` de forme `(batch_size, sequence_length, config.vocab_size)`) -- Scores de prédiction de la tête de modélisation du langage (scores pour chaque jeton du vocabulaire avant SoftMax).
- **cache** (`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/main/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 `cache`) 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 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 transformers import AutoProcessor, UdopForConditionalGeneration
>>> from datasets import load_dataset

>>> # load model and processor
>>> # in this case, we already have performed OCR ourselves
>>> # so we initialize the processor with `apply_ocr=False`
>>> processor = AutoProcessor.from_pretrained("microsoft/udop-large", apply_ocr=False)
>>> model = UdopForConditionalGeneration.from_pretrained("microsoft/udop-large")

>>> # load an example image, along with the words and coordinates
>>> # which were extracted using an OCR engine
>>> dataset = load_dataset("nielsr/funsd-layoutlmv3", split="train")
>>> example = dataset[0]
>>> image = example["image"]
>>> words = example["tokens"]
>>> boxes = example["bboxes"]

>>> # one can use the various task prefixes (prompts) used during pre-training
>>> # e.g. the task prefix for DocVQA is "Question answering. "
>>> question = "Question answering. What is the date on the form?"
>>> encoding = processor(image, question, text_pair=words, boxes=boxes, return_tensors="pt")

>>> # autoregressive generation
>>> predicted_ids = model.generate(**encoding)
>>> print(processor.batch_decode(predicted_ids, skip_special_tokens=True)[0])
9/30/92
```

## UdopEncoderModel[[transformers.UdopEncoderModel]]

#### transformers.UdopEncoderModel[[transformers.UdopEncoderModel]]

```python
transformers.UdopEncoderModel(config: UdopConfig)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/modeling_udop.py#L1584)

**Paramètres :**

config ([UdopConfig](/docs/transformers/main/fr/model_doc/udop#transformers.UdopConfig)) : 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/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle Udop brut, qui produit des états cachés bruts sans aucune tête spécifique au sommet.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/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.UdopEncoderModel.forward]]

```python
forward(input_ids: typing.Optional[torch.Tensor] = None, bbox: dict[str, typing.Any] | None = None, attention_mask: typing.Optional[torch.Tensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, visual_bbox: dict[str, typing.Any] | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/udop/modeling_udop.py#L1615)

**Paramètres :**

input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`) : Indices des jetons de la séquence d'entrée dans le vocabulaire. T5 est un modèle avec des embeddings de position relative, vous pouvez donc rembourrer les entrées à la fois à droite et à gauche. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. Pour en savoir plus sur la préparation de `input_ids` pour le pré-entraînement, reportez-vous à [T5 Training](./t5#training).

bbox (`torch.LongTensor` de forme `({0}, 4)`, *facultatif*) : Boîtes englobantes des jetons de chaque séquence d’entrée. Sélectionnées dans l’intervalle `[0, config.max_2d_position_embeddings-1]`. Chaque boîte englobante doit être une version normalisée au format (x0, y0, x1, y1), où (x0, y0) correspond à la position du coin supérieur gauche de la boîte englobante et (x1, y1) représente la position du coin inférieur droit. Notez que `sequence_length = token_sequence_length + patch_sequence_length + 1`, où `1` correspond au jeton [CLS]. Voir `pixel_values` pour `patch_sequence_length`.

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d'entrée. Les valeurs de pixels peuvent être obtenues à l'aide de [LayoutLMv3ImageProcessor](/docs/transformers/main/fr/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor). Voir [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/main/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails ([UdopProcessor](/docs/transformers/main/fr/model_doc/udop#transformers.UdopProcessor) utilise [LayoutLMv3ImageProcessor](/docs/transformers/main/fr/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) pour le traitement des images).

visual_bbox (`torch.LongTensor` de forme `(batch_size, patch_sequence_length, 4)`, *facultatif*) : Boîtes englobantes de chaque patch dans l'image. Si non fournies, les boîtes englobantes sont créées dans le modèle.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

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

Un `BaseModelOutputWithAttentionMask` 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 ([UdopConfig](/docs/transformers/main/fr/model_doc/udop#transformers.UdopConfig)) et les entrées.

La méthode forward de [UdopEncoderModel](/docs/transformers/main/fr/model_doc/udop#transformers.UdopEncoderModel) 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 modèle. Si `cache` est utilisé, seul l'état caché final des séquences, de forme `(batch_size, 1, hidden_size)`, est renvoyé.
- **attention_mask** (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) -- Masque d'attention utilisé dans le passage avant du modèle pour éviter d'effectuer l'attention sur les indices des jetons de bourrage. Valeurs du masque sélectionnées dans `[0, 1]` :
  - 1 pour les jetons qui ne sont **pas masqués**,
  - 0 pour les jetons **masqués**.
- **cache** (`Cache`, *facultatif*, renvoyé lorsque `use_cache=True` est passé ou lorsque `config.use_cache=True`) -- Il s'agit d'une instance de [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache). 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, le cas échéant, si `config.is_encoder_decoder=True`, dans les blocs d'attention croisée) qui peuvent être utilisés (voir l'entrée `cache`) pour accélérer le décodage séquentiel.
- **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 modèle à la sortie de chaque couche, ainsi que les sorties d’embedding initiales facultatives.
- **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 des attentions 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` et `config.add_cross_attention=True` sont passés, 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.

Exemple :

```python
>>> from transformers import AutoProcessor, UdopEncoderModel
>>> from huggingface_hub import hf_hub_download
>>> from datasets import load_dataset

>>> # load model and processor
>>> # in this case, we already have performed OCR ourselves
>>> # so we initialize the processor with `apply_ocr=False`
>>> processor = AutoProcessor.from_pretrained("microsoft/udop-large", apply_ocr=False)
>>> model = UdopEncoderModel.from_pretrained("microsoft/udop-large")

>>> # load an example image, along with the words and coordinates
>>> # which were extracted using an OCR engine
>>> dataset = load_dataset("nielsr/funsd-layoutlmv3", split="train")
>>> example = dataset[0]
>>> image = example["image"]
>>> words = example["tokens"]
>>> boxes = example["bboxes"]
>>> encoding = processor(image, words, boxes=boxes, return_tensors="pt")

>>> outputs = model(**encoding)
>>> last_hidden_states = outputs.last_hidden_state
```

