做了几年文档处理，我最大的感受是：解析代码写起来只占整个流程的三分之一，真正耗时间的是清洗。很多人拿到一批来源杂乱的文档，第一反应是马上写脚本提取文字，结果跑完一看，文本里全是页眉页脚、乱码、重复段落，甚至不同文件里同一份内容出现好几遍。文档解析和知识清洗，说到底是为了把不可控的原始文件变成可控的结构化数据，为检索、问答、知识库建设打基础。这篇文章是我一段时间的实操记录，围绕文档结构化解析、文本清洗和常用工具选型展开，每条经验都实际跑过。文章不会只列工具，更会讲清楚不同场景下怎么选、为什么这么选，以及踩过哪些坑，希望能给准备做个人知识库、企业资料归档或者语料处理的朋友一些参考。
1. 动手之前先摸清底细：解析的难点不在技术，在文档形态差异
1.1 同样叫PDF，内部差异天差地别
先说一个最容易被忽视的问题：很多人把所有PDF当成同一种东西来处理，这是最大的误区。
同样是PDF，有的是从Word或LaTeX直接导出的文本型PDF，文字可以选中、可以搜索；有的是扫描件，本质是一张张图片，必须靠OCR才能识别文字；还有一种是混合型，前面几页是扫描图，后面几页是从系统里导出的文本。这三种处理路径完全不同，第一步如果判断错了，后面所有环节都会跟着出错。
判断方法其实很简单：用PDF阅读器打开文件，按Ctrl+F搜索一个肯定存在的词语，如果能搜到并且能选中相关文字，基本可以确定是文本型；如果搜不到任何结果，多半是扫描件。但这种方法只适用于少量文件，批量处理时我会用代码快速判断：
import fitz # PyMuPDF def check_pdf_text(path): doc = fitz.open(path) total_chars = 0 pages = min(doc.page_count, 5) # 先抽样前5页 for page in doc[:pages]: text = page.get_text() total_chars += len(text.strip()) doc.close() # 前5页文本量少于200字符，大概率是扫描件或图片型 return total_chars > 200这个方法的基本逻辑是：文本型PDF在正常排版下，前5页至少应该积累几百个字符，而扫描件因为无法直接提取文本，字符量几乎为零。阈值可以按实际文档类型调整，比如有些设计类PDF本身文字就很少，那就得结合页面字体信息来判断。
1.2 解析要解决的不只是“把字提出来”
很多人以为解析就是把文字提取出来，实际上远远不够。我会把文档解析拆成三个层次：
- 第一层是字符流，就是把PDF、Word、网页里的原始文字抠出来；
- 第二层是版面结构，要知道哪些文字是标题、哪些是正文、哪些是表格内容、哪些是页眉页脚；
- 第三层是语义结构，比如章节之间的层级关系、表格的表头与数据行关系、段落之间的逻辑关联。
大多数通用工具能帮你完成第一层，部分能做好第二层，第三层基本要靠代码逻辑或模型来补。但现实中很多人只做到了第一层，就把结果交给下游使用，导致后续检索、问答的效果大打折扣。
举个例子，PDF里常见的一种情况：本来是一张表格，直接用pdfplumber提取文本后，单元格的内容变成一串缺乏分隔的字符串，列和行全乱了。如果不做版面结构恢复，这些数据喂给知识库就是一堆噪音。
拿到一批新文档时，我建议不要急着写完整脚本，先从每个类型中抽5~10份做人工浏览，记录它们有哪些共性、哪些极端情况。这一步看起来没什么技术含量，却能避免后面因为判断失误重写解析逻辑。我自己就吃过亏：有一次直接批量解析几千份文件，跑到一半发现其中半数是从扫描系统存档的图片型PDF，OCR方案没准备，整个流程推到重来。
1.3 不同文档格式的自带“脾气”
按我接触过的实际项目，最常见的输入格式主要是下面这些：
| 格式 | 常见来源 | 解析难点 |
|---|---|---|
| PDF（文本型） | 系统导出、Office转换 | 表格结构、多栏排版、页眉页脚 |
| PDF（扫描型） | 扫描仪、传真存档 | OCR识别、拍照倾斜、清晰度不足 |
| Word | 日常办公、合同、申报材料 | 批注、修订、嵌入图片、保护模式 |
| HTML | 网页资料、在线文档 | 导航、页脚、广告等无关内容 |
| Markdown/TXT | 技术文档、日志 | 编码混乱、特殊符号 |
| Excel | 报表、清单数据 | 合并单元格、多级表头 |
每种格式都有自己的问题，后面会分类型详细讲。但有一条总原则：解析前先建立一个小规模的样本集，用样本集跑通流程，再扩展到全量数据。这不是浪费时间，而是给自己留一条退路。
2. 按文档类型找工具：PDF、Word、网页、扫描件分别怎么办
2.1 文本型PDF：pdfplumber和PyMuPDF的搭配使用
文本型PDF的解析，我目前用得最多的是两个Python库：pdfplumber和PyMuPDF。它们各有擅长，我通常让它们分工合作。
pdfplumber的优势在于版面结构还原，尤其是表格抽取。它的extract_table()能根据页面的线条和文字坐标识别表格结构，对规则表格的还原度很高。但缺点是速度偏慢，适合对精度要求高、文件数量不大的场景。
PyMuPDF（通常是import fitz）的优势是速度快，比pdfplumber快一个数量级，处理几百页的大文件也毫无压力。它的page.get_text()支持多种模式，可以提取带位置信息的文本块，也能直接获取图片内容。
我的常规做法是：先用PyMuPDF快速判断文件类型并抽取全文，如果发现页面中包含表格，再用pdfplumber单独处理表格页。示例代码如下：
import pdfplumber import fitz def extract_pdf_with_tables(path): result = {"text": "", "tables": []} doc = fitz.open(path) for page in doc: result["text"] += page.get_text() + "\n" doc.close() with pdfplumber.open(path) as pdf: for page in pdf.pages: tables = page.extract_tables() if tables: result["tables"].extend(tables) return result这里需要说明的是，extract_table()只对规整的表格有效。遇到无框线表格、合并单元格较多的复杂表格，还是会有偏差，需要自己写坐标修正逻辑或配合规则处理。
2.2 扫描件和图片型PDF：OCR方案选型
扫描件的核心工具是OCR。我把OCR方案分成两派：传统派和深度学习派。
传统派的代表是Tesseract，老牌开源OCR引擎，优势是部署简单、支持语言多，但中文识别效果一般，对付清晰印刷体还行，对复杂排版和低质量图片就比较吃力。
深度学习派的代表是PaddleOCR，百度的开源OCR工具，中文识别精度明显高于Tesseract，而且自带版面分析、表格识别能力。实际测试中，同样一张清晰度一般的扫描件，Tesseract的错字率可能在15%左右，PaddleOCR能控制在3%以内。当然代价是依赖的库更重，第一次安装会比较费劲。
用PaddleOCR的最简流程：
from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang="ch") result = ocr.ocr("scan.png", cls=True) for line in result[0]: text = line[1][0] confidence = line[1][1] print(text, confidence)在跑OCR之前，图片预处理非常关键。我吃过不少亏才意识到，OCR引擎对图片质量极其敏感。基本预处理包括：
- 转灰度图，去掉颜色干扰；
- 拉高分辨率，OCR对小字号文字尤其依赖分辨率，建议至少300dpi以上；
- 做二值化或自适应阈值，提升文字和背景的对比度；
- 纠正倾斜角度，倾斜超过10度识别率会明显下降。
这些操作用OpenCV就能完成，代码不复杂，但效果立竿见影。一套流程预处理过的扫描件，和没预处理直接喂给OCR，识别准确率能差10个百分点以上。
2.3 Word、HTML和其他格式的解析细节
Word文档平时用得很多，解析却常被忽略。最省事的方案是docx2txt，三行代码就能把docx文本提取出来，但它做不了精细操作。如果需要保留段落格式、读取表格、处理图片，用python-docx更合适。比如要区分标题和正文：
import docx doc = docx.Document("example.docx") for para in doc.paragraphs: if para.style.name.startswith("Heading"): print("标题:", para.text) else: print("正文:", para.text)这里有个坑：docx本质是ZIP压缩包，里面是XML文件，任何依赖Word软件的解析方案都需要本机安装Word，这在Linux服务器上会遇到问题。python-docx不依赖Word，直接解析XML，兼容性更好。
网页正文抽取，我推荐trafilatura这个库。它在抽取新闻、博客正文时很准，能自动过滤导航、推荐阅读、页脚等噪音。只允许抓取你有权访问的公开信息前提下，配合requests就可以用：
import requests import trafilatura url = "https://example.com/article" html = requests.get(url, timeout=10).text content = trafilatura.extract(html) print(content)如果页面内容是JavaScript动态渲染的，requests拿不到有效正文，这时考虑Playwright或无头浏览器方案。但那类页面处理成本高，如果可以通过官方API或导出功能替代，我会优先走更稳妥的路径。
3. 知识清洗四个环节：去噪、去重、规范化、质检
3.1 去噪：先把不是内容的“内容”删干净
解析出来的原始文本，用“脏乱差”三个字形容再合适不过。页眉页脚、页码、水印、脚注、URL、特殊字符、甚至从PDF里带出来的乱码符号，全混在正文里。去噪是知识清洗的第一步，也是最机械的一步，但恰恰因为机械，很多人会忽略它的重要性。
我常用的去噪手段是正则表达式加上针对性规则。首先分析样本集里有哪些噪音，把规则一个个列出来，然后逐个测试，不要一次性写一条超长正则想把所有问题都解决，这样容易误杀正文。
典型的规则包括：
import re def clean_noise(text): # 去掉页眉页脚常见的“第X页 / Page X” text = re.sub(r"第\s*[0-9一二三四五六七八九十]+\s*页", "", text) text = re.sub(r"[Pp]age\s*\d+", "", text) # 去掉网址和邮箱 text = re.sub(r"https?://\S+|www\.\S+", "", text) text = re.sub(r"\S+@\S+\.\S+", "", text) # 去掉空行和多余空格 text = re.sub(r"\n{3,}", "\n\n", text) text = re.sub(r"[ \t]+", " ", text) return text.strip()去噪要特别小心“过度清洗”。有一个项目里，我用正则把包含“版权所有”的整行都删掉了，结果有些正文里确实提到了版权归属的句子，被误删了。后来我改成只删除出现在页眉或页脚区域的文本，而不是全局匹配。这个教训说明：去噪规则一定要限定范围，最好结合版面坐标判断一段文字是否位于页面的顶部或底部区域，而不是对所有文本无差别执行。
3.2 去重：从精确去重到近似去重
清洗完噪音后，紧接着要处理的是重复内容。重复分两种：一种是完全相同的复制，例如同一份合同在归档时被扫描了两遍；另一种是内容基本相同但细节略有差异，比如多个版本的同名报告，正文几乎一致，只有个别数据不同。
精确去重最简单，计算文本的哈希值即可：
import hashlib def exact_dedup(texts): seen = set() results = [] for text in texts: h = hashlib.md5(text.encode("utf-8")).hexdigest() if h not in seen: seen.add(h) results.append(text) return results近似去重就复杂得多。我常用的方案是simhash，它能把文本转换成64位的哈希指纹，然后通过“汉明距离”判断相似度。汉明距离小于一个阈值（比如3），就认为两条文本重复。
from simhash import Simhash def is_duplicate(text_a, text_b, threshold=3): hash_a = Simhash(text_a) hash_b = Simhash(text_b) return hash_a.distance(hash_b) <= threshold实际项目中，精确去重能解决80%的重复，simhash负责处理剩下的近似重复。需要注意的是，simhash对长文本效果更好，短文本容易出现误判，所以阈值要结合文本长度调整。另外，对于版本不同的报告，我建议只去重并保留保存时间最新的一份，而不是简单丢弃，防止丢数据。
3.3 规范化：编码、全角半角和字符统一
做过一次中文文档清洗的朋友应该都遇到过编码问题。文件来源不同，有的是UTF-8，有的是GBK，有的连BOM都没有，读取时直接乱码。规范化的第一个任务就是统一编码。
在Python里，读取文本时先尝试UTF-8，失败再用GBK或GB18030，是一个常规套路。chardet库可以帮助识别编码，但它的判断不是100%准确，所以我的习惯是：先chardet给个候选，再用解码后的文本做字符合理性检查，比如统计乱码符号占比。
第二个任务是全角半角转换。中文文档里全角符号和半角符号混杂很常见，尤其是从PDF提取出来之后，逗号、括号、引号经常变成全角或半角不统一。检索、分句时都要统一成同一种形式：
def full_to_half(text): result = [] for char in text: code = ord(char) if code == 0x3000: # 全角空格 code = 0x20 elif 0xFF01 <= code <= 0xFF5E: # 全角字符 code -= 0xFEE0 result.append(chr(code)) return "".join(result)还有Unicode规范化。有的文档里的“fi”这种连字一个字符，有的把同一个字用不同码位表示，最好统一用unicodedata.normalize("NFKC", text)处理，避免后续匹配或检索时出现奇怪问题。
3.4 质检：不设指标的去重和清洗都是自欺欺人
清洗到底做得好不好，不能凭感觉，要用数据说话。我每次处理完一批文档，都会跑一套基础质检脚本，统计以下指标：
- 清洗前后文本量的变化比例，异常波动说明可能有误删；
- 文档的平均长度、长度分布，太短的长文档要特别检查；
- 重复率，包括精确重复和近似重复的比例；
- 乱码符号占比（比如“�”字符的数量）；
- 必须保留的字段完整度，比如日期、编号、来源是否丢失。
这套质检逻辑不复杂，但对发现问题很有效。有一次我的清洗规则把PDF里大量“•”符号替换成空字符串，结果造成很多列表条目粘连在一起，文档长度显著变短。如果没有长度分布这个指标，这个问题可能要等到下游使用时才发现。
批量处理时，我还会把每次清洗的记录写成日志，内容包括文件路径、原始长度、清洗后长度、命中哪些规则。日志的作用有两个：一是方便回溯问题，二是在清洗规则更新后快速对比效果。很多项目后期要反复调整清洗规则，没有日志就只能全部重新跑一遍。
4. 清洗之后的知识组织：分块、元数据与入库
4.1 分块粒度：不要用固定长度切一切了事
清洗完成后，文档仍然是一份份长文，直接存起来其实不太好用。无论是做检索还是喂给模型，都需要把长文切分成合适大小的文本块，这个动作叫分块。
最简单的分块是按固定字符数切割，比如每500个字符切一块。这个方案实现起来容易，但在语义上很粗暴：一个完整段落可能被拦腰切断，一句话可能被拆成两半。对检索场景来说，命中的结果会不完整，对问答场景来说，喂给模型的上下文是断裂的。
我会优先考虑按文档本身的自然结构来分块。Markdown和HTML文档可以用标题层级划分，Word文档可以用Heading样式划分，PDF可以用段落层级划分。自然结构分块的优点是语义相对完整，缺点是不同文档的块大小差异很大，有的段落几十个字，有的上百字。
所以实践中往往采用“段落优先，大小兜底”的策略：先按自然段落聚合成块，尽量保持语义完整，同时设定一个最大长度和最小长度。如果段落过长，再在段落内部按句子边界切分；如果多个连续短段落合计过短，就把它们合并成一块。同时可以设置相邻块之间保留部分重叠，比如重叠一两个句子，避免检索时边界内容被遗漏。
| 分块方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 固定字符切分 | 实现简单，块大小均匀 | 语义断裂，检索质量差 | 快速原型、调试用 |
| 按段落切分 | 语义相对完整 | 块大小不稳定 | 大多数知识库场景 |
| 按标题层级切分 | 结构清晰，适合长文 | 依赖文档格式规范 | 技术文档、报告 |
| 语义分块 | 边界最符合内容逻辑 | 需要额外模型，成本高 | 高质量语料构建 |
4.2 元数据：清洗环节最容易被漏掉的一层信息
文本内容处理完了，元数据经常被忽略。很多文档如果把文件名一丢，光剩正文，就完全不知道这段内容从哪来、是哪年的、属于什么类型。这对后续的筛选、过滤、展示都是致命伤。
我通常会在解析和清洗阶段同步保留一份元数据记录，包括：
- 来源文件路径、文件名；
- 文件类型（PDF、Word、HTML等）；
- 创建时间和最后修改时间；
- 文档编号或企业内部的唯一标识；
- 所属分类或项目名；
- 清洗时间与清洗规则的版本号。
元数据可以和分块后的文本一起存储，也可以独立存储。轻量级方案是把每块文本和对应的元数据写成JSONL格式，每行一个JSON对象：
{"doc_id": "2024-001", "title": "项目报告", "source": "files/report.pdf", "block_index": 3, "text": "这是清洗后的正文段落……"}JSONL的好处是简单、可逐行读取、不依赖数据库，几千上万条数据都能处理。文件数量再大一些，可以换成SQLite，查询性能会更好。
4.3 存储选型：从轻量级JSONL到向量库
谈到存储，很多人一上来就要上Elasticsearch或向量数据库。我觉得这要分阶段。项目初期、数据量不大时，JSONL文件加SQLite已经够用。盲目引入重组件会显著增加维护成本，反而拖慢项目进度。
当然，如果你是要做语料管理、企业内部的知识平台，数据量到了几十万篇以上，那就要考虑正式方案了。这时我会倾向用Elasticsearch存储全文，配合ik分词器处理中文；如果下游要接向量检索，再加向量库，并保持文本和向量之间的主键对应。
另一个细节：入库前要给每个文档和每个分块分配稳定的ID，建议使用UUID或按日期生成的有序ID。这样后续更新、删除、去重都有据可循，不会出现“清了重复文档之后关联数据找不回来”的情况。
5. 常用工具清单与实测经验
5.1 可以直接抄作业的工具选型表
下面这张表是我目前用得顺手的工具组合，按文档类型和用途分类。工具更新迭代挺快，但这套组合在当下是稳定可用的。
| 用途 | 工具/库 | 适用场景 | 注意点 |
|---|---|---|---|
| PDF文本提取 | PyMuPDF | 快速提取文本和位置信息 | 速度最快，但复杂表格版面需配合其他工具 |
| PDF表格抽取 | pdfplumber | 规则表格还原 | 速度慢，适合表格较多的文档 |
| 扫描件OCR | PaddleOCR | 中文扫描件、复杂排版 | 依赖较大，GPU可用时效果更好 |
| OCR备选 | Tesseract | 多语言支持、轻量部署 | 中文精度一般，适合简单印刷体 |
| Word解析 | python-docx | 保留段落样式、读取表格 | 不支持doc格式 |
| Word快速提取 | docx2txt | 只关心纯文本时 | 简单但功能有限 |
| 网页正文抽取 | trafilatura | 新闻、博客、公开文章 | 对动态页面无效 |
| HTML通用解析 | BeautifulSoup | 自定义复杂HTML解析 | 需要自己写规则 |
| 编码检测 | chardet | 判断未知编码 | 只给候选，需二次校验 |
| 近似去重 | simhash | 长文本相似度判断 | 短文本误报率高 |
| 文本分块 | langchain的splitter或自写 | 语义分块 | 规则需结合文档结构设计 |
5.2 这些年踩过的几个典型坑
第一个坑来自PDF表格。有一次我处理一份财报，里面大量表格，用pdfplumber提取后，很多单元格内容顺序错乱，纯文本模式下数字和文字完全对不上。后来定位到原因是部分单元格颜色太浅，页面上有底纹线条干扰，pdfplumber把它们识别成了无框线单元格。解决办法是对页面图片做预处理再识别，或者对无框线表格改用坐标聚类方式手动恢复行列。
第二个坑是OCR的错字。PaddleOCR的准确率确实高，但对特殊字体、艺术字、印章遮挡的文字依然会错。尤其年份、金额这种关键数字，一旦识别错，下游分析就全错。后来我养成了习惯：凡是从OCR拿到的数字型字段，一律二次校验，用正则检测是不是数字，再结合上下文判断是否合理。不能盲信OCR结果。
第三个坑在Word上。某份合同文件设置了编辑保护，python-docx读出来只有第一段，后面全是空白。后来查资料才发现，Word的文档保护不仅限制人在Word里编辑，连底层XML对文本的存储都可能被分段封装。解决方法是先用zipfile检查document.xml是否被加密或分块，必要时做删除保护标记的处理。
第四个坑是网页正文抽取。有些网站看起来是静态HTML，但正文其实是页面底部的一段JSON动态拼出来的，trafilatura抓到的是空字符串。这种页面无法用普通HTTP请求拿到正文，只能回到无头浏览器方案。我的建议是：批量采集网页前，先抽5个不同页面做测试，别等几千条数据跑完才发现全抓空了。
5.3 我的工作习惯：从规则到代码都要留痕
最后分享一套我坚持了很久的工作习惯。
第一，清洗规则和解析参数全部写在配置文件里，不硬编码在脚本中。这样既能复现结果，也方便调整。比如定义一个YAML文件记录页眉页脚的正则、OCR的阈值、分块的最大长度，改动时只改配置，不碰代码。
第二，每批数据设定一个“签名”字段，可以是对全文内容的哈希，也可以是清洗规则的版本号加上时间戳。数据出问题时，一下就能定位是哪批处理的、用了什么规则。
第三，不要在大规模数据上直接调试解析和清洗代码。先在一个只有几十个文件的调试集上跑通，确认效果稳定后，再用全量数据。否则刷了半天日志，发现是正则写错了，白白浪费时间和算力。
这些经验都是在一轮轮真实项目中积累下来的。如果你刚开始接触文档解析和知识清洗，我的建议是别追求一步到位。先把手上的文档类型摸清，选一个趁手的工具跑通最小流程，再逐步叠加清洗规则和质检指标。做知识类项目最忌讳的就是急着上复杂方案，最后被数据质量拖垮。等你的清洗规则稳定、质检指标明确之后，整个流程会越来越顺手，那些一开始觉得麻烦的细节，反而会成为你项目中最大的资产。
