1. 为什么 RAG 的第一步不是模型而是数据导入很多人一上来就研究向量库选型、Embedding 模型对比、重排序策略结果折腾了两周检索效果还是稀烂。我踩过这个坑之后才彻底想明白一件事RAG 的上限在数据导入阶段就已经被锁死了。你后面换再贵的模型、调再细的参数都救不回来一份被切得七零八落的原始文档。这一篇先聚焦最基础、也最容易被轻视的一环——通用文本与结构化文本的导入与解析具体就是从纯文本 txt 到 Markdown 这一类“半结构化”文档的处理。为什么先讲这个因为绝大多数人的知识库素材无非就是几类随手记的 txt 笔记、导出的 Markdown 文档、从网页另存下来的内容、以及各种系统导出的结构化文本。这些格式看起来简单但恰恰是解析环节翻车最多的地方。我见过太多案例一份 300 页的产品手册用默认的字符切分器一切表格被拦腰截断代码块被拆成两半标题和正文混在一起最后检索出来的片段驴唇不对马嘴。用户问“第三章第二节讲了什么”系统返回的是某个表格中间的一行数字。这不是模型的问题是导入解析阶段没有把文档的结构信息保留下来。所以这篇内容适合谁看如果你是刚接触 RAG、正准备搭建第一个知识库的开发者这篇能帮你避开最基础的坑如果你已经踩过一些坑、检索效果不理想这篇能帮你回头检查数据导入环节到底哪里出了问题如果你在做企业级知识管理需要处理大量异构文档这篇提供的思路可以直接套用。核心关键词就几个RAG、数据导入、解析、txt、Markdown。我会围绕这几个词把从原始文本到可检索片段的完整链路拆开讲包括格式识别、结构提取、分块策略、元数据注入以及每一步背后的取舍逻辑。1.1 先搞清楚RAG 里的“数据导入”到底在做什么很多人把数据导入理解成“把文件读进来”这个认知太浅了。在 RAG 的语境下数据导入实际上要完成四件事第一是格式归一化。你的原始素材可能是 txt、Markdown、HTML、PDF、Word甚至是从数据库导出的 CSV。这些格式的底层结构完全不同但最终都要变成同一种中间表示通常是带结构的纯文本加上元数据。第二是结构提取。文档里的标题层级、段落边界、列表、表格、代码块、引用块这些结构信息在后续检索时极其重要。一个标题为“安装步骤”的片段和一个正文里随便一句话检索权重应该是不一样的。第三是语义分块。不能简单地按固定字符数切那样会把完整的语义单元切碎。理想的分块应该尽量保证每个块是一个自包含的语义单元同时控制块的大小在 Embedding 模型的最佳输入范围内。第四是元数据注入。每个块需要携带来源信息来自哪个文件、哪个章节、第几页、什么时间导入的。这些元数据在检索过滤和结果溯源时必不可少。这四件事里格式归一化和结构提取是基础语义分块是核心难点元数据注入是工程细节。下面逐个拆开讲。1.2 为什么从 txt 和 Markdown 讲起有人会问现在 PDF 解析工具那么多为什么不直接从 PDF 开始讲原因很简单txt 和 Markdown 是理解解析本质的最佳切入点。PDF 的解析本质上是在做逆向工程——从排版结果反推逻辑结构这个过程充满了不确定性。而 txt 和 Markdown 不一样它们的结构信息是显式存在的。Markdown 的#就是标题|就是表格 就是代码块。你不需要猜只需要正确识别。先把这两种格式吃透建立起“结构感知”的思维习惯再去处理 PDF 这种“结构隐式”的格式会顺畅很多。而且实际项目中Markdown 正在成为知识库素材的主流格式——很多文档工具都支持导出 Markdown很多技术文档本身就是用 Markdown 写的。2. 通用文本与结构化文本的解析核心思路2.1 格式识别与预处理别急着读文件内容拿到一个文件第一件事不是直接读内容而是先判断它到底是什么格式。这里有个坑文件扩展名不可信。我遇到过.txt文件实际是 HTML 源码的也遇到过.md文件里混着大量 HTML 标签的。稳妥的做法是做一个轻量的格式探测读取文件前 2KB 内容检查是否有 Markdown 特征#开头的行、|表格、 代码块围栏检查是否有 HTML 特征html、div、p等标签检查是否有 CSV 特征逗号分隔、制表符分隔、行列数一致如果都没有按纯文本处理这个探测逻辑不需要很复杂几十行代码就能搞定。但就是这几十行代码能帮你避免后面大量的解析异常。预处理阶段还有几件事要做编码统一。中文文档常见的编码有 UTF-8、GBK、GB2312甚至还有 GB18030。如果编码判断错了读出来全是乱码。我的做法是先用chardet之类的库探测编码然后用探测到的编码读取读完之后统一转成 UTF-8。如果探测置信度低于某个阈值就尝试用 UTF-8 读取失败再回退到 GBK。换行符统一。Windows 的\r\n、Unix 的\n、老 Mac 的\r这三种换行符混在一起会让后续的分行逻辑出错。统一替换成\n是标准操作。空白字符清理。连续多个空行、行尾多余空格、制表符和空格混用这些都会影响结构识别的准确性。但注意不要过度清理比如 Markdown 里行尾两个空格表示换行这个不能删。提示预处理阶段的所有操作都应该是可逆的或者有日志记录的。一旦发现解析结果异常你需要能回溯到原始内容判断是预处理引入的问题还是解析逻辑本身的问题。2.2 结构提取把文档的“骨架”抽出来结构提取的目标是回答一个问题这份文档的层级关系是什么。对于 Markdown结构是显式的。#到######对应六级标题标题之间的内容属于该标题的章节。解析时可以用一个栈来维护当前的标题路径。比如遇到## 第二章栈变成[第二章]再遇到### 2.1 节栈变成[第二章, 2.1 节]。每个内容块都记录它所属的完整标题路径。对于纯文本结构是隐式的但通常有规律可循。常见的模式包括用数字编号的行如1.、1.1、第一章用特殊符号装饰的行如、-----、*****全行加粗或全行大写的行缩进层级变化我一般会写一组正则规则来识别这些模式按优先级依次匹配。匹配到的行标记为“疑似标题”然后根据编号的层级关系推断标题级别。比如1.是一级1.1是二级1.1.1是三级。这里有个经验不要追求 100% 的标题识别准确率。实际文档里总有一些奇怪的格式强行识别反而会引入噪声。我的做法是设置一个置信度阈值高置信度的直接标记为标题低置信度的保留为普通段落但在元数据里标注“疑似标题”。后续检索时可以根据需要决定是否利用这个信息。表格的提取是另一个重点。Markdown 表格用|分隔解析相对简单。纯文本表格就麻烦了可能是空格对齐、制表符对齐、或者用---画边框。我的建议是能识别就识别识别不了就整块保留。千万不要把表格拆成一行一行的文本那样表格的语义就彻底丢了。代码块的识别相对简单Markdown 用 围栏纯文本通常靠缩进或者前后空行判断。代码块在分块时应该作为一个整体不要从中间切开。2.3 分块策略RAG 效果的分水岭分块是数据导入阶段最核心的决策没有之一。分块策略直接决定了检索质量的上限。先说一个反直觉的结论固定长度分块几乎总是错的。很多人图省事直接按 500 字符切重叠 50 字符。这种做法在简单场景下能用但只要文档有结构就会出问题。一个完整的操作步骤被切成两半前半段说“点击设置按钮”后半段说“在弹出窗口中选择高级选项”检索时只召回前半段用户根本不知道下一步该干什么。我的分块策略是结构感知的递归分块具体逻辑如下第一优先级是按结构边界切分。标题、章节、列表项、表格、代码块这些都是天然的边界。一个章节的内容如果不超过最大块大小就整块作为一个 chunk。如果超过再往下切。第二优先级是按语义边界切分。段落是最小的语义单元尽量保证一个段落不被切开。如果单个段落就超过了最大块大小比如一段超长的法律条款那就只能按句子切。第三优先级才是按长度切分。当以上边界都不存在时才退回到按字符数切分并且尽量在句子结束符处断开。块大小的选择需要根据 Embedding 模型来定。大多数中文 Embedding 模型的最佳输入长度在 256 到 512 个 token 之间。我的经验值是目标块大小 400 到 600 字符最大不超过 800 字符块之间重叠 10% 到 15%。重叠的目的是防止边界处的信息丢失但重叠太多会导致检索结果冗余。这里有个细节不同结构的块应该有不同的目标大小。表格和代码块可以大一些因为它们的语义密度高切碎了反而不好。普通叙述性段落可以小一些因为语义密度低块太大反而稀释了关键信息。2.4 元数据设计让每个块都能“自报家门”元数据在检索阶段的价值经常被低估。一个好的元数据设计能让检索效果提升一个档次。每个 chunk 至少应该携带以下元数据元数据字段说明用途source_file来源文件名结果溯源、按文件过滤file_type文件类型按类型过滤、调试heading_path标题路径结果展示、按章节过滤chunk_index块序号排序、去重char_count字符数质量监控has_table是否含表格特殊处理标记has_code是否含代码特殊处理标记import_time导入时间增量更新标题路径heading_path是我认为最有价值的元数据。它记录了当前块所属的完整章节路径比如[第三章 安装部署, 3.2 环境配置, 3.2.1 依赖安装]。在检索结果展示时把这个路径显示出来用户一眼就能知道这个片段来自哪里信任度会高很多。而且在检索时可以利用标题路径做上下文增强。比如用户问“依赖安装有哪些步骤”检索到的块标题路径里包含“依赖安装”这个块的权重就应该提高。这种基于结构的加权比单纯依赖向量相似度要可靠得多。3. 从 txt 到 Markdown 的完整实操流程3.1 环境准备与依赖选择我用的技术栈是 Python核心依赖就几个pip install chardet markdown-it-py beautifulsoup4 lxmlchardet编码探测处理中文文档必备markdown-it-pyMarkdown 解析比正则更可靠beautifulsoup4lxml处理混入的 HTML 内容如果你不想引入太多依赖纯文本处理用标准库就够了。但 Markdown 解析我强烈建议用专门的库自己写正则处理嵌套结构会疯掉。3.2 第一步文件读取与编码归一化import chardet def read_file_safely(file_path): with open(file_path, rb) as f: raw f.read() # 探测编码 detected chardet.detect(raw[:10000]) encoding detected[encoding] confidence detected[confidence] # 置信度低时回退 if confidence 0.7 or encoding is None: encoding utf-8 try: text raw.decode(encoding) except UnicodeDecodeError: # 回退链 for fallback in [utf-8, gbk, gb18030, latin-1]: try: text raw.decode(fallback) break except UnicodeDecodeError: continue else: text raw.decode(utf-8, errorsreplace) # 换行符统一 text text.replace(\r\n, \n).replace(\r, \n) return text这段代码的关键在于回退链。中文文档的编码情况很复杂单一探测不一定准。我实测下来chardet对 UTF-8 和 GBK 的区分准确率大概在 85% 左右剩下的 15% 就得靠回退链兜底。注意latin-1放在回退链最后是有原因的。它能解码任何字节序列永远不会抛异常但解出来的可能是乱码。所以它只是最后的保底不能作为首选。3.3 第二步格式探测与路由import re def detect_format(text): sample text[:2000] # Markdown 特征 md_patterns [ r^#{1,6}\s, # 标题 r^\|.*\|$, # 表格 r^, # 代码块 r^\s*[-*]\s, # 无序列表 r^\s*\d\.\s, # 有序列表 ] md_score sum(1 for p in md_patterns if re.search(p, sample, re.MULTILINE)) # HTML 特征 html_score len(re.findall(r[a-z][^]*, sample)) # CSV 特征 lines sample.split(\n)[:10] csv_score 0 if len(lines) 1: comma_counts [line.count(,) for line in lines if line.strip()] if comma_counts and len(set(comma_counts)) 1 and comma_counts[0] 0: csv_score 3 if md_score 2: return markdown elif html_score 5: return html elif csv_score 3: return csv else: return plaintext这个探测逻辑的核心思想是多特征投票而不是单一特征判断。因为实际文档里经常出现混合情况比如 Markdown 里嵌了 HTML纯文本里用了#做注释。多特征投票能降低误判率。3.4 第三步Markdown 结构解析用markdown-it-py把 Markdown 解析成 token 流然后遍历 token 构建结构树from markdown_it import MarkdownIt def parse_markdown_structure(text): md MarkdownIt() tokens md.parse(text) structure [] heading_stack [] current_content [] for token in tokens: if token.type heading_open: # 保存之前的内容 if current_content: structure.append({ type: content, heading_path: list(heading_stack), text: \n.join(current_content) }) current_content [] level int(token.tag[1]) # h1 - 1 # 维护标题栈 while heading_stack and heading_stack[-1][0] level: heading_stack.pop() heading_stack.append((level, )) elif token.type inline and heading_stack and heading_stack[-1][1] : # 标题文本 heading_stack[-1] (heading_stack[-1][0], token.content) elif token.type in (fence, code_block): current_content.append(f\n{token.content}\n) elif token.type table_open: # 表格单独处理 pass elif token.type inline: current_content.append(token.content) # 处理最后一段 if current_content: structure.append({ type: content, heading_path: [h[1] for h in heading_stack], text: \n.join(current_content) }) return structure这段代码的核心是标题栈。栈里维护的是当前所处的标题路径遇到新标题时根据级别弹出旧标题、压入新标题。每个内容块都记录它被解析时的标题路径。实际使用中还需要处理表格和代码块的完整提取。markdown-it-py的 token 流里表格会被拆成table_open、tr_open、td_open等一系列 token需要专门写逻辑把它们重新组装成结构化的表格数据。3.5 第四步纯文本结构推断纯文本没有显式结构需要靠正则和启发式规则推断def infer_plaintext_structure(text): lines text.split(\n) blocks [] current_block [] current_heading None # 标题识别规则按优先级排列 heading_patterns [ (r^第[一二三四五六七八九十][章节篇]\s*, 1), (r^\d\.\d\.\d\s, 3), (r^\d\.\d\s, 2), (r^\d\.\s, 1), (r^[一二三四五六七八九十][、.]\s*, 2), (r^{3,}$, 0), # 下划线装饰标记上一行为标题 (r^-{3,}$, 0), ] for i, line in enumerate(lines): stripped line.strip() # 空行作为块边界 if not stripped: if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) current_block [] continue # 检查是否是标题 is_heading False for pattern, level in heading_patterns: if re.match(pattern, stripped): if level 0: # 装饰线把上一行提升为标题 if current_block: current_heading current_block.pop() else: # 保存之前的内容 if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) current_block [] current_heading stripped is_heading True break if not is_heading: current_block.append(line) # 收尾 if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) return blocks这套规则不是万能的但覆盖了中文技术文档里 80% 以上的标题格式。剩下的 20% 需要根据具体文档类型定制规则。实操心得我一般会先拿几份典型文档跑一遍把识别错误的标题打印出来针对性调整正则。这个过程通常需要迭代两三轮但一旦调好后续同类文档都能复用。3.6 第五步结构感知的分块有了结构树之后分块就变成了一个递归过程def chunk_by_structure(blocks, max_size600, min_size100, overlap80): chunks [] for block in blocks: text block[text] heading block.get(heading, ) # 块本身不超过限制直接作为一个 chunk if len(text) max_size: if len(text) min_size: chunks.append({ text: text, heading: heading, char_count: len(text) }) continue # 超长块按段落切分 paragraphs text.split(\n\n) current [] current_len 0 for para in paragraphs: para_len len(para) if current_len para_len max_size and current: chunk_text \n\n.join(current) chunks.append({ text: chunk_text, heading: heading, char_count: len(chunk_text) }) # 保留重叠部分 overlap_text chunk_text[-overlap:] if len(chunk_text) overlap else chunk_text current [overlap_text, para] current_len len(overlap_text) para_len else: current.append(para) current_len para_len if current: chunk_text \n\n.join(current) chunks.append({ text: chunk_text, heading: heading, char_count: len(chunk_text) }) return chunks这里有几个关键决策点为什么最小块大小是 100 字符太小的块语义不完整Embedding 出来的向量质量差检索时容易误召回。100 字符大约是一到两句话是语义完整性的下限。为什么重叠是 80 字符这是经验值。重叠太少起不到防止边界信息丢失的作用重叠太多会导致检索结果大量重复。80 字符大约是一句话的长度能保证边界处的语义连续性。表格和代码块怎么处理它们不应该参与常规分块。表格应该整体保留如果太大就按行切分但保留表头。代码块应该整体保留如果太大就按函数或逻辑块切分。3.7 第六步元数据注入与输出最后一步是把分块结果和元数据组装起来输出成后续流程能消费的格式import json from datetime import datetime def build_chunks_with_metadata(chunks, source_file, file_type): result [] for i, chunk in enumerate(chunks): result.append({ id: f{source_file}_{i}, text: chunk[text], metadata: { source_file: source_file, file_type: file_type, heading: chunk.get(heading, ), chunk_index: i, char_count: chunk[char_count], has_table: | in chunk[text] and --- in chunk[text], has_code: in chunk[text], import_time: datetime.now().isoformat() } }) return result输出格式我推荐 JSON Lines每行一个 chunk。这样便于流式处理也便于后续增量更新时按行追加。4. 常见问题与排查技巧实录4.1 编码问题排查速查表现象可能原因排查方法解决方案中文全是乱码编码判断错误用十六进制查看器看字节尝试 GBK/GB18030部分字符乱码混合编码分段探测编码分段解码后拼接问号替代中文解码时 errorsreplace检查原始字节换正确编码重新解码换行符异常混合换行符统计 \r\n 和 \n 数量统一替换编码问题我踩过最坑的一次是一份文档前半部分是 UTF-8后半部分是 GBK。chardet探测出来是 UTF-8结果后半部分全乱码。后来我的做法是分段探测每 10KB 探测一次如果发现编码不一致就分段解码。4.2 结构识别失败的典型场景场景一标题没有编号。有些文档的标题就是加粗的一行文字没有任何编号。这种情况纯文本推断很难识别。我的做法是结合行长和上下文空行来判断如果一行文字长度小于 30 字符前后都有空行且不以标点结尾就标记为疑似标题。场景二列表嵌套过深。Markdown 的嵌套列表用缩进表示但缩进可能是 2 空格、4 空格、或者 Tab。解析时需要统一缩进单位。我的做法是统计所有缩进取最小公约数作为一级缩进单位。场景三表格跨页。从 PDF 转出来的文本表格经常被分页符打断。这种情况需要在预处理阶段识别分页符尝试把跨页的表格拼接起来。拼接逻辑是如果上一页末尾是表格行下一页开头也是表格行且列数一致就尝试合并。4.3 分块质量的快速验证方法分块做完之后怎么知道分得好不好我一般用三个快速检查检查一随机抽样 20 个 chunk人工阅读。看每个 chunk 是否语义完整是否包含足够的上下文。如果发现大量 chunk 以半句话开头或结尾说明分块边界有问题。检查二统计 chunk 大小分布。画个直方图看是否集中在目标大小附近。如果出现大量极小 chunk小于 50 字符或极大 chunk大于 1000 字符说明分块逻辑有漏洞。检查三做一轮检索测试。准备 10 个典型问题看检索结果是否相关。如果检索结果经常是表格中间的一行、或者代码块的片段说明结构处理有问题。实操心得我习惯在分块完成后把 chunk 列表导出成 Markdown 文件用编辑器打开快速浏览。肉眼扫一遍比看统计数字更容易发现异常。4.4 性能优化的几个实用技巧数据导入阶段如果处理大量文档性能会成为瓶颈。几个我实测有效的优化批量读取。不要一个文件一个文件地读用concurrent.futures做并发读取。IO 密集型任务并发能带来数倍提升。惰性解析。如果文档很大不要一次性全部解析成 token 流。markdown-it-py支持流式解析可以边解析边处理。缓存中间结果。结构解析的结果可以缓存起来后续调整分块参数时不需要重新解析。我用pickle把结构树缓存到本地调试分块逻辑时能省大量时间。正则预编译。所有正则表达式在模块加载时就编译好不要每次调用时重新编译。这个优化在小文档上不明显但处理上万份文档时差距很大。5. 从导入到检索的衔接要点5.1 导入结果如何影响检索策略数据导入阶段产出的 chunk 和元数据直接决定了检索阶段能做什么。如果 chunk 携带了heading元数据检索时就可以做基于标题的加权。具体做法是计算 query 和 chunk 标题的相似度把这个相似度作为一个加权因子和向量相似度做加权求和。我实测下来这个加权能让检索准确率提升 10% 到 15%。如果 chunk 标记了has_table和has_code检索时就可以做类型感知的展示。表格类结果用表格渲染代码类结果用代码块渲染用户体验会好很多。如果 chunk 记录了source_file和chunk_index检索时就可以做上下文扩展。召回一个 chunk 后把它的前后相邻 chunk 也取出来拼成更完整的上下文。这个技巧对回答“步骤类”问题特别有效。5.2 增量导入的设计考虑实际项目中知识库是持续更新的。增量导入的设计要点文件指纹。对每个文件计算 MD5 或 SHA256导入前先比对指纹。指纹没变就跳过变了就重新导入。版本管理。每次导入生成一个版本号chunk 的 ID 里包含版本信息。这样检索时可以指定只检索最新版本或者做版本对比。删除处理。文件被删除时对应的 chunk 也要标记删除。不要物理删除而是打上deleted标记检索时过滤掉。这样万一误删还能恢复。5.3 质量监控指标导入流程上线后需要持续监控几个指标指标含义健康范围平均 chunk 大小所有 chunk 的字符数均值300-600极小 chunk 占比小于 50 字符的 chunk 比例 5%极大 chunk 占比大于 1000 字符的 chunk 比例 3%编码异常率解码时使用回退链的比例 2%结构识别率成功识别标题的文档比例 80%这些指标异常时说明导入流程的某个环节出了问题需要回头排查。6. 一些踩坑之后的个人体会做 RAG 数据导入这一年多最大的体会是慢就是快。刚开始我总想快点把数据灌进去结果检索效果差回头返工的时间远超当初省下的时间。后来我养成了一个习惯每接入一种新格式的文档先拿 5 到 10 份样本做小规模测试把解析结果人工过一遍确认没问题了再批量导入。另一个体会是不要迷信自动化。结构识别、分块这些环节纯靠算法很难做到 100% 准确。我的做法是提供一个“人工校正”的接口对于识别异常的文档允许手动调整结构标记。这个接口看起来增加了工作量但实际上大幅提升了最终质量。还有一个细节保留原始文本。不管怎么预处理、怎么分块原始文本一定要完整保留。我见过太多案例预处理时做了不可逆的清洗后来发现清洗掉了关键信息想恢复都恢复不了。我的做法是原始文本单独存一份所有处理都是基于副本进行的。最后分享一个小技巧用检索测试反推导入质量。准备一组典型问题每次调整导入参数后跑一遍检索测试看召回结果的变化。这比看统计指标更直观也更能发现实际问题。我一般会维护一个 50 题左右的测试集覆盖事实查询、步骤查询、对比查询等不同类型每次调整参数后都跑一遍记录准确率变化。这个内容后续还可以这样扩展把 PDF、Word、HTML 这些格式的解析也纳入进来形成一套完整的异构文档导入方案。另外表格和图片的专项处理也值得单独展开特别是表格的结构化提取和图片的 OCR 处理都是实际项目中绕不开的环节。