该模型于 2026-03-21 贡献给 Hugging Face Transformers。

UVDoc

概述

UVDoc 文本图像校正的主要目的是对图像进行几何变换，以修正图像中的文档畸变、倾斜、透视变形等问题。

用法

单输入推理

下例演示了如何使用 AutoImageProcessor 和 UVDocModel 对文档图像进行校正。

自动模型

批量推理

以下是如何使用 UVDoc 执行批量文档校正的方法：

自动模型

UVDocConfig

class transformers.UVDocConfig

< 源码 >

( transformers_version: str | None = None architectures: list[str] | None = None output_hidden_states: bool | None = False return_dict: bool | None = True dtype: typing.Union[str, ForwardRef('torch.dtype'), NoneType] = None chunk_size_feed_forward: int = 0 is_encoder_decoder: bool = False id2label: dict[int, str] | dict[str, str] | None = None label2id: dict[str, int] | dict[str, str] | None = None problem_type: typing.Optional[typing.Literal['regression', 'single_label_classification', 'multi_label_classification']] = None backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None hidden_act: str = 'prelu' padding_mode: str = 'reflect' kernel_size: int = 5 bridge_connector: list[int] | tuple[int, ...] = (128, 128) out_point_positions2D: Sequence = ((128, 32), (32, 2)) )

参数

backbone_config (Union[dict, ~configuration_utils.PreTrainedConfig], 可选) — 骨干网络模型的配置。
hidden_act (str, 可选, 默认为 prelu) — 解码器中的非线性激活函数（函数或字符串）。例如："gelu"、"relu"、"silu" 等。
padding_mode (str, 可选, 默认为 "reflect") — 卷积层的填充模式。支持的模式有 "reflect"、"constant" 和 "replicate"。
kernel_size (int, 可选, 默认为 5) — 骨干网络中卷积层的卷积核大小。
bridge_connector (list[int] | tuple[int, ...], 可选, 默认为 (128, 128)) — 桥接连接器的配置，格式为 [输入通道, 输出通道]。
out_point_positions2D (Sequence[list[int] | tuple[int, ...]], 可选, 默认为 ((128, 32), (32, 2))) — 二维输出点位置层的配置，格式为 [输入通道, 输出通道]。

这是用于存储 UVDocModel 配置的配置类。它根据指定的参数实例化一个 UVDoc 模型，从而定义模型架构。使用默认参数初始化配置将得到与 PaddlePaddle/UVDoc_safetensors 类似的配置。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。阅读 PreTrainedConfig 的文档以获取更多信息。

UVDocModel

class transformers.UVDocModel

< 源码 >

( config: UVDocConfig )

参数

config (UVDocConfig) — 包含模型所有参数的配置类。使用配置文件初始化模型不会加载与模型相关的权重，仅加载配置。请查阅 from_pretrained() 方法以加载模型权重。

该模型将原始文档图像（像素值）作为输入，通过 UVDoc 骨干网络处理以预测空间变换参数，并输出校正后的文档图像张量。

该模型继承自 PreTrainedModel。请查看超类文档以了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头部等）。

此模型也是一个 PyTorch torch.nn.Module 子类。像普通的 PyTorch Module 一样使用它，并参考 PyTorch 文档了解一般用法和行为的所有相关信息。

forward

< 源码 >

( pixel_values: FloatTensor **kwargs: typing_extensions.Unpack[transformers.utils.generic.TransformersKwargs] ) → BaseModelOutputWithNoAttention 或 tuple(torch.FloatTensor)

参数

pixel_values (torch.FloatTensor, 形状为 (batch_size, num_channels, image_size, image_size)) — 输入图像对应的张量。像素值可以使用 UVDocImageProcessor 获取。详情请参阅 UVDocImageProcessor.__call__() (processor_class 使用 UVDocImageProcessor 处理图像)。

BaseModelOutputWithNoAttention 或 tuple(torch.FloatTensor)

一个 BaseModelOutputWithNoAttention 或一个 torch.FloatTensor 元组（如果传入了 return_dict=False 或当 config.return_dict=False 时），根据配置 (UVDocConfig) 和输入的不同包含各种元素。

UVDocModel 的 forward 方法重写了 __call__ 特殊方法。

虽然 forward pass 的实现需要在此函数中定义，但你应该在之后调用 Module 实例而不是这个，因为前者负责运行预处理和后处理步骤，而后者会静默地忽略它们。

last_hidden_state (torch.FloatTensor, 形状为 (batch_size, num_channels, height, width)) — 模型最后一层输出的隐藏状态序列。
hidden_states (tuple(torch.FloatTensor), optional, 当传入 output_hidden_states=True 或 config.output_hidden_states=True 时返回) — torch.FloatTensor 的元组（如果模型有嵌入层，则包含一个嵌入层输出，加上每层的一个输出），形状为 (batch_size, num_channels, height, width)。

模型在每个层输出的隐藏状态以及可选的初始嵌入输出。

UVDocBackboneConfig

class transformers.UVDocBackboneConfig

< 源码 >

( transformers_version: str | None = None architectures: list[str] | None = None output_hidden_states: bool | None = False return_dict: bool | None = True dtype: typing.Union[str, ForwardRef('torch.dtype'), NoneType] = None chunk_size_feed_forward: int = 0 is_encoder_decoder: bool = False id2label: dict[int, str] | dict[str, str] | None = None label2id: dict[str, int] | dict[str, str] | None = None problem_type: typing.Optional[typing.Literal['regression', 'single_label_classification', 'multi_label_classification']] = None _out_features: list[str] | None = None _out_indices: list[int] | None = None resnet_head: Sequence = ((3, 32), (32, 32)) resnet_configs: Sequence = (((32, 32, 1, False), (32, 32, 3, False), (32, 32, 3, False)), ((32, 64, 1, True), (64, 64, 3, False), (64, 64, 3, False), (64, 64, 3, False)), ((64, 128, 1, True), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False))) stage_configs: Sequence = (((128, 1),), ((128, 2),), ((128, 5),), ((128, 8), (128, 3), (128, 2)), ((128, 12), (128, 7), (128, 4)), ((128, 18), (128, 12), (128, 6))) kernel_size: int = 5 )

参数

resnet_head (Sequence[list[int] | tuple[int, ...]], 可选, 默认为 ((3, 32), (32, 32))) — ResNet 头部层的配置，格式为 [输入通道, 输出通道]。
resnet_configs (Sequence[Sequence[tuple[int, int, int, bool] | list[int | bool]]], 可选, 默认为 (((32, 32, 1, False), -- (32, 32, 3, False), (32, 32, 3, False)), ((32, 64, 1, True), (64, 64, 3, False), (64, 64, 3, False), (64, 64, 3, False)), ((64, 128, 1, True), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False)))): ResNet 阶段的配置，格式为 [输入通道, 输出通道, 膨胀值, 下采样]。
stage_configs (Sequence[Sequence[tuple[int, …] | list[int]]], 可选, 默认为 (((128, 1),), ((128, 2),), -- ((128, 5),), ((128, 8),(128, 3),(128, 2),), ((128, 12), (128, 7), (128, 4),), ((128, 18), (128, 12), (128, 6),),)): 桥接模块阶段的配置，格式为 [输入通道, 膨胀值]。每个内部序列对应一个单一的桥接块，外部序列按桥接阶段对块进行分组。
kernel_size (int, 可选, 默认为 5) — 卷积核的大小。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。阅读 PreTrainedConfig 的文档以获取更多信息。

UVDocBackbone

class transformers.UVDocBackbone

< 源码 >

( config: UVDocBackboneConfig )

参数

config (UVDocBackboneConfig) — 包含模型所有参数的配置类。使用配置文件初始化模型不会加载与模型相关的权重，仅加载配置。请查阅 from_pretrained() 方法以加载模型权重。

用于特征提取的 UVDoc 骨干模型。

该模型继承自 PreTrainedModel。请查看超类文档以了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头部等）。

此模型也是一个 PyTorch torch.nn.Module 子类。像普通的 PyTorch Module 一样使用它，并参考 PyTorch 文档了解一般用法和行为的所有相关信息。

forward

< 源码 >

( pixel_values: FloatTensor **kwargs: typing_extensions.Unpack[transformers.utils.generic.TransformersKwargs] ) → BackboneOutput 或 tuple(torch.FloatTensor)

参数

pixel_values (形状为 (batch_size, num_channels, image_size, image_size) 的 torch.FloatTensor) — 对应于输入图像的张量。像素值可以使用 UVDocImageProcessor 获取。详情请参阅 UVDocImageProcessor.__call__()（processor_class 使用 UVDocImageProcessor 处理图像）。

BackboneOutput 或 tuple(torch.FloatTensor)

一个 BackboneOutput 或 torch.FloatTensor 元组（如果传入了 return_dict=False 或 config.return_dict=False 时），根据配置（UVDocConfig）和输入的不同，包含各种元素。

UVDocBackbone 的 forward 方法，覆盖了 __call__ 特殊方法。

虽然 forward pass 的实现需要在此函数中定义，但你应该在之后调用 Module 实例而不是这个，因为前者负责运行预处理和后处理步骤，而后者会静默地忽略它们。

feature_maps (tuple(torch.FloatTensor) of shape (batch_size, num_channels, height, width)) — 阶段的特征图。
hidden_states (tuple(torch.FloatTensor), optional, returned when output_hidden_states=True is passed or when config.output_hidden_states=True) — torch.FloatTensor 元组（一个用于嵌入输出 + 每个层输出一个）的形状为 (batch_size, sequence_length, hidden_size) 或 (batch_size, num_channels, height, width)，具体取决于主干网络。

模型在每个阶段输出的隐藏状态以及初始嵌入输出。
attentions (tuple(torch.FloatTensor), optional, returned when output_attentions=True is passed or when config.output_attentions=True) — torch.FloatTensor 元组（每个层一个）的形状为 (batch_size, num_heads, sequence_length, sequence_length)。仅当主干网络使用注意力时适用。

注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。

UVDocBridge

class transformers.UVDocBridge

< 源码 >

( config )

UVDocImageProcessor

class transformers.UVDocImageProcessor

< 源码 >

( **kwargs: typing_extensions.Unpack[transformers.processing_utils.ImagesKwargs] )

参数

**kwargs (ImagesKwargs, 可选) — 额外的图像预处理选项。模型特定的 kwargs 列在上面；有关支持参数的完整列表，请参阅 TypedDict 类。

构建一个 UVDocImageProcessor 图像处理器。

post_process_document_rectification

< 源码 >

( prediction: Tensor original_images: list scale: float = 255.0 ) → 包含校正图像的字典列表。每个字典有

参数

prediction — 预测的 2D 贝塞尔网格坐标，形状为 (B, 2, H, W)
original_images — 原始输入张量列表，每个形状为 (C, H_i, W_i)。图像的大小可能不同。
scale — 输出图像的缩放因子（默认：255.0）

包含校正图像的字典列表。每个字典有

“images”：形状为 (H, W, 3) 的校正图像张量，数据类型为 torch.uint8，通道顺序为 BGR（适用于 OpenCV 可视化）

后处理文档校正预测，将其转换为校正后的图像。

在 GitHub 上更新