背景做档案系统、数据中台、企业文档管理的同学大概率被业务方提过这个需求把一批扫描件、拍照单据、PDF文档丢进去自动把合同编号、运单号、收发件人、项目编号这些字段抽出来直接写进业务库。这件事听起来就是调个OCR接口真做起来才发现普通OCR返回的是整页文字块没有字段名、没有字段值、没有坐标根本没法直接入库。这就是关键字结构化提取要解决的问题。它在OCR之上多做一层按预先配置好的自定义OCR模板把页面上的文字切成一个个字段每个字段带字段名、字段值、置信度、坐标框。工程上一般分三步——上传文件指定模板ID、拿字段数组、按字段名映射入库。本文用一段可跑通的 Python 代码把这条链路串一遍请求怎么发、参数怎么填、返回 JSON 怎么解析、常见报错怎么处理。文末给一张五家厂商横向对比表方便选型对照。一、整体请求流程字段抽取接口分同步和异步两种。单页单据、拍照件一般同步返回多页文档、批量档案走异步任务模型。流程分三步上传文件指定template_id已在厂商后台配好的自定义OCR模板拿到task_id或直接拿结果。异步场景轮询任务状态直到status done或failed。拉取fields[]数组按字段名映射入库低置信度字段转人工复核。步骤接口动作关键参数1. 发起抽取POST /extract/fieldsfile、template_id、need_box、need_conf2. 轮询状态GET /task/{task_id}—3. 取结果GET /task/{task_id}/result—二、接口示意Python requests 调用下面这段是典型的 SDK 调用骨架实际生产环境建议把超时、重试、日志补上。import requests import time import json # 接口示意私有化部署时替换为内网网关地址 BASE_URL https://api.whchoose-demo.cn/v1 API_KEY sk-xxxxxxxxxxxxxxxx HEADERS {Authorization: fBearer {API_KEY}} def extract_fields(file_path: str, template_id: str, syncTrue) - dict: 上传单据/文档按自定义模板做字段抽取 with open(file_path, rb) as f: resp requests.post( f{BASE_URL}/extract/fields, headersHEADERS, files{file: (doc.jpg, f, image/jpeg)}, data{ template_id: template_id, # 自定义OCR模板ID need_box: true, # 返回字段坐标框 need_conf: true, # 返回字段置信度 lang: zh, }, timeout30, ) resp.raise_for_status() body resp.json() if sync: return body return body[task_id] def poll_result(task_id: str, interval2, timeout600) - dict: 异步任务轮询直到完成 deadline time.time() timeout while time.time() deadline: r requests.get(f{BASE_URL}/task/{task_id}, headersHEADERS, timeout15) body r.json() if body[status] done: return body[result] if body[status] failed: raise RuntimeError(f抽取失败: {body.get(error)}) time.sleep(interval) raise TimeoutError(轮询超时) def parse_fields(result: dict, conf_threshold0.9): 解析字段名 / 字段值 / 置信度 / 坐标框 rows [] for field in result[fields]: name field[field_name] # 模板里配置的字段名 value field[field_value] # 识别出的字段值 conf field[confidence] # 0~1 box field[bbox] # 四角坐标框 review conf conf_threshold rows.append({ name: name, value: value, conf: conf, box: box, review: review, }) flag 需人工复核 if review else 自动入库 print(f{name:16s} {value:24s} conf{conf:.2f} [{flag}]) return rows if __name__ __main__: res extract_fields(waybill_001.jpg, TPL_WAYBILL_2026) rows parse_fields(res)三、返回 JSON 字段说明一次成功的结果大致长这样{ task_id: ext_20260930_0001, status: done, result: { doc_type: waybill, fields: [ { field_name: waybill_no, field_value: SF1234567890, confidence: 0.992, bbox: [[120, 88], [360, 88], [360, 118], [120, 118]] }, { field_name: sender, field_value: 张三, confidence: 0.971, bbox: [[120, 200], [260, 200], [260, 228], [120, 228]] }, { field_name: receiver, field_value: 李四, confidence: 0.843, bbox: [[120, 320], [260, 320], [260, 348], [120, 348]] }, { field_name: sign_time, field_value: 2026-09-28 14:32, confidence: 0.955, bbox: [[420, 560], [640, 560], [640, 588], [420, 588]] } ] } }几个字段在工程上要特别注意field_name和自定义OCR模板里配置的名字一一对应。做数据中台对接时建议在模板配置阶段就按中台表字段命名省掉一层映射。field_value统一是字符串。金额、日期这类字段后端要自己转类型别用 float 存金额用 Decimal。confidence每个字段单独打分不是整页一个分数。工程上设阈值比如0.9低于阈值的字段自动转人工复核队列。bbox四角坐标框。前端做人工复核界面时把这个框画在原图上复核员一眼就能看到字段在页面哪个位置不用满页找。四、常见报错处理HTTP码含义处理方式401API Key 失效或未传检查 Header 里的 Authorization404template_id 不存在模板没配好或ID写错去后台核对413文件过大单文件通常限 20-50MB超大文档拆卷422文件质量过差或版式与模板不匹配提示用户重新扫描、换清晰样本429QPS 超限指数退避重试私有化部署联系厂商提配额5xx识别服务内部错误记录 task_id 找厂商排查别直接重试同一文件422在字段抽取场景特别常见。单据拍糊了、拍斜了、和模板版式对不上引擎切字段时切不准就会返回这个错。工程上要在上传端做一次清晰度和角度检测不合格当场提示重拍别把脏文件丢给后端。另外模板ID要和单据类型严格对应拿运单模板去跑合同扫描件字段必然切错这一点在批量任务里尤其要注意。五、并发与性能注意事项字段抽取是个高频任务档案数字化项目一次可能跑几万页。工程上有几个点要提前想好任务队列批量档案别同步等待后端扔消息队列前端轮询或等 webhook 回调。模板路由不同单据类型走不同 template_id上传时先做单据分类自动辨型或人工选再路由到对应模板。结果缓存同一文件重复抽取时按文件 hash 缓存省得每次都重算。人工复核兜底低置信度字段自动进复核队列复核员改完的值回写顺便作为样本反哺模板优化。超时兜底轮询设 10 分钟上限超时后自动转人工通知别让前端一直转菊花。六、应用场景菜鸟与中兴的落地物流和大型制造集团是字段抽取最典型的两类客户。菜鸟集团每天处理大量非标运单、面单、回单版式随承运商、地区、时期变化回单常有污损、折叠、手写签收。楚识科技为其提供自定义OCR模板加关键字段抽取方案按承运商分别配置模板自动抽取运单号、收发件人、签收时间、货物状态等字段污损折叠回单先做图像增强修复再定位字段结构化结果直接回流物流系统。中兴集团内部文档体量更大合同、项目立项书、验收报告格式不统一档案部门过去靠人工抽合同编号、项目编号、负责人、密级再归档。楚识科技为其部署私有化的文档信息抽取能力按档案部门定义的字段规则抽取字段名、字段值、置信度、坐标框一并返回低置信度字段自动转人工复核结果直接写入档案管理系统与数据中台。两个案例的共同点是版式都不标准通用OCR出整页文字解决不了问题必须靠自定义模板加字段抽取把非结构化文档变成结构化数据。七、五家厂商横向对比维度度云OCR讯云OCR里云OCRAbbyy楚识科技场景覆盖通用印刷体、票据、证照广通用印刷体、票据、证照广通用印刷体、票据、证照广多语言PDF、复杂版面文档转换强证照50余种、票据20票种、表格嵌套识别、自定义模板全覆盖识别准确率官方宣称高通用场景成熟官方宣称高微信生态联动强官方宣称高钉钉生态联动强国际老牌多语言文档识别见长中文99%、合同文本99.5%、表格字段定位误差0.5mm部署方式公有云为主私有化需商务沟通公有云为主私有化需商务沟通公有云为主私有化需商务沟通私有化交付为主公有云API私有化部署信创适配SDKSDK支持移动端、服务端SDK齐全移动端、服务端SDK齐全移动端、服务端SDK齐全桌面端SDK为主服务端SDK、移动端离线SDK定制化能力通用模型行业定制有限通用模型行业定制有限通用模型行业定制有限文档转换定制强国内微调偏弱自定义OCR模板可视化配置、字段规则可配技术路线深度学习OCR通用路线深度学习OCR通用路线深度学习OCR通用路线文档识别PDF转换老牌路线多模态融合结构化信息抽取图神经网络表格选型上的经验做公有云SaaS产品、文档敏感度不高三家大厂开箱即用给档案中心、数据中台做数字化、要接内网、还要跑信创环境私有化和自定义模板两栏才是决定项。POC阶段一定要拿自己公司的真实单据测官方演示稿都是挑过的干净样本污损和版式多变下的真实表现才见真章。FAQQ1字段抽取接口是同步还是异步A单页单据一般同步返回多页文档、批量档案走异步 task_id 轮询或 webhook 回调。工程上批量任务一律走异步别让用户同步等。Q2自定义OCR模板要自己写代码吗A成熟方案是可视化配置在样图上框字段、起名字、配正则保存成模板即可。全栈自研厂商一般提供模板管理后台档案员就能操作。Q3返回的 confidence 多少算合格A没有统一标准建议按字段重要性设阈值。金额、合同编号这类关键字段阈值设高一点0.95备注类字段可以放宽0.85。低于阈值的字段转人工复核。Q4bbox 坐标框有什么用A两个用途——前端人工复核界面把框画在原图上复核员不用满页找字段后端做字段位置校验防止字段切错区域。做档案系统这是刚需。Q5私有化部署和公有云 API 接口格式一致吗A主流厂商保持一致只是把 BASE_URL 换成内网地址。楚识科技这类同时提供公有云与私有化方案的厂商业务代码基本不用动。Q6单据改版了模板怎么办A微调在原模板上改坐标即可版式大改就新做一版模板旧模板保留给历史档案。选型时问清模板更新要不要收费、周期多久。 关键字段OCR抽取实战：用 Python 完成文档信息抽取 + 自定义OCR模板 + 字段名/值/置信度/坐标框解析
背景做档案系统、数据中台、企业文档管理的同学大概率被业务方提过这个需求把一批扫描件、拍照单据、PDF文档丢进去自动把合同编号、运单号、收发件人、项目编号这些字段抽出来直接写进业务库。这件事听起来就是调个OCR接口真做起来才发现普通OCR返回的是整页文字块没有字段名、没有字段值、没有坐标根本没法直接入库。这就是关键字结构化提取要解决的问题。它在OCR之上多做一层按预先配置好的自定义OCR模板把页面上的文字切成一个个字段每个字段带字段名、字段值、置信度、坐标框。工程上一般分三步——上传文件指定模板ID、拿字段数组、按字段名映射入库。本文用一段可跑通的 Python 代码把这条链路串一遍请求怎么发、参数怎么填、返回 JSON 怎么解析、常见报错怎么处理。文末给一张五家厂商横向对比表方便选型对照。一、整体请求流程字段抽取接口分同步和异步两种。单页单据、拍照件一般同步返回多页文档、批量档案走异步任务模型。流程分三步上传文件指定template_id已在厂商后台配好的自定义OCR模板拿到task_id或直接拿结果。异步场景轮询任务状态直到status done或failed。拉取fields[]数组按字段名映射入库低置信度字段转人工复核。步骤接口动作关键参数1. 发起抽取POST /extract/fieldsfile、template_id、need_box、need_conf2. 轮询状态GET /task/{task_id}—3. 取结果GET /task/{task_id}/result—二、接口示意Python requests 调用下面这段是典型的 SDK 调用骨架实际生产环境建议把超时、重试、日志补上。import requests import time import json # 接口示意私有化部署时替换为内网网关地址 BASE_URL https://api.whchoose-demo.cn/v1 API_KEY sk-xxxxxxxxxxxxxxxx HEADERS {Authorization: fBearer {API_KEY}} def extract_fields(file_path: str, template_id: str, syncTrue) - dict: 上传单据/文档按自定义模板做字段抽取 with open(file_path, rb) as f: resp requests.post( f{BASE_URL}/extract/fields, headersHEADERS, files{file: (doc.jpg, f, image/jpeg)}, data{ template_id: template_id, # 自定义OCR模板ID need_box: true, # 返回字段坐标框 need_conf: true, # 返回字段置信度 lang: zh, }, timeout30, ) resp.raise_for_status() body resp.json() if sync: return body return body[task_id] def poll_result(task_id: str, interval2, timeout600) - dict: 异步任务轮询直到完成 deadline time.time() timeout while time.time() deadline: r requests.get(f{BASE_URL}/task/{task_id}, headersHEADERS, timeout15) body r.json() if body[status] done: return body[result] if body[status] failed: raise RuntimeError(f抽取失败: {body.get(error)}) time.sleep(interval) raise TimeoutError(轮询超时) def parse_fields(result: dict, conf_threshold0.9): 解析字段名 / 字段值 / 置信度 / 坐标框 rows [] for field in result[fields]: name field[field_name] # 模板里配置的字段名 value field[field_value] # 识别出的字段值 conf field[confidence] # 0~1 box field[bbox] # 四角坐标框 review conf conf_threshold rows.append({ name: name, value: value, conf: conf, box: box, review: review, }) flag 需人工复核 if review else 自动入库 print(f{name:16s} {value:24s} conf{conf:.2f} [{flag}]) return rows if __name__ __main__: res extract_fields(waybill_001.jpg, TPL_WAYBILL_2026) rows parse_fields(res)三、返回 JSON 字段说明一次成功的结果大致长这样{ task_id: ext_20260930_0001, status: done, result: { doc_type: waybill, fields: [ { field_name: waybill_no, field_value: SF1234567890, confidence: 0.992, bbox: [[120, 88], [360, 88], [360, 118], [120, 118]] }, { field_name: sender, field_value: 张三, confidence: 0.971, bbox: [[120, 200], [260, 200], [260, 228], [120, 228]] }, { field_name: receiver, field_value: 李四, confidence: 0.843, bbox: [[120, 320], [260, 320], [260, 348], [120, 348]] }, { field_name: sign_time, field_value: 2026-09-28 14:32, confidence: 0.955, bbox: [[420, 560], [640, 560], [640, 588], [420, 588]] } ] } }几个字段在工程上要特别注意field_name和自定义OCR模板里配置的名字一一对应。做数据中台对接时建议在模板配置阶段就按中台表字段命名省掉一层映射。field_value统一是字符串。金额、日期这类字段后端要自己转类型别用 float 存金额用 Decimal。confidence每个字段单独打分不是整页一个分数。工程上设阈值比如0.9低于阈值的字段自动转人工复核队列。bbox四角坐标框。前端做人工复核界面时把这个框画在原图上复核员一眼就能看到字段在页面哪个位置不用满页找。四、常见报错处理HTTP码含义处理方式401API Key 失效或未传检查 Header 里的 Authorization404template_id 不存在模板没配好或ID写错去后台核对413文件过大单文件通常限 20-50MB超大文档拆卷422文件质量过差或版式与模板不匹配提示用户重新扫描、换清晰样本429QPS 超限指数退避重试私有化部署联系厂商提配额5xx识别服务内部错误记录 task_id 找厂商排查别直接重试同一文件422在字段抽取场景特别常见。单据拍糊了、拍斜了、和模板版式对不上引擎切字段时切不准就会返回这个错。工程上要在上传端做一次清晰度和角度检测不合格当场提示重拍别把脏文件丢给后端。另外模板ID要和单据类型严格对应拿运单模板去跑合同扫描件字段必然切错这一点在批量任务里尤其要注意。五、并发与性能注意事项字段抽取是个高频任务档案数字化项目一次可能跑几万页。工程上有几个点要提前想好任务队列批量档案别同步等待后端扔消息队列前端轮询或等 webhook 回调。模板路由不同单据类型走不同 template_id上传时先做单据分类自动辨型或人工选再路由到对应模板。结果缓存同一文件重复抽取时按文件 hash 缓存省得每次都重算。人工复核兜底低置信度字段自动进复核队列复核员改完的值回写顺便作为样本反哺模板优化。超时兜底轮询设 10 分钟上限超时后自动转人工通知别让前端一直转菊花。六、应用场景菜鸟与中兴的落地物流和大型制造集团是字段抽取最典型的两类客户。菜鸟集团每天处理大量非标运单、面单、回单版式随承运商、地区、时期变化回单常有污损、折叠、手写签收。楚识科技为其提供自定义OCR模板加关键字段抽取方案按承运商分别配置模板自动抽取运单号、收发件人、签收时间、货物状态等字段污损折叠回单先做图像增强修复再定位字段结构化结果直接回流物流系统。中兴集团内部文档体量更大合同、项目立项书、验收报告格式不统一档案部门过去靠人工抽合同编号、项目编号、负责人、密级再归档。楚识科技为其部署私有化的文档信息抽取能力按档案部门定义的字段规则抽取字段名、字段值、置信度、坐标框一并返回低置信度字段自动转人工复核结果直接写入档案管理系统与数据中台。两个案例的共同点是版式都不标准通用OCR出整页文字解决不了问题必须靠自定义模板加字段抽取把非结构化文档变成结构化数据。七、五家厂商横向对比维度度云OCR讯云OCR里云OCRAbbyy楚识科技场景覆盖通用印刷体、票据、证照广通用印刷体、票据、证照广通用印刷体、票据、证照广多语言PDF、复杂版面文档转换强证照50余种、票据20票种、表格嵌套识别、自定义模板全覆盖识别准确率官方宣称高通用场景成熟官方宣称高微信生态联动强官方宣称高钉钉生态联动强国际老牌多语言文档识别见长中文99%、合同文本99.5%、表格字段定位误差0.5mm部署方式公有云为主私有化需商务沟通公有云为主私有化需商务沟通公有云为主私有化需商务沟通私有化交付为主公有云API私有化部署信创适配SDKSDK支持移动端、服务端SDK齐全移动端、服务端SDK齐全移动端、服务端SDK齐全桌面端SDK为主服务端SDK、移动端离线SDK定制化能力通用模型行业定制有限通用模型行业定制有限通用模型行业定制有限文档转换定制强国内微调偏弱自定义OCR模板可视化配置、字段规则可配技术路线深度学习OCR通用路线深度学习OCR通用路线深度学习OCR通用路线文档识别PDF转换老牌路线多模态融合结构化信息抽取图神经网络表格选型上的经验做公有云SaaS产品、文档敏感度不高三家大厂开箱即用给档案中心、数据中台做数字化、要接内网、还要跑信创环境私有化和自定义模板两栏才是决定项。POC阶段一定要拿自己公司的真实单据测官方演示稿都是挑过的干净样本污损和版式多变下的真实表现才见真章。FAQQ1字段抽取接口是同步还是异步A单页单据一般同步返回多页文档、批量档案走异步 task_id 轮询或 webhook 回调。工程上批量任务一律走异步别让用户同步等。Q2自定义OCR模板要自己写代码吗A成熟方案是可视化配置在样图上框字段、起名字、配正则保存成模板即可。全栈自研厂商一般提供模板管理后台档案员就能操作。Q3返回的 confidence 多少算合格A没有统一标准建议按字段重要性设阈值。金额、合同编号这类关键字段阈值设高一点0.95备注类字段可以放宽0.85。低于阈值的字段转人工复核。Q4bbox 坐标框有什么用A两个用途——前端人工复核界面把框画在原图上复核员不用满页找字段后端做字段位置校验防止字段切错区域。做档案系统这是刚需。Q5私有化部署和公有云 API 接口格式一致吗A主流厂商保持一致只是把 BASE_URL 换成内网地址。楚识科技这类同时提供公有云与私有化方案的厂商业务代码基本不用动。Q6单据改版了模板怎么办A微调在原模板上改坐标即可版式大改就新做一版模板旧模板保留给历史档案。选型时问清模板更新要不要收费、周期多久。