# 文档解析与 OCR

> Cube Agent 2.2.0 正式版（构建 2002007）使用说明。
> 分类：聊天。内容基准：2026-11-07。
> 网页：https://cubeagent.app/docs/documents_ocr/

## PDF 解析入口

聊天中点击待发送或已发送的 PDF 附件进入正文预览，再选择 **更换解析方式 / 文档 OCR**；正文预览中的 **预览原文件** 可用于对照原件。已发送 PDF 采用新结果后，AI 下一次读取会使用更新的内容，不会改写已经生成的回答；正在回复时需先等待完成。知识库导入预览及已保存原 PDF 的文档也可进入 **文档解析** 面板。只保存了正文的旧文档，需重新提供 PDF 才能再次识别。

- **原生**：适合含文本层的 PDF，在本机提取文字。
- **端侧 OCR**：适合扫描件，在本机渲染页面并识别。
- **解析服务**：选择已配置的 MinerU、PaddleOCR 官方云服务或已有兼容服务/视觉模型。

## 配置 MinerU 或 PaddleOCR

打开 **设置 → 模型与用量 → 默认模型 → 文档解析**，进入服务管理，点 **添加文档服务**。选择官方服务，填写 API Token 或 AI Studio Access Token、选择模型，再点 **保存服务**；需要时设为默认。也可以从解析面板的 **管理** 进入。

选择或保存服务不会上传文档。开始解析时请核对服务、模型与上传范围。官方云服务直接接收原 PDF；即使选择部分页面，整份原件仍会上传，确认面板会说明实际范围。视觉模型等其他方式的范围以当次确认提示为准。云服务可能计费，额度和可用性由服务商决定。

## 审核与使用结果

新正文生成后先核对页数、内容及完整性提示，可以对照原文，再选择 **使用此结果**。只识别出部分内容不代表全文完整；失败或取消不会自动替换旧正文。知识库采用新正文后需为更新的文档重新建立语义索引。

## 切换解析方式

在结果页点 **换种方式**，或在上传确认页点 **返回调整**，重新选择原生、端侧 OCR 或解析服务。新任务准备成功后才替换旧任务；准备失败会保留旧任务和结果。替换按完成后的任务数量和 PDF 容量检查，不会把同一旧任务重复算入额度。

旧任务还在运行时，先停止任务；若提示正在停止并释放资源，等待释放后再点 **下一步 / 开始解析**。更换解析服务后仍需核对上传范围，新请求可能重新计费。

## 管理解析任务

- 解析面板中的 **管理解析任务** 可查看各文档的任务；点当前文档的任务回到确认或结果页。右上角 **完成** 只关闭面板，不会停止或丢弃任务。
- 也可从 **设置页右上角** 打开 **任务中心**；在 **设置 → 显示与外观 → 界面** 开启「在其他页面显示任务中心入口」后，助手、对话和知识库页也会显示入口。在 **文档解析** 分组查看任务。**当前** 显示尚待处理的任务；**最近记录** 显示已采用结果或已清理原件的记录；**全部** 同时显示两类。
- 点任务行查看状态、错误原因和已有正文预览；点右侧 **更多操作** 可 **停止任务** 或 **丢弃任务**。任务仍占用资源时需先停止并等待释放，再丢弃。
- **结果待确认** 表示结果已保存、尚未采用。任务中心的 **如何确认结果** 会说明入口：聊天中打开原 PDF 附件 → **更换解析方式 / 文档 OCR**；知识库中返回原文档的解析入口。面板会恢复已有结果，核对后点底部固定的 **使用此结果**；部分内容需再次确认。打开和采用已有结果不会重新发起解析请求，无需重新上传或换种方式。右上角 **完成** 只关闭面板，不等于采用结果。
- 从知识库 **添加文档** 开始解析、尚未保存就退出预览时，知识库可能仍显示 **0 篇资料**。在任务中心找到该文档的 **结果待确认** 任务，点 **恢复导入并保存**，核对已保留正文、选择目标知识库，再点 **保存到知识库**。恢复和保存不重新调用解析服务；保存成功后才标为已采用，并将原 PDF 一并保存。关闭恢复页或保存失败会保留任务，可稍后重试；请勿先丢弃任务。
- **丢弃任务** 会删除该任务未采用的结果及解析副本，保留原文档；确认后才执行。需要继续识别或采用结果，请回到原聊天附件或知识库文档的 **文档解析**。重启应用不会自动续跑付费请求。

## 遇到本地任务限制怎么办？

- **此文档已有运行中或排队任务**：点 **查看当前文档任务**，查看进度或停止旧任务；准备文件、清理原件或停止释放资源期间，稍后重试。
- **运行中和排队任务达到 4 个**：等待任务结束，或在 **管理解析任务 / 任务中心** 停止不再需要的任务。
- **待处理任务达到 16 个**：丢弃不再需要的任务，或回原文档采用结果。失败、已停止和待确认的任务也会保留，关闭面板不会释放额度。
- **保留的解析 PDF 加上本次文件超过 400 MiB**：丢弃不再需要的解析任务后重试。这里统计解析副本，不能据此判断手机存储空间已满。
- **解析任务尚未载入**：点 **重新加载解析任务**；任务列表载入失败时点 **重新加载**。

## 中断、重试与错误

已有远端任务的重试会继续查询原任务或取回结果，不自动重新创建任务。若提交结果不明确，应用会提示，不能据此认定服务未收到文件。停止等待不等于厂商取消任务或停止计费；后台运行受系统限制。

服务繁忙或请求受限时稍后重试；额度不足时检查服务商账户；鉴权失败时检查所选服务与 Token。PaddleOCR 的 10010 表示任务提交队列已满，与每日剩余页数不是同一项限制。

## 其他文档与图片

聊天和知识库还支持 DOCX、XLS/XLSX、OFD、PPT/PPTX、EPUB 等文档；解析、预览和模型上下文各有容量限制，保存原件成功不代表所有方式都能完整处理。单独图片的 OCR 设置仍由 **默认模型 → OCR 识图** 管理，与文档解析服务独立。