Java HttpClient 调用 Gemini 图像理解与金额字段校验
内容提要
文章介绍用 Java 17 的 HttpClient 调用 Gemini 图像理解接口，从发票图片中提取发票号和金额。做法是让模型只返回单行 JSON 候选字段，再由 Java 校验格式、金额上限和必填项，避免把模型输出直接当财务事实。文中给出完整示例代码，并提醒密钥用环境变量、金额用 BigDecimal、HTTP 200 不等于识别成功，仅适合低风险预填和人工审核场景。
延伸解读
为什么不让模型直接输出财务结果
文章的核心思路是把视觉语言模型的输出当作候选字段，而不是最终财务事实。模型可能把“含税金额”和“价税合计”看混，因此 Java 侧必须重新校验发票号格式、金额范围和必填项。这种分工让模型负责识别，程序负责规则判断，避免把模型文本直接用于报销或付款。
示例代码中的校验边界与局限
示例把发票号限定为 6–32 位字母数字或连字符，金额限定在 0–50000 之间，并用 double 做范围门禁。文章明确说明这个上限只是教学阈值，不是通用财务规则，真实金额应使用 BigDecimal 并按币种规则舍入。因此代码适合演示流程，不能直接照搬到生产结算。
HTTP 200 不等于识别成功
文章提醒，即使接口返回 200，也不代表模型正确识别了票据。仍需检查候选字段是否完整、格式是否合法、与业务是否一致。格式异常或无法读取时应进入 REVIEW 流程。这一提醒把错误处理从网络层延伸到业务层，避免仅凭状态码判断成功。
适用场景与工程化注意事项
该方案适合低风险的预填单、票据归档和人工审核加速，不适合无人工复核的付款、税务申报或凭证替代。工程化时可增加图片大小限制、病毒扫描、同一发票号去重、原图访问权限、双模型抽检与人工纠正回流。密钥应通过环境变量读取，避免写入类文件或调试日志。
Q&A
怎么用 Java 17 的 HttpClient 调用 Gemini 图像理解接口从发票图片里提取发票号和金额？
把图片 Base64 编码后作为 inline_data 放进请求体，提示模型只返回单行 JSON（如 {"invoice_no":"","total_amount":"0.00"}），再用 HttpClient 发 POST 请求到 generateContent 接口，最后从响应文本里解析出字段。
为什么不能把 Gemini 返回的金额直接当财务事实使用？
模型输出只是候选字段，可能把“含税金额”和“价税合计”看混，所以必须由 Java 再校验金额格式、上限和必填项，不能直接用于报销或付款。
Java 端对发票号和金额做了哪些校验？
发票号限定为 6–32 位字母数字或连字符；金额解析为数字后要求大于等于 0 且不超过 50000。上限只是教学阈值，实际应改成企业政策。
调用 Gemini 图像理解时有哪些常见错误需要避免？
不要把原始票据上传到调试日志；不要用 double 做真实金额结算（应使用 BigDecimal）；不要只看 HTTP 200 就认为识别成功，还要检查候选字段与业务一致性。
这种发票识别方案适合用在哪些场景？
适合低风险的预填单、票据归档和人工审核加速；不适合无人工复核的付款、税务申报与凭证替代。
工程化落地时还可以增加哪些措施？
可以增加图片大小限制、病毒扫描、同一发票号去重、原图访问权限、双模型抽检与人工纠正回流。
