Unlimited-OCR SGLang深度部署：从本地Wheel安装到OpenAI兼容接口全打通

Unlimited-OCR SGLang深度部署：从本地Wheel安装到OpenAI兼容接口全打通

【免费下载链接】Unlimited-OCRUnlimited OCR Works: Welcome the Era of One-shot Long-horizon Parsing.项目地址: https://gitcode.com/gh_mirrors/un/Unlimited-OCR

本文带你完整走一遍Unlimited-OCR 长文档 OCR 解析模型的 SGLang 部署。Unlimited-OCR 支持单次（one-shot）解析整本长文档、PDF 与多页图片，而 SGLang 部署路径直接提供本地 Wheel 包和 OpenAI 兼容接口——装好本地 Wheel、启动服务后，一条 HTTP 请求就能完成图片与 PDF 的文字识别，全程只需 4 步、约 10 分钟。

🎯 为什么值得部署 Unlimited-OCR

Unlimited-OCR 的核心卖点是"单次调用、长上下文解析"：把整份文档一次性喂给模型，靠 32K 上下文窗口和长程注意力机制（R-SWA）跨页保持语义连贯，而不用逐页切割后人工拼接。架构上由 DeepEncoder 编码器压缩视觉 token，再交给 LLM 解码输出结构化 Markdown：

项目提供三种推理方式，各有适用场景：

本文聚焦 SGLang 路线：它自带定制 Wheel，并内置了防止长文本重复输出的 n-gram 采样处理器（DeepseekOCRNoRepeatNGramLogitProcessor），这是长文档解析质量的关键。完整部署说明见 README.md 的 SGLang 章节。

📦 第 1 步：克隆仓库并安装本地 Wheel

SGLang 路线不能直接 pip 安装开源版 SGLang，必须使用仓库内提供的定制 Wheel（已包含 OCR 定制采样逻辑）：

git clone https://gitcode.com/gh_mirrors/un/Unlimited-OCR cd Unlimited-OCR # 用 uv 创建 Python 3.12 虚拟环境 uv venv --python 3.12 source .venv/bin/activate # 安装本地定制 SGLang Wheel + 依赖 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

三个依赖各管一摊：

• 本地 Wheel：核心推理引擎，文件位于 wheel/sglang-0.0.0.dev11416+g92e8bb79e-py3-none-any.whl
• kernels：GPU 算子库，版本需与 Wheel 配套
• pymupdf：负责把 PDF 逐页转成 300 DPI 图片，是 PDF 解析的预处理环节

🚀 第 2 步：一键启动 SGLang 推理服务

环境装好后，一条命令拉起服务：

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

几个关键参数一次看懂（完整参数见 README.md）：

服务启动后可访问http://127.0.0.1:10000/health确认状态。如果服务提前退出或启动超时，查看日志文件（infer.py默认写入./log/sglang_server.log，启动与等待逻辑见 infer.py 的 start_server）。

🔌 第 3 步：接入 OpenAI 兼容接口

服务启动后，端点就是标准的/v1/chat/completions，消息体结构与 ChatGPT 完全一致：文本指令 + base64 图片，流式返回。最小调用示例：

import base64, json, requests from sglang.srt.sampling.custom_logit_processor import ( DeepseekOCRNoRepeatNGramLogitProcessor, ) def generate(image_paths, image_mode, ngram_window): payload = { "model": "Unlimited-OCR", "messages": [{"role": "user", "content": [ {"type": "text", "text": "document parsing."}, # 每张图片编码为 {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}} ]}], "temperature": 0, "skip_special_tokens": False, "images_config": {"image_mode": image_mode}, "custom_logit_processor": DeepseekOCRNoRepeatNGramLogitProcessor.to_str(), "custom_params": {"ngram_size": 35, "window_size": ngram_window}, "stream": True, } resp = requests.post("http://127.0.0.1:10000/v1/chat/completions", data=json.dumps(payload), timeout=1200, stream=True) # 逐行读取 "data: " 前缀的 SSE 数据，拼接 choices[0].delta.content 即为识别结果

调用时有两个模式要记牢（完整请求逻辑参考 infer.py 的 infer_one）：

PDF 输入需先用 PyMuPDF 转图（infer.py 的 pdf_to_images 封装了该逻辑，默认 300 DPI），再把每页图片作为一组多图请求发送即可。

⚡ 第 4 步：infer.py 一键批量推理

不想自己管理服务器生命周期？项目自带的 infer.py 会自动启动 SGLang 服务、等待就绪、并发派发请求、结束后清理进程，并输出系统级 TPS、平均解码耗时等统计（统计逻辑见 infer.py 的 run 函数）：

# 批量处理一个图片目录 python infer.py --image_dir ./examples/images \ --output_dir ./outputs --concurrency 8 --image_mode gundam # 批量处理 PDF（逐页并发，每页输出一个 .md 文件） python infer.py --pdf ./examples/document.pdf \ --output_dir ./outputs --concurrency 8 --image_mode gundam

常用可调参数（参数解析见 infer.py）：

• --concurrency 8：并发请求数，默认 8
• --gpu 0：指定显卡（等价于CUDA_VISIBLE_DEVICES）
• --model_dir：本地模型路径或 Hugging Face 模型 ID
• --server_log：服务器日志路径，排查启动问题必备

任务编排细节（目录遍历、PDF 拆页、输出命名规则）见 infer.py 的 build_jobs，内置了 5 次重试与 502 退避，偶发网络抖动不会中断整批任务。

👀 效果演示：长文档一次成型

下面演示 Unlimited-OCR 对整份论文 PDF 的单次解析效果——左侧输入原始文档页，右侧实时流式吐出的就是带结构的 Markdown 识别结果：

可以看到表格、公式、章节结构都能被还原，这正是 32K 长上下文 + n-gram 去重采样带来的稳定性。

📚 资料索引

❓ 常见问题速查

• 装的是哪个 SGLang？只能用wheel/目录下的本地 Wheel，PyPI 上的开源版缺少 OCR 定制 logit 处理器，长输出会出现复读。
• 服务一直起不来？打开--server_log指向的日志（./log/sglang_server.log）；显存不足时把--mem-fraction-static从 0.8 调低。
• 请求超时？长文档解码耗时较长，客户端超时建议 ≥ 1200s（与infer.py的REQUEST_TIMEOUT保持一致，见 infer.py 的常量定义）。
• 并发多少合适？默认 8 路并发已是官方推荐起点，可依据 GPU 显存与吞吐表现（观察输出中的 System TPS）再调整。

按照以上四步——本地 Wheel 安装、启动服务、打通 OpenAI 兼容接口、批量推理，Unlimited-OCR 的 SGLang 部署就全部完成。接下来就可以把图片目录或整本 PDF 扔给它，享受"一次调用、整卷解析"的长文档 OCR 体验了。

【免费下载链接】Unlimited-OCRUnlimited OCR Works: Welcome the Era of One-shot Long-horizon Parsing.项目地址: https://gitcode.com/gh_mirrors/un/Unlimited-OCR