1. RAG 数据导入的第一公里为什么文本解析决定了整个系统的上限做过 RAG 的人都有一个共识检索效果不好十有八九不是模型的问题而是数据没处理好。我见过太多团队花大价钱调 embedding 模型、换向量数据库、优化 rerank 策略结果回头一看原始文档里全是乱码、断行、页眉页脚混在一起再好的模型也救不回来。这个项目要解决的问题很具体把各种格式的原始文本txt、Markdown、结构化文档干净地导入到 RAG 知识库中。听起来简单但实际操作中txt 的编码问题、Markdown 的层级解析、表格和代码块的处理每一个都是坑。适合谁看如果你正在搭建 RAG 知识库或者手头有一堆文档要喂给大模型这篇内容能帮你少走至少两周弯路。先说一个基本判断RAG 的数据导入不是“读文件”这么简单它本质上是一个信息保真与结构重建的过程。你从磁盘上读到的字节流和最终存进向量库的 chunk中间要经过编码识别、格式解析、语义分块、元数据标注四个环节。任何一个环节出问题检索质量都会断崖式下跌。我个人的经验是一个 RAG 项目的成败60% 取决于数据导入和解析阶段。剩下的 40% 才是检索策略和生成模型的选择。所以这个系列的第一篇我们先把最基础但也最容易被忽视的 txt 和 Markdown 解析讲透。2. 整体设计思路从字节流到语义块的完整链路2.1 为什么不能直接读文件就完事很多人第一次做 RAG 的时候代码大概长这样open(file.txt).read()然后按固定字数切一刀扔进向量库。跑起来确实能用但你会发现检索出来的内容经常是半句话或者把不相关的段落混在一起。问题出在文本的物理结构和逻辑结构是两回事。一个 txt 文件在磁盘上就是一串字节但它在语义上有段落、有章节、有列表、有代码块。如果你按固定字符数切分等于把一篇文章随机剪碎检索时自然找不到完整语义。所以整体设计要解决三个核心问题编码识别txt 文件可能是 UTF-8、GBK、GB2312、UTF-16甚至是混合编码。读错了就是乱码后续全废。结构解析Markdown 有标题层级、代码块、表格、列表这些结构信息必须保留因为它们代表了语义边界。语义分块切分要尽量在段落边界、标题边界进行保证每个 chunk 是一个完整的语义单元。2.2 解析链路的分层设计我把整个导入流程分成四层每一层各司其职层级职责关键输出读取层识别编码、读取原始字节统一 UTF-8 字符串解析层识别文档结构、提取层级结构化文档树分块层按语义边界切分chunk 列表标注层附加元数据带 metadata 的 chunk这个分层的好处是每一层可以独立替换和测试。比如你发现编码识别有问题只需要改读取层不用动后面的逻辑。解析层换成别的解析器分块策略也不用重写。2.3 为什么选择 Markdown 作为中间格式这里有个关键决策把各种格式统一转换成 Markdown再做后续处理。原因有三点。第一Markdown 是纯文本没有二进制包袱处理起来简单可靠。第二Markdown 天然携带结构信息#表示标题层级 表示代码块|表示表格这些符号可以直接映射成语义边界。第三Markdown 的生态成熟几乎所有编程语言都有现成的解析库。你可能会问为什么不直接转成 HTML 或者 JSONHTML 太啰嗦标签噪音大JSON 虽然结构化好但丢失了人类可读性调试起来麻烦。Markdown 在结构性和可读性之间取得了很好的平衡。注意统一中间格式的前提是你的原始文档能无损转换。如果原始文档里有复杂的嵌套表格或特殊排版转 Markdown 可能会丢信息这时候需要保留原始格式的解析路径。3. txt 文件解析编码识别与清洗的实操细节3.1 编码识别别再用 chardet 一把梭了txt 文件最大的坑就是编码。中文环境下常见的有 UTF-8、GBK、GB2312、GB18030还有 Windows 下常见的 UTF-8 with BOM。很多教程推荐用chardet库自动检测但实测下来chardet 对短文本的检测准确率堪忧尤其是几百字以内的文件经常把 GBK 误判成 UTF-8。我的做法是优先尝试 UTF-8失败后按优先级回退。具体逻辑如下def read_text_file(file_path): encodings [utf-8-sig, utf-8, gb18030, gbk, big5] for enc in encodings: try: with open(file_path, r, encodingenc) as f: content f.read() # 简单校验如果出现大量替换字符说明编码不对 if content.count(\ufffd) / max(len(content), 1) 0.01: return content, enc except (UnicodeDecodeError, LookupError): continue # 全部失败用二进制读取后强制解码 with open(file_path, rb) as f: raw f.read() return raw.decode(utf-8, errorsreplace), utf-8-replace这里有几个细节值得说。utf-8-sig要放在最前面因为它能自动处理 BOM 头而普通utf-8会把 BOM 当成一个可见字符导致第一个 chunk 开头多一个奇怪的符号。gb18030是 GBK 的超集优先于gbk尝试覆盖面更广。那个替换字符比例校验也很关键。有些文件用 UTF-8 能解码成功但实际上是别的编码解出来全是乱码。\ufffd是 Unicode 的替换字符如果它占比超过 1%基本可以判定编码选错了。3.2 文本清洗哪些该删哪些必须留编码问题解决后下一步是清洗。但清洗有个原则只删无意义的噪音不删可能携带语义的内容。必须删的连续的空行超过两个的合并成一个行尾的空白字符零宽字符\u200b、\ufeff等谨慎处理的页眉页脚如果是 PDF 转来的 txt每页都有重复的页眉需要识别并删除。但如果文档本身有章节标题重复出现就不能一刀切。特殊符号像★、◆这类符号可能是列表标记删了会丢失结构信息。我一般会保留一个原始副本清洗后的文本另存方便对比排查。清洗规则用配置文件管理不同来源的文档用不同规则不要写死在代码里。3.3 段落识别换行不等于段落txt 文件里换行符\n有两种含义一种是段落结束一种是行内换行比如从 PDF 复制过来的文本每行都很短。如果不加区分按\n切分会导致 chunk 碎得没法看。判断逻辑是这样的如果一行以句号、问号、感叹号、冒号结尾且下一行开头不是空格或特殊符号那么这是一个段落边界。如果一行很短比如少于 20 个字符且下一行紧接着那很可能是行内换行应该合并。import re def merge_lines(text): lines text.split(\n) merged [] buffer for line in lines: stripped line.strip() if not stripped: if buffer: merged.append(buffer) buffer continue if buffer and not re.search(r[。]$, buffer): buffer stripped else: if buffer: merged.append(buffer) buffer stripped if buffer: merged.append(buffer) return \n\n.join(merged)这段代码的核心思路是用标点符号判断句子是否结束没结束就继续拼接。实测下来对中文文档效果很好能把 PDF 复制出来的碎行重新拼成完整段落。4. Markdown 解析把结构信息变成检索优势4.1 标题层级天然的语义分块边界Markdown 最大的价值在于它的标题层级。#是一级标题##是二级###是三级。这些标题天然就是语义边界按标题切分 chunk比按字数切分合理得多。我的分块策略是这样的以二级标题##为主要切分点如果某个二级标题下的内容超过 800 字再按三级标题###细分。如果三级标题下还是太长才按段落切分。这样保证每个 chunk 既不会太碎也不会太长。import re def parse_markdown_structure(md_text): lines md_text.split(\n) sections [] current {level: 0, title: root, content: []} for line in lines: match re.match(r^(#{1,6})\s(.*), line) if match: if current[content]: sections.append(current) level len(match.group(1)) current {level: level, title: match.group(2).strip(), content: []} else: current[content].append(line) if current[content]: sections.append(current) return sections这个解析器把 Markdown 拆成一个个 section每个 section 带有层级和标题。后续分块时可以把父级标题作为 metadata 附加到子 chunk 上检索时就能知道这个 chunk 属于哪个章节。4.2 代码块和表格不能按普通文本处理Markdown 里的代码块 包裹的内容和表格|分隔的行有特殊语义。代码块里的换行不能当段落边界表格的行也不能随便拆。处理代码块时我建议整个代码块作为一个独立的 chunk不要拆分。因为代码的上下文依赖很强拆开就失去意义了。如果代码块特别长超过 2000 字可以在函数边界处切分但这需要语言相关的解析器复杂度较高。表格的处理更微妙。一个表格如果被拆成多个 chunk检索时只能看到部分行列头信息也丢了。我的做法是把表格转成自然语言描述比如| 模型 | 参数量 | 上下文长度 | |------|--------|------------| | A | 7B | 4096 | | B | 13B | 8192 |转换成模型对比表模型 A 参数量 7B上下文长度 4096模型 B 参数量 13B上下文长度 8192。这样检索时即使用户搜“上下文长度 8192 的模型”也能命中这个 chunk。4.3 数学公式与特殊语法Markdown 里的数学公式$...$和$$...$$在 RAG 里是个麻烦。向量模型对公式的语义理解很弱直接嵌入效果不好。我的建议是把公式转成文字描述或者至少保留公式的 LaTeX 源码同时在旁边加一句自然语言解释。比如$E mc^2$可以处理成“质能方程 E 等于 m 乘以 c 的平方”。这样检索“质能方程”时能命中检索“Emc2”时也能命中。提示如果你的知识库里有大量数学内容建议单独建一个公式索引用专门的数学 embedding 模型处理不要和普通文本混在一起。5. 语义分块策略chunk 大小与重叠的取舍5.1 chunk 大小没有万能值但有判断标准chunk 大小是 RAG 里被讨论最多的话题之一。有人说 512 token 最好有人说 1024还有人说按段落就行。我的经验是chunk 大小取决于你的检索粒度和文档类型。判断标准有三条检索粒度如果你希望检索到具体的操作步骤chunk 要小300-500 字如果希望检索到完整的概念解释chunk 要大800-1200 字。文档类型技术文档适合小 chunk因为内容密度高叙述性文档适合大 chunk因为需要上下文才能理解。模型上下文chunk 大小加上 prompt 和其他上下文不能超过模型的上下文窗口。一般留 30% 余量。我通常的做法是设置一个基准值比如 600 字然后根据实际检索效果调整。调整时不要凭感觉要准备一组测试问题看不同 chunk 大小下的召回率和准确率。5.2 重叠窗口为什么需要需要多少chunk 之间设置重叠是为了防止语义在边界处被切断。比如一个概念的解释跨了两个 chunk如果没有重叠检索时可能只命中一半。重叠大小一般是 chunk 大小的 10%-20%。600 字的 chunk重叠 60-120 字比较合适。重叠太多会导致冗余检索结果重复重叠太少又起不到保护作用。实现重叠有个技巧不要按字符数硬切而是按句子边界切。比如 chunk 大小是 600 字找到第 600 字附近最近的句号在那里切分然后从上一个 chunk 的最后一个句子开始下一个 chunk。这样重叠的是完整句子语义更连贯。5.3 元数据标注让检索更精准每个 chunk 除了文本内容还应该附带元数据。常用的元数据包括source来源文件路径title所属章节标题level标题层级position在文档中的位置第几个 chunktype内容类型正文、代码、表格、列表这些元数据在检索时可以用来过滤。比如用户问“第三章讲了什么”你可以只检索title包含“第三章”的 chunk。或者用户问“代码示例”你可以只检索typecode的 chunk。元数据的另一个用途是溯源。检索到内容后可以告诉用户这段话来自哪个文件的哪个章节增加可信度。6. 常见问题与排查技巧实录6.1 乱码问题速查表现象可能原因解决方法中文显示为方块编码识别错误尝试 gb18030 或 gbk开头有奇怪字符BOM 头未处理使用 utf-8-sig 编码部分字符乱码混合编码分段检测编码逐段解码全部是问号二进制文件误读检查文件类型排除非文本文件换行符异常不同系统换行符差异统一替换 \r\n 和 \r 为 \n6.2 Markdown 解析的坑坑一嵌套列表的层级丢失。Markdown 的嵌套列表用缩进表示但缩进可能是 2 空格、4 空格或 Tab。解析时要统一处理否则层级会乱。**坑二代码块里的冲突**。如果代码内容本身包含会提前结束代码块。解决办法是用更长的反引号包裹比如 或者用缩进式代码块。坑三表格对齐行。Markdown 表格的第二行是|---|---|这样的对齐标记解析时要跳过不能当成数据行。6.3 分块效果的验证方法分块做完后怎么知道效果好不好我一般用三个方法验证第一随机抽样检查。随机抽 20 个 chunk人工看是否语义完整、有没有被切断。第二检索测试。准备 10-20 个典型问题看检索结果是否命中正确的 chunk。第三边界检查。专门检查标题切换处、代码块前后的 chunk这些地方最容易出问题。如果发现某个 chunk 明显不完整不要急着调参数先看看是不是解析阶段就出了问题。很多时候分块效果差是因为上游的解析没做好。6.4 性能优化的小技巧处理大量文件时性能是个问题。几个实用的优化点批量读取不要一个文件一个文件处理用多进程或异步 IO 批量读取。缓存解析结果解析后的结构化数据存成 JSON下次直接读不用重新解析。增量更新只处理新增或修改的文件用文件哈希判断是否变化。流式处理大文件不要一次性读入内存用生成器逐行处理。我在实际项目里用多进程加缓存的方式把 10 万份文档的处理时间从 8 小时压缩到了 40 分钟。关键就是避免重复解析和重复计算。7. 从解析到入库完整流程的串联7.1 目录扫描与文件分类实际项目中文档通常放在一个目录树里。第一步是扫描目录按扩展名分类。.txt走 txt 解析路径.md走 Markdown 解析路径其他格式PDF、Word先转换成 Markdown 再处理。扫描时要注意排除隐藏文件和临时文件比如.DS_Store、~$开头的文件。还要处理符号链接避免循环扫描。7.2 解析结果的统一数据结构不管什么格式解析后都统一成同一个数据结构{ doc_id: 唯一标识, source: 原始文件路径, format: txt 或 markdown, encoding: 识别出的编码, sections: [ { title: 章节标题, level: 2, content: 章节内容, chunks: [ { text: chunk 文本, metadata: {...} } ] } ] }这个结构的好处是格式无关。后续的分块、嵌入、入库逻辑不用关心原始格式只操作这个统一结构。7.3 入库前的最后检查入库前有几个检查点不能跳过空 chunk 检查删除内容为空的 chunk它们会污染检索结果。重复 chunk 检查完全相同的 chunk 只保留一个减少存储和检索开销。长度检查过短的 chunk少于 50 字合并到相邻 chunk过长的 chunk超过 2000 字再切分。编码检查确保所有文本都是有效的 UTF-8没有替换字符。这些检查看起来琐碎但能避免很多后续问题。我见过因为一个空 chunk 导致整个检索结果异常的案例排查了半天才发现是数据问题。7.4 一个完整的处理示例假设有一个docs/目录里面有 txt 和 Markdown 文件。完整处理流程如下import os from pathlib import Path def process_directory(root_dir): results [] for path in Path(root_dir).rglob(*): if path.is_dir() or path.name.startswith(.): continue if path.suffix .txt: content, enc read_text_file(path) content merge_lines(content) sections [{title: path.stem, level: 1, content: content}] elif path.suffix .md: content, enc read_text_file(path) sections parse_markdown_structure(content) else: continue chunks [] for sec in sections: chunks.extend(split_section(sec)) results.append({ source: str(path), format: path.suffix, encoding: enc, chunks: chunks }) return results这个流程跑完你就得到了一份干净的、结构化的、可以直接入库的数据。后续的嵌入和检索都建立在这个基础之上。8. 一些踩坑后的个人体会做 RAG 数据导入这两年最大的体会是不要相信任何“自动”工具。自动编码检测、自动分块、自动清洗听起来省事实际上每个都需要人工校验和调优。数据质量这件事没有捷径。另一个体会是保留原始数据。清洗和解析过程中一定要保留原始文件的副本。有时候调优检索效果需要回头看看原始数据长什么样对比解析后的结果才能找到问题所在。还有就是分块策略要跟着业务走。技术文档和客服问答的分块逻辑完全不同不要指望一套参数打天下。多准备几组测试数据用实际效果说话。最后说一个容易被忽视的点文档的更新和维护。知识库不是建一次就完事文档会更新、会新增。设计导入流程时要考虑增量更新的能力用文件哈希或修改时间判断哪些文件需要重新处理。否则每次全量重建时间和计算成本都受不了。这个系列接下来会讲 PDF、Word、HTML 等格式的解析以及嵌入模型的选择和向量库的调优。数据导入这第一公里走稳了后面的路才好走。