# AI 文档字段结构化解析

> 来源页面: https://www.gugudata.com/api/details/document-field-extraction

## 概览

- API 标识: `document-field-extraction`
- 分类: AI/模型
- 描述: 从文档结构化解析出标准 JSON 数据
- 标签: 文档解析 / 字段抽取 / 结构化 JSON
- 短标签: AI / 文档解析 / 字段抽取 / JSON
- 详情页: https://www.gugudata.com/api/details/document-field-extraction
- LLM Markdown: https://www.gugudata.com/api/details/document-field-extraction/llm.md
- 数据预览: https://www.gugudata.com/preview/document-field-extraction
- 购买开通: https://www.gugudata.com/order/document-field-extraction
- APP KEY 管理: https://www.gugudata.com/portal/
- 订单与续费: https://www.gugudata.com/portal/orders

## 给大模型的接入指令

如果你正在帮助用户接入这个 API，请优先使用本文档中的接口地址、请求方式、请求参数、返回参数、状态码、cURL 示例和预览数据生成代码或排查问题。

- 接入目标: 调用 `AI 文档字段结构化解析`，不要臆造未在文档中出现的参数或返回字段。
- AppKey 获取: 用户登录咕咕数据开发者中心后，在 `APP KEY 管理` 页面复制对应产品的 AppKey。
- AppKey 替换: 示例中的 `YOUR_APPKEY`、`APPKEY`、`{{YOUR_APPKEY}}`、`{{appkey}}`、`{{appKey}}` 都应替换为用户自己的 AppKey。
- AppKey 传递: 推荐使用 `X-GUGUDATA-APPKEY` 或 `X-API-Key` 请求头；OpenAI 兼容客户端可使用 `Authorization: Bearer <AppKey>`；历史示例中的 query 参数 `appkey` 继续有效。
- 开通与续费: 未开通时引导用户访问购买开通页；已开通或需要续费时，引导用户进入开发者中心或订单与续费页。
- 错误处理: HTTP 状态码代表传输层结果，响应体内的业务状态码代表接口业务结果，代码中应分别处理。
- 生产建议: AppKey 应保存在服务端环境变量或密钥配置中，由服务端统一发起请求，不要写入网页、App 客户端或公开仓库。

关键链接:

- 接口详情页: https://www.gugudata.com/api/details/document-field-extraction
- LLM Markdown: https://www.gugudata.com/api/details/document-field-extraction/llm.md
- 数据预览: https://www.gugudata.com/preview/document-field-extraction
- 购买开通页: https://www.gugudata.com/order/document-field-extraction
- 开发者中心 APP KEY 管理: https://www.gugudata.com/portal/
- 订单与续费: https://www.gugudata.com/portal/orders

## API 功能

- 支持 PDF、DOCX、DOC（Word OpenXML 内容）、TXT、MD/Markdown 及纯文本输入，可覆盖合同、招投标文件、采购公告、报告、制度文件和业务申请材料等常见文档；
- 支持调用方自定义 JSON Schema 子集字段结构，按业务字段 Key 返回标准 JSON，便于系统直接入库、对账和流程编排；
- 支持多层 object、array、string、number、integer、boolean 等字段类型定义，可表达复杂文档的层级化结构化要求；
- 支持 required、title、description、format、items、properties 等常用字段约束，让字段口径、单位、格式和业务语义更清晰；
- 内置文档文本抽取能力，能够从可复制文本的 PDF、Word、Markdown 和纯文本中提取正文、段落、表格行等信息；
- 支持 OCR 触发策略配置，原生文本不足或扫描型 PDF 可按 auto、always、never 策略选择是否进行 OCR 辅助解析；
- AI 抽取结果会经过服务端 Schema 校验、类型检查和归一化处理，降低自由文本输出对下游系统造成的不确定性；
- 每个字段返回状态、原始值、归一化值、字段类型、置信度、失败原因和证据片段，便于自动化处理与人工复核；
- 支持字段级失败原因区分，可识别未找到、类型不匹配、低置信度、结果歧义、Schema 不支持和解析异常等情况；
- 返回整体解析统计，包括字段总数、成功字段数、失败字段数和成功率，便于客户侧监控解析质量和任务效果；
- 支持同步与异步两种执行模式，小文档可同步返回，大文档、扫描件或批量任务可通过 operationId 轮询获取结果；
- 支持 Demo 原始文档地址回传，开发者可以对照原文、字段值、证据片段和解析结果快速完成联调验证；
- 适用于招投标解析、采购公告入库、合同字段抽取、财务报告解析、审计材料整理、资质文件审核等高价值业务场景；
- 统一使用 DataStatus + Data 返回结构，便于与咕咕数据现有接口、Postman 集合、OpenAPI 文档和企业后端系统集成；
- 提供 7*24 小时稳定接口服务。
- 全接口支持 HTTPS（TLS v1.0 / v1.1 / v1.2 / v1.3）；
- 全面兼容 Apple ATS；
- 全国多节点 CDN 部署；
- [接口调用状态与状态监控](https://www.gugudata.com/status)

## API 文档

- 接口地址: `https://api.gugudata.com/v1/document-extractions`
- 返回格式: `application/json; charset=utf-8`
- 请求方式: `POST`
- 请求协议: `HTTPS`
- 请求示例: `https://api.gugudata.com/v1/document-extractions?appkey=%e6%97%a0`
- 接口测试: https://api.gugudata.com/v1/document-extractions/demo
- Apifox: https://doc.gugudata.com/
- Postman: https://www.postman.com/gugudata/gugudata-official/collection/1163860-22cb92f5-771a-48fd-89c0-f20a0790a8ce/?action=share&creator=1163860&active-environment=1163860-a95b31ef-324f-43db-b2fc-faa41f45bd35
- OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json

## 鉴权方式

接口支持以下 AppKey 传递方式，任选一种即可；已有请求示例、Postman 集合和历史代码仍可继续使用原来的 `appkey` 参数方式。

| 传输载体 | 参数 | 示例 | 说明 |
| --- | --- | --- | --- |
| HTTP Header | `X-GUGUDATA-APPKEY` | `X-GUGUDATA-APPKEY: YOUR_APPKEY` | 推荐方式，适合服务端接入和统一封装。 |
| HTTP Header | `X-API-Key` | `X-API-Key: YOUR_APPKEY` | 通用 API Key Header，便于和常见 API 客户端集成。 |
| HTTP Header | `Authorization` | `Authorization: Bearer YOUR_APPKEY` | 适合 OpenAI 兼容接口或 Bearer Token 风格客户端。 |
| Query 参数 | `appkey` | `?appkey=YOUR_APPKEY` | 兼容现有示例、Postman 集合、浏览器调试和历史代码。 |

> 部分历史 POST 接口仍兼容表单或 JSON body 中的 `appkey`；新接入建议优先使用 Header 或 Query 参数。

## 请求参数

| 参数名 | 参数类型 | 是否必须 | 默认值 | 备注 |
| --- | --- | --- | --- | --- |
| appkey | string | 是 | 无 | 付费后获取的 APPKEY。文档示例默认通过 Query 参数 appkey 传递；历史 Form 或 JSON body 中的 appkey 仍兼容。 |
| file | string/binary | 否 | 无 | 待解析的文档文件。接口使用 multipart/form-data 上传，file 和 text 必须二选一且不能同时传；支持 PDF、DOCX、DOC（Word OpenXML 内容）、TXT、MD/Markdown。建议优先上传可复制文本的 PDF 或 .docx；扫描版 PDF 可配合 ocrMode=auto/always；空文件、无法识别内容或不支持的传统二进制文档会返回参数错误或文件类型不支持。Demo 原始文件：https://static.gugudata.com/api-demo/document-field-extraction/report-ai-tool-procurement.doc。 |
| text | string | 否 | 无 | 待解析的纯文本内容。适用于调用方已完成网页抽取、OCR、文档转换或内部系统取数后的场景；file 和 text 必须二选一且不能同时传。文本建议保留标题、段落、表格行列关系、编号、金额单位和日期上下文，以提升字段定位、类型归一化和证据片段质量。 |
| schema | string | 是 | 无 | 字段定义 JSON 字符串，采用 JSON Schema 子集。顶层必须是 type=object，properties 中每个 key 是返回结果里的字段 key；支持 string、number、integer、boolean、object、array，以及 required、title、description、format、items、properties 等常用约束。建议使用稳定英文 key，中文展示名放 title，单位、枚举范围、抽取口径和优先章节写入 description。示例：{"type":"object","required":["projectName"],"properties":{"projectName":{"type":"string","title":"项目名称","description":"采购或招标项目名称"}}}。 |
| instruction | string | 否 | 无 | 可选的补充解析说明。用于描述文档背景、金额单位、日期时区、币种、大小写规则、冲突字段优先级、是否优先某个章节等业务口径；字段结构仍以 schema 为准，不建议在 instruction 中重复整份 schema。 |
| ocrMode | string | 否 | auto | OCR 触发模式，可选 auto、always、never。auto 表示系统根据原生文本密度、页数和扫描特征自动判断是否需要 OCR；always 表示即使存在原生文本也尝试 OCR；never 表示只使用原生文本。通常建议使用 auto，扫描件或图片型 PDF 可使用 always，已确认可复制文本的文档可使用 never 降低处理时间。 |
| executionMode | string | 否 | auto | 执行模式，可选 auto、sync、async。auto 表示系统根据文档大小、字符数、页数和处理耗时预估自动选择同步或异步；sync 适合小文档和低延迟调用；async 会创建异步任务并返回 operationId，适合大文档、扫描件、批量文件和后台稳定处理。 |

## 返回参数

| 参数名 | 参数类型 | 备注 |
| --- | --- | --- |
| DataStatus.StatusCode | integer | 业务状态码。100 表示请求成功；501 表示参数错误、Schema 不受支持、输入为空或文件类型不支持；504 表示 AppKey 无效或无权限；-9 表示服务端处理异常。接入时建议同时判断 HTTP 状态码和业务状态码。 |
| DataStatus.StatusDescription | string | 业务状态说明，返回本次请求的处理结果或错误提示，便于日志记录、用户提示和异常排查。 |
| DataStatus.ResponseDateTime | string | 接口响应时间，由服务端生成，可用于调用链路日志、对账和问题定位。 |
| DataStatus.DataTotalCount | integer | 本次返回的数据条数。同步解析成功时通常为 1；异步任务创建成功时表示任务返回对象数量。 |
| Data.requestId | string | 本次文档解析请求 ID。同步结果和异步任务结果都会返回，可用于客户侧日志追踪、排查单次解析结果和与技术支持沟通。 |
| Data.mode | string | 执行模式结果。sync 表示已同步完成并返回字段结果；async 表示已创建异步任务或返回异步任务结果。 |
| Data.document.fileName | string | 文档文件名。file 上传时来自上传文件名；text 输入时可为空，用于区分不同来源的解析结果。 |
| Data.document.contentType | string | 上传文件的 Content-Type，例如 application/pdf、application/vnd.openxmlformats-officedocument.wordprocessingml.document、text/plain 等。 |
| Data.document.extension | string | 服务端识别到的文档扩展名或解析类型，例如 .pdf、.docx、.txt、.md、text 等。 |
| Data.document.pageCount | integer | 文档页数或解析页数估计值。PDF 通常返回实际页数，Word、TXT、Markdown 和纯文本通常按解析结果返回。 |
| Data.document.charCount | integer | 服务端抽取到并参与 AI 解析的文本字符数，可用于判断文档是否为空、是否需要 OCR 或是否超出同步处理范围。 |
| Data.document.textExtraction.method | string | 文本来源方式。native 表示原生文本抽取，ocr 表示 OCR 识别，text 表示调用方直接传入纯文本。 |
| Data.document.textExtraction.sectionCount | integer | 文本分段数量，通常对应段落、表格行、页面片段或 OCR 分段，可辅助判断解析覆盖范围。 |
| Data.summary.totalFields | integer | schema 中需要解析的字段总数，包含嵌套对象和数组中的叶子字段。 |
| Data.summary.succeededFields | integer | 成功解析并通过类型校验、归一化处理的字段数量。 |
| Data.summary.failedFields | integer | 未能成功解析的字段数量，包括未找到、类型不匹配、低置信度、结果歧义、Schema 不支持或解析异常。 |
| Data.summary.successRate | number | 字段解析成功率，取值 0 到 1，计算方式为 succeededFields / totalFields，可用于质量监控和自动化阈值判断。 |
| Data.values | object | 字段解析结果对象。key 与 schema.properties 中的字段 key 保持一致，value 为字段级解析结果。 |
| Data.values.{field}.status | string | 字段级状态。可能值包括 SUCCEEDED、NOT_FOUND、TYPE_MISMATCH、LOW_CONFIDENCE、AMBIGUOUS、UNSUPPORTED_SCHEMA、EXTRACTION_ERROR。 |
| Data.values.{field}.value | any | 从文档中抽取到的原始字段值，尽量保留文档原始表达，例如 70万元、2026年7月29日09点30分、企业全称等。 |
| Data.values.{field}.normalizedValue | any | 按 schema 类型和字段语义归一化后的值，例如金额数字、标准日期时间、布尔值、整数、数组或对象；当字段未找到或类型不匹配时可能为 null。 |
| Data.values.{field}.type | string | 该字段在 schema 中声明的类型，用于客户侧做二次校验、映射和入库。 |
| Data.values.{field}.confidence | number | 字段级置信度，取值 0 到 1。数值越高表示模型越确定；低于阈值时建议进入人工复核或重试流程。 |
| Data.values.{field}.reason | string | 字段失败、低置信度或存在歧义时的原因说明；成功字段通常为空。 |
| Data.values.{field}.evidence[].source | string | 证据片段来源位置，例如 page:1、paragraph:3、table:2:row:5 或 section:1，便于回看原文。 |
| Data.values.{field}.evidence[].text | string | 支持该字段值的简短原文证据片段，便于人工核对和审计留痕。 |
| Data.failedFields[].path | string | 解析失败字段路径。嵌套字段会使用点路径表示，例如 supplier.name 或 items.amount。 |
| Data.failedFields[].status | string | 失败字段状态，取值同字段级 status，用于客户侧按失败类型分流处理。 |
| Data.failedFields[].reason | string | 失败字段原因，例如文档中未找到、提取值与类型不匹配、置信度过低或结果存在歧义。 |
| Data.warnings[] | string | 非致命警告信息。例如 OCR 服务不可用但已使用原生文本解析、OCR 未识别出更多文本等。 |
| Data.sourceDocumentUrl | string | Demo 接口返回的原始示例文档地址，方便开发者对照原文件、证据片段和解析结果；正式接口通常不返回该字段。 |
| Data.operationId | string | 异步模式下返回的任务 ID。调用方可使用 pollingUrl 或现有 operation 查询接口轮询任务状态。 |
| Data.status | string | 异步任务状态，例如 PENDING、RUNNING、SUCCEEDED、FAILED、EXPIRED。同步模式下通常不返回该字段。 |
| Data.pollingUrl | string | 异步任务轮询地址，例如 /ai/operations/{operationId}。任务成功后返回同一套文档解析结果结构。 |
| Data.expiresAt | string | 异步任务过期时间，超过该时间后任务记录可能被清理，建议客户侧及时轮询和持久化结果。 |

## 接口常见 HTTP 响应状态码

> 以下为接口调用中常见的 HTTP 传输层状态码，不等同于响应体内的业务状态码；完整状态码注册表以 IANA HTTP Status Code Registry 为准。

| 状态码 | 状态码解释 | 备注 |
| --- | --- | --- |
| 200 | 请求成功 | HTTP 请求已成功处理；业务状态请结合响应体中的自定义业务码判断。 |
| 201 | 资源已创建 | 创建类接口请求成功，并已生成对应资源。 |
| 202 | 请求已接受 | 请求已被接受处理，结果可能异步完成。 |
| 204 | 无响应内容 | 请求成功但响应体为空，适用于无需返回数据的操作。 |
| 304 | 资源未变更 | 配合缓存或条件请求使用，表示可继续使用本地缓存。 |
| 400 | 请求参数错误 | 请求参数缺失、格式错误或参数组合不合法。 |
| 401 | 认证失败 | 缺少、无效或未通过认证的访问凭证（如 AppKey）。 |
| 403 | 无权限访问 | 订单到期、权限不足或接口额度不可用。 |
| 404 | 资源不存在 | 请求路径不存在。 |
| 405 | 请求方法不允许 | 当前路径不支持该 HTTP 方法。 |
| 408 | 请求超时 | 客户端请求在服务端等待时间内未完成，可稍后重试。 |
| 409 | 请求冲突 | 请求与当前资源状态冲突，调整参数或业务状态后重试。 |
| 413 | 请求内容过大 | 上传文件或请求体超过接口限制。 |
| 414 | 请求地址过长 | 请求 URL 超过服务端可处理长度，建议减少查询参数或改用 POST。 |
| 415 | 请求内容类型不支持 | 上传或请求体的内容类型不符合接口要求。 |
| 422 | 请求语义错误 | 请求格式正确，但参数取值、语义或业务约束无法处理。 |
| 429 | 请求频率受限 | 默认按来源 IP 限速，单 IP 最多 5 QPS，可满足常规业务调用。超出限制时接口会返回 429 请求频率受限；已购买接口订单可加购 10 QPS 扩展。 |
| 431 | 请求头过大 | 请求头字段过大或过多，建议精简 Header 后重试。 |
| 500 | 服务器内部错误 | 服务端处理异常，请稍后重试。 |
| 502 | 网关或上游错误 | 网关或代理从上游服务收到异常响应。 |
| 503 | 服务暂时不可用 | 服务维护、容量保护或依赖异常导致暂时不可用，请稍后重试。 |
| 504 | 网关超时 | 网关等待上游服务响应超时，可稍后重试或降低请求复杂度。 |

## 接口自定义业务状态码

| 业务状态码 | 业务状态码解释 | 备注 |
| --- | --- | --- |
| 100 | 请求成功 | 文档字段解析成功，或异步任务创建成功。 |
| 501 | 参数错误或 schema 不受支持 | 常见原因包括缺少 appkey、file 和 text 未二选一、schema 不是合法 JSON、schema 字段类型不受支持、上传文件为空或文件格式不支持。 |
| 504 | APPKEY 错误或无权限 | AppKey 不存在、已过期、未购买当前接口或没有当前接口调用权限。 |
| -9 | 处理异常 | 服务端解析、OCR、AI 抽取或异步任务处理过程中发生异常，可稍后重试或联系技术支持。 |

## cURL 请求示例

```bash
curl --location 'https://api.gugudata.com/v1/document-extractions?appkey=%e6%97%a0' \
--form 'text=无' \
--form 'schema=无' \
--form 'instruction=无' \
--form 'ocrMode=auto' \
--form 'executionMode=auto' \
--form 'file=@localfile_path.png'
```

## 常见问题 Q&A

### Q: 数据请求有缓存吗？
A: 接口默认以实时响应为目标。对于日更、月更等具备明确更新周期的数据，会在数据周期内采用缓存与预热策略，以提升响应速度和稳定性；实时查询类接口则以接口说明中的更新频率为准。建议业务侧结合数据时效要求设置本地缓存与重试策略，避免高频重复请求。

### Q: 如何保证请求时 AppKey 的安全性？
A: 用户可以登录咕咕数据开发者中心，在 `APP KEY 管理` 页面复制对应产品的 AppKey；未开通接口时先进入当前接口的购买开通页，已开通或到期续费时进入开发者中心或订单与续费页。建议将 AppKey 保存在服务端环境中，由后端统一调用 API，再向前端或业务系统返回必要结果。不要把 AppKey 写入网页、App 客户端或公开仓库；生产环境建议按系统或业务线拆分 AppKey，并保留调用日志，便于权限控制、审计与问题排查。

### Q: 接口可以用于哪些开发语言？
A: 只要支持 HTTPS 请求的语言和框架均可接入，包括 Java、Python、Node.js、PHP、Go、C#、Swift、Kotlin 等。推荐由后端统一封装调用逻辑，集中处理鉴权、缓存、限流、重试和错误码映射，让 Web、App、AI Agent、内部系统和自动化任务复用同一套数据能力。

### Q: 接口性能可以保证吗？
A: GuGuData API 按生产环境标准部署，持续关注接口稳定性、响应速度与可用性。实际响应时间会受接口类型、请求参数、数据源更新和网络环境影响；建议生产接入前进行联调与压测，并设置合理的超时、重试、降级和告警策略。批量处理或高并发场景可提前评估 QPS、白名单和专属容量方案。

## 服务协议以及服务免责声明

- [服务协议](https://www.gugudata.com/license)
- [服务免责声明](https://www.gugudata.com/disclaimer)

## 技术支持

- 技术支持邮箱: support@gugudata.com
- 微信客服: https://work.weixin.qq.com/kfid/kfcf9a60a6afe3337b7