> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# PyMuPDF4LLMLoader 集成

> 使用 LangChain Python 集成 PyMuPDF4LLMLoader 文档加载器。

本指南提供了快速入门 `PyMuPDF4LLMLoader` [文档加载器](https://python.langchain.com/docs/concepts/#document-loaders) 的概述。有关 `PyMuPDF4LLMLoader` 所有功能和配置的详细文档，请前往 [GitHub 仓库](https://github.com/lakinduboteju/langchain-pymupdf4llm)。

## 概述

### 集成详情

| 类                                                                             | 包                                                                         |  本地 | 可序列化 | JS 支持 |
| :---------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :-: | :--: | :---: |
| [`PyMuPDF4LLMLoader`](https://github.com/lakinduboteju/langchain-pymupdf4llm) | [`langchain-pymupdf4llm`](https://pypi.org/project/langchain-pymupdf4llm) |  ✅  |   ❌  |   ❌   |

### 加载器特性

|          来源         | 文档惰性加载 | 原生异步支持 | 提取图像 | 提取表格 |
| :-----------------: | :----: | :----: | :--: | :--: |
| `PyMuPDF4LLMLoader` |    ✅   |    ❌   |   ✅  |   ✅  |

## 设置

要使用 PyMuPDF4LLM 文档加载器，您需要安装 `langchain-pymupdf4llm` 集成包。

### 凭证

使用 PyMuPDF4LLMLoader 无需凭证。

要启用模型调用的自动追踪，请设置您的 [LangSmith](/langsmith/home) API 密钥：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"
```

### 安装

安装 **langchain-community** 和 **langchain-pymupdf4llm**。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -qU langchain-community langchain-pymupdf4llm
```

## 初始化

现在我们可以实例化模型对象并加载文档：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_pymupdf4llm import PyMuPDF4LLMLoader

file_path = "./example_data/layout-parser-paper.pdf"
loader = PyMuPDF4LLMLoader(file_path)
```

## 加载

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
docs = loader.load()
docs[0]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Document(metadata={'producer': 'pdfTeX-1.40.21', 'creator': 'LaTeX with hyperref', 'creationdate': '2021-06-22T01:27:10+00:00', 'source': './example_data/layout-parser-paper.pdf', 'file_path': './example_data/layout-parser-paper.pdf', 'total_pages': 16, 'format': 'PDF 1.5', 'title': '', 'author': '', 'subject': '', 'keywords': '', 'moddate': '2021-06-22T01:27:10+00:00', 'trapped': '', 'modDate': 'D:20210622012710Z', 'creationDate': 'D:20210622012710Z', 'page': 0}, page_content='\`\`\`\nLayoutParser: A Unified Toolkit for Deep\n\n## Learning Based Document Image Analysis\n\n\`\`\`\n\nZejiang Shen[1] (�), Ruochen Zhang[2], Melissa Dell[3], Benjamin Charles Germain\nLee[4], Jacob Carlson[3], and Weining Li[5]\n\n1 Allen Institute for AI\n\`\`\`\n              shannons@allenai.org\n\n\`\`\`\n2 Brown University\n\`\`\`\n             ruochen zhang@brown.edu\n\n\`\`\`\n3 Harvard University\n_{melissadell,jacob carlson}@fas.harvard.edu_\n4 University of Washington\n\`\`\`\n              bcgl@cs.washington.edu\n\n\`\`\`\n5 University of Waterloo\n\`\`\`\n              w422li@uwaterloo.ca\n\n\`\`\`\n\n**Abstract. Recent advances in document image analysis (DIA) have been**\nprimarily driven by the application of neural networks. Ideally, research\noutcomes could be easily deployed in production and extended for further\ninvestigation. However, various factors like loosely organized codebases\nand sophisticated model configurations complicate the easy reuse of important innovations by a wide audience. Though there have been on-going\nefforts to improve reusability and simplify deep learning (DL) model\ndevelopment in disciplines like natural language processing and computer\nvision, none of them are optimized for challenges in the domain of DIA.\nThis represents a major gap in the existing toolkit, as DIA is central to\nacademic research across a wide range of disciplines in the social sciences\nand humanities. This paper introduces LayoutParser, an open-source\nlibrary for streamlining the usage of DL in DIA research and applications. The core LayoutParser library comes with a set of simple and\nintuitive interfaces for applying and customizing DL models for layout detection, character recognition, and many other document processing tasks.\nTo promote extensibility, LayoutParser also incorporates a community\nplatform for sharing both pre-trained models and full document digitization pipelines. We demonstrate that LayoutParser is helpful for both\nlightweight and large-scale digitization pipelines in real-word use cases.\n[The library is publicly available at https://layout-parser.github.io.](https://layout-parser.github.io)\n\n**Keywords: Document Image Analysis · Deep Learning · Layout Analysis**\n\n    - Character Recognition · Open Source library · Toolkit.\n\n### 1 Introduction\n\n\nDeep Learning(DL)-based approaches are the state-of-the-art for a wide range of\ndocument image analysis (DIA) tasks including document image classification [11,\n\n')
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import pprint

pprint.pp(docs[0].metadata)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{'producer': 'pdfTeX-1.40.21',
 'creator': 'LaTeX with hyperref',
 'creationdate': '2021-06-22T01:27:10+00:00',
 'source': './example_data/layout-parser-paper.pdf',
 'file_path': './example_data/layout-parser-paper.pdf',
 'total_pages': 16,
 'format': 'PDF 1.5',
 'title': '',
 'author': '',
 'subject': '',
 'keywords': '',
 'moddate': '2021-06-22T01:27:10+00:00',
 'trapped': '',
 'modDate': 'D:20210622012710Z',
 'creationDate': 'D:20210622012710Z',
 'page': 0}
```

## 惰性加载

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pages = []
for doc in loader.lazy_load():
    pages.append(doc)
    if len(pages) >= 10:
        # 执行一些分页操作，例如：
        # index.upsert(page)

        pages = []
len(pages)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
6
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from IPython.display import Markdown, display

part = pages[0].page_content[778:1189]
print(part)
# Markdown 渲染
display(Markdown(part))
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pprint.pp(pages[0].metadata)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{'producer': 'pdfTeX-1.40.21',
 'creator': 'LaTeX with hyperref',
 'creationdate': '2021-06-22T01:27:10+00:00',
 'source': './example_data/layout-parser-paper.pdf',
 'file_path': './example_data/layout-parser-paper.pdf',
 'total_pages': 16,
 'format': 'PDF 1.5',
 'title': '',
 'author': '',
 'subject': '',
 'keywords': '',
 'moddate': '2021-06-22T01:27:10+00:00',
 'trapped': '',
 'modDate': 'D:20210622012710Z',
 'creationDate': 'D:20210622012710Z',
 'page': 10}
```

元数据属性至少包含以下键：

* source
* page（如果在 *page* 模式下）
* total\_page
* creationdate
* creator
* producer

额外的元数据特定于每个解析器。
这些信息可能很有用（例如，用于对 PDF 进行分类）。

## 分割模式与自定义页面分隔符

加载 PDF 文件时，您可以通过两种不同的方式分割它：

* 按页
* 作为单个文本流

默认情况下，PyMuPDF4LLMLoader 将按页分割 PDF。

### 按页提取 PDF。每页被提取为一个 langchain 文档对象

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
loader = PyMuPDF4LLMLoader(
    "./example_data/layout-parser-paper.pdf",
    mode="page",
)
docs = loader.load()

print(len(docs))
pprint.pp(docs[0].metadata)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
16
{'producer': 'pdfTeX-1.40.21',
 'creator': 'LaTeX with hyperref',
 'creationdate': '2021-06-22T01:27:10+00:00',
 'source': './example_data/layout-parser-paper.pdf',
 'file_path': './example_data/layout-parser-paper.pdf',
 'total_pages': 16,
 'format': 'PDF 1.5',
 'title': '',
 'author': '',
 'subject': '',
 'keywords': '',
 'moddate': '2021-06-22T01:27:10+00:00',
 'trapped': '',
 'modDate': 'D:20210622012710Z',
 'creationDate': 'D:20210622012710Z',
 'page': 0}
```

在此模式下，PDF 按页分割，生成的文档元数据包含 `page`（页码）。但在某些情况下，我们可能希望将 PDF 作为单个文本流处理（这样就不会将某些段落截断）。在这种情况下，您可以使用 *single* 模式：

### 将整个 PDF 提取为单个 langchain 文档对象

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
loader = PyMuPDF4LLMLoader(
    "./example_data/layout-parser-paper.pdf",
    mode="single",
)
docs = loader.load()

print(len(docs))
pprint.pp(docs[0].metadata)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
1
{'producer': 'pdfTeX-1.40.21',
 'creator': 'LaTeX with hyperref',
 'creationdate': '2021-06-22T01:27:10+00:00',
 'source': './example_data/layout-parser-paper.pdf',
 'file_path': './example_data/layout-parser-paper.pdf',
 'total_pages': 16,
 'format': 'PDF 1.5',
 'title': '',
 'author': '',
 'subject': '',
 'keywords': '',
 'moddate': '2021-06-22T01:27:10+00:00',
 'trapped': '',
 'modDate': 'D:20210622012710Z',
 'creationDate': 'D:20210622012710Z'}
```

逻辑上，在此模式下，`page`（页码）元数据会消失。以下是如何在文本流中清晰识别页面结束位置：

### 添加自定义 *pages\_delimiter* 以在 *single* 模式下标识页面结束位置

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
loader = PyMuPDF4LLMLoader(
    "./example_data/layout-parser-paper.pdf",
    mode="single",
    pages_delimiter="\n-------THIS IS A CUSTOM END OF PAGE-------\n\n",
)
docs = loader.load()

part = docs[0].page_content[10663:11317]
print(part)
display(Markdown(part))
```

默认的 `pages_delimiter` 是 \n-----\n\n。
这可以简单地是 \n，或 \f 来明确表示页面更改，或 \<!-- PAGE BREAK --> 以便在 Markdown 查看器中无缝注入而不产生视觉影响。

# 从 PDF 中提取图像

您可以从 PDF 中提取图像（以文本形式），有三种不同的解决方案可供选择：

* rapidOCR（轻量级光学字符识别工具）
* Tesseract（高精度 OCR 工具）
* 多模态语言模型

结果将插入到页面文本的末尾。

### 使用 rapidOCR 从 PDF 中提取图像

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -qU rapidocr-onnxruntime pillow
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_community.document_loaders.parsers import RapidOCRBlobParser

loader = PyMuPDF4LLMLoader(
    "./example_data/layout-parser-paper.pdf",
    mode="page",
    extract_images=True,
    images_parser=RapidOCRBlobParser(),
)
docs = loader.load()

part = docs[5].page_content[1863:]
print(part)
display(Markdown(part))
```

请注意，RapidOCR 设计用于处理中文和英文，不适用于其他语言。

### 使用 tesseract 从 PDF 中提取图像

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -qU pytesseract
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_community.document_loaders.parsers import TesseractBlobParser

loader = PyMuPDF4LLMLoader(
    "./example_data/layout-parser-paper.pdf",
    mode="page",
    extract_images=True,
    images_parser=TesseractBlobParser(),
)
docs = loader.load()

print(docs[5].page_content[1863:])
```

### 使用多模态模型从 PDF 中提取图像

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -qU langchain-openai
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import os

from dotenv import load_dotenv

load_dotenv()
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
True
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from getpass import getpass

if not os.environ.get("OPENAI_API_KEY"):
    os.environ["OPENAI_API_KEY"] = getpass("OpenAI API key =")
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_community.document_loaders.parsers import LLMImageBlobParser
from langchain_openai import ChatOpenAI

loader = PyMuPDF4LLMLoader(
    "./example_data/layout-parser-paper.pdf",
    mode="page",
    extract_images=True,
    images_parser=LLMImageBlobParser(
        model=ChatOpenAI(model="gpt-4.1-mini", max_tokens=1024)
    ),
)
docs = loader.load()

print(docs[5].page_content[1863:])
```

# 从 PDF 中提取表格

使用 PyMUPDF4LLM，您可以从 PDF 中以 *markdown* 格式提取表格：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
loader = PyMuPDF4LLMLoader(
    "./example_data/layout-parser-paper.pdf",
    mode="page",
    # "lines_strict" 是默认策略，
    # 对于具有列线和行线的表格最准确，
    # 但可能不适用于所有文档。
    # "lines" 是一种不太严格的策略，可能对某些文档效果更好。
    # "text" 是最不严格的策略，可能对没有线条表格的文档效果更好。
    table_strategy="lines",
)
docs = loader.load()

part = docs[4].page_content[3210:]
print(part)
display(Markdown(part))
```

## 处理文件

许多文档加载器涉及解析文件。此类加载器之间的区别通常源于文件的解析方式，而不是文件的加载方式。例如，您可以使用 `open` 读取 PDF 或 Markdown 文件的二进制内容，但需要不同的解析逻辑将该二进制数据转换为文本。

因此，将解析逻辑与加载逻辑解耦会很有帮助，这使得无论数据如何加载，都更容易重用给定的解析器。
您可以使用此策略以相同的解析参数分析不同的文件。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_community.document_loaders import FileSystemBlobLoader
from langchain_community.document_loaders.generic import GenericLoader
from langchain_pymupdf4llm import PyMuPDF4LLMParser

loader = GenericLoader(
    blob_loader=FileSystemBlobLoader(
        path="./example_data/",
        glob="*.pdf",
    ),
    blob_parser=PyMuPDF4LLMParser(),
)
docs = loader.load()

part = docs[0].page_content[:562]
print(part)
display(Markdown(part))
```

***

## API 参考

有关 `PyMuPDF4LLMLoader` 所有功能和配置的详细文档，请前往 GitHub 仓库：[github.com/lakinduboteju/langchain-pymupdf4llm](https://github.com/lakinduboteju/langchain-pymupdf4llm)

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\oss\python\integrations\document_loaders\pymupdf4llm.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>