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 모델은 Baidu Inc.의 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에서 제안했습니다.

3B 파라미터 단일 모델이며, 표준 컨텍스트 길이는 32,768 토큰입니다.

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

최근 DeepSeek OCR를 대표로 하는 end-to-end OCR 모델들이 OCR을 다시 주목받게 만들었습니다. LLM을 decoder로 사용하면 언어의 사전 분포를 활용할 수 있어 OCR 성능이 향상된다는 것이 널리 받아들여지는 관점입니다. 그러나 단점도 명확합니다. 출력 시퀀스가 길어질수록 누적되는 KV cache가 메모리 사용량을 증가시키고 생성 속도를 점차 늦추기 때문입니다. 이는 긴 시간 동안 복사 작업을 수행할 때 효율성이 떨어지지 않는 인간과 뚜렷한 대비를 이룹니다. 본 기술 보고서에서는 인간의 parsing working memory를 모방하도록 설계된 Unlimited OCR 모델을 제안합니다. DeepSeek OCR를 baseline으로 삼아, decoder의 모든 attention layer를 우리가 제안한 Reference Sliding Window Attention(R-SWA)로 대체했습니다. R-SWA는 attention 계산 비용을 줄이면서 전체 decoding 과정에서 KV cache를 일정하게 유지합니다. DeepSeek OCR encoder의 높은 압축률과 우리의 일정 KV cache 설계를 결합하여, Unlimited OCR은 표준 최대 길이 32K에서 단일 forward pass로 수십 페이지의 문서를 전사할 수 있습니다. 더욱이 R-SWA는 범용 parsing attention 메커니즘으로, OCR 외에도 ASR, 번역 등의 작업에도 동일하게 적용할 수 있습니다. 코드와 모델 가중치는 http://github.com/baidu/Unlimited-OCR에서 공개되어 있습니다.

Unlimited-OCR은 두 가지 추론 구성을 지원합니다. 기본인 “gundam” 모드는 고해상도 문서를 위해 640x640 타일과 동적 크롭을 사용하며, “base” 모드는 표준 해상도 입력을 위해 단일 1024x1024 전체 뷰를 사용합니다. base 모드를 사용하려면 프로세서에서 crop_to_patches=False를 설정하거나, apply_chat_template()를 사용할 때 processor_kwargs를 통해 전달하세요.

비전 타워는 DeepSeek-OCR-2의 2단계 접근 방식을 따릅니다. SAM ViT-B 인코더가 CLIP ViT 인코더로 입력됩니다. DeepSeek-OCR-2와 달리, CLIP 특징은 SAM 특징과 추가로 연결(concatenate)되어 최종 이미지 토큰을 생성합니다. Unlimited-OCR은 또한 DeepSeek-OCR-2의 학습 가능한 패치 쿼리를 생략합니다.

텍스트 모델은 DeepSeek-OCR-2와 동일하며, Reference Sliding Window Attention(R-SWA)가 추가되었습니다. R-SWA는 생성된 토큰에만 적용됩니다. 모든 이미지 및 프롬프트 토큰은 디코딩 전체 과정에서 완전히 가시적으로 유지되므로, 긴 문서에서도 이전 페이지의 컨텍스트가 손실되지 않습니다.

이 모델은 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를 설정하세요.

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|> 마커로 감싸집니다. 이는 출력의 추가 후처리, 예를 들어 이미지 위에 감지된 바운딩 박스를 그리는 데 유용합니다. 각 감지 결과는 [0, 999] 범위로 정규화된 좌표를 포함하여 <|det|>region_type [x1, y1, x2, y2]<|/det|>text... 형식으로 감싸집니다. 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

클래스 transformers.UnlimitedOcrConfig

UnlimitedOcrTextConfig

class transformers.UnlimitedOcrTextConfig

UnlimitedOcrVisionConfig

class transformers.UnlimitedOcrVisionConfig

UnlimitedOcrVisionEncoderConfig

클래스 transformers.UnlimitedOcrVisionEncoderConfig

UnlimitedOcrSamVisionConfig

class transformers.UnlimitedOcrSamVisionConfig

UnlimitedOcrImageProcessor

클래스 transformers.UnlimitedOcrImageProcessor

crop_image_to_patches

get_number_of_image_patches

pad_to_square

UnlimitedOcrProcessor

class transformers.UnlimitedOcrProcessor

batch_decode

decode

UnlimitedOcrPreTrainedModel

클래스 transformers.UnlimitedOcrPreTrainedModel

UnlimitedOcrTextPreTrainedModel

class transformers.UnlimitedOcrTextPreTrainedModel

UnlimitedOcrTextModel

class transformers.UnlimitedOcrTextModel

forward

UnlimitedOcrVisionModel

class transformers.UnlimitedOcrVisionModel

forward

UnlimitedOcrModel

class transformers.UnlimitedOcrModel

forward

UnlimitedOcrForConditionalGeneration

클래스 transformers.UnlimitedOcrForConditionalGeneration

forward