Unlimited OCR 2 上手指南 三分钟知道它是什么，半小时把它跑起来，一张能贴在评审会上的「该不该用」判定表。

01它是什么

先把它从「又一个 OCR」里择出来：它不是把识别率做得更高的 OCR，而是把「一份文档」当成一次推理单位来处理的文档解析模型。

一句话定义

输入是按页序排好的一组页面图像（或由 PDF 转成的页图），输出是整篇文档的版面块序列：每个块带类型（标题/正文/表格/公式/图注）、标题层级、归一化位置框，以及跨页的延续标记。它返回的不是一段干净正文，而是一棵能还原成 Markdown 的结构。

三个数字记住它的工作原理

这三件事由两个不同机制负责，官方叙述里常被并排讲，容易误当成一个机制：640 是稀疏注意力（SR-SWA）管算力，1.77 GB 是分窗解码管显存。二者独立可拆。深度技术分析见另一份报告，这里不展开。

它的输出长什么样

下面这段是真实格式（取自官方 utils/README.md），一页一个 <PAGE>，块与块之间靠 <BLOCK> 分隔，块头与内容用 <FORK> 断开：

模型原始输出（未后处理）

<PAGE><BLOCK>title<LEVEL1>[120,88,880,142]<FORK>第三章 资产减值
<BLOCK>text[120,160,880,268]<FORK>本公司于每一资产负债表日对长期资产判断是否存在减值迹象……
<BLOCK>cross_table[120,300,880,610]<FORK><table><tr><td>项目</td><td>期末余额</td></tr>……
<PAGE><BLOCK>append_table[120,90,880,420]<FORK><table><tr><td>项目</td><td>期末余额</td></tr>……

跑一次 process_unlimitedOCR2.py 之后：

后处理输出（Markdown）

# 第三章 资产减值

本公司于每一资产负债表日对长期资产判断是否存在减值迹象……

<!-- 两个 cross_table / append_table 片段已合并，重复的表头行已自动去重 -->
<table><tr><td>项目</td><td>期末余额</td></tr>……</table>

注意最后一段：表格在 Markdown 里仍然是 HTML，跨页片段被拼成一张表并干掉了重复表头。这正是它相对「逐页识别再拼接」的核心价值——合并逻辑是模型在原生长上下文里做出的，不是你在后处理里猜的。

和你熟悉的三条路的分工

它不是「更强的 OCR」，是一条不同的取舍线。放在一起看最清楚：

把它放进血统里看得更明白：DeepSeek-OCR 证明了「用视觉 token 压缩页面」这条路可行，Unlimited OCR（一代）把文本侧的长上下文问题解决了一半、卡在 40 页，二代把视觉侧也拆掉，才有了「页数不再是硬上限」。所以二代相对一代的唯一实质提升就是长文档——单页几乎没动（OmniDocBench 93.92 → 94.02）。

五个名词，知道结论就够

02怎么跑

整条链路有四段，每段都会静默失败。先看清楚失败点在哪，再动手。

三条路线，先选一条

不要一上来就部署 SGLang。先按你要验证的问题选路线——80% 的人只需要路线 A 就能做完决策。

路线 A · Transformers 直跑

官方在 Python 3.10 / torch==2.13.0 / transformers==4.52.1 / A800-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

加载一次，然后直接调两个方法：

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()

# 多页：一次请求吃完整篇，跨页上下文才在
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)

# 单页：默认走 gundam（动态切块），精度更高
text = model.infer(tokenizer, image_file="your_doc/page_1.jpg",
                   output_path="output/single", save_results=True)

路线 B · SGLang 服务化

SGLang 那条路有个隐藏门槛：必须用仓库自带的定制 wheel（sglang-0.5.20.dev10+g8d62f5fb9c），和你现有的环境大概率版本冲突。所以第一步永远是独立虚拟环境：

uv venv --python 3.10
source .venv/bin/activate

uv pip install wheel/sglang-0.5.20.dev10+g8d62f5fb9c-py3-none-any.whl
uv pip install pymupdf==1.27.2.2
uv pip install fastokens==0.3.2

然后用一组环境变量把显存按住——这一段是“不设就 OOM”的部分，不是调优：

# 分窗调度：1 = 开，0 = 整文档塞一个窗口（千页级必炸）
export SGLANG_UOCR_EANABLE_DOC_LIMIT=1
export SGLANG_UOCR_DOC_GUNDAM_PAGE_WINDOW=10   # gundam 每窗页数
export SGLANG_UOCR_DOC_BASE_PAGE_WINDOW=10     # base 每窗页数
export SGLANG_UOCR_MAX_PAGE_TOKENS=20000        # 每页输出上限

# SAM 注意力偏置的分块上限：默认 512 会一次要 ~462 MiB 连续显存并可能 OOM
export SGLANG_OPT_UOCR_SAM_REL_POS_BIAS_MB=64
# 大 crop 张量走 /dev/shm，绕开 tokenizer → scheduler 的 pickle
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

启动服务（关键参数已按官方建议调到保守值，尖括号内是场景相关）：

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

请求怎么拼

服务起好后是 OpenAI 兼容接口。下面这段是从官方示例精简出的最小可用客户端，带三处必须写对的地方：

import base64, json, os, tempfile
import fitz, requests
from sglang.srt.sampling.custom_logit_processor import DeepseekOCRNoRepeatNGramLogitProcessor

server_url = "http://127.0.0.1:10000"
NGRAM = DeepseekOCRNoRepeatNGramLogitProcessor.to_str()
session = requests.Session()
session.trust_env = False          # ① 绕开系统代理，否则本机 127.0.0.1 也会被代理吞掉

def pdf_to_images(pdf_path, dpi=300):
    doc = fitz.open(pdf_path)
    tmp = tempfile.mkdtemp(prefix="pdf_ocr_")
    mat = fitz.Matrix(dpi / 72, dpi / 72)
    out = []
    for i, page in enumerate(doc):
        p = os.path.join(tmp, f"page_{i + 1:04d}.png")
        page.get_pixmap(matrix=mat).save(p)
        out.append(p)
    return out

def build_content(paths):
    prompt = "<PAGE><image>" * len(paths) + "Multi page parsing."   # ② 页数必须与图数严格相等
    parts = []
    for p in paths:
        b64 = base64.b64encode(open(p, "rb").read()).decode()
        parts.append({"type": "image_url",
                      "image_url": {"url": f"data:image/png;base64,{b64}"}})
    return parts + [{"type": "text", "text": prompt}]

def generate(paths, crop_mode=True, tokens_per_page=8000):
    payload = {
        "model": "Unlimited-OCR-2",
        "messages": [{"role": "user", "content": build_content(paths)}],
        "max_tokens": tokens_per_page * len(paths),   # ③ 全篇总预算，不是每页
        "temperature": 0,
        "skip_special_tokens": False,              # 关掉就丢 <PAGE>，页码全错
        "images_config": {"crop_mode": crop_mode},   # True=gundam  False=base
        "custom_logit_processor": NGRAM,
        "custom_params": {
            "ngram_size": 35,
            "window_size": 1024 if len(paths) > 1 else 128,  # 防复读
            "page_token_id": 128827,
            "eos_token_id": 1,
            "max_page_tokens": 20000,
        },
        "stream": True,
    }
    r = session.post(f"{server_url}/v1/chat/completions", json=payload,
                     timeout=6000, stream=True)
    r.raise_for_status()
    chunks = []
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        data = line[5:].strip()
        if data == "[DONE]":
            break
        ev = json.loads(data)
        for c in (ev.get("choices") or []):
            chunks.append((c.get("delta") or {}).get("content") or "")
    return "".join(chunks)

raw = generate(pdf_to_images("your_doc.pdf", dpi=300))

后处理：把它变成能用的 Markdown

两种用法，批量跑还是嵌进代码：

# 批量：把一个目录下的原始输出（.txt/.md）全转成 Markdown
python utils/process_unlimitedOCR2.py --infer-dir raw --out-dir pred

# 嵌进流水线
from process_unlimitedOCR2 import convert
markdown = convert(raw_output)

它认得的块类型一共这些，看懂这张表你就知道能从输出里拿到什么：

参数速查：每一个都写清楚“动了会怎样”

排错：症状 → 原因 → 处置

验收清单：一天走完，别省第 3 步

• 1 · 拿你自己最长的一份文档跑通务必 > 100 页。单页一次、多页一次，都要出结果。通过标准：结构肉眼可读，不是“没报错”。
• 2 · 抽 6 处跨页结构逐字核对3 处跨页表格（表头去重、列对齐）+ 3 处跨页段落（有没有被截断/重复）。这是它唯一不可替代的能力，不过关就别往下走。
• 3 · 做「块边界 vs 块内部」的分层对比官方材料没做这一项。按页位置抽边界页与内部页各 10 页，算编辑距离；差距 < 2 个百分点可接受，明显偏大说明窗口要调大。这一步决定你敢不敢上生产。
• 4 · 压一次并发，记录 TPS 与峰值显存B=16 下与官方 1,315 TPS / 1.77GB KV 同量级即可；差一个数量级说明参数没调对，不是模型不行。
• 5 · 跑一遍你的真实后处理页眉页脚、公式包裹、标题树、图片切图——四件事各验一遍。这一步最容易被跳过，也最容易在上线后暴露。

03什么时候用

一句话：页数够多、且文档的结构价值大于文字价值时用它。这两条缺一条，它就不如你现有的方案。

先过三个问题，再谈部署

六个它确实值钱的场景

五个明确别用的场景

成本粗算：先算清“每千页”再谈采购

官方给的吞吐是 1,315 TPS @ B=16（A800-80GB）。按每页约 1,000 个输出 token 反推，单卡理论上限约 4,700 页/小时；扣掉 PDF→图（300 dpi 单页约 0.2–0.4 秒 CPU）、prefill、排队与重试，实际按 40–60% 折算更稳。下面全部是算术推算，不是实测。

把它换成钱只有一个公式：每千页成本 ≈ (1000 ÷ 单卡小时页数) × 你的卡时单价。按 2,500 页/卡时算，每千页约 0.4 卡时——卡时单价你自己代入，因为租用与自建、包月与按量的差别比模型本身的差别还大。

04边界与风险

这一节不是唱衰，是把“上线后才会发现”的事提前摆到桌面上。

05速查附录

入口与一手材料

关键常量（写死在代码里，别猜）

最小可行代码骨架

# 1. PDF → 页图（300 dpi）           fitz.Matrix(300/72, 300/72)
# 2. 页图 → 原始块串                  POST /v1/chat/completions，stream=True
# 3. 块串 → Markdown                  convert(raw) 或 process_unlimitedOCR2.py
# 4. 你的业务                         按 # 标题切块 / pd.read_html 取表 / bbox 裁图

from process_unlimitedOCR2 import convert
md = convert(raw)                      # 别忘了这一步，否则拿到的是块语法
open("doc.md", "w").write(md)

一句话记忆卡