AI Agent Engineer

AI Agent Engineer

结构、标题、列表与表格

9 min read

结构、标题、列表与表格

本节目标

把“纯文本抽取”升级为结构化元素：保留标题层级、列表、代码、表格、阅读顺序和来源位置，并能区分源文档显式提供的结构与解析器推断出的结构。

为什么一串文字不够

句子“必须禁用外部工具”如果位于“高风险操作”标题下，含义与适用范围就依赖标题路径。表格中的 0.92 若丢掉行名、列名和单位，也无法安全回答问题。对 RAG 来说，结构既帮助切块和召回，也是引用与人工复核的证据。

常见元素包括：

  • title、heading、paragraph；
  • 有序/无序 list_item 及嵌套层级；
  • code_block、语言和原始空白；
  • table、行、列、表头、合并关系与 caption；
  • 图片、公式、脚注、页眉/页脚；
  • 页面、坐标、字符/词范围和阅读顺序。

显式结构与推断结构

HTML 的 <h2>、Markdown 的 ## 和 DOCX 样式可能显式表达标题。PDF 页面上“字号大且加粗”只是视觉特征，未必真是标题。建议为元素记录：

  • structure_source: explicit | inferred；
  • 推断器与版本；
  • 使用的规则或模型配置；
  • 可选置信信号和警告；
  • 原始位置，供人回看页面。

置信信号只能帮助排序复核，不能自动证明语义正确。视觉模型输出同样是概率性推断，不应覆盖原生结构或原始坐标。

一个可追溯元素契约

{
  "element_id": "sha256:abc...:e0012",
  "kind": "paragraph",
  "text": "请求必须设置超时。",
  "text_sha256": "...",
  "order": 12,
  "location": {"page": 3, "bbox": [72, 120, 510, 158]},
  "section_path": ["可靠性", "超时"],
  "attributes": {"structure_source": "explicit"}
}

element_id 在同一个源版本和解析配置内应稳定；order 表示采用的阅读顺序；location 用于回到原文。对于文本文件，本库项目用 line_start/line_end；PDF 可用页码和 bounding box。坐标系必须注明原点、单位、旋转和裁切框，否则数字本身不可解释。

不要把敏感全文复制到每个日志或索引记录。文本与元数据的存储权限可以分开，但引用链不能断。

标题、列表和代码

标题路径

解析标题时维护栈：遇到 H2 就关闭此前同级及更深层级，再把新标题压入。若从 H1 直接跳到 H3，不要凭空断言中间标题；可以保留跳级警告。标题重复很常见，因此 section_path + order 比标题字符串更可靠。

列表

列表项需保存：有序/无序、层级、序号（如有）、复选状态和父项关系。将嵌套列表平铺成段落会丢掉步骤依赖与例外条件。

代码

代码块的换行和缩进属于语义。保留语言标记、原始文本、来源位置；展示或执行前再做密钥检测与安全治理。文档里的代码从来不是“因为来自知识库就可信”。

表格：同时保存结构和派生文本

表格至少需要：

  • 行列与表头；
  • 合并单元格、跨页关系（若可得）；
  • caption、脚注、单位；
  • 页面/坐标与原始单元格文本；
  • 结构推断警告。

为了检索，可以把一行派生为“模型 A 的延迟为 120 ms”，但这句话必须指向原表格，且不能替代结构化单元格。否则列错位时，派生句会把错误包装得更自然。

典型难点包括无边框表、重复表头、跨页表、单元格换行、嵌套表、脚注和合并单元格。DataFrame 能构造出来只说明语法成功，不说明行列事实正确。

阅读顺序与版面

PDF 内部对象顺序可能是“左栏第一行、右栏第一行、左栏第二行”，也可能把页眉、脚注插入正文。简单按 (y, x) 排序在多栏、浮动图片和旋转页面上会失败。

可采用分层策略：

  1. 优先使用格式中可信的逻辑结构；
  2. 对页面建立版面区域和栏；
  3. 在区域内排序元素；
  4. 标记页眉页脚、caption、脚注等角色；
  5. 用目标文档类型的人工样本验证顺序。

Docling 等现代解析框架把版面、阅读顺序、表格、公式与统一文档表示作为独立能力。这说明“选一个库”不会消除契约与评测工作；版本、模型和配置变化仍需重新验收。

质量检查

自动检查可发现：

  • 标题层级异常或所有内容都成了一个段落；
  • 元素 order 重复、位置越界、页数缺失；
  • 页眉页脚在每页重复进入正文；
  • 表格列数漂移、空表头、重复表头未处理；
  • 异常长行、大量空元素或零宽字符激增；
  • 派生文本找不到原元素。

人工 gold set 还要逐项标注：阅读顺序、标题父子关系、关键表格单元、公式和图注。自动完整性高不等于语义正确。

常见错误与排查

  • 按字体大小写死标题：不同模板、脚注和封面会破坏规则。
  • 先丢页码/坐标再切块：后续无法可靠引用与修复。
  • 把结构解析和 chunking 混为一步：改变切块策略就被迫重跑昂贵解析。
  • 只保留 LLM/VLM 生成的 Markdown：生成文本可能补写、重排或遗漏；应保留中间结构与原始定位。
  • 忽略重复标题：只用标题名生成 ID 会碰撞。

练习

  1. 为标题、段落、嵌套列表、代码、表格和图注扩展上面的元素 schema。
  2. 给一个双栏页面画出区域划分与阅读顺序，列出三种会让 (y, x) 排序失败的情况。
  3. 将表格一行转换成检索文本，并写出它回到原单元格的指针。
  4. 为 20 份目标文档设计 gold set：至少覆盖重复页眉、跨页表格、脚注、中文/英文混排和代码。

自测

  • 我能区分显式结构与推断结构。
  • 我能为任一元素保存稳定身份、顺序和可解释位置。
  • 我知道派生表格文本不能替代原结构。
  • 我会单独评测阅读顺序、层级和关键单元格。

参考资料与下一步

来源获取日期：2026-07-22。下一步：PDF 与 OCR 边界。

Backlinks