baidu/Unlimited-OCR · 上手攻略

  • 仓库：baidu/Unlimited-OCR
  • 链接：https://github.com/baidu/Unlimited-OCR
  • 分类：multimodal · document-parsing · OCR
  • 作者：Tom
  • 更新：2026-07-06

这是什么

Unlimited-OCR 是百度开源的多模态文档解析模型，定位是「一键长文档解析」——单张图片、PDF 多页、整本手册均可一次性处理，输出结构化文本。发布于 2026 年 6 月，arXiv 论文编号 2606.23050。

官方将其定位为对 DeepSeek-OCR 的进一步推进，核心能力：

  • 单图 OCR：发票、截图、照片、扫描件均可
  • 多图/多页 PDF 解析：一次性输入多张图片，输出一致的结构化文本
  • 长文档端到端：最大上下文 32768 tokens，覆盖整本手册或长报告
  • 多平台部署：HuggingFace Transformers / vLLM / SGLang / ModelScope / 百度云

解决什么问题

传统 OCR + NLP 管道有三个常见痛点：

  1. 多步骤串联：检测→切分→识别→后处理，每步独立，误差会累积
  2. 长文档处理差：大多数方案只能单页处理，多页一致性无法保证
  3. 版面理解弱：表格、多栏、图文混排的文档容易被错误拆行

Unlimited-OCR 的思路是用一个端到端多模态模型直接输出结构化文本，跳过传统 OCR 的多步骤管道，对长文档的跨页一致性也有专门设计（ngram_window 机制减少重复）。

快速安装

依赖环境

  • Python 3.12.3+（官方测试环境）
  • CUDA 12.9+（NVIDIA GPU）
  • 依赖包（官方 requirements 测试版本）：
torch==2.10.0
torchvision==0.25.0
transformers==4.57.1
Pillow==12.1.1
matplotlib==3.10.8
einops==0.8.2
addict==2.4.0
easydict==1.13
pymupdf==1.27.2.2
psutil==7.2.2

安装模型（Transformers 方式）

import os
import torch
from transformers import AutoModel, AutoTokenizer

model_name = 'baidu/Unlimited-OCR'

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,
)
model = model.eval().cuda()

⚠️ 模型首次加载会从 HuggingFace Hub 下载约数 GB 的权重，请确保网络通畅。

核心用法

单图推理（支持两种配置）

# gundam 配置（推荐文档）：base_size=1024, image_size=640, crop_mode=True
model.infer(
    tokenizer,
    prompt='<image>document parsing.',
    image_file='your_image.jpg',
    output_path='your/output/dir',
    base_size=1024, image_size=640, crop_mode=True,
    max_length=32768,
    no_repeat_ngram_size=35, ngram_window=128,
    save_results=True,
)

# base 配置（通用）：base_size=1024, image_size=1024, crop_mode=False
model.infer(
    tokenizer,
    prompt='<image>document parsing.',
    image_file='your_image.jpg',
    output_path='your/output/dir',
    base_size=1024, image_size=1024, crop_mode=False,
    max_length=32768,
    no_repeat_ngram_size=35, ngram_window=128,
    save_results=True,
)

多图/多页解析（仅 base 配置）

model.infer_multi(
    tokenizer,
    prompt='<image>Multi page parsing.',
    image_files=['page1.png', 'page2.png', 'page3.png'],
    output_path='your/output/dir',
    image_size=1024,
    max_length=32768,
    no_repeat_ngram_size=35, ngram_window=1024,
    save_results=True,
)

PDF 解析（完整流程）

import os, tempfile, fitz  # PyMuPDF

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

model.infer_multi(
    tokenizer,
    prompt='<image>Multi page parsing.',
    image_files=pdf_to_images('your_doc.pdf', dpi=300),
    output_path='your/output/dir',
    image_size=1024,
    max_length=32768,
    no_repeat_ngram_size=35, ngram_window=1024,
    save_results=True,
)

关键参数说明

参数 含义 推荐值
image_size 输入图像处理尺寸 640（gundam）/ 1024（base）
crop_mode 是否裁剪切分 True（gundam）/ False（base）
max_length 最大输出 token 数 32768（长文档建议用满）
no_repeat_ngram_size 防止重复 ngram 大小 35（文档）/ 10（对话）
ngram_window 重复检测窗口大小 128（单图）/ 1024（多页）
save_results 是否保存结果到 output_path True

部署方案

vLLM（生产级推理）

官方提供 Docker 镜像：

# 默认 CUDA 13.0
docker pull vllm/vllm-openai:unlimited-ocr

# Hopper GPU（CUDA 12.9）
docker pull vllm/vllm-openai:unlimited-ocr-cu129

参考：vLLM 官方部署指南

SGLang（推荐生产部署）

uv venv --python 3.12
source .venv/bin/activate
uv pip install wheel/sglang-0.0.0.dev11416+g92e8bb79e-py3-none-any.whl
uv pip install kernels==0.11.7
uv pip install pymupdf==1.27.2.2

python -m sglang.launch_server \
    --model baidu/Unlimited-OCR \
    --served-model-name Unlimited-OCR \
    --attention-backend fa3 \
    --page-size 1 \
    --mem-fraction-static 0.8 \
    --context-length 32768 \
    --enable-custom-logit-processor \
    --disable-overlap-schedule \
    --skip-server-warmup \
    --host 0.0.0.0 \
    --port 10000

批量推理脚本

# 图片目录
python infer.py \
    --image_dir ./examples/images \
    --output_dir ./outputs \
    --concurrency 8 \
    --image_mode gundam

# PDF
python infer.py \
    --pdf ./examples/document.pdf \
    --output_dir ./outputs \
    --concurrency 8 \
    --image_mode gundam

常用选项：--model_dir（本地路径或 HuggingFace ID）、--gpu（CUDA_VISIBLE_DEVICES）、--server_log（SGLang 日志路径）。

典型适用场景

  • 长文档数字化：整本手册、报告、政策文件的一键 OCR，输出可搜索文本
  • PDF 批量转结构化文本：取代传统 OCR 软件 + NLP 后处理管道
  • 企业文档处理：发票、合同、表单的多页批量解析
  • AI 应用后端：作为 RAG 系统的文档解析前端，将图片/PDF 转为 LLM 可处理的文本

坑与注意

  1. Python 版本敏感：官方测试环境为 Python 3.12.3，使用 3.11 以下版本可能遇到兼容性问题
  2. CUDA 版本：生产部署推荐 CUDA 12.9 或 13.0，低于 12.6 可能无法运行 bf16 推理
  3. GPU 显存需求：长文档（max_length=32768）显存占用较大，建议 24GB+ 显存的卡（如 A100、RTX 4090）
  4. ngram_window 多页要调大：文档说明多页场景窗口应从 128 增大到 1024，混用会导致跨页重复输出
  5. PyMuPDF 版本锁定 1.27.2.2：新版本 API 可能有细微差异，建议严格按官方版本安装
  6. trust_remote_code=True 必要：模型使用自定义前向传播，必须开启此参数

与同类对比

模型 发布方 上下文 多页支持 部署方式
Unlimited-OCR 百度 32768 ✅ 原生多图 Transformers / vLLM / SGLang
DeepSeek-OCR DeepSeek 较大 ✅ API
PaddleOCR 百度飞桨 单页为主 需拼接管道 Python SDK
GPT-4o Vision OpenAI 128k tokens ✅ API

核心差异：Unlimited-OCR 是开源自托管方案里少有的原生多页 + 长上下文 OCR 模型，不需要调用商业 API，适合企业内网部署和数据隐私敏感场景。

一句话结论

需要在本地/内网处理大量图片或 PDF 文档，且希望获得跨页一致的长文档 OCR 能力？Unlimited-OCR 是目前最值得评估的开源选择——支持 Transformers 直接加载和 vLLM/SGLang 生产部署。

数据来源：GitHub README（2026-07-03）、arXiv 论文 2606.23050（2026-06-23）、HuggingFace 模型页、vLLM Recipes 页面。torch 2.10.0、transformers 4.57.1 等具体版本号为官方测试环境版本，实际使用请以仓库 README 最新说明为准。