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

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

一、核心依赖与库说明

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

库名称	功能说明	必备性
langchain-community	LangChain 社区版，包含 UnstructuredFileLoader 等核心解析类	必需
unstructured	底层文档解析引擎，支持 20+ 文档格式的结构化转换	必需
unstructured[pdf]	unstructured 的 PDF 解析扩展，包含 pdfminer、pypdf 等解析器	处理 PDF 时必需
unstructured[md]	Markdown 解析扩展，支持标题、列表、代码块等元素识别	处理 Markdown 时必需
pdf2image	将 PDF 页面转换为图像（用于复杂排版或扫描件解析）	可选（高精度 PDF 解析时需用）
python-multipart	支持多部分文档解析（如包含附件的 PDF）	可选

安装命令：

# 基础安装（含 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）初始化参数详解

参数名	类型	功能说明	示例值
file_path	str / Path / 列表（可选）	本地文件路径，支持单个或多个文件（列表形式）。与 file、web_url 互斥，三选一。	"./report.pdf" 或 ["./a.pdf", "./b.md"]
file	IO[bytes] / 列表（可选）	字节流对象（如打开的文件句柄），支持单个或多个。用于直接处理内存中的文件数据。	open("doc.pdf", "rb")
web_url	str（可选）	网页 URL，用于加载并解析网页内容（自动提取文本和结构）。	"https://example.com/article"
partition_via_api	bool（默认 False）	是否通过 Unstructured API 解析文档（需配置 api_key）。False 则使用本地引擎解析。	True（使用 API）、False（本地解析）
post_processors	列表[Callable[[str], str]]（可选）	文本后处理函数列表，每个函数接收字符串并返回处理后的字符串（如去除多余空格、替换特殊字符）。	[lambda x: x.strip(), lambda x: x.replace("\n", " ")]
api_key	str（可选）	Unstructured API 的密钥，当 partition_via_api=True 时必填。可通过环境变量 UNSTRUCTURED_API_KEY 配置。	"your_api_key_here"
client	UnstructuredClient（可选）	自定义的 UnstructuredClient 实例，用于高级 API 配置（如超时设置、代理等）。	UnstructuredClient(api_key="key", timeout=30)
url	str（可选）	Unstructured API 的服务地址，默认使用官方地址。仅当 partition_via_api=True 时有效。	"https://custom-unstructured-api.com"
**kwargs	任意键值对	传递给底层解析引擎的参数，如 strategy="hi_res"（高精度解析）、ocr_languages="chi_sim"（OCR 语言）等。	strategy="hi_res", pdf_infer_table_structure=True
coordinates	bool类型	配置是否在元数据中保留元素的坐标信息： ①启用后，解析结果的 metadata 会包含每个元素（如标题、段落）在文档中的位置坐标（如像素坐标、页面范围）； ②适用于需要定位文本在原始文档中物理位置的场景（如高亮显示、文档对比，像有表格提取解析需求则避开）。	True

（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",  # 网页 URLpartition_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 库的原生参数"""

核心参数解析

参数名	类型	功能详解	示例值
file_path	str/Path	待解析文件的本地路径（必填）	“./docs/report.pdf”
mode	str	解析后文档的组织方式： ① “single”：所有内容合并为一个 Document 对象 ② “elements”：按元素(标题、段落等)拆分为多个 Document 对象	“elements”
post_processors	List[Callable]	对解析后的元素列表进行处理的函数（如过滤空白、合并短文本）	[lambda els: [e for e in els if e.text.strip()]]
strategy	str	解析策略（通过 unstructured_kwargs 传递）： ① “fast”：快速解析(优先文本提取) ② “hi_res”：高精度解析(保留复杂结构) ③ “ocr_only”：强制 OCR 识别（扫描件）	“hi_res”
pdf_infer_table_structure	bool	是否解析 PDF 表格结构（仅 PDF 有效），设为 True 时表格转为 Markdown 格式	True
md_start_tag/md_end_tag	str	Markdown 解析时的起始/结束标记（用于提取文档片段）	“”, “”

方法：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 场景下）
file_path	str/Path	待解析 PDF 文件的本地路径（必填），需确保文件后缀为 .pdf
mode	str	解析模式： - “single”：合并所有页面内容为单个文档 - “elements”：按 PDF 中的元素（标题、表格等）拆分
post_processors	List[Callable]	针对 PDF 解析结果的后处理函数（如过滤页眉页脚、合并跨页段落）
**unstructured_kwargs	任意键值对	PDF 专用解析参数： - strategy：解析策略（“hi_res” 适合复杂排版 PDF） - pdf_infer_table_structure：是否解析表格结构 - page_numbers：指定解析的页码列表（如 [1,3,5]）

• 与通用加载器的区别：默认启用 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 场景下）
file_path	str/Path	待解析 Markdown 文件的本地路径（必填），需确保文件后缀为 .md 或 .markdown
mode	str	解析模式： ① “single”：合并所有内容为单个文档 ② “elements”：按 Markdown 元素（标题、列表等）拆分
post_processors	List[Callable]	针对 Markdown 解析结果的后处理函数（如过滤注释、合并相邻文本）
**unstructured_kwargs	任意键值对	Markdown 专用解析参数： ① md_start_tag/md_end_tag：提取指定标记包裹的内容 ② include_headers_footers：是否包含文档首尾的注释内容

• 特性：自动识别 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() 方法保留了合并元素的元数据（如最早的页码），确保溯源性。