LangChain
09 · 文档加载器
txt、PDF、扫描件 OCR、目录、GitHub、网页、搜索
- LangChain
- Python
本节速览
这一节的每一块内容,分别是干什么的:
| 内容 | 是干什么的 |
|---|---|
| Document | 统一数据抽象,任何来源都转成 page_content + metadata |
| 文本与 PDF Loader | 本地文件加载 |
| 扫描件 OCR | 图片型 PDF 识别成文字再入库 |
| 目录批量加载 | 整个文件夹一次读入 |
| GitHub / 网页 / 搜索 Loader | 远程仓库、URL、搜索结果加载 |
RAG 第一步:把各种来源的原始数据加载进 LangChain。每种数据源对应一个 Loader,load() 统一返回 Document 列表。
版本说明:加载器从 langchain_community.document_loaders 导入,安装 pip install langchain-community。该包已被官方宣布 sunset(issue #674),不再接受新集成、只做必要维护,因此导入时必打一条 DeprecationWarning——功能照常。langchain_classic.document_loaders 里的同名类只是转发层,底层仍是 community 那一份代码,警告一模一样,换过去没有任何规避作用(本章代码统一从 community 导入)。官方给的方向是独立集成包,但 TextLoader / PyPDFLoader 目前没有对应独立包,所以仍走 community。想让输出干净,就在导入前加一行过滤(本章后面几处示例都这样写):
import warnings
warnings.filterwarnings("ignore", message="`langchain-community` is being sunset*")
配套数据下载
本章示例引用的文件都在这里,下载后放进项目的 data/ 目录,即可原样跑通全部代码:
| 文件 | 类型 | 说明 |
|---|---|---|
| qiu.txt | UTF-8 文本 | 《秋园小记》散文,TextLoader 示例 |
| gbk文件.txt | GBK 编码文本 | 悬疑小说开头,演示编码错误与 autodetect_encoding |
| report.pdf | 文字型 PDF(12 页) | 年度报告,每页一个 Document,元数据带页码 |
| novel.pdf | 文字型 PDF(12 页) | 《城南旧频》小说,演示整本合并 |
| scan.pdf | 图片型 PDF(2 页) | 模拟扫描件,页面是图片、没有文字层,演示 PyPDFLoader 读不出字、OCR 加载器读得出 |
文字型与图片型的区别,一句话:文字型的页面由文字层构成,直接抽取;图片型(扫描件/拍照)的页面是整张图片,抽取结果为空,必须先 OCR(下文有现场演示)。
Document:统一数据抽象
没有它会怎样——PDF 一套解析、网页一套爬取、txt 一套读取,每种来源一个数据结构,下游切分器要为每种来源写一套适配。
有了它——万物归 Document(page_content + metadata),切分、入库只认这一个结构。
不管原始数据是 PDF、网页还是搜索结果,加载结果都是 Document:
| 字段 | 含义 |
|---|---|
page_content | 文本内容,后续切分与 embedding 的对象 |
metadata | 元数据:来源路径、页码等,用于检索后过滤和答案溯源 |
类比记忆:Document 是一个快递包裹——page_content 是箱子里面的货,metadata 是面单。货会被拆开重组(切分)、被扫描识别(向量化),但面单一路贴着走,到终点你依然知道它从哪来。
手工构造两个 Document,看看它长什么样(加载器 load() 出来的就是这种对象,这里先手工模拟):
from langchain_core.documents import Document # 统一文档对象
pages = [
Document(page_content="退货请在下单后 7 天内发起。",
metadata={"source": "售后手册.pdf", "page": 3}),
Document(page_content="会员积分每年 12 月 31 日清零。",
metadata={"source": "售后手册.pdf", "page": 4}),
]
for doc in pages:
print(doc.page_content) # 货:正文,后续切分、向量化的对象
print(doc.metadata) # 面单:来源、页码——不向量化,只负责跟着走
# 退货请在下单后 7 天内发起。
# {'source': '售后手册.pdf', 'page': 3}
# 会员积分每年 12 月 31 日清零。
# {'source': '售后手册.pdf', 'page': 4}
为什么非要把「货」和「面单」焊在一起?看检索命中之后能干什么:
# 接上一块:pages 是上面手工构造的两个 Document
hit = pages[0] # 假设向量检索命中的是第一块
print(f"答案出处:{hit.metadata['source']} 第 {hit.metadata['page']} 页")
# 答案出处:售后手册.pdf 第 3 页
如果只传裸字符串,走到这一步就断了——字符串上没长「我来自哪」这个信息,引用角标 [1]、按来源过滤、文档级权限全都无从谈起。后面整条流水线(加载器产出 → 切分器消费产出 → 向量库存的就是它)流通的都是这个结构,切分时子块还会自动继承父块的 metadata。
加载器速查
| Loader | 数据源 | 额外依赖 |
|---|---|---|
TextLoader | 单个 txt 文件 | 无 |
PyPDFLoader | PDF(文字型),按页切分 | pypdf |
load_scanned_pdf(本章自建) | 图片型(扫描)PDF | pypdfium2、pillow、rapidocr-onnxruntime |
DirectoryLoader | 目录批量加载 | 取决于 loader_cls |
GithubFileLoader | GitHub 仓库 | 无 |
WebBaseLoader | 静态网页 | beautifulsoup4 |
| SerpAPI(用 SDK 自建) | 搜索结果 | serpapi |
文本与 PDF
没有它会怎样——PDF 自己找库解析:装错库中文乱码,表格变成碎字符串,扫描件完全读不出。
有了它——loader 统一处理,load() 出来就是 Document 列表。
from langchain_community.document_loaders import PyPDFLoader, TextLoader # PDF 与 txt 加载器
docs = TextLoader("data/qiu.txt").load() # 整个文件一个 Document
pdfs = PyPDFLoader("data/report.pdf").load() # 每页一个 Document
print(len(docs), len(pdfs)) # txt 恒为 1;PDF 几页就是几个
# 1 12
print(docs[0].page_content[:30]) # txt 的正文就是整个文件内容
# 《秋园小记》
# 秋天的后园里,墙角有一棵老槐树。风一起
print(pdfs[0].metadata) # PDF 元数据自带页码(从 0 开始)
# {'producer': 'PyPDF', 'creator': 'PyPDF', 'creationdate': '2026-10-13T12:49:52+00:00',
# 'source': 'data/report.pdf', 'total_pages': 12, 'page': 0, 'page_label': '1'}
PyPDFLoader 默认按页切分,每个 Document 的 metadata 带 page 页码(从 0 开始)、total_pages 总页数、page_label 页码字符串,producer/creator/creationdate 是 pypdf 从 PDF 文档信息里读出来的(各库、各版本字段略有出入,page 与 source 一定有)。Python 版没有「整本合并」开关,需要时手动拼接:
from langchain_community.document_loaders import PyPDFLoader # PDF 加载器
from langchain_core.documents import Document # 统一文档对象
pdfs = PyPDFLoader("data/novel.pdf").load() # 按页加载,每页一个 Document
pdf = Document(
page_content="\n\n".join(doc.page_content for doc in pdfs), # 全文拼成一段
metadata=pdfs[0].metadata, # 元数据取第一页的,source 还在
)
print(len(pdfs), len(pdf.page_content)) # 12 页合成一个长文本
# 12 2329
print(pdf.metadata)
# {'producer': 'PyPDF', 'creator': 'PyPDF', 'creationdate': '2026-10-13T12:49:52+00:00',
# 'source': 'data/novel.pdf', 'total_pages': 12, 'page': 0, 'page_label': '1'}
TextLoader 打开非 UTF-8 文件(比如 GBK 编码的中文 txt)报编码错误时,传 autodetect_encoding=True:
from langchain_community.document_loaders import TextLoader # txt 加载器
docs = TextLoader("data/gbk文件.txt", autodetect_encoding=True).load()
print(len(docs)) # 还是 1 个 Document
# 1
print(docs[0].page_content[:20]) # 不再抛 UnicodeDecodeError,正文正常读出
# 第一章 风起云涌
# 大厦将倾之际,总有人看
scan.pdf 是图片型(扫描件)PDF:页面上的字是「画」上去的图片,不是文字。看 PyPDFLoader 的下场:
from langchain_community.document_loaders import PyPDFLoader # PDF 加载器
scan = PyPDFLoader("data/scan.pdf").load() # 图片型 PDF:能"读",但读不到字
print(len(scan)) # 页数正常,Document 照样给
# 2
print(repr(scan[0].page_content.strip())) # 一个字都读不出——没有文字层
# ''
不报错、不警告,悄悄给你一个空字符串——这种文件混进知识库,就是「明明入库了却永远搜不到」的隐形事故。图片型 PDF 的正确姿势是先 OCR 再入库,下一节就把这份 scan.pdf 真正读出来。企业知识库建设里最常见的坑就在这:大量历史扫描件,入库容易,能被检索到难。
扫描件 OCR
没有它会怎样——图片型 PDF 永远读不出字,上一节那种空字符串入库了也检索不到。
有了它——图片里的字识别成文本,照样组装成 Document,下游切分、入库一行不用改。
OCR 引擎用 RapidOCR(onnxruntime 版):模型从 PaddleOCR 转成 onnx 打包在 wheel 里,装完离线可用,中英文都认。Tesseract 中文识别偏弱,Windows 上还得装系统程序;PaddleOCR 官方版要拖整个 paddlepaddle 框架,依赖重。「PDF 页面 → 图片」这步交给 pypdfium2,它只封装 PDFium、自身零依赖,to_pil() 需要的 Pillow 得另行安装:
pip install pypdfium2 pillow rapidocr-onnxruntime # onnxruntime、opencv、numpy 随 rapidocr-onnxruntime 自动装上
rapidocr-onnxruntime 要求 Python < 3.13,更高的 Python 版本用官方新出的统一包 rapidocr。另外,它其实也声明了 Pillow 依赖(内部读图要用),上面显式装一份只是让 to_pil() 的来源更明确。
加载器存成 ocr_loader.py,python ocr_loader.py 直接跑演示。思路三步:pypdfium2 把每页渲染成图片,RapidOCR 认字,组装成和 PyPDFLoader 同结构的 Document:每页一个,metadata 同样带 source 和从 0 开始的 page:
import numpy as np # 图像转数组喂给 OCR
import pypdfium2 as pdfium # PDF 渲染成图片
from rapidocr_onnxruntime import RapidOCR # OCR 引擎,中英文模型内置在包里
from langchain_core.documents import Document # 统一文档对象
_ocr = RapidOCR() # 模块级建一个实例,首次调用加载模型几秒,之后全进程复用
def load_scanned_pdf(path: str, scale: float = 2.0) -> list:
"""OCR 整本扫描 PDF,返回与 PyPDFLoader 同结构的 Document 列表(每页一个)。
scale: 渲染放大倍数,越大越清晰也越慢;2.0 对常规扫描件够用,小字可用 3.0
"""
pdf = pdfium.PdfDocument(path)
docs = []
for i, page in enumerate(pdf):
img = page.render(scale=scale).to_pil()
result, _ = _ocr(np.array(img)) # result 每项是 [文字坐标, 文本, 置信度],取第 2 项拼正文
text = "\n".join(item[1] for item in result) if result else ""
docs.append(Document(page_content=text, metadata={"source": path, "page": i}))
return docs
if __name__ == "__main__":
docs = load_scanned_pdf("data/scan.pdf")
print(len(docs), "页") # 页数与 PyPDFLoader 读出来的一致
# 2 页
for d in docs:
print(f"--- 第 {d.metadata['page']} 页({len(d.page_content)} 字) ---")
print(d.page_content[:150])
# --- 第 0 页(82 字) ---
# 售后维修申请单
# 申请单位:城南旧货市场管理处
# 设备名称:收音机(无商标)
# 送修日期:2026年10月13日
# 故障描述:夜间出现异常频率
# 处理意见:建议移交技术科检测
# --- 第 1 页(76 字) ---
# 技术科检测回执
# 检测编号:SC-2026-1013
# 检测结论:频率来源不明
# 备注:该设备出厂信息无法查证
# 复核人:(签名)
# 日期:2026年10月14日
同一个文件,PyPDFLoader 给空字符串,这里两页各读出 82、76 字,检测编号、送修日期这些关键字段都在。实测两页约 10 秒(含首次加载模型),大批量扫描件要把这个耗时算进建库周期。识别率不够时:小字把 scale 提到 3.0,噪点、倾斜严重的件先做图像预处理;重要语料入库前抽检。另一条路是多模态模型直接读图,效果更好但按 token 计费,大批量时成本高。这个函数就是图片型 PDF 的入库入口,产出与文字型 PDF 同构,切分、embedding、入库走同一套流程。
目录批量加载
没有它会怎样——几十个文件写 os.walk 手动循环:过滤后缀、拼路径、猜编码、包 Document,这套样板每个项目抄一遍。
有了它——DirectoryLoader 一个参数搞定,还能配 glob 和递归。
DirectoryLoader 用 glob 匹配文件,绑定一种加载器。多种格式分别建实例再拼接:
import warnings
warnings.filterwarnings("ignore", message="`langchain-community` is being sunset*")
from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader, TextLoader # 目录、PDF、txt 加载器
from langchain_core.documents import Document
class AutoEncodingTextLoader(TextLoader):
"""先按 UTF-8 读,失败自动降级 GBK——目录里编码混杂时不用写死一种"""
def lazy_load(self):
for enc in ("utf-8", "gbk"):
try:
with open(self.file_path, encoding=enc) as f:
text = f.read()
yield Document(page_content=text, metadata={"source": self.file_path})
return
except UnicodeDecodeError:
continue
raise RuntimeError(f"utf-8/gbk 都读不了: {self.file_path}")
txt_loader = DirectoryLoader("./data", glob="**/*.txt", loader_cls=AutoEncodingTextLoader)
pdf_loader = DirectoryLoader("./data", glob="**/*.pdf", loader_cls=PyPDFLoader)
docs = txt_loader.load() + pdf_loader.load()
print(len(docs)) # 匹配到的 txt 文件数 + 所有 PDF 的总页数
# 47
for doc in docs[:3]: # 每一块都能说出自己来自哪个文件
print(doc.metadata["source"])
# data/notes/day01.txt
# data/notes/day02.txt
# data/report.pdf
不匹配 glob 的文件直接跳过。loader_kwargs 把参数转传给底层加载器,show_progress=True 显示进度条:
import warnings
warnings.filterwarnings("ignore", message="`langchain-community` is being sunset*")
from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader # 目录、PDF 加载器
pdf_loader = DirectoryLoader(
"./data",
glob="**/*.pdf",
loader_cls=PyPDFLoader,
# loader_kwargs={"password": "xxx"}, # 只在目录里的 PDF 全部加密时才开;没加密的文件收到密码反而报错
show_progress=True, # 大目录加载时显示进度条
)
docs = pdf_loader.load()
print(len(docs)) # 进度条走完后,输出的还是熟悉的 Document 列表
# 31
GitHub 仓库
没有它会怎样——要么整个仓库 clone 下来自己遍历,要么手调 GitHub API 处理分页和鉴权,拿到的还是碎片。
有了它——GithubFileLoader 按仓库 / 分支 / 路径直接拉文件,过滤代码类型。
适合给「代码问答」类应用建库。先到 github.com/settings/tokens 页面,点 Generate new token(classic),勾选 repo 权限,生成后立即复制(只显示这一次),存进 .env 的 GITHUB_TOKEN:
import warnings
warnings.filterwarnings("ignore", message="`langchain-community` is being sunset*")
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_community.document_loaders import GithubFileLoader # 加载 GitHub 仓库
load_dotenv()
def code_file_filter(file_path: str) -> bool:
# 白名单放行文本类源码文件——黑名单挡不住图片/字体等二进制,当 UTF-8 解码会炸
return file_path.endswith((".ts", ".js", ".mjs", ".cjs", ".css", ".html"))
loader = GithubFileLoader(
repo="tailwindlabs/tailwindcss", # 注意是 "owner/repo",不是完整 URL
branch="main", # 已实测默认分支是 main(教程写成 master 所以 404)
file_filter=code_file_filter,
access_token=os.environ["GITHUB_TOKEN"],
)
docs = loader.load()
print(len(docs)) # file_filter 放行了多少个文件
# 38
print(docs[0].metadata["source"]) # 每块的 source 就是仓库里的文件路径
# src/cli/index.js
print(docs[0].page_content[:40]) # 正文就是文件源码,可直接切分入库
# import { createRequire } from 'module
坑:仓库树默认整体递归拉取,大仓库会产生大量 API 请求。测试阶段先用 file_filter 只放行少量文件验证流程。
网页
没有它会怎样——自己 requests + BeautifulSoup:正文提取规则每个网站一套,遇到 JS 渲染的页面拿到的是空壳 HTML。
有了它——loader 内置正文提取,load() 直接出正文文本。
WebBaseLoader 抓取网页并提取正文,只处理静态 HTML,不执行页面里的 JS:
import os
os.environ.setdefault("USER_AGENT", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) langchain-demo")
import warnings
warnings.filterwarnings("ignore", message="`langchain-community` is being sunset*")
import bs4 # HTML 解析
from langchain_community.document_loaders import WebBaseLoader # 抓取网页正文
loader = WebBaseLoader("https://example.com/blog/post")
docs = loader.load()
print(len(docs)) # 单个 URL 就是一个 Document
# 1
print(docs[0].metadata) # source 记录了原始链接,溯源用
# {'source': 'https://example.com/blog/post'}
print(docs[0].page_content.strip()[:60]) # 提取出的正文文本,不是原始 HTML
# How to Build a Scalable Design System……
# 只要部分内容时用 SoupStrainer 过滤——注意先确认目标页真实用的标签层级(此站用 h2,没有 h3)
loader = WebBaseLoader(
"https://memolab.cn/docs/agent/langchain/09-%E6%96%87%E6%A1%A3%E5%8A%A0%E8%BD%BD%E5%99%A8/#%E5%8A%A0%E8%BD%BD%E5%99%A8%E9%80%9F%E6%9F%A5",
bs_kwargs={"parse_only": bs4.SoupStrainer("h2")},
)
docs = loader.load()
print(docs[0].page_content) # 正文只剩命中标签的文本,入库更干净
# Getting Started
# Installation
# Theming
JS 渲染的 SPA 页面抓不到正文,换 Playwright 等浏览器类方案。
搜索结果
没有它会怎样——想拿搜索结果当语料,要自己申请搜索 API、处理配额和反爬,拿到的还是 HTML 要二次清洗。
有了它——搜索 loader 一行出结果列表,直接进 RAG 管线。
Python 版没有现成的 SerpAPILoader,用 serpapi SDK 取回结果后手工构造 Document,字段完全可控。Key 到 serpapi.com 注册获取,登录后首页就能看到(免费计划每月 100 次搜索):
import warnings
warnings.filterwarnings("ignore", message="`langchain-community` is being sunset*")
import json # 序列化搜索结果
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from serpapi import GoogleSearch # SerpAPI 搜索客户端(包名是 google-search-results,不是 serpapi)
from langchain_core.documents import Document # 统一文档对象
load_dotenv()
api_key = os.environ.get("SERP_KEY")
if not api_key:
raise SystemExit("还没有配置 SERP_KEY —— 到 https://serpapi.com 注册(免费 100 次/月),"
"拿到 key 后在 .env 里加一行 SERP_KEY=你的key,再运行")
results = GoogleSearch({
"q": "什么是 github copilot",
"api_key": api_key,
}).get_dict()
docs = [
Document(
page_content=json.dumps(result, ensure_ascii=False),
metadata={"source": "SerpAPI", "response_type": "organic_results"},
)
for result in results.get("organic_results", [])
]
print(len(docs)) # organic_results 有几条就是几个 Document
# 10
print(docs[0].page_content[:80]) # 标题、摘要、链接都序列化进了正文
# {"position": 1, "title": "GitHub Copilot · Your AI pair programmer", "lin
print(docs[0].metadata) # 面单标注了数据来源与类型,方便后续过滤
# {'source': 'SerpAPI', 'response_type': 'organic_results'}
每条结果的标题、摘要、链接都写进了 page_content,等于「搜索 + 取摘要」一步完成。搜索类 API 有配额(SerpAPI 免费计划每月 100 次),线上应用要考虑缓存。