文档内容抽取

Description

从 PDF、图片、Word、Excel 等非结构化文档中按 JSON Schema 抽取发票号码、金额、日期、姓名等业务字段。当用户要求从发票、合同、简历、收据、报表等文档中提取结构化字段;当用户提到文档抽取、字段提取、票据识别、合同要素录入、表单归档、发票报销自动化;或需要把非结构化文档转为结构化 JSON 且不想写 OCR 预处理或正则规则时使用。

When to Use

用户要求从 PDF/图片/Word/Excel 中提取发票号码、金额、日期、姓名等业务字段
用户提到:文档抽取、字段提取、票据识别、合同要素录入、表单归档、发票报销自动化
需要把非结构化文档转为结构化 JSON,且不想写 OCR 预处理或正则规则
输入是发票、合同、简历、收据、报表等单页或多页文档

安全与执行前检查

只有在用户允许将文件上传到 Anspire 服务时才调用 API。
API Key 只从全局共享凭证文件读取,不接受命令行参数,不读取环境变量中的 Key 本身。
首次或更新 API Key:运行 python /path/to/skill/scripts/anspire_api.py configure(隐藏输入)。保存后只告知"认证配置已更新",不展示配置文件路径。
没有 API Key 时不要调用 API。引导用户打开 Anspire 控制台 API Key 设置页,完成注册、登录和 API Key 创建,然后通过 configure 完成认证。
API Key 返回 401 时,清除失效值并要求用户重新配置。
不要把 API Key 写入 Skill 包、日志或最终回复。
使用本 Skill 目录中的 scripts/anspire_api.py,不要假设当前工作目录是 Skill 根目录。
输入是身份证、护照、合同、财务票据等个人信息时,提醒用户文件会发送到第三方服务。

使用方法

文档内容抽取

使用简化 Schema 或标准 JSON Schema 描述要抽取的字段:

python /path/to/skill/scripts/anspire_api.py extract \
  --file /path/to/document.pdf \
  --schema '{"发票号码":"string","金额":"number","开票日期":"string"}' \
  --quiet

规则:

--file 与 --url 必须二选一。
--schema 与 --schema-file 必须二选一。
字段名使用业务语义,类型使用 string、number、boolean、array 或 object。
常规抽取不要启用 --with-grounding;只有用户要求字段溯源、原文定位或坐标时才启用。
用户只需要字段值时增加 --result-only。
脚本 stdout 保留 JSON,供后续流程使用;最终回复不要直接倾倒完整原始 JSON。
最终回复使用下方展示模板,只展示 Schema 字段对应的识别结果,以及实际生成的输出文件路径。
不主动附加识别质量评价、复核建议或字段置信度分析,除非用户明确要求。

文档抽取展示模板

## 文档抽取结果

| 字段 | 识别结果 |
|---|---|
| 字段 A | 值 A |
| 字段 B | 值 B |

结果文件:`/path/to/result.json`

展示要求:

string、number、boolean 直接展示值。
array 使用换行列表展示,不要压成难读的单行 JSON。
object 使用字段嵌套表格或折叠列表展示。
null、空字符串和未识别字段必须如实展示为"未识别",不得自行补值。
默认不展示 task_id、耗时、request ID 等技术元数据。
只有用户明确要求溯源时才展示 grounding;未启用 --with-grounding 时不要展示坐标信息。

document-extract 端点详情

端点:POST /open-api/v1/document/extract

Content-Type:multipart/form-data

multipart 字段名:file

请求参数:

| 参数名 | 类型 | 必填 | 参数说明 | 示例 | |---|---|---|---|---| | file | file | 是 | 待抽取文档,支持 pdf/jpg/png/tiff/doc/docx | sample.pdf | | schema | JSON string | 是 | 字段抽取 Schema(见下文) | {"发票号码":"string","金额":"number"} | | source | string | 否 | 来源标识,透传给接口 | invoice-flow |

Schema 用法

简化 Schema(推荐):{"字段名": "类型"},类型支持 string/number/boolean/array/object。

{"发票号码": "string", "金额": "number", "开票日期": "string", "明细": "array"}

字段名用业务语义(如"发票号码"而非"field1"),识别准确率更高
也支持标准 JSON Schema(带 description/enum/items 等),但简化 Schema 已能满足大多数场景
Schema 非合法 JSON 或类型不支持时返回 400(invalid_request)

文件格式支持:pdf、jpg、png、tiff、doc、docx

响应字段(以 API 实际返回为准):

| 字段 | 类型 | 说明 | |---|---|---| | task_id | string | 任务唯一 ID | | status | string | success 表示成功 | | request_id | string | 请求唯一 ID,联系支持时提供 | | result | object | 抽取结果;key 为 Schema 中定义的字段名,value 为识别值 | | result.{字段名} | string|number|boolean|array|object | 对应 Schema 字段的识别值;未识别时为 null 或空字符串 |

响应示例:

{
  "task_id": "xxxxxxxxxxxxxxxx",
  "status": "success",
  "request_id": "req_xxxxxxxxxxxxx",
  "result": {
    "发票号码": "12345678",
    "金额": 1000.00,
    "开票日期": "2026-08-11",
    "明细": [{"名称": "咨询服务", "单价": 1000.00}]
  }
}

说明:本 skill 只返回字段值,不返回字段坐标。如需字段在文档中的位置(页码+坐标),使用 anspire-document-locate skill(自动启用 with_grounding=true)。

输出与错误处理

交互调用默认使用 --quiet,避免摘要和 JSON 重复展示。
需要管道处理时同时使用 --result-only。
成功时只展示识别结果和输出路径;不要把请求头、API Key 或完整调试日志放入最终回复。
失败时根据退出码说明原因(见下方退出码表)。
输出文件已存在时不要无提示覆盖;改用新的输出路径或先征得用户同意。

错误处理

根据退出码说明原因:

| 退出码 | 含义 | 处理建议 | |---|---|---| | 0 | 成功 | 解析响应 JSON | | 1 | 参数/Schema/文件格式错误 | 检查参数和文件类型 | | 2 | API Key 无效或缺失 | 按「安全与执行前检查」第 4 步引导用户 | | 3 | 权限或配额不足 | 升级套餐或联系商务 | | 4 | 限流重试后仍失败 | 稍后重试 | | 5 | 服务端错误重试后仍失败 | 联系支持 | | 6 | 网络或其他本地错误 | 检查网络和文件路径 |

参考

references/api_reference.md:完整 API 字段、请求响应示例、Schema 进阶用法、凭证管理细节、迁移说明、端点详情。

Anspire-文档自定义内容抽取

文档内容抽取

Description

When to Use

安全与执行前检查

使用方法

文档内容抽取

文档抽取展示模板

document-extract 端点详情

Schema 用法

输出与错误处理

错误处理

参考