企业官网建设流程全解析

1. RAG 数据导入与解析的整体设计思路

做 RAG 应用的人都有一个共识：模型选型只决定了效果的上限，而数据质量决定了效果的下限。我见过太多团队花大力气调 prompt、换 embedding 模型，最后发现召回不准的根源在于——原始文档压根没解析干净。PDF 里的表格被拆成了乱码，Markdown 的层级结构全丢了，txt 文件里一段话被硬生生截断成两半。所以这个系列的第一篇，我想把最基础但也最容易被忽视的环节讲透：从 txt 到 Markdown 的通用文本与结构化解析。

为什么先从 txt 和 Markdown 入手？因为这两类格式是所有 RAG 数据源里最“干净”的，没有 PDF 那种复杂的版面分析，也没有 HTML 那种嵌套标签。但恰恰是这种“看起来简单”，让很多人掉以轻心。txt 的编码问题、换行符差异、段落边界识别，Markdown 的标题层级、代码块保护、表格转换，每一个细节处理不好，都会在后续的 chunk 切分和向量化阶段被放大成检索噪声。

这篇文章适合谁看？如果你正在搭建 RAG 知识库，手头有一堆 txt 笔记、Markdown 文档、或者从网页保存下来的文本，想搞清楚怎么把它们变成高质量的 chunk，那这篇就是为你写的。我会从整体设计思路讲起，然后拆解核心细节，再给出可直接复现的实操流程，最后把我踩过的坑和排查技巧整理成速查表。全程不依赖特定框架，LangChain、LlamaIndex 或者自己手写管道都能套用。

1.1 为什么通用文本解析是 RAG 的第一道生死关

RAG 的流程拆开看就三步：导入、检索、生成。很多人把精力全砸在检索和生成上，导入环节随便找个 loader 一跑就完事。但实际项目中，导入阶段引入的噪声，检索阶段是无论如何也补不回来的。举个例子，一份产品需求文档里有个关键参数表，如果解析时表格结构丢失，变成了一串用空格分隔的数字，那用户问“XX 参数是多少”时，向量检索几乎不可能命中这个 chunk，因为语义已经完全散了。

通用文本解析的核心目标不是“把文件读进来”，而是在保留原始语义结构的前提下，把非结构化文本转成机器可理解的结构化片段。txt 和 Markdown 虽然格式简单，但它们承载的语义信息并不少：段落之间的空行代表主题切换，Markdown 的标题层级代表内容归属，代码块代表不可拆分的原子单元。这些结构信息如果能在导入阶段被正确识别和保留，后续的 chunk 切分就能做到“按语义边界切”，而不是“按字符数硬切”。

我个人的经验是，导入阶段多花一小时做结构解析，检索阶段能省十小时的调参时间。这不是夸张，而是因为语义边界的识别直接决定了 chunk 的质量，而 chunk 质量是 RAG 召回率的天花板。

1.2 从 txt 到 Markdown 的解析链路设计

整个解析链路我习惯分成四层：读取层、清洗层、结构识别层、输出层。读取层负责把文件内容以正确的编码读进来，处理 BOM、换行符差异；清洗层去掉页眉页脚、多余空行、不可见字符；结构识别层是核心，负责识别段落、标题、列表、代码块、表格等语义单元；输出层把识别结果统一转成 Markdown 格式，因为 Markdown 是后续 chunk 切分最友好的中间表示。

为什么选 Markdown 作为中间格式？因为 Markdown 的语法天然携带层级信息。#的数量直接对应标题级别，空行对应段落边界，代码块用反引号包裹，表格用管道符分隔。这些标记在后续用 MarkdownHeaderTextSplitter 之类的工具切分时，可以直接作为分割依据。相比之下，纯 txt 没有任何结构标记，切分时只能靠空行和字符数猜，效果差很多。

这个链路的设计原则是先归一化再结构化。不管输入是 GBK 编码的 txt、带 BOM 的 UTF-8、还是从网页复制来的混合换行符文本，读取层统一转成 UTF-8 无 BOM、LF 换行的标准格式。清洗层用正则去掉连续空行、行尾空格、零宽字符。结构识别层再基于清洗后的文本做模式匹配。这样每一层的职责单一，出问题时容易定位是哪一层的锅。

2. 核心细节解析与实操要点

2.1 编码识别与换行符归一化

编码问题是 txt 解析的第一大坑。国内很多老文档是 GBK 或 GB2312 编码，直接按 UTF-8 读会报 UnicodeDecodeError 或者读出乱码。我的做法是用chardet或charset-normalizer先探测编码，再按探测结果读取，读完后统一转成 UTF-8。但 chardet 对短文本的探测准确率不高，所以我会加一个兜底逻辑：如果探测置信度低于 0.7，就按 GBK 试读，如果 GBK 也失败，再用errors='replace'强行读，同时记录警告日志。

换行符的坑更隐蔽。Windows 的\r\n、Linux 的\n、老 Mac 的\r，三种换行符混在一起时，按行切分会出问题。我习惯在读取后立刻做一次text.replace('\r\n', '\n').replace('\r', '\n')，把所有换行符统一成\n。这一步看似简单，但如果不做，后面用正则匹配段落边界时，\n\n可能匹配不到\r\n\r\n，导致段落识别失败。

还有一个容易被忽视的点是BOM 头。UTF-8 with BOM 的文件开头会有\ufeff字符，如果不处理，第一个 chunk 的开头会多一个不可见字符，影响 embedding 质量。读取时用encoding='utf-8-sig'可以自动去掉 BOM。

注意：不要用open()默认编码读取，Python 在 Windows 上默认是 GBK，在 Linux 上默认是 UTF-8，跨平台行为不一致。永远显式指定编码，或者用二进制模式读入后自己 decode。

2.2 段落边界识别与空行处理

txt 文件里段落之间通常用空行分隔，但实际情况千奇百怪：有的用两个空行，有的用三个，有的在空行里夹了空格或制表符。我的处理策略是先把连续空行压缩成一个空行，再去掉空行里的空白字符。正则re.sub(r'\n\s*\n', '\n\n', text)可以做到这一点。压缩后再按\n\n切分，就能得到比较干净的段落列表。

但有些 txt 是从 PDF 复制出来的，段落之间没有空行，只有换行。这种情况下，单靠空行切分会把整篇文档切成一个巨大的段落。我的补救方案是基于句子边界做二次切分：先用正则识别中文句号、问号、感叹号、分号，以及英文的.?!;，在句子边界处插入换行，再按空行切分。这样即使原始文本没有段落空行，也能得到语义相对完整的片段。

还有一个细节是列表项的识别。txt 里的列表可能用-、*、1.、（1）、①等各种符号开头。我会用一组正则模式匹配这些行首标记，把连续的列表项归为一个列表块，在输出 Markdown 时转成标准列表语法。这样做的好处是后续 chunk 切分时，列表不会被从中间切断。

2.3 Markdown 结构解析的优先级策略

Markdown 解析比 txt 复杂的地方在于嵌套结构。一个##标题下面可能有###子标题，子标题下面可能有代码块和表格。如果解析时只做扁平化处理，层级信息就丢了。我的做法是构建一棵文档树：每个标题作为一个节点，标题下的内容作为该节点的子内容，遇到更高级别的标题就回溯到对应的父节点。

具体实现上，我用一个栈来维护当前路径。遇到#标题时，弹出栈中所有级别大于等于当前级别的节点，然后把当前标题压栈。遇到普通段落、代码块、表格时，挂到栈顶节点下。这样解析完就得到一棵带层级的树，每个叶子节点都是一个语义完整的 chunk 候选。

代码块的处理要特别小心。Markdown 代码块用三个反引号包裹，里面可能包含任何字符，包括看起来像标题的#行。如果解析时不做保护，代码块里的# 注释会被误识别为标题。我的做法是先用正则把代码块整体提取出来，用占位符替换，解析完其他结构后再把代码块填回去。表格同理，先用占位符保护，避免表格里的|被误解析。

提示：Markdown 的标题识别要区分行首和行内。只有行首的#才是标题，行内的#是普通字符。正则要用^#{1,6}\s并开启多行模式。

2.4 表格与代码块的保护性解析

表格是 RAG 里最容易出问题的结构。Markdown 表格用|分隔列，用---分隔表头和表体。解析时我会把表格转成两种形式：一种是保留 Markdown 原格式，适合直接展示；另一种是转成“列名: 值”的键值对文本，适合 embedding。为什么要转键值对？因为向量模型对|分隔的表格理解能力有限，而“参数名: 数值”这种自然语言形式更容易被语义检索命中。

代码块的处理原则是整块保留，不切分。一个代码块无论多长，都应该作为一个完整的 chunk，因为代码的语义完整性依赖于上下文。如果按字符数硬切，一个函数被切成两半，检索出来也没法用。我会在代码块前后加特殊标记，比如[CODE_START]和[CODE_END]，在 chunk 切分时识别这些标记，确保代码块不被切断。

表格转键值对的逻辑是这样的：读第一行作为列名，后续每行生成一个列名1: 值1, 列名2: 值2的字符串。如果表格有合并单元格或者嵌套结构，Markdown 本身表达不了，这种情况我会保留原始 Markdown 并加注释说明。实测下来，简单表格转键值对后，检索命中率能提升 20% 以上。

3. 实操过程与核心环节实现

3.1 环境准备与依赖安装

这套解析流程我习惯用 Python 实现，依赖不多，核心就几个库。charset-normalizer做编码探测，regex做增强正则匹配，markdown-it-py做 Markdown 语法解析。如果你用 LangChain，它自带的TextLoader和MarkdownHeaderTextSplitter也能用，但我更推荐自己写解析层，因为可控性更强，出问题容易定位。

pip install charset-normalizer regex markdown-it-py

如果你打算把解析结果直接接入向量库，还需要装对应的客户端，比如chromadb、qdrant-client或者pymilvus。但这一篇我们只聚焦解析，向量化留到下一篇讲。

3.2 txt 文件解析的完整代码实现

先看读取和清洗层。这段代码处理编码探测、BOM 去除、换行符归一化和空行压缩：

import re from charset_normalizer import from_path def read_text_file(file_path): # 编码探测 result = from_path(file_path).best() if result is None: raise ValueError(f"无法识别文件编码: {file_path}") text = str(result) # 去除 BOM text = text.lstrip('\ufeff') # 换行符归一化 text = text.replace('\r\n', '\n').replace('\r', '\n') # 去除零宽字符 text = re.sub(r'[\u200b\u200c\u200d\ufeff]', '', text) # 压缩连续空行 text = re.sub(r'\n\s*\n', '\n\n', text) # 去除行尾空格 text = re.sub(r'[ \t]+\n', '\n', text) return text.strip()

这段代码里，from_path会返回多个候选编码，best()取置信度最高的。如果文件很短导致探测不准，可以加一个 fallback：先试 UTF-8，失败再试 GBK。零宽字符的去除很重要，从网页复制来的文本经常夹带这些不可见字符，它们会干扰后续的正则匹配。

接下来是段落识别和列表处理：

def split_paragraphs(text): # 按空行切分 raw_paragraphs = re.split(r'\n\n+', text) paragraphs = [] for para in raw_paragraphs: para = para.strip() if not para: continue # 检测是否为列表块 lines = para.split('\n') if is_list_block(lines): paragraphs.append(format_list_block(lines)) else: # 长段落按句子边界二次切分 if len(para) > 800: paragraphs.extend(split_by_sentence(para)) else: paragraphs.append(para) return paragraphs def is_list_block(lines): list_pattern = re.compile(r'^\s*([-*+]|\d+[.)]|[（(]\d+[）)]|[①-⑩])\s+') return all(list_pattern.match(line) for line in lines if line.strip()) def format_list_block(lines): formatted = [] for line in lines: line = line.strip() # 统一转成 Markdown 无序列表 line = re.sub(r'^\s*([-*+]|\d+[.)]|[（(]\d+[）)]|[①-⑩])\s+', '- ', line) formatted.append(line) return '\n'.join(formatted) def split_by_sentence(text): # 在句子边界插入换行 sentence_end = re.compile(r'([。！？；.!?;])\s*') text = sentence_end.sub(r'\1\n', text) sentences = [s.strip() for s in text.split('\n') if s.strip()] # 合并短句，避免切得太碎 chunks = [] buffer = '' for sent in sentences: if len(buffer) + len(sent) < 400: buffer += sent else: if buffer: chunks.append(buffer) buffer = sent if buffer: chunks.append(buffer) return chunks

这里有个经验值：段落长度超过 800 字就考虑二次切分，合并短句时以 400 字为界。这两个数字不是拍脑袋定的，而是根据主流 embedding 模型的上下文窗口和语义完整性权衡出来的。800 字大约对应 500-600 个 token，在大多数模型的窗口范围内；400 字合并阈值保证每个 chunk 有足够的语义密度，不会因为太短而缺乏上下文。

3.3 Markdown 结构化解析的实现

Markdown 解析我用markdown-it-py把文本转成 token 流，再基于 token 构建文档树。核心逻辑是维护一个标题栈：

from markdown_it import MarkdownIt def parse_markdown(text): md = MarkdownIt() tokens = md.parse(text) tree = {'level': 0, 'title': 'root', 'content': [], 'children': []} stack = [tree] current_content = [] for token in tokens: if token.type == 'heading_open': # 保存当前内容到栈顶节点 if current_content: stack[-1]['content'].append('\n'.join(current_content)) current_content = [] level = int(token.tag[1]) # 弹出级别大于等于当前的节点 while len(stack) > 1 and stack[-1]['level'] >= level: stack.pop() new_node = {'level': level, 'title': '', 'content': [], 'children': []} stack[-1]['children'].append(new_node) stack.append(new_node) elif token.type == 'inline' and stack[-1]['title'] == '': # 标题文本 stack[-1]['title'] = token.content elif token.type in ('fence', 'code_block'): # 代码块整体保留 current_content.append(f"```\n{token.content}\n```") elif token.type == 'table_open': # 表格处理，这里简化处理，实际需要遍历表格 token pass elif token.type == 'inline': current_content.append(token.content) if current_content: stack[-1]['content'].append('\n'.join(current_content)) return tree

这段代码的关键点是标题栈的维护。遇到##标题时，如果栈顶是###，就弹出###再压入##；如果栈顶是#，就直接压入##作为子节点。这样构建出的树，每个节点的路径就是完整的标题层级，比如产品文档 > 接口说明 > 认证方式。后续 chunk 切分时，可以把路径作为 metadata 附加到每个 chunk 上，检索时能大幅提升准确率。

代码块用fencetoken 识别，token.content就是代码内容，直接整体保留。表格的完整处理需要遍历table_open、tr_open、td_open等 token，代码比较长，这里省略，核心思路是把表头和数据行分别提取，再转成键值对文本。

3.4 输出层：统一转 Markdown 与 metadata 附加

解析完 txt 和 Markdown 后，输出层要做两件事：统一转成 Markdown 格式，以及给每个 chunk 附加 metadata。txt 解析出的段落列表，我会按顺序加上## 段落 N的标题，转成 Markdown。Markdown 解析出的树，我会做一次深度优先遍历，把每个叶子节点的内容加上标题路径作为前缀。

metadata 至少包含这几个字段：source（源文件路径）、title_path（标题层级路径）、chunk_type（paragraph/code/table/list）、char_count（字符数）。这些字段在后续向量化时一起存入向量库，检索时可以按chunk_type过滤，比如只检索代码块，或者只检索表格。

def tree_to_chunks(tree, source, path=None): if path is None: path = [] chunks = [] current_path = path + [tree['title']] if tree['title'] != 'root' else path for content in tree['content']: chunks.append({ 'text': content, 'metadata': { 'source': source, 'title_path': ' > '.join(current_path), 'chunk_type': 'paragraph', 'char_count': len(content) } }) for child in tree['children']: chunks.extend(tree_to_chunks(child, source, current_path)) return chunks

这样输出的每个 chunk 都带着完整的标题路径，比如产品文档 > 接口说明 > 认证方式。检索时用户问“认证方式有哪些”，即使 chunk 里没有出现“认证方式”这个词，标题路径也能帮助向量模型建立关联。

4. 常见问题与排查技巧实录

4.1 编码乱码与特殊字符处理速查

编码问题排查我总结了一个流程：先看文件头有没有 BOM，有 BOM 就用utf-8-sig读；没有 BOM 就用 charset-normalizer 探测；探测置信度低就手动试 GBK、GB18030、Big5。如果读出来是乱码但没报错，大概率是编码探测错了，用errors='replace'读一遍，看替换字符�的位置，能反推原始编码。

特殊字符方面，最常见的是零宽空格\u200b、零宽非连接符\u200c、零宽连接符\u200d，以及软连字符\u00ad。这些字符从网页复制时经常带进来，肉眼看不见但会干扰正则匹配。我的清洗层里固定加一条re.sub(r'[\u200b\u200c\u200d\u00ad\ufeff]', '', text)，一劳永逸。

还有一个坑是全角空格和半角空格混用。中文文档里经常出现全角空格\u3000，按半角空格切分会失败。清洗时统一把全角空格转成半角：text.replace('\u3000', ' ')。

4.2 Markdown 解析常见异常与修复

Markdown 解析最常遇到的问题是标题识别错误。比如代码块里的# 这是注释被误识别为一级标题。修复方法是在解析前用占位符保护代码块。具体做法：用正则r'```[\s\S]*?```'匹配所有代码块，替换成__CODE_BLOCK_0__这样的占位符，解析完再把代码块填回去。

另一个问题是表格解析不完整。Markdown 表格要求表头下面必须有|---|---|分隔行，但有些文档漏了这一行，导致表格被当成普通段落。我的处理是：如果检测到连续多行都以|开头和结尾，但第二行不是分隔行，就自动补一个分隔行，再按表格解析。

还有嵌套列表的层级丢失。Markdown 用缩进表示嵌套，但缩进可能是 2 空格、4 空格或 Tab。解析时我会先把 Tab 转成 4 空格，再按缩进深度计算层级。如果缩进不规律，就按“遇到更小缩进就回退层级”的规则处理。

提示：Markdown 解析不要追求 100% 还原原始结构，重点是保留对检索有用的语义信息。标题层级、代码块边界、表格数据这三样保住了，RAG 效果就不会差。

4.3 性能优化与批量处理建议

当文件数量上千时，逐个读取解析会很慢。我的优化策略是批量读取 + 多进程解析。读取层用concurrent.futures.ThreadPoolExecutor并发读文件，因为 IO 密集；解析层用ProcessPoolExecutor多进程，因为正则和字符串操作是 CPU 密集。实测下来，1000 个 txt 文件从 3 分钟降到 40 秒左右。

内存方面，不要一次性把所有文件读进内存。用生成器逐文件处理，解析完一个就输出一个，及时释放。如果单个文件特别大（比如超过 100MB 的 txt），要分块读取，避免内存溢出。

还有一个经验是缓存解析结果。解析后的 chunk 列表可以序列化成 JSON 存到磁盘，下次直接加载，不用重新解析。文件内容没变时，用文件哈希判断是否命中缓存。这个优化在调试阶段特别有用，改 chunk 切分策略时不用反复解析原始文件。

4.4 解析质量自检清单

解析完一批文件后，我习惯做一次质量自检，确保没有明显问题。自检清单如下：

• 随机抽 10 个 chunk，检查开头和结尾是否语义完整，有没有被从中间切断
• 检查是否有 chunk 长度超过 2000 字，过长 chunk 需要二次切分
• 检查是否有 chunk 长度小于 20 字，过短 chunk 考虑合并
• 检查代码块是否完整，有没有被切分
• 检查表格是否转成了键值对，键值对格式是否正确
• 检查 metadata 的 title_path 是否为空，空路径说明标题识别失败
• 检查特殊字符是否清洗干净，搜索\u200b等零宽字符

这个清单我每次导入新数据源时都会跑一遍，能提前发现 80% 的解析问题。剩下的 20% 通常要等检索效果不好时才能暴露，那时候再回头查解析日志。

5. 从解析到切分的衔接要点

解析只是第一步，解析结果最终要喂给 chunk 切分器。这里有个衔接要点：解析时保留的结构信息，切分时要充分利用。比如解析出的标题路径，切分时应该作为 chunk 的前缀或者 metadata；解析出的代码块标记，切分时要识别并保护；解析出的表格键值对，切分时不要从中间切断。

我习惯在解析输出时就把 chunk 的边界定好，而不是等切分器再切一次。因为解析阶段掌握的结构信息最全，这时候定边界最准确。具体做法是：解析出的每个段落、每个代码块、每个表格，都作为一个独立的 chunk 候选，如果超过长度阈值再二次切分。这样切分器只需要做长度控制，不需要做语义判断。

下一篇我会讲 PDF 和 HTML 的解析，那两种格式的版面分析更复杂，但核心思路是一样的：先归一化，再结构化，最后按语义边界输出。把 txt 和 Markdown 这两个简单格式吃透，后面处理复杂格式时就有了参照系。

我个人在实际操作中的体会是，解析环节最值得投入时间的地方不是写代码，而是观察数据。拿几十个真实文件出来，逐个看解析结果，看哪里切错了、哪里丢了结构，然后针对性修规则。这个过程比盲目调参有效得多。我见过太多人上来就调 embedding 模型，结果数据本身就没解析干净，调什么都是白搭。