Unlimited-OCR 使用教程

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

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，把模型权重拉到本地。国内网络推荐用魔搭，速度更快：

# 方式一：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

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

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() 常用参数说明：

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

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

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

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

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

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

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

# 启动本地 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 能理解、能操作的结构化文字——总结要点、提取字段、生成表格、写成代码或报告，全交给它。