Gemini 视觉文档结构化抽取实战:发票字段、校验重试与人工闸
首页 / 文章 / 技术教程 / Gemini 视觉文档结构化抽取实战:发票字段、校验重试与人工闸
用Itzyk多模态 chat.completions 做票据/文档结构化抽取:schema、Data URL、校验重试、预处理与复核台。Base URL xxx/v1。
作者:智枢 ZhiShu · 发布:2026-10-26 · 更新:2026-11-16
一、为什么「看图聊天」不等于「单据入账」? 多模态 Demo 里丢一张发票问「这是什么」,模型能侃侃而谈。财务/运营要的是: 固定字段、可校验、可重试、可审计 的 JSON——金额必须能 Decimal ,日期必须能解析,缺字段要显式 null 而不是散文省略。视觉能力只是输入通道;结构化与校验才是业务闭环。 Itzyk API( xxx )通过 OpenAI Compatible 的 chat.completions 承载 Gemini 多模态:消息里混排 text 与 image url (常见为 Data URL 或可访问 HTTPS 图)。Base URL: xxx/v1 。本文给出发票/面单类抽取的 schema、提示词、校验重试与费用控制,默认模型 gemini-3.6-flash 。 事实锚点:Itzyk API(xxx)上视觉理解走 POST /v1/chat/completions ,user content 为多段 text + image url ;鉴权 Authorization: Bearer sk-... 。 多模态通识见 文本图片视频一次打通 /articles/gemini-multimodal-text-image-video ;JSON 约束见 结构化输出实战 /articles/gemini-structured-json-output-guide 。 --- 二、管道拆解:影像 → 字段 → 业务 不要指望「一次 prompt 解决所有单据类型」。按 文档类型 分路由:增值税发票、快递面单、身份证复印件——各自一份 schema 与 few-shot。路由可用规则(文件名/上传入口)或先跑一次廉价「类型分类」调用。 准备: 控制台: xxx/ 。模型清单与价格: /services xxx/services 、 /pricing xxx/pricing 。 --- 三、先定 Schema,再让模型看图 以「简版商业发票」为例: 规则: - 金额用 number,禁止「壹万圆」 unless 你另有中文大写字段。 - 看不见的字段输出 null ,禁止瞎编税号。 - confidence 与 needs human 强制模型自报;低置信进人工队列。 - line items 上限(如 30 行),防止超长输出炸费用。 System 提示要点: --- 四、Python:图片 Data URL + 校验重试 " : text = re.sub r"^ ", "", text return json.loads text def validate invoice obj: dict - list str : errs = if not isinstance obj, dict : return "root not object" for k in "seller name", "invoice number", "total amount" : if k not in obj: errs.append f"missing:{k}" date = obj.get "issue date" if date is not None and not re.fullmatch r"\d{4}-\d{2}-\d{2}", str date : errs.append "bad issue date" for amt key in "total amount", "tax amount" : v = obj.get amt key if v is None: continue try: if Decimal str v dict: url = image to data url path messages = {"role": "system", "content": SYSTEM}, { "role": "user", "content": {"type": "text", "text": "抽取该发票字段,严格按 schema 输出 JSON。"}, {"type": "image url", "image url": {"url": url}}, , }, last err = None for attempt in range max retry + 1 : resp = client.chat.completions.create model=MODEL, messages=messages, temperature=0, raw = resp.choices 0 .message.content or "" try: obj = extract json raw except Exception as e: last err = f"parse:{e}" messages.append {"role": "assistant", "content": raw} messages.append { "role": "user", "content": "输出不是合法 JSON。请只输出 JSON 对象,不要代码围栏。", } continue errs = validate invoice obj if not errs: return obj last err = ",".join errs messages.append {"role": "assistant", "content": raw} messages.append { "role": "user", "content": f"校验失败:{last err}。请修正后只输出 JSON。", } raise ValueError f"extract failed:{last err}" if name == " main ": print json.dumps extract invoice "samples/invoice.png" , ensure ascii=False, indent=2 | 模型爱用 Markdown | 解析时剥围栏;重试强调「禁止围栏」 | | 金额错位 | 把税额当成价税合计 | schema 分字段;few-shot 含易混样例 | | 日期格式漂移 | 2024年1月2日 | 校验正则;失败回灌 | | 行项目丢失 | 页裁切过紧 | 分页抽取或放宽裁剪 | | 胡编税号 | 模糊区域瞎补 | system 强制 null;低置信人工 | | 超时 | 图过大/页过多 | 压缩、降分辨率、拆页并行 | | 402 | 余额不足 | 停队列告警充值,勿盲重试 | 线下用 curl 手册 /articles/curl-debug-gemini-api-handbook 先确认纯文本 chat 正常,再排查多模态 content 结构是否符合 SDK 要求。 --- 十、Node 侧最小片段 拿到字符串后仍要走与 Python 相同的 extract json + validate invoice ; 语言不重要,校验重要 。 --- 十一、人工复核台怎么设计(最小) 1. 列表: needs human=true 或校验失败的任务。 2. 详情:原图 + 模型 JSON 并排;金额、购方销方可编辑。 3. 保存:写 human corrected=true ,并把纠正对沉淀进 few-shot / 评测集。 4. 抽检:即使自动通过,也按金额分位抽样 5%~10%。 没有复核台就全自动入账,等于把模型幻觉直接写进总账。 --- 十二、上线检查表 1. 样张集(≥50)+ 字段级指标达标;金额字段零容忍。 2. 校验失败只重试有限次并进人工;有死信队列。 3. 图片大小、MIME、页数白名单;超限先拒后提示压缩。 4. 幂等键与审计:原图 hash、模型原文、最终字段、操作者。 5. 控制台模型权限含所用 Gemini 视觉型号: /services xxx/services 。 6. 预算帽:单日视觉 Token / 费用上限,超限暂停消费队列。 7. 文档与错误码: 开发者文档 xxx/docs 。 --- 十三、预处理清单:进模型之前能做的便宜事 模型很贵,OpenCV/ImageMagick 很便宜。建议固定流水线: 1. 纠偏 :检测二维码/表格线估计旋转角,转正。 2. 裁边 :去掉大块黑边与手指遮挡区域(保守裁,避免切掉税号)。 3. 分辨率 :最长边限制在 1280~1920;票据字体过小再局部超分,而不是整图 4K。 4. 对比度 :扫描件偏灰时做轻度自适应均衡;过度锐化会引入伪边缘。 5. 脱敏贴片 :对身份证号等区域盖色块后再送视觉(若业务允许)。 预处理参数进版本号: preproc ver 与 schema ver 一并写入审计。评测集要用「预处理后」的图,否则线上线下不一致。 手机拍摄常见问题是透视变形;若字段准确率上不去,优先加「拍平提示」或文档扫描 SDK,而不是盲目换更大模型。Flash 在清晰图上往往已够用;模糊图换 Pro 也救不了焦点。 --- 十四、字段级指标与上线门槛 不要只报「整单准确率」。至少拆开: | 字段 | 上线门槛(示例) | 不过则 | |------|------------------|--------| | invoice number | ≥99% | 禁止全自动 | | total amount | ≥99.5% | 禁止全自动 | | issue date
本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。