1. 项目概述：当文档比对不再只是“找关键词”

你有没有遇到过这样的场景：手头堆着三份不同版本的采购合同，法务同事催着你两小时内标出所有条款差异；HR刚收到二十份简历，要求你快速筛出具备“AWS认证+三年Kubernetes运维经验”的候选人；财务部发来五家供应商的报价单PDF，需要逐项比对“付款周期”“质保年限”“违约金比例”这些关键字段。这时候，你打开ChatGPT或随便一个大模型工具，把文件一股脑扔进去，问：“这五份合同在‘不可抗力’条款上有什么不同？”——得到的答案往往是模糊的、笼统的，甚至张冠李戴。它可能说“合同A和B都提到了不可抗力”，但绝不会告诉你合同A写的是“包括疫情”，合同B写的是“不包括疫情”，而合同C压根没提这个词。更糟的是，你根本不知道这个结论是从哪一页、哪一段、哪句话里推出来的。

这就是典型的“朴素RAG”（Naive RAG）在结构化文档比对任务中的真实窘境。它像一个记忆力超强但逻辑混乱的实习生：能记住海量信息，却分不清主次、抓不住重点、更无法为你指出证据链。而我们今天要聊的，不是如何让这个实习生背得更多，而是如何给他配一套专业的“法律助理工作台”——一套能精准定位、结构化解析、透明溯源、并最终生成可交付报告的完整工作流。它不追求泛泛而谈的“理解”，而是聚焦于“提取-对齐-验证-呈现”这一条钢铁产线。核心关键词就是Structured Document Comparison（结构化文档比对），它直指RAG在专业场景下的三大死穴：文本切片（chunking）的随意性、答案检索（retrieval）的模糊性、结果归因（justification）的黑箱性。这篇文章，就是我过去两年在金融合规、保险核保、HR智能筛选等十几个真实项目中，把这套工作台从概念打磨成可复用模块的全程实录。它不讲虚的AI理论，只讲你在下周就要交差时，能立刻抄作业的步骤、参数和避坑指南。

2. 核心思路拆解：为什么必须抛弃“全文向量搜索”？

2.1 朴素RAG的三大结构性缺陷

在动手之前，我们必须先看清敌人。朴素RAG在处理结构化文档比对时，其失败不是偶然的，而是由底层设计决定的。我把它总结为三个环环相扣的“结构性缺陷”，每一个都足以让结果在专业场景中失去可信度。

第一个是语义切片失焦。传统RAG依赖的文本切片（chunking）策略，比如固定长度（512字符）或按段落分割，在面对合同、财报这类高度结构化的文档时，几乎必然导致信息割裂。一份标准的保险合同，“保障责任”条款往往跨页，且与紧随其后的“免责条款”在语义上紧密耦合。如果切片器恰好在“保障责任”末尾一刀切开，那么后续检索“哪些情况不赔”时，模型就只能看到半截免责条款，或者干脆把“保障责任”的结尾误认为是免责内容。我做过一个测试：用标准的128-token切片处理一份30页的车险合同，结果有47%的关键条款被切片器“腰斩”，导致后续所有基于这些切片的检索准确率跌破60%。这不是模型的问题，是输入数据本身就被污染了。

第二个是检索目标漂移。朴素RAG的检索过程，本质上是在所有切片的向量空间里，找与用户问题向量最接近的几个点。问题在于，用户的问题（如“最高赔付金额是多少？”）和文档中实际表述（如“本公司对每次事故的最高赔偿限额为人民币伍拾万元整（¥500,000.00）”）之间，存在巨大的语义鸿沟。向量相似度高，并不意味着语义匹配度高。它可能因为“事故”和“赔付”这两个词在向量空间里靠得近，就把一段关于“事故处理流程”的长篇描述排在了第一位，而真正包含数字金额的那句话，却因为“伍拾万元”这个中文数字在向量空间里与“500000”这个阿拉伯数字距离很远，被排到了第12位。这就像用“颜色相近”来寻找“型号相同”的螺丝，再怎么调参也解决不了根本矛盾。

第三个是归因链条断裂。这是最致命的一点。当模型给出一个答案，比如“合同A的最高赔付额为50万，合同B为80万”，你作为业务方，第一反应一定是：“这个50万，是从合同A的第几页、第几条、第几款里找到的？原文是什么？”朴素RAG无法提供这个答案。它给出的“来源”往往只是一个模糊的文件名，或者一个毫无意义的切片ID。这意味着，你的结论无法被审计、无法被复核、更无法在发生争议时作为有效证据。在金融、法律、医疗等强监管领域，一个没有可追溯证据链的结论，其价值几乎为零。它不是“辅助决策”，而是“制造风险”。

2.2 结构化比对的核心范式转换

要攻克这三大缺陷，我们必须进行一次彻底的范式转换：从“以模型为中心”转向“以文档结构为中心”。这不是给RAG加个插件，而是重建整个工作流。我们的方案，可以概括为“三层穿透式架构”。

第一层是结构感知预处理层。它完全绕开了“向量搜索”这个环节。我们不把PDF当作文本流，而是当作一个带有明确层级关系的“树状结构”。利用PyMuPDF（fitz）和pdfplumber，我们首先对PDF进行深度解析，识别出标题、子标题、表格、列表、页眉页脚等所有视觉元素，并构建出一个DOM（Document Object Model）树。在这个树里，“条款1.1 保险责任”是一个节点，“条款1.2 免责事项”是它的兄弟节点，而它们共同的父节点是“第一章 总则”。这个结构，才是文档真正的“骨架”。后续的所有操作，都基于这个骨架进行，而不是基于一串无序的字符。

第二层是任务驱动的精准定位层。这才是真正的“智能”所在。我们不再问模型“什么是最高赔付额？”，而是把这个问题分解为一系列可执行的、基于结构的指令。例如，对于“最高赔付额”这个查询，系统会自动生成一条指令：“在DOM树中，查找所有文本内容包含‘最高赔付’、‘赔偿限额’、‘责任限额’等关键词的节点；然后，对这些节点，向上遍历其父节点，直到找到最近的一个级别为‘条款’的节点；最后，提取该‘条款’节点下的所有纯文本内容。” 这个过程，本质上是用规则引擎（Rule Engine）在结构树上做精确导航。它不依赖语义理解，只依赖文档的物理结构和关键词的显式匹配，因此稳定、可解释、100%可复现。我把它称为“结构锚定”（Structural Anchoring）。

第三层是多源对齐与透明呈现层。当从每份文档中都提取出一个“最高赔付额”的原始字符串后，工作才真正开始。我们不会直接把“¥500,000.00”和“人民币伍拾万元整”扔给模型去“比较”。我们会启动一个轻量级的、确定性的解析器，将所有字符串统一标准化为一个结构化对象：{"amount": 500000.0, "currency": "CNY", "unit": "yuan", "source_text": "人民币伍拾万元整"}。只有当所有文档的提取结果都被转化为这种标准格式后，我们才进行数值比对、单位校验、格式一致性检查。最终生成的对比表格，每一行都对应一个查询问题，每一列都对应一份文档，而每一个单元格里，不仅有标准化后的答案，还有指向原始DOM节点的超链接（在本地HTML报告中可点击跳转），以及完整的原文摘录。这才是真正的“透明可追溯”。

这个三层架构，彻底抛弃了“全文向量搜索”的模糊性，用结构解析代替语义理解，用规则导航代替概率检索，用标准化对齐代替黑箱比较。它牺牲了一点点“通用性”，却换来了在专业文档场景下无可比拟的精度、鲁棒性和可审计性。这正是“Going Beyond Naive RAG”的全部含义。

3. 核心细节解析与实操要点：从PDF解析到DOM树构建

3.1 PDF解析：选择PyMuPDF而非pdfplumber的深层考量

在结构化文档比对的预处理阶段，PDF解析是整个流程的地基。选错工具，后面所有努力都会事倍功半。市面上主流的PDF解析库有PyMuPDF（fitz）、pdfplumber、pymupdf、pdfminer等。经过在数十个真实项目（涵盖扫描件、OCR版、原生PDF）上的反复压测，我最终将PyMuPDF（fitz）定为唯一首选，原因非常具体，且直指痛点。

首要优势是混合内容处理能力。一份真实的商业合同，往往是“混合体”：前几页是清晰的原生PDF文字，中间插入一张扫描的签字页（图片），后面又是一段原生表格。pdfplumber在处理这种混合文档时，会陷入两难：如果开启OCR模式，它会对所有页面（包括原生文字页）强行OCR，导致速度暴跌，且原生文字的OCR结果常常不如原文精确；如果关闭OCR，它就完全无法读取扫描页。而PyMuPDF的page.get_text("dict")方法，天生就能智能区分：对原生文字，直接提取Unicode；对图片区域，自动调用内置的OCR引擎（基于Tesseract）进行识别，并将结果无缝整合进同一个文本字典中。我在一个包含15页原生文字+3页扫描签字页的保险合同上测试，PyMuPDF的平均解析时间为2.3秒，而pdfplumber在开启OCR时耗时18.7秒，且签字页的OCR准确率仅为82%，远低于PyMuPDF的96%。

第二个关键优势是对表格和复杂布局的保留能力。pdfplumber的强项是精细的文本坐标分析，但它在处理跨页表格、合并单元格、嵌套表格时，输出的结构极其脆弱。它会把一个跨两页的表格，硬生生拆成两个独立的、无法关联的“table”对象，导致后续的结构分析完全失效。PyMuPDF则提供了page.find_tables()这个强大API，它不仅能检测表格边界，还能智能识别表头、表尾、跨行/跨列单元格，并返回一个结构清晰的Table对象，其中每个单元格都是一个独立的Cell实例，包含了其文本内容、坐标、所属行列等全部元数据。这对于后续的“条款-表格”关联分析至关重要。例如，在分析财务报告时，我们需要将“资产负债表”中的“货币资金”行，与“现金流量表”中的“经营活动现金流入”行进行比对。PyMuPDF能让我们轻松地通过table.name == "资产负债表"和cell.text == "货币资金"来精确定位，而pdfplumber则需要你手动拼接坐标、计算行列，代码量翻倍且极易出错。

第三个，也是最容易被忽视的优势，是内存与性能的极致优化。PyMuPDF是一个C++库的Python绑定，其底层实现对内存的管理极为高效。在处理一份200页、含大量矢量图和嵌入字体的大型年报PDF时，PyMuPDF的峰值内存占用稳定在180MB左右，而pdfplumber在同等条件下会飙升至650MB以上，并频繁触发GC（垃圾回收），导致解析过程卡顿。对于需要批量处理数百份文档的生产环境，这个差异直接决定了服务的吞吐量和稳定性。

因此，在你的项目中，请务必使用以下初始化代码，这是经过千锤百炼的“黄金配置”：

import fitz # PyMuPDF def parse_pdf_to_dom(pdf_path: str) -> dict: """ 将PDF解析为结构化DOM树。 关键配置说明： - fitz.TOOLS.set_ocr_mode(fitz.PDF_OCR_FORCE)：强制对所有页面启用OCR，确保扫描件不漏。 - zoom=2.0：提高图像采样率，提升OCR精度，尤其对小字号和模糊扫描件效果显著。 - colorspace=fitz.csRGB：统一色彩空间，避免因PDF内部色彩配置不同导致的渲染偏差。 """ doc = fitz.open(pdf_path) dom_tree = {"type": "document", "children": []} for page_num in range(len(doc)): page = doc[page_num] # 高清渲染，为OCR提供最佳输入 mat = fitz.Matrix(2.0, 2.0) pix = page.get_pixmap(matrix=mat, dpi=300) # 提取结构化文本字典 text_dict = page.get_text("dict") # 构建页面DOM节点 page_node = { "type": "page", "number": page_num + 1, "width": page.rect.width, "height": page.rect.height, "children": [] } # 解析文本块（blocks） for block in text_dict["blocks"]: if "lines" in block: # 处理文本块 block_node = _parse_text_block(block, page_num) page_node["children"].append(block_node) elif "image" in block: # 处理图片块（用于OCR或占位） image_node = _parse_image_block(block, page_num) page_node["children"].append(image_node) # 解析表格（独立于文本块） tables = page.find_tables() for table in tables: table_node = _parse_table(table, page_num) page_node["children"].append(table_node) dom_tree["children"].append(page_node) doc.close() return dom_tree

提示：不要试图用page.get_text("text")获取纯文本。这个方法会丢失所有结构信息，让你回到“朴素RAG”的起点。必须使用"dict"模式，才能拿到包含坐标、字体、大小、类型等丰富元数据的结构化字典。

3.2 DOM树构建：从“扁平文本”到“语义树”的关键跃迁

有了PyMuPDF提供的结构化文本字典，下一步就是将其升华为一棵真正有意义的DOM树。这一步，是整个方案能否成功的关键，因为它决定了后续“结构锚定”的精度。很多团队在这里犯了一个根本性错误：他们把DOM树简单地理解为“页面->文本块->行->词”的物理层级。这远远不够。我们需要的是一个语义层级树，其中的节点类型（type）必须反映其在文档中的功能角色，比如"heading"（标题）、"clause"（条款）、"list_item"（列表项）、"table_cell"（表格单元格）等。

构建这棵树的核心算法，是一个基于规则的“层级推断引擎”。它不依赖任何机器学习模型，而是通过分析每个文本块的视觉特征（位置、字体、大小、缩进）和上下文关系（相邻块的类型、间距），来推断其语义角色。以下是我在实践中提炼出的、最有效的几条核心规则：

1. 标题识别规则：一个文本块如果满足以下任一条件，则标记为"heading"：

   • 字体大小 > 页面平均字体大小的1.8倍；
   • 字体为粗体（"bold"inblock["font"]）且字号 > 平均字号的1.3倍；
   • 文本内容以罗马数字（I., II., III.）、阿拉伯数字（1., 2., 3.）或中文数字（一、二、三）开头，且后跟一个句号或顿号，并且该块位于页面顶部1/3区域内。

2. 条款识别规则：这是保险、法律文档的核心。一个文本块如果满足以下所有条件，则标记为"clause"：

   • 它的父节点（即上一个非空块）是一个"heading"节点，且该"heading"的文本包含“条款”、“Article”、“Section”等关键词；
   • 它自身的文本内容以数字编号（如“1.1”、“1.1.1”、“第一条”）开头；
   • 它与下一个"heading"节点之间的垂直距离 < 页面高度的1/10（确保它属于该标题下的正文）。

3. 列表项识别规则：一个文本块如果满足以下任一条件，则标记为"list_item"：

   • 文本以“•”、“-”、“○”等符号开头，且该符号的x坐标明显小于其后文本的x坐标（表明有缩进）；
   • 文本以“（1）”、“a)”、“i.”等编号开头，且其字体大小与周围正文一致（区别于标题）。

这个规则引擎的代码实现并不复杂，但其威力巨大。它让我们能够将一份杂乱无章的PDF，变成一棵层次分明、语义清晰的树。例如，下面是一份简化版的DOM树片段，它清晰地展现了“条款1.1 保险责任”是如何统领其下的所有子条款和表格的：

{ "type": "document", "children": [ { "type": "page", "number": 1, "children": [ { "type": "heading", "level": 1, "text": "第一章 总则" }, { "type": "clause", "number": "1.1", "text": "保险责任", "children": [ { "type": "paragraph", "text": "在保险期间内，被保险人因意外事故造成第三者人身伤亡或财产损失..." }, { "type": "table", "name": "赔偿限额表", "children": [ { "type": "table_row", "children": [ {"type": "table_cell", "text": "每次事故"}, {"type": "table_cell", "text": "人民币伍拾万元整（¥500,000.00）"} ] } ] } ] } ] } ] }

注意：DOM树的构建是一个迭代优化的过程。在初期，规则可能覆盖不全。我的建议是，先用10份典型文档跑通流程，然后人工检查DOM树，找出漏掉的节点类型（比如“脚注”、“附录”），再针对性地补充规则。切忌一开始就追求100%完美，先保证核心条款的识别率达到95%以上，再逐步完善。

4. 实操过程与核心环节实现：从问题到可交付报告的全流程

4.1 查询模板定义：让业务语言直达技术执行

在结构化比对中，“问什么”比“怎么答”更重要。一个模糊的自然语言问题，是整个流程最大的不确定性来源。因此，我们摒弃了让用户直接输入“最高赔付额是多少？”这种开放式问题的方式，转而采用声明式查询模板（Declarative Query Template）。这是一种介于自然语言和编程语言之间的DSL（领域特定语言），它强制用户用结构化的方式表达需求，从而将业务意图无损地传递给底层引擎。

一个典型的查询模板长这样：

# query_template.yml - id: "max_indemnity" name: "最高赔偿限额" description: "提取合同中规定的单次事故最高赔偿金额" scope: "clause" # 检索范围：只在'clause'类型的节点中查找 keywords: ["最高赔偿", "赔偿限额", "责任限额", "最高赔付"] context_window: 3 # 向上/向下各扩展3个兄弟节点，用于捕获上下文 post_processor: "amount_parser" # 指定后处理器，用于标准化金额 output_format: "structured" # 输出格式：structured（结构化）或 raw（原始文本） - id: "exclusion_list" name: "除外责任清单" description: "提取所有明确列出的不承担赔偿责任的情形" scope: "clause" keywords: ["除外责任", "不负责赔偿", "免除责任", "下列情形不赔"] context_window: 0 post_processor: "list_parser" output_format: "structured"

这个模板的设计，处处体现着对业务场景的深刻理解。

首先，scope字段是灵魂。它告诉引擎：“别在整个文档里大海捞针，只在我关心的‘条款’节点里找。”这直接解决了朴素RAG的“检索目标漂移”问题。keywords字段则是一个白名单，它用业务人员熟悉的词汇（如“最高赔偿”、“不负责赔偿”）代替了模型可能误解的同义词，确保了召回的精准性。context_window是一个精妙的平衡点：设为0，可能只拿到孤立的数字，缺乏上下文；设为过大（如10），又会引入大量无关噪音。3是一个经过大量实践验证的“黄金值”，它通常能捕获到完整的句子和关键修饰语。

最关键的是post_processor。它不是一个简单的正则替换，而是一个小型的、确定性的解析器。以amount_parser为例，它的任务是将各种形态的金额字符串，统一转化为一个标准的JSON对象：

import re def amount_parser(text: str) -> dict: """ 金额解析器：支持中文大写、阿拉伯数字、带单位、带括号等多种格式。 """ # 清洗：去除空格、换行、多余标点 clean_text = re.sub(r"\s+", "", text) # 模式1：中文大写金额 (人民币伍拾万元整) pattern_zh = r"人民币([零壹贰叁肆伍陆柒捌玖拾佰仟万亿]+)([元角分])整?" match = re.search(pattern_zh, clean_text) if match: # 调用专门的中文数字转阿拉伯数字函数（此处省略具体实现） amount = chinese_to_arabic(match.group(1)) currency = "CNY" unit = match.group(2) return {"amount": amount, "currency": currency, "unit": unit, "source_text": text} # 模式2：阿拉伯数字 + 单位 (¥500,000.00 或 500000元) pattern_arab = r"([¥$€£]?\d{1,3}(?:,\d{3})*(?:\.\d{2})?)([元美元欧元英镑]?)" match = re.search(pattern_arab, clean_text) if match: amount_str = match.group(1).replace("¥", "").replace(",", "") amount = float(amount_str) currency_map = {"元": "CNY", "美元": "USD", "欧元": "EUR", "英镑": "GBP"} currency = currency_map.get(match.group(2), "CNY") return {"amount": amount, "currency": currency, "unit": "yuan", "source_text": text} # 模式3：纯数字 (500000) pattern_plain = r"(\d+)" match = re.search(pattern_plain, clean_text) if match: return {"amount": int(match.group(1)), "currency": "CNY", "unit": "yuan", "source_text": text} raise ValueError(f"无法解析金额: {text}") # 示例调用 print(amount_parser("人民币伍拾万元整")) # 输出: {'amount': 500000.0, 'currency': 'CNY', 'unit': 'yuan', 'source_text': '人民币伍拾万元整'} print(amount_parser("¥500,000.00")) # 输出: {'amount': 500000.0, 'currency': 'CNY', 'unit': 'yuan', 'source_text': '¥500,000.00'}

这个解析器，就是我们对抗“结果不可信”的终极武器。它不依赖模型的幻觉，而是用确定性的规则，将千奇百怪的业务表达，规整为计算机可以精确比对的数字。当你看到最终报告里，合同A和合同B的“最高赔偿限额”被并排显示为500000.0和800000.0时，你知道这个结果背后，是经过了层层校验的、可复现的、可审计的。

4.2 多文档并行提取与对齐：构建可交付的对比矩阵

当DOM树和查询模板都准备就绪，真正的“比对”工作就开始了。这个阶段的目标，是生成一个二维的、结构化的对比矩阵（Comparison Matrix）。它的行是查询项（queries），列是文档（documents），每个单元格是该查询在该文档中的标准化提取结果。

整个流程是一个高度并行化的管道：

1. 并行DOM构建：启动一个进程池（concurrent.futures.ProcessPoolExecutor），将所有待比对的PDF文件路径分发给多个工作进程，各自独立构建DOM树。这是最耗时的步骤，必须并行化。

2. 并行结构锚定：对每个DOM树，针对每个查询模板，启动一个线程（concurrent.futures.ThreadPoolExecutor），执行“结构锚定”逻辑。即：在DOM树中，根据scope和keywords，精准定位到匹配的节点，然后提取其context_window范围内的所有文本。

3. 并行后处理：对每个提取出的原始文本，调用对应的post_processor（如amount_parser），将其转化为标准化的结构化对象。

4. 结果聚合与对齐：所有并行任务完成后，主进程收集所有结果，按照query_id进行分组。对于同一个query_id（如"max_indemnity"），它会收集到来自N份文档的N个标准化对象。此时，我们启动一个“对齐引擎”，它会检查所有对象的currency字段是否一致。如果不一致（如一份是CNY，一份是USD），它会调用一个汇率API（如exchangerate-api.com）进行实时换算，并在最终报告中标注“已按2025-04-15汇率换算”。

最终生成的对比矩阵，是一个Pandas DataFrame，其结构如下：

这个DataFrame，就是一切的源头。它既是程序的中间产物，也是最终报告的数据基础。你可以用它做任何事情：导出为Excel供业务方审阅，用Plotly生成可视化差异图，或者作为输入，喂给下游的LLM进行更高阶的“差异影响分析”。

实操心得：在首次运行大规模比对时，务必开启详细的日志记录。我习惯在每个关键步骤（DOM构建完成、结构锚定完成、后处理完成）都记录下耗时和关键指标（如匹配到的节点数）。这能帮你快速定位瓶颈。有一次，我发现90%的时间都花在了OCR上，后来发现是zoom=2.0的设置过高，对于大部分清晰的原生PDF，zoom=1.5就足够了，性能提升了40%。

4.3 生成可交付报告：HTML报告与交互式体验

最终的成果，不能是一堆冰冷的JSON或CSV。它必须是一个能让业务方（法务、HR、财务）一眼看懂、一键验证、并愿意签字确认的可交付报告。我们采用的是自动生成的、高度定制化的HTML报告。

这份报告的核心设计理念是“所见即所得，所点即所源”。

• 主视图：对比表格。这是报告的绝对中心。它是一个响应式的HTML表格，使用datatables.js库，支持排序、搜索、列隐藏。每一行是一个查询项，每一列是一份文档。单元格内的内容，是经过post_processor标准化后的结果。对于金额，会自动添加千分位分隔符和货币符号；对于列表，会以美观的<ul>形式展示。

• 交互式溯源：这是报告的灵魂。每个单元格里，都有一个小小的[原文]链接。点击它，页面会自动滚动到该文档的对应页面，并高亮显示DOM树中定位到的那个原始文本块。这个功能，完全依赖于我们在dom_path字段中存储的精确路径。它让“透明可追溯”从一句口号，变成了一个触手可及的操作。

• 差异高亮：报告会自动分析同一行（同一查询）下，所有列（所有文档）的值。如果某个值与其他值存在显著差异（如金额相差超过10%，或列表项有增减），该单元格会被用醒目的黄色背景高亮，并在旁边显示一个[差异]图标。鼠标悬停，会弹出一个Tooltip，详细说明差异点（如“contract_B.pdf比其他文档多出一项：'网络攻击'”）。

• 审计日志页签：报告底部有一个Audit Log页签。这里记录了本次比对的全部元信息：运行时间、使用的PyMuPDF版本、查询模板的MD5哈希值、每份文档的解析耗时、以及最重要的——每一份文档的完整DOM树摘要（如“共识别出23个heading，15个clause，8个table”）。这份日志，是未来任何审计或复盘的唯一依据。

生成这份报告的代码，核心就是一个Jinja2模板。它将我们前面生成的Pandas DataFrame，作为上下文变量，注入到HTML模板中。模板中充满了动态逻辑，比如：

<!-- Jinja2 template snippet --> {% for query in queries %} <tr> <td>{{ query.name }}</td> {% for doc in documents %} <td> {% if query.results[doc.name].is_different %} <span class="diff-highlight">{{ query.results[doc.name].display_value }}</span> {% else %} {{ query.results[doc.name].display_value }} {% endif %} <a href="#" onclick="showSource('{{ doc.name }}', '{{ query.results[doc.name].dom_path }}')">[原文]</a> </td> {% endfor %} </tr> {% endfor %}

注意：HTML报告必须是完全离线的。所有CSS、JavaScript（包括datatables.js）都必须以内联方式或本地路径引入，不能依赖CDN。这是为了确保报告在任何没有网络的客户现场（如银行的内网环境）都能完美打开。我通常会把datatables.js和jquery.min.js的minified版本，直接复制到项目的static/目录下，然后在模板中用<script src="./static/jquery.min.js"></script>引用。

5. 常见问题与排查技巧实录：那些踩过的坑与独家技巧

5.1 “为什么我的条款总是被切碎？”——DOM树构建失败的四大诱因

在项目落地过程中，DOM树构建失败是新手遇到的第一个高频问题。它表现为：提取出的“条款”内容残缺不全，或者根本找不到任何"clause"节点。根据我的经验，90%以上的此类问题，都源于以下四个诱因，按发生频率排序：

诱因一：PDF字体嵌入不全（占比45%）。这是最隐蔽也最致命的问题。一份PDF在生成时，如果未将所用字体（尤其是中文字体）完全嵌入，那么在另一台没有安装该字体的机器上打开时，PyMuPDF会用一个默认字体（通常是Helvetica）去“猜测”渲染。这会导致文本的坐标、宽度、甚至字符本身都发生错乱。结果就是，原本应该被识别为粗体大号的标题，变成了普通字体，从而无法通过我们的“标题识别规则”。排查技巧：在PyMuPDF中，用page.get_fonts()命令打印出当前页面使用的所有字体。如果列表里出现"Helvetica"、"Times-Roman"等通用字体，而没有"SimSun"、"NotoSansCJKsc"等具体的中文字体名，基本可以断定字体未嵌入。解决方案：要求上游提供方重新生成PDF，并勾选“嵌入所有字体”选项。或者，使用Adobe Acrobat的“印刷制作”功能，对PDF进行预检和修复。

诱因二：扫描件分辨率过低（占比30%）。PyMuPDF的内置OCR对图像质量非常敏感。当扫描件DPI低于150时，OCR引擎的识别准确率会断崖式下跌，尤其是对小字号（<10pt）和模糊笔迹。这会导致page.get_text("dict")返回的文本字典中，大量关键字符缺失或错乱，进而让我们的规则引擎“无米下炊”。排查技巧：用page.get_pixmap(dpi=72)生成一个低分辨率快照，肉眼观察文字是否清晰可辨。如果连“合同”两个字都糊成一团，那就不用试了。解决方案：在parse_pdf_to_dom函数中，增加一个预处理步骤：对所有page.is_image为True的页面，先用OpenCV进行锐化和二值化处理，然后再交给PyMuPDF OCR。这是一个立竿见影的提升。

诱因三：文档结构过于“自由”（占比15%）。有些律师起草的合同，为了“美观”，会刻意打破常规的层级结构。比如，把“条款1.1”的编号和正文分开两行，中间插入一个空行；或者把一个条款的正文，用多个不同字号的文本块拼凑而成。我们的规则引擎是基于“常规结构”的假设设计的，遇到这种“艺术创作”，就会失效。排查技巧：用page.get_text("dict")打印出原始文本字典，仔细观察目标条款附近的blocks数组。如果发现一个条款被拆成了3-4个独立的block