LangChain-Unstructured 基础使用：PDF 与 Markdown 处理解析

LangChain-Unstructured 基础使用：PDF 与 Markdown 处理解析

LangChain-Unstructured 作为 LangChain 生态中处理非结构化文档的核心工具，提供了丰富的类和方法来解析 PDF 和 Markdown 等格式。本文将系统讲解其核心库、关键类、方法参数及实战示例，帮助你全面掌握文档解析流程。

一、核心依赖与库说明

在使用 LangChain-Unstructured 处理 PDF 和 Markdown 时，需了解以下核心依赖及其作用：

安装命令：

# 基础安装（含 PDF 和 Markdown 支持）
pip install langchain-community unstructured[pdf,md] pdf2image

二、核心类与方法详解

LangChain-Unstructured 中最核心的类是 UnstructuredFileLoader（通用文件加载器）和衍生的 UnstructuredPDFLoader、UnstructuredMarkdownLoader（专用加载器）。以下详细讲解其用法。

1.UnstructuredLoader

UnstructuredLoader 是 langchain-unstructured 库中用于加载和解析非结构化文档的核心类，它提供了更灵活的文档处理能力，支持本地文件、字节流、网页 URL 等多种输入方式，并可通过 API 或本地引擎解析文档。是处理非结构化文档的强大工具，其核心优势在于：

1. 多输入支持：本地文件、字节流、网页 URL 全覆盖。
2. 灵活解析方式：本地解析（离线）或 API 解析（高精度，支持复杂场景）。
3. 可扩展处理：通过 post_processors 自定义文本清洗逻辑。
4. 适配多场景：同步/异步、惰性/非惰性加载，满足不同性能需求。

使用时需根据文档类型（文本/扫描 PDF、网页等）和场景（离线/在线、同步/异步）选择合适的参数配置，解析后的 Document 对象可直接用于文本分割、向量存储等后续步骤，为 LLM 应用（如问答、摘要）提供结构化输入。以下是其详细使用指南：

（1）类原型与核心功能

类定义

class langchain_unstructured.document_loaders.UnstructuredLoader(
    file_path: str | Path | list[str] | list[Path] | None = None,
    *,
    file: IO[bytes] | list[IO[bytes]] | None = None,
    partition_via_api: bool = False,
    post_processors: list[Callable[[str], str]] | None = None,
    api_key: str | None = None,
    client: UnstructuredClient | None = None,
    url: str | None = None,
    web_url: str | None = None,
    **kwargs: Any,
)[source]

核心功能

• 支持多种输入源：本地文件路径、字节流（IO[bytes]）、网页 URL（web_url）。
• 可选择本地解析或通过 Unstructured API 解析（partition_via_api 控制）。
• 提供文档后处理能力（post_processors），如文本清洗、格式转换等。
• 输出结构化的 Document 对象，包含文本内容（page_content）和元数据（metadata）。

（2）初始化参数详解

（3）核心方法详解

① load()

load() → list[Document]

• 功能：同步加载并解析文档，返回 Document 对象列表。
• 适用场景：中小型文件，需一次性获取所有结果。

② lazy_load()

lazy_load() → Iterator[Document]

• 功能：同步惰性加载，返回迭代器，逐次生成 Document 对象。
• 适用场景：大型文件或批量处理，减少内存占用。

③ aload()（异步）

async aload() → list[Document]

• 功能：异步加载并解析文档，返回 Document 列表。适用于异步代码环境（如 asyncio）。

④ alazy_load()（异步）

async alazy_load() → AsyncIterator[Document]

• 功能：异步惰性加载，返回异步迭代器，通过 async for 逐次获取 Document。

⑤ load_and_split()

load_and_split(text_splitter: TextSplitter | None = None) → list[Document]

• 功能：加载文档后按指定的 TextSplitter 拆分内容，返回拆分后的 Document 片段（用于 RAG 等场景）。
• 参数：text_splitter 为文本分割器，默认使用 RecursiveCharacterTextSplitter。

（3）使用示例

示例 1：解析本地 PDF 文件（本地引擎，带后处理）

from langchain_unstructured.document_loaders import UnstructuredLoader

# 定义后处理函数：去除空白并替换换行
def clean_text(text: str) -> str:
    return text.strip().replace("\n", " ")

# 初始化加载器
loader = UnstructuredLoader(
    file_path="./example.pdf",
    partition_via_api=False,  # 本地解析
    post_processors=[clean_text],  # 应用文本清洗
    strategy="hi_res",  # 高精度解析
    pdf_infer_table_structure=True  # 解析表格结构
)

# 加载文档
documents = loader.load()

# 输出结果
print(f"解析得到 {len(documents)} 个文档元素")
print(f"第一个元素类型：{documents[0].metadata['category']}")
print(f"内容预览：{documents[0].page_content[:200]}")

预期输出

解析得到 15 个文档元素
第一个元素类型：Title
内容预览：2024 年技术趋势报告 本报告总结了 2024 年人工智能、区块链等领域的核心趋势，包含市场数据和案例分析。以下为主要内容：...

结果分析

• 本地解析模式无需 API 密钥，适合离线场景。
• post_processors 成功去除了文本中的多余空白和换行，使内容更整洁。
• strategy="hi_res" 确保了复杂排版（如表格）的准确解析，元数据 category 标记了元素类型（标题、段落等）。

示例 2：通过 URL 加载网页内容

from langchain_unstructured.document_loaders import UnstructuredLoader

# 初始化加载器（解析网页）
loader = UnstructuredLoader(
    web_url="https://example.com/ai-trends",  # 网页 URL
    partition_via_api=False  # 本地解析网页
)

# 惰性加载（逐元素获取）
for doc in loader.lazy_load():
    print(f"元素类型：{doc.metadata['category']}")
    print(f"内容：{doc.page_content[:150]}\n---")

预期输出

元素类型：Title
内容：2024 年人工智能发展趋势
---
元素类型：NarrativeText
内容：随着大模型技术的成熟，2024 年人工智能在各行各业的应用进一步深化，尤其是在医疗、教育和制造业...
---
元素类型：ListItem
内容：- 多模态模型成为主流，跨媒体理解能力显著提升
---

结果分析

• web_url 参数直接加载网页并提取结构化元素（标题、段落、列表等），元数据 category 标记了元素类型。
• lazy_load() 逐次返回元素，适合处理长网页，避免一次性加载占用过多内存。

示例 3：使用 API 解析扫描型 PDF（OCR 识别）

from langchain_unstructured.document_loaders import UnstructuredLoader
import os

# 配置 API 密钥（也可通过环境变量设置）
os.environ["UNSTRUCTURED_API_KEY"] = "your_api_key"

# 初始化加载器（API 解析 + OCR）
loader = UnstructuredLoader(
    file_path="./scan_pdf.pdf",  # 扫描型 PDF（图片内容）
    partition_via_api=True,  # 使用 API 解析
    ocr_languages="eng+chi_sim"  # 支持中英双语 OCR
)

# 异步加载（适合 API 调用，避免阻塞）
import asyncio
async def main():
    docs = await loader.aload()
    print(f"OCR 解析结果：{docs[0].page_content[:300]}")

asyncio.run(main())

预期输出

OCR 解析结果：这是一份扫描的报告，包含中英文内容。2024 年全球 AI 市场规模预计达到 2 万亿美元，同比增长 40%。Key points: 1. 生成式 AI 商业化加速；2. 边缘 AI 设备普及...

结果分析

• partition_via_api=True 启用 Unstructured API，结合 OCR 技术成功识别扫描型 PDF 中的文本。
• ocr_languages 指定识别语言，确保中英双语内容准确提取。
• 异步方法 aload() 适合 API 调用场景，提高代码效率。

2. UnstructuredFileLoader

UnstructuredFileLoader 是 LangChain-Unstructured 中设计最通用的本地文件加载器，其核心定位是作为各类非结构化文档（包括但不限于 PDF、Markdown、Word、HTML、TXT 等本地文件）的统一解析入口。它的底层通过调用 unstructured 库的多格式解析能力，能够根据文件的后缀名自动匹配对应的解析引擎（例如对 .pdf 文件启用 PDF 解析器，对 .md 文件启用 Markdown 解析器），无需开发者手动指定文件类型。

类原型

class UnstructuredFileLoader(BaseLoader):
    def __init__(
        self,
        file_path: Union[str, Path],
        mode: str = "single",
        post_processors: Optional[List[Callable[[List[Element]], List[Element]]]] = None,
        **unstructured_kwargs: Any,
    ) -> None:
        """
        参数说明：
        - file_path: 文件路径（字符串或 Path 对象）
        - mode: 解析模式（"single" 合并为单个文档；"elements" 按元素拆分）
        - post_processors: 解析后处理函数列表（如过滤空文本）
        -** unstructured_kwargs: 传递给 unstructured 库的原生参数
        """

核心参数解析

方法：load()

功能：执行解析并返回文档列表
返回值：List[Document]（每个 Document 含 page_content 文本和 metadata 元数据）

简单使用示例

from langchain_community.document_loaders import UnstructuredFileLoader

# 初始化加载器，解析一个简单的TXT文件（通用加载器支持多格式）
loader = UnstructuredFileLoader(
    file_path="./sample.txt",  # 任意格式文件路径
    mode="single",  # 合并为单个文档
    strategy="fast"  # 快速解析模式
)

# 执行解析
documents = loader.load()

# 输出结果
print(f"解析得到的文档数量：{len(documents)}")
print(f"文档内容预览：{documents[0].page_content[:200]}")
print(f"文档元数据：{documents[0].metadata}")

预期运行结果

解析得到的文档数量：1
文档内容预览：这是一个示例文本文件，包含简单的段落内容。
它用于演示UnstructuredFileLoader的基本功能，
该加载器能够自动识别文件类型并提取文本。
文档元数据：{'source': './sample.txt', 'filename': 'sample.txt'}

结果分析

• 示例中使用 UnstructuredFileLoader 解析 TXT 文件，无需额外配置格式参数，体现了其“通用”特性；
• mode="single" 模式下，所有文本被合并为一个 Document 对象，适合需要完整文本的场景；
• 元数据中包含文件来源（source）和文件名（filename），便于追踪文档原始位置。

3. UnstructuredPDFLoader 与 UnstructuredMarkdownLoader

是 UnstructuredLoader 的子类，预配置了对应格式的解析参数，使用更简洁。

UnstructuredPDFLoader（PDF 专用）

UnstructuredPDFLoader 是针对 PDF 格式优化的专用加载器，继承自 UnstructuredFileLoader。它在通用加载器的基础上，预设了 PDF 解析的专属参数和引擎（如默认启用 pdfminer 解析器），能够更精准地处理 PDF 特有的结构（如页面布局、字体样式、嵌入表格等）。对于包含复杂排版（如多列文本、跨页表格、水印）的 PDF 文档，该加载器能通过内置的格式适配逻辑减少文本错乱问题。此外，它原生支持 PDF 特有的解析参数（如 pdf_infer_table_structure 用于表格识别），无需通过 unstructured_kwargs 间接传递，提升了代码的可读性。

类原型

class UnstructuredPDFLoader(UnstructuredFileLoader):
    def __init__(
        self,
        file_path: Union[str, Path],
        mode: str = "single",
        post_processors: Optional[List[Callable[[List[Element]], List[Element]]]] = None,
        **unstructured_kwargs: Any,
    ) -> None:
        super().__init__(file_path, mode, post_processors,** unstructured_kwargs)

核心参数解析（与父类一致，重点强调 PDF 适配特性）

• 与通用加载器的区别：默认启用 PDF 专用解析引擎，无需额外指定文件类型。

简单使用示例

from langchain_community.document_loaders import UnstructuredPDFLoader

# 初始化PDF专用加载器，解析含标题和段落的PDF
loader = UnstructuredPDFLoader(
    file_path="./report.pdf",
    mode="elements",  # 按元素拆分
    strategy="fast"  # 快速解析
)

# 执行解析
documents = loader.load()

# 输出结果
print(f"解析得到的元素数量：{len(documents)}")
# 打印第一个元素的类型和内容
print(f"第一个元素类型：{documents[0].metadata['element_type']}")
print(f"第一个元素内容：{documents[0].page_content[:150]}")

预期运行结果

解析得到的元素数量：8
第一个元素类型：Title
第一个元素内容：2024年人工智能发展报告
========================================
发布日期：2024年1月

结果分析

• 专用加载器自动识别 PDF 中的标题元素（element_type="Title"），体现了对 PDF 格式的针对性优化；
• mode="elements" 模式下，文档按语义单元拆分，便于后续按元素类型（标题/段落等）筛选内容；
• 无需手动指定文件类型，加载器默认使用 PDF 解析引擎，简化了配置。

UnstructuredMarkdownLoader（Markdown 专用）

UnstructuredMarkdownLoader 是专为 Markdown 格式设计的加载器，继承自 UnstructuredFileLoader。它深度适配 Markdown 的语法规则，能够精准识别标题层级（# 至 ######）、列表（有序/无序）、代码块（```包裹）、引用（> 开头）等特有元素，并在元数据中标记对应的 element_type（如 Header、ListItem、Code）。对于包含嵌套结构（如列表中嵌套代码块）的复杂 Markdown 文档，该加载器能保持元素间的层级关系，避免解析错乱。与通用加载器相比，它无需自动判断文件类型，直接调用 Markdown 专用解析逻辑，解析效率和精度更高。

类原型

class UnstructuredMarkdownLoader(UnstructuredFileLoader):
    def __init__(
        self,
        file_path: Union[str, Path],
        mode: str = "single",
        post_processors: Optional[List[Callable[[List[Element]], List[Element]]]] = None,
        **unstructured_kwargs: Any,
    ) -> None:
        super().__init__(file_path, mode, post_processors,** unstructured_kwargs)

核心参数解析（与父类一致，重点强调 Markdown 适配特性）

• 特性：自动识别 Markdown 中的标题（#）、列表（-/*）、代码块（```）等元素。

简单使用示例

from langchain_community.document_loaders import UnstructuredMarkdownLoader

# 初始化Markdown专用加载器，解析含列表的文档
loader = UnstructuredMarkdownLoader(
    file_path="./guide.md",
    mode="elements"  # 按元素拆分
)

# 执行解析
documents = loader.load()

# 筛选列表项元素
list_items = [doc for doc in documents if doc.metadata["element_type"] == "ListItem"]

# 输出结果
print(f"解析得到的列表项数量：{len(list_items)}")
print(f"第一个列表项内容：{list_items[0].page_content}")

预期运行结果

解析得到的列表项数量：3
第一个列表项内容：- 安装依赖：`pip install langchain-community unstructured`

结果分析

• 专用加载器精准识别 Markdown 中的列表项（element_type="ListItem"），保留了原始格式（包括 - 符号和代码块标记）；
• 对于技术文档等富含结构化元素的 Markdown 文件，这种针对性解析能有效分离不同类型的内容，便于后续处理（如单独提取代码块）。

三、PDF 解析实战示例

示例 1：高精度解析含表格的 PDF

解析包含标题、段落和表格的复杂 PDF，保留表格结构。

from langchain_community.document_loaders import UnstructuredPDFLoader

# 1. 初始化加载器（高精度模式 + 解析表格）
loader = UnstructuredPDFLoader(
    file_path="./example_pdf.pdf",
    mode="elements",  # 按元素拆分
    strategy="hi_res",  # 高精度解析
    pdf_infer_table_structure=True  # 解析表格为 Markdown 格式
)

# 2. 执行解析
documents = loader.load()

# 3. 输出解析结果（筛选关键元素）
print(f"共解析出 {len(documents)} 个元素")
for doc in documents[:4]:  # 打印前4个元素
    print(f"\n类型：{doc.metadata['element_type']}")
    print(f"页码：{doc.metadata['page_number']}")
    print(f"内容：{doc.page_content[:150]}...")  # 预览前150字符

预期输出(这里具体内容根据文件内容来定，下面输出仅作参考)

共解析出 12 个元素

类型：Title
页码：1
内容：2023 人工智能行业报告...

类型：NarrativeText
页码：1
内容：人工智能（AI）行业在 2023 年迎来爆发式增长，全球市场规模突破 1.5 万亿美元，同比增长 37%...

类型：Table
页码：2
内容：| 领域       | 市场规模（亿美元） | 增长率 |
|------------|------------------|--------|
| 计算机视觉   | 4200             | 45%    |
| 自然语言处理 | 3800             | 52%    |...

类型：ListItem
页码：3
内容：1. 技术趋势：多模态模型成为主流，跨领域融合能力显著提升...

结果分析

• 解析结果按元素类型（标题、正文、表格、列表项）拆分，元数据包含页码和类型，便于后续筛选。
• 表格被转为 Markdown 格式（| 字段 | 值 |），保留了原始结构，可直接用于 LLM 处理或转换为 DataFrame。

示例 2：处理扫描型 PDF（OCR 识别）

对无法直接复制文本的扫描件 PDF，使用 OCR 策略解析。

loader = UnstructuredPDFLoader(
    file_path="./scan_pdf.pdf",  # 扫描型 PDF（图片内容）
    mode="single",  # 合并为单个文档
    strategy="ocr_only",  # 强制 OCR 识别
    ocr_languages="eng+chi_sim"  # 支持英文和中文
)

documents = loader.load()
print(f"OCR 解析结果：\n{documents[0].page_content[:500]}")

预期输出

OCR 解析结果：
这是一份扫描的中文报告，包含中英文混合内容。
报告摘要：
2023 年全球 AI 专利申请量达 12 万件，其中中国占比 45%，位居全球第一。
Key Findings:
- AI 芯片性能提升 300%，成本下降 50%...

结果分析

• strategy="ocr_only" 强制启用 OCR 引擎，即使 PDF 是图片也能提取文本。
• ocr_languages 指定识别语言（chi_sim 为简体中文），确保多语言内容准确解析。

四、Markdown 解析实战示例

示例 3：解析含复杂结构的 Markdown

解析包含标题、代码块、公式的 Markdown 文件。

from langchain_community.document_loaders import UnstructuredMarkdownLoader

# 1. 初始化加载器
loader = UnstructuredMarkdownLoader(
    file_path="./example_md.md",
    mode="elements",  # 按元素拆分
    md_start_tag="<CONTENT>",  # 可选：仅解析标签内的内容
    md_end_tag="</CONTENT>"
)

# 2. 执行解析
documents = loader.load()

# 3. 输出解析结果
for doc in documents[:3]:
    print(f"\n类型：{doc.metadata['element_type']}")
    print(f"内容：{doc.page_content[:200]}...")

预期输出

类型：Header
内容：# 机器学习工作流详解...

类型：Paragraph
内容：机器学习工作流包含数据收集、预处理、模型训练、评估四个核心阶段，各阶段需紧密配合...

类型：Code
内容：```python
# 数据预处理示例
import pandas as pd
df = pd.read_csv("data.csv")
df = df.dropna()  # 去除缺失值
```...

结果分析

• Markdown 中的元素被精准识别：Header（标题）、Paragraph（段落）、Code（代码块）。
• 通过 md_start_tag 和 md_end_tag 可提取文档中的特定片段（如仅解析 <CONTENT> 标签包裹的内容），适合处理大型文档。

五、进阶技巧：后处理函数与元素过滤

解析后的元素可能包含空白文本或冗余内容，可通过 post_processors 优化。

from langchain_community.document_loaders import UnstructuredFileLoader

# 定义后处理函数：过滤空白文本 + 合并短文本
def filter_and_merge(elements):
    # 1. 过滤空白元素
    filtered = [e for e in elements if e.text.strip() and len(e.text) > 50]
    # 2. 合并短文本（小于200字符的相邻元素）
    merged = []
    current = []
    for e in filtered:
        if current and len(" ".join([c.text for c in current])) + len(e.text) < 200:
            current.append(e)
        else:
            if current:
                merged.append(current)
            current = [e]
    if current:
        merged.append(current)
    # 3. 转换为合并后的元素
    return [merged_elem[0].merge(merged_elem[1:]) for merged_elem in merged]

# 应用后处理函数
loader = UnstructuredFileLoader(
    file_path="./example.pdf",
    mode="elements",
    post_processors=[filter_and_merge],  # 启用后处理
    strategy="fast"
)

documents = loader.load()
print(f"后处理后剩余 {len(documents)} 个元素")

预期输出

后处理后剩余 8 个元素

结果分析

• 后处理函数过滤了空白文本和过短元素（<50字符），并合并了相邻的短文本，减少了元素数量，便于后续处理。
• element.merge() 方法保留了合并元素的元数据（如最早的页码），确保溯源性。