Unlimited-OCR-2 Transformers推理实战：单页与多页文档解析全攻略-开发者社区

Unlimited-OCR-2 Transformers推理实战：单页与多页文档解析全攻略

【免费下载链接】Unlimited-OCR-2项目地址: https://ai.gitcode.com/hf_mirrors/baidu/Unlimited-OCR-2

Unlimited-OCR-2 是百度推出的开源 OCR 3.0 文档解析模型，基于 Transformers 即可直接加载运行，支持单页扫描件识别与整本 PDF 的多页文档解析。本文用最短的路径带你完成：环境安装、模型加载、单页解析、多页解析四个核心步骤，并讲清两种推理模式（gundam / base）的差别，新手也能一次跑通。

什么是 Unlimited-OCR-2：从"长文档"到"无限页"解析

传统 OCR 模型处理长文档时，注意力计算量随页数呈平方级增长，页数一多就 OOM 或超时。Unlimited-OCR-2 引入了SR-SWA（Sparse Reference Sliding Window Attention，稀疏参考滑动窗口注意力），把超长的图文注意力交互压缩到一个固定大小的工作参考集（如 512 个 token），从而让单步解码的延迟和显存占用基本不随文档长度增长。

它在数十页基准（如 MPDocBench）和上百页极限基准（如 MarathonDocBench）上均取得 SOTA 成绩，官方性能对比如下：

模型架构细节可见技术报告 Unlimited-OCR-2.pdf，配置与超参数集中在 config.json 中。

一键安装：最快配置 Transformers 推理环境

官方验证过的环境为 Python 3.10、NVIDIA A800-80GB 显卡（其他 80GB 级显卡可参考）。一条命令装齐依赖：

pip install torch==2.13.0 torchvision pillow transformers==4.52.1 huggingface-hub==0.36.0 \ tokenizers==0.21.4 addict==2.4.0 einops==0.8.2 easydict==1.13

💡 版本敏感提示：该模型依赖 transformers 的自定义代码加载机制，transformers与huggingface-hub版本请保持一致，避免加载时报属性缺失。

一行代码加载模型

模型以baidu/Unlimited-OCR-2仓库形式提供（即本仓库：权重分片 + 自定义建模代码），加载时务必加trust_remote_code=True：

import torch from transformers import AutoModel, AutoTokenizer model_name = "baidu/Unlimited-OCR-2" tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True) model = AutoModel.from_pretrained(model_name, trust_remote_code=True, use_safetensors=True, torch_dtype=torch.bfloat16).eval().cuda()

模型加载一次，之后可反复调用解析接口，无需重复初始化。

单页文档解析：model.infer 调用示例

单页场景推荐使用infer接口（实现见 modeling_unlimitedocr.py）。它默认启用gundam 模式——把单页图像动态切分为多个 640×640 的小块（动态 tiling，2~16 块自适应），让大字号、表格、公式等细节不丢失：

text = model.infer(tokenizer, image_file="your_doc/page_1.jpg", output_path="output/single", save_results=True)

image_file支持图片路径或 PIL 对象；
save_results=True时会在output_path下生成解析结果与标注图（下文详述）；
常用调参项：max_page_tokens（每页输出上限，默认 20000）、temperature（默认 0，贪心解码）。

多页文档解析：model.infer_multi 跨页上下文

整份文档（几十页甚至上百页）可以一次请求解析完，模型能利用跨页上下文（如续页表格、跨页章节）。infer_multi接口（实现见 modeling_unlimitedocr.py）的用法：

pages = [f"your_doc/page_{i}.jpg" for i in range(1, 8)] text, num_tokens = model.infer_multi(tokenizer, image_files=pages, output_path="output/multi", save_results=True)

使用要点：

按页序传图：image_files中的顺序就是文档页序；
自动构建 prompt：内部自动生成"<PAGE><image>" * num_pages + "Multi page parsing."，无需手写；
base 模式编码：每页编码为一张全局视图（不做切块），因此多页解析的显存占用基本与页数解耦；
输出对齐：结果中每页对应一个<PAGE>标记，顺序与输入一致，方便按页切分。

两种模式的选型速查

场景	接口	编码模式	特点
单页高清细节	`infer`	gundam（动态切块）	文字小、表格密也不糊
整份文档	`infer_multi`	base（整页全局视图）	跨页上下文 + 显存友好
显式指定	`infer(crop_mode=True/False)`	强制 gundam / base	高级用户按需求切换

读懂输出：save_results 生成了什么

设置save_results=True后，_uocr_save_results（modeling_unlimitedocr.py）会在output_path下写入：

result.md：Markdown 化结果，公式与图表引用已替换为图片链接，可直接阅读；
result_raw.md：模型原始输出（保留<PAGE>、<ref>等特殊标记）；
result_with_boxes_*.jpg：在原图上绘制文字/图表位置框的可视化图；
images/page_*_*.jpg：从页面中切出的公式、表格等引用图。

同时，推理过程内置了PageCountGuard（输出页数与输入页数对齐、每页 token 上限保护）与可选的 NoRepeatNGram 去重，输出更稳定。

从试用到生产：SGLang 部署一句话

Transformers 适合快速验证；正式服务建议用 SGLang，仓库已内置定制 wheel：sglang-0.5.20.dev13+g75b9b06b02-py3-none-any.whl。启动服务后走 OpenAI 兼容 API（/v1/chat/completions），并可通过SGLANG_UOCR_DOC_GUNDAM_PAGE_WINDOW等环境变量按"页窗口"调度超长文档，完整启动命令与环境变量说明见 README.md 的 SGLang 章节。

仓库关键文件速查

文件	作用
modeling_unlimitedocr.py	模型主体，`infer`/`infer_multi`推理入口
modeling_deepseekv2.py	DeepSeek-V2 解码器与稀疏注意力推理路径
deepencoder.py	视觉编码器（SAM-ViT-B），负责图文编码
dash_attention.py	DASH 块稀疏注意力核心实现
conversation.py	对话模板与消息格式化
tokenizer.json / special_tokens_map.json	分词器与特殊 token（`<PAGE>`等）定义
Unlimited-OCR-2.pdf	技术报告（Unlimited OCR Works）