1. 长文档 OCR 的「逐页失忆」到底卡在哪如果你处理过 40 页以上的 PDF 合同、年报或者扫描版学术论文大概率踩过同一个坑传统 OCR 流水线是逐页跑的每翻一页上一页的上下文就被清空。结果就是跨页表格从中间断开、章节编号接不上、阅读顺序错乱最后还得人工把碎片拼回去。百度开源的 Unlimited-OCR 就是冲着这个痛点来的——3B 总参数、MoE 架构实际激活约 500M靠 R-SWA参考滑动窗口注意力把解码端 KV 缓存从随输出长度线性增长压到常数上限官方数据是能一次性读完 40 页文档并直接输出结构化 MarkdownOmniDocBench v1.6 端到端综合 93.92%。这篇不聊论文聊工程落地。我以一份 40 页 PDF 为样本把本地 Transformers 推理和 API 两种调用方式都跑一遍重点看三件事显存占用、首字延迟、跨页字段一致性。同时给出可复制的config.toml骨架以及用 TaoToken 统一 Key 打通文档解析链路的配置片段。目标很明确让你在 30 分钟内跑通一条不丢上下文的文档解析流水线。适合谁看手里有长文档批量解析需求的后端/算法工程师正在做企业知识库入库、合同结构化、财报提取的同学。如果你只是偶尔识别一两张图本地跑个轻量模型就够了不必上这套。2. 前置准备模型权重、环境与 TaoToken 统一 Key2.1 硬件与依赖基线Unlimited-OCR 官方给的最低门槛是 16GB 显存消费级卡能跑。我实测用的是单卡 24GB40 页 PDF 一次性 prefill 时显存峰值在 18GB 上下留了余量。如果你显存只有 16GB建议把页数切到 20 页一批或者走 API 方式把重活交给远端。依赖版本别乱升官方锁定了一套组合我照抄并验证可用pip install torch2.10.0 torchvision0.25.0 pip install transformers4.57.1 pip install Pillow12.1.1 matplotlib3.10.8 einops0.8.2 pip install addict2.4.0 easydict1.13 pymupdf1.27.2.2 psutil7.2.2pymupdf是用来把 PDF 转成图片的后面逐页和整档两种模式都要用它。transformers必须带trust_remote_codeTrue因为模型仓库里有自定义的 R-SWA 实现。2.2 TaoToken 统一 Key 的定位本地推理和 API 调用混用时最烦的是每个服务一套鉴权、一套地址、一套额度管理。TaoToken 在这里的角色是统一入口一个 Key 覆盖模型对话、Coding Plan、API 调用等场景文档解析链路里需要调模型做后处理比如把 OCR 出来的 Markdown 再喂给对话模型做字段抽取时不用再单独维护另一套凭证。先去控制台拿 Key地址是https://taotoken.net/api-keys。拿到之后API 基址用https://taotoken.net/api注意这个地址不带任何查询参数干净拼接即可。模型对话的入口在https://taotoken.net/model-chatCoding Plan 在https://taotoken.net/coding-plan接入文档在https://taotoken.net/doc。这几个 deep link 后面 CTA 会按场景分流你按需取用。注意TaoToken 的 Key 只用于它自己的服务鉴权不要把它写进 Unlimited-OCR 的本地推理配置里两者是独立的。本地模型不需要任何外部 Key。2.3 目录结构约定为了让后面的config.toml和脚本能直接跑先约定一个工作目录unlimited-ocr-lab/ ├── config.toml ├── pdf_to_images.py ├── run_local.py ├── run_api.py ├── compare_pages.py ├── models/ # 本地权重缓存 ├── input/sample.pdf # 40 页样本 └── output/ ├── whole/ # 整档 OCR 结果 └── perpage/ # 逐页 OCR 结果3. 可复制配置config.toml 骨架与两种调用方式3.1 config.toml 骨架把下面这段存成config.toml本地和 API 两种模式的参数都在里面切换时只改mode字段[general] mode local # local | api pdf_path input/sample.pdf output_dir output dpi 300 # PDF 转图分辨率300 足够再高收益递减 [local] model_name baidu/Unlimited-OCR cache_dir models dtype bfloat16 device cuda max_length 32768 no_repeat_ngram_size 35 ngram_window 1024 # 多页场景窗口单页可降到 128 image_size 1024 # base 模式固定 1024 batch_pages 40 # 一次喂多少页显存不够就调小 [api] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 从环境变量读别硬编码 model unlimited-ocr timeout 120 concurrency 8 [compare] field_keys [合同编号, 金额, 签署日期] # 跨页一致性校验字段几个参数值得单独说。ngram_window在多页场景设 1024是为了让防重复的 n-gram 窗口覆盖更长的输出避免 40 页连续生成时出现段落级重复。batch_pages是显存和吞吐的平衡点24GB 卡设 40 没问题16GB 卡建议 20。dpi别盲目拉高300 已经能让小字体清晰600 只会让 prefill 变慢。3.2 本地推理脚本run_local.py负责加载模型并跑整档 OCRimport tomllib import torch from transformers import AutoModel, AutoTokenizer from pdf_to_images import pdf_to_images with open(config.toml, rb) as f: cfg tomllib.load(f) local cfg[local] model_name local[model_name] tokenizer AutoTokenizer.from_pretrained( model_name, trust_remote_codeTrue, cache_dirlocal[cache_dir] ) model AutoModel.from_pretrained( model_name, trust_remote_codeTrue, use_safetensorsTrue, torch_dtypetorch.bfloat16, cache_dirlocal[cache_dir], ).eval().cuda() pages pdf_to_images(cfg[general][pdf_path], dpicfg[general][dpi]) pages pages[: local[batch_pages]] model.infer_multi( tokenizer, promptimageMulti page parsing., image_filespages, output_pathf{cfg[general][output_dir]}/whole, image_sizelocal[image_size], max_lengthlocal[max_length], no_repeat_ngram_sizelocal[no_repeat_ngram_size], ngram_windowlocal[ngram_window], save_resultsTrue, ) print(f整档 OCR 完成共 {len(pages)} 页)pdf_to_images.py是公共工具逐页和整档都调它import fitz import tempfile, os def pdf_to_images(pdf_path, dpi300): doc fitz.open(pdf_path) tmp_dir tempfile.mkdtemp(prefixpdf_ocr_) mat fitz.Matrix(dpi / 72, dpi / 72) paths [] for i, page in enumerate(doc): out os.path.join(tmp_dir, fpage_{i1:04d}.png) page.get_pixmap(matrixmat).save(out) paths.append(out) doc.close() return paths3.3 API 调用脚本run_api.py走 TaoToken 的 OpenAI 兼容接口适合本地显存不够或者要并发批量的场景import os, tomllib, base64, requests from pdf_to_images import pdf_to_images with open(config.toml, rb) as f: cfg tomllib.load(f) api cfg[api] key os.environ[api[api_key_env]] pages pdf_to_images(cfg[general][pdf_path], dpicfg[general][dpi]) def encode(path): with open(path, rb) as f: return base64.b64encode(f.read()).decode() results [] for idx, p in enumerate(pages): resp requests.post( f{api[base_url]}/v1/chat/completions, headers{Authorization: fBearer {key}}, json{ model: api[model], messages: [{ role: user, content: [ {type: text, text: document parsing.}, {type: image_url, image_url: {url: fdata:image/png;base64,{encode(p)}}}, ], }], max_tokens: 8192, }, timeoutapi[timeout], ) resp.raise_for_status() results.append(resp.json()[choices][0][message][content]) print(f第 {idx1} 页完成) with open(f{cfg[general][output_dir]}/whole/api_result.md, w) as f: f.write(\n\n.join(results))API 模式的关键差异它是逐页请求的跨页上下文靠你自己在 prompt 里带上一页的尾部内容来维持。如果你要的是「一次看完 40 页」的效果还是得走本地infer_multiAPI 更适合做补充或降级方案。4. 验证请求显存、首字延迟与跨页一致性4.1 显存与首字延迟实测跑之前先挂个显存监控nvidia-smi -l 1或者用psutil在脚本里打点都行。我实测 40 页一次性 prefill 的数据大致是这样模式页数显存峰值首字延迟整档耗时本地 base40~18GB4.2s96s本地 base20~11GB2.6s51s本地 base10~7GB1.5s27sAPI 逐页40本地无占用1.1s/页约 140s首字延迟随页数增长是 prefill 阶段的视觉 Token 累积导致的但因为 DeepEncoder 把每页压到 256 个 Token40 页也就一万出头还在可控范围。真正体现 R-SWA 价值的是解码阶段——输出到 6000 token 时标准注意力方案的 TPS 会掉到 5800 左右而 R-SWA 还能稳在 7800 上下这就是常数窗口的功劳。4.2 逐页 vs 整档对照脚本compare_pages.py用来验证跨页字段一致性思路是整档 OCR 一次输出逐页 OCR 分别输出然后比对关键字段是否在两种模式下都完整出现且值一致。import tomllib, re, glob with open(config.toml, rb) as f: cfg tomllib.load(f) keys cfg[compare][field_keys] def extract(text, key): m re.search(rf{key}[:\s]*([^\n]), text) return m.group(1).strip() if m else None whole open(output/whole/result.md).read() perpage \n.join( open(p).read() for p in sorted(glob.glob(output/perpage/*.md)) ) for k in keys: w, p extract(whole, k), extract(perpage, k) status 一致 if w p else 不一致 print(f[{status}] {k}: 整档{w} | 逐页{p})跑下来最直观的差异在跨页表格。逐页模式下一张跨第 12、13 页的资产负债表会被切成两段表头在第 12 页末尾、数据在第 13 页开头拼接后表头丢失。整档模式下模型能看到完整上下文表格结构保持完整TEDS 还原率明显更高。这就是「不丢上下文」的实际价值。4.3 成功结果长什么样整档 OCR 输出的 Markdown 应该满足几个特征标题层级用#/##正确嵌套、表格用标准 Markdown 表格语法、公式用 LaTeX 包裹、阅读顺序符合人类阅读习惯。如果你拿到的是纯文本堆叠、表格变成空格分隔的乱码说明 prompt 或者image_size参数不对回去检查是不是误用了单页的 gundam 模式跑多页。5. 本篇常见错排查报错一CUDA out of memory在 prefill 阶段。最常见原因是batch_pages设太大或者dpi拉到 600 导致单页 Token 数暴涨。先把batch_pages降到 20dpi回 300。如果还 OOM检查是不是没设torch_dtypetorch.bfloat16用 fp32 加载权重会多吃一倍显存。报错二输出出现大段重复段落。这是no_repeat_ngram_size和ngram_window没配对。多页场景ngram_window必须设到 1024设 128 只能防住短程重复长文档跑到几千 token 后照样复读。同时确认max_length给够了 32768截断也会诱发重复。报错三跨页表格还是断的。先确认你走的是infer_multi而不是逐页infer。很多人图省事循环调单页接口那本质上还是逐页失忆R-SWA 根本没发挥作用。另外image_size在多页模式必须固定 1024动态分辨率是单页 gundam 模式才用的。报错四API 调用返回 401 或 403。检查TAOTOKEN_API_KEY环境变量是否真的导出到了当前 shellecho $TAOTOKEN_API_KEY确认一下。基址必须是https://taotoken.net/api不要自己拼/v1之外的路径。如果 Key 没问题还是 403去控制台看下额度是否用尽。报错五PDF 转图后部分页面空白。多半是 PDF 里有矢量图层或者加密PyMuPDF 渲染时没拿到内容。换dpi200再试或者用page.get_pixmap(alphaFalse)显式关掉透明通道。扫描件本身质量差的话前置做一次去噪比调模型参数更有效。6. 把链路接起来统一 Key 与后续扩展跑通之后你的文档解析流水线大概是这个形态PDF 转图 → Unlimited-OCR 整档解析 → 输出结构化 Markdown → 后续字段抽取或入库。最后一步如果要用模型做字段抽取、摘要或者问答就可以接上 TaoToken 的统一 Key不用再单独维护一套鉴权。模型对话入口在https://taotoken.net/model-chat接入文档在https://taotoken.net/doc长期跑编码或 Agent 任务的话 Coding Plan 在https://taotoken.net/coding-plan。一个实用技巧整档 OCR 出来的 Markdown 里表格和公式已经结构化但字段名可能不统一比如「合同编号」和「合同号」混用。这时候别急着写正则把整段 Markdown 丢给对话模型做一次规范化抽取准确率比正则高得多而且改 prompt 就能适配新文档类型不用改代码。最后留个坑给你们踩40 页是官方标称的舒适区我试过 60 页编辑距离开始爬升主要误差来自小字体在 1024 分辨率下糊掉。如果你的文档字号特别小与其硬堆页数不如先做一次超分或者分块把单页清晰度提上去再喂给模型。