extract-document-data

用途

Extract Document Data 用于从文档中提取结构化 JSON 数据，并带有逐值溯源（grounding）能力：每个提取出的值都会标注它来自哪里（页码、置信度），而文档中并不清晰存在的值会被报告在 not_found 中，而不是被编造出来。它适合把非结构化文档转换为 JSON 以接入下游系统，尤其适用于“编造的值比缺失的值更糟糕”的场景，例如借贷、会计和合规。

主要能力

逐值溯源：每个值携带 confidence（模型自报的置信度）和 page（来源页码）。
缺失即报告：not_found[] 列出请求但模型找不到的字段，缺失会被如实报告，绝不猜测。
页面统计：pages_read 显示处理了多少页（每个文档有页数限制）。
三种提取模式：
- 临时字段（Ad-hoc fields）：直接告诉 API 你想要哪些字段。
- 模板（Template）：使用内置 schema，包括 payslip、tax_invoice、bank_statement、receipt、contract。
- 无 schema（Schema-free）：省略 fields，让模型提取它找到的内容。
表格按结构保留提取；多页文档逐页处理。

使用方式

获取文档：URL 或本地文件路径（PDF、PNG、JPEG、DOCX）。
选择提取模式。临时字段模式示例：

curl -X POST https://www.stipple.sh/v1/extract \
  -F "file=@payslip.pdf" \
  -F 'fields=[{"name":"employer_name"},{"name":"net_pay"},{"name":"pay_date"}]' \
  -H "Authorization: Bearer $STIPPLE_API_KEY"

模板模式通过 template 表单字段传入 payslip、tax_invoice、bank_statement、receipt、contract 之一。

解读响应。响应示例：

{
  "mode": "schema_free",
  "document_type": "payslip",
  "pages_read": 1,
  "fields": {
    "employer_name": {"value": "Acme Cleaning Pty Ltd", "confidence": 0.95, "page": 1},
    "net_pay": {"value": "2845.10", "confidence": 0.97, "page": 1}
  },
  "not_found": ["ytd_tax"]
}

如实报告。这是提取，不是验证——值只是文档显示的内容，并不证明其真实性。例如应报告“Employer: Acme Cleaning Pty Ltd (confidence 0.95, page 1)”，以及“ytd_tax: not found in document”，绝不能写成“ytd_tax: 0”或给出猜测。若需要判断“这份文档是否真实”，应先配合 verify-document 技能使用。

输出格式

工资单字段（有据可依，而非猜测）示例：

  Employer          Acme Cleaning Pty Ltd  (confidence 0.95, page 1)
  Employee          J. Citizen             (confidence 0.98, page 1)
  Net pay           2,845.10               (confidence 0.97, page 1)
  Superannuation    268.20                 (confidence 0.93, page 1)

not_found: ytd_tax
(absences are reported, never hallucinated)

适用场景

解析工资单、发票、银行对账单、收据或合同。
将非结构化文档转换为 JSON 供下游系统使用。
任何“编造值比缺失值更糟糕”的提取任务（借贷、会计、合规）。

限制与安全

发票、对账单、工资单和合同通常包含敏感的个人、财务或商业数据。上传到托管第三方之前，应获得明确批准，尽量减少提交内容，并确认当前的保留、驻留、访问和删除条款。
置信度和页码溯源并不能证明提取值正确，也不能证明源文档真实。在付款、借贷、会计、合规或法律行动之前，应对关键数值与原始文档及权威系统进行核对。
保留原始文件和提取响应，以便人工复核者能够复现并纠正有争议的字段。

备注

模型每读取一页消耗 1 个 credit（最少 1 个）；适用每周免费额度。
模板：payslip、tax_invoice、bank_statement、receipt、contract——作为 template 表单字段传入。
与 verify-document 配合使用（先运行，用于真实性校验）——来自被篡改文档的提取值仍然是错误的。
可在 https://www.stipple.sh 获取免费 key，用于超出匿名额度的计量。