# Table Transformer

## Обзор

Модель Table Transformer была предложена в статье [PubTables-1M: Towards comprehensive table extraction from unstructured documents](https://huggingface.co/papers/2110.00061) Брэндоном Смоком, Рохитом Песалой и Робин Абрахам. Авторы представляют новый датасет PubTables-1M для оценки прогресса в извлечении таблиц из неструктурированных документов, а также в распознавании структуры таблиц и функциональном анализе. Авторы обучают две модели [DETR](detr): одну для обнаружения таблиц и другую для распознавания их структуры, получившие название Table Transformers.

Аннотация из статьи следующая:

*Недавно были достигнуты значительные успехи в применении машинного обучения к задаче вывода и извлечения структуры таблиц из неструктурированных документов. Однако одной из главных проблем по-прежнему остаётся создание наборов данных с полным и однозначным эталонным значением (ground truth) в больших масштабах. Для решения этой задачи мы разработали новый, более комплексный набор данных для извлечения таблиц, названный PubTables-1M. PubTables-1M содержит почти один миллион таблиц из научных статей, поддерживает несколько входных модальностей и включает подробную информацию о заголовках и расположении элементов структуры таблиц, что делает его полезным для широкого спектра подходов к моделированию. Кроме того, он решает значительный источник несоответствий в эталонных данных, наблюдавшийся в предыдущих наборах данных и называемый переизбыточным сегментированием (oversegmentation), с помощью новой процедуры канонизации. Мы показываем, что эти улучшения приводят к значительному повышению качества обучения и более надёжной оценке производительности моделей при тестировании для задачи распознавания структуры таблиц. Более того, мы демонстрируем, что модели обнаружения объектов на основе трансформеров, обученные на PubTables-1M, дают отличные результаты для всех трёх задач — обнаружения, распознавания структуры и функционального анализа — без необходимости какой-либо специальной настройки под эти задачи.*

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

 Уточнение обнаружения таблиц и распознавания структуры таблиц. Источник — оригинальная статья.

Авторы выпустили 2 модели: одна для [обнаружения таблиц](https://huggingface.co/microsoft/table-transformer-detection) в документах, другая — для [распознавания структуры таблиц](https://huggingface.co/microsoft/table-transformer-structure-recognition) (задача распознавания отдельных строк, столбцов и т. д. в таблице).

Эта модель была предоставлена пользователем [nielsr](https://huggingface.co/nielsr). Исходный код можно найти [здесь](https://github.com/microsoft/table-transformer).

> [!TIP]
> Установите `use_kernels=True` в [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained), чтобы заменить поддерживаемые слои на оптимизированные ядра из Hub. Подробнее см. в разделе [Загрузка ядер](../kernel_doc/loading_kernels).

## Ресурсы

- Демо-ноутбук для Table Transformer можно найти [здесь](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/Table%20Transformer).
- Оказалось, что паддинг изображений имеет большое значение для детекции. Интересный тред на GitHub с ответами авторов можно найти [здесь](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)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/configuration_table_transformer.py#L25)

**Параметры:**

is_encoder_decoder (`bool`, *необязательный*, по умолчанию `True`) : Используется ли модель в качестве энкодера/декодера.

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Конфигурация базовой модели.

num_channels (`int`, *необязательный*, по умолчанию `3`) : Количество входных каналов.

num_queries (`int`, *optional*, по умолчанию 100) : Количество запросов объектов, то есть слотов для обнаружения. Это максимальное число объектов, которые [TableTransformerModel](/docs/transformers/v5.23.0/ru/model_doc/table-transformer#transformers.TableTransformerModel) может обнаружить на одном изображении. Для COCO мы рекомендуем 100 запросов.

encoder_layers (`int`, *необязательный*, по умолчанию `6`) : Количество скрытых слоев в кодере Transformer. Если не задано, будет использовано то же значение, что и у `num_layers`.

encoder_ffn_dim (`int`, *optional*, по умолчанию `2048`) : Размерность «промежуточного» (часто называемого feed-forward) слоя в энкодере.

encoder_attention_heads (`int`, *необязательный*, по умолчанию `8`) : Количество головок внимания для каждого слоя внимания в кодере Transformer.

decoder_layers (`int`, *необязательный*, по умолчанию `6`) : Количество скрытых слоев в декодере Transformer. Если не задано, будет использовано то же значение, что и у `num_layers`.

decoder_ffn_dim (`int`, *необязательный*, по умолчанию `2048`) : Размерность «промежуточного» (часто называемого feed-forward) слоя в декодере.

decoder_attention_heads (`int`, *необязательный*, по умолчанию `8`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

encoder_layerdrop (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Вероятность LayerDrop для энкодера. Подробнее см. в [статье о LayerDrop](see https://huggingface.co/papers/1909.11556).

decoder_layerdrop (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Вероятность LayerDrop для декодера. Подробнее см. в [статье о LayerDrop](see https://huggingface.co/papers/1909.11556).

activation_function (`str`, *необязательный*, по умолчанию `relu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

d_model (`int`, *необязательный*, по умолчанию `256`) : Размер слоев кодировщика и пулера.

dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Доля для всех слоёв dropout.

attention_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент dropout для вероятностей внимания.

activation_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент dropout для активаций внутри полносвязного слоя.

init_std (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

init_xavier_std (`float`, *необязательный*, по умолчанию `1.0`) : Коэффициент масштабирования, используемый для инициализации кросс-внимания по методу Ксавье.

auxiliary_loss (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли вспомогательные потери декодирования (потери на каждом слое декодера).

position_embedding_type (`str`, *необязательный*, по умолчанию `"sine"`) : Тип позиционных эмбеддингов, применяемых поверх признаков изображения. Одно из значений `"sine"` или `"learned"`.

dilation (`bool`, *необязательный*, по умолчанию `False`) : Заменять ли stride на dilation в последнем свёрточном блоке (DC5). Поддерживается только при `use_timm_backbone` = `True`.

class_cost (`int`, *optional*, по умолчанию `1`) : Относительный вес ошибки классификации в стоимости венгерского сопоставления.

bbox_cost (`int`, *optional*, по умолчанию `5`) : Относительный вес ошибки L1 для ограничивающих прямоугольников в стоимости венгерского сопоставления.

giou_cost (`int`, *optional*, по умолчанию `2`) : Относительный вес обобщённой функции потерь IoU в стоимости венгерского сопоставления.

mask_loss_coefficient (`int`, *optional*, по умолчанию `1`) : Относительный вес фокальной функции потерь в функции потерь паноптической сегментации.

dice_loss_coefficient (`int`, *optional*, по умолчанию `1`) : Относительный вес функции потерь dice в функции потерь паноптической сегментации.

bbox_loss_coefficient (`int`, *optional*, по умолчанию `5`) : Относительный вес потери L1 для ограничивающих прямоугольников в потере паноптической сегментации.

giou_loss_coefficient (`int`, *optional*, по умолчанию `2`) : Относительный вес обобщённой функции потерь IoU в функции потерь паноптической сегментации.

eos_coefficient (`float`, *необязательный*, по умолчанию `0.1`) : Относительный вес класса «нет объекта» в функции потерь обнаружения объектов.

Это класс конфигурации для хранения настроек модели Table Transformer. Он используется для создания модели Table Transformer в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [microsoft/table-transformer-detection](https://huggingface.co/microsoft/table-transformer-detection)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

Примеры:

```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)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/modeling_table_transformer.py#L967)

**Параметры:**

config ([TableTransformerConfig](/docs/transformers/v5.23.0/ru/model_doc/table-transformer#transformers.TableTransformerConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Table Transformer в базовом виде (состоящая из backbone и encoder-decoder Transformer), выводящая «сырые» hidden-states без какого-либо специализированного head сверху.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### 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)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/modeling_table_transformer.py#L996)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [DetrImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/detr#transformers.DetrImageProcessor). Подробности см. в [DetrImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [DetrImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/detr#transformers.DetrImageProcessor) для обработки изображений).

pixel_mask (`torch.Tensor` формы `(batch_size, height, width)`, *необязательный*) : Маска для исключения пикселей отступов из внимания. Значения маски выбираются из `[0, 1]`:  - 1 для реальных пикселей (т. е. **не замаскированных**), - 0 для пикселей отступов (т. е. **замаскированных**).  [Что такое маски внимания?](../glossary#attention-mask)

decoder_attention_mask (`torch.Tensor` формы `(batch_size, num_queries)`, *необязательный*) : По умолчанию не используется. Может применяться для маскирования запросов объектов.

encoder_outputs (`torch.Tensor`, *необязательный*) : Кортеж, состоящий из (`last_hidden_state`, *необязательный*: `hidden_states`, *необязательный*: `attentions`) `last_hidden_state` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) представляет собой последовательность скрытых состояний на выходе последнего слоя кодировщика. Используется в кросс-внимании декодера.

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи сглаженной карты признаков (выход backbone + проекционного слоя), можно напрямую передать сглаженное представление изображения.

decoder_inputs_embeds (`torch.Tensor` формы `(batch_size, num_queries, hidden_size)`, *необязательно*) : По желанию, вместо инициализации запросов тензором нулей, можно передать встроенное представление напрямую.

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

return_dict (`bool`, *необязательный*) : Нужно ли возвращать [ModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

**Возвращает:** `TableTransformerModelOutput` или `tuple(torch.Tensor)`

`TableTransformerModelOutput` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([TableTransformerConfig](/docs/transformers/v5.23.0/ru/model_doc/table-transformer#transformers.TableTransformerConfig)) и входных данных.

Метод forward модели [TableTransformerModel](/docs/transformers/v5.23.0/ru/model_doc/table-transformer#transformers.TableTransformerModel) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя декодера модели.

  Если используется `past_key_values`, выводится только последнее скрытое состояние последовательностей формы `(batch_size, 1, hidden_size)`.
- **past_key_values** (`EncoderDecoderCache`, *необязательный*, возвращается при передаче `use_cache=True` или при `config.use_cache=True`) -- это экземпляр [EncoderDecoderCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.EncoderDecoderCache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера на выходе каждого слоя, а также необязательные выходные значения начального эмбеддинга.
- **decoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **cross_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) — Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кросс-внимания декодера, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах кросс-внимания.
- **encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя энкодера модели.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния энкодера на выходе каждого слоя, а также необязательные выходные значения начального эмбеддинга.
- **encoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **intermediate_hidden_states** (`torch.Tensor` формы `(config.decoder_layers, batch_size, sequence_length, hidden_size)`, *необязательный*, возвращается при `config.auxiliary_loss=True`) -- Промежуточные активации декодера, то есть выход каждого слоя декодера, прошедший через layernorm.

Примеры:

```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)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/modeling_table_transformer.py#L1136)

**Параметры:**

config ([TableTransformerConfig](/docs/transformers/v5.23.0/ru/model_doc/table-transformer#transformers.TableTransformerConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Table Transformer (состоящая из базовой сети и трансформера с архитектурой «кодекдер») с головными модулями для обнаружения объектов, предназначенная для таких задач, как обнаружение объектов в COCO.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### 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)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/table_transformer/modeling_table_transformer.py#L1155)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [DetrImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/detr#transformers.DetrImageProcessor). Подробности см. в [DetrImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [DetrImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/detr#transformers.DetrImageProcessor) для обработки изображений).

pixel_mask (`torch.Tensor` формы `(batch_size, height, width)`, *необязательный*) : Маска для исключения пикселей отступов из внимания. Значения маски выбираются из `[0, 1]`:  - 1 для реальных пикселей (т. е. **не замаскированных**), - 0 для пикселей отступов (т. е. **замаскированных**).  [Что такое маски внимания?](../glossary#attention-mask)

decoder_attention_mask (`torch.Tensor` формы `(batch_size, num_queries)`, *необязательный*) : По умолчанию не используется. Может применяться для маскирования запросов объектов.

encoder_outputs (`torch.Tensor`, *необязательный*) : Кортеж, состоящий из (`last_hidden_state`, *необязательный*: `hidden_states`, *необязательный*: `attentions`) `last_hidden_state` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) представляет собой последовательность скрытых состояний на выходе последнего слоя кодировщика. Используется в кросс-внимании декодера.

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи сглаженной карты признаков (выход backbone + проекционного слоя), можно напрямую передать сглаженное представление изображения.

decoder_inputs_embeds (`torch.Tensor` формы `(batch_size, num_queries, hidden_size)`, *необязательно*) : По желанию, вместо инициализации запросов тензором нулей, можно передать встроенное представление напрямую.

labels (`list[Dict]` длины `(batch_size,)`, *необязательный*) : Метки для вычисления функции потерь бипартитного сопоставления. Список словарей, каждый из которых содержит как минимум следующие два ключа: 'class_labels' и 'boxes' (соответственно, метки классов и ограничивающие рамки изображения в батче). Сами метки классов должны представлять собой `torch.LongTensor` длины `(number of bounding boxes in the image,)`, а рамки — `torch.Tensor` формы `(number of bounding boxes in the image, 4)`.

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

return_dict (`bool`, *необязательный*) : Нужно ли возвращать [ModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

**Возвращает:** `TableTransformerObjectDetectionOutput` или `tuple(torch.Tensor)`

Объект `TableTransformerObjectDetectionOutput` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([TableTransformerConfig](/docs/transformers/v5.23.0/ru/model_doc/table-transformer#transformers.TableTransformerConfig)) и входных данных.

Метод forward класса [TableTransformerForObjectDetection](/docs/transformers/v5.23.0/ru/model_doc/table-transformer#transformers.TableTransformerForObjectDetection) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если предоставлены `labels`)) -- Суммарная потеря, представляющая собой линейную комбинацию отрицательного логарифма правдоподобия (кросс-энтропии) для предсказания класса и потери для ограничивающих прямоугольников. Последняя определяется как линейная комбинация L1-потери и обобщенной масштабно-инвариантной потери IoU.
- **loss_dict** (`Dict`, *необязательный*) -- Словарь, содержащий отдельные значения потерь. Полезно для ведения журнала.
- **logits** (`torch.Tensor` формы `(batch_size, num_queries, num_classes + 1)`) -- Логиты классификации (включая no-object) для всех запросов.
- **pred_boxes** (`torch.Tensor` формы `(batch_size, num_queries, 4)`) -- Нормализованные координаты границ для всех запросов, представленные в виде (center_x, center_y, width, height). Эти значения нормализованы в диапазоне [0, 1] относительно размера каждого отдельного изображения в батче (игнорируя возможное выравнивание). Для получения ненормализованных границ используйте `~TableTransformerImageProcessor.post_process_object_detection`.
- **auxiliary_outputs** (`list[Dict]`, *необязательный*) -- Необязательный параметр, возвращается только при активации вспомогательных потерь (т. е. когда `config.auxiliary_loss` установлен в `True`) и при наличии меток. Это список словарей, содержащих два указанных выше ключа (`logits` и `pred_boxes`) для каждого слоя декодера.
- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя декодера модели.
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера на выходе каждого слоя, а также выходные значения начального слоя встраивания.
- **decoder_attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **cross_attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кросс-внимания декодера, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах кросс-внимания.
- **encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя энкодера модели.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния кодировщика на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
- **encoder_attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) — Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Примеры:

```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]
```

