1. 痛点突围：它究竟击穿了什么工程死穴？

传统光学字符识别方案在面对长达数十页的复杂 PDF 文档时，普遍受制于单图尺寸暴增带来的显存溢出，或者多图拼接造成的局部语义丢失。研发团队为了切分文档往往需要编写冗余的切图脚本，这直接引发了上下文碎片化与版面恢复错乱。百度开源的 Unlimited-OCR 引入了 One-shot 长视距解析范式，将单页与多页文档输入统一到 Transformer 架构中，直接规避了传统流水线式 OCR 中间结果传递的损耗。

💡 架构核心洞见：通过原生支持 32768 超长上下文与自定义 Logit 处理器，该项目把长文档解析从“分块拼图”拉回了“大模型原生生成”的单次前向传播路径。

2. 核心架构与底层数据流向解析

系统底层通过 Python 运行环境调用 Hugging Face Transformers 或 SGLang 后端，将输入图像转化为张量并通过 infer 或 infer_multi 接口分发。PyMuPDF 负责将高分辨率 PDF 转换为标准 PNG 图像序列，输入端根据配置项切换 gundam 或 base 渲染模式。计算图在执行时利用注意力后端与 N-gram 重复抑制逻辑，防止大文本生成过程中的死循环与显存吞噬。

[ PDF / Image Input ] ---> [ PyMuPDF / fitz Parser ] ---> [ Image Array / Tensor ]
                                                                  │
                                                                  ▼
[ SGLang / vLLM Server ] <--- [ Tokenizer / Prompt Engine ] <--- [ Config Router (gundam/base) ]
        │
        ▼
[ Custom Logit Processor (No-Repeat N-gram) ] ---> [ 32768 Context Window Output ]

在底层权衡方面，项目舍弃了轻量级但对复杂表格无能为力的传统 CNN 分割架构，转而拥抱高算力开销的视觉语言大模型底座。这种权衡牺牲了边缘设备的推理速度，但在数据中心或高端 GPU 集群上换取了近乎完美的版面恢复精度与跨页语义连贯性。

3. 技术选型与性能横向硬核对比

选型维度 本方案 (Unlimited-OCR) 传统实现范式 典型竞品方案 生产环境收益
长文档支持 原生支持多页并行与 32k 上下文 单页切块输入，强依赖外部拼接 依赖多轮对话拼接，Token 消耗大 杜绝长文本截断与上下文丢失
推理后端生态 原生支持 vLLM、SGLang、Transformers 依赖定制化 C++ 推理引擎 仅绑定特定厂商云端 API 极大降低私有化集群部署改造门槛
版面还原能力 端到端视觉大模型直接输出结构化文本 需串联版面分析、OCR 与规则解析 传统多阶段流水线误差累积严重 显著减少人工校验与清洗成本
训练与微调 深度对接 ms-swift 社区生态 封闭黑盒，无法进行私有数据微调 仅提供固定权重下载 满足垂直行业高精度定制需求

表格背后的技术选型逻辑非常清晰。Unlimited-OCR 并没有重复造轮子去写底层的算子优化，而是直接站在 vLLM 和 SGLang 两个现代高性能推理巨人的肩膀上，把主要精力集中在视觉长序列建模与自定义 Logit 惩罚器的工程实现上。

4. 手把手极客实操：从零构建最小闭环

生产环境推荐采用 Python 3.12.3 搭配 CUDA 12.9 运行环境。首先克隆并安装依赖包，确保 PyTorch 与 Transformers 版本匹配。

# 创建虚拟环境并安装核心依赖
uv venv --python 3.12
source .venv/bin/activate

uv pip install torch==2.10.0 torchvision==0.25.0 transformers==4.57.1 Pillow==12.1.1 pymupdf==1.27.2.2

以下是基于 Hugging Face Transformers 运行单图与多页 PDF 解析的最小生产级 Python 脚本：

import os
import torch
import fitz  # PyMuPDF 库，用于将 PDF 页面转换为高精度图像
from transformers import AutoModel, AutoTokenizer

model_name = 'baidu/Unlimited-OCR'

# 加载对应的 Tokenizer 并开启远程代码信任
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)

# 以 bfloat16 精度加载模型权重并挂载至 CUDA 设备
model = AutoModel.from_pretrained(
    model_name,
    trust_remote_code=True,
    use_safetensors=True,
    torch_dtype=torch.bfloat16,
).eval().cuda()

# 定义 PDF 转图像函数，DPI 设置为 300 以保证 OCR 识别清晰度
def pdf_to_images(pdf_path, dpi=300):
    doc = fitz.open(pdf_path)
    import tempfile
    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

# 执行多页 PDF 文档的端到端解析
image_files = pdf_to_images('sample_document.pdf', dpi=300)

model.infer_multi(
    tokenizer,
    prompt='<image>Multi page parsing.',
    image_files=image_files,
    output_path='./output_results',
    image_size=1024,
    max_length=32768,
    no_repeat_ngram_size=35,
    ngram_window=1024,
    save_results=True,
)

运行上述脚本后，模型将在指定的 ./output_results 目录中生成结构化解析文本，同时自动处理长文本生成的内存回收。

5. 生产落地踩坑指南与避坑建议 (Gotchas)

在将该项目部署至高并发生产环境时，务必注意硬件资源分配与长序列带来的显存峰值波动。

⚠️ 避坑预警 1：显存溢出与图像分辨率失控： 在处理超大尺寸图纸或高 DPI PDF 时，若直接使用 base 模式全分辨率输入（image_size=1024 且多页并发），极易触发 CUDA Out of Memory。生产环境中务必根据 GPU 显存大小（建议最低配置 A100/H100 80G）严格限制单次输入的页数，或切换至 gundam 裁剪模式降低单步显存占用。

⚠️ 避坑预警 2：N-gram 惩罚参数配置不当引发死循环： 大模型在处理长尾排版或含有大量重复表格线的长文档时，容易陷入局部文本陷入重复生成的死循环。调用推理接口时必须显式配置 no_repeat_ngram_size=35 与 ngram_window=1024（多页模式），切勿使用默认的无约束采样参数。