# 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 采用基于 [T5](t5) 的编码器-解码器 Transformer 架构，用于文档图像分类、文档解析和文档视觉问答等文档 AI 任务。 该论文的摘要如下： 我们提出了通用文档处理（UDOP），这是一个基础文档 AI 模型，它将文本、图像和布局模态与多种任务格式（包括文档理解和生成）统一起来。UDOP 利用文本内容与文档图像之间的空间相关性，使用一种统一的表示来建模图像、文本和布局模态。借助新颖的视觉-文本-布局 Transformer，UDOP 将预训练和多领域下游任务统一到一个基于提示的序列生成方案中。UDOP 在大规模无标签文档语料库上使用创新的自监督目标进行预训练，同时也使用了多样化的有标签数据。此外，UDOP 还通过掩码图像重建学习从文本和布局模态生成文档图像。据我们所知，这是文档 AI 领域首次由单一模型同时实现高质量的神经文档编辑和内容定制。我们的方法在 9 个文档 AI 任务上达到了最先进水平，例如文档理解和问答，涵盖了财务报告、学术论文和网站等多种数据领域。UDOP 在文档理解基准（DUE）的排行榜上位列第一。* drawing UDOP 架构。摘自原始论文。 ## 使用技巧 - 除了 *input_ids* 之外，[UdopForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopForConditionalGeneration) 还期望输入 `bbox`，即输入标记的边界框（即二维位置）。这些可以通过外部 OCR 引擎（例如 Google 的 [Tesseract](https://github.com/tesseract-ocr/tesseract)，有可用的 [Python 封装](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` 对应于该 token 所在原始文档的宽度和高度。例如，可以使用 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/v5.23.0/zh/model_doc/udop#transformers.UdopProcessor) 为模型准备图像和文本，该类会处理所有这些工作。默认情况下，此类使用 Tesseract 引擎从给定文档中提取单词和边界框（坐标）列表。其功能与 [LayoutLMv3Processor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3Processor) 等效，因此支持传入 `apply_ocr=False`（如果您希望使用自己的 OCR 引擎）或 `apply_ocr=True`（如果您希望使用默认 OCR 引擎）。有关所有可能的使用场景，请参阅 [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/v5.23.0/zh/model_doc/udop#transformers.UdopEncoderModel) 进行微调，它是 UDOP 中仅包含编码器的部分，可以被视为一种类似于 LayoutLMv3 的 Transformer 编码器。对于判别式任务，只需在其上方添加一个线性分类器，并在带标签的数据集上进行微调即可。 该模型由 [nielsr](https://huggingface.co/nielsr) 贡献。原始代码可在[此处](https://github.com/microsoft/UDOP)找到。 ## 资源 以下是 Hugging Face 官方和社区（以 🌎 标识）提供的资源列表，旨在帮助您入门 UDOP。如果您有兴趣提交资源以收录于此，请随时发起 Pull Request，我们将进行审核！理想情况下，该资源应展示一些新内容，而非重复现有资源。 - 有关 UDOP 的演示笔记本可在[此处](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UDOP)找到，其中展示了如何 to fine-tune UDOP on a custom dataset as well as inference. 🌎 - [文档问答任务指南](../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/v5.23.0/src/transformers/models/udop/configuration_udop.py#L24) **参数：** is_encoder_decoder (`bool`，*可选*，默认为 `True`)：模型是否用作编码器/解码器。 vocab_size (`int`，*可选*，默认为 `33201`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。 d_model (`int`，*可选*，默认为 `1024`)：编码器层和池化层的大小。 d_kv (`int`, *可选*，默认为 `64`)：每个注意力头中键、查询和值投影的大小。投影层的 `inner_dim` 将定义为 `num_heads * d_kv`。 d_ff (`int`，*可选*，默认为 `4096`)：MLP 表示的维度。 num_layers (`int`，*可选*，默认为 `24`)：Transformer 解码器中的隐藏层数。 num_decoder_layers (`int`, *可选*) : Transformer 解码器中的隐藏层数。如果未设置，将使用与 `num_layers` 相同的值。 num_heads (`int`，*可选*，默认为 `16`)：Transformer 解码器中每个注意力层的注意力头数量。 relative_attention_num_buckets (`int`，*可选*，默认为 32)：每个注意力层使用的桶数。 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"`)：要使用的前馈层类型。应为 `"relu"` 或 `"gated-gelu"` 之一。Udopv1.1 使用 `"gated-gelu"` 前馈投影。原始 Udop 使用 `"relu"`。 use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。 pad_token_id (`int`，*可选*，默认为 `0`)：词表中用于填充的 Token ID。 eos_token_id (`Union[int, list[int]]`，*可选*，默认为 `1`)：词汇表中用于表示流结束（end-of-stream）的 Token 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`)：每个 patch 的大小（分辨率）。 num_channels (`int`，*可选*，默认为 `3`)：输入通道数。 is_decoder (`bool`，*可选*，默认为 `False`)：模型是否用作解码器。如果为 `False`，则模型用作编码器。 add_cross_attention (`bool`，*可选*，默认为 `False`)：是否应在模型中添加交叉注意力层。 tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。 这是用于存储 UdopModel 配置的类。它根据指定的参数实例化 Udop 模型，并定义模型架构。使用默认值实例化配置将生成与 [microsoft/udop-large](https://huggingface.co/microsoft/udop-large) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/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 = '', sep_token = '', unk_token = '', pad_token = '', 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/v5.23.0/src/transformers/models/udop/tokenization_udop.py#L139) **参数：** eos_token (`str`, *可选*, 默认为 `""`) : 序列结束标记。 在使用特殊标记构建序列时，序列结束使用的标记并非此标记，而是 `sep_token`。 sep_token (`str`，*可选*，默认为 `""`)：分隔符标记，用于从多个序列构建序列时，例如用于序列分类的两个序列，或用于问答的文本和问题。它也用作使用特殊标记构建的序列的最后一个标记。 unk_token (`str`，*可选*，默认为 `""`)：未知标记。不在词汇表中的标记无法转换为 ID，因此会被设置为该标记。 pad_token (`str`，*可选*，默认为 `""`)：用于填充的标记，例如在对长度不同的序列进行批处理时。 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]`，*可选*，默认为 `["NOTUSED", "NOTUSED"]`)：分词器使用的额外特殊标记。 构建一个“快速”的 UDOP 分词器（由 HuggingFace 的 *tokenizers* 库提供支持）。改编自 [LayoutXLMTokenizer](/docs/transformers/v5.23.0/zh/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) 和 [T5Tokenizer](/docs/transformers/v5.23.0/zh/model_doc/t5#transformers.T5Tokenizer)。基于 [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models)。 该分词器继承自 [TokenizersBackend](/docs/transformers/v5.23.0/zh/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[int], token_ids_1: list[int] | None = None) ``` [来源](https://github.com/huggingface/transformers/blob/v5.23.0/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 序列的格式如下： - 单条序列：` X ` - 序列对：` A B ` #### 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/v5.23.0/src/transformers/tokenization_utils_base.py#L1337) **参数：** token_ids_0 : （可能已格式化的）序列的 ID 列表。 token_ids_1 : 当 `already_has_special_tokens=True` 时未使用。在这种情况下，必须为 None。 already_has_special_tokens : 序列是否已使用特殊标记进行格式化。 **返回：** 一个包含 [0, 1] 范围内整数的列表 1 表示特殊标记，0 表示序列标记。 从未添加特殊标记的标记列表中检索序列 ID。 对于快速分词器，数据整理器会传入 `already_has_special_tokens=True` 来调用此方法，以在已格式化的序列上构建掩码。在这种情况下，我们通过检查元素是否属于 `all_special_ids` 来计算掩码。 #### create_token_type_ids_from_sequences[[transformers.UdopTokenizer.create_token_type_ids_from_sequences]] ```python create_token_type_ids_from_sequences(token_ids_0: list[int], token_ids_1: list[int] | None = None) ``` [来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/udop/tokenization_udop.py#L997) **参数：** token_ids_0 (`list[int]`) : ID 列表。 token_ids_1 (`list[int]`, *可选*) : 用于序列对的可选第二个 ID 列表。 **返回：** `list[int]` 零列表。 根据传入的两个序列创建掩码，用于序列对分类任务。XLM-RoBERTa 不使用 token type ids，因此返回一个全零列表。 #### save_vocabulary[[transformers.UdopTokenizer.save_vocabulary]] ```python save_vocabulary(save_directory: str, filename_prefix: str | None = None) ``` [来源](https://github.com/huggingface/transformers/blob/v5.23.0/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/v5.23.0/src/transformers/models/udop/processing_udop.py#L50) **参数：** image_processor (`LayoutLMv3ImageProcessor`)：图像处理器是必需的输入。 tokenizer (`UdopTokenizer`)：分词器是必需的输入。 构建一个 UdopProcessor，它将图像处理器和分词器封装为单一处理器。 [UdopProcessor](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopProcessor) 提供了 [LayoutLMv3ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) 和 [UdopTokenizer](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopTokenizer) 的所有功能。有关更多信息，请参阅 [~LayoutLMv3ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) 和 [~UdopTokenizer](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopTokenizer)。 #### __调用__[[transformers.UdopProcessor.__call__]] ```python __call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text: str | list[str] | list[list[str]] = None, boxes: list[list[int]] | list[list[list[int]]] | None = None, word_labels: list[int] | list[list[int]] | None = None, **kwargs: *) ``` [来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/udop/processing_udop.py#L73) **参数：** 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` 以避免与批量输入产生歧义。 boxes (`list[list[int]]`, `list[list[list[int]]]`, *可选*) : 归一化到 [0, 1000] 范围内的词级边界框。 word_labels (`list[int]`, `list[list[int]]`, *可选*) : 用于 token 分类任务的词级整数标签。 return_mm_token_type_ids (`bool`, *kwargs*) : 是否返回多模态 token 类型 ID，以指示多模态占位符 token 的位置。 return_text_replacement_offsets (`bool`, *kwargs*) : 是否返回每个多模态占位符及其替换项的字符偏移量。 return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。 - ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/zh/main_classes/processors#transformers.ProcessingKwargs), *可选*) : 针对每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。 **返回：** `~image_processing_base.BatchFeature` - **data** (`dict`) -- 由 __call__ 方法返回的列表/数组/张量字典（例如 'pixel_values'）。 - **tensor_type** (`Union[None, str, TensorType]`，*可选*) -- 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。 ## UdopModel[[transformers.UdopModel]] #### transformers.UdopModel[[transformers.UdopModel]] ```python transformers.UdopModel(config: UdopConfig) ``` [来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/udop/modeling_udop.py#L1251) **参数：** config ([UdopConfig](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。 未添加任何特定头部的裸 Udop 模型，直接输出原始隐藏状态。 该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/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: *) ``` [来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/udop/modeling_udop.py#L1287) **参数：** input_ids (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中各个 token 在词汇表中的索引。默认情况下，填充（padding）会被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取这些索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids) attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask) bbox (`torch.LongTensor`，形状为 `({0}, 4)`，*可选*) : 每个输入序列中各个 token 的边界框。取值范围为 `[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] token。有关 `patch_sequence_length` 的信息，请参阅 `pixel_values`。 pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*)：与输入图像对应的张量。可以使用 [LayoutLMv3ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) 获取像素值。有关详细信息，请参阅 [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（[UdopProcessor](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopProcessor) 使用 [LayoutLMv3ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) 处理图像）。 visual_bbox (`torch.LongTensor`，形状为 `(batch_size, patch_sequence_length, 4)`，*可选*)：图像中每个 patch 的边界框。如果未提供，边界框将在模型中创建。 decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*) : 解码器输入序列中词元在词汇表中的索引。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取这些索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是解码器输入 ID？](../glossary#decoder-input-ids) T5 使用 `pad_token_id` 作为 `decoder_input_ids` 生成的起始词元。如果使用 `past_key_values`，则只需输入最后几个 `decoder_input_ids`（参见 `past_key_values`）。要了解如何为预训练准备 `decoder_input_ids`，请参阅 [T5 Training](./t5#training)。 decoder_attention_mask (`torch.BoolTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*) : 默认行为：生成一个忽略 `decoder_input_ids` 中填充标记的张量。默认情况下也会使用因果掩码。 inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。 encoder_outputs (`torch.Tensor`, *可选*) : 由 (`last_hidden_state`, *可选*: `hidden_states`, *可选*: `attentions`) `last_hidden_state` 形状为 `(batch_size, sequence_length, hidden_size)`, *可选*) 组成的元组，是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力。 past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。 decoder_inputs_embeds (`torch.Tensor`，形状为 `(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/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) 或 `tuple(torch.Tensor)` 一个 [Seq2SeqModelOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[UdopConfig](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopConfig)）和输入。 [UdopModel](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopModel) 的 forward 方法重写了 `__call__` 特殊方法。 尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。 - **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型解码器最后一层输出的隐藏状态序列。 如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。 - **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。 包含预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。 - **decoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。 解码器在每一层输出处的隐藏状态，以及可选的初始嵌入输出。 - **decoder_attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。 解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。 - **cross_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。 解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。 - **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。 - **encoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。 编码器每层输出处的隐藏状态，以及可选的初始嵌入输出。 - **encoder_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。 编码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。 示例： ```python >>> from 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/v5.23.0/src/transformers/models/udop/modeling_udop.py#L1405) **参数：** config ([UdopConfig](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。 UDOP 编码器-解码器 Transformer，顶部配有语言建模头，能够根据文档图像和可选的提示词生成文本。 该类基于 [T5ForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/t5#transformers.T5ForConditionalGeneration)，并进行了扩展以处理图像和布局（2D）数据。 该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/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: *) ``` [来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/udop/modeling_udop.py#L1447) **参数：** input_ids (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中各个 token 在词汇表中的索引。默认情况下，填充（padding）会被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取这些索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids) attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask) bbox (`torch.LongTensor`，形状为 `({0}, 4)`，*可选*) : 每个输入序列中各个 token 的边界框。取值范围为 `[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] token。有关 `patch_sequence_length` 的信息，请参阅 `pixel_values`。 pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*)：与输入图像对应的张量。可以使用 [LayoutLMv3ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) 获取像素值。有关详细信息，请参阅 [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（[UdopProcessor](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopProcessor) 使用 [LayoutLMv3ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) 处理图像）。 visual_bbox (`torch.LongTensor`，形状为 `(batch_size, patch_sequence_length, 4)`，*可选*)：图像中每个 patch 的边界框。如果未提供，边界框将在模型中创建。 decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*) : 解码器输入序列中词元在词汇表中的索引。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取这些索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是解码器输入 ID？](../glossary#decoder-input-ids) T5 使用 `pad_token_id` 作为 `decoder_input_ids` 生成的起始词元。如果使用 `past_key_values`，则只需输入最后几个 `decoder_input_ids`（参见 `past_key_values`）。要了解如何为预训练准备 `decoder_input_ids`，请参阅 [T5 Training](./t5#training)。 decoder_attention_mask (`torch.BoolTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*) : 默认行为：生成一个忽略 `decoder_input_ids` 中填充标记的张量。默认情况下也会使用因果掩码。 inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。 encoder_outputs (`torch.Tensor`, *可选*) : 由 (`last_hidden_state`, *可选*: `hidden_states`, *可选*: `attentions`) `last_hidden_state` 形状为 `(batch_size, sequence_length, hidden_size)`, *可选*) 组成的元组，是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力。 past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。 decoder_inputs_embeds (`torch.Tensor`，形状为 `(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`，形状为 `(batch_size,)`，*可选*)：用于计算语言建模损失的标签。索引应在 `[-100, 0, ..., config.vocab_size - 1]` 范围内。所有设置为 `-100` 的标签都会被忽略（被掩码），损失仅针对 `[0, ..., config.vocab_size]` 范围内的标签进行计算。 **返回：** [Seq2SeqLMOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 或 `tuple(torch.Tensor)` 一个 [Seq2SeqLMOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[UdopConfig](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopConfig)）和输入。 [UdopForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopForConditionalGeneration) 的 forward 方法重写了 `__call__` 特殊方法。 尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。 - **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，在提供 `labels` 时返回) -- 语言建模损失。 - **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。 - **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。 包含预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。 - **decoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。 解码器在每一层输出处的隐藏状态，以及初始嵌入输出。 - **decoder_attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。 解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。 - **cross_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。 解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。 - **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。 - **encoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。 编码器在每一层输出处的隐藏状态，以及初始嵌入输出。 - **encoder_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。 编码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。 示例： ```python >>> from 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/v5.23.0/src/transformers/models/udop/modeling_udop.py#L1579) **参数：** config ([UdopConfig](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。 未添加任何特定头部的裸 Udop 模型，直接输出原始隐藏状态。 该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/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: *) ``` [来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/udop/modeling_udop.py#L1610) **参数：** input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`)：输入序列词元在词汇表中的索引。T5 是一个具有相对位置嵌入的模型，因此您可以在输入的右侧和左侧进行填充。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。要了解如何为预训练准备 `input_ids`，请查看 [T5 Training](./t5#training)。 bbox (`torch.LongTensor`，形状为 `({0}, 4)`，*可选*) : 每个输入序列中各个 token 的边界框。取值范围为 `[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] token。有关 `patch_sequence_length` 的信息，请参阅 `pixel_values`。 attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask) pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*)：与输入图像对应的张量。可以使用 [LayoutLMv3ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) 获取像素值。有关详细信息，请参阅 [LayoutLMv3ImageProcessor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（[UdopProcessor](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopProcessor) 使用 [LayoutLMv3ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv3#transformers.LayoutLMv3ImageProcessor) 处理图像）。 visual_bbox (`torch.LongTensor`，形状为 `(batch_size, patch_sequence_length, 4)`，*可选*)：图像中每个 patch 的边界框。如果未提供，边界框将在模型中创建。 inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。 **返回：** `BaseModelOutputWithAttentionMask` 或 `tuple(torch.Tensor)` `BaseModelOutputWithAttentionMask` 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[UdopConfig](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopConfig)）和输入。 [UdopEncoderModel](/docs/transformers/v5.23.0/zh/model_doc/udop#transformers.UdopEncoderModel) 的 forward 方法重写了 `__call__` 特殊方法。 尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。 - **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列最后一个隐藏状态。 - **attention_mask** (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*) -- 在模型的前向传播中使用的注意力掩码，用于避免对填充（padding）标记的索引执行注意力操作。掩码值取自 `[0, 1]`： - 1 表示未被**屏蔽**的 token， - 对于被**掩码**的 token，值为 0。 - **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。 包含预计算的隐藏状态（自注意力块中的键和值，以及如果 `config.is_encoder_decoder=True` 则还包括交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。 - **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。 - **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 ```