跳转到主要内容

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.txtUTF-8 文本《秋园小记》散文,TextLoader 示例
gbk文件.txtGBK 编码文本悬疑小说开头,演示编码错误与 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 文件无
PyPDFLoaderPDF(文字型),按页切分pypdf
load_scanned_pdf(本章自建)图片型(扫描)PDFpypdfium2、pillow、rapidocr-onnxruntime
DirectoryLoader目录批量加载取决于 loader_cls
GithubFileLoaderGitHub 仓库无
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 次),线上应用要考虑缓存。


上一节:RAG 原理 · 下一节:文本切分