LangChain文本读取全指南：加载器、编码与切分

最近在搭一个本地的RAG知识库项目，第一关就卡在了最基础的问题上：怎么把散落在电脑里的一大堆txt、md、CSV文本文件，用LangChain干净地读进来。试了几个小时，踩了不少编码和路径的坑之后，我发现网上讲RAG的数据处理，大部分都直接从切分和向量化开始，很少有人把“读取文本数据”这一步单独拿出来讲透。这篇就把我从LangChain读取文本的完整过程和踩坑记录写下来，给准备入门RAG的朋友做个参考。不管是做知识库问答、文档助手，还是想把现有资料变成模型能用的上下文，这篇文章的实操部分都能直接照抄。

1. RAG入门第一步：先搞懂数据是怎么变成“知识”的

1.1 一条完整的RAG链路长什么样

RAG，检索增强生成，说白了就是给大模型外挂一个“资料库”。模型本身不会凭空知道你硬盘里的项目文档、产品手册或者读书笔记写了什么，RAG要做的就是把这些问题变成可检索的片段，在模型回答之前先把相关内容捞出来，作为上下文塞给模型。完整链路通常长这样：读取原始文档 → 文档切分 → 向量Embedding → 存入向量库 → 用户提问时检索 → 拼接提示词 → 模型生成答案。

大部分教程会直接跳过第一步，默认你已经拿到了一个干净的文本字符串。但真实世界里的数据根本不是这样：文件可能是GBK编码，可能一个文件夹里混着几十种格式，可能CSV用的不是逗号是分号。这些变量全都是在第一步“读取”时暴露出来的。所以我的经验是，RAG入门的第一个项目，一定要把读取这个动作单独拎出来练一遍，不然到了后面向量化、检索阶段，你根本分不清是上游数据的问题还是下游算法的问题。

1.2 源头质量决定知识库上限

很多人试RAG，发现回答效果不好，第一反应是换模型或者调Embedding参数。但我见到的绝大多数案例，问题都出在源头——文本压根没读干净。比如PDF某些页是扫描图，读出来是一堆空白；比如HTML里的导航栏、广告区块没清洗，变成了检索时的巨大噪音；再比如一个文档被切成了几百个碎片，每片都短得没有上下文。

这里有一个核心认知：RAG的上限由“数据输入端”决定，而不是由模型决定。模型再聪明，如果你喂给它的检索结果本身就是残缺的、带噪音的，它也只能基于垃圾往外推理。所以“读取文本数据”看似简单，实际上决定了整个知识库的地基。这也是为什么我反复劝刚接触RAG的朋友，多花点时间把文件读明白：把格式处理干净、把元数据补全、把编码理顺，后面所有事情都会顺手起来。

很多人在聊天时问“rag知识库能存储图片嘛”，其实答案就在读取这一步：RAG本身不直接存储图片，图片需要先通过多模态模型转成文字描述，再作为文本进入后续流程。所以读取环节不仅处理纯文本，还决定了图片等其他介质能不能进你的知识库，这属于另一个大话题，这篇先聚焦文本读取。

2. LangChain加载器：用之前先弄明白这几点

2.1 所有加载器的核心：Document对象

LangChain把“读取文件”这件事抽象成了统一的接口，叫DocumentLoader，也就是文档加载器。你不需要关心这个文件是txt、是CSV、还是JSON，因为所有加载器最后返回的都是同一个东西——Document对象。

Document虽然叫“文档”，但它其实只是两个字段的组合：page_content是正文内容，字符串类型，模型和Embedding真正关心的就是它；metadata是元数据，字典类型，用来记录来源文件名、页码、生成时间这些辅助信息。为什么要区分这两个字段？因为检索以后，你需要能回溯“这段内容到底来自哪份文件”，这就是metadata存在的意义。

加载器的通用用法只有两行代码：

python复制from langchain_community.document_loaders import TextLoader

loader = TextLoader("example.txt")
docs = loader.load()

load()方法会返回一个List[Document]。如果把读取和切分两步连起来做，可以用load_and_split()，它会自动用默认的切分器把文档切成多个片段。我建议新手先单独用load()，亲眼看看返回了哪些内容，再决定怎么切。

2.2 常见加载器分类和适用场景

LangChain社区里文档加载器非常多，我按自己的使用频率给它们分了个类。第一类是通用文本类，包括TextLoader、DirectoryLoader，适合读txt、md、log这类纯文本文件；第二类是表格类，包括CSVLoader和DataFrameLoader，适合读表格数据；第三类是结构化数据类，比如JSONLoader，读取JSON文件时能自定义字段映射规则，灵活性最高。

我用一张表把这几种常用加载器的适用场景做对比，方便你选型：

顺带回应一个被问过很多次的问题：“有没有本地的rag文本拆解工具”。你其实不需要专门找，LangChain的加载器加后面要讲的切分器，组合起来就是这个工具的完整形态。所谓文本拆解工具，核心就是“读取+切分”两步，LangChain全都能做。

3. 实操：从txt到JSON，四种常见文本格式的读取

3.1 TextLoader：最朴素的文本加载器

TextLoader是所有加载器里最基础的一个。在没有特殊需求、只是想把本地文本文件读成Document时，它是最稳妥的选择。基础代码如下：

python复制from langchain_community.document_loaders import TextLoader

loader = TextLoader("guide.md", encoding="utf-8")
docs = loader.load()
print(docs[0].page_content[:500])
print(docs[0].metadata)

这里我加了encoding="utf-8"，指定以UTF-8编码读取文件。这个参数后面专门讲，它在中文环境里几乎必用。读取成功后，你能看到page_content是文件的完整正文，metadata里默认只有source，也就是文件路径。

有一类特殊情况下需要格外注意：如果你的文件本身带有BOM头，或者混合编码，TextLoader直接读会失败。此时可以把autodetect_encoding=True加进去，让LangChain自动探测编码再读取。这个参数是我在Windows和macOS之间交换文件时的救命稻草，建议遇到编码问题第一时间试试。

3.2 DirectoryLoader：批量读取文件夹内容

当你有几十个文件要一起加载时，逐一手写TextLoader就不现实了。这时用DirectoryLoader最为方便。它接收一个目录路径，然后自动扫描文件夹里的所有文件。我的典型用法是这样的：

python复制from langchain_community.document_loaders import DirectoryLoader
from langchain_community.document_loaders import TextLoader

loader = DirectoryLoader(
    path="./docs",
    glob="**/*.md",
    loader_cls=TextLoader,
    loader_kwargs={"encoding": "utf-8"},
    show_progress=True,
)
docs = loader.load()

这里要重点解释几个参数。path是你要扫描的根目录。glob是一个通配符模式，控制扫描哪些文件，"**/*.md"表示递归所有子目录下的所有markdown文件，如果你只想扫当前目录的txt，可以改成"*.txt"。loader_cls指定用哪个加载器来处理命中的文件，loader_kwargs则是给这个加载器传递额外参数，比如编码。

这里有个实操经验：show_progress=True不要省。当你批量处理上千份文件时，它会在终端实时显示进度条，能帮你判断是卡死还是在运行。我第一次没加这个参数，处理三百个PDF时一度以为程序挂了，加了之后才知道只是读得比较慢。

3.3 CSVLoader：表格数据这样读才对

CSV文件在真实项目中太常见了，产品列表、用户反馈、运行日志，到处都有。CSVLoader的作用是把表格里的每一行转成一个Document，所有列拼接成该文档的正文。直接上代码：

python复制from langchain_community.document_loaders.csv_loader import CSVLoader

loader = CSVLoader(file_path="report.csv", source_column="标题", encoding="utf-8")
docs = loader.load()

默认情况下，CSVLoader会把所有列的值用逗号拼起来，比如“张三, 25, 北京”这样，作为page_content。如果你指定了source_column，比如这里指定“标题”列，那每一行文档的metadata里就会带上该行标题列的值，后续追溯来源时非常好用。

CSVLoader最大的坑在于分隔符。很多导出的文件表面叫CSV，实际上是用分号或者Tab分隔的。遇到这种情况，可以在初始化时传一个csv_args参数手动指定：csv_args={"delimiter": ";"}。我踩过这个坑：有一次处理某个银行导出的csv，默认把它按逗号解析，结果每一行整段内容都变成了一个单元格，读出来全是错位的文本。遇到表格内容不对时，先怀疑分隔符，基本不会错。

3.4 JSONLoader：结构化数据的精准提取

JSON文件的结构化程度最高，但也最容易“挑错数据”。如果直接把整个JSON文件塞进TextLoader，那读出来的只是一堆键值对括号，毫无语义价值。更好的做法是用JSONLoader加jq_schema参数去精准提取你要的字段。

python复制from langchain_community.document_loaders import JSONLoader

loader = JSONLoader(
    file_path="data.json",
    jq_schema=".messages[].content",
    text_content=False,
)
docs = loader.load()

这里的jq_schema是jq语法，用来定位JSON里的数组和对象。比如上面这句，意思是从messages数组里取出每个元素的content字段，每个content变成一个Document。这个方案的好处是：只在链条里保留对问答有用的内容，丢弃所有无关元数据。

要运行JSONLoader，需要先安装jq库，在终端执行pip install jq。我遇到过不少朋友在这步卡住，一直报ModuleNotFoundError: jq，就是少了这个系统依赖。另外我个人的建议是，如果JSON过于复杂，可以先在Python里用json库预处理一次，把它压平成一个简单字典，再交给LangChain，这样维护起来心智负担小得多。

4. 编码、路径和中文文本的一些坑

4.1 编码问题：为什么中文文件总报UnicodeDecodeError

新手用LangChain读取文本，遇到最多的报错就是UnicodeDecodeError。这个错误的本质是，文件里的字节序列不符合你指定的解码规则。最典型的情况是：文件是用GBK编码的简体中文（Windows中文系统非常常见），而你用默认的UTF-8去解，结果解到一半遇到无法映射的字节，直接抛异常。

为什么默认是UTF-8？因为这是现代Linux和macOS的标准编码，LangChain的默认值也合理地选了它。但Windows上传上来的老文件，或者某些国产软件导出的文件，仍然是GBK。所以我的处理方法是，先尝试encoding="utf-8"，如果报错，就把autodetect_encoding=True加上，让LangChain自己去识别编码。

python复制loader = TextLoader("legacy.txt", autodetect_encoding=True)
docs = loader.load()

如果autodetect_encoding也没能正确识别，那就手动指定编码。常见的备选方案有encoding="gbk"和encoding="gb18030"，其中gb18030是GBK的超集，兼容性更好。关键是要理解：这些参数不是玄学，而是为每个具体文件的编码准备的。

4.2 glob模式与路径处理

批量加载时，glob参数决定了哪些文件会被扫描。这里有一个容易被忽视的坑：相对路径的基准点是DirectoryLoader传入的path参数。举个例子，path="./docs"，glob="**/*.txt"，那实际扫描的是./docs下所有层级的txt文件。如果你写glob="docs/**/*.txt"，那LangChain会去./docs/docs/下找文件，自然什么都找不到。

还有Windows路径分隔符的问题。Windows用反斜杠\，而glob的通配符通常用正斜杠/。我的建议是，统一用Python的pathlib模块来处理路径，避免手写字符串导致系统不兼容。

python复制from pathlib import Path

base_dir = Path("./docs")
loader = DirectoryLoader(str(base_dir), glob="**/*.md", loader_cls=TextLoader)

用Path对象的好处是它在不同系统间自动处理分隔符差异，而且你可以随时用base_dir / "子目录"来拼接路径，不会出现/和\混乱的问题。

4.3 metadata的补充与清洗

读取阶段很多人只关注page_content，忽略了metadata的价值。其实metadata在RAG应用里非常关键，因为检索之后通常需要告诉用户“这笔内容来自哪份文件”，或者按来源做权限控制。

我用过一个很有效的工程习惯：在批量加载完以后，遍历docs列表，把文件路径、最后修改时间、甚至业务标签注入到metadata里：

python复制for doc in docs:
    doc.metadata["file_type"] = doc.metadata["source"].split(".")[-1]
    doc.metadata["created_date"] = "2025-01-01"

这样在后续检索阶段，你就可以通过metadata过滤高权重文档，或者按类型排除噪音文件。这个习惯花的时间很少，但对知识库质量提升是立竿见影的。

5. 读完不是终点：切分器选择逻辑

5.1 为什么要切分，为什么不能整篇塞进去

读完文件之后，接下来要面对的是切分。很多新手问：“既然我已经读到了完整文档，为什么不直接整篇拿去Embedding？”这里有几个硬性原因。第一，Embedding模型有输入长度上限，常见的是512或1024个token，超长文本会被截断或报错。第二，检索器是以“片段为单位”做相似度匹配的，如果你整个文档作为一个向量，用户问“第三章第二节的注意点在哪里”，模型拿整个文档的向量去匹配，精度会被严重稀释。

打个比方，这就像图书馆里的书，如果不拆开，只给读者一个“整本图书”的索书号，他要找其中一句话，就必须把整本书搬下来。切分的目的就是让检索粒度变细，匹配更精准，同时保留足够的上下文语境。

5.2 两种主流切分器对比和参数选择

LangChain里最常用的切分器是CharacterTextSplitter和RecursiveCharacterTextSplitter。前者只按固定分隔符切分，简单但容易切断语义；后者会先按最粗的分隔符（比如段落）切，发现太长再往下一级（比如句号、逗号、空格）递归地切，切出来的结果更容易保持语义完整性。我直接推荐后者。

用RecursiveCharacterTextSplitter时，核心参数是chunk_size和chunk_overlap。chunk_size大约400到800，中文数据建议400到600每个分片，因为中文字符信息密度高，而且Tokenizer本身会把多字节字符拆成多个token。经验值可以与实际测试结合：打开一个切分后的片段，看它是否语义完整，如果话说到一半就断了，说明chunk_size太小或者分隔符列表不够细致。

python复制from langchain_text_splitters import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,
    chunk_overlap=50,
    separators=["\n\n", "\n", "。", "！", "？", "，"],
)
split_docs = splitter.split_documents(docs)
print(len(split_docs))

chunk_overlap的作用，是让相邻分片之间保留少量重叠文字，避免在切分边界处丢失关键上下文。这个值一般设为chunk_size的10%到20%就够用了。

5.3 中文场景如何配置切分参数

中文文本与英文有个显著差异：英文天然以空格分词，按空格切分不会破坏单词单位；中文没有空格，如果分隔符列表里只有"\n\n"和"\n"，长段的中文文字会一刀切在任意字符之间，把完整的句子锯成两段。所以中文场景下，分隔符列表一定要把句号、问号、感叹号和逗号都包含进去，让切分器优先在句子边界切。

我自己的经验配置是：先按双换行（段落）切，还是太长就按单换行切，再不行就按句号问号感叹号切，最后才按逗号。这个优先级顺序保证切分结果尽量保持语义完整。另外语言还能通过一个实用小技巧验证——把切好的分片打出来扫一眼，如果连续几个分片开头都是“的”、“了”、“所以”，那就说明切得太碎了，该调大chunk_size或调整分隔符顺序。

6. 问题排查：读取阶段最常见的报错和解法

6.1 六个高频报错速查表

以下是我实测里遇到频率最高的六个问题，整理成一张速查表，建议收藏：

6.2 三条优化建议

第一，读取之后先打印len(docs)和首尾片段，确认加载数量和内容都与预期一致。这一步只要十几秒，却能拦住绝大部分后续的检索故障。第二，定期把metadata里的source字段标准化，统一用相对路径，方便以后在向量库迁移、权限控制时能追踪来源。第三，遇到零散格式的文本时，不要迷信单一加载器，先预处理、清洗再加载，比如HTML可以用BeautifulSoup把正文抽出来，PDF先探测是否可复制文字，这些都是LangChain加载器解决不了的领域，得自己动手。

我个人在实际操作中有个体会：读取文本数据这一步，做得越透彻，后面构建的知识库就越扎实。很多人以为LangChain入门就是调一个貌似高端的流程，实际上真正决定知识库能用多久的，恰恰是那些看起来不炫技的读文件细节。把编码、路径、元数据、切分这会事理顺了，RAG的整个链路就已经成功了一大半。下一步再接入Embedding和向量库，你手上的数据就已经是干净、可检索、有来源的状态了。