1、产品简介
基于商品 SKU 识别与多模态大模型定位构建的轻量陈列检测产品，面向货架、端架、冰柜、陈列台和堆头照片。产品按 SKU 汇总商品位置，并补充可见单品定位与短名称，便于业务系统开展商品位置展示、陈列盘点和后续铺货核验。
2、适用场景
陈列商品盘点：按 SKU 汇总识别到的商品框，供业务系统统计。
铺货清单核对：将识别出的 SKU 列表与业务侧目标清单比对。
单品位置复核：结合商品框和可见名称辅助检查识别结果。
3、功能介绍
按 SKU 聚合：Products 中同一 SkuId 汇总多个 Boxes，skuIds 返回去重后的 SKU 编码列表。
补充单品定位：多模态模型逐个定位可辨认的销售包装，并给出可确认的短名称。
两组结果独立使用：Products 来自 SKU 识别，grounding 来自补充定位；grounding 不返回 SKU 编码，也不承诺与 Products 逐项对应。
支持单张 HTTPS 图片输入；补充定位最多返回 12 个目标，每个目标包含类别、位置框和最多 24 字的可见文字，并通过 coverage 标明定位是否完整。
4、开发指南
本文请求和响应字段遵循对应搭建文档的实际大小写及结构。示例为业务工作流输入输出，不额外假设平台网关封装；对外调用地址、鉴权方式和网关封装应以实际发布接口为准。
4.1 请求参数
参数名 | 类型 | 必填 | 说明 |
imageUrl | String | 是 | 待识别原图的 HTTPS 地址；须可访问，不含空白或 URL 用户名密码 |
4.2 请求示例
{
"imageUrl": "https://example.com/images/api-05.jpg"
}示例图片地址和知识库标识（如有）为占位值，调用时替换为实际资源。
4.3 响应参数
通用字段：
字段路径 | 类型 | 说明 |
success | Boolean | 调用是否成功；有效业务结论不等于审核通过 |
errorCode | String | 成功为空字符串；失败为错误码 |
errorMessage | String | 成功为空字符串；失败为具体错误说明 |
result | Object | 业务结果；失败时为空对象 |
usageMap | Object | 成功为 {"ProcessingCount":1}；失败为空对象 |
usageMap.ProcessingCount | Integer | 成功处理计数为 1；失败时该字段不返回 |
业务字段：
字段路径 | 类型 | 说明 |
result.type | String | 固定为 sku |
result.Products | Array | 按 SKU 汇总的结果；成功时非空 |
| result.Products[ ].SkuId | String | 识别编码；由识别名称移除末尾 _ce 后得到 |
| result.Products[ ].Boxes | Array | 该 SKU 对应的位置框 |
| result.Products[ ].Boxes[ ].Left / Top / Right / Bottom | Integer | 左、上、右、下坐标；范围 0–1000，框必须有面积 |
| result.skuIds | Array | 去重后的 SkuId 列表 |
补充定位字段：
字段路径 | 类型 | 说明 |
result.grounding | Object | 补充元素定位结果 |
result.grounding.coverage | String | complete：相关可见目标完整；partial：仅部分目标有效或可辨认；空字符串：未获得有效补充定位结果 |
result.grounding.regions | Array | 目标数组，最多 12 项；没有相关目标时可为空 |
| result.grounding.regions[ ].label | String | 目标类别，枚举见下表 |
| result.grounding.regions[ ].bbox_2d | Integer[4] | [左上x,左上y,右下x,右下y]；0–1000；左<右，上<下 |
| result.grounding.regions[ ].text | String | 最多 24 字的可确认短名称或文字；看不清时为空字符串 |
目标类别：
label | 含义 |
product | 商品单品 |
坐标换算：横坐标像素值 = 横坐标 × 原图宽度 / 1000；纵坐标像素值 = 纵坐标 × 原图高度 / 1000。
定位仅有部分结果时可返回 success=true、coverage=partial。发生截断时，仅保留已完整解析的合法目标；删除无效框、去重、截短文字或超出目标数量限制也会标记 partial。合法空 regions 可成功，但不代表前置业务结果也允许为空。主业务识别成功后，补充定位失败不影响整体成功：grounding.coverage 返回空字符串，grounding.regions 返回空数组，ProcessingCount 仍为 1。主业务识别失败时，整体返回失败。
SKU 结果跳过空名称、empty 和 caps，按 SkuId 合并位置。本版本不会额外过滤全部 daiding 待定项。商品框由原归一化坐标乘 1000、四舍五入并限制到 0–1000。Products 为空，或待处理商品的位置框非法、无面积时返回失败；补充定位最多 12 框的限制仅适用于 grounding。
4.4 响应示例
以下均为结构示例，非实测结果。
1）成功响应
{
"success": true,
"errorCode": "",
"errorMessage": "",
"result": {
"type": "sku",
"Products": [
{
"SkuId": "sku_test",
"Boxes": [
{
"Left": 100,
"Top": 200,
"Right": 300,
"Bottom": 400
}
]
}
],
"skuIds": [
"sku_test"
],
"grounding": {
"coverage": "complete",
"regions": [
{
"label": "product",
"bbox_2d": [
100,
200,
300,
400
],
"text": "饮料"
}
]
}
},
"usageMap": {
"ProcessingCount": 1
}
}2）补充定位仅返回部分结果
{
"success": true,
"errorCode": "",
"errorMessage": "",
"result": {
"type": "sku",
"Products": [
{
"SkuId": "sku_test",
"Boxes": [
{
"Left": 100,
"Top": 200,
"Right": 300,
"Bottom": 400
}
]
}
],
"skuIds": [
"sku_test"
],
"grounding": {
"coverage": "partial",
"regions": [
{
"label": "product",
"bbox_2d": [
100,
200,
300,
400
],
"text": ""
}
]
}
},
"usageMap": {
"ProcessingCount": 1
}
}主业务成功，补充定位不可用
{
"success": true,
"errorCode": "",
"errorMessage": "",
"result": {
"type": "sku",
"Products": [
{
"SkuId": "sku_test",
"Boxes": [
{
"Left": 100,
"Top": 200,
"Right": 300,
"Bottom": 400
}
]
}
],
"skuIds": [
"sku_test"
],
"grounding": {
"coverage": "",
"regions": [ ]
}
},
"usageMap": {
"ProcessingCount": 1
}
}参数错误响应
{
"success": false,
"errorCode": "InvalidParameter",
"errorMessage": "imageUrl 必须为有效的 HTTPS 图片地址",
"usageMap": {},
"result": {}
}处理失败响应
{
"success": false,
"errorCode": "DownstreamUnavailable",
"errorMessage": "未获得有效商品识别结果",
"usageMap": {},
"result": {}
}4.5 错误码
错误码 | 含义 | 处理建议 |
InvalidParameter | 输入不合法或识别服务明确返回业务错误 | 根据 errorMessage 修正参数或业务输入后重新调用 |
DownstreamUnavailable | 鉴权、限流、超时、空响应、缺字段或解析等处理异常 | 根据 errorMessage 检查资源与服务状态；临时故障可稍后重试 |
应结合 success、errorCode、errorMessage 判断结果。源搭建文档未约定每类业务错误对应的 HTTP 状态码。平台公共错误码可参考错误码，本接口工作流错误码以上表为准。