Unlimited-OCR长文档解析：R-SWA机制原理与生产部署指南

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

如果你正在处理一份几十页的PDF报告、一本扫描版电子书，或者一份复杂的学术论文，想把它们转换成可编辑、可搜索的文本，你大概率会面临一个经典困境：速度与质量的取舍。

传统的OCR工具，无论是开源的Tesseract还是商业软件，处理单页文档尚可，但面对长文档时，要么需要逐页处理再手动拼接，流程繁琐且容易出错；要么使用一些端到端模型，但输出长度一长，推理速度就急剧下降，显存占用飙升，体验非常割裂。更不用说在转换过程中，表格结构、公式、排版等信息的丢失，常常让后期整理工作苦不堪言。

最近，百度开源的Unlimited-OCR在技术社区引起了不小的讨论。很多文章都在强调它的“长文档一次解析”和“速度提升”，这当然是它的亮点。但如果你只看到这些，可能会错过它真正解决的核心工程问题，以及它背后那个巧妙的设计——Reference Sliding Window Attention (R-SWA)。这个设计，才是让它在长文档场景下实现“速度不随页数增长”的关键。

这篇文章不会只复述官方新闻稿。我们将深入拆解Unlimited-OCR，回答几个更实际的问题：它到底解决了传统OCR和现有端到端模型的哪些痛点？那个听起来很厉害的R-SWA机制，原理是什么，为什么能省显存、提速度？作为开发者，我们如何快速上手，从单张图片测试到批量处理PDF？更重要的是，在实际部署中，有哪些参数需要调优，又会遇到哪些“坑”？

我们将从一次真实的长文档处理需求出发，带你理解Unlimited-OCR的技术内核，并附上完整的本地部署、代码调用及生产级优化指南。无论你是需要处理大量扫描文档的开发者，还是对高效文档解析技术感兴趣的研究者，这篇文章都将提供可直接落地的参考。

1. Unlimited-OCR 究竟解决了什么问题？

在深入代码之前，我们必须先厘清Unlimited-OCR瞄准的靶心。它不是一个通用的“更好”的OCR，而是专门针对长文档、多页、结构化输出场景的优化方案。其价值体现在三个层面的“解放”：

第一，解放了工程拼接的复杂度。过去处理一份20页的PDF，标准流程是：用PyMuPDF或类似库拆分成20张图片 -> 循环调用OCR接口20次 -> 将20份识别结果（通常是JSON或文本）按顺序拼接 -> 处理可能存在的页码错乱、内容重复或缺失问题。Unlimited-OCR的“长程解析”能力，让你可以直接将整个PDF（或图片列表）喂给模型，一次调用，得到一份完整的、连贯的Markdown文档。这不仅仅是少写一个for循环，更是消除了中间环节出错的风险。

第二，解放了被KV Cache拖累的推理速度。以DeepSeek-OCR为代表的现代端到端OCR模型，本质是视觉-语言模型。它们使用Transformer解码器自回归地生成文本。这里有一个关键瓶颈：每生成一个新的token（字词），模型都需要回顾之前生成的所有token（历史信息），这些历史信息以Key-Value缓存的形式存储在显存中。文档越长，生成的token越多，这个缓存就越大，导致推理速度越来越慢，显存占用越来越高。这就是为什么长文档场景下，很多模型会“越跑越慢”。Unlimited-OCR通过R-SWA机制，将文本侧的KV缓存大小固定为一个常数（默认128），从根本上切断了速度与文档长度的线性增长关系。

第三，解放了对“完美单页识别”的过度依赖。传统逐页处理时，如果某一页识别效果差（如模糊、倾斜），这一页的结果就是独立的“坏点”，需要单独处理。而Unlimited-OCR在一次前向传播中处理所有页面，模型能够利用跨页的上下文信息。例如，上一页的一个模糊单词，可能因为下一页出现的清晰相同词汇或上下文语义而得到纠正。这使得模型对局部噪声的鲁棒性更强。

所以，Unlimited-OCR的核心价值在于：它为长文档OCR提供了一种“系统级”的解决方案，而不仅仅是“模型级”的改进。它通过改变模型注意力机制，将长文档处理从一个需要复杂工程拼接的“批处理任务”，变成了一个自然的、连续的“理解任务”。

2. 核心原理：R-SWA 如何打破长文档的速度枷锁？

要理解Unlimited-OCR的魔力，必须搞懂Reference Sliding Window Attention。我们可以用一个简单的类比来理解：

想象你在阅读一本很厚的书（长文档），并需要做笔记（生成文本）。

• 传统方式（标准注意力）：每写下一句笔记，你都需要回头翻阅之前写过的所有笔记，以确保连贯。书越厚，笔记越多，你回头翻阅的历史笔记堆就越高，查找和思考的速度自然越来越慢。
• R-SWA方式：你面前始终摊开着这本书的全部页面（图像Token始终完整可见，作为“参考”）。但是，对于你自己的笔记，你只允许查看最近写下的几页（例如最近128个token）。更早的笔记会被归档，不再实时查阅。这样，无论这本书多厚，你维持的“工作记忆”（KV Cache）大小是固定的，因此阅读和做笔记的速度可以保持稳定。

下面我们从技术层面拆解：

1. 信息分离：图像 vs. 文本R-SWA将输入分为两类信息：

• 图像Token（Reference）：由视觉编码器（DeepEncoder）从PDF页面图像提取的特征。这些信息在解码生成文本的整个过程中始终完全可见。因为图像内容是固定的“参考源”，模型需要随时能“看到”它来识别文字和结构。
• 文本Token（Sliding Window）：模型自回归生成的Markdown文本。对于这部分，R-SWA采用了一个滑动窗口机制。模型在生成下一个token时，只能“注意”到最近生成的W个文本token（W是窗口大小，默认为128）。更早的文本历史被移出KV缓存。

2. 数学本质：从 O(T) 到 O(1) 的复杂度降低标准Transformer解码器的KV缓存大小与已生成序列长度T成线性关系：O(T)。这是速度瓶颈的根源。 R-SWA将文本侧的缓存大小限制为固定窗口W，因此其缓存复杂度变为常数：O(1)（图像侧缓存也是常数）。这意味着，无论生成1000个token还是10000个token，模型需要维护和计算的KV缓存总量基本不变，从而实现了稳定的推理延迟和显存占用。

3. 为什么这在OCR任务中是可行的？这基于一个对OCR任务特性的深刻洞察：文本生成的连贯性主要依赖于局部上下文和全局的视觉信息，而非长距离的文本历史。

• 在生成一个段落时，模型更需要知道当前句子和上一句的关系（局部上下文），以及当前看到的图像区域是什么（视觉参考）。
• 很少需要依赖几十句话之前的文本内容来决定当前字符的识别。即使需要（如章节标题的呼应），这些信息也可以通过模型对固定视觉内容的持续访问来间接获得。

因此，牺牲掉对全部文本历史的注意力，换取常数级的缓存开销，对于长文档OCR来说是一笔非常划算的“交易”。这也是Unlimited-OCR论文中，在输出长达6000个token时，速度仍能比基线提升35%的根本原因。

3. 环境准备与模型获取

在开始动手之前，请确保你的环境满足基本要求。Unlimited-OCR对算力有一定要求，建议在配备NVIDIA GPU的机器上运行。

3.1 硬件与基础软件要求

• 操作系统：Linux (Ubuntu 20.04/22.04 推荐) 或 Windows (WSL2)。
• GPU：至少8GB显存（用于基础推理），处理长文档或高并发建议16GB以上。模型支持CUDA。
• Python: 3.12 或更高版本。
• CUDA: 12.9。请确保你的NVIDIA驱动支持此版本的CUDA。

3.2 创建并激活Python虚拟环境

使用虚拟环境是管理项目依赖的最佳实践，可以避免包冲突。

# 创建虚拟环境 python -m venv unlimited-ocr-env # 激活虚拟环境 # Linux/macOS source unlimited-ocr-env/bin/activate # Windows unlimited-ocr-env\Scripts\activate

3.3 安装PyTorch

根据你的CUDA版本，从 PyTorch官网 获取安装命令。这里以CUDA 12.9为例：

pip install torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu129

3.4 下载Unlimited-OCR模型

模型已开源在ModelScope和GitHub。推荐使用ModelScope的modelscope库下载，它会自动处理模型文件和配置文件。

# 安装 modelscope pip install modelscope # 下载模型到本地目录 (例如 ./Unlimited-OCR) modelscope download --model PaddlePaddle/Unlimited-OCR --local_dir ./Unlimited-OCR

下载过程可能需要一些时间，因为模型文件较大（约几个GB）。完成后，你的./Unlimited-OCR目录下应包含config.json,model.safetensors等文件。

4. 快速开始：单张图片推理

我们先从一个最简单的例子开始，验证环境是否正确，并理解基本的API调用方式。这里我们使用Hugging Facetransformers库进行推理。

4.1 安装额外依赖

除了PyTorch和modelscope，还需要安装一些必要的库。

pip install transformers==4.57.1 pip install Pillow==12.1.1 matplotlib==3.10.8 einops==0.8.2 pip install addict==2.4.0 easydict==1.13 pymupdf==1.27.2.2 psutil==7.2.2

• transformers: Hugging Face 模型加载和推理库。
• Pillow: 图像处理库。
• pymupdf: 用于PDF文件处理的库，在后续多页推理中会用到。

4.2 编写单图推理脚本

创建一个Python文件，例如demo_single.py。

# demo_single.py from transformers import AutoModel, AutoTokenizer import torch # 1. 指定模型路径（刚才下载的目录） model_path = "./Unlimited-OCR" # 2. 加载tokenizer和模型 print("Loading tokenizer and model...") tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModel.from_pretrained( model_path, trust_remote_code=True, use_safetensors=True ).eval().cuda() # 将模型移动到GPU print("Model loaded successfully.") # 3. 准备一张测试图片，替换为你的图片路径 image_file = "./test_image.jpg" # 示例图片路径 # 4. 执行推理 print(f"Processing image: {image_file}") result = model.infer( tokenizer, prompt='<image>document parsing.', # 触发文档解析的提示词 image_file=image_file, output_path='./output', # 输出目录，Markdown文件将保存在这里 base_size=1024, # 基础尺寸，影响视觉编码 image_size=640, # 输入模型的图像尺寸 crop_mode=True, # Gundam模式：启用裁剪，适合单页高精度识别 max_length=32768, # 最大生成长度，支持长文档 no_repeat_ngram_size=35, # 重复ngram惩罚，避免重复生成 ngram_window=128, # R-SWA的滑动窗口大小 save_results=True, # 保存结果到文件 ) # 5. 打印结果（结果也会保存到 ./output/ 目录下） print("\n--- Recognition Result (Preview) ---") # result 可能是一个字典或特定对象，根据实际情况访问文本内容 # 这里假设结果的主要文本在 `text` 字段 if hasattr(result, 'text'): print(result.text[:500]) # 打印前500个字符预览 elif isinstance(result, dict) and 'text' in result: print(result['text'][:500]) else: print("Result saved to ./output/ directory.")

关键参数解释：

• crop_mode=True(Gundam模式)：此模式会对图像进行智能裁剪，专注于文本区域，对于清晰但背景复杂的单页文档（如扫描的论文页面）识别精度更高。
• image_size=640：在Gundam模式下，图像会被resize到640x640左右进行处理。
• ngram_window=128：这就是R-SWA的滑动窗口大小。它决定了模型在生成文本时能“回头看”多远的历史文本token。128是一个经验值，平衡了上下文依赖和缓存效率。

4.3 运行脚本

将你的测试图片（如一份扫描的合同、一页论文）命名为test_image.jpg放在脚本同级目录，然后运行：

python demo_single.py

如果一切顺利，你会在终端看到加载日志，并在./output目录下找到一个以时间戳或图片名命名的Markdown文件（.md），里面就是结构化的识别结果。

5. 核心应用：多页PDF与批量图片处理

单张图片只是开胃菜，Unlimited-OCR的真正威力在于处理多页文档。我们来看两种主要场景：多张独立图片和一个完整的PDF文件。

5.1 多张图片批量推理

假设你有一个文件夹，里面是按顺序命名的页面图片（page1.png,page2.png, ...）。

# demo_multi_images.py from transformers import AutoModel, AutoTokenizer import os model_path = "./Unlimited-OCR" tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModel.from_pretrained( model_path, trust_remote_code=True, use_safetensors=True ).eval().cuda() # 假设图片存放在 ./doc_images/ 目录下，并按文件名排序 image_dir = "./doc_images" image_files = [os.path.join(image_dir, f) for f in sorted(os.listdir(image_dir)) if f.lower().endswith(('.png', '.jpg', '.jpeg'))] print(f"Found {len(image_files)} images to process.") result = model.infer_multi( tokenizer, prompt='<image>Multi page parsing.', image_files=image_files, # 传入图片路径列表 output_path='./output_multi', image_size=1024, # Base模式：多页时使用1024尺寸 max_length=32768, no_repeat_ngram_size=35, ngram_window=1024, # 多页场景建议使用更大的窗口（如1024） save_results=True, ) print("Multi-page processing completed. Results saved.")

注意这里的两个重要变化：

1. image_size=1024(Base模式)：对于多页文档，通常关闭crop_mode（即使用Base模式），并将image_size设为1024。这能保证每页图像以相对统一的方式被编码，有利于模型理解跨页的版面结构。
2. ngram_window=1024：在多页场景下，为了保持跨页的连贯性（例如章节标题、表格跨页），可能需要更大的文本上下文窗口。这里将其设置为1024，意味着模型在生成当前页末尾内容时，还能“记住”前面最多1024个token（约几百字）的文本历史。

5.2 直接处理PDF文件

Unlimited-OCR的API本身不直接接受PDF，但我们可以用PyMuPDF(fitz) 轻松地将PDF转换为图片列表。

# demo_pdf.py from transformers import AutoModel, AutoTokenizer import fitz # PyMuPDF import os from PIL import Image import io model_path = "./Unlimited-OCR" tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModel.from_pretrained( model_path, trust_remote_code=True, use_safetensors=True ).eval().cuda() def pdf_to_images(pdf_path, dpi=300): """将PDF每一页转换为PIL Image列表""" doc = fitz.open(pdf_path) images = [] for page_num in range(len(doc)): page = doc.load_page(page_num) # 渲染页面为RGB像素图 pix = page.get_pixmap(matrix=fitz.Matrix(dpi/72, dpi/72)) img_data = pix.tobytes("ppm") img = Image.open(io.BytesIO(img_data)) images.append(img) doc.close() return images # 1. 指定PDF路径 pdf_path = "./your_document.pdf" # 2. 转换为图片 print(f"Converting PDF to images: {pdf_path}") pil_images = pdf_to_images(pdf_path, dpi=300) # 300 DPI保证清晰度 print(f"Converted {len(pil_images)} pages.") # 3. 临时保存图片到内存或磁盘，以供模型读取 # 这里演示临时保存到磁盘（生产环境可优化为内存处理） temp_dir = "./temp_pdf_images" os.makedirs(temp_dir, exist_ok=True) image_paths = [] for i, img in enumerate(pil_images): temp_path = os.path.join(temp_dir, f"page_{i:04d}.png") img.save(temp_path, "PNG") image_paths.append(temp_path) # 4. 调用多页推理 try: result = model.infer_multi( tokenizer, prompt='<image>Multi page parsing.', image_files=image_paths, output_path='./output_pdf', image_size=1024, max_length=32768, no_repeat_ngram_size=35, ngram_window=1024, save_results=True, ) print("PDF processing completed successfully.") finally: # 5. 清理临时图片文件（可选） for f in image_paths: os.remove(f) os.rmdir(temp_dir)

这个脚本完成了从PDF到结构化Markdown的完整流水线。关键点在于使用PyMuPDF以高DPI（如300）渲染PDF页面，以确保OCR的输入质量。

6. 生产级部署：使用SGLang实现高并发API服务

对于需要服务化、处理大量并发请求的生产环境，使用原始的transformers库逐条推理效率较低。Unlimited-OCR官方推荐使用SGLang进行部署。SGLang是一个针对大语言模型推理的高性能运行时，支持动态批处理、持续批处理等优化，并能提供OpenAI兼容的API接口。

6.1 SGLang环境搭建

首先，需要从Unlimited-OCR的GitHub仓库获取为该项目定制的SGLang wheel文件进行安装。

# 1. 克隆仓库（如果尚未克隆） git clone https://github.com/baidu/Unlimited-OCR.git cd Unlimited-OCR # 2. 创建新的虚拟环境（建议与transformers环境隔离） uv venv --python 3.12 source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 3. 安装定制的SGLang wheel（路径可能根据仓库更新而变化，请查看仓库说明） # 通常wheel文件在仓库的某个子目录下，例如 `third_party/` uv pip install third_party/sglang-0.0.0.dev11416+g92e8bb79e-py3-none-any.whl # 4. 安装其他必要依赖 uv pip install kernels==0.11.7 uv pip install pymupdf==1.27.2.2 # 确保torch等已安装

6.2 启动SGLang推理服务器

以下命令启动一个加载了Unlimited-OCR模型的推理服务器。

python -m sglang.launch_server \ --model PaddlePaddle/Unlimited-OCR \ # 指定模型，会自动从ModelScope下载 --served-model-name Unlimited-OCR \ # 服务名称 --attention-backend fa3 \ # 使用FlashAttention-3加速 --page-size 1 \ # 批处理页面大小 --mem-fraction-static 0.8 \ # 80%显存用于静态分配（KV缓存等） --context-length 32768 \ # 最大上下文长度 --enable-custom-logit-processor \ # 启用自定义逻辑处理器（用于no-repeat-ngram） --disable-overlap-schedule \ # 禁用重叠调度（根据实际情况调整） --skip-server-warmup \ # 跳过服务预热（调试时可加） --host 0.0.0.0 --port 10000 # 服务监听地址和端口

关键参数解析：

• --attention-backend fa3：使用FlashAttention-3，能显著提升注意力计算速度，降低显存占用。
• --mem-fraction-static 0.8：将GPU显存的80%预留给模型的权重、KV缓存等静态数据。这有助于提高内存利用率和减少碎片。如果你的显存紧张，可以适当调低。
• --context-length 32768：与模型配置一致，支持长达32K的上下文。
• --enable-custom-logit-processor：必须开启，以支持Unlimited-OCR所需的no_repeat_ngram_size功能，避免生成重复内容。

服务器启动后，会监听http://0.0.0.0:10000。

6.3 使用OpenAI兼容的API进行调用

SGLang服务器提供了与OpenAI ChatCompletion兼容的API端点。你可以使用任何HTTP客户端或OpenAI SDK进行调用。

# demo_sglang_client.py import openai import base64 from pathlib import Path # 配置客户端指向本地SGLang服务器 client = openai.OpenAI( base_url="http://localhost:10000/v1", # SGLang的API地址 api_key="no-api-key-required" # 本地部署通常不需要key ) def encode_image(image_path): """将图片编码为base64字符串""" with open(image_path, "rb") as image_file: return base64.b64encode(image_file.read()).decode('utf-8') # 准备请求 image_path = "./test_image.jpg" base64_image = encode_image(image_path) # 构建消息，注意格式 response = client.chat.completions.create( model="Unlimited-OCR", # 与 --served-model-name 一致 messages=[ { "role": "user", "content": [ {"type": "text", "text": "<image>document parsing."}, { "type": "image_url", "image_url": { "url": f"data:image/jpeg;base64,{base64_image}" } } ] } ], max_tokens=32768, # 最大生成token数 temperature=0.01, # 低温度保证输出确定性 # 可以通过 extra_body 传递模型特定参数，具体需参考SGLang文档 # extra_body={"ngram_window": 128, "no_repeat_ngram_size": 35} ) # 输出结果 print(response.choices[0].message.content)

这种方式非常适合集成到现有的AI应用框架中，或者构建一个可水平扩展的OCR微服务。

7. 参数调优与最佳实践

直接使用默认参数能工作，但针对不同的文档类型和质量，进行微调能获得更好的效果。以下是一些关键参数的经验性调整指南。

7.1 图像预处理模式：crop_mode与image_size

这是影响识别精度的首要参数。

• crop_mode=True(Gundam模式) +image_size=640：
  • 适用场景：单页、背景干净、文字密集的文档，如扫描的合同、论文、书籍页面。
  • 原理：模型会先检测文本区域并进行裁剪，然后以较高分辨率（相对裁剪后区域）处理，能提升小字体和复杂版式的识别率。
  • 缺点：对于有大量图表、图片或非规则排版的页面，裁剪可能出错。
• crop_mode=False(Base模式) +image_size=1024：
  • 适用场景：多页文档、包含大量图表/图片的文档、版面复杂的杂志或报告。
  • 原理：将整页图像缩放到固定尺寸（如1024x1024）输入模型。保留了完整的页面全局布局信息，有利于理解图表位置、分栏等结构。
  • 建议：处理多页PDF时，统一使用Base模式，以保证各页面处理方式一致，便于模型学习跨页结构。

7.2 R-SWA窗口大小：ngram_window

这个参数控制模型能回溯多远的文本历史。

• ngram_window=128(默认)：适用于大多数单页或短文档。提供了足够的局部上下文，同时缓存效率最高。
• ngram_window=512 或 1024：适用于长文档，尤其是需要强跨页连贯性的场景，如：
  • 表格跨越多页。
  • 列表项跨页继续。
  • 章节标题与内容的远距离引用。
  • 增大窗口会轻微增加计算量，但对于长文档的整体质量提升可能有帮助。

7.3 重复惩罚：no_repeat_ngram_size

用于防止模型生成重复的短语或句子。

• no_repeat_ngram_size=35(默认)：在生成过程中，禁止重复出现任何35-gram（35个token的序列）。这个值设置得较大，能有效避免长文档中大段内容的重复生成。
• 如果发现输出中有不合理的重复，可以尝试调小此值，如设为10或15。但注意，调太小可能无法抑制真正的重复。
• 如果模型似乎“卡住”在某个循环，可以尝试调大此值，或检查输入图像质量。

7.4 生产环境部署建议

1. 使用SGLang：对于任何有并发需求的场景，SGLang都是比直接使用transformers更好的选择。它提供了更优的批处理、内存管理和API服务。
2. 监控显存与速度：使用nvtop或nvidia-smi监控GPU显存占用和利用率。根据监控结果调整--mem-fraction-static和批处理大小(--page-size)。
3. 实现异步处理队列：对于大量PDF文件，不要同步阻塞处理。实现一个任务队列（如Redis + Celery），将PDF转换和OCR任务异步化，并通过SGLang API调用。
4. 结果后处理：Unlimited-OCR输出的是Markdown。你可能需要：
   • 使用正则表达式或解析库进一步提取特定结构（如标题、作者、摘要）。
   • 将Markdown表格转换为CSV或Excel。
   • 对识别结果进行拼写检查或术语纠正（尤其是在专业领域）。

8. 常见问题与排查思路

在实际使用中，你可能会遇到以下问题。这里提供一个快速排查指南。

问题现象	可能原因	排查方式	解决方案
模型加载失败，提示TrustRemoteCode错误	模型代码需要信任远程执行。	检查错误信息是否包含trust_remote_code。	在AutoModel.from_pretrained和AutoTokenizer.from_pretrained中确保设置了trust_remote_code=True。
推理时显存溢出 (OOM)	1. 单张图片分辨率过高。 2. 批处理大小太大。 3.max_length设置过长。	1. 检查输入图片尺寸。 2. 监控nvidia-smi的显存占用。	1. 在预处理阶段将图片缩放至合理尺寸（如长边不超过2048）。 2. 减小SGLang的--page-size。 3. 根据文档实际长度调整max_length。
识别结果出现大量重复文本	1.no_repeat_ngram_size设置不当。 2. 图像质量差，模型置信度低。 3. 滑动窗口ngram_window太小，丢失了必要上下文。	1. 检查输出中重复的模式。 2. 查看原始图像是否模糊、有污渍。	1. 调整no_repeat_ngram_size（先调大，若无效再调小）。 2. 预处理图像，提高对比度、去噪。 3. 尝试增大ngram_window。
多页文档顺序错乱	1. 图片文件列表顺序错误。 2. PDF渲染时页面顺序错误。	1. 打印image_files列表确认顺序。 2. 检查PDF文件本身是否有异常分页。	1. 使用sorted(os.listdir(...))确保文件名排序正确。 2. 使用PyMuPDF时，确认load_page的索引从0开始。
表格或复杂排版识别效果差	1. 使用了crop_mode=True，破坏了表格整体结构。 2.image_size太小，细节丢失。	1. 对比crop_mode为True和False的结果。 2. 检查输出Markdown中表格符号 (`	`) 是否完整。
SGLang服务启动失败	1. 端口被占用。 2. 模型下载不完整。 3. CUDA版本或驱动不兼容。	1. 检查端口10000。 2. 查看SGLang启动日志。 3. 运行nvidia-smi确认CUDA可用。	1. 更换--port。 2. 删除模型缓存重新下载。 3. 确保环境满足CUDA 12.9和PyTorch要求。
处理速度没有预期中快	1. 未使用GPU。 2. 未启用FlashAttention。 3. 输入图像尺寸过大。	1. 确认模型.cuda()调用成功。 2. SGLang启动参数检查--attention-backend fa3。 3. 测量单张图片预处理时间。	1. 确保PyTorch CUDA版本正确。 2. 安装正确的FlashAttention-3依赖。 3. 在保持质量的前提下，预处理时缩小图像。

9. 总结：何时选择Unlimited-OCR？

经过以上的技术剖析和实践演练，我们可以对Unlimited-OCR做一个清晰的定位。它不是一个“万能”OCR替换方案，而是在特定赛道上具有显著优势的利器。

你应该优先考虑使用 Unlimited-OCR 的场景：

1. 文档长度超过10页：其常数级KV缓存的优势开始凸显，处理速度稳定，无需工程拼接。
2. 需要高度结构化的输出：直接输出Markdown，完美保留标题、列表、表格、代码块等结构，省去后解析的麻烦。
3. 处理扫描版PDF或书籍：端到端模型的语言先验能更好地处理模糊、倾斜、手写体干扰等情况。
4. 构建自动化文档处理流水线：其SGLang API服务化部署方式，易于集成，适合处理海量文档。

你可能需要权衡或选择其他方案的场景：

1. 仅处理单张截图或短文本：轻量级OCR（如PaddleOCR、EasyOCR）可能更快、资源消耗更少。
2. 对输出格式有极其定制化的要求：如果只需要纯文本，Unlimited-OCR的Markdown输出可能显得“过重”。
3. 极度缺乏GPU资源：模型需要GPU才能达到实用速度。如果只有CPU，推理会非常慢。
4. 处理非文档类图像（自然场景文字）：Unlimited-OCR主要针对文档图像优化，在街景、商品包装等场景可能不如专用模型。

最后的实践建议：在决定投入生产前，用你业务中最具代表性的真实文档（尤其是那些让现有方案头疼的长文档、复杂表格文档）做一个全面的测试。关注识别准确率、速度、显存消耗以及输出Markdown的结构完整性。Unlimited-OCR的开源降低了尝试门槛，其针对长文档的“系统级”解决方案思路，无疑为文档智能处理领域提供了一个新的、强有力的选项。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度