做内容中台和知识库的朋友大概都碰过这个活：手上一批 Word 交底文档、技术白皮书 PDF、还有一些扫描件，要求统一转成结构化 XML，喂给下游的检索、排版、归档系统。需求方一般只给一句话——“转成 XML”，但真正落地的时候你会发现，这句话背后藏着一整套工程问题：什么算“高质量”？Word 和 PDF 凭什么能用一套流程处理？标题层级丢了怎么补？跨页表格怎么接上？我前后在三个不同规模的项目里干过这件事，从最初直接调库一把梭，到后来老老实实拆成三层管线，踩的坑足够写一篇长文。
这篇东西面向的是需要真正把文档转出可用 XML 的开发者、内容工程师和技术文档负责人，不管你之前只写过几行python-docx，还是已经在折腾版面分析模型，下面的拆解应该都能对上你的场景。核心关键词就三个：Word/PDF 解析、结构化 XML、语义标签映射。我不打算讲“XML 是什么”这种基础，直接进入工程细节。
1. 先把"高质量 XML"这件事定义清楚
很多人一上来就问用什么库，这个问题其实问早了。真正决定项目成败的是你对“高质量”的定义。我见过最典型的失败案例是：脚本跑通了，输出了几百个.xml文件，用浏览器打开也不报错，需求方验收的时候翻了两个文件就说不行。原因是转出来的东西长这样：<p><strong>第一章 概述</strong></p>，标题就是一段加粗的段落。文件是合法的 XML，但下游拿不到任何结构信息，目录生成不了，锚点定位不了，检索权重也没法按标题加权。这种活干完等于白干。
1.1 结构质量：从"能打开"到"能机器消费"
XML 的质量其实有三个清晰的台阶，我在项目里习惯把它们当作三个验收关卡。第一关是well-formed，也就是标签闭合正确、属性加引号、有唯一根节点，这关靠解析器就能保证，基本不会有人栽在这里。第二关是valid，能通过 XSD 或 DTD 校验，元素名、层级、属性都符合你定义的词汇表，这关开始有门槛了，因为你需要先有一份 Schema，而很多团队是先写转换代码、后补 Schema，顺序反了就会反复返工。第三关是语义可消费，这才是真正的分水岭——下游程序能不能只靠 XML 就还原出文档的逻辑骨架，而完全不需要回看原始文件。
举个具体的判断标准：把转好的 XML 丢给一个完全没见过原文的人，让他基于标签画出一份目录树和表格清单，如果他能画对 90% 以上，结构质量就过关了。这个测试方法比任何指标都直接，我在两个项目里都用过，非常好使。
1.2 内容质量：保真是有预算的
必须接受一个现实：转换不可能 100% 无损。Word 里的浮动文本框、艺术字、SmartArt、带旋转的图形组合，这些东西在语义 XML 里几乎没有对应表达。硬要保真，你就得把整页渲染成图片塞进去，那还不如直接交付 PDF。
我的做法是在项目启动阶段就跟需求方明确一张保真清单，把内容分成三档。第一档是必须逐字无损的：正文文字、数字、单位、上下标、公式符号、表格里的每一个单元格值，这些错一个字符都是事故。第二档是允许结构近似的：多栏排版可以拍平成单栏，首字下沉可以退化成普通段落，页眉页脚可以抽取成元数据而不进入正文流。第三档是允许丢弃的：装饰性边框、底纹颜色、页码、水印。这张清单写进需求文档，后面所有争议都有依据。
提示：保真清单必须由需求方签字确认，尤其是"页码是否保留"这一条。页码看着无关紧要，但如果下游要做引用定位，缺了它会非常麻烦。
1.3 语义质量：标签体系别拍脑袋
标签体系的设计有个很实际的取舍：递归结构还是平铺结构。递归就是<sec><title>...</title><sec>...</sec></sec>，靠嵌套表达层级；平铺就是<h1>到<h6>一路排列，靠标签名表达层级。递归结构更适合章节深度不确定的长文档，XPath 查询也优雅；平铺结构更适合深度固定、需要快速切片的内容，比如一段一段喂给检索系统。
我在一个技术手册项目里选了递归，因为那批文档章节深度从两层到五层都有；在另一个政策条文集的项目里选了平铺，因为结构就是"章-条-款"三层，固定死了，平铺反而查询更快。选哪个不是技术问题，是内容形态问题。判断方法很简单：统计一下你所有源文档的标题层级分布，如果第 4、5 级的出现频率低于 5%，平铺加一个通用<h>带level属性就够用了。
2. 整体链路与方案选型
搞清楚质量定义之后，才轮到架构。我最开始的做法是写一个大函数，读文件、判断类型、分叉处理、直接拼 XML 字符串。这套东西在样本量小于 50 的时候勉强能用，一旦上千份就彻底失控——因为你没有任何中间态可以检查，出了问题只能靠肉眼比对原文和输出。
2.1 三段式管线：解析层 / 归一化层 / 序列化层
后来我把流程拆成了三层，这个改动是整个项目里收益最大的一次重构。解析层只负责一件事：把 Word 或 PDF 变成统一的内存结构，也就是中间表示（IR），不管源格式多恶心，出口必须是干净的 Python 字典或对象。归一化层在 IR 上做清洗和修补：字符规范化、标题层级补全、表格矩阵化、空段落剔除。序列化层把 IR 渲染成目标 XML，做标签映射、属性填充、命名空间声明、缩进美化。
拆开之后的好处立竿见影。调试的时候可以直接print(ir)看中间态，问题定位从“猜哪一步坏了”变成“看 IR 对不对”。加新格式的时候，比如后来要支持 Markdown，只需要再写一个解析器，后面两层完全复用。归一化规则调整的时候，也不用再碰解析代码，改动风险大幅降低。
代价是代码量大概多了 40%，多了一层数据结构定义。但考虑到你后面要反复调规则、加格式、修 bug，这笔投入一两个月就能回本。
2.2 Word 和 PDF 必须走两条完全不同的路
这是新手最容易犯的错：以为有个万能库能同时搞定两种格式。真相是，Word 和 PDF 的信息密度差了一个数量级，处理策略必须分开设计。
| 维度 | Word（.docx） | |
|---|---|---|
| 内部结构 | 完整的段落、样式、层级对象树 | 只有绘图指令和字符坐标 |
| 标题识别 | 读样式名即可，准确率接近 100% | 靠字号、字重、间距推断，准确率 70%~90% |
| 表格识别 | 有明确的表格对象和单元格边界 | 靠线条检测或文本对齐推断 |
| 阅读顺序 | 文档流本身就是顺序 | 必须重建，多栏和浮动元素是灾难 |
| 扫描件 | 不存在这个概念 | 需要 OCR，误差叠加 |
| 主要难点 | 样式不规范、嵌套混乱 | 版面复杂、字符编码异常 |
看清这张表，方案就明确了：Word 走样式驱动的解析路线，PDF 走几何驱动的解析路线。两者的 IR 出口统一，但内部实现没有任何复用空间，别在这上面浪费时间。
2.3 目标词汇表怎么选
自建还是用现成的，这个决定影响后面所有的标签命名。我把常见的几个选项列出来对比：
| 词汇表 | 适合场景 | 优势 | 局限 |
|---|---|---|---|
| DocBook | 技术文档、书籍 | 元素丰富，工具链成熟 | 元素太多，学习成本高，容易用错 |
| TEI | 人文社科、古籍、校勘 | 学术表达能力强 | 通用业务场景显得笨重 |
| JATS | 学术期刊、论文 | 元数据规范清晰 | 面向期刊，业务文档适配差 |
| 自建最小集 | 企业内部、检索入库 | 完全贴合业务，易维护 | 需要自己写 Schema 和校验 |
我的实际选择是自建最小集 + 借鉴命名。核心元素控制在 15 个以内：doc、meta、sec、title、p、list、item、table、row、cell、figure、formula、note、ref、code。这个集合覆盖了绝大多数业务文档，新同事半小时就能记住。命名风格上参考 DocBook 的简短风格，但只借名字不借复杂度。
注意：一旦词汇表定下来并开始产出数据，改名的成本极高。定版前务必把未来两年可能的内容类型都过一遍，尤其是公式、脚注、交叉引用这三类，最容易在后期才发现没位置放。
3. Word 侧实操：从样式树里挖结构
Word 这一侧的核心认知是：.docx 本质上是个 zip 包，里面是一堆 XML。你把后缀改成.zip解压，会看到word/document.xml，打开它你就能看到所有内容。这个认知很重要，因为它意味着你完全可以绕开所有第三方库，直接读原始 XML——当然一般没必要，但遇到库不支持的特性时，这是最后的退路。
3.1 为什么不能直接用 Word 自带的"另存为 XML"
有人会想，Word 本身就能导出 XML，为什么还要写代码？因为 Word 导出的是 WordprocessingML，标签长这样：<w:p><w:pPr><w:pStyle w:val="Heading1"/></w:pPr><w:r><w:t>第一章</w:t></w:r></w:p>。这是排版描述语言，不是语义标记。它告诉你"这段用了 Heading1 样式、里面有个文本运行"，但你的下游系统要的是"这是一个一级标题，内容是第一章"。中间那层映射还是得你自己做。
更要命的是 WordprocessingML 的元素数量超过 200 个，属性更多，直接喂给业务系统谁看谁崩溃。所以正确做法是：读 WordprocessingML，映射成自己的最小词汇表，输出语义 XML。别偷这个懒。
3.2 工具取舍与骨架代码
Python 生态里几个常见选择，我按实际使用体验说一下。
python-docx是最主流的，API 友好，段落、表格、样式都能直接访问，缺点是它默认会做一些“友好化”处理，比如自动合并相邻的相同格式 run，有时候会吞掉你需要的信息。docx2python更偏内容抽取，输出嵌套列表，做纯文本导出很快，但结构信息保留得不够细致。mammoth是 Node 生态的，主打 docx 转 HTML，思路很对（强调语义映射），Python 里有个mammoth包但功能弱一档。pandoc是万金油，命令行一把梭能出很多格式，缺点是它的 XML 输出受限于它自己的 AST，你想要的自定义标签它不一定支持，而且批量处理时启动开销不小。
我的组合是：python-docx 做主体解析，遇到它搞不定的特性时直接 lxml 读原始 XML 兜底。骨架大概长这样：
from docx import Document from docx.table import Table from docx.text.paragraph import Paragraph def iter_block_items(parent): """按文档流顺序交替产出段落和表格，这是关键""" from docx.oxml.ns import qn parent_elm = parent.element.body for child in parent_elm.iterchildren(): if child.tag == qn('w:p'): yield Paragraph(child, parent) elif child.tag == qn('w:tbl'): yield Table(child, parent)这段代码的价值在于顺序。很多人直接doc.paragraphs然后doc.tables分开遍历，结果所有表格都被挪到文末，位置信息全丢了。用iter_block_items才能保证段落和表格按照原文的先后顺序被处理，这是能否还原正确阅读顺序的第一道关口。
3.3 样式到标签的映射表怎么建
拿到段落之后，核心工作是判断它是什么。Word 里最可靠的信号是paragraph.style.name，但这里有个大坑：样式名会因语言版本而不同。同一份文档，在英文版 Word 里叫Heading 1，中文版里可能是标题 1，还有些模板会自定义成1级标题、H1、章标题。如果你的映射表只写了一行Heading 1 -> h1，那中文文档全军覆没。
我的做法是建一张 YAML 映射表，用正则匹配 + 优先级来兜底：
style_map: - pattern: '^(Heading|标题)\s*([1-6])$' tag: 'h{2}' - pattern: '^(Title|标题)$' tag: 'h1' - pattern: '^(Subtitle|副标题)$' tag: 'p' attrs: {role: 'subtitle'} - pattern: '^(List Paragraph|列表段落)$' tag: 'item' - pattern: '^(Caption|题注)$' tag: 'caption' - pattern: '^(Quote|引用)$' tag: 'quote' - pattern: '.*' tag: 'p'最后那条通配规则很重要，它是兜底用的。解析器按顺序匹配，命中第一条就停，所以具体规则一定要排在通配规则前面。这张表我建议单独放一个配置文件，别硬编码在代码里，因为不同客户、不同批次的文档样式命名差异极大，改配置比改代码安全得多。
除了样式名，还有两个辅助信号可以用来纠错。一是字号，如果某个段落样式是Normal但字号明显大于正文中位数，很可能是个没套样式的标题，我一般会把这种情况标记出来人工确认。二是编号，段落文本以“一、”“（一）”“1.1”开头且字数少于 40 的，大概率是标题，可以作为交叉验证。
3.4 表格、合并单元格、嵌套列表的处理
Word 表格最麻烦的是gridSpan（横向合并）和vMerge（纵向合并）。python-docx 的cell.text在合并单元格上会重复返回同一份内容，直接遍历会导致数据重复、列对齐全乱。
正确的做法是先把表格还原成一个规整的二维矩阵，再序列化。思路是：先计算出总列数（所有行的 gridSpan 之和的最大值），然后逐行遍历，遇到横向合并就在矩阵里占多个位置并记录colspan，遇到纵向合并就沿用上一行的内容并记录rowspan。这个过程写起来大概七八十行代码，但没有捷径。
输出的时候，合并信息放在属性里：
<table id="t1" cols="4"> <row> <cell rowspan="2" colspan="1">类别</cell> <cell colspan="3">指标说明</cell> </row> <row> <cell>上限</cell> <cell>下限</cell> <cell>单位</cell> </row> </table>嵌套列表要单独说。Word 的多级列表不是靠样式表达的，而是靠numPr里的numId和ilvl。ilvl就是层级，从 0 开始。你需要读取paragraph._p.pPr.numPr.ilvl.val拿到层级，然后用一个栈来维护当前列表的嵌套关系，遇到同级就新开<item>，遇到更深一级就嵌套<list>，遇到更浅就出栈。这块逻辑不复杂但很容易写错，建议用几个精心构造的测试文档反复验证，尤其是“跳级”的情况（从层级 0 直接到层级 2），实际文档里真会出现。
4. PDF 侧的实操：版面分析加文本回填
PDF 是完全不同的物种。它本质上是“如何在纸上画字”的指令集合，每个字符带着自己的坐标、字体、字号、颜色被画到指定位置。文档的“结构”从头到尾都不存在，你要做的是从几何信息里反推出结构。这个过程本质上是启发式的，别指望 100% 准确，目标是做到 90% 以上然后接受人工抽检。
4.1 PDF 只有坐标，先搞清楚你要抽什么
打开一个 PDF 解析出来的词列表，你会看到类似这样的东西：{'text': '第一章', 'x0': 72.0, 'x1': 108.5, 'top': 96.2, 'bottom': 114.8, 'size': 18.0}。页面上所有文字都变成了这样一个个带坐标的矩形框，没有任何顺序保证。
所以 PDF 侧的完整流程是：先抽所有词，再按坐标聚成行，再按行聚成块，再按字体特征分类，最后按位置排序。每一步都有一堆参数要调，下面逐个说。
工具选择上，pdfplumber适合抽词和表格，坐标信息给得很细，调试方便；PyMuPDF（fitz）速度明显更快，适合大批量处理，但 API 的风格不太一样。我的常规组合是：批量跑用 PyMuPDF 抽基础信息，需要精细表格处理的时候降级到 pdfplumber 局部处理。速度差距实测在三到五倍，文档量大时这个差距很致命。
4.2 行与块的聚类：容差怎么算
把词聚成行，靠的是纵坐标重叠。这里的关键参数是行容差，我一开始拍了个 2 像素，结果大部分文档都正常，遇到几份字号混排的文档就崩了。后来改成动态计算：
sizes = [w['size'] for w in words if w['size'] > 0] median_size = statistics.median(sizes) line_tol = median_size * 0.5 # 行容差：半个中位字号 col_gap = median_size * 1.5 # 断行阈值：1.5 倍字号以上的横向空隙为什么是 0.5 倍？因为同一行内不同字号的字符，垂直中心最多偏移半个字号；超过这个量级基本就是两行了。为什么断行阈值用 1.5 倍？因为正常词间距大约在 0.25 到 0.5 个字号之间，而栏间距通常是 2 个字号以上，1.5 是个偏保守的安全值，宁可少断也不要错断——断错了会把一行拆成两段，反而更难修。
聚成行之后，再按行距把行聚成块。段落之间的行距一般会大于段内行距，我用的判据是：gap > median_line_gap * 1.4就认为是段落边界。这个 1.4 的系数同样是通过观察几十份文档的行距分布定下来的，不是拍脑袋。
4.3 用字号直方图定标题层级
标题识别的核心假设是：标题的字号大于正文。做法是先统计全文档的字号频次，取出现次数最多的那个字号作为正文字号基准（这个统计方法很稳，因为正文永远占大头），然后把明显大于基准的字号按大小排序，映射到 h1 到 h6。
有几个细节能显著提升准确率。第一，加个字符数过滤：一个字号很大的块，如果字符数超过 40，大概率是封面大标题或者引文，不该进正文层级；真正的小标题通常很短。第二，考虑字重：有些文档的标题字号和正文一样，只是加粗，这时候要把fontname里的Bold特征也纳入判断。第三，位置加权：靠近页面上部、且前面有较大空白间隙的块，是标题的概率更高。这三条规则叠起来，我在几批技术文档上测的标题识别准确率从七成提到了九成左右。
from collections import Counter sizes = Counter(round(w['size']) for w in all_words) body_size = sizes.most_common(1)[0][0] # 正文基准字号 head_sizes = sorted({s for s in sizes if s >= body_size * 1.15}, reverse=True) size_to_level = {s: f'h{i+1}' for i, s in enumerate(head_sizes[:6])}1.15这个系数是经验值，低于它会误判（有些文档正文和标题只差一个磅值），高于 1.3 会漏判小标题。另外记得给size_to_level做个兜底，如果head_sizes超过 6 个，多出来的全部映射到 h6，别让层级溢出。
4.4 阅读顺序重建：PDF 转换最大的坑
多栏排版是 PDF 转换的重灾区。一个双栏页面，如果按坐标简单从上到下排，你会得到“左栏第一行、右栏第一行、左栏第二行、右栏第二行”这种交错的结果，完全没法读。
我的处理顺序是：先检测栏数，再按栏分块，最后栏内排序、栏间拼接。检测栏数的办法是画一条横向投影线：把页面上所有文本块的 x 区间累加成一个数组，找那些“所有块都不覆盖”的 x 区间，这些空白带就是栏分隔线。如果找到 1 条贯穿全页的空白带，就是双栏；2 条就是三栏。
页眉页脚要单独处理。判据是两个：一是位置，出现在页面上边缘 8% 或下边缘 8% 区域内的；二是重复，在多页的相同位置出现相似内容的。命中的块直接抽到<meta>里，不进入正文流。这个处理一定要做，否则每个页面的页码和文件标题都会混进正文，噪音极大。
跨页表格和跨页段落也是常见问题。段落好办，比较上一页最后一个块和下一页第一个块的行距特征，接近就合并。表格麻烦些，我的做法是：如果上一页最后一个表格没有闭合边框（底边线缺失），且下一页开头是个没有表头的表格，就尝试合并。这个启发式规则准确率大概七八成，剩下的靠人工抽检标记。
4.5 扫描件：OCR 加版面检测的组合拳
扫描件是另一个量级的问题。整页就是一张图，没有文字层，必须先 OCR。预处理这一步千万别省：转灰度、二值化、去噪、纠偏，四步做完再送 OCR，识别率能差出十几个百分点。分辨率上，300 dpi 是个比较稳的起点，低于 200 dpi 小字号基本废掉，高于 400 dpi 收益递减但耗时线性增长。
版面检测现在有现成的模型可用，输出的是区域框加类别（文字、标题、表格、图片）。拿到区域框之后，流程就跟文字版 PDF 接上了：按区域坐标排序、区域内做 OCR、按类别映射到不同标签。这里有个容易忽略的点——OCR 结果是按行返回的，但表格区域里的行可能是跨单元格的，得先用线条检测把表格结构拿出来，再把每个单元格区域单独送 OCR，最后拼装。直接整块 OCR 会把表格拍成一堆错位的文本行。
5. 归一化层：把脏数据洗成可校验的树
前面两层跑完，你手上大概是一棵还算像样的 IR 树，但里面一定有一堆脏东西。归一化层的工作就是把它们清理掉，让序列化层可以不加判断地直接渲染。
5.1 中间表示长什么样
IR 我用的是嵌套字典，结构大概这样：
{ "type": "doc", "meta": {"title": "...", "source": "a.docx", "pages": 12}, "children": [ {"type": "h1", "text": "第一章 概述", "id": "sec-1"}, {"type": "p", "text": "正文内容……", "style": "body"}, {"type": "table", "cols": 3, "rows": [ [{"text": "类别", "rowspan": 1, "colspan": 1}, ...] ]} ] }这个结构的核心是扁平的 children 列表 + 显式的 type 字段。为什么不直接做成递归的sec嵌套？因为 Word 的标题层级经常跳级（从 h1 直接到 h3），扁平结构允许你先收集再修补，等层级补全之后，在序列化阶段再决定要不要包成嵌套的sec。这个“先扁平后嵌套”的策略救过我好几次。
5.2 字符清洗：那些看不见的坑
字符层面的问题看着琐碎，但每一个都能让下游的检索和比对出错。我整理了一份必做的清洗清单：
| 问题类型 | 具体表现 | 处理方式 |
|---|---|---|
| 全角半角混用 | 数字、括号、冒号全角 | 数字和标点统一转半角，中文标点保留 |
| 连字字符 | PDF 抽出的 fi、fl、ff | 展开成 fi、fl、ff |
| 软连字符 | 行末断词留下的 0xAD | 直接删除并拼接前后词 |
| 不间断空格 | 0xA0，视觉上和空格一样 | 转成普通空格 |
| 零宽字符 | 0x200B，肉眼不可见 | 全部删除 |
| 中英文间距 | PDF 抽取后中英文间无空格 | 按规则补入或保持，需统一策略 |
| 重复空格 | 排版对齐留下的连续空格 | 压缩为单个 |
| 段落断词 | PDF 行末连字符跨行断开 | 检测行末连字符，与下一行首拼接 |
这张表我建议直接做成一个clean_text()函数，所有文本入口都过一遍。别嫌麻烦，我曾经因为没处理软连字符，导致同一个术语在检索系统里出现了七种不同拼法，排查了半天才发现问题出在 PDF 的断词上。
5.3 Schema 校验和流水线卡口
XML 生成完不校验，等于没做完。XSD 写起来不难，关键是别写得太严。我第一版 XSD 把每个元素的属性都限制死了，结果任何一点异常都会导致整批文件校验失败，最后只能把校验关掉。后来改成分层校验：必填元素和结构层级严格校验，可选属性和文本内容宽松处理，校验失败的文件单独落到一个quarantine目录，不阻断整批流程。
from lxml import etree def validate(xml_path, xsd_path): schema = etree.XMLSchema(etree.parse(xsd_path)) doc = etree.parse(xml_path) if not schema.validate(doc): errors = [f"{e.line}: {e.message}" for e in schema.error_log] return False, errors return True, []校验放在 CI 里跑更有价值。每次转换规则改动，跑一遍回归样本集，看校验通过率和结构指标有没有退化。这套东西建立起来之后，改规则的胆子会大很多，因为你知道有网兜着。
6. 质量评估与常见问题排查
转换质量不能靠感觉，得有指标。我用的三个核心指标是：字符级召回率、块级结构 F1、表格单元格准确率。第一个衡量文字有没有丢，第二个衡量结构对不对，第三个单独盯表格这个最大的风险点。
6.1 指标怎么算
字符级召回最简单：把源文档的纯文本和输出 XML 的纯文本都做规范化（去空白、统一标点），然后算1 - edit_distance / len(source)。这个指标低于 0.98 就要查原因了，通常是 OCR 错误或者表格内容丢失。
块级结构 F1 需要人工标注一批样本，标出每个块的类型（标题/段落/表格），然后跟输出比对算精确率和召回率。这个成本高，但样本量不用太大，两三百个块就能看出问题。我在项目里标了 500 个块，每次规则大改后重跑，能及时发现“修复了一个问题、引入了两个新问题”的情况。
表格单元格准确率单独算，因为它是加权最高的部分。做法是人工核对表格里的值，错一格算一个错误。我给自己定的目标是 99%，实际在文字版 PDF 上能做到 99.5% 左右，扫描件大概 97%。
6.2 常见问题速查表
下面这张表是我这些年攒下来的问题清单，基本都是高频出现的：
| 现象 | 大概率原因 | 排查方向 |
|---|---|---|
| 输出 XML 为空或极少 | 解析器读到了空文档，或者样式匹配全落到兜底规则 | 打印 IR 中间态，看 children 长度 |
| 标题层级全是一级 | 字号聚类只识别出一个层级，或样式名全一致 | 检查字号直方图分布 |
| 表格内容重复 | 合并单元格未做矩阵化，直接被遍历 | 检查 gridSpan/vMerge 处理逻辑 |
| 中文变乱码或方框 | PDF 字体缺少 ToUnicode 映射 | 换解析库试试，或降级 OCR |
| 阅读顺序错乱 | 多栏排版未检测，或绝对定位元素干扰 | 打印坐标，检查栏分隔检测 |
| 段落被拆成多段 | 行距聚类阈值过小 | 调大 gap 系数，从 1.4 试到 1.8 |
| 段落被合并成一段 | 行距阈值过大，或首行缩进未识别 | 检查首行缩进特征是否被忽略 |
| 校验批量失败 | XSD 过严，或必填属性缺失 | 分层校验，先过结构再管属性 |
| 处理速度极慢 | 逐页调用重量级解析，未做批处理 | 换 PyMuPDF，或分页并行 |
6.3 几条踩坑换来的经验
别用“一个脚本通吃”。我试过写一个自动判断格式、自动选择策略的万能入口，结果发现 Word 和 PDF 的参数没有一个能共用，最终那个函数变成了一个巨大的 if-else 分支，可读性极差。老老实实写两个模块，各自调优，比什么都强。
样本集比代码重要。项目初期我花了两周时间收集和标注 200 份有代表性的文档，包括正常文档、复杂表格、多栏排版、扫描件、带公式的、带脚注的。后面每次改规则都拿这批样本回归。没有这个样本集，所有的“优化”都是盲改。
人工抽检不能省。自动化指标能发现大问题，但发现不了“标题识别对了、但层级映射反了”这种逻辑错误。我一般每批抽 20 份，手工看一遍目录结构，二十分钟的事，能拦住很多低级错误。
字体信息不要丢。PDF 解析的时候顺手把字体名和字重记下来，分类的时候用得上。有些文档标题不加粗不放大，全靠字体区分，比如正文用宋体、标题用黑体，这个信号在中文文档里非常常见，别浪费。
先跑通再优化。我最开始总想着一步做到完美，结果卡在表格合并的逻辑上两周没进展。后来改成先输出能用的版本（表格拍平成段落），让下游先接上，再回头做表格结构化，整个项目节奏才顺过来。
给 id 加稳定规则。每个<sec>和<table>都要有 id，方便下游引用。id 的生成别用随机数，用“章节路径哈希”或者“序号 + 标题 slug”，保证同一份文档重复转换时 id 一致，不然下游的增量更新会疯掉。
6.4 一个容易被忽略的收尾动作
转换完别急着交付，最后一步做反向验证：写个小脚本读你的 XML，按标签重新渲染成纯文本或 HTML，然后跟原始文档做并排对比。这一步能暴露出很多“格式正确但内容错位”的问题，比如表格的行列转置了、列表项丢失了、脚注挂错了位置。我现在的标准流程里，这一步和 Schema 校验是绑定的，缺一不可。
另外，输出 XML 的可读性也别忽视。加个缩进美化器，按层级缩进两个空格，长文本行做适当换行。这东西不影响程序解析，但会极大影响人工 review 的效率——毕竟你总要有人去看的，一堆挤在一行里的 XML 谁看谁头疼。
最后一个我自己的习惯：每批转换任务留一份原始文档到输出的映射日志，记录每份文件走了哪条分支、命中了哪些规则、耗时多少、有没有告警。出问题的时候按日志往回查，比重新跑一遍快得多。这个日志我一般用 JSONL 存，一份文件一行，方便 grep。
