Java 17 调用视觉 Responses API：JSON 约束与人工复核路由
内容提要
文章介绍使用Java 17标准HttpClient调用视觉Responses API，让模型输出商品图的JSON候选信息，再根据置信度和字段完整性决定自动发布（AUTO）或转人工复核（REVIEW）。强调模型输出仅为候选，高风险品类必须人工确认，并需设置超时、审计记录和分层评测集。
延伸解读
为什么模型输出只能当候选
文章强调，图像模型擅长把像素归纳成文字，但无法替企业定义“错一次的代价”。即使模型给出高置信度，童装年龄段、医疗器械、过敏原、奢侈品真伪等高风险品类也必须强制人工复核。置信度本身是模型声明，并非经过校准的概率，因此不能直接作为自动发布的唯一依据。
自动发布门禁的工程实现要点
示例代码用置信度阈值和字段完整性决定 AUTO 或 REVIEW，但生产环境需注意：不要用正则从 HTTP 响应提取模型文本，应使用 Jackson 等库解析 Responses 输出数组，并设置结构化输出约束。同时要检查模型是否真的返回了字段，而非只看 HTTP 200。金额、尺寸、库存等不应直接自动写库，应先写草稿并由业务系统校验。
评测集与权限设计不能省
文章指出，评测集不能只挑清晰的成功样本，应收集遮挡、拼图、多件商品、反光、外包装不一致和文字混杂等失败案例，并按品类和风险分层。每次更换模型、提示词或预处理，需用同一冻结样本比较自动放行率、人工改写率和严重错误率，后两项未恶化才扩大自动范围。权限上，模型只读授权对象，业务服务写草稿，审核员确认必须记名。
Q&A
Java 17 如何调用视觉 Responses API 并让模型返回 JSON 格式的商品信息？
使用 Java 17 标准 HttpClient 向 https://api.openai.com/v1/responses 发送 POST 请求，请求体包含 model 和 input 数组，input 中同时放入 input_text（提示词要求只返回 JSON）和 input_image（图片 URL）。设置 Authorization 和 Content-Type 头，超时 30 秒。示例代码中提示词为：识别商品图，只返回 JSON：{"category":"","material":"","confidence":0.0}。
模型返回的 JSON 候选信息如何决定自动发布还是转人工复核？
根据置信度和字段完整性决定：当 confidence >= 0.90 且 category 和 material 字段均非空时返回 AUTO，否则返回 REVIEW。示例中 decide 方法实现了该逻辑。高风险品类（如童装年龄段、医疗器械、过敏原、奢侈品真伪）即使置信度高也应强制 REVIEW。
为什么模型输出只能作为候选信息，不能直接写入库存系统？
因为模型可能自信地输出错误尺寸、材质或适用人群，且置信度是模型声明而非校准概率。模型不应拥有库存系统的写权限。正确做法是先写草稿，由业务系统做单位、枚举和权限校验，高风险品类必须人工确认。
调用视觉 API 时常见的错误有哪些？
常见错误有四个：1. 把本地磁盘路径当作 image_url，服务端看不到，应使用官方允许的 URL 或数据输入形式；2. 只看 HTTP 200，不检查模型是否真的给出了字段，应检查空字段并路由复核；3. 金额、尺寸和库存直接自动写库，应先写草稿并做业务校验；4. 没有设置 30 秒请求超时，网络抖动会占满工作线程。
这个方案适合哪些业务场景，不适合哪些？
适合商品建档、资产盘点、质检初筛等“人机协同”任务。不适合识别人脸后决定资格、自动鉴定高价值真伪，或在没有授权的数据上批量处理。
如何构建评测集来验证和扩大自动发布范围？
评测集不能只挑清晰成功样本，应收集遮挡、拼图、多件商品、反光、外包装不一致和文字混杂等失败案例，并按品类和风险分层。每次更换模型、提示词或预处理时，用同一冻结样本比较自动放行率、人工改写率和严重错误率；后两项没有恶化，才扩大自动范围。
工程化落地还需要做哪些配套措施？
需要用队列隔离上传与推理，按哈希去重，给每次决策创建审计记录，并让审核员的改动回流为评测集。权限要落在系统里：模型只读授权对象，业务服务才写草稿，审核员确认必须记名。REVIEW 只是风险控制一层，不能替代隐私、告知和删除责任。
