Transformers documentation

UnlimitedOcr

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

该模型于 2026-06-23 在 HF papers 上发布，并于 2026-10-14 贡献至 Hugging Face Transformers。

UnlimitedOcr

概述

UnlimitedOcr 模型由百度公司的 Youyang Yin、Huanhuan Liu、Qunyi Xie、Chaorun Liu、Shiqi Yang、Shaohua Wang、Zhanlong Liu、Hao Zou、Jinyue Chen、Shu Wei、Jingjing Wu、Mingxin Huang、Zhen Wu、Guibin Wang、Tengyu Du 和 Lei Jia 在 Unlimited OCR Works 中提出。

它是一个具有 30 亿参数的单一模型，标准上下文长度为 32,768 个 token。

该论文的摘要如下：

近期，以 DeepSeek OCR 为代表的端到端 OCR 模型再次将 OCR 推至聚光灯下。一种普遍的观点认为，将大语言模型（LLM）用作解码器，能够利用语言的先验分布，从而提升 OCR 性能。然而，其弊端同样明显：随着输出序列变长，累积的 KV cache 会导致内存消耗增加，并使生成速度逐渐变慢。这与人类的表现形成鲜明对比——人类在执行长时程的抄写任务时，效率并不会出现此类下降。在本技术报告中，我们提出了 Unlimited OCR，一个旨在模拟人类解析工作记忆的模型。以 DeepSeek OCR 为基线，我们将解码器中的所有注意力层替换为我们提出的 Reference Sliding Window Attention（R-SWA），在保持整个解码过程中 KV cache 恒定的同时，降低了注意力计算成本。通过将 DeepSeek OCR 编码器的高压缩率与我们恒定的 KV cache 设计相结合，Unlimited OCR 能够在标准最大长度 32K 下，通过单次前向传播转录数十页文档。更重要的是，R-SWA 是一种通用的解析注意力机制——除了 OCR 之外，它同样适用于 ASR、翻译等任务。代码和模型权重已公开于 http://github.com/baidu/Unlimited-OCR

Unlimited-OCR 支持两种推理配置：默认的 “gundam” 模式使用 640x640 的图块，并结合动态裁剪来处理高分辨率文档；“base” 模式则使用单个 1024x1024 的全局视图来处理标准分辨率的输入。要启用 base 模式，请在 processor 中设置 crop_to_patches=False，或者在使用 apply_chat_template() 时通过 processor_kwargs 传入该参数。

视觉塔采用了 DeepSeek-OCR-2 中的两阶段方法：SAM ViT-B 编码器作为输入，接入 CLIP ViT 编码器。与 DeepSeek-OCR-2 不同，CLIP 特征还会与 SAM 特征进行拼接，以生成最终的图像 token。Unlimited-OCR 还省略了 DeepSeek-OCR-2 中的可学习 patch 查询。

文本模型与 DeepSeek-OCR-2 相同，额外增加了 Reference Sliding Window Attention (R-SWA)。R-SWA 仅应用于生成的 token。所有图像和提示 token 在整个解码过程中均保持完全可见，因此长文档不会因早期页面而丢失上下文。

该模型由 guarin 贡献。原始代码可在此处找到。

原始实现使用 torch.autocast 以 bfloat16 运行模型。请将 forward 和 generate 调用包裹在 autocast 上下文中，以复现其输出。
with torch.autocast(device_type=model.device.type, dtype=torch.bfloat16):
    output = model.generate(**inputs)

单页 OCR

多页 OCR

from transformers import AutoProcessor, AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained("baidu/Unlimited-OCR", device_map="auto")
processor = AutoProcessor.from_pretrained("baidu/Unlimited-OCR")

image = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_suggestion_form.jpg"
messages = [
    {
        "role": "user",
        "content": [{"type": "image", "url": image}, {"type": "text", "text": "document parsing."}],
    }
]
inputs = processor.apply_chat_template(
    messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt"
).to(model.device, model.dtype)

output = model.generate(**inputs, max_new_tokens=512)
processor.decode(output[0, inputs["input_ids"].shape[1]:], skip_special_tokens=True)
# image [383, 87, 497, 171]\ntext [333, 201, 558, 230]R&D QUALITY IMPROVEMENT\nSUGGESTION/SOLUTION FORM...

# All bounding boxes are in (x1, y1, x2, y2) format with coordinates normalized to [0, 999]

批处理

对于批量处理，请传入一个消息列表。如果图像尺寸不同，请将处理器的 padding=True 设置为 True。

from transformers import AutoProcessor, AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained("baidu/Unlimited-OCR", device_map="auto")
processor = AutoProcessor.from_pretrained("baidu/Unlimited-OCR")

image1 = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_suggestion_form.jpg"
image2 = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_receipt.jpeg"
messages = [
    [
        {
            "role": "user",
            "content": [{"type": "image", "url": image}, {"type": "text", "text": "document parsing."}],
        }
    ]
    for image in [image1, image2]
]
inputs = processor.apply_chat_template(
    messages,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    processor_kwargs={"padding": True},
).to(model.device, model.dtype)

output = model.generate(**inputs)
processor.decode(output[0, inputs["input_ids"].shape[1]:], skip_special_tokens=True)
# image [383, 87, 497, 171]\ntext [333, 201, 558, 230]R&D QUALITY IMPROVEMENT\nSUGGESTION/SOLUTION FORM...

# All bounding boxes are in (x1, y1, x2, y2) format with coordinates normalized to [0, 999]

区域检测

将 skip_special_tokens=False 设置为 <|det|>...<|/det|> 标记，以包裹所有检测结果和区域类型。这对于输出的进一步后处理非常有用，例如在图像上绘制检测到的边界框。每个检测结果的格式为 <|det|>region_type [x1, y1, x2, y2]<|/det|>text...，其中坐标已归一化到 [0, 999] 范围内。将 return_detections=True 设置为 {"region_type": region_type, "box": [x1, y1, x2, y2], "text": "..."} 以获取一个额外的字典列表，其中包含所有解析后的检测结果。

from transformers import AutoProcessor, AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained("baidu/Unlimited-OCR", device_map="auto")
processor = AutoProcessor.from_pretrained("baidu/Unlimited-OCR")

image = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_suggestion_form.jpg"
messages = [
    {
        "role": "user",
        "content": [{"type": "image", "url": image}, {"type": "text", "text": "document parsing."}],
    }
]
inputs = processor.apply_chat_template(
    messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt"
).to(model.device, model.dtype)

output = model.generate(**inputs)
decoded, detections = processor.decode(output[0, inputs["input_ids"].shape[1]:], skip_special_tokens=False, return_detections=True)
# <|det|>image [383, 87, 497, 171]<|/det|>\n<|det|>text [333, 201, 558, 230]<|/det|>R&D QUALITY IMPROVEMENT\nSUGGESTION/SOLUTION FORM...

# Visualization
import random
import matplotlib.pyplot as plt
import matplotlib.patches as patches
from transformers.image_utils import load_image

image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_suggestion_form.jpg")
width, height = image.size

figure, axis = plt.subplots(figsize=(10, 12))
axis.imshow(image)
for detection in detections:
    region_type = detection["region_type"]
    x1, y1, x2, y2 = detection["box"]
    x1, y1, x2, y2 = int(x1) / 999 * width, int(y1) / 999 * height, int(x2) / 999 * width, int(y2) / 999 * height
    color = (random.random(), random.random(), random.random())
    rectangle = patches.Rectangle((x1, y1), x2 - x1, y2 - y1, linewidth=1.5, edgecolor=color, facecolor="none")
    axis.add_patch(rectangle)
    axis.text(x1, y1, region_type, color="white", fontsize=8, backgroundcolor=color, verticalalignment="top")
axis.axis("off")
plt.show()

Transformers

UnlimitedOcr

概述

批处理

区域检测

UnlimitedOcrConfig

class transformers.UnlimitedOcrConfig

UnlimitedOcrTextConfig

class transformers.UnlimitedOcrTextConfig

UnlimitedOcrVisionConfig

class transformers.UnlimitedOcrVisionConfig

UnlimitedOcrVisionEncoderConfig

class transformers.UnlimitedOcrVisionEncoderConfig

UnlimitedOcrSamVisionConfig

class transformers.UnlimitedOcrSamVisionConfig

UnlimitedOcrImageProcessor

class transformers.UnlimitedOcrImageProcessor

crop_image_to_patches

get_number_of_image_patches

pad_to_square

UnlimitedOcrProcessor

class transformers.UnlimitedOcrProcessor

batch_decode

decode

UnlimitedOcrPreTrainedModel

class transformers.UnlimitedOcrPreTrainedModel

UnlimitedOcrTextPreTrainedModel

class transformers.UnlimitedOcrTextPreTrainedModel

UnlimitedOcrTextModel

class transformers.UnlimitedOcrTextModel

forward

UnlimitedOcrVisionModel

class transformers.UnlimitedOcrVisionModel

forward

UnlimitedOcrModel

class transformers.UnlimitedOcrModel

forward

UnlimitedOcrForConditionalGeneration

class transformers.UnlimitedOcrForConditionalGeneration

forward