The project's README from github.com/crunz-ai/nativePDF-structurer. As one markdown file: README.md.
简体中文 | English
一个面向大体量数字原生 PDF 的、零 OCR、零模型依赖的文档结构化工具。
项目主要服务于厂商发布的技术文档,例如设备操作手册、维修手册、安装说明、 产品选型手册、电气手册和技术目录。这类 PDF 往往包含数十至数百页内容,并 反复出现页眉页尾、参数表、步骤编号、设备插图、矢量标注和图文混排区域; NativePDF Structurer 的处理策略主要围绕这些结构设计。
学术论文可以作为普通数字原生 PDF 处理,但不是当前版本的主要优化场景。 项目不把复杂公式准确还原为 LaTeX 作为目标。默认公式以页面渲染图保留;可选的 LaTeX 通道只依据原生文字层,对结构明确的简单公式进行保守尝试,结果不保证可靠, 不能替代专业公式识别工具。项目也没有针对论文中的引用关系、双栏论文模板和语义 章节分类进行专项建模。对于页数较少的论文(少于20页),尤其需要公式恢复、OCR、图表理解或 图片语义识别时,更推荐直接使用 MinerU 等具备模型或 VLM 解析路径的 成熟工具。
项目关注“长文档能否稳定进入 RAG 流程”,不局限于追求单页 PDF 到 Markdown 的表面转换。典型输入通常具备以下特征:
本项目的设计目标,是在不依赖图片语义识别和 VLM 推理的前提下,针对复杂的 数字原生 PDF 完成尽可能充分的结构还原,并在厂商手册、技术目录等目标场景中, 使最终输出的可用性接近 MinerU 这类完整文档解析工具。这里描述的是项目方向, 不是已经完成统一数据集精度对标的结论;两类工具依赖条件和优势场景并不相同。
项目不使用 OCR 或视觉语言模型补猜页面语义,而是利用 PDF 已有的文字层、 字体、坐标、图片对象和矢量路径建立可审计的结构化结果。因此,它最适合文字层 和绘图对象保存完整的数字原生厂商 PDF。
NativePDF Structurer 可以独立使用,也可以作为后续 RAG 或多模态流水线的结构化 输入层。不要求理解图片语义时,项目输出的 Markdown、图片、表格及可选 IR 本身就可以作为最终产物。项目可以识别图片、矢量图、表格及其空间关系,并保留 图内原生文字,但不会判断设备图片表达的语义,也不会生成图片描述、故障解释或 操作含义。
如果后续任务需要理解图片内容,可以将视觉区域 PNG、表格、Markdown、IR 和 provenance 继续交给 VLM 处理。这样先由确定性的 PDF 图元分析完成切分、排序和 来源定位,再只对确有需要的视觉区域调用模型。
项目除输出 Markdown 外,还包括:
两种使用方式:
数字原生 PDF
-> NativePDF Structurer(结构恢复、资源切分、阅读顺序、来源定位)
-> Markdown + 图片/表格 + IR + provenance
├─ 直接作为最终文档或 RAG 输入(不需要图片释义)
└─ 可选 VLM(图片语义描述、图表理解或多模态索引)
-> 语义增强后的 RAG 入库与检索
项目使用 PyMuPDF 的原生文字、字体、图片、矢量路径和坐标信息,重建页面的 阅读顺序、章节层级、表格和视觉区域。项目不依赖 OCR、GPU、Poppler、 Ghostscript 或外部文档服务。
项目的模块边界、页面阶段契约、Claim 所有权模型和扩展流程见
docs/architecture.md。
PageRunContext:隔离单页可变状态和文档级配置;以下图片直接取自三份厂商 PDF 的前 60 页回归结果,未经过 OCR 或模型二次 修复。README 只保留少量转换产物,用于说明输出形态;相关原始内容、图形和 商标归对应权利人所有。
维修手册中的设备图可能同时包含位图、矢量轮廓、引线、警告符号、小型参数框 和图内文字。项目将彼此连接的对象保留为一个视觉区域,避免在 Markdown 中被 拆成顺序错乱的多张小图。
产品选型手册中,规则表格和相邻的尺寸矢量图会分别进入表格通道与视觉区域 通道。表格可以同时输出用于阅读的 PNG 和用于后续处理的 CSV,尺寸图则保留 原始版面关系。
|
|
| 参数表:PNG + CSV | 尺寸图:视觉区域 PNG |
操作手册常用编号引线解释设备接口,再由下一张表逐项说明编号含义。项目会 保留编号图的整体几何关系,并让说明表紧随其后输出,便于阅读和后续 RAG 分块。
对于这类内容,Markdown 通常保留视觉结果、原生图内文字和表格数据入口:

> **图内文字(PDF原生文本)**
> X100
> X101 IN
### Table 1 (20 × 2)

[CSV data](tables/page_017_table_01_rotated_+0.csv)
| 组件 | 验证版本 | 用途 |
|---|---|---|
| PyMuPDF | 1.28.0 | PDF 文字、图片、绘图、表格和渲染 |
| NumPy | 2.5.1 | 掩码和几何数组 |
| OpenCV headless | 5.0.0.93 | 形态学处理和连通域 |
| Pillow | 12.3.0 | 图片输出和调试覆盖层 |
[!CAUTION] OpenCV 只应安装
opencv-python-headless。不要同时安装其他提供cv2模块的 OpenCV 发行包,否则可能发生模块覆盖或二进制依赖冲突。
下载或克隆源码后,进入项目根目录:
cd nativePDF-structurer
conda env create -f environment.yml
conda activate nativePDF-structurer
python -m nativePDF_structurer --help
建议在新的虚拟环境中安装:
python -m venv .venv
source .venv/bin/activate # macOS / Linux
# .venv\Scripts\Activate.ps1 # Windows PowerShell
python -m pip install .
nativePDF-structurer --help
参与开发时使用 editable install,并复现项目验证过的依赖版本:
python -m pip install -r requirements.txt
python -m pip install -e . --no-deps
python -c "import nativePDF_structurer; print(nativePDF_structurer.__version__)"
python -m nativePDF_structurer --help
nativePDF-structurer --help
以上命令应输出版本号 0.1.0,并通过模块入口和命令行入口显示帮助信息。
python -m unittest discover -s tests -v
PyMuPDF 具有独立的 AGPL / 商业授权条款。重新分发包含本项目的应用前,请单独 确认 PyMuPDF 和项目内第三方组件的许可证要求。
python -m nativePDF_structurer input.pdf -o output/
默认只生成主 Markdown 及其引用的图片和 CSV。页码使用从 1 开始的编号:
python -m nativePDF_structurer input.pdf \
-o output-debug/ \
--pages 1-60 \
--debug-output
常用选项:
--pages SPEC 选择页码,例如 1-20,24,28
--debug-output 输出 IR、JSON、报告和调试图
--heading-detection / --no-heading-detection
--font-heading-inference / --no-font-heading-inference
--table-header-detection / --no-table-header-detection
--keep-header-text / --no-keep-header-text
--formula-detection / --no-formula-detection
--formula-output MODE 公式输出:image(默认)、latex 或 hybrid
--pdf-outline-heading-assignment / --no-pdf-outline-heading-assignment
--force-pure-text-table-to-markdown / --no-force-pure-text-table-to-markdown
公式默认渲染为 PNG,以避免复杂上下标、分式和混合字体公式被错误改写。
使用 --formula-output latex 或 --formula-output hybrid 时,程序只对
能够由原生文字层明确线性化的简单公式尝试输出 Markdown 数学块;复杂或有歧义的
公式自动回退为 PNG,因此该通道不承诺数学语义和排版完全正确。生成的 $$ ... $$
需要由下游 Markdown 阅读器提供 MathJax 或 KaTeX 渲染,项目本身不额外引入
LaTeX 编译器或 Python 数学包。
最简模式通常包含:
output/
├── document_with_reflowed_text_and_tables.md
├── source_images/
├── visual_regions/
├── tables/
└── formula_images/ # 开启公式处理时创建
调试模式额外包含:
document_ir.json;from pathlib import Path
from nativePDF_structurer import RunConfig, run
config = RunConfig(
source_pdf=Path("input.pdf"),
output_dir=Path("output"),
pages=(1, 2, 3),
debug_output=False,
)
result = run(config)
print(result.summary)
适合数字原生 PDF:PDF 中需要存在可读取的文字层、图片对象或矢量路径。
不保证直接解决以下情况:
项目提供通用的输出 manifest 工具,用于比较文件路径、大小和 SHA-256:
python -m nativePDF_structurer.regression_manifest create \
output manifest.json
python -m nativePDF_structurer.regression_manifest verify \
output manifest.json
除明确注明的第三方内容外,本项目原创代码采用 Apache License 2.0 授权。该许可证允许使用、修改和再分发,并提供 明确的专利授权条款。
许可证边界需要特别注意:
docs/assets/examples/ 中的厂商文档示例图片不属于 Apache-2.0 再授权范围。完整说明见 THIRD_PARTY_NOTICES.md。本项目采用 Apache-2.0 不代表 PyMuPDF 或其他第三方组件的许可证义务被解除。
本项目的阅读顺序处理受
GapTree Sort Algorithm
启发,并以 hiroi-sora 开源的 GapTree 实现为基础,结合本项目对 PDF 文字、
表格、图片和矢量区域的统一排序需求进行了扩展。感谢作者公开这一清晰而实用的
版面排序思路与实现。第三方代码的 MIT 许可证保留在
nativePDF_structurer/_vendor/GapTree_LICENSE.txt。