https://github.com/baidu/Unlimited-OCR
面向读者:后端工程师、全栈工程师、AI 应用开发者、技术架构师
一、先认识 Unlimited-OCR:它解决的是什么问题?
最近百度开源的 Unlimited-OCR 值得关注。
项目地址:
- GitHub:baidu/Unlimited-OCR
- Hugging Face:baidu/Unlimited-OCR-2
它并不是传统意义上只负责识别文字的 OCR 引擎,而是一个面向复杂文档理解的视觉语言模型(Vision-Language Model,VLM)。
先理解一个区别:
传统 OCR 的目标是把图片中的文字提取出来,而 Unlimited-OCR 的目标是理解整份文档的内容、结构和上下文。
例如,一份 100 页的 PDF:
- 传统 OCR:逐页识别文字,然后把结果拼接起来。
- 普通视觉语言模型:把文档送给模型,但受到上下文长度、显存和计算量的限制。
- Unlimited-OCR 2:专门针对长文档设计,让模型能够处理跨页面的结构和上下文关系。
这意味着它不仅可以识别文字,还能处理:
- 文档标题和章节层级。
- 段落、文本块和阅读顺序。
- 表格及跨页表格。
- 图片、图表、印章等视觉元素。
- 多页文档之间的上下文关系。
这类能力对于合同、医疗票据、财务报表、技术文档、论文、档案数字化等业务很有价值。
二、Unlimited-OCR 与 Unlimited-OCR 2 有什么区别?
首先明确:你给出的两个链接实际上是同一个项目的代码仓库和第二代模型权重,并不是两个独立的 OCR 产品。
| 对比 | Unlimited-OCR 1 | Unlimited-OCR 2 |
|---|---|---|
| 定位 | 长文档解析 | 超长文档解析 |
| 核心特点 | 多页文档理解 | 无限视野文档解析设计 |
| 注意力机制 | 常规视觉语言模型架构 | SR-SWA |
| 跨页理解 | 支持 | 进一步增强 |
| 超长文档 | 受到上下文及计算资源约束 | 面向超长文档设计 |
| 推理方式 | Transformers、SGLang | Transformers、定制 SGLang |
| 推荐用途 | 一般文档解析 | 大量页面、复杂长文档 |
这里最值得研究的是第二代模型的技术创新。
2.1 SR-SWA:Sparse Reference Sliding Window Attention
Unlimited-OCR 2 核心创新
先简单理解传统 Transformer 的注意力机制。
假设一份文档经过视觉编码后产生了大量 Token。
传统 Self-Attention 需要计算 Token 之间的关联:
Attention(Q, K, V) = Softmax(QKᵀ / √d) · V
如果 Token 数量为 N,注意力计算和相关矩阵的规模通常随 N² 增长。
这会带来两个问题:
- 文档越长,计算量增长越快。
- 需要保留的中间状态越来越多,显存压力也越来越大。
对于几百页的文档,这个问题尤其明显。
Unlimited-OCR 2 引入了 SR-SWA(Sparse Reference Sliding Window Attention)。
它的核心思想是:
不需要让每一个新 Token 永远关注全部历史 Token,而是维护一组有限规模的参考信息,让后续计算基于这些参考信息进行。
可以把它理解成阅读一本很长的书:
- 普通注意力:每读一页,都试图重新关联之前所有内容。
- SR-SWA:维护一组重要的参考信息,后续阅读时优先利用这些信息。
官方介绍中提到,工作参考集合可以压缩到固定规模,例如 512 个 Token,使得解码阶段的计算和显存占用不再随着文档长度以传统方式持续增长。
注意,这并不意味着整个系统的资源消耗完全与文档长度无关。图像编码、页面处理、输出 Token、磁盘和网络传输仍然需要消耗资源。
它解决的主要是超长文档解析中的注意力计算瓶颈。
官方技术说明:
2.2 为什么叫 Unlimited?
这里的 Unlimited 不是说可以不受任何资源限制地输入无限页 PDF。
它强调的是一种新的文档解析能力:在有限工作上下文的情况下,持续处理很长的文档,而不必像传统方案一样随着历史长度不断扩大注意力计算规模。
对于工程师而言,可以把它理解为:
- 不必简单地把 100 页拆成 100 次互不相关的 OCR。
- 模型可以在多页文档中建立关联。
- 可以尝试处理跨页表格、跨页章节和连续内容。
- 可以通过页面窗口调度,在资源可控的情况下处理更长的文档。
官方使用 MPDocBench 和 MarathonDocBench 进行长文档能力评估,后者面向数百页级别的文档场景。
这也是它和普通 OCR 产品最大的区别。
三、整体技术架构
从工程角度看,Unlimited-OCR 2 可以拆成四个部分:
| 模块 | 主要职责 |
|---|---|
| 图像预处理 | PDF 转图片、分辨率处理、页面排序 |
| 视觉编码器 | 把页面图像转换成视觉特征 |
| 文档解析模型 | 理解文字、布局、结构和跨页关系 |
| 后处理 | 将模型特殊标记转换成 Markdown、HTML 等格式 |
一个典型的处理过程:
用户上传 PDF
|
v
PDF 页面解析
|
v
转换为图片
|
v
Unlimited-OCR 2
|
v
原始文档结构输出
|
v
后处理
|
+-- Markdown
+-- HTML 表格
+-- 图片引用
+-- 页面结构
|
v
业务系统存储
|
v
全文搜索 / RAG / AI 问答
这里有一个值得注意的设计:
OCR 模型不负责你的业务数据建模。
例如,它可以识别一张医疗发票中的金额、日期和项目,但最终要不要报销、报销多少,应该交给业务规则和后续审核系统。
不要把 OCR、文档理解和业务决策混在一起。
四、硬件要求:需要什么 GPU?
这是实际部署之前必须考虑的问题。
先看官方提供的信息:
- Unlimited-OCR 2 的模型文件在 Hugging Face 上总计约 6.87 GB。
- 官方 Transformers 测试环境使用 NVIDIA A800 80GB。
- 官方推荐 SGLang 作为服务化推理方案。
- 模型使用 BF16 权重进行官方 Transformers 示例推理。
注意:模型文件大小不等于推理所需显存。实际还需要考虑视觉编码、激活值、KV Cache、CUDA Graph、并发请求以及页面分辨率等。
4.1 硬件配置建议
下面是工程部署的初步选型建议,不是百度官方公布的最低硬件要求。
| GPU 显存 | 建议用途 |
|---|---|
| 16GB | 不建议直接作为完整 BF16 部署目标 |
| 24GB | 可以尝试研究优化后的低并发部署,但需要实际验证 |
| 32GB | 可以作为优化部署的实验目标 |
| 48GB | 更适合单卡实验和中小规模服务评估 |
| 80GB | 更接近官方 A800 测试环境,适合完整部署及进一步压测 |
我个人会这样选:
- 个人学习:租用 80GB GPU,先跑通官方方案。
- 产品原型:评估 48GB、80GB GPU 的实际峰值显存。
- 生产环境:根据并发、PDF 页数、输出长度进行压测,再确定 GPU 数量。
不要只根据模型权重大小买显卡。
特别是 SGLang 启动时还需要为权重、KV Cache 和其他运行时内存预留空间。
4.2 CPU、内存和磁盘
除了 GPU,还需要:
| 硬件 | 建议 |
|---|---|
| CPU | 8 核以上 |
| 系统内存 | 32GB 起步,建议 64GB |
| 磁盘 | 50GB 起步,建议 100GB 以上 |
| GPU | 优先 NVIDIA CUDA |
| 操作系统 | Linux Ubuntu |
| Python | 3.10(官方 SGLang 方案) |
这些是我给出的实验环境配置建议,不是官方最低门槛。
如果是大量 PDF 批量处理,还要考虑图片临时文件、模型缓存、日志和结果存储的空间。
五、部署方式一:Transformers 直接运行
如果你想先理解模型的使用方法,建议从 Transformers 开始。
它不需要先搭建完整推理服务,可以直接在 Python 中加载模型。
5.1 准备环境
建议使用 Ubuntu + NVIDIA GPU。
创建虚拟环境:
uv venv --python 3.10
source .venv/bin/activate
安装官方测试版本的依赖:
uv 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
这里使用的是仓库给出的版本组合。PyTorch 安装时还需要根据机器 CUDA 环境选择匹配的安装源和构建版本,不要直接假设默认 pip 包一定适合当前 GPU。
检查 GPU:
nvidia-smi
检查 PyTorch:
python -c "
import torch
print(torch.__version__)
print(torch.cuda.is_available())
print(torch.cuda.get_device_name(0))
"
5.2 下载模型
模型地址:
可以直接通过 Transformers 下载,也可以提前下载到本地。
pip install -U huggingface_hub
hf download baidu/Unlimited-OCR-2 \
--local-dir ./models/Unlimited-OCR-2
模型目录中主要包含:
Unlimited-OCR-2/
+-- config.json
+-- generation_config.json
+-- model-00001-of-00002.safetensors
+-- model-00002-of-00002.safetensors
+-- model.safetensors.index.json
+-- tokenizer.json
+-- tokenizer_config.json
+-- modeling_unlimitedocr.py
+-- modeling_deepseekv2.py
+-- ...
这里需要特别注意:
模型采用了自定义模型代码,因此加载时需要:
trust_remote_code=True
这意味着 Transformers 会执行模型仓库中的 Python 代码。
生产环境中不要盲目信任远程代码,建议固定模型 revision,审查代码,并在隔离环境中运行。
5.3 加载模型
创建 test_ocr.py:
import torch
from transformers import AutoModel, AutoTokenizer
MODEL_PATH = "./models/Unlimited-OCR-2"
print("Loading tokenizer...")
tokenizer = AutoTokenizer.from_pretrained(
MODEL_PATH,
trust_remote_code=True,
)
print("Loading model...")
model = AutoModel.from_pretrained(
MODEL_PATH,
trust_remote_code=True,
use_safetensors=True,
torch_dtype=torch.bfloat16,
)
model = model.eval().cuda()
print("Model loaded successfully!")
运行:
python test_ocr.py
这里有几个关键参数:
| 参数 | 作用 |
|---|---|
trust_remote_code=True | 加载仓库自定义模型实现 |
use_safetensors=True | 使用 Safetensors 权重 |
torch_dtype=torch.bfloat16 | 使用 BF16 精度 |
eval() | 切换到推理模式 |
cuda() | 将模型放到 GPU |
如果 GPU 不支持 BF16,不能简单认为这段代码可以直接运行,需要评估模型实现支持的其他精度及其兼容性。
5.4 单页图片 OCR
先准备一张图片:
test.jpg
执行:
text = model.infer(
tokenizer,
image_file="test.jpg",
output_path="./output/single",
save_results=True,
)
print(text)
这里的 infer() 默认使用 Gundam 模式进行动态切图。
官方给出的单页推理接口就是这种形式。
5.5 多页 PDF 文档 OCR
这才是 Unlimited-OCR 2 最值得关注的能力。
传统 OCR 往往会把 PDF 拆成多个图片,逐页调用 OCR,然后将结果拼接。
但 Unlimited-OCR 2 提供了专门的 infer_multi() 接口。
pages = [
"document/page_1.jpg",
"document/page_2.jpg",
"document/page_3.jpg",
"document/page_4.jpg",
]
text, num_tokens = model.infer_multi(
tokenizer,
image_files=pages,
output_path="./output/multi",
save_results=True,
)
print("Token count:", num_tokens)
print(text)
这里有一个很重要的区别:
infer():单页推理,默认使用动态切图。infer_multi():多页推理,将多页文档作为一次请求处理。
多页推理会自动构造类似下面的 Prompt:
<PAGE><image>
<PAGE><image>
<PAGE><image>
<PAGE><image>
Multi page parsing.
每页按输入顺序编码为一个全局视图,输出也按相同顺序包含对应的 <PAGE> 标记。
这意味着模型有机会理解不同页面之间的关联,而不是仅仅把多个独立 OCR 结果拼接起来。
注意:infer_multi() 的多页输入不等于没有页面数量和资源限制。实际处理能力仍然受到显存、输出长度和运行环境影响。
官方代码和说明:Unlimited-OCR README。
六、部署方式二:使用 SGLang 搭建推理服务
生产化部署优先研究此方案
如果你打算将 OCR 能力接入 Django、FastAPI、Java 或 Go 后端,我更推荐将模型独立部署成推理服务。
原因很简单:
- 模型只加载一次。
- 多个业务系统可以共享。
- 可以集中管理 GPU 资源。
- 可以统一处理并发和请求队列。
- 业务后端不需要依赖 PyTorch。
- 可以独立升级模型。
6.1 为什么选择 SGLang?
SGLang 是一个面向大模型推理和服务化的框架。
Unlimited-OCR 2 官方提供了专门的 SGLang 部署方案。
它不仅仅是把模型包一层 HTTP API,还涉及:
- 请求调度。
- 多请求并发。
- GPU 内存管理。
- CUDA Graph。
- 多页文档处理。
- 页面窗口调度。
需要注意,Unlimited-OCR 2 的官方方案使用了定制版 SGLang,不应直接认为普通最新版 SGLang 与它完全兼容。
6.2 安装 SGLang
进入项目:
git clone https://github.com/baidu/Unlimited-OCR.git
cd Unlimited-OCR
创建 Python 3.10 环境:
uv venv --python 3.10
source .venv/bin/activate
安装官方提供的定制版 SGLang:
uv pip install \
wheel/sglang-0.5.20.dev13+g75b9b06b02-py3-none-any.whl
安装其他依赖:
uv pip install pymupdf==1.27.2.2
uv pip install fastokens==0.3.2
为什么不直接安装普通 SGLang?
因为项目使用了与模型实现配套的自定义推理逻辑,版本不匹配可能导致模型加载、特殊 Token 处理或推理过程出现问题。
6.3 配置环境变量
官方给出了一组针对超长文档推理的参数:
export SGLANG_UOCR_EANABLE_DOC_LIMIT=1
export SGLANG_UOCR_DOC_GUNDAM_PAGE_WINDOW=10
export SGLANG_UOCR_DOC_BASE_PAGE_WINDOW=10
export SGLANG_UOCR_MAX_PAGE_TOKENS=20000
export SGLANG_OPT_UOCR_SAM_REL_POS_BIAS_MB=64
export SGLANG_UOCR_SHM_WRAP_MODEL_DATA=1
export SGLANG_UOCR_SHM_WRAP_MIN_MB=1
export SGLANG_VLM_CACHE_SIZE_MB=0
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
几个重要参数:
| 参数 | 作用 |
|---|---|
DOC_LIMIT | 是否启用文档页面窗口调度 |
GUNDAM_PAGE_WINDOW | Gundam 模式每个窗口的页数 |
BASE_PAGE_WINDOW | Base 模式每个窗口的页数 |
MAX_PAGE_TOKENS | 每页最大输出 Token 数 |
SAM_REL_POS_BIAS_MB | 限制相关注意力偏置分块内存 |
SHM_WRAP_MODEL_DATA | 大型模型数据通过共享内存传输 |
VLM_CACHE_SIZE_MB | 控制视觉模型缓存 |
expandable_segments | 缓解 CUDA 显存碎片问题 |
这里有个容易忽略的细节:
SGLANG_UOCR_EANABLE_DOC_LIMIT 的官方变量名确实是 EANABLE,不是通常认为的 ENABLE。使用官方代码时不要自行改名。
6.4 启动服务
执行:
python -m sglang.launch_server \
--model-path baidu/Unlimited-OCR-2 \
--served-model-name Unlimited-OCR-2 \
--chat-template unlimited-ocr \
--tokenizer-backend fastokens \
--tokenizer-worker-num 8 \
--mem-fraction-static 0.7 \
--max-running-requests 64 \
--max-prefill-tokens 2048 \
--enable-custom-logit-processor \
--enable-streaming-session \
--allow-auto-truncate \
--disable-radix-cache \
--mm-preprocess-cache-size-mb 0 \
--cuda-graph-backend-decode full \
--cuda-graph-max-bs-decode 64 \
--cuda-graph-backend-prefill full \
--cuda-graph-max-bs-prefill 16384 \
--cuda-graph-bs-prefill 1024 2048 \
--cuda-graph-config '{"prefill": {"backend": "full", "full_prefill_max_req": 64}}' \
--host 0.0.0.0 \
--port 10000
服务启动后:
http://127.0.0.1:10000
官方方案使用 OpenAI 兼容 API,可以通过 HTTP 接入其他语言的后端系统。
6.5 这些参数如何影响显存?
这里有几个值得架构师关注的参数。
--mem-fraction-static 0.7
控制用于模型权重及 KV Cache 等静态资源的显存比例。
官方指出,在 32 个以上并发请求的场景中,0.75 可能留下的运行时空间不足,而 0.7 是其给出的较稳定配置。
--max-prefill-tokens 2048
影响 Prefill 阶段的临时张量规模。
官方特别指出,从 4096 降到 2048,可以将对应峰值内存开销大约减半。
页面窗口大小
例如:
export SGLANG_UOCR_DOC_GUNDAM_PAGE_WINDOW=10
意味着 Gundam 模式下以 10 页为一个窗口进行调度。
窗口越小,峰值内存压力可能越低,但跨窗口的表格合并、内容关联也可能受到影响。
所以不要简单地把窗口调得越小越好。
这些参数需要根据实际 GPU 和文档类型进行测试。官方提供的配置是一个起点,不是所有机器都能直接照搬的最优参数。
官方完整启动参数见:GitHub README 的 SGLang 部署章节。
七、如何调用 OCR 服务?
现在我们已经有了一个独立的 OCR 推理服务。
接下来需要解决一个问题:后端如何把 PDF 图片发送给模型?
官方提供的是 OpenAI 兼容的多模态接口。
这里需要注意:虽然 API 形式兼容 OpenAI,但它不是普通的纯文本 Chat Completion。请求中需要包含图片内容和对应的特殊 Prompt。
7.1 PDF 转图片
先安装 PyMuPDF:
pip install pymupdf requests
编写 PDF 转图片函数:
import fitz
import os
def pdf_to_images(pdf_path, output_dir, dpi=200):
os.makedirs(output_dir, exist_ok=True)
doc = fitz.open(pdf_path)
image_paths = []
matrix = fitz.Matrix(dpi / 72, dpi / 72)
for i, page in enumerate(doc):
path = os.path.join(
output_dir,
f"page_{i + 1:04d}.jpg"
)
pix = page.get_pixmap(
matrix=matrix,
alpha=False
)
pix.save(path)
image_paths.append(path)
doc.close()
return image_paths
这里的 DPI 可以根据业务场景调整:
- 150 DPI:一般文字文档。
- 200 DPI:日常文档处理。
- 300 DPI:小字、印章、复杂表格等场景。
注意:分辨率越高,图像数据越大,显存和处理时间也可能增加。
7.2 图片 Base64 编码
官方接口使用图片 URL 的形式传递图片,可以直接使用 Base64 Data URL。
import base64
import os
def encode_image(image_path):
ext = os.path.splitext(image_path)[1].lower()
mime = (
"image/jpeg"
if ext in (".jpg", ".jpeg")
else f"image/{ext.lstrip('.')}"
)
with open(image_path, "rb") as f:
data = base64.b64encode(f.read()).decode("utf-8")
return {
"type": "image_url",
"image_url": {
"url": f"data:{mime};base64,{data}"
}
}
7.3 构建多页请求
def build_content(image_paths):
prompt = (
"<PAGE><image>" * len(image_paths)
+ "Multi page parsing."
)
content = [
encode_image(path)
for path in image_paths
]
content.append({
"type": "text",
"text": prompt
})
return content
这里有一个容易踩坑的地方:
<PAGE><image> 是模型使用的特殊提示格式,不是让我们把图片文件名放进 Prompt。
每张图片作为一个独立的图像内容传入,Prompt 中再标记页面数量和解析任务。
7.4 发送请求
官方示例中还使用了模型专用的 N-gram Logit Processor。
import requests
from sglang.srt.sampling.custom_logit_processor import (
DeepseekOCRNoRepeatNGramLogitProcessor
)
server_url = "http://127.0.0.1:10000"
ngram_processor = (
DeepseekOCRNoRepeatNGramLogitProcessor.to_str()
)
def recognize_document(image_paths):
payload = {
"model": "Unlimited-OCR-2",
"messages": [
{
"role": "user",
"content": build_content(image_paths)
}
],
"temperature": 0.0,
"max_tokens": 20000,
"extra_body": {
"custom_logit_processor": ngram_processor
}
}
response = requests.post(
f"{server_url}/v1/chat/completions",
json=payload,
timeout=600
)
response.raise_for_status()
return response.json()
这里的请求参数是基于官方 SGLang 调用方式整理的工程示例。实际部署时,需要与所使用的 SGLang 版本及模型模板核对,尤其是自定义 Logit Processor 参数的传递方式。
调用:
images = pdf_to_images(
"contract.pdf",
"./tmp/contract"
)
result = recognize_document(images)
print(result)
官方参考实现:
八、模型输出是什么格式?
这一点非常重要。
很多人会以为 OCR 模型最终返回 Markdown。
但 Unlimited-OCR 2 的原始输出并不是 Markdown,而是一种包含特殊标记的文档布局结构。
例如:
<PAGE>
<BLOCK>title<LEVEL1>
[100,100,900,200]
<FORK>
第一章 项目介绍
<BLOCK>text
[100,220,900,400]
<FORK>
这里是项目的正文内容...
<PAGE>
<BLOCK>title<LEVEL1>
...
其中:
| 标记 | 含义 |
|---|---|
<PAGE> | 新页面 |
<BLOCK> | 文档中的一个内容块 |
<LEVEL1> | 一级标题 |
<LEVEL2> | 二级标题 |
<FORK> | 内容与布局块之间的分隔 |
bbox | 内容块的坐标信息 |
cross_table | 跨页表格相关标记 |
append_table | 表格续接相关标记 |
这说明模型不仅在识别文字,还在输出文档的结构信息。
8.1 为什么需要后处理?
假设模型识别出了一张跨越三页的表格。
如果直接把三页的输出拼起来,可能得到三个不完整的表格。
但实际业务希望得到一张完整表格。
这就需要后处理。
百度官方仓库提供了:
utils/
+-- process_unlimitedOCR2.py
它可以把模型的原始输出转换成 Markdown。
主要处理:
- 按
<PAGE>分割页面。 - 根据
<LEVELn>恢复标题层级。 - 将图片、图表、印章等转换成图片引用。
- 保留表格 HTML。
- 合并跨页表格。
- 处理跨页内容续接。
- 清理多余特殊标记和异常结构。
8.2 使用官方后处理脚本
假设原始模型输出保存在:
raw/
+-- document1.txt
+-- document2.txt
+-- document3.txt
执行:
python utils/process_unlimitedOCR2.py \
--infer-dir raw \
--out-dir markdown
输出:
markdown/
+-- document1.md
+-- document2.md
+-- document3.md
也可以直接在 Python 中调用:
from process_unlimitedOCR2 import convert
markdown = convert(raw_output)
print(markdown)
这里特别推荐使用官方后处理,而不是自己简单地通过字符串替换删除特殊 Token。
因为跨页表格合并、标题层级恢复、阅读顺序等都有一定的逻辑复杂度。
官方说明:Unlimited-OCR 后处理文档。
九、如何集成到实际业务系统?
前面讲的是模型部署和调用。
对于后端工程师来说,真正重要的是如何将它变成一个可用的业务能力。
我建议采用下面这种架构。
9.1 推荐系统架构
Web / Mobile
|
v
API Gateway
|
v
Django / FastAPI
|
┌--------┴--------┐
| |
v v
MySQL Object Storage
任务信息 原始 PDF
状态记录 页面图片
OCR 结果 处理结果
|
v
Message Queue
|
v
OCR Worker
|
v
PDF 转图片
|
v
SGLang 推理服务
|
v
原始结构化结果
|
v
后处理
|
┌----┴-----┐
v v
Markdown HTML
| |
+----┬-----┘
v
MySQL / OSS
|
v
全文搜索 / RAG
这里有几个设计原则。
第一,模型服务和业务服务分离。
不要直接在 Django 的 Web 请求进程中加载 OCR 模型。
原因:
- 模型占用大量 GPU 显存。
- Web 请求不应该长期占用 GPU。
- 模型升级不应该影响业务 API。
- OCR 服务需要独立扩缩容。
第二,OCR 采用异步任务。
一个 100 页的 PDF 可能需要较长时间处理。
不能让用户一直等待 HTTP 请求返回。
建议:
POST /api/documents
上传文档,返回:
{
"task_id": "ocr_20261119_001",
"status": "pending"
}
然后:
GET /api/ocr/tasks/ocr_20261119_001
查询任务状态。
状态建议:
pending
|
v
preprocessing
|
v
processing
|
v
postprocessing
|
v
completed
失败时:
failed
同时记录失败原因、重试次数、模型版本和耗时。
第三,原始输出和后处理结果都要保留。
建议至少保存:
- 原始 PDF。
- 页面图片(可按策略清理)。
- 模型原始输出。
- Markdown 转换结果。
- HTML 表格。
- 模型版本。
- 处理耗时。
- Token 统计。
- 任务错误信息。
不要只保存最终 Markdown。
因为将来升级模型或者优化后处理算法时,原始输出可能非常有价值。
9.2 数据库设计参考
可以设计三张主要数据表。
ocr_documents:文档表
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 主键 |
| filename | VARCHAR | 文件名 |
| file_url | VARCHAR | 原始文件地址 |
| file_hash | VARCHAR | 文件 SHA256 |
| page_count | INT | 页面数量 |
| status | VARCHAR | 当前状态 |
| created_at | DATETIME | 创建时间 |
ocr_tasks:任务表
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 主键 |
| document_id | BIGINT | 文档 ID |
| model_name | VARCHAR | 模型名称 |
| model_version | VARCHAR | 模型版本 |
| status | VARCHAR | 任务状态 |
| retry_count | INT | 重试次数 |
| started_at | DATETIME | 开始时间 |
| finished_at | DATETIME | 完成时间 |
| error_message | TEXT | 错误信息 |
ocr_pages:页面结果表
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 主键 |
| task_id | BIGINT | 任务 ID |
| page_no | INT | 页码 |
| raw_content | LONGTEXT | 原始内容 |
| markdown | LONGTEXT | Markdown 内容 |
| layout_json | JSON | 页面布局信息 |
另外可以单独设计 ocr_blocks 表,用于保存标题、段落、表格、图片等内容块及其坐标。
是否需要拆分页面和 Block,取决于后续是否需要做文档可视化、内容定位和结构化检索。
十、与 RAG 知识库结合
这是我认为 Unlimited-OCR 2 非常有价值的一个应用方向。
以前构建企业知识库,经常是:
PDF
|
v
普通 OCR
|
v
纯文本
|
v
文本切片
|
v
Embedding
|
v
向量数据库
|
v
RAG
这种方式有一个问题:
文档结构丢失。
例如:
第三章 费用报销
3.1 住院医疗费用
3.1.1 报销范围
表格:
项目 | 报销比例 | 限额
...
如果直接把所有内容转换为纯文本,标题和表格之间的关系可能丢失。
Unlimited-OCR 2 可以提供更丰富的结构信息。
我建议改成:
PDF
|
v
Unlimited-OCR 2
|
v
文档结构解析
|
v
Markdown + HTML
|
v
结构化切片
|
+-- 标题路径
+-- 正文段落
+-- 表格
+-- 图片
+-- 页面位置
|
v
Embedding
|
v
向量数据库
|
v
RAG
10.1 如何设计文档切片?
举个例子:
原始文档:
第一章 医疗保险政策
1.1 住院医疗费用
1.1.1 报销比例
职工医保报销比例为 85%。
1.1.2 起付线
一级医院起付线为 200 元。
不要简单地按每 500 个字符切片。
建议保留标题路径:
{
"document_id": 1001,
"page_start": 10,
"page_end": 10,
"section_path": [
"第一章 医疗保险政策",
"1.1 住院医疗费用",
"1.1.1 报销比例"
],
"content": "职工医保报销比例为 85%。",
"content_type": "paragraph"
}
对于表格:
{
"document_id": 1001,
"page_start": 11,
"page_end": 12,
"section_path": [
"第一章 医疗保险政策",
"1.1 住院医疗费用"
],
"content_type": "table",
"content": "<table>...</table>"
}
这里要特别注意:跨页表格应当尽量保留为一个完整的逻辑单元,而不是在分页时直接切断。
10.2 结合实际业务:智能理赔系统
如果将它用在医疗保险理赔系统中,我认为可以承担三个任务:
任务一:医疗资料识别
- 医疗发票。
- 住院病历。
- 出院小结。
- 处方。
- 检查报告。
- 费用清单。
任务二:保险政策文档解析
例如:
- 医保目录。
- 商业保险条款。
- 报销规则。
- 医疗服务价格目录。
- 保险责任说明。
任务三:构建理赔知识库
将保险条款、医疗政策和业务规范转换为结构化知识,供后续 AI 审核使用。
不过要特别强调:
OCR 识别结果不能直接作为理赔依据。
例如发票金额、发票号码、医疗日期等关键字段,必须进行校验。可以采用规则引擎、交叉验证和人工复核,避免视觉模型的识别错误直接影响理赔结果。
对于金额、发票号码等字段,建议单独建立准确率评估集,逐字段统计识别准确率。
十一、Unlimited-OCR 2 的局限性
技术上很有意思,但不要把它理解为可以替代所有 OCR 产品。
我认为至少需要关注以下问题。
11.1 GPU 成本
这是一个视觉语言模型,不是轻量级 OCR 引擎。
如果业务只是每天识别几百张简单的发票,部署完整模型可能并不划算。
可以考虑:
- PaddleOCR 等传统 OCR 负责简单票据。
- Unlimited-OCR 负责复杂文档和多页 PDF。
- 通用 LLM 负责后续信息抽取和语义分析。
11.2 超长文档不代表准确率无限提升
SR-SWA 解决的是长上下文计算瓶颈,不意味着模型不会出现:
- 文字识别错误。
- 表格内容错位。
- 页面遗漏。
- 内容重复。
- 跨页关联错误。
- 视觉信息误判。
尤其是低分辨率扫描件、模糊印章、手写内容,需要单独测试。
11.3 输出需要后处理
原始输出包含特殊 Token 和布局信息。
如果要接入业务系统,需要建立自己的数据标准和转换逻辑。
不要把模型原始输出直接当成最终业务数据。
11.4 生产环境需要压力测试
至少需要测试:
| 测试项目 | 关注指标 |
|---|---|
| 单页 OCR | 延迟、准确率 |
| 10 页 PDF | 总耗时、跨页理解 |
| 50 页 PDF | 显存、吞吐量 |
| 100 页 PDF | 长文档稳定性 |
| 多任务并发 | GPU 利用率、排队时间 |
| 异常文件 | 超时、失败恢复 |
| 跨页表格 | 表格完整率 |
特别建议测试不同页数、不同分辨率和不同文档类型,而不是只用一份官方 Demo 测试。
十二、与其他 OCR 方案怎么选择?
工程选型时,我建议不要只看模型排行榜,而是根据实际业务需求选择。
| 方案 | 优势 | 适合场景 |
|---|---|---|
| PaddleOCR | 轻量、成熟、部署灵活 | 普通票据、图片文字 |
| Tesseract | 资源占用低、传统 OCR | 简单文字识别 |
| MinerU | 文档解析、PDF 转 Markdown | 学术论文、技术文档 |
| DeepSeek-OCR | 视觉语言模型文档解析 | 复杂文档理解 |
| Unlimited-OCR 2 | 超长文档、跨页结构解析 | 大型 PDF、档案、长报告 |
相关项目:
这里需要区分:这些项目的功能定位、输入输出和评测数据集不完全相同,不能简单根据表格认为某个方案在所有任务上都更好。
十三、学习和实践路线
如果你想真正掌握这个项目,我建议分成四个阶段。
第一阶段:跑通模型
- 准备 NVIDIA GPU 环境。
- 下载模型权重。
- Transformers 加载模型。
- 完成单页图片 OCR。
- 完成多页 PDF OCR。
目标:理解模型如何使用
第二阶段:研究模型输出
- 分析
<PAGE>、<BLOCK>、<FORK>。 - 研究坐标和页面布局。
- 研究跨页表格合并。
- 修改后处理脚本。
- 将结果转换成自定义 JSON。
目标:理解文档结构解析
第三阶段:部署推理服务
- 使用 SGLang。
- 调整显存参数。
- 接入 HTTP API。
- 测试并发请求。
- 测量吞吐量和延迟。
目标:掌握模型服务化
第四阶段:构建完整应用
- Django/FastAPI 后端。
- Redis + Celery 异步任务。
- MySQL 任务管理。
- OSS 文档存储。
- Markdown/HTML 解析。
- RAG 知识库。
目标:形成可实际使用的产品
十四、最后总结
我认为 Unlimited-OCR 2 值得关注的地方,并不是又出现了一个识别文字更准确的 OCR 模型。
而是它在尝试解决一个长期存在的问题:
如何让 AI 真正理解一份很长的文档,而不只是识别其中的一张图片或者某一页文字。
对于后端工程师和架构师来说,值得重点研究的有三个方向:
- 模型层: SR-SWA 如何降低超长文档的注意力计算开销。
- 推理层: SGLang 如何实现模型服务化、页面窗口调度和并发管理。
- 应用层: 如何把文档布局、跨页表格和语义结构转化为可检索、可计算的业务数据。
尤其是第三点。
过去我们做文档数字化,通常是 PDF 转图片、OCR 转文字、文字存数据库。
未来更有价值的方向,是将 PDF 转化成一份真正有结构、有层级、有语义关系的数字文档。
这也是它与 RAG、企业知识库、智能审核、文档自动化结合的价值所在。
官方资料与延伸阅读
- 1. GitHub 项目:baidu/Unlimited-OCR,源码、推理代码、部署说明、后处理工具及论文。
- 2. Hugging Face 模型:baidu/Unlimited-OCR-2,模型权重、模型卡、配置文件和推理示例。
- 3. 论文与技术研究
- Unlimited OCR 2 论文
- Unlimited OCR 第一代论文
- 4. 其他资源
- SGLang 官方文档
- Transformers 官方文档
注:本文依据截至 2026 年 11 月 19 日的项目说明整理。模型性能及硬件配置建议需要以实际部署和测试为准。项目及模型仓库标注 MIT License,正式商用前仍建议核对具体依赖的许可证。
我的一个建议: 如果要把这篇教程进一步变成真正能动手的项目,可以做一个「本地 PDF 智能解析平台」:上传 PDF → Unlimited-OCR 2 → Markdown/HTML → 文档结构化 → RAG 检索。这个项目能够同时覆盖模型部署、后端架构、异步任务、文件存储和 AI 应用开发,实践价值很高。