spaCy Layout：使用 spaCy 处理 PDF、Word 文档等

此插件与 Docling 集成，可将 PDF、Word 文档 等多种输入格式的结构化处理引入您的 spaCy 流程中。它以文本格式输出干净的 结构化数据，并创建 spaCy 熟悉的 Doc 对象，使您能够访问诸如章节或标题等带标签的文本片段，以及已将数据转换为 pandas.DataFrame 的表格。

此工作流让您轻松地将强大的 NLP 技术 应用于文档，包括语言学分析、命名实体识别、文本分类等。它也非常适合用于实现 RAG 流水线中的分块操作。

📖 博客文章：“从 PDF 到 AI 就绪的结构化数据：深度解析”
—— 一种新的模块化工作流，用于将 PDF 及类似文档转换为结构化数据，其中包含 spacy-layout 和 Docling。

📝 使用方法

⚠️ 本包需要 Python 3.10 或更高版本。

pip install spacy-layout

在使用 nlp 对象初始化 spaCyLayout 预处理器进行分词后，您可以调用它来处理文档路径，将其转换为结构化数据。生成的 Doc 对象包含布局跨度，这些跨度映射到原始文本，并暴露各种属性，包括内容类型和布局特征。

import spacy
from spacy_layout import spaCyLayout

nlp = spacy.blank("en")
layout = spaCyLayout(nlp)

# 处理文档并创建 spaCy Doc 对象
doc = layout("./starcraft.pdf")

# 文档的文本内容
print(doc.text)
# 文档布局，包括页数和页面尺寸
print(doc._.layout)
# 文档中的表格及其提取的数据
print(doc._.tables)
# 文档的 Markdown 表示
print(doc._.markdown)

# 不同部分的布局跨度
for span in doc.spans["layout"]:
    # 文档部分及文本中的标记和字符偏移量
    print(span.text, span.start, span.end, span.start_char, span.end_char)
    # 部分类型，例如 "text"、"title"、"section_header" 等
    print(span.label_)
    # 部分的布局特征，包括边界框
    print(span._.layout)
    # 距离该跨度最近的标题（准确性取决于文档结构）
    print(span._.heading)

如果您需要大规模处理大量文档，可以使用 spaCyLayout.pipe 方法，该方法接受路径或字节的可迭代对象，并生成 Doc 对象：

paths = ["one.pdf", "two.pdf", "three.pdf", ...]
for doc in layout.pipe(paths):
    print(doc._.layout)

spaCy 还允许您对已创建的 Doc 调用 nlp 对象，因此您可以轻松应用组件流水线来进行 语言学分析 或 命名实体识别，使用 基于规则的匹配 或 spaCy 支持的任何其他功能。

# 加载基于 Transformer 的英语流水线
# 安装：python -m spacy download en_core_web_trf
nlp = spacy.load("en_core_web_trf")
layout = spaCyLayout(nlp)

doc = layout("./starcraft.pdf")
# 应用流水线以获取词性标注、依存关系、实体等
doc = nlp(doc)

表格和表格数据

表格在布局跨度中以 "table" 标签出现，并可通过快捷方式 Doc._.tables 访问。它们会暴露一个 layout 扩展属性，以及一个包含表格数据并已转换为 pandas.DataFrame 的 data 属性。

for table in doc._.tables:
    # 标记位置和边界框
    print(table.start, table.end, table._.layout)
    # 内容的 pandas.DataFrame
    print(table._.data)

默认情况下，跨度文本是一个占位符 TABLE，但您可以自定义表格的呈现方式，只需向 spaCyLayout 提供一个 display_table 回调函数，该函数接收数据的 pandas.DataFrame。这使您能够在文档文本中包含表格信息，并在后续过程中使用这些信息，例如在使用训练好的命名实体识别器或文本分类器进行信息提取时。

def display_table(df: pd.DataFrame) -> str:
    return f"表格包含以下列：{', '.join(df.columns.tolist())}"

layout = spaCyLayout(nlp, display_table=display_table)

序列化

处理完文档后，您可以将结构化的 Doc 对象以 spaCy 高效的二进制格式进行 序列化，这样就不必再次执行资源密集型的转换过程。

from spacy.tokens import DocBin

docs = layout.pipe(["one.pdf", "two.pdf", "three.pdf"])
doc_bin = DocBin(docs=docs, store_user_data=True)
doc_bin.to_disk("./file.spacy")

⚠️ 关于带有扩展属性的反序列化说明： 自定义扩展属性，如 Doc._.layout，目前是在初始化 spaCyLayout 时注册的。因此，如果您从二进制文件中加载包含布局信息的 Doc 对象，就需要重新初始化 spaCyLayout 以便重新填充这些自定义属性。我们计划在未来的版本中对此进行优化。

+ layout = spacyLayout(nlp)
doc_bin = DocBin(store_user_data=True).from_disk("./file.spacy")
docs = list(doc_bin.get_docs(nlp.vocab))

🎛️ API

数据和扩展属性

layout = spaCyLayout(nlp)
doc = layout("./starcraft.pdf")
print(doc._.layout)
for span in doc.spans["layout"]:
    print(span.label_, span._.layout)

属性	类型	描述
Doc._.layout	DocLayout	文档的布局特征。
Doc._.pages	list[tuple[PageLayout, list[Span]]]	文档中的页面及其包含的跨度。
Doc._.tables	list[Span]	文档中的所有表格。
Doc._.markdown	str	文档的 Markdown 表示形式。
Doc.spans["layout"]	spacy.tokens.SpanGroup	文档中的布局跨度。
Span.label_	str	提取的布局跨度的类型，例如 "text" 或 "section_header"。选项请参见 这里。
Span.label	int	跨度标签的整数 ID。
Span.id	int	布局跨度的连续索引。
Span._.layout	SpanLayout | None	布局跨度的布局特征。
Span._.heading	Span | None	如果存在，距离跨度最近的标题。
Span._.data	pandas.DataFrame | None	表格跨度提取的数据。

dataclass PageLayout

属性	类型	描述
page_no	int	页码（从 1 开始）。
width	float	页面宽度，单位为像素。
height	float	页面高度，单位为像素。

dataclass DocLayout

属性	类型	描述
pages	list[PageLayout]	文档中的页面。

dataclass SpanLayout

属性	类型	描述
x	float	包围框的水平偏移量，单位为像素。
y	float	包围框的垂直偏移量，单位为像素。
width	float	包围框的宽度，单位为像素。
height	float	包围框的高度，单位为像素。
page_no	int	跨度所在的页码。

class spaCyLayout

method spaCyLayout.__init__

初始化文档处理器。

nlp = spacy.blank("en")
layout = spaCyLayout(nlp)

参数	类型	描述
nlp	spacy.language.Language	用于分词的已初始化 nlp 对象。
separator	str	用于在创建的 Doc 对象中分隔各部分的标记。该分隔符不会包含在布局跨度中。如果为 None，则不添加分隔符。默认值为 "\n\n"。
attrs	dict[str, str]	覆盖自定义 spaCy 属性。可包括 "doc_layout"、"doc_pages"、"doc_tables"、"doc_markdown"、"span_layout"、"span_data"、"span_heading" 和 "span_group"。
headings	list[str]	用于检测 Span._.heading 的标题标签。默认值为 ["section_header", "page_header", "title"]。
display_table	Callable[[pandas.DataFrame], str] | str	用于生成表格在 Doc.text 中的文本表示或占位符文本的函数。默认值为 "TABLE"。
docling_options	dict[InputFormat, FormatOption]	传递给 Docling 的 DocumentConverter 的 格式选项。
返回值	spaCyLayout	初始化后的对象。

method spaCyLayout.__call__

处理文档并创建一个包含文本内容和布局跨度的 spaCy Doc 对象，默认可通过 Doc.spans["layout"] 访问。

layout = spaCyLayout(nlp)
doc = layout("./starcraft.pdf")

参数	类型	描述
source	str | Path | bytes | DoclingDocument	要处理的文档路径、字节数据或已创建的 DoclingDocument。
返回值	Doc	处理后的 spaCy Doc 对象。

method spaCyLayout.pipe

处理多个文档并创建 spaCy Doc 对象。如果您需要大规模处理大量文档，建议使用此方法。as_tuples 的行为与 spaCy 的 Language.pipe 相同。

layout = spaCyLayout(nlp)
paths = ["one.pdf", "two.pdf", "three.pdf", ...]
docs = layout.pipe(paths)

sources = [("one.pdf", {"id": 1}), ("two.pdf", {"id": 2})]
for doc, context in layout.pipe(sources, as_tuples=True):
    ...

参数	类型	描述
sources	Iterable[str | Path | bytes] | Iterable[tuple[str | Path | bytes, Any]]	要处理的文档路径或字节数据，或者当 as_tuples 设置为 True 时的 (source, context) 元组。
as_tuples	bool	如果设置为 True，输入应为 (source, context) 元组的可迭代对象。输出将是 (doc, context) 元组序列。默认值为 False。
产出	Doc | tuple[Doc, Any]	处理后的 spaCy Doc 对象，或当 as_tuples 设置为 True 时的 (doc, context) 元组。

💡 示例和代码片段

本节包含更多关于如何使用 spacy-layout 的示例。如果您有合适的示例，欢迎提交 pull request！

使用 matplotlib 可视化页面及边界框

import pypdfium2 as pdfium
import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle
import spacy
from spacy_layout import spaCyLayout

DOCUMENT_PATH = "./document.pdf"

# 加载 PDF 并将其转换为图像
pdf = pdfium.PdfDocument(DOCUMENT_PATH)
page_image = pdf[2].render(scale=1)  # 获取第 3 页（索引为 2）
numpy_array = page_image.to_numpy()
# 使用 spaCy 处理文档
nlp = spacy.blank("en")
layout = spaCyLayout(nlp)
doc = layout(DOCUMENT_PATH)

# 获取第 3 页的布局和各部分
page = doc._.pages[2]
page_layout = doc._.layout.pages[2]
# 创建图形和坐标轴，并设置页面尺寸
fig, ax = plt.subplots(figsize=(12, 16))
# 显示 PDF 图像
ax.imshow(numpy_array)
# 为每个部分的边界框添加矩形
for section in page[1]:
    # 创建矩形补丁
    rect = Rectangle(
        (section._.layout.x, section._.layout.y),
        section._.layout.width,
        section._.layout.height,
        fill=False,
        color="blue",
        linewidth=1,
        alpha=0.5
    )
    ax.add_patch(rect)
    # 在框顶部添加文本标签
    ax.text(
        section._.layout.x,
        section._.layout.y,
        section.label_,
        fontsize=8,
        color="red",
        verticalalignment="bottom"
    )

ax.axis("off")  # 隐藏坐标轴
plt.show()

spaCy Layout 快速上手指南

spaCy Layout 是一个强大的 spaCy 插件，集成了 Docling，能够将 PDF、Word 文档等非结构化文件转换为带有布局信息的结构化数据。它生成标准的 spaCy Doc 对象，支持提取章节、标题、表格（自动转为 pandas DataFrame）等元素，非常适合用于 RAG 管道构建、文档信息抽取及语言学分析。

环境准备

在开始之前，请确保满足以下系统要求：

• Python 版本：必须为 Python 3.10 或更高版本。
• 前置依赖：需已安装 spacy。
• 推荐镜像：国内开发者建议使用清华源或阿里源加速安装。

安装步骤

使用 pip 进行安装。如需加速，可指定国内镜像源：

pip install spacy-layout -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：该包会自动处理与 Docling 的集成，无需单独安装 Docling 核心库。

基本使用

以下是处理单个 PDF 文档并提取结构化信息的最简示例。

1. 初始化与处理文档

首先创建一个空白的 spaCy nlp 对象，初始化 spaCyLayout，然后直接调用它处理文件路径。

import spacy
from spacy_layout import spaCyLayout

# 初始化空白英语模型（仅用于分词基础架构）
nlp = spacy.blank("en")

# 初始化布局处理器
layout = spaCyLayout(nlp)

# 处理文档（支持 .pdf, .docx 等），返回 spaCy Doc 对象
doc = layout("./starcraft.pdf")

# 查看纯文本内容
print(doc.text)

# 查看文档布局信息（页数、尺寸等）
print(doc._.layout)

# 查看提取的表格数据 (pandas.DataFrame)
print(doc._.tables)

# 获取文档的 Markdown 表示
print(doc._.markdown)

2. 遍历布局片段 (Spans)

doc.spans["layout"] 包含了所有识别出的布局元素（如标题、段落、表格占位符）。你可以访问其类型标签、位置坐标及关联的标题。

for span in doc.spans["layout"]:
    # 输出：文本内容, 起始/结束 token 索引, 起始/结束字符索引
    print(span.text, span.start, span.end, span.start_char, span.end_char)
    
    # 输出：片段类型 (例如: "text", "title", "section_header", "table")
    print(span.label_)
    
    # 输出：布局特征（包含边界框坐标 x, y, width, height 及页码）
    print(span._.layout)
    
    # 输出：距离该片段最近的标题（若存在）
    print(span._.heading)

3. 结合 NLP 流水线

生成的 Doc 对象完全兼容 spaCy 的标准流水线。你可以加载预训练模型（如实体识别、依存句法分析）进一步处理文档内容。

# 加载预训练模型 (需先运行: python -m spacy download en_core_web_trf)
nlp = spacy.load("en_core_web_trf")

# 重新初始化 layout 处理器（使用带能力的 nlp 对象）
layout = spaCyLayout(nlp)

# 处理文档
doc = layout("./starcraft.pdf")

# 应用 NLP 流水线：添加词性标注、实体识别等信息
doc = nlp(doc)

# 现在可以正常使用 spaCy 功能，例如提取实体
for ent in doc.ents:
    print(ent.text, ent.label_)

4. 批量处理

处理大量文档时，推荐使用 .pipe() 方法以提高效率：

paths = ["doc1.pdf", "doc2.pdf", "doc3.pdf"]

for doc in layout.pipe(paths):
    # 处理每个文档的布局信息
    print(f"Processed {len(doc._.pages)} pages")