> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# PDF 处理与解析联动预览

> 使用 PDF 文档转换插件提取版式、表格和图片，并在原始 PDF 与解析块之间进行联动检查。

XpertAI 为 PDF 提供两类互补能力：

* **知识入库转换器**负责把 PDF 转换为可分块、可索引的 Markdown 和结构化版式数据。其中，百度 PaddleOCR‑VL 可以驱动 PDF 解析联动预览。
* **Agent PDF 工具**允许数字专家按需把任务中的 PDF 转为 Markdown 和逐页图片，不会自动把结果写入知识库。

理解两者的区别有助于选择正确的处理链路。

| 能力                     | 使用位置      | 主要用途                                  | 是否直接进入知识库流水线  |
| ---------------------- | --------- | ------------------------------------- | ------------- |
| 百度 PaddleOCR‑VL 文档转换器  | 知识流水线     | 复杂 PDF、扫描件、表格、图片、公式和版式解析              | 是             |
| 百度 Unlimited‑OCR 文档转换器 | 知识流水线     | 长文档 Markdown 解析                       | 是             |
| MinerU 文档转换器           | 知识流水线     | 官方精准解析或自托管 PDF 解析，支持 OCR、公式、表格和原始结果归档 | 是             |
| Pdfium：PDF 转 Markdown  | Agent 工具集 | Agent 临时读取 PDF、生成逐页图片和 Markdown       | 否，除非后续工作流显式入库 |

## 百度 OCR 文档转换插件

`@xpert-ai/plugin-baidu-ocr` 在 XpertAI 中注册一个“百度 OCR”系统集成和两个文档转换器。两者复用平台现有的凭证、文件权限、后台文档任务、分块器和索引流程，不创建独立的知识处理链路。

### 两个转换器

| 转换器              | 输出与特点                                | 推荐场景                     | PDF 联动预览    |
| ---------------- | ------------------------------------ | ------------------------ | ----------- |
| 百度 PaddleOCR‑VL  | Markdown、分页结构、版式块、表格、图片、坐标、多边形和可选行坐标 | 扫描 PDF、复杂排版、技术手册、表格和图文混排 | 支持          |
| 百度 Unlimited‑OCR | 稳定 Markdown，并可保存服务返回的原始文件            | 内容较长、主要关注文本结果的文档         | 当前不提供坐标叠加预览 |

<Note>
  PDF 双栏联动预览要求转换器输出分页版式和坐标。当前百度 OCR 插件中，PaddleOCR‑VL 满足这一要求；Unlimited‑OCR 只使用稳定的 Markdown 结果，不假设服务返回未公开的 JSON 结构。
</Note>

### 支持的输入

插件支持当前百度文档解析接口接受的 PDF、JPG/JPEG、PNG、BMP、TIF/TIFF、OFD、DOC/DOCX、TXT、WPS 和 PPT/PPTX。

本页重点介绍 PDF。其他格式可以进入相同转换流程，但左侧“原文坐标叠加”当前只在原文件为 PDF 时显示。

### 配置百度 OCR 连接

1. 由组织管理员安装并启用 `@xpert-ai/plugin-baidu-ocr`。
2. 进入“设置 > 系统集成”，新建“百度 OCR”连接。
3. 填写百度智能云 OCR 应用的 API Key 和 Secret Key。
4. 选择上传方式、轮询间隔和任务超时时间，保存并验证连接。

API Key 和 Secret Key 使用平台凭证机制保存，不会写入文档 metadata 或任务日志。

#### 上传方式

| 方式     | 说明                                      |
| ------ | --------------------------------------- |
| 自动     | 推荐。存在本地文件内容时优先使用 Base64，并按服务限制处理大型 PDF。 |
| Base64 | 直接上传文件内容，适用于平台能够读取原始文件的场景。              |
| 公开 URL | 将外部可访问的文档 URL 交给服务端拉取。URL 必须能被百度服务访问。   |

默认轮询间隔为 7 秒，默认任务超时为 1800 秒。可根据文件大小和服务响应情况调整。

### 在知识流水线中使用

1. 打开知识流水线的“文档转换器”节点。
2. 选择“百度 PaddleOCR‑VL”或“百度 Unlimited‑OCR”。
3. 选择已经创建的百度 OCR 集成连接。
4. 配置转换选项并完成流水线的分块器、嵌入和知识库节点。
5. 测试并发布流水线，然后上传或重新处理 PDF。

PaddleOCR‑VL 提供以下选项：

| 选项     | 默认值 | 作用                                    |
| ------ | --- | ------------------------------------- |
| 解析统计图表 | 关闭  | 请求服务识别并描述统计图表内容。                      |
| 合并跨页表格 | 开启  | 合并跨页连续表格。                             |
| 识别标题层级 | 开启  | 推断标题等级并生成更有结构的 Markdown。              |
| 识别印章内容 | 关闭  | 识别文档中的印章区域。                           |
| 返回行坐标  | 开启  | 保存更细粒度的文本行位置信息。                       |
| 保留原始结果 | 开启  | 保存 Markdown、结构化 JSON 和任务响应，便于诊断与预览重建。 |
| 保留解析图片 | 开启  | 在服务签名链接有效期内下载并保存解析图片。                 |

Unlimited‑OCR 当前提供“保留原始结果”选项，用于保存 Markdown、可用 JSON 和任务响应。

### 大型 PDF

百度接口当前每个解析任务最多处理 500 页 PDF。对于超过限制、且平台能够读取原始字节的 PDF，插件会：

1. 按页数和上传大小切分为有界的顺序任务；
2. 逐批提交并等待结果；
3. 将每批页码重新映射为原 PDF 的全局页码；
4. 合并 Markdown、版式块、图片资产和来源映射；
5. 保留批次索引、源页范围、任务 ID 和日志 ID，便于排查失败批次。

某一批次失败时，错误信息会明确显示批次序号和原文页码范围，不会把不完整结果静默写入索引。

## MinerU 文档转换插件

`@xpert-ai/plugin-mineru` 将 MinerU 接入 XpertAI 知识流水线，支持 **MinerU 官方精准解析 API** 和 **自托管 mineru-api / mineru-router** 两种部署方式。它复用 XpertAI 的系统集成、凭证、工作区文件、后台任务、分块和索引能力。

### 服务模式

| 模式     | 接口与特点                                                            | 认证                |
| ------ | ---------------------------------------------------------------- | ----------------- |
| 官方 API | 使用 `https://mineru.net/api/v4` 精准解析 API；支持文件预签名上传、公开 URL 和批量任务轮询 | Access Token 必填   |
| 自托管    | 使用当前 mineru-api 或 mineru-router 的同步 `/file_parse` 接口             | Token 可选，取决于自托管网关 |

插件没有使用官方 Agent 轻量 API。知识入库需要处理更大的文档并保存结构化产物，因此官方模式使用精准解析 API。

### 配置 MinerU 连接

1. 由组织管理员安装并启用 `@xpert-ai/plugin-mineru`。
2. 进入“设置 > 系统集成”，新建 MinerU 连接。
3. 选择“官方 API”或“自托管”。
4. 填写服务地址和 Access Token；官方地址不填写时使用默认 v4 地址。
5. 官方模式选择文件提交方式，并配置轮询、任务和单次请求超时。
6. 保存并验证连接，然后在知识流水线的文档转换节点中选择 MinerU。

#### 官方文件提交方式

| 方式     | 说明                                                |
| ------ | ------------------------------------------------- |
| 自动     | 推荐。有工作区原文件时通过 MinerU 预签名 URL 上传；没有本地文件时回退到公开 URL。 |
| 文件上传   | 强制读取工作区原文件并通过预签名 URL 上传。                          |
| 公开 URL | 使用外部可访问的文档 URL 创建解析任务。                            |

官方模式默认轮询间隔为 5 秒，任务超时为 1800 秒，单次请求超时为 1200 秒。Access Token 使用平台凭证机制保存，不会写入任务日志或文档 metadata。

### 转换选项

| 选项          | 默认值        | 作用                                         |
| ----------- | ---------- | ------------------------------------------ |
| OCR         | 开启         | 对扫描内容执行 OCR。                               |
| 公式识别        | 开启         | 提取并保留公式。                                   |
| 表格识别        | 开启         | 解析文档表格。                                    |
| 语言          | `ch`       | 选择 MinerU OCR 语言包。                         |
| 模型版本        | `vlm`      | 选择 `vlm` 或 `pipeline`。                     |
| 自托管后端       | `pipeline` | 选择 pipeline、hybrid、VLM 或对应 HTTP client 后端。 |
| 自托管模型服务 URL | 空          | 为 HTTP client 后端指定模型服务地址。                  |
| 解析方式        | `auto`     | 自托管模式可选择 `auto`、`txt` 或 `ocr`。             |
| 保留原始结果      | 开启         | 保存 Markdown、结构化 JSON、模型输出和图片资产。            |

### 官方 PDF 处理流程

在推荐的“自动”方式下，插件会读取 XpertAI 工作区中的 PDF，通过 MinerU 批量接口取得预签名上传 URL，上传文件并轮询解析结果，最后下载完整结果压缩包并写回知识库工作区。

MinerU 官方精准解析 API 当前每个文件限制为 200 页和 200 MB。超过限制的 PDF 会被切分为：

* 每个部分最多 200 页；
* 每个部分控制在约 190 MiB；
* 每个官方上传批次最多提交 50 个部分；
* 最终 metadata 保留源页范围、批次 ID、批次序号和总批次数。

显式“公开 URL”方式使用官方单任务 URL 接口。自托管模式由 XpertAI 后台任务调用同步 `/file_parse`，因此无需再建立插件私有任务队列。

### 输出与安全

MinerU 将 Markdown 作为文档转换结果交给现有分块器，并可以归档：

* `content_list.json` 和稳定的 `content_list_v2.json`；
* `middle.json`、`layout.json`、模型原始输出；
* Markdown 引用的图片和其他结果资产；
* 服务类型、模型、后端、批次和源页范围 metadata。

Markdown 与 HTML 中的图片路径会被改写为 XpertAI 工作区 URL。下载结果压缩包时，插件会校验 ZIP 条目路径并限制解压规模，避免越界路径和无界写入。

<Note>
  MinerU 当前会保存结构化结果和源页范围，但尚未输出 XpertAI PDF 联动预览所需的分页版式坐标契约，因此不会显示原文坐标框或双栏解析联动。MinerU 处理后的最终 Markdown 和 Chunks 仍可正常入库、检索和管理。后续转换器若输出统一版式契约，即可接入同一套预览框架。
</Note>

## PDF 解析联动预览

使用 PaddleOCR‑VL 完整处理 PDF 后，在文档列表点击“打开解析预览”，或进入文档详情的“解析预览”标签页，即可同时检查原 PDF 和解析结果。

### 双栏界面

* **左侧原文**：使用原始 PDF 渲染页面，并将识别坐标或多边形叠加在页面上。
* **右侧解析结果**：按页展示 Markdown、结构、表格、图片和 JSON。
* **分栏调节**：拖动分隔线调整两侧宽度；也可以用键盘左右键微调。
* **移动端**：在“原文”和“解析结果”两个面板之间切换。

原文工具栏支持上一页、下一页、输入页码、缩放和适应宽度。页面缩放范围为 50%～300%。

### 版式类型

解析结果统一为与服务商无关的版式类型：

```text theme={null}
文本、标题、表格、图片、公式、页眉、页脚、脚注、页码、印章、其他
```

左侧可以按类型显示或隐藏坐标框。右侧只有在文档包含对应元素时才显示“表格”和“图片”标签页。

### 点击与滚动联动

* 滚动左侧原文时，右侧会同步到相同页和相近的页内进度；
* 滚动右侧解析结果时，左侧也会反向同步；
* 点击 PDF 上的坐标框，会选中对应解析块并将右侧结果滚动到该块；
* 点击右侧解析块，会高亮左侧对应区域；
* 当前页和选中块写入页面地址参数，刷新或在有权限的会话中打开链接时可以恢复位置。

同步按“页码 + 页内相对进度”计算，因此即使左右两侧内容高度不同，也能保持可理解的位置对应关系。

### 解析结果视图

| 视图       | 说明                               |
| -------- | -------------------------------- |
| Markdown | 按阅读顺序渲染每个解析块的 Markdown，并显示已保存图片。 |
| 结构       | 显示块类型、原始服务类型、阅读顺序和坐标。            |
| 表格       | 只显示表格解析块。                        |
| 图片       | 只显示图片解析块及保存的图片资产。                |
| JSON     | 按页加载原始结构化数据，用于高级诊断。              |

### 与最终知识分块的关系

“解析预览”展示的是**文档转换器在文本切分之前识别出的版式块**；“Chunks”标签页展示的是经过分块器处理、最终用于索引和召回的知识分块。两者不会被混为同一种数据。

PaddleOCR‑VL 会在合并 Markdown 时生成来源映射。分块器切分后，每个最终分块可以保留：

* 起止源页 `pageStart` / `pageEnd`；
* 单页分块的 `page`；
* 参与该分块的原始版式块 ID；
* 关联图片等资产。

这些信息为召回引用、问题排查和后续的精确溯源保留了稳定依据。当前可视化点击联动主要发生在**原 PDF 与解析版式块**之间；最终知识分块仍在“Chunks”标签页独立管理。

### 大文档性能

预览不会一次加载整份大型文档：

* 首次只读取轻量页面索引；
* 解析页按当前页附近的窗口加载；
* PDF 只渲染当前页前后有限范围；
* JSON 在进入对应标签且滚动到页面时才加载；
* 原始 PDF 支持按字节范围读取。

因此，大型 PDF 仍可连续滚动，而服务端和浏览器不需要同时持有所有页面详情。

### 安全与一致性

* 原始 PDF、解析页和图片资产都使用知识库权限进行访问控制；
* 客户端只获得不透明的资产 ID，不暴露服务端文件路径；
* 解析快照按页保存并进行大小与哈希校验；
* 原文件内容变化或快照完整性校验失败时，旧预览不会继续显示为有效结果；修改转换器配置后需要执行完整重新处理，才能生成对应的新预览；
* PDF 页面比例与识别坐标不兼容时，系统隐藏坐标叠加并显示提示，避免错误标注。

如果解析预览显示不可用或过期，请选择“转换并处理”执行完整重新处理。仅重新分块适合修改 Chunker 参数，但不会用新的转换器重新识别原文。

## Pdfium：Agent PDF 转 Markdown 工具插件

`@xpert-ai/plugin-pdfium` 是 Agent 工具插件。启用后，可以为数字专家添加“PDF to Markdown / PDF 转 Markdown”内置工具集，其工具名为 `pdf_to_markdown`。

Agent 可以从以下任一来源读取 PDF：

* 文件 URL；
* 工作区文件路径；
* Base64、Buffer 或 Uint8Array 文件内容；
* 一个文件对象或文件对象列表。

工具逐页提取 PDF 文本，并按指定渲染比例输出 PNG 页面图片。默认比例为 2.0。结果包含：

* 汇总 Markdown，其中按页插入图片和可提取文本；
* `result.md`；
* `page-1.png`、`page-2.png` 等逐页图片；
* 文件路径、可用时的工作区 URL、MIME 类型和图片页码。

该插件不需要外部账号或 API Key，适合 Agent 临时阅读任务附件、生成页面图片或把 PDF 内容交给后续工具。

<Warning>
  Pdfium 使用 PDF 自带文本层提取文字，它不是 OCR 服务。扫描页如果没有可提取文本，工具仍会生成页面图片，但不会自动识别图片中的文字。需要扫描件 OCR、表格识别或 PDF 坐标联动时，请使用 PaddleOCR‑VL 等知识入库转换器。
</Warning>

## 选择建议

| 需求                                     | 推荐能力                                            |
| -------------------------------------- | ----------------------------------------------- |
| 将 PDF 长期写入知识库并参与召回                     | 知识流水线文档转换器                                      |
| 扫描件、复杂版式、表格和原文坐标联动                     | 百度 PaddleOCR‑VL                                 |
| 长文档主要提取 Markdown                       | 百度 Unlimited‑OCR                                |
| 需要 MinerU 官方精准解析、VLM/pipeline 模型或自托管解析 | MinerU                                          |
| Agent 临时读取任务中的普通文本 PDF                 | Pdfium：PDF 转 Markdown                           |
| 其他解析服务                                 | Unstructured 等转换器；是否支持坐标预览取决于其是否输出 XpertAI 版式契约 |

接下来可阅读[维护文档](/zh-Hans/ai/knowledge-base/maintain-documents)、[知识流水线编排](/zh-Hans/ai/knowledge-base/create-knowledge-base-via-pipeline/step-2-pipeline-orchestration)和[召回测试](/zh-Hans/ai/knowledge-base/recall-test)。