1. 为什么 RAG 的第一步不是模型而是数据导入很多人一上来就盯着向量库选型、Embedding 模型对比、重排序策略调参结果跑出来的效果一塌糊涂回头一查问题根本不在检索环节而是喂进去的数据本身就是一锅粥。我见过太多团队在 RAG 项目上翻车八成以上的根因都指向同一个地方数据导入与解析这一层没做扎实。RAG也就是检索增强生成它的核心逻辑说白了就三步把外部知识切好、存好、查好然后交给大模型去组织答案。这三步里后面两步的优化空间其实是有天花板的但第一步的数据质量直接决定了整个系统的上限。你喂进去的是乱码、是断句错乱的段落、是丢失了标题层级的纯文本那检索出来的东西再精准也是垃圾进垃圾出。这一篇我聚焦在通用文本与结构化数据的导入和解析上具体覆盖从最朴素的 txt 文件到带层级结构的 Markdown 文档的处理链路。为什么先讲这两类因为它们是 RAG 数据源里最基础、最高频、也最容易被低估的格式。你把手头的 txt 和 Markdown 吃透了后面再去处理 PDF、Word、HTML 这些复杂格式思路是一脉相承的。这篇文章适合谁看如果你正在搭建自己的 RAG 知识库或者你手头有一堆文档想导入到某个智能问答系统里又或者你单纯想搞清楚“为什么我的 RAG 效果不好”那这篇内容应该能帮你省下不少试错时间。我会从整体设计思路讲起然后拆解 txt 和 Markdown 各自的解析要点接着给出可直接复现的实操流程最后把我踩过的坑和排查经验整理出来。2. 数据导入与解析的整体设计思路2.1 先搞清楚你的数据到底长什么样在动手写任何解析代码之前我强烈建议你先做一件事把手头所有待导入的文件列一个清单按格式分类然后每种格式随机抽三到五个文件打开看看。这一步听起来很废话但我保证你会发现很多意想不到的情况。比如你以为都是纯 txt结果里面混着 GBK 编码的、混着带 BOM 头的、混着用全角空格做缩进的、混着从某个老系统导出来的带特殊分隔符的。我自己的习惯是建一个简单的表格来管理这个清单大致长这样文件格式数量编码情况是否有层级结构特殊问题txt纯文本320UTF-8 为主少量 GBK无部分文件用空行分段部分用全角空格txt日志导出85UTF-8无时间戳前缀需要剥离Markdown140UTF-8有标题层级不统一有的从 H1 开始有的从 H2Markdown带公式30UTF-8有数学公式需要特殊处理这张表看起来简单但它能帮你快速判断哪些文件可以批量统一处理哪些需要单独写规则。不要一上来就写一个“万能解析器”那是给自己挖坑。先分类再针对每类写最小可用的处理逻辑跑通了再合并。2.2 解析的目标不是“读出来”而是“切得好”很多人对解析的理解停留在“能把文件内容读成字符串”这个层面但对于 RAG 来说这只是起点。真正重要的是读出来的内容能不能被切成语义完整的块。举个具体的例子。假设你有一个 txt 文件内容是某个产品的使用手册里面用空行分隔了不同章节。如果你只是简单按固定字符数切分比如每 500 个字符切一刀那很可能把一个完整的操作步骤拦腰截断前半段在块 A后半段在块 B。检索的时候用户问“怎么重置设备”系统可能只召回了前半段大模型拿到的上下文是不完整的回答自然也是残缺的。所以解析阶段的核心任务是两件事第一尽可能保留原文的结构信息标题、段落、列表、代码块等第二基于这些结构信息做语义感知的切分而不是机械地按长度切。这就是为什么 Markdown 比纯 txt 更好处理——Markdown 本身就带层级标记你天然就知道哪里是标题、哪里是正文、哪里是列表。2.3 为什么选择“先统一转 Markdown”这条路线在实际项目中我倾向于把各种格式的文本先统一转换成 Markdown然后再做切分和向量化。这个选择背后有几个考量。第一Markdown 的表达能力足够覆盖绝大多数文档结构。标题、段落、列表、表格、代码块、引用这些元素在技术文档、产品手册、教程类内容里几乎全覆盖了。第二Markdown 是纯文本处理起来没有二进制格式的那些坑编码问题也相对好解决。第三Markdown 的语法标记本身就是很好的切分信号——#开头的行是标题连续的非空行是段落-或1.开头的是列表项这些都可以直接用来指导切分策略。当然这条路线也有代价。比如 PDF 里的复杂表格、图片里的文字、扫描件的 OCR 结果转成 Markdown 会丢失一些信息。但对于 txt 和原生 Markdown 来说这个转换几乎是无损的甚至对 txt 来说是一种“结构化增强”——你通过解析规则给原本没有结构的纯文本加上了结构。3. txt 文件解析的核心细节与实操要点3.1 编码问题第一步就能卡住你txt 文件最大的坑就是编码。你以为都是 UTF-8实际上国内很多老系统导出的 txt 是 GBK 或 GB2312还有一些是带 BOM 的 UTF-8。如果你用默认的 UTF-8 去读 GBK 文件轻则乱码重则直接抛异常。我的处理策略是这样的先尝试用 UTF-8 读取如果失败或者读出来的内容里出现大量替换字符比如\ufffd就切换到 GBK 再试。更稳妥的做法是用chardet这类库先探测编码但探测也不是百分百准确尤其是短文件。所以最终我采用的是“探测 尝试 校验”的三段式策略。import chardet def detect_encoding(file_path): with open(file_path, rb) as f: raw f.read(10000) # 读前 10KB 做探测 result chardet.detect(raw) return result[encoding], result[confidence] def read_txt_safely(file_path): encoding, confidence detect_encoding(file_path) # 置信度低于 0.7 时按优先级依次尝试 candidates [encoding, utf-8, gbk, gb2312, latin-1] for enc in candidates: if enc is None: continue 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 # 兜底用 latin-1 强制读取保证不抛异常 with open(file_path, r, encodinglatin-1) as f: return f.read(), latin-1这段代码里有个细节值得说为什么最后用 latin-1 兜底因为 latin-1 能映射所有字节值不会抛异常虽然读出来的可能是乱码但至少不会让整个流程崩掉。你可以在后续步骤里标记这个文件“编码异常”人工介入处理。注意不要用errorsignore来静默跳过解码错误那样会悄悄丢掉内容后面排查起来非常痛苦。宁可让它报错也不要丢数据。3.2 段落识别空行不是唯一信号纯 txt 没有 Markdown 那样的显式结构标记所以你需要从排版习惯里推断结构。最常见的段落分隔信号是空行但实际情况往往更复杂。我遇到过几种典型的 txt 排版风格第一种是标准空行分段两个段落之间有一个或多个空行。这种最好处理直接按空行切分即可。第二种是用全角空格或制表符做首行缩进段落之间没有空行。这种就需要用正则来识别“以缩进开头的行”作为新段落的起点。第三种是每行都很短像是从某个系统里导出来的每行可能是一个独立的记录。这种就不能按段落切了得按行切然后根据内容判断是否需要合并。我的做法是先统计文件里的空行比例和行长度分布然后根据这些特征选择切分策略。具体来说import re def analyze_txt_structure(content): lines content.split(\n) total_lines len(lines) empty_lines sum(1 for line in lines if line.strip() ) avg_line_length sum(len(line) for line in lines) / max(total_lines, 1) # 判断排版风格 if empty_lines / max(total_lines, 1) 0.15: return blank_line_separated # 空行分段 elif avg_line_length 40: return short_line # 短行可能是记录式 else: return indent_separated # 缩进分段对于blank_line_separated风格直接按连续空行切分。对于indent_separated用正则^\s{2,}或^\u3000来识别新段落。对于short_line先按行切然后看相邻行是否语义连续比如上一行末尾没有句号、下一行开头是小写字母等决定是否合并。3.3 从纯文本到 Markdown 的转换规则把 txt 转成 Markdown 的核心目的是给纯文本加上结构标记方便后续切分。转换规则不需要太复杂抓住几个关键点就够了。标题识别是最重要的一环。纯 txt 里的标题通常有这些特征单独占一行、长度较短、可能带有编号如“第一章”、“1.1”、“一、”、前后有空行。我用的正则大致是这样的def detect_heading(line): line line.strip() if not line or len(line) 60: return None # 匹配常见标题模式 patterns [ (r^第[一二三四五六七八九十百千][章节部分], 2), # 第X章 (r^[一二三四五六七八九十]、, 2), # 一、 (r^\d\.\d\s, 3), # 1.1 (r^\d\.\s, 2), # 1. (r^[(]\d[)], 3), # (1) ] for pattern, level in patterns: if re.match(pattern, line): return level return None识别到标题后在行首加上对应数量的#即可。列表项的识别类似以-、*、·、•开头的行可以统一转成 Markdown 的-列表。代码块的处理稍微麻烦一点纯 txt 里代码通常靠缩进或分隔线来标识如果原文没有明确标记我一般不做代码块转换避免误判。实操心得转换规则不要追求一步到位。先写一个基础版本跑一批文件看看效果然后针对误判的 case 逐步调整正则。我前后迭代了五六版才把标题识别的准确率做到可接受的水平。4. Markdown 文件解析的核心细节与实操要点4.1 标题层级切分的第一信号Markdown 的标题层级是天然的切分边界。一个 H2 标题下面的内容通常是一个完整的主题段落适合作为一个独立的检索单元。但这里有个常见问题不同来源的 Markdown 文件标题层级的起点不一样。有的文件从 H1 开始有的直接从 H2 开始还有的混用 H1 和 H2 表示同一层级。我的处理方式是先扫描整个文件的标题层级分布然后做归一化。具体来说找到文件里出现的最高层级标题数字最小的那个把它映射为 H1其余依次上移。这样保证不同文件的层级结构是一致的。import re def normalize_headings(content): lines content.split(\n) heading_levels [] for line in lines: match re.match(r^(#{1,6})\s, line) if match: heading_levels.append(len(match.group(1))) if not heading_levels: return content min_level min(heading_levels) if min_level 1: return content # 将所有标题层级上移 offset min_level - 1 normalized_lines [] for line in lines: match re.match(r^(#{1,6})\s(.*), line) if match: new_level max(1, len(match.group(1)) - offset) normalized_lines.append(# * new_level match.group(2)) else: normalized_lines.append(line) return \n.join(normalized_lines)4.2 代码块与公式不能按普通文本处理Markdown 里的代码块用 包裹的内容和数学公式用$或$$包裹的内容需要特殊对待。代码块里的换行、缩进、特殊字符都是有意义的如果你在切分时把代码块从中间截断那这段代码就废了。我的策略是在切分前先标记出所有代码块和公式块的位置切分时确保这些块不被切断。如果某个代码块本身就很长超过切分阈值那就把它单独作为一个块不做进一步切分。def extract_protected_blocks(content): 提取代码块和公式块的位置范围 protected [] # 匹配 包裹的代码块 for match in re.finditer(r[\s\S]*?, content): protected.append((match.start(), match.end(), code)) # 匹配 $$ 包裹的公式块 for match in re.finditer(r\$\$[\s\S]*?\$\$, content): protected.append((match.start(), match.end(), formula)) return sorted(protected, keylambda x: x[0])有了这些位置信息切分的时候就可以判断当前切分点是否落在某个保护块内部如果是就把切分点移到块的外面。4.3 表格处理转成自然语言还是保留原格式Markdown 表格在 RAG 里是个棘手的东西。表格的结构化信息很强但向量化的时候如果把整个表格当成一段文本来处理检索效果往往不好。因为表格里的单元格内容是碎片化的语义不连贯。我试过两种方案。第一种是保留表格原格式直接把 Markdown 表格文本作为一个块。第二种是把表格转成自然语言的描述比如“产品 A 的价格是 100 元库存是 50 件”。实测下来第二种方案在问答场景下的检索准确率更高但转换过程需要针对表格的语义做定制不是通用的。对于通用场景我的建议是如果表格不大行数少于 10 行保留原格式如果表格很大考虑按行拆分成多个块每个块包含表头和一行的数据。这样既保留了结构信息又避免了单个块过大。5. 完整实操流程从原始文件到可检索的数据块5.1 整体流程概览把前面讲的各个环节串起来一个完整的处理流程大致是这样的扫描输入目录收集所有 txt 和 Markdown 文件对每个文件进行编码检测和读取如果是 txt执行结构分析和 Markdown 转换如果是 Markdown执行标题层级归一化提取保护块代码块、公式块的位置基于标题层级和段落边界进行语义切分对每个切分块进行清洗和元数据标注输出结构化的 JSON 或 JSONL 文件供后续向量化使用这个流程看起来步骤不少但每一步的逻辑都是独立的可以单独调试和优化。5.2 语义切分的具体实现切分是整个流程里最核心的一步。我的切分策略是“标题优先段落次之长度为兜底”。具体来说首先按标题层级切分每个标题及其下属内容作为一个候选块。如果某个标题下的内容太长超过设定的最大长度就进一步按段落切分。如果段落还是太长就按句子切分。如果句子也超长比如那种没有标点的长文本才按固定长度硬切。def semantic_chunk(content, max_chunk_size800, min_chunk_size100): 基于 Markdown 结构的语义切分 # 先按标题切分 sections split_by_headings(content) chunks [] for section in sections: if len(section[content]) max_chunk_size: if len(section[content]) min_chunk_size: chunks.append(section) else: # 太短的块尝试与相邻块合并 if chunks and len(chunks[-1][content]) len(section[content]) max_chunk_size: chunks[-1][content] \n\n section[content] else: chunks.append(section) else: # 按段落进一步切分 sub_chunks split_by_paragraphs(section, max_chunk_size) chunks.extend(sub_chunks) return chunks这里有几个参数需要根据实际情况调整。max_chunk_size我一般设在 500 到 1000 个字符之间具体取决于你的 Embedding 模型的最大输入长度和检索粒度需求。min_chunk_size是为了避免产生太多碎片化的短块一般设在 100 到 200 字符。注意切分长度不是越短越好。太短的块会丢失上下文检索时可能召回一堆不相关的碎片。太长的块则会稀释语义焦点导致检索精度下降。我的经验是对于技术文档类内容600 到 800 字符是一个比较舒服的区间。5.3 元数据标注让每个块都能被追溯每个切分出来的块除了文本内容本身还需要附带一些元数据。这些元数据在后续的检索和排序环节会发挥重要作用。我通常会给每个块标注这些字段字段名说明示例source_file来源文件路径docs/product_manual.txtchunk_index在文件中的序号12heading_path所属标题层级路径第三章 3.2 设备重置content_type内容类型paragraph / code / table / listchar_count字符数623has_code是否包含代码块trueheading_path这个字段特别有用。当用户提问时如果检索到的块带有明确的标题路径大模型就能更好地理解这段内容的上下文位置生成的回答也更有条理。5.4 输出格式与后续对接处理完的块我一般输出成 JSONL 格式每行一个 JSON 对象。这种格式的好处是流式处理方便而且可以直接被大多数向量数据库的导入工具识别。{id: doc001_chunk012, content: 设备重置的具体步骤如下..., metadata: {source_file: docs/product_manual.txt, chunk_index: 12, heading_path: 第三章 3.2 设备重置, content_type: paragraph, char_count: 623}}输出之后下一步就是调用 Embedding 模型把content转成向量然后连同 metadata 一起存入向量数据库。这部分内容涉及到 Embedding 模型选型和向量库操作我打算放在这个系列的第二篇里展开讲。6. 常见问题与排查技巧实录6.1 编码乱码问题速查现象可能原因解决方法中文显示为乱码文件是 GBK 编码用 UTF-8 读取用 chardet 检测后切换编码开头出现\ufeffUTF-8 BOM 头读取时用utf-8-sig编码部分字符显示为\ufffd编码不兼容或文件损坏尝试其他编码或标记文件异常全文都是问号编码完全错误用 latin-1 读取后人工检查6.2 切分效果不好的排查思路如果你发现检索效果不理想先别急着换模型按这个顺序排查切分环节第一步随机抽几个检索结果看看召回的块内容是否完整。如果块的内容明显被截断说明切分粒度有问题。第二步检查块的标题路径是否正确。如果标题识别错误会导致块被归到错误的章节下检索时自然匹配不上。第三步看看是否有大量超短块少于 50 字符。这些块往往是噪音会干扰检索排序。第四步检查代码块和表格是否被正确保护。如果代码块被从中间切断那这个块基本就废了。6.3 我踩过的几个坑第一个坑过度依赖固定长度切分。刚开始图省事直接按 500 字符切结果大量语义完整的段落被切断。后来改成基于标题和段落的语义切分检索准确率明显提升。第二个坑忽略了 Markdown 的嵌套结构。有些 Markdown 文件里列表项下面还有子列表子列表下面还有代码块。如果只按标题切分这些嵌套结构会被打乱。后来我在切分时增加了对列表层级的处理确保嵌套内容不被拆散。第三个坑元数据丢失。早期版本我只输出了文本内容没有保留来源文件和标题路径。结果检索到问题答案后无法追溯原文也没法给用户展示引用来源。后来补上了元数据整个系统的可信度提升了一个档次。第四个坑没有处理空文件和超短文件。有些 txt 文件只有几行内容或者干脆是空的。这些文件如果不过滤会产生大量无意义的块。现在的做法是文件内容少于 50 字符的直接跳过并在日志里记录。6.4 性能优化的小技巧当文件数量达到几千个的时候处理速度会成为瓶颈。我做了几个优化一是用多进程并行处理文件每个进程独立处理一个文件互不干扰二是把编码检测的结果缓存起来同一个目录下的文件往往编码一致不需要每个都重新探测三是切分后的块先攒在内存里达到一定数量再批量写入磁盘减少 IO 次数。from multiprocessing import Pool def process_file(file_path): # 单个文件的完整处理流程 content, encoding read_txt_safely(file_path) # ... 后续处理 return chunks def batch_process(file_paths, workers4): with Pool(workers) as pool: results pool.map(process_file, file_paths) # 合并结果 all_chunks [] for chunks in results: all_chunks.extend(chunks) return all_chunks这套流程跑下来一千个左右的 txt 和 Markdown 文件从读取到输出结构化块大概需要两三分钟具体取决于文件大小和机器性能。7. 一些关于数据质量的个人体会做 RAG 项目这段时间我最大的感受是数据导入和解析这件事投入产出比远比想象中高。你可能花两天时间优化切分策略效果提升比换一个更贵的 Embedding 模型还明显。而且这部分工作是可控的、可解释的出了问题能定位到具体哪个环节。另外一点体会是不要追求一步到位。我见过有人想写一个“万能解析器”处理所有格式结果代码复杂度爆炸维护成本极高。更好的做法是分阶段推进先把 txt 和 Markdown 这类简单格式跑通验证整个链路没问题再逐步加入 PDF、HTML 等复杂格式。每加入一种新格式只需要扩展对应的解析模块核心的切分和输出逻辑可以复用。还有一个容易被忽略的点是数据清洗。原始文件里往往夹杂着页眉页脚、广告文本、无关的导航信息。这些内容如果不清理会污染检索结果。我的做法是在解析阶段加一个简单的规则过滤比如过滤掉重复出现的短行、过滤掉包含特定关键词的行如“版权所有”、“点击这里”等。规则不需要太复杂能覆盖大部分噪音就够了。最后说一个关于切分粒度的经验不同用途的 RAG 系统最优切分粒度是不一样的。如果是做精确的事实问答块可以小一点500 字符左右提高检索精度。如果是做长文摘要或综合分析块可以大一点1000 到 1500 字符保留更多上下文。没有万能参数只能根据你的实际场景去试。