文档字段抽取如何避免“有值但无证据”关键不是完成一次调用而是让输入口径、处理状态和结果证据可以复核。本文围绕“如何从 PDF、DOCX 或纯文本中抽取结构化字段并保存字段原值、规范值和证据位置”给出一套面向真实业务流程的实现方式。问题与结果将文档读取、字段抽取、Schema 校验和人工复核拆成独立状态任何字段都能回到原文证据。适用场景合同与报告字段入库长文档结构化归档业务表单自动预填与复核实现前先确定边界文件和纯文本只能选择一种主输入Schema 必须在抽取前版本化低置信度、类型错误或证据缺失的字段进入人工复核可验证工作流API 编排与职责步骤接口请求方式用途文档解析AI 文档字段结构化解析POST上传文件或文本并按 JSON Schema 返回结构化字段任务查询异步任务状态查询GET大文档或扫描件使用operationId查询处理状态主接口地址为POST https://api.gugudata.com/v1/document-extractions接口使用multipart/form-data。file与text必须二选一schema必填ocrMode支持auto、always、neverexecutionMode支持auto、sync、async。最小可运行实现先定义稳定的业务字段{ type: object, required: [projectName, budgetAmount], properties: { projectName: { type: string, title: 项目名称 }, budgetAmount: { type: number, title: 预算金额, description: 统一按万元返回 }, bidDeadline: { type: string, format: date-time, title: 投标截止时间 } } }使用文件上传curl -X POST https://api.gugudata.com/v1/document-extractions?appkeyYOUR_APPKEY \ -F fileprocurement-notice.pdf \ -F schema{type:object,required:[projectName,budgetAmount],properties:{projectName:{type:string,title:项目名称},budgetAmount:{type:number,title:预算金额,description:统一按万元返回},bidDeadline:{type:string,format:date-time,title:投标截止时间}}} \ -F instruction金额统一按万元日期使用北京时间 \ -F ocrModeauto \ -F executionModeauto在 Python 服务中可以把 Schema 和文件一起提交import json import requests APPKEY YOUR_APPKEY def extract_document(path: str, schema: dict) - dict: Extract validated fields from one document. with open(path, rb) as document: response requests.post( https://api.gugudata.com/v1/document-extractions, params{appkey: APPKEY}, files{file: document}, data{ schema: json.dumps(schema, ensure_asciiFalse), instruction: 金额统一按万元日期使用北京时间, ocrMode: auto, executionMode: auto, }, timeout90, ) response.raise_for_status() return response.json()结果如何进入业务系统同步成功时重点读取以下字段字段用途Data.document文件名、类型、页数、字符数和实际文本提取方式Data.summary字段总数、成功数、失败数和成功率Data.values字段状态、原值、规范化值、类型、置信度和证据Data.failedFields需要重试或人工复核的字段路径Data.warningsOCR 降级等非致命警告入库时不要只保存normalizedValue。建议同时保存value、status、confidence、evidence、requestId和 Schema 版本。这样字段发生争议时可以回到原文证据而不是重新猜测模型当时为何返回该值。长文本不会只处理前半段。调用方应在成功结果中检查processedCharCount charCount且isCompletetrue并记录chunkCount。任一文本块处理失败时任务不会以完整成功结束。格式与 Schema 边界文件最大 30 MiBPDF 最多 500 页文本最多 120,000 字符。支持 PDF、DOCX、TXT、MD/Markdown二进制.doc需要先转换为.docx或 PDF。对于可复制文本的 PDF可以先用 PDF 文本提取 建立全文基线扫描件则通过 图片流 OCR 补充识别结果并保留实际处理方式。Schema 最大 64 KiB顶层必须是 object最多 6 层、200 节点和 100 个叶子字段。format仅支持date、date-time、email和uri。instruction最多 4,000 字符不能改变 Schema 或证据规则。异步任务设计当接口返回modeasync和operationId时Agent 应进入任务状态机而不是把创建成功当成解析成功PENDING - RUNNING - SUCCEEDED - FAILED - EXPIRED查询地址示例curl https://api.gugudata.com/ai/operations/OPERATION_ID \ -H X-GUGUDATA-APPKEY: YOUR_APPKEY任务成功后最终结果位于Data.result使用与同步结果相同的复核和入库流程。失败分类与降级file与text同时存在、同时为空、Schema 非法、文件类型不支持时应直接标记为输入错误。LOW_CONFIDENCE和AMBIGUOUS不是系统异常而是需要人工判断的字段状态。模型、OCR 或外部依赖失败时返回业务码 901 与 HTTP 503不应伪装为成功结果。扫描件 OCR 失败但原生文本仍可用时接口可能返回警告。Agent 可以继续处理但必须保留warnings并避免把任务标记为“无警告成功”。数据契约与留痕字段作用document_id稳定业务标识用于关联记录和请求追踪source_hash内容哈希用于完整性、版本和重复识别schema_version输入、规则或产物版本变更时保留旧版本field_path业务数据字段保存来源、口径和缺失状态raw_value原始来源或响应供后续复核normalized_value业务数据字段保存来源、口径和缺失状态evidence_location业务数据字段保存来源、口径和缺失状态review_status显式状态或原因禁止以空值代替失败重试应新增尝试记录不覆盖最后一次失败。派生结果必须关联输入版本、生成时间和业务状态。验收清单每个必填字段都有值或明确缺失原因字段值可以定位到页码、段落或文本片段人工修改保留原值和修改记录能力边界字段抽取结果是候选结构化数据不能替代合同审查、身份核验或其他专业判断。示例中的YOUR_APPKEY仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中。