前端转 Agent 开发 · 第六节

🚀 前端转 Agent 开发 · 第六节：Document Loader 文档加载器

📅 学习日期：2026-09-11（Day 06） 🧑‍💻 学习者：一名前端开发工程师 🎯 今日目标：搞懂 Loader 数据接入体系，实战 CSV / JSON / TXT / PDF 四种加载器

📖 写在前面：这不就是 webpack loader 吗？！

看到 "Loader" 这个词，前端er 应该会心一笑 😄 ------ webpack 的 loader 把 .less、.vue、图片统统转成 JS 模块；LangChain 的 loader 把 PDF、Word、CSV、JSON 统统转成 Document。同一个设计哲学：异构输入 → 标准化输出。

所有 Loader 的产出物是统一的 Document 结构，就两个字段：

bash 复制代码

📄 Document
├── page_content  # 📝 正文内容（字符串）
└── metadata      # 🏷️ 元数据（来源、行号、文件名、权限标签...）

💡 前端类比：Document ≈ 接口返回的标准响应体 { data, meta } ------ 不管后端是什么数据库，到我手里格式永远一致，下游代码不用改。

🖼️ Loader 在企业级 Agent 里的角色：数据接入适配器

Loader 的五大职责：

🔍 解析：把 PDF、Word、JSON、CSV 等读进来
📐 标准化 ：统一成 Document（page_content + metadata）
📦 批量/流式：支持目录、S3、大文件
🏷️ 元数据：记录来源、行号、文件名、权限标签
🎯 为后续服务：分块、向量化、检索、RAG、分析

🏢 六大企业场景速览

场景	说明
📚 RAG 知识库	公司制度、合同、手册、Wiki、工单 → 向量化检索
📊 文件问答分析	业务人员没数据库权限，直接上传 CSV/Excel 让 Agent 分析
🔎 多源知识统一搜索	数据库导出 CSV + API JSON + PDF → 统一 Document → 企业搜索
🧾 半结构化数据接入	JSONLoader 的主场：API 响应、JSONL 日志、配置、Mongo/ES 导出
🗄️ 离线快照与审计	生产库只读导出 → 对象存储 → Loader 读取 → 离线分析/合规
🚀 原型验证	读几个 PDF 做 RAG、读 CSV 做问答，快速验证 Agent 想法

📊 一、CSVLoader：表格行变 Document

💻 示例代码

python 复制代码

from langchain_community.document_loaders import CSVLoader

csv_loader = CSVLoader(
    file_path="",   # 📂 文件路径
    encoding="utf-8"
)
# 方式一：load() 一次性全部加载
# file = csv_loader.load()

# 方式二：lazy_load() 懒加载，逐行产出 🐢
file = csv_loader.lazy_load()

for i in file:
    print(i.page_content)  # 📝 每一行 CSV = 一个 Document

⚖️ load vs lazy_load 怎么选？

方式	行为	适用场景
`load()`	一次性读全量到内存 📦	小文件，要反复用
`lazy_load()`	迭代器逐条产出 🐢	大文件，省内存（类似前端 ES6 的 generator / 分页拉取）

🤔 相关思考：file_path 也可以是"活的"

file_path 不用写死 ------ 上游模块把数据存成 CSV 落到某个位置，把路径传给下游 ，CSVLoader 读取解析后继续往下游传。这就是一条数据管道 ：数据库 → 导出 CSV → 沙箱/对象存储 → CSVLoader → Agent 分析。

🏢 CSVLoader 能为企业做什么？

📊 用户上传 CSV 分析 ：业务人员没库权限，上传文件 + CSVLoader + Pandas 分析
🏦 第三方数据交换：银行流水、供应商报价、政府报表，对方只给 CSV
☁️ 对象存储里的 CSV：S3/OSS 上大量导出文件，Agent 按需读取
📚 RAG 知识库：CSV 每一行转成 Document，向量化后检索
🗄️ 离线快照/审计归档：每月导出 CSV，固定不变，方便追溯

🧾 二、JSONLoader：半结构化数据的主场

处理 JSON 数据，封装为 Document 对象。需要先装依赖：

bash 复制代码

pip install jq

python 复制代码

from langchain_community.document_loaders import JSONLoader

loader = JSONLoader(
    file_path="你的文件路径",
    jq_schema="提取的字段"   # 🔍 用 jq 语法声明要提取哪部分数据
)
document = loader.load()
print(document)

💡 jq_schema 是 jq 查询语法（jq 是 JSON 界的"XPath/CSS 选择器"），可以精准声明"我要这个嵌套字段"，不用手动写解析逻辑。

JSONLoader 特别适合：API 返回的 JSON、应用日志 JSONL、配置数据、NoSQL 导出（MongoDB、Elasticsearch）、事件流/消息队列消息、嵌套结构的业务数据。

✂️ 三、TextLoader + 递归字符切割器

💡 为什么读完还要切？

大模型上下文有限，长文档必须**切小块（Chunk）**再向量化。这里用到 RecursiveCharacterTextSplitter（递归字符文本分割器）：按自然段落递归分割大文档，可指定小块最大字符数、重叠字符数、分隔符等。

python 复制代码

from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

loader = TextLoader(file_path="文件路径", encoding="utf-8")
file = loader.load()

# ✂️ 字符切割器
spliter = RecursiveCharacterTextSplitter(
    chunk_size=100,          # 📏 每个小块最大字符数
    chunk_overlap=10,        # 🔗 相邻块重叠字符数
    length_function=len,     # #️⃣ 字符数量统计函数
    separators=["\n", ""]    # ✂️ 优先按换行切，切不动再按字符切
)

split_doc = spliter.split_documents(file)
print(len(split_doc))  # 🧮 切成了多少块
for i in split_doc:
    print("=====")
    print(i)
    print("=====end===")

🔗 chunk_overlap 是干嘛的？

防止语义被"拦腰切断" ------ 相邻两块保留一小段重叠，就像前端虚拟列表的分片缓冲区：

css 复制代码

原文：AAAAAAAA BBBB CCCCCCCC DDDD
chunk1：[AAAAAAAA BBBB]
chunk2：　　　[BBBB CCCCCCCC DDDD]
         ↑↑ overlap 重叠区，上下文不断裂

📐 参数速查

参数	含义
`chunk_size`	单块最大字符数
`chunk_overlap`	相邻块的重叠字符数（保上下文）
`length_function`	长度计算函数（默认 `len`）
`separators`	递归切割的优先分隔符，从段落级到字符级逐级降级

📕 四、PyPDFLoader：PDF 按页解析

解析 PDF 文件类型，参数支持模式、密码等，具体看源码。

python 复制代码

from langchain_community.document_loaders import PyPDFLoader

loader = PyPDFLoader(
    file_path="文件路径",
    mode="page",        # 📄 按页切分：每页一个 Document
)

file = loader.lazy_load()  # 🐢 懒加载逐页产出

count = 0
for i in file:
    count += 1
    print(f"====={count}======")
    print(i)
    print("=====end===")

💡 mode="page" 按页切分对 RAG 很友好：metadata 里自带页码，检索命中后可以精确回答"在第 X 页"📑

🗺️ 明日计划

🔎 学习 Retriever（检索器）：向量库怎么把最相关的 Chunk 捞出来
🧮 动手跑一次 Embedding，把今天的 Chunk 真正灌进向量库
🌐 试试 WebBaseLoader / DirectoryLoader，批量加载网页和整个目录
🤖 组装第一个 RAG 问答链：Loader → Splitter → 向量库 → 检索 → 回答

🎯 今日总结

📌 一句话 ：Loader 就是 Agent 的"数据接入适配器"（同 webpack loader 的哲学）------ 把任意格式文件统一成 Document(page_content + metadata)；大文件用 lazy_load() 懒加载，长文本用 RecursiveCharacterTextSplitter 切块，PDF 按页切，CSV 按行切，JSON 用 jq 语法精准提取。

markdown 复制代码

   📊 万物格式  →  🔌 Loader  →  📄 Document  →  ✂️ Chunk  →  🗃️ 向量库
        （RAG 的第一公里，数据从此标准化 🛣️）

第六天，从"会聊天"升级到"会喂数据" ✅ 下一站，检索器与向量库 ------ 让 Agent 自己翻资料...... 🌱