API#

PyMuPDF4LLM API#

property version#

打印库的版本。

to_markdown(doc: pymupdf.Document | str, *, pages: list | range | None = None, hdr_info: Any = None, write_images: bool = False, embed_images: bool = False, ignore_images: bool = False, ignore_graphics: bool = False, dpi: int = 150, filename=None, image_path='', image_format='png', image_size_limit=0.05, force_text=True, margins=0, page_chunks: bool = False, page_width: float = 612, page_height: float = None, table_strategy='lines_strict', graphics_limit: int = None, ignore_code: bool = False, extract_words: bool = False, show_progress: bool = False, use_glyphs=False) → str | list[dict]#

读取文件的页面，并以 Markdown 格式输出其页面文本。具体实现方式可以通过多种参数来影响。请注意，支持从 Markdown 文本构建页面块。

参数：

  • doc (Document,str) – 文件，可指定为文件路径字符串，或指定为 PyMuPDF 文档（通过 pymupdf.open 创建）。为了使用 pathlib.Path 规范、Python 类文件对象、内存中文档等，您必须使用 PyMuPDF 文档。

  • pages (list) – 可选，指定用于输出的页面（注意：指定从 0 开始的页码）。如果省略，则处理所有页面。

  • hdr_info – 可选。如果您想提供自己的标题检测逻辑，请使用此参数。它可以是一个可调用对象，或一个具有名为 get_header_id 方法的对象。它必须接受一个文本跨度（extractDICT() 中包含的跨度字典）和一个关键字参数“page”（即所属的 Page 对象）。它必须返回空字符串“”或最多 6 个“#”字符后跟一个空格。如果省略，将执行完整的文档扫描以查找最流行的字体大小，并根据它们派生标题级别。要完全避免此行为，请指定 hdr_info=lambda s, page=None: "" 或 hdr_info=False。

  • write_images (bool) – 遇到图像或矢量图形时，将从相应的页面区域创建图像并存储在指定文件夹中。将生成指向这些图像的 Markdown 引用。这些区域中包含的任何文本都不会包含在文本输出中（但会作为图像的一部分出现）。因此，如果您的文档包含写在整页图像上的文本，请确保将此参数设置为 False。

  • embed_images (bool) – 与 write_images 类似，但图像将作为 base64 编码的字符串包含在 markdown 文本中。如果使用，将忽略 write_images 和 image_path。这可能会极大地增加您的 markdown 文本大小。

  • ignore_images (bool) –（v.0.0.20 新增）忽略页面上的图像。当页面非常拥挤（通常是表示演示幻灯片的文档的情况）时，这有助于正确检测文本。也加快了处理时间。

  • ignore_graphics (bool) –（v.0.0.20 新增）忽略页面上的矢量图形。当页面非常拥挤（通常是表示演示幻灯片的文档的情况）时，这有助于正确检测文本。也加快了处理时间。矢量图形仍用于表格检测。

  • image_size_limit (float) – 这必须是一个小于 1 的正值。如果 width / page.rect.width <= image_size_limit 或 height / page.rect.height <= image_size_limit，则忽略图像。例如，默认值 0.05 意味着要考虑包含图像，其宽度和高度必须分别大于页面宽度和高度的 5%。

  • dpi (int) – 指定所需图像分辨率（每英寸点数）。仅当 write_images=True 时相关。默认值为 150。

  • image_path (str) – 将图像存储在此文件夹中。当 write_images=True 时相关。默认值为脚本目录的路径。

  • image_format (str) – 通过其扩展名指定所需的图像格式。默认值为“png”（便携式网络图形）。另一个流行的格式可能是“jpg”。可能的值包括所有支持的输出格式。

  • force_text (bool) – 即使图像/图形重叠，也生成文本输出。此文本将出现在相应图像之后。如果 write_images=True，此参数可以设置为 False 以抑制图像上文本的重复。

  • margins (float,list) –

    一个浮点数或包含 2 或 4 个浮点数的序列，用于指定页面边界。只有在边界内的对象才会被考虑进行输出。

    • margin=f 对应 (f, f, f, f)，表示 (左, 上, 右, 下)。

    • (top, bottom) 对应 (0, 上, 0, 下)。

    • 要始终读取整页（默认），请使用 margins=0。

  • page_chunks (bool) –

    如果 True，输出将是 Document.page_count 个字典的列表（每页一个）。每个字典具有以下结构：

    • “metadata” - 一个字典，包含文档的元数据 Document.metadata，并增加了附加键 “file_path”（文件名）、“page_count”（文档页数）和 “page_number”（基于 1 的页码）。

    • “toc_items” - 指向此页面的目录项列表。此列表中的每个项的格式为 [lvl, title, pagenumber]，其中 lvl 是层级，title 是字符串，pagenumber 是基于 1 的页码。

    • “tables” - 此页面上的表格列表。每个项是一个字典，包含键“bbox”、“row_count”和“col_count”。键“bbox”是一个以元组格式表示的表格在页面上的位置的 pymupdf.Rect。

    • “images” - 页面上的图像列表。这是页面方法 Page.get_image_info() 的副本。

    • “graphics” - 页面上的矢量图形矩形列表。这是由方法 Page.cluster_drawings() 提供的聚类矢量图形的边界框列表。

    • “text” - 页面内容，以 Markdown 文本表示。

    • “words” - 如果使用了 extract_words=True。这是由 page.get_text("words") 提供的元组列表 (x0, y0, x1, y1, "wordstring", bno, lno, wno)。然而，这些元组的顺序与 markdown 文本字符串中生成的顺序相同，因此遵循多列文本。对于表格中的文本也是如此：单词按照表格行单元格的顺序提取。

  • filename (str) –（v.0.0.19 新增）覆盖或设置写入图像所需的文件名。当文档作为内存对象提供时（该对象没有固有文件名），此参数很有用。

  • page_width (float) – 指定所需的页面宽度。对于具有固定页面宽度的文档（如 PDF、XPS 等），此参数将被忽略。然而，可重排的文档，如电子书、office [2] 或文本文件，没有固定的页面尺寸，默认假定具有 Letter 格式宽度 (612) 和“无限”页面高度。这意味着整个文档被视为一个大页面。

  • page_height (float) – 指定所需的页面高度。相关性请参阅 page_width 参数。如果使用默认值 None，文档将显示为一个宽度为 page_width 的大页面。因此在这种情况下，不会出现 markdown 分页符（最后一个除外），或者只会返回一个页面块。

  • table_strategy (str) – 表格检测策略。默认值为 "lines_strict"，它忽略背景颜色。在某些情况下，其他策略可能更成功，例如 "lines"，它使用所有矢量图形对象进行检测。v0.0.19 更改：值为 None 时，将完全不执行任何表格检测。当您知道文档不包含表格时，这可能很有用。可以显著节省执行时间。

  • graphics_limit (int) – 使用此参数限制处理过多的矢量图形元素。科技文档或通过图形命令模拟文本的页面可能包含数万个此类对象。由于矢量图形用于多种目的的分析，运行时可能会迅速变得无法忍受。使用此参数，如果矢量图形数量超出阈值，将忽略所有矢量图形。v0.0.19 更改：页面仍将被处理，并且应提取文本、表格和图像。

  • ignore_code (bool) – 如果 True，则等宽文本不接收特殊格式。将不再生成代码块。如果使用了 extract_words=True，此值将设置为 True。

  • extract_words (bool) – 值为 True 将强制 page_chunks=True，并为每个页面字典添加键“words”。其值是 PyMuPDF 的 Page 方法 get_text("words") 提供的单词列表。此列表中单词的顺序与提取的文本相同。

  • show_progress (bool) –

    默认值为 False。值为 True 时，将在页面转换为 Markdown 时显示文本进度条。它看起来类似于以下内容：

    正在处理 input.pdf… [==================== ] (148/291)

  • use_glyphs (bool) –（v.0.0.19 新增）默认值为 False。值为 True 时，将使用字符的字形编号而不是字符本身。

返回值：

一个包含所有选定文档页面组合文本的字符串，或一个字典列表。

LlamaMarkdownReader(*args, **kwargs)#

使用 LlamaIndex 包创建一个 pdf_markdown_reader.PDFMarkdownReader。请注意，安装 pymupdf4llm 时，不会自动安装此包。

有关可能参数的详细信息，请参阅 LlamaIndex 文档 [1]。

抛出异常：

NotImplementedError：请安装所需的 LlamaIndex 包。

返回值：

一个 pdf_markdown_reader.PDFMarkdownReader 并显示消息“Successfully imported LlamaIndex”。请注意，此方法需要几秒钟才能执行。有关使用 markdown 阅读器的详细信息，请参见下文。

class IdentifyHeaders#
__init__(self, doc: pymupdf.Document | str, *, pages: list | range | None = None, body_limit: float = 11, max_levels: int = 6)#

创建一个对象，该对象将文本字体大小映射到 Markdown 语法中用于指示标题级别的相应“#”字符数。该对象通过扫描文档以查找字体大小的“流行度”来创建。最流行的字体大小和所有较小的尺寸用于正文。较大的字体大小映射到相应的标题级别 - 对应于 HTML 标签 <h1> 到 <h6>。

所有字体大小都将四舍五入为整数值。

如果需要超过 6 个标题级别，则小于 <h6> 字体大小的最大数字将用于正文。

请注意，创建对象会读取和检查整个文档的文本 - 与随后在 to_markdown() 方法中再次读取文档无关。如果您不覆盖其 hdr_info=None 参数，则 to_markdown() 方法默认会创建此对象。

参数：

  • doc (Document,str) – 文件，可指定为文件路径字符串，或指定为 PyMuPDF 文档（通过 pymupdf.open 创建）。为了使用 pathlib.Path 规范、Python 类文件对象、内存中文档等，您必须使用 PyMuPDF 文档。

  • pages (list) – 可选，指定要考虑的页面。如果省略，则处理所有页面。

  • body_limit (float) – 正文文本的默认字体大小限制。仅当文档扫描未提供有效信息时使用。

  • max_levels (int) – 要使用的最大标题级别数。有效值在 range(1, 7) 中。默认值为 6，对应于 HTML 标签 <h1> 到 <h6>。较小的值将限制生成的标题级别数。例如，值为 3 时，只会生成标题标签“#”、“##”和“###”。所有小于对应于“###”的字体大小的文本都将视为正文。

get_header_id(self, span: dict, page=None) → str#

返回适当的 markdown 标题前缀。这要么是空字符串“”或是一个由“#”字符后跟一个空格组成的字符串。

给定从“dict”提取的文本跨度，确定由 0 到 n 个连接的“#”字符组成的 markdown 标题前缀字符串。

参数：

  • span (dict) – 一个包含文本跨度信息的字典。这与 page.get_text("dict") 返回的字典相同。

  • page (Page) – 所属的页面对象。当需要提取附加信息时，可以使用此参数。

返回值：

一个由“#”字符后跟一个空格组成的字符串。

header_id#

一个字典，将（整数）字体大小映射到 Markdown 标题字符串，例如 {14: '# ', 12: '## '}。该字典由 IdentifyHeaders 构造函数创建。键是文档中文本跨度的字体大小。值是相应的标题字符串。

body_limit#

一个整数值，表示正文文本的字体大小限制。计算方法为 min(header_id.keys()) - 1。在上述示例中，body_limit 将为 11。

如何限制标题级别（示例）

将生成的标题级别限制为 3

import pymupdf, pymupdf4llm

filename = "input.pdf"
doc = pymupdf.open(filename)  # use a Document for subsequent processing
my_headers = pymupdf4llm.IdentifyHeaders(doc, max_levels=3)  # generate header info
md_text = pymupdf4llm.to_markdown(doc, hdr_info=my_headers)

如何提供您自己的标题逻辑（示例 1）

提供您自己的函数，该函数使用预先确定的固定字体大小

import pymupdf, pymupdf4llm

filename = "input.pdf"
doc = pymupdf.open(filename)  # use a Document for subsequent processing

def my_headers(span, page=None):
    """
    Provide some custom header logic.
    This is a callable which accepts a text span and the page.
    Could be extended to check for other properties of the span, for
    instance the font name, text color and other attributes.
    """
    # header level is h1 if font size is larger than 14
    # header level is h2 if font size is larger than 10
    # otherwise it is body text
    if span["size"] > 14:
        return "# "
    elif span["size"] > 10:
        return "## "
    else:
        return ""

# this will *NOT* scan the document for font sizes!
md_text = pymupdf4llm.to_markdown(doc, hdr_info=my_headers)

如何提供您自己的标题逻辑（示例 2）

此用户函数使用文档的目录 – 假设书签文本也作为标题行出现在页面上（这当然不一定！）

import pymupdf, pymupdf4llm

filename = "input.pdf"
doc = pymupdf.open(filename)  # use a Document for subsequent processing
TOC = doc.get_toc()  # use the table of contents for determining headers

def my_headers(span, page=None):
    """
    Provide some custom header logic (experimental!).
    This callable checks whether the span text matches any of the
    TOC titles on this page.
    If so, use TOC hierarchy level as header level.
    """
    # TOC items on this page:
    toc = [t for t in TOC if t[-1] == page.number + 1]

    if not toc:  # no TOC items on this page
        return ""

    # look for a match in the TOC items
    for lvl, title, _ in toc:
        if span["text"].startswith(title):
            return "#" * lvl + " "
        if title.startswith(span["text"]):
            return "#" * lvl + " "

    return ""

# this will *NOT* scan the document for font sizes!
md_text = pymupdf4llm.to_markdown(doc, hdr_info=my_headers)
class TocHeaders#
__init__(self, doc: pymupdf.Document | str)#

创建一个对象，该对象使用文档的目录 (TOC) 来确定标题级别。对象创建时，通过 Document.get_toc() 方法读取目录。然后，TOC 数据用于在 to_markdown() 方法中确定标题级别。

这是 IdentifyHeaders 的替代方案。它不是通过完整文档来识别字体大小，而是使用文档的目录 (TOC) 来识别页面上的标题。与 IdentifyHeaders 一样，这也不能保证找到标题，但对于结构良好的目录，比基于字体大小的方法更有可能正确识别文档页面上的标题行。

它还有一个优点是比基于字体大小的方法快得多，因为它不执行完整的文档扫描，甚至不访问任何文档页面。

此方法效果很好的例子是 Adobe 的 PDF 文档文件。

请注意，此功能不读取目录可能作为普通标准文本存在的文档页面。它仅访问由 Document.get_toc() 方法提供的数据。对于目录不作为书签集合提供的文档，它不会识别任何标题。

get_header_id(self, span: dict, page=None) → str#

返回适当的 markdown 标题前缀。这要么是空字符串“”或是一个由“#”字符后跟一个空格组成的字符串。

给定从“dict”提取变体得到的文本跨度，确定由 0 到 n 个连接的“#”字符组成的 markdown 标题前缀字符串。

参数：

  • span (dict) – 一个包含文本跨度信息的字典。这与 page.get_text("dict") 返回的字典相同。

  • page (Page) – 所属的页面对象。当需要提取附加信息时，可以使用此参数。

返回值：

一个由“#”字符后跟一个空格组成的字符串。

如何使用类 TocHeaders

这是前一个示例 2 的一个版本，它使用 TocHeaders 进行标题识别

import pymupdf, pymupdf4llm

filename = "input.pdf"

doc = pymupdf.open(filename)  # use a Document for subsequent processing
my_headers = pymupdf4llm.TocHeaders(doc)  # use the table of contents for determining headers

# this will *NOT* scan the document for font sizes!
md_text = pymupdf4llm.to_markdown(doc, hdr_info=my_headers)
class pdf_markdown_reader.PDFMarkdownReader#
load_data(file_path: Union[Path, str], extra_info: Optional[Dict] = None, **load_kwargs: Any) → List[LlamaIndexDocument]#

这是您当前应该用于提取 markdown 数据的 markdown 阅读器中唯一的方法。请在任何情况下忽略 aload_data() 和 lazy_load_data() 方法。use_doc_meta() 等其他方法可能有用，也可能无用。有关更多信息，请参阅 LlamaIndex 文档 [1]。

在底层，此方法将执行 to_markdown()。

返回值：

一个 LlamaIndexDocument 文档列表 - 每页一个。

有关更改列表，请参阅文件 CHANGES.md。

注脚

本软件按“原样”提供，不附带任何明示或暗示的担保。本软件按许可分发，除非获得该许可条款的明确授权，否则不得复制、修改或分发。有关许可信息，请访问 artifex.com 或联系 Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States 获取更多信息。

本文档涵盖所有版本，直至 1.26.0。