🎯 课程主题
学习 Word、Markdown、HTML 等非结构化格式文件的加载，以及 DirectoryLoader 批量加载文件夹，最后剖析 BaseLoader 父类的统一接口设计。
📝 核心知识点
Word 文件加载器（Docx2txtLoader / UnstructuredWordDocumentLoader）
- Word 属于非结构化数据，需导入
unstructured包 - 核心参数：
file_path：Word 文件路径mode："single"— 整个文件作为一个 Document"elements"— 按标题切分为多个 Document
from langchain_community.document_loaders import UnstructuredWordDocumentLoader
loader = UnstructuredWordDocumentLoader(
file_path="./sample.docx",
mode="single" # 或 "elements"
)
docs = loader.load()
# mode="single" → len(docs) == 1
# mode="elements" → len(docs) 取决于标题数量
Markdown 文件加载器（UnstructuredMarkdownLoader）
- 同样基于
unstructured包 - 核心参数：
file_path：Markdown 文件路径mode："single"/"elements"（按标题切分）strategy：解析策略"fast"：快速模式，不做复杂版面分析"hi_res"（high resolution）：高分辨率模式，精度更高但耗时较长
from langchain_community.document_loaders import UnstructuredMarkdownLoader
# 快速模式，整体加载
loader = UnstructuredMarkdownLoader(
file_path="./sample.md",
mode="single",
strategy="fast"
)
docs = loader.load()
# len(docs) == 1
# 按标题切分
loader = UnstructuredMarkdownLoader(
file_path="./sample.md",
mode="elements",
strategy="fast"
)
docs = loader.load()
# len(docs) == 19（取决于文档结构）
HTML 文件加载器（UnstructuredHTMLLoader）
- 参数体系与 Markdown 加载器一致：
file_path、mode、strategy- 额外支持
include_ocr—— 是否对图片中的文字进行 OCR 提取
from langchain_community.document_loaders import UnstructuredHTMLLoader
loader = UnstructuredHTMLLoader(
file_path="./sample.html",
mode="elements",
strategy="fast"
)
docs = loader.load()
DirectoryLoader（批量加载文件夹）
- 加载整个文件夹下的所有文件（按通配符过滤）
- 核心参数：
path：文件夹路径glob：UNIX 风格通配符（如"*.py"）use_multithreading：是否开启多线程加速show_progress：是否显示进度条loader_cls：指定底层使用的具体 Loader
from langchain_community.document_loaders import DirectoryLoader, TextLoader
loader = DirectoryLoader(
path="./load_files",
glob="*.py",
use_multithreading=True,
show_progress=True,
loader_cls=TextLoader
)
docs = loader.load()
# len(docs) == 4（该目录下有 4 个 .py 文件）
BaseLoader 父类源码分析
所有 Loader 都继承自 BaseLoader，提供了一套统一接口：
| 方法 | 输入 | 输出 | 说明 |
|---|---|---|---|
load() | 无 | List[Document] | 最常用，返回 Document 列表 |
load_and_split(text_splitter) | TextSplitter 实例 | List[Document] | 加载的同时进行切分 |
lazy_load() | 无 | Iterator[Document] | 惰性加载，适用于大文件 |
Document 结构
class Document:
page_content: str # 文档文本内容
metadata: dict # 元数据（文件名、页数等）
🏗️ 架构与工作流
💻 代码实战
完整示例：多种格式联合加载
from langchain_community.document_loaders import (
UnstructuredWordDocumentLoader,
UnstructuredMarkdownLoader,
UnstructuredHTMLLoader,
DirectoryLoader,
TextLoader
)
# Word 加载
word_loader = UnstructuredWordDocumentLoader(
file_path="./docs/report.docx", mode="single"
)
word_docs = word_loader.load()
# Markdown 加载（按标题切分）
md_loader = UnstructuredMarkdownLoader(
file_path="./docs/readme.md", mode="elements", strategy="fast"
)
md_docs = md_loader.load()
# HTML 加载
html_loader = UnstructuredHTMLLoader(
file_path="./docs/page.html", mode="elements", strategy="fast"
)
html_docs = html_loader.load()
# 批量加载 Python 文件
dir_loader = DirectoryLoader(
path="./src",
glob="*.py",
use_multithreading=True,
show_progress=True,
loader_cls=TextLoader
)
py_docs = dir_loader.load()
# 合并所有文档
all_docs = word_docs + md_docs + html_docs + py_docs
print(f"共加载 {len(all_docs)} 个 Document")
⚠️ 常见问题与避坑指南
- 依赖问题：Word/Markdown/HTML 的 Loader 都需要
unstructured包，需提前通过requirements.txt安装。 - mode 选择：
"single"用于粗略加载，后续再统一切分"elements"按文档结构（标题）预切分，但切分粒度可能不均匀
- strategy 选择：
"fast"适合大多数场景，速度快"hi_res"精度更高但慢，用于对文档结构要求严格的场景
- DirectoryLoader 的通配符：使用 UNIX 风格路径通配符，Windows 下需注意路径分隔符。
- 多线程加速：
use_multithreading=True可显著加快批量加载速度，但在某些环境下可能不稳定。 - Document 的 metadata：不同 Loader 生成的 metadata 字段不同，使用时需注意兼容性。
💡 个人总结与延伸
- 统一接口的价值：所有 Loader 都继承
BaseLoader，遵循load()→List[Document]的统一范式。这意味着无论加载什么格式，下游处理流程完全一致，体现了 LangChain 链式架构的核心设计理念。 - mode 参数的设计哲学：
"single"保留完整语义，"elements"做预切分。实际项目中建议先"single"加载，再用专用的 TextSplitter 做精细化切分，比"elements"更可控。 - DirectoryLoader 的实用性：在 RAG 项目中，往往需要加载整个知识库文件夹。结合
glob过滤和loader_cls指定，可以灵活应对混合格式的文档集合。 - load_and_split 是一个便捷方法，但在生产环境中建议分开操作（先 load 再 split），以便更精细地控制切分参数和调试中间结果。