# UDOP

## Tổng quan

Mô hình UDOP được đề xuất trong [Unifying Vision, Text, and Layout for Universal Document Processing](https://huggingface.co/papers/2212.02623) bởi Zineng Tang, Ziyi Yang, Guoxin Wang, Yuwei Fang, Yang Liu, Chenguang Zhu, Michael Zeng, Cha Zhang, Mohit Bansal. UDOP áp dụng kiến trúc Transformer encoder-decoder dựa trên [T5](t5) cho các tác vụ AI tài liệu như phân loại ảnh tài liệu, phân tích tài liệu và trả lời câu hỏi trực quan về tài liệu.

Tóm tắt từ bài báo như sau:

Chúng tôi đề xuất Universal Document Processing (UDOP), một mô hình nền tảng Document AI thống nhất các phương thức văn bản, hình ảnh và bố cục cùng với các định dạng tác vụ đa dạng, bao gồm cả hiểu và tạo tài liệu. UDOP khai thác tương quan không gian giữa nội dung văn bản và hình ảnh tài liệu để mô hình hóa các phương thức hình ảnh, văn bản và bố cục bằng một biểu diễn thống nhất. Với Vision-Text-Layout Transformer mới, UDOP thống nhất tiền huấn luyện và các tác vụ hạ nguồn đa lĩnh vực vào một phương án tạo chuỗi dựa trên prompt. UDOP được tiền huấn luyện trên cả các kho ngữ liệu tài liệu quy mô lớn không nhãn bằng các mục tiêu tự giám sát sáng tạo và dữ liệu có nhãn đa dạng. UDOP cũng học cách tạo hình ảnh tài liệu từ các phương thức văn bản và bố cục thông qua tái tạo hình ảnh có che. Theo hiểu biết của chúng tôi, đây là lần đầu tiên trong lĩnh vực Document AI mà một mô hình đồng thời đạt được chỉnh sửa tài liệu bằng mạng nơ-ron chất lượng cao và tùy chỉnh nội dung. Phương pháp của chúng tôi thiết lập mức tiên tiến nhất (state-of-the-art) trên 9 tác vụ Document AI, ví dụ như hiểu tài liệu và QA, trên các lĩnh vực dữ liệu đa dạng như báo cáo tài chính, bài báo học thuật và trang web. UDOP xếp hạng nhất trên bảng xếp hạng của 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"/>

 Kiến trúc UDOP. Được trích từ bài báo gốc.

## Mẹo sử dụng

- Ngoài *input_ids*, [UdopForConditionalGeneration](/docs/transformers/main/vi/model_doc/udop#transformers.UdopForConditionalGeneration) còn mong đợi đầu vào `bbox`, tức là các hộp bao (bounding box) (tức là vị trí 2D) của các token đầu vào. Chúng có thể được lấy bằng một bộ máy OCR bên ngoài như [Tesseract](https://github.com/tesseract-ocr/tesseract) của Google (có sẵn [Python wrapper](https://pypi.org/project/pytesseract/)). Mỗi hộp bao nên ở định dạng (x0, y0, x1, y1), trong đó (x0, y0) tương ứng với vị trí góc trên bên trái của hộp bao, và (x1, y1) đại diện cho vị trí góc dưới bên phải. Lưu ý rằng trước tiên cần chuẩn hóa các hộp bao về thang đo 0-1000. Để chuẩn hóa, bạn có thể sử dụng hàm sau:

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

Ở đây, `width` và `height` tương ứng với chiều rộng và chiều cao của tài liệu gốc mà token xuất hiện. Những giá trị này có thể được lấy bằng cách sử dụng thư viện Python Image Library (PIL), ví dụ như sau:

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

Bạn có thể sử dụng [UdopProcessor](/docs/transformers/main/vi/model_doc/udop#transformers.UdopProcessor) để chuẩn bị hình ảnh và văn bản cho mô hình, lớp này sẽ xử lý toàn bộ các bước đó. Mặc định, lớp này sử dụng engine Tesseract để trích xuất danh sách các từ và hộp (tọa độ) từ một tài liệu cho trước. Chức năng của nó tương đương với [LayoutLMv3Processor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3Processor), do đó nó hỗ trợ truyền `apply_ocr=False` nếu bạn muốn sử dụng engine OCR của riêng mình hoặc `apply_ocr=True` nếu bạn muốn sử dụng engine OCR mặc định. Tham khảo [hướng dẫn sử dụng của LayoutLMv2](layoutlmv2#usage-layoutlmv2processor) về tất cả các trường hợp sử dụng có thể (chức năng của `UdopProcessor` là giống hệt).

- Nếu sử dụng một bộ máy OCR tùy chọn, một khuyến nghị là [Read API](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/how-to/call-read-api) của Azure, hỗ trợ các đoạn dòng (line segments) theo nghĩa thông thường. Việc sử dụng nhúng vị trí đoạn (segment position embeddings) thường cho hiệu suất tốt hơn.
- Vào thời điểm suy luận, khuyến nghị sử dụng phương thức `generate` để tự hồi quy tạo văn bản dựa trên ảnh tài liệu.
- Mô hình đã được huấn luyện trước trên cả các mục tiêu tự giám sát và có giám sát. Người dùng có thể sử dụng các tiền tố tác vụ (prompts) khác nhau được dùng trong quá trình huấn luyện trước để kiểm tra khả năng sẵn có của mô hình. Ví dụ, mô hình có thể được đưa prompt "Question answering. What is the date?", vì "Question answering." là tiền tố tác vụ được sử dụng trong quá trình huấn luyện trước cho DocVQA. Tham khảo [bài báo](https://huggingface.co/papers/2212.02623) (bảng 1) để biết tất cả các tiền tố tác vụ.
- Người dùng cũng có thể tinh chỉnh [UdopEncoderModel](/docs/transformers/main/vi/model_doc/udop#transformers.UdopEncoderModel), đây là phần chỉ có encoder của UDOP, có thể được xem là một encoder Transformer tương tự LayoutLMv3. Đối với các tác vụ phân biệt, người dùng chỉ cần thêm một bộ phân loại tuyến tính phía trên và tinh chỉnh nó trên một tập dữ liệu có nhãn.

Mô hình này được đóng góp bởi [nielsr](https://huggingface.co/nielsr). Mã gốc có thể được tìm thấy [tại đây](https://github.com/microsoft/UDOP).

## Tài nguyên

Danh sách các tài nguyên chính thức của Hugging Face và cộng đồng (được đánh dấu bằng 🌎) để giúp bạn bắt đầu với UDOP. Nếu bạn quan tâm đến việc gửi tài nguyên để được đưa vào đây, hãy thoải mái mở một Pull Request và chúng tôi sẽ xem xét! Tài nguyên lý tưởng nên minh họa một điều gì đó mới thay vì sao chép một tài nguyên hiện có.

- Các notebook demo về UDOP có thể được tìm thấy [tại đây](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UDOP), cho thấy cách
để tinh chỉnh UDOP trên một tập dữ liệu tùy chỉnh cũng như suy luận. 🌎
- [Hướng dẫn cho tác vụ trả lời câu hỏi từ tài liệu](../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)
```

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

**Tham số:**

is_encoder_decoder (`bool`, *tùy chọn*, mặc định là `True`) : Xác định xem mô hình có được sử dụng như một bộ mã hóa/giải mã hay không.

vocab_size (`int`, *tùy chọn*, mặc định là `33201`) : Kích thước từ vựng của mô hình. Xác định số lượng token khác nhau có thể được biểu diễn bởi `input_ids`.

d_model (`int`, *tuỳ chọn*, mặc định là `1024`) : Kích thước của các lớp encoder và lớp pooler.

d_kv (`int`, *tuỳ chọn*, mặc định là `64`) : Kích thước của các phép chiếu key, query, value cho mỗi đầu chú ý. `inner_dim` của lớp chiếu sẽ được định nghĩa là `num_heads * d_kv`.

d_ff (`int`, *tuỳ chọn*, mặc định là `4096`) : Kích thước của các biểu diễn MLP.

num_layers (`int`, *tuỳ chọn*, mặc định là `24`) : Số lượng lớp ẩn trong bộ giải mã Transformer.

num_decoder_layers (`int`, *tuỳ chọn*) : Số lượng lớp ẩn trong bộ giải mã Transformer. Sẽ sử dụng cùng giá trị với `num_layers` nếu không được đặt.

num_heads (`int`, *tuỳ chọn*, mặc định là `16`) : Số lượng đầu chú ý cho mỗi lớp chú ý trong bộ giải mã Transformer.

relative_attention_num_buckets (`int`, *tuỳ chọn*, mặc định là 32) : Số lượng bucket được sử dụng cho mỗi lớp attention.

relative_attention_max_distance (`int`, *tuỳ chọn*, mặc định là 128) : Khoảng cách tối đa của các chuỗi dài hơn cho việc tách bucket.

relative_bias_args (`list[dict]`, *tùy chọn*, mặc định là `[{'type' : '1d'}, {'type': 'horizontal'}, {'type': 'vertical'}]`): Một danh sách các từ điển chứa các đối số cho các lớp bias tương đối.

dropout_rate (`Union[float, int]`, *tùy chọn*, mặc định là `0.1`) : Tỷ lệ cho tất cả các lớp dropout.

layer_norm_epsilon (`float`, *tuỳ chọn*, mặc định là `1e-06`) : Epsilon được sử dụng bởi các lớp chuẩn hóa lớp (layer normalization).

initializer_factor (`float`, *tuỳ chọn*, mặc định là `1.0`) : Hệ số để khởi tạo tất cả các ma trận trọng số (nên giữ ở mức 1, được sử dụng bên trong cho việc kiểm tra khởi tạo).

feed_forward_proj (`string`, *tuỳ chọn*, mặc định là `"relu"`) : Loại lớp feed forward sẽ được sử dụng. Phải là một trong `"relu"` hoặc `"gated-gelu"`. Udopv1.1 sử dụng phép chiếu feed forward `"gated-gelu"`. Udop gốc sử dụng `"relu"`.

use_cache (`bool`, *tùy chọn*, mặc định là `True`) : Xác định xem mô hình có nên trả về các chú ý key/values cuối cùng hay không (không được sử dụng bởi tất cả các mô hình). Chỉ liên quan nếu `config.is_decoder=True` hoặc khi mô hình là mô hình sinh chỉ có decoder.

pad_token_id (`int`, *tùy chọn*, mặc định là `0`) : Id của token được sử dụng để đệm (padding) trong từ vựng.

eos_token_id (`Union[int, list[int]]`, *tùy chọn*, mặc định là `1`) : Id của token được sử dụng cho end-of-stream trong bảng từ vựng.

max_2d_position_embeddings (`int`, *optional*, mặc định là 1024) : Số lượng tối đa của các embedding vị trí tuyệt đối cho mã hóa vị trí tương đối.

image_size (`Union[int, list[int], tuple[int, int]]`, *tùy chọn*, mặc định là `224`) : Kích thước (độ phân giải) của mỗi hình ảnh.

patch_size (`Union[int, list[int], tuple[int, int]]`, *tùy chọn*, mặc định là `16`) : Kích thước (độ phân giải) của mỗi patch.

num_channels (`int`, *tuỳ chọn*, mặc định là `3`) : Số lượng kênh đầu vào.

is_decoder (`bool`, *tùy chọn*, mặc định là `False`) : Xác định xem mô hình có được sử dụng như một bộ giải mã (decoder) hay không. Nếu `False`, mô hình sẽ được sử dụng như một bộ mã hóa (encoder).

add_cross_attention (`bool`, *tùy chọn*, mặc định là `False`) : Xác định xem có nên thêm các lớp cross-attention vào mô hình hay không.

tie_word_embeddings (`bool`, *tùy chọn*, mặc định là `True`) : Có nên gắn kết các nhúng trọng số theo ánh xạ `tied_weights_keys` của mô hình hay không.

Đây là lớp cấu hình để lưu trữ cấu hình của một UdopModel. Nó được sử dụng để khởi tạo một mô hình Udop theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của [microsoft/udop-large](https://huggingface.co/microsoft/udop-large)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

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

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

**Tham số:**

eos_token (`str`, *tùy chọn*, mặc định là `"</s>"`) : Token kết thúc chuỗi. Khi xây dựng một chuỗi bằng các token đặc biệt, đây không phải là token được dùng cho việc kết thúc chuỗi. Token được dùng là `sep_token`.

sep_token (`str`, *tùy chọn*, mặc định là `"</s>"`) : Token phân cách, được sử dụng khi xây dựng một chuỗi từ nhiều chuỗi, ví dụ như hai chuỗi cho phân loại chuỗi hoặc một văn bản và một câu hỏi cho trả lời câu hỏi. Nó cũng được sử dụng làm token cuối cùng của một chuỗi được xây dựng với các token đặc biệt.

unk_token (`str`, *tùy chọn*, mặc định là `"<unk>"`) : Token không xác định. Một token không có trong từ vựng sẽ không thể được chuyển đổi thành ID và sẽ được gán thành token này thay thế.

pad_token (`str`, *tùy chọn*, mặc định là `"<pad>"`) : Token được sử dụng để đệm, chẳng hạn khi xử lý các lô (batch) các chuỗi có độ dài khác nhau.

sep_token_box (`list[int]`, *tùy chọn*, mặc định là `[1000, 1000, 1000, 1000]`) : Hộp bao (bounding box) được sử dụng cho token đặc biệt [SEP].

pad_token_box (`list[int]`, *tuỳ chọn*, mặc định là `[0, 0, 0, 0]`) : Hộp bao (bounding box) được sử dụng cho token đặc biệt [PAD].

pad_token_label (`int`, *tuỳ chọn*, mặc định là -100) : Nhãn được sử dụng cho các token đệm. Mặc định là -100, đây là `ignore_index` của CrossEntropyLoss trong PyTorch.

only_label_first_subword (`bool`, *tùy chọn*, mặc định là `True`) : Có chỉ gán nhãn cho subword đầu tiên hay không, trong trường hợp các nhãn từ được cung cấp.

extra_special_tokens (`list[str]`, *tùy chọn*, mặc định là `["<s>NOTUSED", "</s>NOTUSED"]`) : Các token đặc biệt bổ sung được sử dụng bởi tokenizer.

Xây dựng bộ phân từ UDOP "nhanh" (dựa trên thư viện *tokenizers* của HuggingFace). Được điều chỉnh từ [LayoutXLMTokenizer](/docs/transformers/main/vi/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) và [T5Tokenizer](/docs/transformers/main/vi/model_doc/t5#transformers.T5Tokenizer). Dựa trên [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models).

Tokenizer này kế thừa từ [TokenizersBackend](/docs/transformers/main/vi/main_classes/tokenizer#transformers.TokenizersBackend), lớp chứa hầu hết các phương thức chính. Người dùng nên tham khảo lớp cha này để biết thêm thông tin về các phương thức đó.

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

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

**Tham số:**

token_ids_0 (`list[int]`) : Danh sách các ID mà các token đặc biệt sẽ được thêm vào.

token_ids_1 (`list[int]`, *tuỳ chọn*) : Danh sách ID thứ hai tuỳ chọn cho các cặp chuỗi.

**Trả về:** `list[int]`

Danh sách [input IDs](../glossary#input-ids) với các token đặc biệt phù hợp.

Xây dựng đầu vào mô hình từ một chuỗi hoặc một cặp chuỗi cho các tác vụ phân loại chuỗi bằng cách nối và thêm các token đặc biệt. Một chuỗi XLM-RoBERTa có định dạng như sau:

- một chuỗi đơn: `<s> X </s>`
- cặp chuỗi: `<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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_base.py#L1338)

**Tham số:**

token_ids_0 : Danh sách các ID của chuỗi (có thể đã được định dạng).

token_ids_1 : Không được sử dụng khi `already_has_special_tokens=True`. Trong trường hợp đó, giá trị phải là None.

already_has_special_tokens : Xác định xem chuỗi đã được định dạng với các token đặc biệt hay chưa.

**Trả về:** Một danh sách các số nguyên trong khoảng [0, 1]

1 cho token đặc biệt, 0 cho token chuỗi.

Lấy các id chuỗi từ một danh sách token không có token đặc biệt nào được thêm vào.

Đối với các tokenizer nhanh, các data collator gọi hàm này với `already_has_special_tokens=True` để xây dựng một mask trên một chuỗi đã được định dạng sẵn. Trong trường hợp đó, chúng ta tính mask bằng cách kiểm tra sự thuộc về trong `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, token_ids_1: list[int] | None = None)
```

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

**Tham số:**

token_ids_0 (`list[int]`) : Danh sách các ID.

token_ids_1 (`list[int]`, *tuỳ chọn*) : Danh sách ID thứ hai tuỳ chọn cho các cặp chuỗi.

**Trả về:** `list[int]`

Danh sách các số 0.

Tạo một mask từ hai chuỗi được truyền vào để sử dụng trong một tác vụ phân loại cặp chuỗi. XLM-RoBERTa không sử dụng token type ids, do đó một danh sách các số 0 được trả về.

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

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

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

Lưu các tệp từ vựng của tokenizer. Đối với TokenizersBackend, tệp tokenizer.json được lưu bởi lớp cơ sở. Phương thức này trả về một bộ rỗng vì chúng ta chỉ sử dụng tokenizer.json.

## UdopProcessor[[transformers.UdopProcessor]]

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

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

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

**Tham số:**

image_processor (`LayoutLMv3ImageProcessor`) : Bộ xử lý ảnh là một đầu vào bắt buộc.

tokenizer (`UdopTokenizer`) : Tokenizer là đầu vào bắt buộc.

Tạo một UdopProcessor đóng gói một bộ xử lý ảnh và một tokenizer thành một bộ xử lý duy nhất.

[UdopProcessor](/docs/transformers/main/vi/model_doc/udop#transformers.UdopProcessor) cung cấp đầy đủ các chức năng của [LayoutLMv3ImageProcessor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) và [UdopTokenizer](/docs/transformers/main/vi/model_doc/udop#transformers.UdopTokenizer). Xem [~LayoutLMv3ImageProcessor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) và [~UdopTokenizer](/docs/transformers/main/vi/model_doc/udop#transformers.UdopTokenizer) để biết thêm thông tin.

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

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

**Tham số:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *tùy chọn*) : Ảnh cần tiền xử lý. Kỳ vọng một ảnh đơn hoặc một lô ảnh với giá trị pixel dao động từ 0 đến 255. Nếu truyền vào các ảnh có giá trị pixel nằm trong khoảng từ 0 đến 1, hãy đặt `do_rescale=False`.

text (`Union[str, list[str], list[list[str]]]`, *tùy chọn*) : Chuỗi hoặc lô các chuỗi cần được mã hóa. Mỗi chuỗi có thể là một chuỗi ký tự hoặc một danh sách các chuỗi ký tự (chuỗi đã được tách token trước). Nếu bạn truyền vào đầu vào đã tách token trước, hãy đặt `is_split_into_words=True` để tránh nhầm lẫn với các đầu vào dạng lô.

return_tensors (`str` hoặc [TensorType](/docs/transformers/main/vi/internal/file_utils#transformers.TensorType), *optional*) : Nếu được đặt, sẽ trả về các tensor của một framework cụ thể. Các giá trị chấp nhận được là:  - `'pt'`: Trả về các đối tượng `torch.Tensor` của PyTorch. - `'np'`: Trả về các đối tượng `np.ndarray` của NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/vi/main_classes/processors#transformers.ProcessingKwargs), *optional*) : Các tùy chọn xử lý bổ sung cho từng phương thức (text, images, videos, audio). Các tham số cụ thể của model được liệt kê ở trên; xem lớp TypedDict để biết danh sách đầy đủ các đối số được hỗ trợ.

**Trả về:** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- Từ điển chứa các danh sách/mảng/tensor được trả về bởi phương thức __call__ ('pixel_values', v.v.).
- **tensor_type** (`Union[None, str, TensorType]`, *tùy chọn*) -- Bạn có thể cung cấp tensor_type tại đây để chuyển đổi các danh sách số nguyên trong Tensor PyTorch/Numpy khi khởi tạo.

## UdopModel[[transformers.UdopModel]]

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

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

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

**Tham số:**

config ([UdopConfig](/docs/transformers/main/vi/model_doc/udop#transformers.UdopConfig)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số của mô hình.

Mô hình Udop cơ bản, xuất ra các hidden-state thô mà không có bất kỳ head cụ thể nào ở phía trên.

Mô hình này kế thừa từ [PreTrainedModel](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu ra, v.v.)

Mô hình này cũng là một lớp con của [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.

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

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

**Tham số:**

input_ids (`torch.Tensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Chỉ số của các token trong chuỗi đầu vào theo từ vựng. Mặc định, các token đệm (padding) sẽ bị bỏ qua. Có thể lấy chỉ số bằng cách sử dụng [AutoTokenizer](/docs/transformers/main/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) để biết thêm chi tiết. [ID đầu vào là gì?](../glossary#input-ids)

attention_mask (`torch.Tensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Mặt nạ để tránh thực hiện chú ý trên các chỉ số token đệm. Các giá trị mặt nạ được chọn trong `[0, 1]`:  - 1 cho các token **không bị che**, - 0 cho các token **bị che**.  [Mặt nạ chú ý là gì?](../glossary#attention-mask)

bbox (`torch.LongTensor` có shape `({0}, 4)`, *tùy chọn*) : Các bounding box của các token trong mỗi chuỗi đầu vào. Được chọn trong khoảng `[0, config.max_2d_position_embeddings-1]`. Mỗi bounding box phải là phiên bản đã chuẩn hóa ở định dạng (x0, y0, x1, y1), trong đó (x0, y0) tương ứng với vị trí góc trên bên trái của bounding box, và (x1, y1) đại diện cho vị trí góc dưới bên phải. Lưu ý rằng `sequence_length = token_sequence_length + patch_sequence_length + 1` trong đó `1` là cho token [CLS]. Xem `pixel_values` để biết về `patch_sequence_length`.

pixel_values (`torch.Tensor` có shape `(batch_size, num_channels, image_size, image_size)`, *tùy chọn*) : Các tensor tương ứng với các ảnh đầu vào. Giá trị pixel có thể được lấy bằng cách sử dụng [LayoutLMv3ImageProcessor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor). Xem [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/main/vi/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) để biết chi tiết ([UdopProcessor](/docs/transformers/main/vi/model_doc/udop#transformers.UdopProcessor) sử dụng [LayoutLMv3ImageProcessor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) để xử lý ảnh).

visual_bbox (`torch.LongTensor` có shape `(batch_size, patch_sequence_length, 4)`, *tùy chọn*) : Các bounding box của từng patch trong ảnh. Nếu không được cung cấp, các bounding box sẽ được tạo trong model.

decoder_input_ids (`torch.LongTensor` có shape `(batch_size, target_sequence_length)`, *tùy chọn*) : Chỉ số của các token trong chuỗi đầu vào bộ giải mã trong từ vựng. Các chỉ số có thể được lấy bằng cách sử dụng [AutoTokenizer](/docs/transformers/main/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) để biết chi tiết. [Các ID đầu vào bộ giải mã là gì?](../glossary#decoder-input-ids) T5 sử dụng `pad_token_id` làm token bắt đầu cho việc tạo `decoder_input_ids`. Nếu `past_key_values` được sử dụng, tùy chọn chỉ cần nhập `decoder_input_ids` cuối cùng (xem `past_key_values`). Để biết thêm về cách chuẩn bị `decoder_input_ids` cho huấn luyện trước, hãy xem [T5 Training](./t5#training).

decoder_attention_mask (`torch.BoolTensor` có shape `(batch_size, target_sequence_length)`, *tùy chọn*) : Hành vi mặc định: tạo một tensor bỏ qua các token pad trong `decoder_input_ids`. Causal mask cũng sẽ được sử dụng theo mặc định.

inputs_embeds (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) : Tùy chọn, thay vì truyền `input_ids`, bạn có thể chọn cách truyền trực tiếp một biểu diễn nhúng. Điều này hữu ích nếu bạn muốn kiểm soát nhiều hơn cách chuyển đổi các chỉ số `input_ids` thành các vector liên quan so với ma trận tra cứu nhúng nội bộ của mô hình.

encoder_outputs (`torch.Tensor`, *tùy chọn*) : Tuple gồm (`last_hidden_state`, *tùy chọn*: `hidden_states`, *tùy chọn*: `attentions`) `last_hidden_state` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) là một chuỗi các hidden-states tại đầu ra của lớp cuối cùng của encoder. Được sử dụng trong cross-attention của decoder.

past_key_values (`~cache_utils.Cache`, *tùy chọn*) : Các hidden-states đã tính trước (key và values trong các khối self-attention và cross-attention) có thể được sử dụng để tăng tốc giải mã tuần tự. Điều này thường bao gồm `past_key_values` do mô hình trả về ở một giai đoạn giải mã trước đó, khi `use_cache=True` hoặc `config.use_cache=True`.  Chỉ cho phép [Cache](/docs/transformers/main/vi/internal/generation_utils#transformers.Cache) instance làm đầu vào, xem [hướng dẫn kv cache](https://huggingface.co/docs/transformers/en/kv_cache) của chúng tôi. Nếu không truyền `past_key_values`, [DynamicCache](/docs/transformers/main/vi/internal/generation_utils#transformers.DynamicCache) sẽ được khởi tạo theo mặc định.  Mô hình sẽ xuất ra cùng định dạng cache được đưa vào làm đầu vào.  Nếu sử dụng `past_key_values`, người dùng được kỳ vọng chỉ nhập các `input_ids` chưa được xử lý (những phần chưa có trạng thái key value quá khứ được cung cấp cho mô hình này) có shape `(batch_size, unprocessed_length)` thay vì tất cả `input_ids` có shape `(batch_size, sequence_length)`.

decoder_inputs_embeds (`torch.Tensor` có shape `(batch_size, target_sequence_length, hidden_size)`, *tùy chọn*) : Tùy chọn, thay vì truyền `decoder_input_ids`, bạn có thể chọn truyền trực tiếp một biểu diễn nhúng. Nếu `past_key_values` được sử dụng, tùy chọn chỉ cần nhập `decoder_inputs_embeds` cuối cùng (xem `past_key_values`). Điều này hữu ích nếu bạn muốn kiểm soát nhiều hơn cách chuyển đổi các chỉ số `decoder_input_ids` thành các vector liên quan so với ma trận tra cứu nhúng nội bộ của mô hình. Nếu cả `decoder_input_ids` và `decoder_inputs_embeds` đều không được đặt, `decoder_inputs_embeds` sẽ nhận giá trị của `inputs_embeds`.

use_cache (`bool`, *tùy chọn*) : Nếu được đặt thành `True`, các trạng thái khóa và giá trị `past_key_values` sẽ được trả về và có thể được sử dụng để tăng tốc quá trình giải mã (xem `past_key_values`).

**Trả về:** [Seq2SeqModelOutput](/docs/transformers/main/vi/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) hoặc `tuple(torch.Tensor)`

Một [Seq2SeqModelOutput](/docs/transformers/main/vi/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các thành phần khác nhau tùy thuộc vào cấu hình ([UdopConfig](/docs/transformers/main/vi/model_doc/udop#transformers.UdopConfig)) và đầu vào.

Phương thức forward của [UdopModel](/docs/transformers/main/vi/model_doc/udop#transformers.UdopModel) ghi đè lên phương thức đặc biệt `__call__`.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, bạn nên gọi instance của `Module` sau đó thay vì gọi hàm này, vì instance `Module` sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ bỏ qua chúng một cách im lặng.

- **last_hidden_state** (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`) -- Chuỗi các trạng thái ẩn (hidden-states) tại đầu ra của lớp cuối cùng của bộ giải mã (decoder) của mô hình.

  Nếu `past_key_values` được sử dụng, chỉ có hidden-state cuối cùng của các chuỗi có shape `(batch_size, 1, hidden_size)` được xuất ra.
- **past_key_values** (`EncoderDecoderCache`, *tùy chọn*, được trả về khi `use_cache=True` được truyền vào hoặc khi `config.use_cache=True`) -- Đây là một instance của [EncoderDecoderCache](/docs/transformers/main/vi/internal/generation_utils#transformers.EncoderDecoderCache). Để biết thêm chi tiết, hãy xem [hướng dẫn về kv cache](https://huggingface.co/docs/transformers/en/kv_cache) của chúng tôi.

  Chứa các hidden-states đã được tính trước (key và values trong các khối self-attention và trong các khối cross-attention) có thể được sử dụng (xem đầu vào `past_key_values`) để tăng tốc độ giải mã tuần tự.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_hidden_states=True` được truyền vào hoặc khi `config.output_hidden_states=True`) -- Bộ tuple của `torch.Tensor` (một cho đầu ra của các embedding, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng `(batch_size, sequence_length, hidden_size)`.

  Trạng thái ẩn của bộ giải mã tại đầu ra của mỗi lớp cùng với các đầu ra nhúng ban đầu tùy chọn.
- **decoder_attentions** (`tuple(torch.Tensor)`, *tùy chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý của bộ giải mã, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý tự (self-attention).
- **cross_attentions** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý của lớp cross-attention của bộ giải mã, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý chéo.
- **encoder_last_hidden_state** (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) -- Chuỗi các trạng thái ẩn tại đầu ra của lớp cuối cùng của bộ mã hóa trong mô hình.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_hidden_states=True` được truyền vào hoặc khi `config.output_hidden_states=True`) -- Bộ tuple các `torch.Tensor` (một cho đầu ra của các embedding, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng `(batch_size, sequence_length, hidden_size)`.

  Trạng thái ẩn của bộ mã hóa tại đầu ra của mỗi lớp cùng với các đầu ra nhúng ban đầu tùy chọn.
- **encoder_attentions** (`tuple(torch.Tensor)`, *tùy chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý của bộ mã hóa, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý tự thân.

Ví dụ:

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

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

**Tham số:**

config ([UdopConfig](/docs/transformers/main/vi/model_doc/udop#transformers.UdopConfig)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số của mô hình.

Transformer encoder-decoder UDOP với đầu mô hình hóa ngôn ngữ ở trên, cho phép tạo văn bản dựa trên hình ảnh tài liệu và một prompt tùy chọn.

Lớp này dựa trên [T5ForConditionalGeneration](/docs/transformers/main/vi/model_doc/t5#transformers.T5ForConditionalGeneration), được mở rộng để xử lý dữ liệu hình ảnh và bố cục (2D).

Mô hình này kế thừa từ [PreTrainedModel](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu ra, v.v.)

Mô hình này cũng là một lớp con của [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.

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

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

**Tham số:**

input_ids (`torch.Tensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Chỉ số của các token trong chuỗi đầu vào theo từ vựng. Mặc định, các token đệm (padding) sẽ bị bỏ qua. Có thể lấy chỉ số bằng cách sử dụng [AutoTokenizer](/docs/transformers/main/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) để biết thêm chi tiết. [ID đầu vào là gì?](../glossary#input-ids)

attention_mask (`torch.Tensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Mặt nạ để tránh thực hiện chú ý trên các chỉ số token đệm. Các giá trị mặt nạ được chọn trong `[0, 1]`:  - 1 cho các token **không bị che**, - 0 cho các token **bị che**.  [Mặt nạ chú ý là gì?](../glossary#attention-mask)

bbox (`torch.LongTensor` có shape `({0}, 4)`, *tùy chọn*) : Các bounding box của các token trong mỗi chuỗi đầu vào. Được chọn trong khoảng `[0, config.max_2d_position_embeddings-1]`. Mỗi bounding box phải là phiên bản đã chuẩn hóa ở định dạng (x0, y0, x1, y1), trong đó (x0, y0) tương ứng với vị trí góc trên bên trái của bounding box, và (x1, y1) đại diện cho vị trí góc dưới bên phải. Lưu ý rằng `sequence_length = token_sequence_length + patch_sequence_length + 1` trong đó `1` là cho token [CLS]. Xem `pixel_values` để biết về `patch_sequence_length`.

pixel_values (`torch.Tensor` có shape `(batch_size, num_channels, image_size, image_size)`, *tùy chọn*) : Các tensor tương ứng với các ảnh đầu vào. Giá trị pixel có thể được lấy bằng cách sử dụng [LayoutLMv3ImageProcessor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor). Xem [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/main/vi/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) để biết chi tiết ([UdopProcessor](/docs/transformers/main/vi/model_doc/udop#transformers.UdopProcessor) sử dụng [LayoutLMv3ImageProcessor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) để xử lý ảnh).

visual_bbox (`torch.LongTensor` có shape `(batch_size, patch_sequence_length, 4)`, *tùy chọn*) : Các bounding box của từng patch trong ảnh. Nếu không được cung cấp, các bounding box sẽ được tạo trong model.

decoder_input_ids (`torch.LongTensor` có shape `(batch_size, target_sequence_length)`, *tùy chọn*) : Chỉ số của các token trong chuỗi đầu vào bộ giải mã trong từ vựng. Các chỉ số có thể được lấy bằng cách sử dụng [AutoTokenizer](/docs/transformers/main/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) để biết chi tiết. [Các ID đầu vào bộ giải mã là gì?](../glossary#decoder-input-ids) T5 sử dụng `pad_token_id` làm token bắt đầu cho việc tạo `decoder_input_ids`. Nếu `past_key_values` được sử dụng, tùy chọn chỉ cần nhập `decoder_input_ids` cuối cùng (xem `past_key_values`). Để biết thêm về cách chuẩn bị `decoder_input_ids` cho huấn luyện trước, hãy xem [T5 Training](./t5#training).

decoder_attention_mask (`torch.BoolTensor` có shape `(batch_size, target_sequence_length)`, *tùy chọn*) : Hành vi mặc định: tạo một tensor bỏ qua các token pad trong `decoder_input_ids`. Causal mask cũng sẽ được sử dụng theo mặc định.

inputs_embeds (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) : Tùy chọn, thay vì truyền `input_ids`, bạn có thể chọn cách truyền trực tiếp một biểu diễn nhúng. Điều này hữu ích nếu bạn muốn kiểm soát nhiều hơn cách chuyển đổi các chỉ số `input_ids` thành các vector liên quan so với ma trận tra cứu nhúng nội bộ của mô hình.

encoder_outputs (`torch.Tensor`, *tùy chọn*) : Tuple gồm (`last_hidden_state`, *tùy chọn*: `hidden_states`, *tùy chọn*: `attentions`) `last_hidden_state` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) là một chuỗi các hidden-states tại đầu ra của lớp cuối cùng của encoder. Được sử dụng trong cross-attention của decoder.

past_key_values (`~cache_utils.Cache`, *tùy chọn*) : Các hidden-states đã tính trước (key và values trong các khối self-attention và cross-attention) có thể được sử dụng để tăng tốc giải mã tuần tự. Điều này thường bao gồm `past_key_values` do mô hình trả về ở một giai đoạn giải mã trước đó, khi `use_cache=True` hoặc `config.use_cache=True`.  Chỉ cho phép [Cache](/docs/transformers/main/vi/internal/generation_utils#transformers.Cache) instance làm đầu vào, xem [hướng dẫn kv cache](https://huggingface.co/docs/transformers/en/kv_cache) của chúng tôi. Nếu không truyền `past_key_values`, [DynamicCache](/docs/transformers/main/vi/internal/generation_utils#transformers.DynamicCache) sẽ được khởi tạo theo mặc định.  Mô hình sẽ xuất ra cùng định dạng cache được đưa vào làm đầu vào.  Nếu sử dụng `past_key_values`, người dùng được kỳ vọng chỉ nhập các `input_ids` chưa được xử lý (những phần chưa có trạng thái key value quá khứ được cung cấp cho mô hình này) có shape `(batch_size, unprocessed_length)` thay vì tất cả `input_ids` có shape `(batch_size, sequence_length)`.

decoder_inputs_embeds (`torch.Tensor` có shape `(batch_size, target_sequence_length, hidden_size)`, *tùy chọn*) : Tùy chọn, thay vì truyền `decoder_input_ids`, bạn có thể chọn truyền trực tiếp một biểu diễn nhúng. Nếu `past_key_values` được sử dụng, tùy chọn chỉ cần nhập `decoder_inputs_embeds` cuối cùng (xem `past_key_values`). Điều này hữu ích nếu bạn muốn kiểm soát nhiều hơn cách chuyển đổi các chỉ số `decoder_input_ids` thành các vector liên quan so với ma trận tra cứu nhúng nội bộ của mô hình. Nếu cả `decoder_input_ids` và `decoder_inputs_embeds` đều không được đặt, `decoder_inputs_embeds` sẽ nhận giá trị của `inputs_embeds`.

use_cache (`bool`, *tùy chọn*) : Nếu được đặt thành `True`, các trạng thái khóa và giá trị `past_key_values` sẽ được trả về và có thể được sử dụng để tăng tốc quá trình giải mã (xem `past_key_values`).

labels (`torch.LongTensor` có hình dạng `(batch_size,)`, *tùy chọn*) : Nhãn để tính toán tổn thất mô hình hóa ngôn ngữ. Chỉ số phải nằm trong `[-100, 0, ..., config.vocab_size - 1]`. Tất cả các nhãn được đặt thành `-100` sẽ bị bỏ qua (che), tổn thất chỉ được tính cho các nhãn trong `[0, ..., config.vocab_size]`.

**Trả về:** [Seq2SeqLMOutput](/docs/transformers/main/vi/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) hoặc `tuple(torch.Tensor)`

Một [Seq2SeqLMOutput](/docs/transformers/main/vi/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các phần tử khác nhau tùy thuộc vào cấu hình ([UdopConfig](/docs/transformers/main/vi/model_doc/udop#transformers.UdopConfig)) và đầu vào.

Phương thức forward của [UdopForConditionalGeneration](/docs/transformers/main/vi/model_doc/udop#transformers.UdopForConditionalGeneration) ghi đè lên phương thức đặc biệt `__call__`.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, bạn nên gọi instance của `Module` sau đó thay vì gọi hàm này, vì instance `Module` sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ bỏ qua chúng một cách im lặng.

- **loss** (`torch.Tensor` có shape `(1,)`, *tuỳ chọn*, được trả về khi `labels` được cung cấp) -- Loss của language modeling.
- **logits** (`torch.Tensor` có hình dạng `(batch_size, sequence_length, config.vocab_size)`) -- Điểm dự đoán của đầu mô hình hóa ngôn ngữ (điểm cho mỗi token từ vựng trước SoftMax).
- **past_key_values** (`EncoderDecoderCache`, *tùy chọn*, được trả về khi `use_cache=True` được truyền vào hoặc khi `config.use_cache=True`) -- Đây là một instance của [EncoderDecoderCache](/docs/transformers/main/vi/internal/generation_utils#transformers.EncoderDecoderCache). Để biết thêm chi tiết, hãy xem [hướng dẫn về kv cache](https://huggingface.co/docs/transformers/en/kv_cache) của chúng tôi.

  Chứa các hidden-states đã được tính trước (key và values trong các khối self-attention và trong các khối cross-attention) có thể được sử dụng (xem đầu vào `past_key_values`) để tăng tốc độ giải mã tuần tự.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_hidden_states=True` được truyền vào hoặc khi `config.output_hidden_states=True`) -- Bộ tuple của `torch.Tensor` (một cho đầu ra của các embedding, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng `(batch_size, sequence_length, hidden_size)`.

  Trạng thái ẩn của bộ giải mã tại đầu ra của mỗi lớp cùng với đầu ra của nhúng ban đầu.
- **decoder_attentions** (`tuple(torch.Tensor)`, *tùy chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý của bộ giải mã, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý tự (self-attention).
- **cross_attentions** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý của lớp cross-attention của bộ giải mã, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý chéo.
- **encoder_last_hidden_state** (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) -- Chuỗi các trạng thái ẩn tại đầu ra của lớp cuối cùng của bộ mã hóa trong mô hình.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_hidden_states=True` được truyền vào hoặc khi `config.output_hidden_states=True`) -- Bộ tuple các `torch.Tensor` (một cho đầu ra của các embedding, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng `(batch_size, sequence_length, hidden_size)`.

  Trạng thái ẩn của bộ mã hóa tại đầu ra của mỗi lớp cùng với đầu ra của nhúng ban đầu.
- **encoder_attentions** (`tuple(torch.Tensor)`, *tùy chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý của bộ mã hóa, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý tự thân.

Ví dụ:

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

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

**Tham số:**

config ([UdopConfig](/docs/transformers/main/vi/model_doc/udop#transformers.UdopConfig)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số của mô hình.

Mô hình Udop cơ bản, xuất ra các hidden-state thô mà không có bất kỳ head cụ thể nào ở phía trên.

Mô hình này kế thừa từ [PreTrainedModel](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu ra, v.v.)

Mô hình này cũng là một lớp con của [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.

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

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

**Tham số:**

input_ids (`torch.LongTensor` có shape `(batch_size, sequence_length)`) : Chỉ số của các token trong chuỗi đầu vào theo từ điển. T5 là mô hình có position embeddings tương đối nên bạn có thể pad đầu vào ở cả bên phải và bên trái.  Các chỉ số có thể được lấy bằng [AutoTokenizer](/docs/transformers/main/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) để biết chi tiết.  Để tìm hiểu thêm về cách chuẩn bị `input_ids` cho pretraining, hãy xem [T5 Training](./t5#training).

bbox (`torch.LongTensor` có shape `({0}, 4)`, *tùy chọn*) : Các bounding box của các token trong mỗi chuỗi đầu vào. Được chọn trong khoảng `[0, config.max_2d_position_embeddings-1]`. Mỗi bounding box phải là phiên bản đã chuẩn hóa ở định dạng (x0, y0, x1, y1), trong đó (x0, y0) tương ứng với vị trí góc trên bên trái của bounding box, và (x1, y1) đại diện cho vị trí góc dưới bên phải. Lưu ý rằng `sequence_length = token_sequence_length + patch_sequence_length + 1` trong đó `1` là cho token [CLS]. Xem `pixel_values` để biết về `patch_sequence_length`.

attention_mask (`torch.Tensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Mặt nạ để tránh thực hiện chú ý trên các chỉ số token đệm. Các giá trị mặt nạ được chọn trong `[0, 1]`:  - 1 cho các token **không bị che**, - 0 cho các token **bị che**.  [Mặt nạ chú ý là gì?](../glossary#attention-mask)

pixel_values (`torch.Tensor` có shape `(batch_size, num_channels, image_size, image_size)`, *tùy chọn*) : Các tensor tương ứng với các ảnh đầu vào. Giá trị pixel có thể được lấy bằng cách sử dụng [LayoutLMv3ImageProcessor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor). Xem [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/main/vi/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) để biết chi tiết ([UdopProcessor](/docs/transformers/main/vi/model_doc/udop#transformers.UdopProcessor) sử dụng [LayoutLMv3ImageProcessor](/docs/transformers/main/vi/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) để xử lý ảnh).

visual_bbox (`torch.LongTensor` có shape `(batch_size, patch_sequence_length, 4)`, *tùy chọn*) : Các bounding box của từng patch trong ảnh. Nếu không được cung cấp, các bounding box sẽ được tạo trong model.

inputs_embeds (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) : Tùy chọn, thay vì truyền `input_ids`, bạn có thể chọn cách truyền trực tiếp một biểu diễn nhúng. Điều này hữu ích nếu bạn muốn kiểm soát nhiều hơn cách chuyển đổi các chỉ số `input_ids` thành các vector liên quan so với ma trận tra cứu nhúng nội bộ của mô hình.

**Trả về:** `BaseModelOutputWithAttentionMask` hoặc `tuple(torch.Tensor)`

Một `BaseModelOutputWithAttentionMask` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền vào hoặc khi `config.return_dict=False`) bao gồm các thành phần khác nhau tùy thuộc vào cấu hình ([UdopConfig](/docs/transformers/main/vi/model_doc/udop#transformers.UdopConfig)) và đầu vào.

Phương thức forward của [UdopEncoderModel](/docs/transformers/main/vi/model_doc/udop#transformers.UdopEncoderModel) ghi đè lên phương thức đặc biệt `__call__`.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, bạn nên gọi instance của `Module` sau đó thay vì gọi hàm này, vì instance `Module` sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ bỏ qua chúng một cách im lặng.

- **last_hidden_state** (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`) -- Chuỗi các hidden-state tại đầu ra của lớp cuối cùng của mô hình. Nếu `past_key_values` được sử dụng, chỉ có hidden-state cuối cùng của các chuỗi với hình dạng `(batch_size, 1, hidden_size)` được đưa ra.
- **attention_mask** (`torch.Tensor` có shape `(batch_size, sequence_length)`, *tùy chọn*) -- Mặt nạ chú ý (attention mask) được sử dụng trong bước forward của mô hình để tránh thực hiện chú ý trên các chỉ số token đệm (padding). Các giá trị mặt nạ được chọn trong `[0, 1]`:
  - 1 cho các token **không bị che**,
  - 0 cho các token bị **che**.
- **past_key_values** (`Cache`, *tùy chọn*, được trả về khi `use_cache=True` được truyền vào hoặc khi `config.use_cache=True`) -- Đây là một instance của [Cache](/docs/transformers/main/vi/internal/generation_utils#transformers.Cache). Để biết thêm chi tiết, hãy xem [hướng dẫn về kv cache](https://huggingface.co/docs/transformers/en/kv_cache) của chúng tôi.

  Chứa các hidden-states đã được tính trước (key và values trong các khối self-attention và tùy chọn nếu `config.is_encoder_decoder=True` trong các khối cross-attention) có thể được sử dụng (xem đầu vào `past_key_values`) để tăng tốc độ giải mã tuần tự.
- **hidden_states** (`tuple(torch.Tensor)`, *tùy chọn*, được trả về khi truyền `output_hidden_states=True` hoặc khi `config.output_hidden_states=True`) -- Tuple của `torch.Tensor` (một tensor cho đầu ra của embeddings, nếu model có lớp embedding, + một tensor cho đầu ra của mỗi lớp) có shape `(batch_size, sequence_length, hidden_size)`. Hidden-states của model tại đầu ra của mỗi lớp cùng với đầu ra embedding ban đầu tùy chọn.
- **attentions** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi truyền `output_attentions=True` hoặc khi `config.output_attentions=True`) -- Bộ tuple các `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`. Trọng số chú ý sau softmax của attention, được dùng để tính trung bình có trọng số trong các đầu self-attention.
- **cross_attentions** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi truyền `output_attentions=True` và `config.add_cross_attention=True` hoặc khi `config.output_attentions=True`) -- Bộ tuple các `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`. Trọng số chú ý của lớp cross-attention trong decoder, sau softmax chú ý, được dùng để tính trung bình có trọng số trong các đầu chú ý cross-attention.

Ví dụ:

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