ade-python字段溯源实战：用extraction_metadata与grounding让每个提取值都能回指原文

ade-python 是 LandingAI Agentic Document Extraction（ADE）的官方 Python 库，负责把 PDF、图片解析为结构化 Markdown，再从中抽取类型化字段。本文将用 extraction_metadata 与 grounding 两个内置机制，手把手教你实现字段溯源：让每个提取出来的值都能回指到原文的具体位置，做到可审计、可核对。

为什么字段溯源很重要？

文档抽取最常被质疑的一点是：模型给出的 total: 12,800.00，到底是从文档哪里来的？人工抽查时还得重新翻原文逐字比对。

ade-python 的 v2 接口把"出处"直接做进了响应里，形成三段式溯源链路：

整条链路不需要任何额外服务，一次 parse + 一次 extract + 一次 ground 即可完成。

准备工作：安装与 API Key

pip install landingai-ade
export VISION_AGENT_API_KEY=<your-api-key>

创建客户端后即可使用，客户端会自动读取环境变量中的密钥：

from landingai_ade import LandingAIADE

client = LandingAIADE()

第一步：parse 拿到原文结构树

parse 把文档转成 Markdown，同时返回一棵 document → page → element 的 structure 树。这棵树是后续溯源的"地图"：每个节点都内嵌 grounding 信息，包括页码 page、在 Markdown 中的字符区间 range，以及归一化页面坐标框 box（见 src/landingai_ade/types/v2/parse_response.py#L56-L85 中 V2ParseBox、V2ParseRange、V2ParseNodeGrounding 的定义）。

parsed = client.v2.parse(document="invoice.pdf")
print(parsed.markdown)          # 全文 Markdown
print(parsed.structure)         # 带页码、区间、坐标的结构树

💡 如果某个页面解析失败，请求仍会返回（HTTP 206），失败页码列在 metadata.failed_pages 里，溯源时可以把这些页先排除。

第二步：extract 拿到每个字段的字符区间

定义好 Pydantic 模型后调用 extract，除了拿到 extraction 里的字段值，还会拿到结构完全镜像它的 extraction_metadata——每个字段都是 {value, ranges} 形式，ranges 是该值在 Markdown 中的字符偏移区间（按 Unicode 码点计，见 metadata.range_units）：

from pydantic import BaseModel, Field

class Invoice(BaseModel):
    invoice_number: str = Field(description="The invoice number")
    total: str = Field(description="Invoice grand total")

result = client.v2.extract(schema=Invoice, markdown=parsed.markdown)
print(result.extraction)
# {'invoice_number': 'INV-042', 'total': '12,800.00'}
print(result.extraction_metadata)
# {'invoice_number': {'value': 'INV-042', 'ranges': [{'start': 13, 'end': 31}]}, ...}

有了 ranges，你甚至不需要第三步就能自己"回指"：用 markdown[start:end] 切片即可还原该字段的原文片段。字段类型定义见 src/landingai_ade/types/v2/extract_response.py。

第三步：ground 把字段映射回原文块

字符区间只回答"在哪段文字"，而 ground 进一步回答"在哪一页、哪个原文块、页面什么位置"。它把 extraction_metadata 中每个 {value, ranges} 叶子，与 structure 中每个块的 grounding.range 做重叠匹配，返回一棵镜像树：每个字段变成一个 structure 块列表（含 block_id、type、page、range）：

grounded = client.v2.ground(
    extraction_metadata=result.extraction_metadata,
    structure=parsed.structure,
)
print(grounded.grounding)

输出示意：

{'invoice_number': [
    {'block_id': 'text-1', 'type': 'text',
     'grounding': {'page': 1, 'range': {'start': 13, 'end': 31}}}
]}

这样审核人员拿到任何一个字段值，都能定位到"第 1 页、text-1 块"，配合坐标框还能在 PDF 上高亮显示。响应模型见 src/landingai_ade/types/v2/ground_response.py，接口实现在 src/landingai_ade/resources/v2/v2.py#L125-L145。

实战要点与常见坑

• structure 必须匹配：block id 只在传入的 structure 内解析，务必把 extract 所用 Markdown 对应的那次 parse 结果传进去，官方冒烟测试就是这么串的：parse → extract → ground，参考 tests/contract/test_v2_smoke.py#L175-L188。
• ground 仅支持同步调用，没有异步 jobs 路由；但文档不大时一次调用毫秒级返回，通常无需担心。
• 想要更快可以关掉 grounding：extract 传 grounding=False 会跳过落位阶段、响应更快，但所有 extraction_metadata 叶子的 ranges 都变成 None，溯源能力随之关闭（且抽取结果可能与落位运行略有差异）。需要溯源的线上场景请保持默认开启。
• 部分字段抽不到时：默认 strict=False 会跳过不支持的字段继续抽取，此时响应里的 schema_violation_error 会提示抽取不完整，审核时应对此报警。
• 想留档审计：parse / extract 都支持 save_to="./output" 参数，把完整响应（含全部溯源信息）落盘为 JSON，方便事后复查。
• 完整的调用示例可运行 examples/v2_extract.py，其中还演示了用 extract_jobs.wait 处理长耗时抽取。

小结

ade-python 把字段溯源做成了三个开箱即用的步骤：parse 给出带坐标的结构树，extract 的 extraction_metadata 给出每个字段的原文字符区间，ground 再把字段精确落位到原文块。对需要人工审核、合规留痕的文档抽取场景，这套"值 + 区间 + 原文块"的三级回指，让每个提取结果都可以被快速验证，而不必再肉眼比对全文。

赞 分享