- 知识入库转换器负责把 PDF 转换为可分块、可索引的 Markdown 和结构化版式数据。其中，百度 PaddleOCR‑VL 可以驱动 PDF 解析联动预览。
- Agent PDF 工具允许数字专家按需把任务中的 PDF 转为 Markdown 和逐页图片，不会自动把结果写入知识库。
百度 OCR 文档转换插件
@xpert-ai/plugin-baidu-ocr 在 XpertAI 中注册一个“百度 OCR”系统集成和两个文档转换器。两者复用平台现有的凭证、文件权限、后台文档任务、分块器和索引流程，不创建独立的知识处理链路。
两个转换器
PDF 双栏联动预览要求转换器输出分页版式和坐标。当前百度 OCR 插件中，PaddleOCR‑VL 满足这一要求；Unlimited‑OCR 只使用稳定的 Markdown 结果，不假设服务返回未公开的 JSON 结构。
支持的输入
插件支持当前百度文档解析接口接受的 PDF、JPG/JPEG、PNG、BMP、TIF/TIFF、OFD、DOC/DOCX、TXT、WPS 和 PPT/PPTX。 本页重点介绍 PDF。其他格式可以进入相同转换流程，但左侧“原文坐标叠加”当前只在原文件为 PDF 时显示。配置百度 OCR 连接
- 由组织管理员安装并启用
@xpert-ai/plugin-baidu-ocr。 - 进入“设置 > 系统集成”，新建“百度 OCR”连接。
- 填写百度智能云 OCR 应用的 API Key 和 Secret Key。
- 选择上传方式、轮询间隔和任务超时时间，保存并验证连接。
上传方式
默认轮询间隔为 7 秒，默认任务超时为 1800 秒。可根据文件大小和服务响应情况调整。
在知识流水线中使用
- 打开知识流水线的“文档转换器”节点。
- 选择“百度 PaddleOCR‑VL”或“百度 Unlimited‑OCR”。
- 选择已经创建的百度 OCR 集成连接。
- 配置转换选项并完成流水线的分块器、嵌入和知识库节点。
- 测试并发布流水线，然后上传或重新处理 PDF。
Unlimited‑OCR 当前提供“保留原始结果”选项，用于保存 Markdown、可用 JSON 和任务响应。
大型 PDF
百度接口当前每个解析任务最多处理 500 页 PDF。对于超过限制、且平台能够读取原始字节的 PDF，插件会：- 按页数和上传大小切分为有界的顺序任务；
- 逐批提交并等待结果；
- 将每批页码重新映射为原 PDF 的全局页码；
- 合并 Markdown、版式块、图片资产和来源映射；
- 保留批次索引、源页范围、任务 ID 和日志 ID，便于排查失败批次。
MinerU 文档转换插件
@xpert-ai/plugin-mineru 将 MinerU 接入 XpertAI 知识流水线，支持 MinerU 官方精准解析 API 和 自托管 mineru-api / mineru-router 两种部署方式。它复用 XpertAI 的系统集成、凭证、工作区文件、后台任务、分块和索引能力。
服务模式
插件没有使用官方 Agent 轻量 API。知识入库需要处理更大的文档并保存结构化产物，因此官方模式使用精准解析 API。
配置 MinerU 连接
- 由组织管理员安装并启用
@xpert-ai/plugin-mineru。 - 进入“设置 > 系统集成”，新建 MinerU 连接。
- 选择“官方 API”或“自托管”。
- 填写服务地址和 Access Token；官方地址不填写时使用默认 v4 地址。
- 官方模式选择文件提交方式，并配置轮询、任务和单次请求超时。
- 保存并验证连接，然后在知识流水线的文档转换节点中选择 MinerU。
官方文件提交方式
官方模式默认轮询间隔为 5 秒，任务超时为 1800 秒，单次请求超时为 1200 秒。Access Token 使用平台凭证机制保存，不会写入任务日志或文档 metadata。
转换选项
官方 PDF 处理流程
在推荐的“自动”方式下，插件会读取 XpertAI 工作区中的 PDF，通过 MinerU 批量接口取得预签名上传 URL，上传文件并轮询解析结果，最后下载完整结果压缩包并写回知识库工作区。 MinerU 官方精准解析 API 当前每个文件限制为 200 页和 200 MB。超过限制的 PDF 会被切分为：- 每个部分最多 200 页；
- 每个部分控制在约 190 MiB；
- 每个官方上传批次最多提交 50 个部分；
- 最终 metadata 保留源页范围、批次 ID、批次序号和总批次数。
/file_parse，因此无需再建立插件私有任务队列。
输出与安全
MinerU 将 Markdown 作为文档转换结果交给现有分块器，并可以归档：content_list.json和稳定的content_list_v2.json；middle.json、layout.json、模型原始输出；- Markdown 引用的图片和其他结果资产；
- 服务类型、模型、后端、批次和源页范围 metadata。
MinerU 当前会保存结构化结果和源页范围，但尚未输出 XpertAI PDF 联动预览所需的分页版式坐标契约，因此不会显示原文坐标框或双栏解析联动。MinerU 处理后的最终 Markdown 和 Chunks 仍可正常入库、检索和管理。后续转换器若输出统一版式契约，即可接入同一套预览框架。
PDF 解析联动预览
使用 PaddleOCR‑VL 完整处理 PDF 后，在文档列表点击“打开解析预览”，或进入文档详情的“解析预览”标签页，即可同时检查原 PDF 和解析结果。双栏界面
- 左侧原文：使用原始 PDF 渲染页面，并将识别坐标或多边形叠加在页面上。
- 右侧解析结果：按页展示 Markdown、结构、表格、图片和 JSON。
- 分栏调节：拖动分隔线调整两侧宽度；也可以用键盘左右键微调。
- 移动端：在“原文”和“解析结果”两个面板之间切换。
版式类型
解析结果统一为与服务商无关的版式类型：点击与滚动联动
- 滚动左侧原文时，右侧会同步到相同页和相近的页内进度；
- 滚动右侧解析结果时，左侧也会反向同步；
- 点击 PDF 上的坐标框，会选中对应解析块并将右侧结果滚动到该块；
- 点击右侧解析块，会高亮左侧对应区域；
- 当前页和选中块写入页面地址参数，刷新或在有权限的会话中打开链接时可以恢复位置。
解析结果视图
与最终知识分块的关系
“解析预览”展示的是文档转换器在文本切分之前识别出的版式块；“Chunks”标签页展示的是经过分块器处理、最终用于索引和召回的知识分块。两者不会被混为同一种数据。 PaddleOCR‑VL 会在合并 Markdown 时生成来源映射。分块器切分后，每个最终分块可以保留：- 起止源页
pageStart/pageEnd； - 单页分块的
page； - 参与该分块的原始版式块 ID；
- 关联图片等资产。
大文档性能
预览不会一次加载整份大型文档：- 首次只读取轻量页面索引；
- 解析页按当前页附近的窗口加载；
- PDF 只渲染当前页前后有限范围；
- JSON 在进入对应标签且滚动到页面时才加载；
- 原始 PDF 支持按字节范围读取。
安全与一致性
- 原始 PDF、解析页和图片资产都使用知识库权限进行访问控制；
- 客户端只获得不透明的资产 ID，不暴露服务端文件路径；
- 解析快照按页保存并进行大小与哈希校验；
- 原文件内容变化或快照完整性校验失败时，旧预览不会继续显示为有效结果；修改转换器配置后需要执行完整重新处理，才能生成对应的新预览；
- PDF 页面比例与识别坐标不兼容时，系统隐藏坐标叠加并显示提示，避免错误标注。
Pdfium：Agent PDF 转 Markdown 工具插件
@xpert-ai/plugin-pdfium 是 Agent 工具插件。启用后，可以为数字专家添加“PDF to Markdown / PDF 转 Markdown”内置工具集，其工具名为 pdf_to_markdown。
Agent 可以从以下任一来源读取 PDF：
- 文件 URL；
- 工作区文件路径；
- Base64、Buffer 或 Uint8Array 文件内容；
- 一个文件对象或文件对象列表。
- 汇总 Markdown，其中按页插入图片和可提取文本；
result.md；page-1.png、page-2.png等逐页图片；- 文件路径、可用时的工作区 URL、MIME 类型和图片页码。
选择建议
接下来可阅读维护文档、知识流水线编排和召回测试。