Unlimited-OCR 使用教程

📖 项目简介

Unlimited-OCR（无限 OCR） 是百度在 2026 年 6 月开源的端到端文档解析大模型，一发布就冲上 GitHub 热榜、狂揽 14K+ Star，采用最宽松的 MIT 协议，完全免费可商用。

它以 DeepSeek-OCR 为基线打造，是一个总参数 3B、实际激活仅 5 亿的混合专家（MoE）模型。最大的突破是把解码器里的标准注意力全部换成了自研的 R-SWA（参考滑动窗口注意力）：无论输出多长，KV 缓存都保持恒定大小，因此能在标准 32K 上下文里一口气读完几十页、甚至整本书，速度还不会随长度衰减。

在权威文档解析基准 OmniDocBench v1.5 上，它以 93% 的总分拿下端到端 SOTA，比 DeepSeek-OCR 高出整整 6 个百分点。合同、发票、扫描件、手写笔记、带公式和表格的论文，都能原样还原成 Markdown。把它的输出丢给 Codex，就等于给 AI 编程装上了「读文档」的能力——任何文档都能秒变结构化文字，供 Codex 总结、检索、二次加工。

📎 相关链接与下载地址（点击展开）

GitHub 项目： github.com/baidu/Unlimited-OCR
Hugging Face 模型： huggingface.co/baidu/Unlimited-OCR
ModelScope 魔搭： modelscope.cn/models/PaddlePaddle/Unlimited-OCR
更多教程：关注公众号 / 抖音 / 视频号「IT小圈」

✨ 核心亮点

📚

长文档一口气读完

R-SWA 恒定 KV 缓存，32K 上下文内单次读完 40+ 页，整本书都不在话下

🥇

端到端 SOTA

OmniDocBench v1.5 拿下 93% 总分第一，比 DeepSeek-OCR 高 6 个百分点

⚡

速度不衰减

总参 3B 仅激活 5 亿，输出越长越省，长文档比 DeepSeek-OCR 快约 35%

📊

版式全还原

表格、数学公式、多栏排版、手写字，统统原样转成 Markdown

🧩 它能读什么、输出什么

项目	说明
输入格式	常见图片（PNG / JPG / JPEG 等）、多页 PDF（自动逐页转图片再解析）
文档类型	合同、发票、报销单、扫描件、书籍、论文、报表、PPT/截图、手写笔记等
版式还原	标题层级、正文段落、表格、数学公式（LaTeX）、多栏排版、图注
输出格式	干净的 Markdown（表格转 Markdown 表格、公式转 LaTeX），可直接进笔记 / Word / Codex
语言	中文、英文及混排文档，长文档、复杂版式尤其擅长
单次容量	标准 32K 上下文下，一次前向即可读完 40+ 页；配合 R-SWA，整本书也能连续解析

🖥️ 环境要求

环境	建议配置
操作系统	Linux（推荐）/ Windows（WSL2）/ macOS（Apple Silicon 可用 MLX 方案）
Python	3.10 及以上
显卡	NVIDIA GPU；模型总参 3B、激活仅 5 亿，显存占用友好，8GB 显存起步的消费级显卡即可跑（长文档、并发越多越吃显存）
无显卡	可用带 GPU 的云服务器；或用 Ollama / llama.cpp 的量化版在较低配置上体验
关键依赖	`torch`、`transformers`、`accelerate`；跑 PDF 需 `pdf2image`+`pillow`；生产部署可用 `sglang` 或 `vllm`

🚀 如何使用

💡

下面按「装环境 → 下模型 → 单张图 → 批量/PDF → 交给 Codex」五步走。只想快速体验的话，用 Ollama 拉量化版最省事；追求速度和精度就用下面的原生 / SGLang 方案。

准备 Python 环境

建议 Python 3.10+，装好 PyTorch（对应你的 CUDA 版本）和推理依赖：

                        bash
                        conda create -n ocr python=3.10 -y
conda activate ocr

# 安装 PyTorch（按自己的 CUDA 版本选择）+ 推理依赖
pip install torch transformers accelerate
# 处理 PDF 需要额外装（把每页转成图片）
pip install pdf2image pillow
                    

下载模型权重

在 Hugging Face 或国内的 ModelScope 魔搭搜索 baidu/Unlimited-OCR，把模型权重拉到本地。国内网络推荐用魔搭，速度更快：

                        bash
                        # 方式一：Hugging Face
pip install -U huggingface_hub
huggingface-cli download baidu/Unlimited-OCR --local-dir ./Unlimited-OCR

# 方式二：ModelScope（国内更快）
pip install -U modelscope
modelscope download --model PaddlePaddle/Unlimited-OCR --local_dir ./Unlimited-OCR
                    

跑一张图 / 一份 PDF

克隆仓库后，参照 README 里的示例脚本加载模型，喂入图片或 PDF，即可把文档转成 Markdown。核心流程如下（以仓库 README 最新示例为准）：

                        python
                        from transformers import AutoModel, AutoTokenizer

model_path = "./Unlimited-OCR"
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
model = AutoModel.from_pretrained(
    model_path, trust_remote_code=True
).eval().cuda()

# 单张图片：把文档图片解析成 Markdown
result = model.infer(tokenizer, image_file="contract.png")
print(result)

# 多页 PDF：先把每页转成图片，再逐页/整篇解析
# from pdf2image import convert_from_path
# pages = convert_from_path("report.pdf")
                    

✅

输出的是干净的 Markdown：标题、正文、表格、公式一应俱全，可直接复制进笔记、Word，或交给下一步的 Codex。

infer() 常用参数说明：

参数	作用
`prompt`	任务指令，文档解析用 `<image>document parsing.`；多页用 `Multi page parsing.`
`image_file`	输入图片路径（单张）
`output_path`	结果保存目录（配合 `save_results=True`）
`base_size` / `image_size`	图片预处理分辨率，越大越清晰、越吃显存，默认 `1024` / `640`
`crop_mode`	是否切图分块处理，大图 / 长文档建议设 `True`
`max_length`	最大输出长度，长文档设到 `32768`
`no_repeat_ngram_size` / `ngram_window`	抑制重复的关键参数，官方推荐 `35` / `128`，遇到重复输出别乱改

🎛️

两种图片模式：gundam 模式精度更高、适合复杂版式和长文档（推荐）；base 模式更快更省显存，适合简单文档或显存吃紧时。

批量处理整个目录 / 多页 PDF

仓库自带 infer.py，会自动拉起 SGLang 服务并并发处理一整个图片目录或一份多页 PDF，适合成批扫描件、整本 PDF 的场景：

                        bash
                        # 处理一整个图片目录（并发 8）
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
                    

⚙️

--concurrency 是同时处理的并发数：显存大就调高、加速批量任务；显存小就调低防止 OOM。结果按文件名逐个写进 --output_dir。

让 Codex 调用它

有两种方式把这份 OCR 能力交给 Codex：

① 最简单——Codex 直接跑命令：Codex CLI 本身能执行 shell 命令，直接让它调用仓库自带的 infer.py（支持整个图片目录或 PDF），把文档转成 Markdown 拿回来：

                        bash
                        # 批量把一个 PDF 解析成 Markdown（仓库自带脚本）
python infer.py --pdf ./report.pdf --output_dir ./outputs --image_mode gundam
                    

② 进阶——起一个本地 OpenAI 兼容服务：用自带的 SGLang / vLLM 把模型跑成一个标准 /v1/chat/completions 接口，Codex（或任意支持 OpenAI API 的客户端）像调用普通多模态模型一样发图片、收 Markdown：

                        bash
                        # 启动本地 OpenAI 兼容服务
python -m sglang.launch_server --model baidu/Unlimited-OCR \
    --served-model-name Unlimited-OCR --context-length 32768 \
    --enable-custom-logit-processor --port 10000
                    

🔌

想更丝滑，可以给它套一层 OCR 类 MCP 服务（基线 DeepSeek-OCR 已有支持 Codex CLI 的现成 MCP，把端点指到本地 Unlimited-OCR 即可），在 ~/.codex/config.toml 里注册后，Codex 就能把「读文档」当成一个内置工具随时调用。

✅

这样一来，一张扫描件 / 一份合同就变成了 Codex 能理解、能操作的结构化文字——总结要点、提取字段、生成表格、写成代码或报告，全交给它。

🎯 典型应用场景

📑

合同 / 发票数字化

扫描件、拍照的合同发票批量转文字，再交给 Codex 提取金额、条款、字段入表

📚

长文档 / 整本书解析

几十页的报告、论文、书籍一次读完，转成 Markdown 便于检索和二次编辑

✍️

手写笔记整理

手写笔记、白板照片转成可编辑文字，告别手动誊抄

🧮

论文公式 / 表格

数学公式转 LaTeX、表格转 Markdown，理工科资料整理利器

🤖

喂给 AI 编程

把文档转成结构化文字丢给 Codex，让它读需求文档、写代码、出报告

🔒

本地私有部署

完全本地运行，敏感文档不出本机，合规又安心

📈 性能表现

指标	表现
OmniDocBench v1.5 总分	约 93%，端到端 SOTA，比 DeepSeek-OCR 高约 6 个百分点
OmniDocBench v1.6	约 93.9%，可媲美甚至超过体量大数十倍的模型
长输出速度	6000 token 输出时比 DeepSeek-OCR 快约 35%，且不随长度衰减
长程解析	可一次解析 40+ 页，编辑距离低于 0.11
模型体量	总参 3B、激活仅 5 亿（MoE），显存友好

🧠

秘诀是 R-SWA（参考滑动窗口注意力）：每生成一个 token 只关注「全部图像 token + 最近 128 个输出 token」，让 KV 缓存恒定不膨胀——模仿人抄写长文时的"工作记忆 + 适度遗忘"，所以又快又准。

❓ 常见问题

Q: 它和普通 OCR、DeepSeek-OCR 有什么区别？

普通 OCR 只把字认出来，版式全丢；Unlimited-OCR 是端到端大模型，能保留表格、公式、多栏排版并输出 Markdown。相比基线 DeepSeek-OCR，它靠 R-SWA 让 KV 缓存恒定，能一次读完几十页长文档，长输出时速度更快、精度还更高。

Q: 支持中文和手写字吗？

支持。中英文档、扫描件、手写笔记、发票合同都能识别，对长文档、复杂版式尤其擅长。

Q: 一定要显卡吗？配置要求高不高？

需要 NVIDIA 显卡。好在它总参数才 3B、实际只激活 5 亿参数，显存占用相对友好，主流消费级显卡就能跑；没有本地显卡可以用带 GPU 的云服务器。

Q: 支持哪些输入格式？

常见图片（PNG / JPG / JPEG 等）和多页 PDF 都支持。PDF 会先把每一页转成图片再解析，所以处理 PDF 记得装上 pdf2image 和 pillow。

Q: gundam 和 base 两种模式怎么选？

gundam 精度高、适合复杂版式和长文档，是默认推荐；base 更快更省显存，适合简单文档或显存吃紧的机器。拿不准就先用 gundam。

Q: 输出出现重复内容怎么办？

这类端到端 OCR 长输出时可能重复。项目已内置抑制重复的参数（no_repeat_ngram_size=35、ngram_window=128），保持官方默认值即可，不建议随意改动。

Q: 显存不够、报 OOM 怎么办？

可以：①换 base 模式；②调小 base_size / image_size；③批量处理时把 --concurrency 调低；④用 Ollama / llama.cpp 的量化版（如 4-bit）在低显存机器上跑。

Q: 怎么和 Codex 结合使用？

见上面第 5 步：既可以让 Codex CLI 直接跑 infer.py 把文档转 Markdown，也可以起一个本地 OpenAI 兼容服务、或套一层 OCR MCP，让 Codex 把「读文档」当成一个随手可调的工具。

Q: 它和百度 PaddleOCR 是什么关系？

是百度在 OCR 方向的新技术路线：以 DeepSeek-OCR 为基线、用自研 R-SWA 打造的端到端长文档解析大模型，思路上也致谢了 PaddleOCR。定位和传统 PaddleOCR 不同——它更擅长长文档、复杂版式的端到端解析并直出 Markdown。

Q: 可以商用吗？

可以。项目采用 MIT 协议，代码和模型权重都完全开源，可自由用于商业项目。