# UDOP

## 개요

UDOP 모델은 Zineng Tang, Ziyi Yang, Guoxin Wang, Yuwei Fang, Yang Liu, Chenguang Zhu, Michael Zeng, Cha Zhang, Mohit Bansal이 발표한 [Unifying Vision, Text, and Layout for Universal Document Processing](https://huggingface.co/papers/2212.02623)에서 제안되었습니다. UDOP는 문서 이미지 분류, 문서 파싱, 문서 시각 질의응답과 같은 문서 AI 작업을 위해 [T5](t5) 기반의 인코더-디코더 Transformer 아키텍처를 채택합니다.

해당 논문의 초록은 다음과 같습니다:

Universal Document Processing(UDOP)을 제안합니다. UDOP는 문서 이해 및 생성을 포함한 다양한 작업 형식과 함께 텍스트, 이미지, 레이아웃 모달리티를 통합하는 기반 Document AI 모델입니다. UDOP는 텍스트 콘텐츠와 문서 이미지 간의 공간적 상관관계를 활용하여 이미지, 텍스트, 레이아웃 모달리티를 하나의 균일한 표현으로 모델링합니다. 새로운 Vision-Text-Layout Transformer를 통해 UDOP는 사전 학습과 다중 도메인 하위 작업을 프롬프트 기반 시퀀스 생성 방식으로 통합합니다. UDOP는 혁신적인 자기 지도 학습 목표를 사용하여 대규모 무라벨 문서 코퍼스와 다양한 라벨링 데이터로 사전 학습됩니다. 또한 UDOP는 마스킹 이미지 재구성을 통해 텍스트와 레이아웃 모달리티로부터 문서 이미지를 생성하는 것을 학습합니다. 저자의 지식 범위 내에서, 이는 Document AI 분야에서 하나의 모델이 고품질 신경 문서 편집과 콘텐츠 커스터마이징을 동시에 달성한 최초의 사례입니다. 본 방법은 금융 보고서, 학술 논문, 웹사이트와 같은 다양한 데이터 도메인에서 문서 이해 및 QA를 포함한 9가지 Document AI 작업에서 최첨단 성능을 달성했습니다. UDOP는 Document Understanding Benchmark(DUE) 리더보드에서 1위를 기록합니다.*

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

 UDOP 아키텍처. 원 논문에서 가져왔습니다.

## 사용 팁

- *input_ids* 외에도 [UdopForConditionalGeneration](/docs/transformers/main/ko/model_doc/udop#transformers.UdopForConditionalGeneration)은 입력 토큰의 바운딩 박스(즉, 2D 좌표)인 `bbox` 입력을 기대합니다. 이는 Google의 [Tesseract](https://github.com/tesseract-ocr/tesseract)와 같은 외부 OCR 엔진을 사용하여 얻을 수 있습니다([Python wrapper](https://pypi.org/project/pytesseract/)가 사용 가능합니다). 각 바운딩 박스는 (x0, y0, x1, y1) 형식이어야 하며, 여기서 (x0, y0)는 바운딩 박스의 왼쪽 위 모서리 위치를, (x1, y1)은 오른쪽 아래 모서리 위치를 나타냅니다. 바운딩 박스를 0-1000 스케일로 정규화해야 한다는 점에 유의하세요. 정규화를 위해 다음 함수를 사용할 수 있습니다:

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

여기서 `width`와 `height`는 해당 토큰이 포함된 원본 문서의 너비와 높이에 해당합니다. 예를 들어 Python Image Library(PIL) 라이브러리를 사용하여 다음과 같이 얻을 수 있습니다:

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

[UdopProcessor](/docs/transformers/main/ko/model_doc/udop#transformers.UdopProcessor)를 사용하면 이미지와 텍스트를 모델에 맞게 준비할 수 있으며, 이 클래스가 이러한 모든 작업을 처리합니다. 기본적으로 이 클래스는 Tesseract 엔진을 사용하여 주어진 문서에서 단어 목록과 박스(좌표)를 추출합니다. 그 기능은 [LayoutLMv3Processor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3Processor)와 동일하므로, 자체 OCR 엔진을 사용하려면 `apply_ocr=False`를, 기본 OCR 엔진을 사용하려면 `apply_ocr=True`를 전달할 수 있습니다. 가능한 모든 사용 사례에 대해서는 [LayoutLMv2 사용 가이드](layoutlmv2#usage-layoutlmv2processor)를 참조하세요(`UdopProcessor`의 기능은 동일합니다).

- 원하는 OCR 엔진을 직접 사용하는 경우, 라인 세그먼트를 지원하는 Azure의 [Read API](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/how-to/call-read-api) 사용을 권장합니다. 세그먼트 위치 임베딩을 사용하면 일반적으로 더 나은 성능을 얻을 수 있습니다.
- 추론 시에는 문서 이미지를 입력하여 텍스트를 자기회귀적으로 생성하기 위해 `generate` 메서드를 사용하는 것이 권장됩니다.
- The model has been pre-trained on both self-supervised and supervised objectives. One can use the various task prefixes (prompts) used during pre-training to test out the out-of-the-box capabilities. For instance, the model can be prompted with "Question answering. What is the date?", as "Question answering." is the task prefix used during pre-training for DocVQA. Refer to the [paper](https://huggingface.co/papers/2212.02623) (table 1) for all task prefixes.
- [UdopEncoderModel](/docs/transformers/main/ko/model_doc/udop#transformers.UdopEncoderModel)도 fine-tune할 수 있습니다. 이는 UDOP의 encoder-only 부분으로, LayoutLMv3과 유사한 Transformer encoder로 볼 수 있습니다. 판별형(discriminative) 작업의 경우, 이 위에 linear classifier를 추가하고 라벨이 붙은 데이터셋으로 fine-tune하면 됩니다.

이 모델은 [nielsr](https://huggingface.co/nielsr)에 의해 기여되었습니다. 원본 코드는 [여기](https://github.com/microsoft/UDOP)에서 찾을 수 있습니다.

## 리소스

UDOP을 시작하는 데 도움이 되는 공식 Hugging Face 및 커뮤니티(🌎로 표시) 리소스 목록입니다. 여기에 포함할 리소스를 제출하고 싶으시면 Pull Request를 열어 주시면 검토하겠습니다! 기존 리소스와 중복되는 것보다는 새로운 것을 보여주는 것이 이상적입니다.

- UDOP에 대한 데모 노트북은 [여기](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UDOP)에서 찾을 수 있으며,
커스텀 데이터셋으로 UDOP을 파인튜닝하는 방법과 추론을 수행하는 방법을 배웁니다. 🌎
- [문서 질의응답 작업 가이드](../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)
```

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

**매개변수:**

is_encoder_decoder (`bool`, *선택 사항*, 기본값 `True`) : 모델이 인코더/디코더로 사용되는지 여부.

vocab_size (`int`, *선택 사항*, 기본값 `33201`) : 모델의 어휘 크기입니다. `input_ids`로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다.

d_model (`int`, *선택 사항*, 기본값 `1024`) : 인코더 레이어와 풀러 레이어의 크기.

d_kv (`int`, *선택 사항*, 기본값 `64`) : 각 어텐션 헤드당 키, 쿼리, 값 투영의 크기. 투영 레이어의 `inner_dim`은 `num_heads * d_kv`로 정의됩니다.

d_ff (`int`, *선택 사항*, 기본값 `4096`) : MLP 표현의 차원.

num_layers (`int`, *선택 사항*, 기본값 `24`) : Transformer decoder의 숨겨진 레이어 수.

num_decoder_layers (`int`, *선택 사항*) : Transformer 디코더의 숨겨진 레이어 수. 설정되지 않으면 `num_layers`와 동일한 값을 사용합니다.

num_heads (`int`, *선택 사항*, 기본값 `16`) : Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다.

relative_attention_num_buckets (`int`, *선택 사항*, 기본값 32) : 각 attention layer에 사용할 버킷의 수입니다.

relative_attention_max_distance (`int`, *선택 사항*, 기본값 128) : 버킷 분리를 위한 더 긴 시퀀스의 최대 거리입니다.

relative_bias_args (`list[dict]`, *선택 사항*, 기본값은 `[{'type' : '1d'}, {'type': 'horizontal'}, {'type': 'vertical'}]`): 상대 편향 레이어의 인수를 포함하는 사전 목록입니다.

dropout_rate (`Union[float, int]`, *선택 사항*, 기본값 `0.1`) : 모든 dropout 레이어의 비율입니다.

layer_norm_epsilon (`float`, *선택 사항*, 기본값 `1e-06`) : 레이어 정규화 레이어에서 사용되는 epsilon 값입니다.

initializer_factor (`float`, *선택 사항*, 기본값 `1.0`) : 모든 가중치 행렬을 초기화하는 계수입니다(1로 유지해야 하며, 초기화 테스트를 위해 내부적으로 사용됨).

feed_forward_proj (`string`, *선택 사항*, 기본값 `"relu"`) : 사용할 feed forward layer의 유형입니다. `"relu"` 또는 `"gated-gelu"` 중 하나여야 합니다. Udopv1.1은 `"gated-gelu"` feed forward projection을 사용합니다. 원래 Udop은 `"relu"`를 사용합니다.

use_cache (`bool`, *선택 사항*, 기본값 `True`) : 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음). `config.is_decoder=True`인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다.

pad_token_id (`int`, *선택 사항*, 기본값 `0`) : 어휘에서 패딩에 사용되는 토큰 ID입니다.

eos_token_id (`Union[int, list[int]]`, *선택 사항*, 기본값 `1`) : 어휘에서 스트림 종료에 사용되는 토큰 ID입니다.

max_2d_position_embeddings (`int`, *선택 사항*, 기본값 1024) : 상대 위치 인코딩을 위한 최대 절대 위치 임베딩입니다.

image_size (`Union[int, list[int], tuple[int, int]]`, *선택*, 기본값 `224`) : 각 이미지의 크기(해상도).

patch_size (`Union[int, list[int], tuple[int, int]]`, *선택*, 기본값 `16`) : 각 패치의 크기(해상도).

num_channels (`int`, *선택 사항*, 기본값 `3`) : 입력 채널의 수입니다.

is_decoder (`bool`, *선택 사항*, 기본값 `False`) : 모델이 디코더로 사용되는지 여부를 나타냅니다. `False`인 경우 모델은 인코더로 사용됩니다.

add_cross_attention (`bool`, *선택 사항*, 기본값 `False`) : 모델에 cross-attention 레이어를 추가할지 여부.

tie_word_embeddings (`bool`, *선택 사항*, 기본값 `True`) : 모델의 `tied_weights_keys` 매핑에 따라 가중치 임베딩을 묶을지 여부.

이것은 UdopModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Udop 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [microsoft/udop-large](https://huggingface.co/microsoft/udop-large)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

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

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

**매개변수:**

eos_token (`str`, *선택 사항*, 기본값 `"</s>"`) : 시퀀스 종료 토큰. 특수 토큰을 사용하여 시퀀스를 구성할 때, 시퀀스 종료에 사용되는 토큰은 이 토큰이 아닙니다. 사용되는 토큰은 `sep_token`입니다.

sep_token (`str`, *선택 사항*, 기본값 `"</s>"`) : 여러 시퀀스로 시퀀스를 구성할 때 사용되는 구분자 토큰입니다. 예를 들어 시퀀스 분류를 위한 두 시퀀스나 질의응답을 위한 텍스트와 질문 등에 사용됩니다. 특수 토큰으로 구성된 시퀀스의 마지막 토큰으로도 사용됩니다.

unk_token (`str`, *선택*, 기본값 `"<unk>"`) : 알 수 없는 토큰. 어휘에 없는 토큰은 ID로 변환할 수 없으므로 이 토큰으로 설정됩니다.

pad_token (`str`, *선택 사항*, 기본값 `"<pad>"`) : 패딩에 사용되는 토큰입니다. 예를 들어 길이가 다른 시퀀스를 배치할 때 사용됩니다.

sep_token_box (`list[int]`, *선택 사항*, 기본값 `[1000, 1000, 1000, 1000]`) : 특수 [SEP] 토큰에 사용할 바운딩 박스입니다.

pad_token_box (`list[int]`, *선택 사항*, 기본값 `[0, 0, 0, 0]`) : 특수 [PAD] 토큰에 사용할 바운딩 박스입니다.

pad_token_label (`int`, *선택 사항*, 기본값 -100) : 패딩 토큰에 사용할 라벨입니다. 기본값은 -100이며, 이는 PyTorch의 CrossEntropyLoss의 `ignore_index`입니다.

only_label_first_subword (`bool`, *선택 사항*, 기본값 `True`) : 단어 라벨이 제공된 경우 첫 번째 서브워드만 라벨링할지 여부.

extra_special_tokens (`list[str]`, *선택 사항*, 기본값 `["<s>NOTUSED", "</s>NOTUSED"]`) : 토크나이저가 사용하는 추가 특수 토큰입니다.

HuggingFace의 *tokenizers* 라이브러리를 기반으로 하는 "fast" UDOP 토크나이저를 구성합니다. [LayoutXLMTokenizer](/docs/transformers/main/ko/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) 및 [T5Tokenizer](/docs/transformers/main/ko/model_doc/t5#transformers.T5Tokenizer)에서 가져왔습니다. [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models)를 기반으로 합니다.

이 토크나이저는 대부분의 주요 메서드를 포함하는 [TokenizersBackend](/docs/transformers/main/ko/main_classes/tokenizer#transformers.TokenizersBackend)에서 상속됩니다. 해당 메서드에 대한 자세한 정보는 이 상위 클래스를 참고하세요.

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

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

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

**매개변수:**

token_ids_0 (`list[int]`) : 특수 토큰이 추가될 ID 목록.

token_ids_1 (`list[int]`, *선택 사항*) : 시퀀스 쌍을 위한 선택적 두 번째 ID 목록.

**반환값:** `list[int]`

적절한 특수 토큰이 포함된 [입력 ID](../glossary#input-ids) 목록

시퀀스 분류 작업을 위해 시퀀스 또는 시퀀스 쌍에서 모델 입력을 생성하려면 특수 토큰을 추가하고 연결합니다. XLM-RoBERTa 시퀀스는 다음 형식을 가집니다:

- 단일 시퀀스: `<s> X </s>`
- 시퀀스 쌍: `<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)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_base.py#L1338)

**매개변수:**

token_ids_0 : (이미 포맷된) 시퀀스의 ID 목록.

token_ids_1 : `already_has_special_tokens=True`인 경우 사용되지 않습니다. 이 경우 None이어야 합니다.

already_has_special_tokens : 시퀀스가 이미 특수 토큰으로 포맷되어 있는지 여부.

**반환값:** [0, 1] 범위의 정수 목록

특수 토큰은 1, 시퀀스 토큰은 0입니다.

…

빠른 토크나이저의 경우, 데이터 콜레이터는 이미 포맷된 시퀀스에 대한 마스크를 생성하기 위해 `already_has_special_tokens=True`를 전달하여 이 메서드를 호출합니다. 이 경우 `all_special_ids`에 대한 멤버십을 확인하여 마스크를 계산합니다.

#### 시퀀스에서 토큰 타입 ID 생성[[transformers.UdopTokenizer.create_token_type_ids_from_sequences]]

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

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

**매개변수:**

token_ids_0 (`list[int]`) : ID 목록.

token_ids_1 (`list[int]`, *선택 사항*) : 시퀀스 쌍을 위한 선택적 두 번째 ID 목록.

**반환값:** `list[int]`

0으로만 이루어진 리스트.

시퀀스-페어 분류 작업에 사용될 두 시퀀스로부터 마스크를 생성합니다. XLM-RoBERTa는 토큰 타입 ID를 사용하지 않으므로, 0의 목록이 반환됩니다.

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

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

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

토크나이저 어휘 파일을 저장합니다. TokenizersBackend의 경우 tokenizer.json 파일은 베이스 클래스에 의해 저장됩니다. 이 메서드는 tokenizer.json만 사용하므로 빈 튜플을 반환합니다.

## UdopProcessor[[transformers.UdopProcessor]]

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

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

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

**매개변수:**

image_processor (`LayoutLMv3ImageProcessor`) : 이미지 프로세서가 필수 입력입니다.

tokenizer (`UdopTokenizer`) : 토크나이저는 필수 입력입니다.

이미지 프로세서와 토크나이저를 단일 프로세서로 래핑하는 UdopProcessor를 생성합니다.

[UdopProcessor](/docs/transformers/main/ko/model_doc/udop#transformers.UdopProcessor)는 [LayoutLMv3ImageProcessor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor)와 [UdopTokenizer](/docs/transformers/main/ko/model_doc/udop#transformers.UdopTokenizer)의 모든 기능을 제공합니다. 자세한 내용은 [~LayoutLMv3ImageProcessor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor)와 [~UdopTokenizer](/docs/transformers/main/ko/model_doc/udop#transformers.UdopTokenizer)를 참고하세요.

#### __call__[[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, **kwargs: *<class 'transformers.models.udop.processing_udop.UdopProcessorKwargs'>)
```

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

**매개변수:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *선택*) : 전처리할 이미지. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 범위로 이루어진 이미지를 전달하는 경우 `do_rescale=False`로 설정하세요.

text (`Union[str, list[str], list[list[str]]]`, *선택*) : 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 사전 토큰화된 입력을 전달하는 경우, 배치 입력과의 혼동을 피하기 위해 `is_split_into_words=True`를 설정하세요.

return_tensors (`str` 또는 [TensorType](/docs/transformers/main/ko/internal/file_utils#transformers.TensorType), *optional*) : 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:  - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: NumPy `np.ndarray` 객체를 반환합니다.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/ko/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

**반환값:** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- __call__ 메서드가 반환하는 리스트/배열/텐서 딕셔너리('pixel_values' 등).
- **tensor_type** (`Union[None, str, TensorType]`, *선택 사항*) -- 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type을 지정할 수 있습니다.

## UdopModel[[transformers.UdopModel]]

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

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

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

**매개변수:**

config ([UdopConfig](/docs/transformers/main/ko/model_doc/udop#transformers.UdopConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 기본 Udop Model입니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### 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, past_key_values: 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'>)
```

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

**매개변수:**

input_ids (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

bbox (`torch.LongTensor`, shape `({0}, 4)`, *선택 사항*) : 각 입력 시퀀스 토큰의 바운딩 박스. `[0, config.max_2d_position_embeddings-1]` 범위에서 선택됩니다. 각 바운딩 박스는 (x0, y0, x1, y1) 형식의 정규화된 버전이어야 하며, 여기서 (x0, y0)는 바운딩 박스의 왼쪽 위 모서리 위치를, (x1, y1)는 오른쪽 아래 모서리 위치를 나타냅니다. `sequence_length = token_sequence_length + patch_sequence_length + 1`이며, 여기서 `1`은 [CLS] 토큰을 위한 것입니다. `patch_sequence_length`에 대해서는 `pixel_values`를 참조하세요.

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [LayoutLMv3ImageProcessor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/main/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하십시오 ([UdopProcessor](/docs/transformers/main/ko/model_doc/udop#transformers.UdopProcessor)는 이미지 처리에 [LayoutLMv3ImageProcessor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor)를 사용합니다).

visual_bbox (`torch.LongTensor`, shape `(batch_size, patch_sequence_length, 4)`, *선택 사항*) : 이미지에서 각 패치의 바운딩 박스입니다. 제공되지 않으면 모델에서 바운딩 박스가 생성됩니다.

decoder_input_ids (`torch.LongTensor`, shape `(batch_size, target_sequence_length)`, *선택 사항*) : 어휘에서 디코더 입력 시퀀스 토큰의 인덱스입니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [디코더 입력 ID란 무엇인가요?](../glossary#decoder-input-ids) T5는 `decoder_input_ids` 생성의 시작 토큰으로 `pad_token_id`를 사용합니다. `past_key_values`를 사용하는 경우, 선택적으로 마지막 `decoder_input_ids`만 입력하면 됩니다(`past_key_values` 참조). 사전 학습을 위해 `decoder_input_ids`를 준비하는 방법에 대해서는 [T5 Training](./t5#training)을 확인하세요.

decoder_attention_mask (`torch.BoolTensor`, shape `(batch_size, target_sequence_length)`, *선택 사항*) : 기본 동작: `decoder_input_ids`의 pad 토큰을 무시하는 텐서를 생성합니다. 기본적으로 Causal mask도 사용됩니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

encoder_outputs (`torch.Tensor`, *선택 사항*) : (`last_hidden_state`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`) `last_hidden_state`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)이며, 인코더의 마지막 레이어 출력에서 생성된 hidden-states의 시퀀스입니다. 디코더의 cross-attention에 사용됩니다.

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

decoder_inputs_embeds (`torch.Tensor`, shape `(batch_size, target_sequence_length, hidden_size)`, *선택 사항*) : `decoder_input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. `past_key_values`를 사용하는 경우, 선택적으로 마지막 `decoder_inputs_embeds`만 입력하면 됩니다(`past_key_values` 참조). 모델 내부 임베딩 조회 행렬보다 `decoder_input_ids` 인덱스를 관련 벡터로 변환하는 방식을 더 세밀하게 제어하려는 경우 유용합니다. `decoder_input_ids`와 `decoder_inputs_embeds`가 모두 설정되지 않은 경우, `decoder_inputs_embeds`는 `inputs_embeds`의 값을 취합니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

**반환값:** [Seq2SeqModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) 또는 `tuple(torch.Tensor)`

구성([UdopConfig](/docs/transformers/main/ko/model_doc/udop#transformers.UdopConfig))과 입력에 따라 다양한 요소를 포함하는 [Seq2SeqModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[UdopModel](/docs/transformers/main/ko/model_doc/udop#transformers.UdopModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 decoder 마지막 레이어 출력의 hidden-state 시퀀스입니다.

  `past_key_values`가 사용되면, `(batch_size, 1, hidden_size)` 형태의 시퀀스의 마지막 hidden-state만 출력됩니다.
- **past_key_values** (`EncoderDecoderCache`, *선택 사항*, `use_cache=True`가 전달되거나 `config.use_cache=True`인 경우 반환됨) -- [EncoderDecoderCache](/docs/transformers/main/ko/internal/generation_utils#transformers.EncoderDecoderCache) 인스턴스입니다. 자세한 내용은 [kv 캐시 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록과 크로스-어텐션 블록의 key 및 values)를 포함합니다(입력 `past_key_values` 참조).
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어 출력의 decoder hidden-states와 선택적인 초기 embedding 출력
- **decoder_attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor` 튜플이며, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 decoder의 attention 가중치입니다.
- **cross_attentions** (`tuple(torch.Tensor)`, *선택*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  decoder의 cross-attention 레이어에서 attention softmax를 적용한 후, cross-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention 가중치입니다.
- **encoder_last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) -- 모델 인코더의 마지막 레이어 출력의 hidden-state 시퀀스입니다.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`일 때 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어 출력의 인코더 hidden-states와 선택적인 초기 임베딩 출력.
- **encoder_attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어에 하나씩 포함된 `torch.Tensor` 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  인코더의 어텐션 가중치입니다. 어텐션 softmax 이후에 self-attention 헤드에서 가중 평균을 계산하는 데 사용됩니다.

예:

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

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

**매개변수:**

config ([UdopConfig](/docs/transformers/main/ko/model_doc/udop#transformers.UdopConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

언어 모델링 헤드가 위에 있는 UDOP 인코더-디코더 Transformer로, 문서 이미지와 선택적 프롬프트를 입력으로 받아 텍스트를 생성할 수 있습니다.

이 클래스는 [T5ForConditionalGeneration](/docs/transformers/main/ko/model_doc/t5#transformers.T5ForConditionalGeneration)을 기반으로 하며, 이미지와 레이아웃(2D) 데이터를 처리하도록 확장되었습니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### 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, past_key_values: 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'>)
```

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

**매개변수:**

input_ids (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

bbox (`torch.LongTensor`, shape `({0}, 4)`, *선택 사항*) : 각 입력 시퀀스 토큰의 바운딩 박스. `[0, config.max_2d_position_embeddings-1]` 범위에서 선택됩니다. 각 바운딩 박스는 (x0, y0, x1, y1) 형식의 정규화된 버전이어야 하며, 여기서 (x0, y0)는 바운딩 박스의 왼쪽 위 모서리 위치를, (x1, y1)는 오른쪽 아래 모서리 위치를 나타냅니다. `sequence_length = token_sequence_length + patch_sequence_length + 1`이며, 여기서 `1`은 [CLS] 토큰을 위한 것입니다. `patch_sequence_length`에 대해서는 `pixel_values`를 참조하세요.

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [LayoutLMv3ImageProcessor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/main/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하십시오 ([UdopProcessor](/docs/transformers/main/ko/model_doc/udop#transformers.UdopProcessor)는 이미지 처리에 [LayoutLMv3ImageProcessor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor)를 사용합니다).

visual_bbox (`torch.LongTensor`, shape `(batch_size, patch_sequence_length, 4)`, *선택 사항*) : 이미지에서 각 패치의 바운딩 박스입니다. 제공되지 않으면 모델에서 바운딩 박스가 생성됩니다.

decoder_input_ids (`torch.LongTensor`, shape `(batch_size, target_sequence_length)`, *선택 사항*) : 어휘에서 디코더 입력 시퀀스 토큰의 인덱스입니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [디코더 입력 ID란 무엇인가요?](../glossary#decoder-input-ids) T5는 `decoder_input_ids` 생성의 시작 토큰으로 `pad_token_id`를 사용합니다. `past_key_values`를 사용하는 경우, 선택적으로 마지막 `decoder_input_ids`만 입력하면 됩니다(`past_key_values` 참조). 사전 학습을 위해 `decoder_input_ids`를 준비하는 방법에 대해서는 [T5 Training](./t5#training)을 확인하세요.

decoder_attention_mask (`torch.BoolTensor`, shape `(batch_size, target_sequence_length)`, *선택 사항*) : 기본 동작: `decoder_input_ids`의 pad 토큰을 무시하는 텐서를 생성합니다. 기본적으로 Causal mask도 사용됩니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

encoder_outputs (`torch.Tensor`, *선택 사항*) : (`last_hidden_state`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`) `last_hidden_state`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)이며, 인코더의 마지막 레이어 출력에서 생성된 hidden-states의 시퀀스입니다. 디코더의 cross-attention에 사용됩니다.

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

decoder_inputs_embeds (`torch.Tensor`, shape `(batch_size, target_sequence_length, hidden_size)`, *선택 사항*) : `decoder_input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. `past_key_values`를 사용하는 경우, 선택적으로 마지막 `decoder_inputs_embeds`만 입력하면 됩니다(`past_key_values` 참조). 모델 내부 임베딩 조회 행렬보다 `decoder_input_ids` 인덱스를 관련 벡터로 변환하는 방식을 더 세밀하게 제어하려는 경우 유용합니다. `decoder_input_ids`와 `decoder_inputs_embeds`가 모두 설정되지 않은 경우, `decoder_inputs_embeds`는 `inputs_embeds`의 값을 취합니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

labels (`torch.LongTensor`, shape `(batch_size,)`, *선택 사항*) : 언어 모델링 손실을 계산하기 위한 라벨. 인덱스는 `[-100, 0, ..., config.vocab_size - 1]` 범위에 있어야 합니다. `-100`으로 설정된 모든 라벨은 무시(마스크)되며, 손실은 `[0, ..., config.vocab_size]` 범위의 라벨에 대해서만 계산됩니다.

**반환값:** [Seq2SeqLMOutput](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 또는 `tuple(torch.Tensor)`

구성([UdopConfig](/docs/transformers/main/ko/model_doc/udop#transformers.UdopConfig))과 입력에 따라 다양한 요소를 포함하는 [Seq2SeqLMOutput](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[UdopForConditionalGeneration](/docs/transformers/main/ko/model_doc/udop#transformers.UdopForConditionalGeneration)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, shape `(1,)`, *선택*, `labels`이 제공될 때 반환됨) -- 언어 모델링 손실.
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.vocab_size)`) -- 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).
- **past_key_values** (`EncoderDecoderCache`, *선택 사항*, `use_cache=True`가 전달되거나 `config.use_cache=True`인 경우 반환됨) -- [EncoderDecoderCache](/docs/transformers/main/ko/internal/generation_utils#transformers.EncoderDecoderCache) 인스턴스입니다. 자세한 내용은 [kv 캐시 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록과 크로스-어텐션 블록의 key 및 values)를 포함합니다(입력 `past_key_values` 참조).
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어의 출력에서 디코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **decoder_attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor` 튜플이며, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 decoder의 attention 가중치입니다.
- **cross_attentions** (`tuple(torch.Tensor)`, *선택*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  decoder의 cross-attention 레이어에서 attention softmax를 적용한 후, cross-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention 가중치입니다.
- **encoder_last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) -- 모델 인코더의 마지막 레이어 출력의 hidden-state 시퀀스입니다.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`일 때 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어의 출력에서 인코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **encoder_attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어에 하나씩 포함된 `torch.Tensor` 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  인코더의 어텐션 가중치입니다. 어텐션 softmax 이후에 self-attention 헤드에서 가중 평균을 계산하는 데 사용됩니다.

예:

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

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

**매개변수:**

config ([UdopConfig](/docs/transformers/main/ko/model_doc/udop#transformers.UdopConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 기본 Udop Model입니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

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

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

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : 어휘 사전에서 입력 시퀀스 토큰의 인덱스입니다. T5는 상대 위치 임베딩을 사용하는 모델이므로 입력을 오른쪽과 왼쪽 모두에 패딩할 수 있습니다. 인덱스는 [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. 사전 학습을 위해 `input_ids`를 준비하는 방법에 대해서는 [T5 Training](./t5#training)을 확인하세요.

bbox (`torch.LongTensor`, shape `({0}, 4)`, *선택 사항*) : 각 입력 시퀀스 토큰의 바운딩 박스. `[0, config.max_2d_position_embeddings-1]` 범위에서 선택됩니다. 각 바운딩 박스는 (x0, y0, x1, y1) 형식의 정규화된 버전이어야 하며, 여기서 (x0, y0)는 바운딩 박스의 왼쪽 위 모서리 위치를, (x1, y1)는 오른쪽 아래 모서리 위치를 나타냅니다. `sequence_length = token_sequence_length + patch_sequence_length + 1`이며, 여기서 `1`은 [CLS] 토큰을 위한 것입니다. `patch_sequence_length`에 대해서는 `pixel_values`를 참조하세요.

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [LayoutLMv3ImageProcessor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/main/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하십시오 ([UdopProcessor](/docs/transformers/main/ko/model_doc/udop#transformers.UdopProcessor)는 이미지 처리에 [LayoutLMv3ImageProcessor](/docs/transformers/main/ko/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor)를 사용합니다).

visual_bbox (`torch.LongTensor`, shape `(batch_size, patch_sequence_length, 4)`, *선택 사항*) : 이미지에서 각 패치의 바운딩 박스입니다. 제공되지 않으면 모델에서 바운딩 박스가 생성됩니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

**반환값:** `BaseModelOutputWithAttentionMask` 또는 `tuple(torch.Tensor)`

A `BaseModelOutputWithAttentionMask` or a tuple of `torch.Tensor` (if `return_dict=False` is passed or when `config.return_dict=False`) comprising various elements depending on the configuration ([UdopConfig](/docs/transformers/main/ko/model_doc/udop#transformers.UdopConfig)) and inputs.

[UdopEncoderModel](/docs/transformers/main/ko/model_doc/udop#transformers.UdopEncoderModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다. `past_key_values`를 사용하는 경우, shape가 `(batch_size, 1, hidden_size)`인 시퀀스의 마지막 hidden-state만 출력됩니다.
- **attention_mask** (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) -- 모델의 forward pass에서 padding 토큰 인덱스에 대한 attention을 수행하지 않도록 사용되는 attention mask. `[0, 1]` 범위에서 선택된 mask 값:
  - **마스크되지 않은** 토큰에 대해 1
  - **마스크**된 토큰에 대해 0
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value, 그리고 `config.is_encoder_decoder=True`인 경우 크로스 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 `(batch_size, sequence_length, hidden_size)`입니다. 각 레이어 출력 시점의 모델 hidden-states와 선택적인 초기 임베딩 출력을 포함합니다.
- **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.add_cross_attention=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다. 어텐션 softmax 이후 디코더의 크로스 어텐션 레이어의 어텐션 가중치로, 크로스 어텐션 헤드에서 가중 평균을 계산하는 데 사용됩니다.

예:

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