papermage

⚠️ 本项目是EMNLP 2023的一份研究原型。由于其他项目的优先级较高，我们可能不会定期修复问题或维护该项目。目前，我们在Dolma项目下开发相关的科学PDF解析功能，请关注该仓库即将发布的版本。感谢！

设置

conda create -n papermage python=3.11
conda activate papermage

如果您从源代码安装：

pip install -e '.[dev,predictors,visualizers]'

如果您从PyPI安装：

pip install 'papermage[dev,predictors,visualizers]'

（根据您的命令行shell，可能需要添加或移除引号）。

如果您使用的是MacOSX，还需要运行：

conda install poppler

单元测试

python -m pytest

查看最新失败的测试：

python -m pytest --lf --no-cov -n0

针对特定测试类名：

python -m pytest -k 'TestPDFPlumberParser' --no-cov -n0

快速入门

1. 从PDF首次创建文档

from papermage.recipes import CoreRecipe

recipe = CoreRecipe()
doc = recipe.run("tests/fixtures/papermage.pdf")

2. 理解输出：Document类

什么是Document？至少它包含一些文本，存储在.symbols层中，即一个字符串。例如：

> doc.symbols
"PaperMage: A Unified Toolkit for Processing, Representing, and\nManipulating Visually-..."

但当您有多种不同的方式来分割.symbols时，这个库就显得非常有用。例如，将论文分割成页面，再将每个页面分割成行：

for page in doc.pages:
    print(f'\n=== PAGE: {page.id} ===\n\n')
    for row in page.rows:
        print(row.text)
        
...
=== PAGE: 5 ===

4
Vignette: Building an Attributed QA
System for Scientific Papers
How could researchers leverage papermage for
their research? Here, we walk through a user sce-
nario in which a researcher (Lucy) is prototyping
an attributed QA system for science.
System Design.
Drawing inspiration from Ko
...

这展示了该库的两个优点：

• Document提供了不同层次分割symbols的可迭代对象。选项包括pages、tokens、rows、sentences、sections等。不过，并非每个解析器都会提供所有这些分割。

• 这些分割单元（在我们的库中称为Entity对象）能够感知并访问其他类型的分割。例如，您可以调用page.rows来获取与特定页面相交的所有行。或者调用sent.tokens来获取与特定句子相交的所有标记。又或者调用sent.rows来获取与特定句子相交的行。这些索引是在创建Document时以及每次新增Entity类型时动态构建的。极端情况下，只要文档中存在这些层，您就可以这样写：

for page in doc.pages:
    for sent in page.sentences:
        for row in sent.rows: 
            ...

您可以通过以下方式检查文档中可用的层：

> doc.layers
['tokens',
 'rows',
 'pages',
 'words',
 'sentences',
 'blocks',
 'vila_entities',
 'titles',
 'authors',
 'abstracts',
 'keywords',
 'sections',
 'lists',
 'bibliographies',
 'equations',
 'algorithms',
 'figures',
 'tables',
 'captions',
 'headers',
 'footers',
 'footnotes',
 'symbols',
 'images',
 'metadata',
 'entities',
 'relations']

3. 理解实体之间的交集

请注意，Entity之间并不一定完全嵌套。例如，如果您运行以下代码会怎样：

for sent in doc.sentences:
    for row in sent.rows:
        print([token.text for token in row.tokens])

即使某些标记位于句子之外，它们仍然会被打印出来。这是因为当我们从句子跳转到其行时，我们寻找的是与该句子有任何重叠的所有行。行可能会超出句子的边界，因此其中可能包含句子之外的标记。

使用此库的关键在于理解这些不同层是如何定义的，并预见它们之间可能的交互方式。我们尽量做出直观的设计，但也鼓励用户通过实验来熟悉各个层。

4. Entity中包含什么？

每个Entity对象都存储了关于其内容和位置的信息：

• .spans: List[Span]，Span是指向Document.symbols的指针（即Span(start=0, end=5)对应于symbols[0:5]）。默认情况下，遍历Entity时，您实际上是在遍历它的.spans。

• .boxes: List[Box]，Box表示页面上的矩形区域。每个Span都关联一个Box。

• .metadata: Metadata，这是一个类似字典的自由格式对象，用于存储关于该Entity的额外元数据。通常这些字段是空的。

5. 如何手动创建自己的Document？

Document是通过拼接三种工具创建的：Parsers、Rasterizers和Predictors。

• Parsers以PDF为输入，返回包含.symbols和其他层的Document。我们使用的示例是一个基于PDFPlumber的封装——MIT许可证工具。

• Rasterizers以PDF为输入，为每页生成一张图像，并将其添加到Document.images中。我们使用的示例是PDF2Image——MIT许可证工具。

• Predictors接收一个Document并应用某种操作，计算出一组新的Entity对象，然后将其插入到我们的Document中。这些预测器都是内部开发的，可以是简单的启发式方法，也可以是完整的机器学习模型。

6. 如何保存我的Document？

import json
with open('filename.json', 'w') as f_out:
    json.dump(doc.to_json(), f_out, indent=4)

将会生成类似以下的内容：

{
    "symbols": "PaperMage: A Unified Toolkit for Processing, Representing, an...",
    "entities": {
        "rows": [...],
        "tokens": [...],
        "words": [...],
        "blocks": [...],
        "sentences": [...]
    },
    "metadata": {...}
}

7. 如何加载我的Document？

可以使用以下代码重新构建一个Document：

with open('filename.json') as f_in:
    doc_dict = json.load(f_in)
    doc = Document.from_json(doc_dict)

注意：一种常见的模式是先加载之前保存的文档，然后在其基础上运行一些额外的Predictors，最后保存结果。

有关如何使用您自己的数据训练自定义预测器的更多信息，请参阅papermage/predictors/README.md。

更多使用模式请参考papermage/examples/quick_start_demo.ipynb笔记本。

PaperMage 快速上手指南

PaperMage 是一个用于处理、表示和操作科学论文视觉结构的统一工具包。它能够将 PDF 解析为包含多层级语义（如页面、行、句子、公式等）的结构化文档对象。

注意：本项目目前是 EMNLP 2023 的研究原型，维护频率较低。相关的科学 PDF 解析功能正在 Dolma 项目中开发，建议关注该项目的后续发布。

环境准备

系统要求

• 操作系统：Linux, macOS, Windows
• Python 版本：推荐 Python 3.11
• macOS 用户特别依赖：需要安装 poppler 库以支持 PDF 渲染。

前置依赖

在开始安装前，请确保已安装 conda (推荐) 或具备相应的 Python 环境。

macOS 用户必做：

conda install poppler

安装步骤

推荐使用 conda 创建独立虚拟环境以避免依赖冲突。

1. 创建并激活环境

conda create -n papermage python=3.11
conda activate papermage

2. 安装 PaperMage

方式 A：从源码安装（推荐开发者使用） 克隆仓库后，在项目根目录运行：

pip install -e '.[dev,predictors,visualizers]'

方式 B：从 PyPI 安装

pip install 'papermage[dev,predictors,visualizers]'

(注：根据命令行外壳不同，可能需要调整引号的使用)

国内加速提示：如遇下载缓慢，可添加清华或阿里镜像源： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 'papermage[dev,predictors,visualizers]'

基本使用

1. 解析 PDF 生成文档

使用内置的 CoreRecipe 即可快速将 PDF 转换为 Document 对象。

from papermage.recipes import CoreRecipe

# 初始化配方
recipe = CoreRecipe()

# 运行解析，输入为 PDF 文件路径
doc = recipe.run("tests/fixtures/papermage.pdf")

2. 访问文档内容

Document 对象的核心是 .symbols（纯文本），但其强大之处在于提供了多种层级切片（Layers），如 pages, rows, sentences, tokens 等。

查看原始文本：

print(doc.symbols)

按层级遍历（例如：按页 -> 按行）：

for page in doc.pages:
    print(f'\n=== PAGE: {page.id} ===\n')
    for row in page.rows:
        print(row.text)

查看可用的所有层级：

print(doc.layers)
# 输出示例：['tokens', 'rows', 'pages', 'sentences', 'figures', 'tables', ...]

3. 理解实体（Entity）与交叉引用

PaperMage 中的每个片段（如句子、行）都是一个 Entity 对象。它们之间不是严格的嵌套关系，而是基于空间重叠的动态关联。

你可以轻松跨越层级查询，例如获取某个句子所涉及的所有行：

for sent in doc.sentences:
    # 获取与该句子有重叠的所有行
    for row in sent.rows: 
        print([token.text for token in row.tokens])

4. 保存与加载文档

解析后的文档可以序列化为 JSON 以便后续使用或增量处理。

保存文档：

import json

with open('output_doc.json', 'w') as f_out:
    json.dump(doc.to_json(), f_out, indent=4)

加载文档：

from papermage import Document
import json

with open('output_doc.json') as f_in:
    doc_dict = json.load(f_in)
    doc = Document.from_json(doc_dict)