LangChain 数据加载器详解

本文只介绍 LangChain 的数据加载器（Document Loaders）：它们是什么、有哪些类型、如何使用，以及如何根据数据源选择合适的加载器。

目录前置：数据加载器功能汇总表

LangChain 的加载器来自核心包、langchain-community 以及大量第三方集成包。下面汇总本文涉及的全部主要加载器。由于第三方集成会持续增加，表中的“功能”按数据来源和实际用途概括；使用前仍应以当前版本的官方集成文档为准。

类别	Loader	主要功能	常见使用场景
本地文件	TextLoader	读取 TXT、Markdown 等纯文本文件	本地笔记、说明文档
本地文件	DirectoryLoader	遍历目录，并把每个文件交给指定 Loader 批量处理	批量导入知识库
本地文件	CSVLoader	按行或按字段读取 CSV 数据，并转换为文档	FAQ、商品表、数据表
本地文件	JSONLoader	从 JSON 中提取指定字段或对象	API 数据、配置数据
本地文件	PythonLoader	读取 Python 源代码	代码问答、代码检索
通用文件	UnstructuredFileLoader / UnstructuredLoader	借助 Unstructured 解析多种非结构化文件	混合格式文档库
PDF	PyPDFLoader	使用 pypdf 提取 PDF 文本，通常按页生成文档	普通文本型 PDF
PDF	PyMuPDFLoader	使用 PyMuPDF 读取 PDF 页面和文本	追求速度和兼容性的 PDF 处理
PDF	PDFPlumberLoader	使用 pdfplumber 提取文本、页面位置和表格信息	表格型 PDF、版面分析
PDF	PDFMinerLoader	使用 PDFMiner 进行文本提取	需要 PDFMiner 解析能力的文档
PDF	UnstructuredPDFLoader	使用 Unstructured 解析 PDF 的文本和结构元素	复杂排版 PDF
PDF	DoclingLoader / Docling	解析文档结构、表格、标题和版面	复杂 PDF、企业文档
PDF	PyMuPDF4LLMLoader	使用面向 LLM 的 PyMuPDF 处理 PDF	需要 Markdown 化的 PDF 内容
PDF	PDFParser	通过外部 PDF 解析服务提取文档内容	云端 PDF 解析
PDF	MinerULoader	使用 MinerU 解析 PDF 和其他复杂文档	学术论文、复杂版面
PDF	PdfInspectorLoader	检查和提取 PDF 内的文本、布局或元素信息	PDF 质量检查、结构化提取
PDF	PdfmuseLoader	提取 PDF/DOCX 的文本、表格、坐标和区块元数据	需要精确引用位置的 RAG
PDF	OpenDataLoader PDF	通过 OpenDataLoader 解析 PDF	企业文档解析
PDF	OxidizePdfLoader	使用 Rust 引擎解析 PDF，并辅助生成分块数据	大量 PDF、稳定解析
PDF	CVFileLoader	读取带有嵌入 Markdown、HTML 或 JSON 的简历 PDF	简历和结构化 PDF
PDF	HwpHwpxLoader	读取 HWP/HWPX 文档	韩文办公文档
PDF / 文档	Upstage Document Parse Loader	使用 Upstage 文档解析服务提取内容和结构	企业级复杂文档
PDF / 文档	UnDatasIO	通过 UnDatasIO 服务解析文档	云端文档解析
PDF / 文档	PolarisAIDataInsightLoader	使用 Polaris AI 文档抽取服务提取结构化内容	Office、PDF 等复杂文件
Office	Docx2txtLoader	提取 Word 文档中的正文文本	简单 .docx 文档
Office	UnstructuredWordDocumentLoader	解析 Word 文档的段落、标题和结构元素	企业 Word 文档
Office	UnstructuredPowerPointLoader	提取 PowerPoint 幻灯片中的文本和结构	培训材料、演示文稿
Office	UnstructuredExcelLoader	提取 Excel 工作簿、工作表和表格内容	表格知识库
网页	WebBaseLoader	加载并解析单个网页	文档页面、博客、帮助中心
网页	RecursiveUrlLoader	从入口 URL 递归发现和加载网页	小型网站、文档站
网页	SitemapLoader	根据 Sitemap 批量加载网页	网站知识库、帮助中心
网页	FirecrawlLoader	通过 Firecrawl 抓取、清洗和转换网页	动态网站、整站采集
网页	ApifyCrawlLoader	通过 Apify 爬虫抓取网页并转成文档	大规模网站抓取
网页	ApifyDatasetLoader	从 Apify 数据集读取已经抓取的数据	复用爬虫结果
网页	UnstructuredURLLoader	使用 Unstructured 解析 URL 内容	通用网页文本提取
网页	DomPrunerLoader	修剪网页 DOM，去除无关内容并压缩成 Markdown	降低网页噪声和 Token 消耗
网页	DiffbotCrawlLoader	使用 Diffbot 爬取网站并提取结构化内容	新闻、商品、网站数据
网页	DiffbotExtractLoader	使用 Diffbot 从网页中提取结构化实体信息	网页信息抽取
网页	AgentQLLoader	使用自然语言或查询从网页中提取结构化数据	动态网页数据提取
网页	HyperbrowserLoader	使用无头浏览器访问和抓取网页	需要浏览器执行能力的网页
网页	PlasmateSOMLoader	从浏览器页面提取带有 Set of Mark 的结构化内容	Agent 浏览器任务
网页 / 云端	HydrafetchLoader	通过 Hydrafetch 获取网页或远程内容	远程内容采集
云存储	GoogleDriveLoader	从 Google Drive 读取 Google 文档等内容	团队云端知识库
云存储	GCSFileLoader	读取 Google Cloud Storage 中的单个对象	云端文件导入
云存储	GCSDirectoryLoader	批量读取 GCS Bucket 中的文件	云端批量知识库
云存储	Azure Blob Storage Loader	从 Azure Blob Storage 容器或 Blob 读取文档	Azure 文件知识库
云存储	XNSBlobLoader	从 XNS Blob 存储读取对象	XNS 云端数据
云存储	langchain_box	从 Box 云盘读取和同步文件	企业云盘知识库
协作工具	SlackLoader	读取 Slack 频道和消息	团队聊天知识库
协作工具	TrelloLoader	读取 Trello 看板、列表和卡片	项目管理知识库
协作工具	Notion 相关 Loader	读取 Notion 页面、数据库和块内容	团队文档知识库
协作工具	ConfluenceLoader	读取 Confluence 页面和空间内容	企业 Wiki
协作工具	GoogleClassroomLoader	读取 Google Classroom 课程资料	教学资料库
协作工具	AgentMailLoader	读取 AgentMail 邮件内容	邮件知识库、邮件 Agent
知识库平台	Outline Loader	读取 Outline 知识库文档	团队 Wiki
知识库平台	Docugami Loader	从 Docugami 文档管理系统读取结构化文档	企业文档管理
知识库平台	LangSmithLoader	读取 LangSmith 中的追踪、数据或相关记录	调试数据、评估数据
代码仓库	GitLoader	从 Git 仓库加载指定文件	本地代码库问答
代码仓库	GithubFileLoader	从 GitHub 仓库读取文件	GitHub 代码检索
数据库	SnowflakeLoader	从 Snowflake 数据仓库读取数据	企业数据仓库
数据库	Google BigQuery Loader	从 BigQuery 查询或读取数据	云端分析数据
数据库	Google Cloud SQL Loader	从 Cloud SQL 的 PostgreSQL、MySQL 或 SQL Server 读取数据	云数据库
数据库	Google AlloyDB for PostgreSQL Loader	从 AlloyDB PostgreSQL 数据库读取数据	云端 PostgreSQL
数据库	Google Spanner Loader	从 Spanner 分布式数据库读取数据	大规模关系数据
数据库	Google Firestore Loader	从 Firestore Native 或 Datastore 模式读取文档	NoSQL 文档数据
数据库	Google Bigtable Loader	从 Bigtable 读取宽列数据	大规模键值数据
数据库	Oracle Autonomous Database Loader	从 Oracle Autonomous Database 读取数据	Oracle 云数据库
数据库	Google El Carro for Oracle Loader	读取运行在 Google Cloud 上的 Oracle 数据	Oracle 云迁移场景
数据库	Kinetica Document Loader	从 Kinetica 数据平台读取文档或数据	实时分析数据
数据库	SingleStoreLoader	从 SingleStore 数据库读取数据	实时数据库、混合检索
数据库	AstraDB Loader	从 Astra DB 读取文档或向量相关数据	Cassandra 云服务
数据库	PowerScaleDocumentLoader	从 Dell PowerScale 文件和文档存储读取内容	企业文件系统
数据处理	PySparkDataFrameLoader	把 PySpark DataFrame 的行转换成 Document	大数据处理结果
数据处理	AirbyteLoader	读取 Airbyte 同步到的数据源	多源数据同步
数据处理	Google Memorystore for Redis Loader	从 Redis 数据服务读取记录	缓存或键值数据
音频 / 视频	YoutubeLoader / YoutubeLoaderDL	获取 YouTube 字幕或视频转录文本	视频问答、课程知识库
音频 / 视频	Google Speech-to-Text Audio Transcripts Loader	读取语音转文字结果	音频转录知识库
音频 / 视频	Soniox Loader	使用 Soniox 语音服务获取转录文本	音频、会议记录
OCR / 视觉	PaddleOCR-VL Loader	使用 OCR 和视觉模型解析文字、版面和图片	扫描件、图文混排文档
企业文件	AlfrescoLoader	从 Alfresco 内容管理系统读取文档	企业内容管理
企业文件	OpenDMALoader	从 OpenDMA 文档管理系统读取内容	企业文档归档
企业文件	CapslaneLoader	从 Capslane 内容服务读取文档	企业内容接入
企业文件	SecureLangChainLoader	在安全控制环境中加载外部文档	受控数据接入
企业文件	ReplyLayerLoader	从 ReplyLayer 服务读取内容	企业消息或内容接入
企业文件	OpeddFeedLoader	读取带授权和来源信息的 Opedd 内容目录	合规内容接入
企业文件	EnconvertLoader	通过 Enconvert 服务转换并读取文件	格式转换、文档导入
其他	GutenbergLoader	读取 Project Gutenberg 电子书	公版书籍知识库
其他	ConLLULoader	读取 CoNLL-U 格式的语言学标注数据	NLP 训练和分析
其他	NucliaLoader	从 Nuclia 知识平台读取内容	Nuclia 知识库
其他	IuguLoader	从 Iugu 服务读取相关业务记录	Iugu 数据接入

注意：官方“全部加载器”目录包含大量社区和合作方集成，名称和数量会随版本变化；有些加载器并不在同一个 Python 包中，也可能需要独立安装对应集成包。官方当前分类和完整目录可参考 Document loader integrations。

1. 什么是数据加载器

数据加载器负责从不同来源读取数据，并把数据转换成 LangChain 统一的 Document 对象。

PDF / 网页 / TXT / 数据库 / 云盘
              ↓
          Document Loader
              ↓
Document(page_content, metadata)

一个 Document 通常包含两个部分：

Document(
    page_content="这是文档的正文内容",
    metadata={
        "source": "manual.pdf",
        "page": 3
    }
)

• page_content：正文内容。
• metadata：来源、页码、标题、创建时间等辅助信息。

这些信息后续可以交给文本切分器、Embedding 模型和向量数据库，用于构建 RAG 知识库。

2. 加载器的统一接口

LangChain 的加载器通常实现 BaseLoader 接口。最常见的方法有两个：

方法	作用	适合场景
load()	一次性加载全部文档	文件较小、代码简单
lazy_load()	逐个或分批返回文档	大文件、大规模数据

使用 load()

from langchain_community.document_loaders import TextLoader

loader = TextLoader("notes.txt", encoding="utf-8")
documents = loader.load()

for document in documents:
    print(document.page_content)
    print(document.metadata)

使用 lazy_load()

from langchain_community.document_loaders import TextLoader

loader = TextLoader("large-notes.txt", encoding="utf-8")

for document in loader.lazy_load():
    print(document.page_content[:100])

3. 常见的数据加载器分类

LangChain 官方文档中的加载器数量很多，而且会随着版本和集成生态变化。学习时不需要把所有类名都背下来，更重要的是根据数据源选择合适的类别。

3.1 本地文本文件

Loader	用途
TextLoader	TXT、Markdown 等纯文本文件
DirectoryLoader	批量加载一个目录中的文件
CSVLoader	CSV 表格文件
JSONLoader	JSON 文件
PythonLoader	Python 源代码文件
UnstructuredFileLoader	通过 Unstructured 处理多种文件格式

加载 TXT 文件

from langchain_community.document_loaders import TextLoader

loader = TextLoader("data/intro.txt", encoding="utf-8")
documents = loader.load()

批量加载目录

from langchain_community.document_loaders import DirectoryLoader
from langchain_community.document_loaders import TextLoader

loader = DirectoryLoader(
    "data/",
    glob="**/*.txt",
    loader_cls=TextLoader,
    loader_kwargs={"encoding": "utf-8"}
)

documents = loader.load()

DirectoryLoader 本身通常不负责解析所有格式，它更像一个批处理器：遍历目录，然后把每个文件交给指定的 loader_cls。

3.2 PDF 文件

PDF 是 RAG 中最常见、也最容易出问题的数据源之一。

Loader	特点
PyPDFLoader	使用 pypdf，适合普通文本型 PDF
PyMuPDFLoader	使用 PyMuPDF，速度和兼容性较好
PDFPlumberLoader	对文本定位和表格处理更友好
PDFMinerLoader	使用 PDFMiner 提取文本
UnstructuredPDFLoader	适合复杂文档结构
DoclingLoader	适合复杂排版、表格和结构化解析

使用 PyPDFLoader

from langchain_community.document_loaders import PyPDFLoader

loader = PyPDFLoader("manual.pdf")
documents = loader.load()

print(len(documents))
print(documents[0].metadata)

普通 PDF 通常会按页生成多个 Document，元数据中可能包含页码和文件来源。

如何选择 PDF Loader

• PDF 主要是连续文字：先尝试 PyPDFLoader。
• 需要更好的速度或页面处理：尝试 PyMuPDFLoader。
• 包含表格、复杂布局、多栏排版：考虑 PDFPlumberLoader、Unstructured 或 Docling。
• PDF 是扫描图片：普通文本 Loader 通常无法读取，需要 OCR 或支持视觉解析的方案。

3.3 Word、PowerPoint 和 Excel

常见的 Office 文档加载方式包括：

Loader	用途
Docx2txtLoader	提取 Word 文档正文
UnstructuredWordDocumentLoader	解析 Word 结构
UnstructuredPowerPointLoader	提取 PowerPoint 内容
UnstructuredExcelLoader	读取 Excel 内容

示例：

from langchain_community.document_loaders import Docx2txtLoader

loader = Docx2txtLoader("report.docx")
documents = loader.load()

对于 Office 文档，重点不是“能不能加载”，而是是否能保留标题、段落、表格和页面结构。结构丢失后，即使后面的向量检索正常，回答质量也可能下降。

3.4 网页和网站

Loader	用途
WebBaseLoader	加载单个网页
RecursiveUrlLoader	从入口地址递归抓取网页
SitemapLoader	根据网站 Sitemap 批量加载页面
FirecrawlLoader	使用 Firecrawl 抓取和清洗网页
ApifyCrawlLoader	使用 Apify 抓取网站内容
UnstructuredURLLoader	使用 Unstructured 解析网页

加载单个网页

from langchain_community.document_loaders import WebBaseLoader

loader = WebBaseLoader("https://example.com/docs")
documents = loader.load()

网页加载通常还需要处理：

• 导航栏、页脚和广告内容。
• 动态 JavaScript 页面。
• 访问频率限制和 robots.txt。
• 网页更新后的增量同步。
• 页面标题、URL 和发布时间等元数据。

如果只是学习，可以从 WebBaseLoader 开始；如果要抓取一个完整网站，通常需要专门的爬虫或网页解析服务。

3.5 云存储和生产力工具

LangChain 也提供了连接云存储和协作工具的加载器，例如：

数据来源	常见 Loader
Google Drive	GoogleDriveLoader
Google Cloud Storage	GCSFileLoader、GCSDirectoryLoader
Slack	SlackLoader
Trello	TrelloLoader
Notion	Notion 相关 Loader
Confluence	ConfluenceLoader
GitHub	GithubFileLoader

这类 Loader 通常需要：

• API Key 或 OAuth 授权。
• 指定文件夹、频道、数据库或页面范围。
• 处理访问权限和用户隐私。
• 保存来源 ID 和更新时间，方便后续增量更新。

3.6 代码仓库

代码也可以作为知识库数据，例如用于构建代码问答助手。

常见加载方式包括：

• GitLoader：加载 Git 仓库中的文件。
• GithubFileLoader：从 GitHub 获取文件。
• PythonLoader：加载 Python 源代码。
• DirectoryLoader：批量加载指定扩展名的代码文件。

代码加载时通常需要过滤：

• .git 目录。
• 构建产物和依赖目录。
• 二进制文件。
• 密钥、配置文件和环境变量文件。

3.7 数据库和数据平台

LangChain 生态中也有面向数据库、数据仓库和 DataFrame 的加载集成，例如：

• Snowflake 相关 Loader。
• BigQuery 相关集成。
• PySparkDataFrameLoader。
• 其他数据库或云数据平台 Loader。

不过，数据库问答不一定要把所有数据转换成向量。对于结构化数据，直接生成 SQL 查询往往更合适；只有当数据库字段中包含大量文本时，才适合把文本字段加载、切分并建立向量索引。

3.8 音频和视频

常见场景是把视频字幕或音频转录结果加载为文档，例如：

• YoutubeLoader：读取 YouTube 字幕。
• 语音转文字服务 Loader：先转录音频，再生成 Document。
• 视频内容解析服务：提取字幕、画面描述和时间戳。

这类数据最好保留时间信息，例如：

{
    "source": "video.mp4",
    "start_time": 120,
    "end_time": 160
}

这样回答时可以定位到视频的具体时间段。

4. Loader、Parser 和 Splitter 的区别

这几个概念容易混淆：

组件	主要职责
Loader	从数据源读取内容
Parser	从复杂格式中提取正文和结构
Splitter	把长文本切成适合检索的片段
Embedding	把文本转换成向量
Vector Store	保存向量并执行相似度检索

典型流程如下：

Loader
  ↓
Parser / Cleaner
  ↓
Text Splitter
  ↓
Embedding
  ↓
Vector Store

有些集成会把 Loader 和 Parser 合并，因此一个 Loader 可能同时完成读取和解析工作。

5. 如何选择数据加载器

可以使用下面的决策方式：

你的数据	推荐起点
TXT、Markdown	TextLoader
一批本地文件	DirectoryLoader
普通 PDF	PyPDFLoader
表格型 PDF	PDFPlumberLoader 或专门的文档解析器
扫描 PDF	OCR 或视觉文档解析器
Word、PPT、复杂 Office	Unstructured 或 Docling
单个网页	WebBaseLoader
整个网站	Sitemap、爬虫或网页抓取服务
GitHub 代码	GithubFileLoader
结构化数据库	优先考虑 SQL 查询，而不是直接向量化
视频字幕	YoutubeLoader 或转录服务

学习阶段建议先掌握以下 6 个：

TextLoader
DirectoryLoader
PyPDFLoader
WebBaseLoader
CSVLoader
DoclingLoader

6. 包和版本问题

许多常用 Loader 的导入路径是：

from langchain_community.document_loaders import TextLoader

但 LangChain 的集成正在逐步拆分到独立的集成包中。例如某些文档解析器可能需要单独安装对应包，而不是只安装 langchain。

因此安装时要注意：

pip install -U langchain langchain-community

具体 Loader 还可能需要额外依赖，例如 PDF 解析库、网页解析库、OCR 库或云服务 SDK。最可靠的做法是根据当前版本的官方集成页面安装对应依赖。

7. 常见问题和坑

7.1 编码问题

中文文本文件经常遇到编码错误，可以显式指定编码：

loader = TextLoader("notes.txt", encoding="utf-8")

7.2 PDF 能打开，但提取不到文字

这通常意味着 PDF 是扫描图片，或者文本编码和排版结构比较特殊。此时需要 OCR 或更强的文档解析工具。

7.3 元数据丢失

如果只保留正文，不保留 source、页码和标题，后续很难展示引用，也不利于权限过滤和问题排查。

7.4 一次性加载过多数据

大规模数据不适合直接调用 load() 把所有内容放进内存，可以使用 lazy_load()，并结合批处理和增量更新。

7.5 把结构化数据强行当成文本

表格、数据库和 JSON 具有结构。简单拼成字符串虽然可以建立向量，但可能破坏字段关系。对于这类数据，要考虑保留字段名、主键、时间和业务关系。

7.6 加载成功不等于知识库质量高

Loader 只负责把数据读进来。真正影响检索效果的，还包括：

• 文档清洗质量。
• 文本切分方式。
• 元数据设计。
• Embedding 模型。
• 检索策略。
• 文档是否过时或重复。

8. 一个完整的本地 PDF 加载示例

from langchain_community.document_loaders import PyPDFLoader


def load_pdf(path: str):
    loader = PyPDFLoader(path)
    documents = loader.load()

    for index, document in enumerate(documents):
        document.metadata["document_type"] = "pdf"
        document.metadata["page_index"] = index

    return documents


documents = load_pdf("manual.pdf")

print(f"加载了 {len(documents)} 个 Document")
print(documents[0].metadata)

9. 总结

LangChain 数据加载器的核心价值，是把不同来源的数据转换成统一的 Document 格式。

可以用一句话记忆：

Loader 负责“把资料拿进来”，Parser 负责“把资料读出来”，Splitter 负责“把资料切好”，后续组件再负责向量化和检索。

常用选择可以概括为：

文本       → TextLoader
目录       → DirectoryLoader
PDF        → PyPDFLoader / PyMuPDFLoader
复杂文档   → Unstructured / Docling
网页       → WebBaseLoader
云端数据   → 对应云服务 Loader
代码       → GitLoader / GithubFileLoader
视频字幕   → YoutubeLoader

参考资料

• LangChain 官方：Document loader integrations
• LangChain 官方：Python API Reference