Unlimited OCR 2部署指南：千页文档解析服务上线实践

一、部署概述：部署什么、达到什么效果

本文要完成的部署任务，是将百度于10月27日正式开源的超长文档解析模型Unlimited OCR 2（模型权重已发布至开源模型托管平台）部署为一套可稳定对外提供服务的文档解析系统。部署完成后，系统应达到以下效果：

• 支持单页与多页两种推理模式，覆盖从单张扫描件到整本图书的输入跨度；
• 对按顺序输入的多页文档图像，在同一次请求中完成各页解析，输出严格保留页面顺序的文本结果；
• 依托跨页上下文，对跨页段落、跨页表格等连续内容保持语义连贯；
• 在有限显存条件下稳定处理百页级乃至千页级文档——官方展示了总页数超过3600页的系列图书连续解析实测案例。

本文适合的读者：需要搭建文档解析或OCR服务的AI应用开发者；负责GPU推理服务上线与维护的运维工程师；进行资源规划与技术选型的架构师；以及需要批量完成档案、图书、合同、研究报告等长文档数字化的企业技术团队。

部署前需要建立的基本认知：Unlimited OCR 2属于视觉语言大模型形态的解析服务，输入是按序排列的文档图像（通常由PDF逐页转换而来），输出是文本结果；系统资源瓶颈集中在GPU显存与算力；在服务形态上，它通常表现为“常驻推理服务+异步任务队列+对象存储”的组合，而非一次性的脚本调用。理解这三点，才能理解后文每一步部署动作的原因。

二、模型机制与部署设计的对应关系

部署方案不能脱离模型机制凭空设计。相比前代主要处理数十页文档，Unlimited OCR 2的三项核心更新，分别对应三个部署设计要点。

1. 跨页连续解析 → 接口以“文档”为一等公民。 模型接受按顺序排列的多页文档图像，在同一次请求中解析各页内容，输出保留页面顺序并利用跨页上下文处理连续内容。因此，服务接口应按“文档（页面序列）”而非“单张图片”设计：预处理层负责生成有序页面序列，后处理层负责严格保序聚合，任何一个环节打乱页序都会破坏解析效果。

2. 稀疏参考滑动窗口注意力（SR-SWA）→ 显存效率决定部署密度。 SR-SWA通过页面门控筛选与当前解析相关的页面，并利用视觉Token桶保留长距离参考信息，避免对全部历史视觉Token的重复计算，从而显著减少长文档解析中的注意力计算量与显存开销。对部署的直接意义是：同等显存可支撑更长文档与更高并发；同时，要真正获得这一收益，推理运行时必须正确启用该机制，这是选型时需要重点确认的事项。

3. 超长文档处理 → 分页窗口调度是核心配置项。 模型结合固定规模的工作参考集合与分页窗口调度，在有限上下文窗口内处理更长文档。分页窗口大小直接决定单次调度纳入上下文的页面范围，进而影响显存占用与跨页效果，是部署中最需要通过压测校准的参数。

能力与性能基线：官方公布的评测结果显示，该模型在面向多页文档解析的公开基准上取得84.6分，在面向百页级长文档解析的公开基准上取得77.1分；在官方百页文档测试中，SR-SWA单步解码速度相较全注意力方案提升约7倍，相较前代稀疏窗口方案（R-SWA）提升约5.6倍。容量规划时必须注意：这是单步解码速度的对比，并非完整PDF解析流程的端到端加速比，吞吐估算应以端到端压测为准。

三、典型部署场景

• 档案与图书批量数字化：整卷档案、成套图书的离线文本化，输入规模大、页数多，是超长文档连续解析的典型场景，适合采用异步批处理架构。
• 企业知识库与检索增强语料生产：知识库建设需要把历史文档、制度文件、技术手册批量转为可检索文本，跨页上下文能力可明显减少段落断裂带来的语义损失。
• 长文档结构化处理：合同、审计报告、招股说明材料、标书等动辄数百页的文档，需要整册解析后再做信息抽取与 downstream 分析。
• 流水线中间件：将解析服务嵌入数据加工流水线，作为上游图像与下游文本应用之间的标准组件，通过API对外提供能力。

场景不同，部署形态差异很大：在线服务要求低时延与弹性扩缩容；离线批处理要求高吞吐与错峰调度。建议在部署前先明确自身场景归属，再决定资源与架构。

四、整体架构与组件拆解

一套生产可用的部署通常包含以下组件，每个组件的存在都有明确理由：

层次	组件	职责与设计要点
接入层	负载均衡、API网关	统一入口、身份鉴权、限流熔断；长文档请求耗时长，必须在入口做并发控制
调度层	任务队列、任务状态存储	超长文档解析耗时以分钟计，同步HTTP极易超时，应异步提交、状态轮询或回调通知
预处理层	PDF转图像、排序、压缩	将PDF按页转为图像并保证顺序，按显存预算规整图像尺寸
推理层	GPU节点、模型服务	承载模型本体，选择原生框架或高性能推理引擎，管理分页窗口与批处理
后处理层	结果聚合模块	将分页输出按页序拼接为完整文档文本，处理分页边界
存储层	权重存储、输入输出对象存储	权重多副本分发，文档与解析结果的生命周期管理
可观测层	日志、指标、告警	采集GPU利用率、显存峰值、接口时延、队列积压等关键指标

之所以要完整拆解这套架构，是因为Unlimited OCR 2解决的“显存与长文档”矛盾发生在推理层，但请求排队、页序管理、结果聚合等问题都发生在推理层之外——任何一层缺失，“千页解析”在生产上都无法真正可用。

五、前置准备清单

硬件资源。 官方原生框架示例基于80GB级大显存数据中心GPU给出，且官方明确提示：实际内存需求与文档长度、图像尺寸及并发量有关。因此建议：验证环境配置单卡80GB级显存即可跑通功能；生产环境则必须结合真实文档的页数分布、图像分辨率和目标并发做压测后再定容，避免按“单卡跑通”想当然地推算产能。

软件环境。 需要准备：服务器操作系统；与GPU匹配的驱动及计算运行时；独立的语言运行时环境与深度学习框架依赖；如选择高性能路径，还需安装对应的推理引擎。生产环境强烈建议以容器镜像固化上述依赖，保证开发、测试、生产三套环境的版本一致性。

模型与依赖获取。 从开源模型托管平台获取Unlimited OCR 2权重，下载后进行完整性校验并记录版本；离线或内网环境应通过内网镜像渠道分发权重，避免部署过程依赖公网。

网络准备。 规划服务监听端口与访问策略：推理服务建议只监听内网地址，对外统一经网关暴露；如需跨网络调用，提前打通安全组与防火墙规则。

数据准备。 准备覆盖典型页数量级（1页、10页、100页）的样例文档集，以及将PDF转换为按序图像的通用工具链，用于部署后的功能验证与性能压测。

六、部署流程：六步完成上线

步骤一：环境初始化。 安装GPU驱动与计算运行时并验证设备可用；创建独立的运行时环境或容器；确认磁盘空间足以容纳权重与临时文件。此步的目的是排除底层环境干扰，让后续问题排查有干净基线。

步骤二：获取并校验模型权重。 从开源模型托管平台下载权重至约定目录，完成校验并记录版本号。版本信息必须写入部署清单，这是后续回滚的依据。

步骤三：选择推理路径。 官方提供两类方案：

路径	说明	适用场景
原生框架推理	基于主流深度学习框架的原生方案，支持单页及多页推理，官方示例基于80GB级显存GPU	功能验证、精度对齐、二次开发
高性能推理引擎	官方提供分页窗口和并发参数配置	生产环境、高吞吐、多路并发

建议采用两段式路径：先以原生框架方案在验证环境确认效果符合预期，再将同一套权重迁移至高性能推理引擎做生产部署；两步使用相同版本权重与相同验证用例，确保效果一致。

步骤四：服务化封装。 为模型封装标准API：请求包含文档标识与按序页面图像；超长文档建议分段提交、服务端按页序拼接；短文档可走同步接口，长文档走异步任务接口。通用配置示例如下（伪代码，仅示意配置逻辑，非真实命令）：

MODEL_PATH = "/data/models/unlimited-ocr-2"   # 校验后的权重目录
engine = InferenceEngine(
    model_path     = MODEL_PATH,
    attention_mode = "sr-swa",        # 启用稀疏参考滑动窗口注意力
    paging_window  = W,               # 分页窗口大小，按显存压测确定
)
service = DocumentParseAPI(
    engine            = engine,
    max_pages_per_req = N,            # 单请求页数上限，超长文档分段提交
    concurrency       = C,            # 并发数，显存占用随其近似线性增长
    image_max_side    = S,            # 图像长边上限，权衡精度与显存
    request_timeout   = T,            # 长文档任务建议改走异步接口
)
service.listen(host="内网地址", port=8080)

上述参数没有通用标准答案：分页窗口、并发数、图像尺寸三者共同决定显存峰值，官方亦提示实际内存需求与文档长度、图像尺寸及并发量有关，务必用自有文档的压测数据回填，而不是照抄他人配置。

步骤五：启动服务并开放访问。 由进程管理器或容器编排托管服务进程，配置健康检查与异常自动重启；先在内网完成连通性验证，再经网关开放访问并启用传输加密。

步骤六：冒烟验证。 用预备的样例集执行最小闭环：单页解析返回正常文本、多页解析页序正确、长文档任务可提交可查询，通过后再进入正式验证。

七、关键配置说明与风险点

• 分页窗口大小：决定调度进上下文的页面范围。过小会削弱跨页上下文的连续性，过大则推高显存峰值。建议以目标文档的P99页数为输入做梯度压测，找到效果与资源的平衡点。
• 并发参数：高性能推理引擎提供并发配置。提升并发可增加吞吐，但显存占用同步上升，超并发是显存溢出的最常见诱因。
• 单请求页数上限：设置上限的目的是把“任意长度输入”转化为“可预估资源消耗”，超长文档由调用方分段提交、服务端按序聚合。
• 图像尺寸：视觉Token数量随分辨率增长，直接决定计算量与显存。在满足识别精度的前提下取最低可用分辨率，是性价比最高的优化手段。
• 超时与重试：长文档任务耗时波动大，同步接口要设置宽松超时，异步队列要设计幂等重试，避免任务重复消费浪费算力。

八、上线验证清单

1. 功能验证：单页、多页用例输出内容正确；与验证环境（原生框架方案）的结果对比，确认生产路径效果一致。
2. 顺序性验证：构造带有明显页序特征的文档，确认输出页序与输入一致。
3. 连续性验证：构造跨页段落、跨页表格用例，确认上下文连续、无断裂或重复。
4. 性能验证：记录端到端时延、吞吐与显存峰值，与容量规划对照；注意单步解码速度的倍数关系（约7倍/5.6倍）不能直接换算为端到端加速比。
5. 稳定性验证：按目标并发持续压测数小时以上，观察显存是否随时间增长（排查泄漏）、错误率是否稳定。
6. 监控确认：确认GPU利用率、显存、接口时延、队列积压等指标已接入监控并配置告警阈值。

九、常见问题与排查思路

• 显存溢出（OOM）：最常见问题。按“降并发 → 减分页窗口 → 降图像分辨率 → 减少单请求页数”的顺序逐项调整，每次只改一项并复测，定位真实瓶颈。
• 推理缓慢：先确认稀疏注意力机制在新路径中确实生效，再查GPU利用率是否打满、是否被预处理或后处理拖累、是否因分页窗口过小导致调度过于频繁。
• 输出乱序或跨页断裂：检查预处理是否保序、后处理是否按页序拼接、调用方分段提交时是否携带正确的页码信息。
• 长任务超时：将长文档任务从同步接口迁移至异步队列，检查状态轮询或回调是否正常、重试是否幂等。
• 权重加载失败：核对磁盘空间、文件完整性校验结果，以及运行时与模型版本的匹配关系。
• 服务不可达：依次检查进程状态、监听地址与端口、安全组与防火墙规则、网关路由配置。

十、运维与优化建议

• 监控告警：除通用资源指标外，重点盯防显存峰值与队列积压——这两个指标往往先于故障出现异常。
• 弹性与扩容：多实例部署加负载均衡；批处理任务可错峰调度至低价时段，在保证峰值体验的同时控制成本。
• 版本管理与回滚：始终保留上一版本的权重与服务镜像；新版本以灰度方式上线，异常时可在分钟级切回。版本号与验证用例应作为部署清单固化下来。
• 安全控制：服务仅内网监听、网关统一鉴权与白名单控制、传输链路加密；文档数据涉及敏感信息时，明确输入输出的留存策略并纳入日志审计。
• 成本治理：GPU按压测结论定容、不盲目超配；输出文本与中间图像设置存储生命周期策略；闲时释放验证环境的临时资源。
• 持续迭代：跟踪官方版本更新，新版本上线前用固定验证集回归效果，避免“升级即事故”。

十一、总结

部署Unlimited OCR 2的主线可以概括为：以“文档（页面序列）”为核心设计接口，以显存压测确定分页窗口、并发与图像尺寸三项关键参数，以“原生框架验证、高性能引擎生产”的两段式路径完成上线，再以功能、顺序性、连续性、性能、稳定性五类验证确认部署质量。模型通过SR-SWA与分页窗口调度，把千页级文档的解析压缩到有限显存可承载的范围内——而部署工程师的职责，是把这一能力封装成可观测、可回滚、可扩缩容的稳定服务，并在上线后持续守护其容量、安全与成本。