Python Responses API视觉输入与本地金额校验最小实现
内容提要
文章介绍用 Python 调用 Responses API 识别发票图片的最小实现：模型仅输出候选字段，本地用 Decimal 重算含税金额并校验币种与上限，通过后才进入人工确认。强调不用浮点数算钱、不让模型决定批准、不记录密钥和原图，并给出超时与结构化输出等失败处理建议。
延伸解读
为什么金额校验必须放在本地
文章的核心设计是让视觉模型只输出候选字段，真正的金额判断由本地 Decimal 重算完成。这样做的好处是：模型识别错误不会直接变成付款动作，币种、上限和勾稽关系都由可审计的代码规则决定。对读者来说，这意味着任何涉及金额的 AI 提取场景，都应把模型定位为“录入助手”而非“审批者”，本地规则才是最终门禁。
代码里几个容易被忽略的工程细节
示例用 REST 而非 SDK，是为了让超时、异常和解析失败的分支对初学者可见。代码设置了 30 秒超时，并在调用或解析失败时统一返回拒绝理由。文章还提醒不要用浮点数算钱、不要把原始票据和密钥写进日志。这些细节说明，最小实现的价值不只在“能跑通”，更在于把失败路径和敏感信息处理提前暴露出来。
常见失败与生产环境的差距
文章列出四类常见问题：图片过大或格式不支持、模型返回 Markdown 围栏而非 JSON、网络超时、以及多税率发票无法套用单一小计公式。对应的生产建议包括压缩图片、启用结构化输出或更严格解析、重试并加幂等键。读者应意识到，示例适合低风险预录入和人工前置核验，不能直接用于绕过财务审批或税务判断。
接入真实页面时该展示什么
文章建议页面同时展示原图缩略图、模型原始候选、本地复算值和拒绝原因，而不是只给一个绿色“已通过”徽标。这样使用者能区分是识别值、规则计算值，还是两者存在差额。若模型读不出图片，应保留上传记录并让用户补图；若规则不通过，允许修正字段但要求说明原因。敏感字段日志只保留哈希或掩码，原图按保留期删除。
Q&A
如何用 Python 调用 Responses API 识别发票图片并校验金额？
使用 requests 库向 https://api.openai.com/v1/responses 发送 POST 请求，将图片 base64 编码后作为 input_image 传入，提示模型只返回 JSON 格式的 subtotal、tax、total、currency。收到响应后，用 Decimal 重算含税金额，检查币种是否为 CNY、总额是否超过上限（如 2000 元），以及 subtotal + tax 是否等于 total（误差不超过 0.01）。通过校验后进入人工确认。
为什么不能用浮点数计算发票金额？
浮点数存在精度问题，可能导致金额计算出现微小误差，例如 0.1 + 0.2 不等于 0.3。在财务场景中，这种误差可能累积并导致对账失败或错误批准。文章强调必须使用 Decimal 类型进行金额计算，以确保精确性。
模型识别出发票金额后，为什么不能直接批准付款？
因为模型输出只是候选字段，可能存在识别错误或幻觉。系统必须由本地规则进行二次校验，包括重算含税金额、检查币种和上限，只有通过校验才能进入人工确认。模型不能决定是否批准，最终批准权应保留给人工或财务审批流程。
调用 Responses API 时常见的失败情况有哪些？如何处理？
常见失败包括：图片太大或格式不支持，需压缩并核对视觉文档；模型返回 Markdown 围栏而非纯 JSON，应启用结构化输出或严格解析；网络超时，代码已设 30 秒超时，生产环境应增加重试和幂等键；发票有多税率时不能沿用单一小计公式。此外，需处理字段缺失或非数字的情况。
这个最小实现适合哪些业务场景？有哪些限制？
适合低风险预录入和人工前置核验，例如发票、收据、质检单的字段提取。不适合绕过财务审批、税务判断或未获授权的证件处理。它仅作为辅助工具，不能替代人工决策，且需注意敏感信息保护。
在生产环境中，如何安全地处理发票图片和密钥？
不要将原始票据和密钥写入日志。对发票号、身份证号等敏感字段，日志只保留哈希或局部掩码。原图应按组织保留期自动删除。密钥通过环境变量设置，避免硬编码。批量场景可使用同一文件的 SHA-256 作为幂等键，防止重复处理。
