MinerU 4 原生 PDF 文本解析与 JSON 结果往返验证-未完纪

来源：原文；作者或维护方：OpenDataLab / MinerU team（原页未署个人作者）。中文编译整理与技术核对：未完纪。核对日期：2026-10-05。

编辑自绘技术示意图；用于解释本文流程，不代表运行结果。

对于本身带有文字层的 PDF，很多任务只需要先把文字结构导出，再验证解析结果能否保存和恢复，不必从 OCR 或远端推理服务开始。MinerU 4 的 Python SDK 提供了这样一条短路径：显式选择 flash、指定 ocr_mode="txt"，把需要的 PDF 页解析成共享结果对象，再输出 Markdown 和 JSON。

本文按既定选题范围编译 MinerU 官方 Python SDK 页的本地原生 PDF 示例，只处理文字层及结果往返；不纳入同页后半段自托管 V1 API、Standard 远端解析、批处理服务或模型下载流程。维护方为 OpenDataLab / MinerU team，源页未署个人作者。

版本与输入范围

2026-10-05 核对的公开页面与 mineru-4.0.10-released 标签中的 SDK 文档都包含下文使用的导入方式、参数和结果方法。因此本文讨论的是 MinerU 4 的接口，不能直接套用于旧版 magic_pdf 工作流。

先在隔离的开发环境中准备匹配版本的 MinerU，再选择一份你有权处理、已经知道自带可提取文字层的本地 PDF。本例用 document.pdf 表示该文件，没有替读者下载任何输入，也不假设某个公网报告始终在线。敏感文档应留在符合数据要求的环境中。

mineru.parser 导出无状态的 parse、parse_async、MinerUParser 和共享的 ParseResult。调用这些入口本身并不创建文档库。默认 PDF 页范围是全部页面；page_range="1-3" 使用从 1 开始的页码，表示第 1 至第 3 页。

官方 Tiers and Runtimes 页指出原生文字解析无需推理模型，并且 PDF 的本地 parse() 默认层级是 Standard，因此示例里的 tier="flash" 是有意义的显式选择。Flash 本身也存在处理扫描件的 OCR 路径；本文限定 txt 文字路径，不把 Flash 这个层级名称等同于任何输入都无需模型。

解析、导出与恢复

下面保留官方原例的调用顺序：

from pathlib import Path
from mineru.parser import parse, ParseResult

result = parse("document.pdf", tier="flash", ocr_mode="txt", page_range="1-3")
Path("document.md").write_text(result.markdown(), encoding="utf-8")
Path("document.json").write_text(result.to_json(), encoding="utf-8")
restored = ParseResult.from_json(result.to_json())
assert restored.to_dict() == result.to_dict()

parse() 先解析指定文件的前三页，得到 ParseResult。result.markdown() 给出可阅读的 Markdown 表达；result.to_json() 给出结果对象的 JSON 表达。两次 write_text() 都显式使用 UTF-8，以避免文本编码依赖当前环境。

接着，ParseResult.from_json(...) 根据 JSON 字符串重建结果。最后比较两个对象的 to_dict()，验证这一次序列化和反序列化在字典表示上是否一致。这样可以把“解析成功”和“结果能够恢复”分开理解。

这个断言的证明范围

原例传给 from_json() 的是再次调用 result.to_json() 得到的内存字符串，不是刚写到磁盘的 document.json 文件。因此原例验证的是内存中的结果往返，不能据此宣称文件写入、再次读取或长期存档兼容性已经验证。

即便这个断言通过，也只能说明字典表示相同。它不证明源 PDF 的每个字都被正确提取，不证明阅读顺序、表格、公式或图片完整，不证明不同 MinerU 版本之间的 JSON 都兼容，更不验证 Markdown 导出再导入的往返。Python 在启用优化选项时可以移除 assert；如果要把它作为工作流必须执行的检查，应使用显式条件并抛出异常。

编辑补充：核对实际写出的 JSON 文件

若目标是验证本地落盘后的读取，可以使用下面这个小改版。与原文相比，它创建一个专用输出目录，使用独占写入模式避免覆盖现有同名文件，读取实际 JSON 文件，并把可被优化删除的 assert 改成显式异常。这些是编辑补充，未经本次执行；它们不会让提取质量自动得到保证。

from pathlib import Path
from mineru.parser import parse, ParseResult

input_pdf = Path("document.pdf")
output_dir = Path("native-text-output")
output_dir.mkdir(exist_ok=True)

result = parse(str(input_pdf), tier="flash", ocr_mode="txt", page_range="1-3")
markdown_path = output_dir / "document.md"
json_path = output_dir / "document.json"

# Exclusive creation: fail rather than overwrite an existing output.
with markdown_path.open("x", encoding="utf-8") as handle:
    handle.write(result.markdown())
with json_path.open("x", encoding="utf-8") as handle:
    handle.write(result.to_json())

restored = ParseResult.from_json(json_path.read_text(encoding="utf-8"))
if restored.to_dict() != result.to_dict():
    raise ValueError("ParseResult JSON round-trip differs")

这个改版仍然不是跨文件原子事务：如果第一份文件写入成功、第二份失败，目录中会留下部分输出。再次运行时，独占模式会拒绝覆盖已有文件；应先人工核对本次输出，另选新的输出目录或文件名。生产系统需要自行设计临时文件、提交、失败清理和重试规则，不能把这段演示直接称作可靠批处理系统。

输入与结果的安全边界

本文不处理扫描页，也不承诺缺少文字层时自动回退到 OCR。应先确认文字层可用，再对照抽查原 PDF 与 Markdown；若主要内容是扫描图像、复杂版式或公式，换解析路径是另一项任务。不要用“成功返回 JSON”掩盖输入类型不合适的问题。

源示例没有 API URL、访问密钥或远程请求语句，选择的是本地路径；这不等于对 MinerU 整个依赖树作了网络行为审计。处理不可信 PDF 仍应使用受限目录、资源配额和及时更新的解析依赖。导出的 Markdown、链接和文字也都是源文件内容，接入网页、命令或模型工具时需要按目标环境转义与校验，不能直接当指令执行。

本次仅静态核对页面、固定版本文档、代码片段与许可；没有安装 MinerU、解析 PDF 或执行断言，因此没有任何“测试通过”的运行结论。

保留 MinerU 的附加许可条件

4.0.10 标签的 MinerU Open Source License 以 Apache License 2.0 为基础，并附有额外条件：使用者及关联方按合并口径，月活跃用户超过 1 亿或月总收入超过 2000 万美元时，继续相应用途需取得单独商业许可；基于 MinerU 向第三方提供在线服务，需要在相关界面或公开文档的显著位置标明使用了 MinerU。该许可还列有不满足相关义务时的终止条款。不要把它简写为“无附加条件的 Apache-2.0”。

这里记录的是源版本实际声明，不能代替读取完整许可。本文没有使用任何推理权重，代码许可、权重许可与文章转载授权也不是同一件事。