这是一篇为你整理的关于 Unlimited-OCR 的技术实操指南，重点解析如何利用这项新技术打破长文档识别的性能瓶颈。

一、 为什么关注 Unlimited-OCR？

传统的端到端大模型 OCR（如早期的 DeepSeek-OCR）在处理几十甚至上百页的长篇 PDF 时，面临着一个致命的架构瓶颈：KV Cache 的线性飙升。随着输出文本不断拉长，显存消耗呈 $O(N)$ 暴增，极易导致服务器 OOM（内存溢出）。在此之前，开发者被迫采用“按页切分识别，再手动拼接”的 for-loop 范式，不但工程繁琐，还容易丢失跨页表格和段落的上下文。

2026 年 6 月开源的 Unlimited-OCR（由百度团队主导发布）通过引入 R-SWA（Reference Sliding Window Attention，参考滑动窗口注意力） 机制，彻底改变了这一现状。它让解码器在生成当前字词时，仅与“所有的图像视觉 Token”和“最近 128 个生成的 Token”保持关联连接。

这种设计让 KV Cache 的显存占用直接从线性级压缩为常数级。它保留了 DeepEncoder 极高的图像压缩率，能够在一个 Forward Pass（单次前向传播）中塞下多达 32K 长度的上下文，一口气解析几十页的长卷宗，并且在 OmniDocBench 上超越了 DeepSeek-OCR 创下 SOTA 纪录。

二、 核心架构模式解析

Unlimited-OCR 针对不同的业务场景，在 API 层面设计了两种解析模式：

三、 实操部署与推理链路

由于 R-SWA 是高度定制的注意力算子，官方强烈推荐搭配 SGLang 框架进行推理服务部署，以获得最佳的吞吐量（TPS）和恒定的响应延迟。

1. 初始化运行环境:
   建议使用 uv 来隔离 Python 环境。你需要安装定制版的 SGLang 以及用于处理 PDF 切页的依赖包：

uv venv --python 3.12source .venv/bin/activate# 安装 SGLang 及定制的底层 Kernelsuv pip install wheel/sglang-0.0.0.dev11416+g92e8bb79e-py3-none-any.whluv pip install kernels==0.11.7# 安装 PDF 转图片的工具uv pip install pymupdf==1.27.2.2

1. 原生 HuggingFace 脚本测试 (适合单机调试):
   如果你只是想快速测试几十页的长文档，可以直接调用原生的 infer_multi 接口：

import osimport tempfileimport fitz# PyMuPDFfrom transformers import AutoTokenizer, AutoModelForCausalLMmodel_path = ”baidu/Unlimited-OCR”tokenizer = AutoTokenizer.from_pretrained(model_path)# trust_remote_code 必须为 True，以加载 R-SWA 自定义算子model = AutoModelForCausalLM.from_pretrained(model_path, trust_remote_code=True).cuda()# 工具函数：将多页 PDF 转化为图片地址列表def pdf_to_images(pdf_path, dpi=300): doc = fitz.open(pdf_path) tmp_dir = tempfile.mkdtemp(prefix='pdf_ocr_') mat = fitz.Matrix(dpi / 72, dpi / 72) paths = [] for i, page in enumerate(doc): out = os.path.join(tmp_dir, f'page_{i+1:04d}.png') page.get_pixmap(matrix=mat).save(out) paths.append(out) doc.close() return paths# 执行长程 Multi-page 推理model.infer_multi( tokenizer, prompt='<image>Multi page parsing.', image_files=pdf_to_images('your_long_document.pdf', dpi=300), output_path='./output_dir', image_size=1024,# 必须使用 base 配置 max_length=32768,# 设定最大 Token 长度 no_repeat_ngram_size=35,# 防复读关键参数 ngram_window=1024, save_results=True)

1. 拉起 SGLang 高并发服务端 (适合生产环境):
   面对高并发的 API 需求，使用 SGLang 原生启动 Server 才能完全发挥“常数级 KV Cache”的显存优势：

python -m sglang.launch_server \ --model-path baidu/Unlimited-OCR \ --port 10000 \ --trust-remote-code

启动后，你的应用层系统即可向 

http://127.0.0.1:10000/generate

发送包含 base64 图像数组的 JSON Payload，进行 OpenAI 风格的异步流式调用。

四、 实战避坑建议

1. 多模态对齐边界：
    Unlimited-OCR 的输入基础仍是单页图像组合。在准备数据时，将 PDF 切分为单页图片输入即可，不要提前把多页长图拼接成一张超长条形图，那会超出 DeepEncoder 的分辨率极值。
2. 文本生成复读控制：
    大模型在生成极长序列时容易陷入局部重复（复读机现象）。在调用参数中，务必开启并调优 no_repeat_ngram_size 和 ngram_window 惩罚机制。
3. ONNX 导出：
    如果你的目标运行平台受限（如脱离 CUDA 的纯 CPU 推理或边缘端），可以利用项目组提供的导出脚本（依赖 onnxscript）生成 unlimited_ocr.onnx 图文件，降低部署门槛。