陈列检测

1.1 产品简介

陈列检测基于多模态大模型（MLLM）和视觉向量召回，对门店实拍的货架、地堆等陈列图片进行商品检测和 SKU 识别。服务先定位独立商品包装，获得边界框和初步名称，再将商品图像与客户专属 SKU 知识库进行相似度匹配，输出逐商品结构化结果。

业务系统可根据返回的商品位置、SKU 编码、名称和相似度，开展陈列盘点、铺货核验、远程稽核与人工复核。

1.2 适用场景

铺货清单比对、缺货判断和陈列合规判定由业务系统结合识别结果及门店任务要求完成。

1.3 核心能力

• 检测与召回协同。 检测阶段提供位置框和初步名称，召回阶段提供知识库内的 SKU 编码、名称及相似度。

• 指定知识库召回。 RagId 定位本次检索的商品知识库，服务结合调用身份进行访问控制。

• 逐商品输出。 每个检测框独立返回位置、首位召回商品和候选列表，便于业务统计及人工追溯。

• 自定义检测规则。 通过 Rule 描述标注范围、单品划分和输出格式，适配不同陈列场景。

• 知识库持续维护。 通过后台或内容管理 API 维护商品图片，待处理完成、知识库可用后用于识别。

2.1 识别流程

门店实拍货架或地堆图片
    ↓
多模态大模型逐件检测商品
    ↓
输出商品框与初步名称
    ↓
按框提取商品图像并计算视觉向量
    ↓
在 RagId 指定的商品知识库中召回 SKU
    ↓
返回框坐标、Top1、Topk、相似度及逐框错误
    ↓
业务系统按阈值、目标 SKU 清单和业务规则处理结果

检测阶段的初步名称帮助描述图片内容。业务对接时，从 Top1.SkuName 读取召回的商品名称，并结合 Top1.Score 判断是否采用。

2.2 接入顺序

1. 开通 Aidge 服务，为调用身份配置 RAM 授权。

2. 在产品后台新建知识库，选择通用链路和通用模型。

3. 下载模板、填写商品资料并上传，等待知识库可用。

4. 在官方 API 调试页验证少量样本，核对框位置、名称、SKU 编码和相似度。

5. 使用官方 SDK 接入业务系统，配置 60 秒读超时。

6. 根据实际流控控制发送频率，处理调用异常和逐框失败，持续维护商品知识库。

3.1 开通服务

使用接口前，请先完成 Aidge 服务开通。

Aidge 服务开通地址

3.2 配置授权

为调用接口的 RAM 用户或 RAM 角色授予系统策略 AliyunAidgeFullAccess。添加权限时搜索 aidge，选择该策略并确认授权。

该接口对应的权限 Action 为 aidge:MerchandisePlacementDetection，资源范围为 *。管理员采用自定义权限策略时，可结合 API 授权信息配置。调用身份还需具有目标知识库的访问权限。

阿里云凭据在客户服务端配置。本文 Python 示例通过环境变量读取 AccessKey。

5.1 选择通用链路

进入 Aidge 后台的商品知识库管理，创建知识库时选择 通用链路。在模型选择项中选择对应的 通用模型，再完成知识库创建。

建议优先使用通用模型开展测试和接入。如需使用场景定制训练模型，请先与智能巡检团队沟通，确认合作方案及模型适用范围后再选择，避免自行选用。

5.2 下载模板并准备商品数据

进入已创建的知识库，按照页面指引导入商品数据。

建议先下载后台提供的模板，按模板填写商品信息后，再上传至知识库。 文件格式、列名、必填项和批次要求，以下载时的模板及后台提示为准。

准备的数据需要包含商品标识、商品名称和商品参考图片。既有系统字段可按下表整理，上传时使用后台模板的实际字段。

后台字段映射页面如使用 PrimaryKey、SkuName、SkuImageUrl，分别对应上述商品标识、商品名称和商品图片地址。同一个 SKU 可以关联多张参考图，商品数与图片记录数分别统计。

5.3 检查导入结果

上传完成后，检查导入结果，处理失败项，等待商品图片处理及索引构建完成。知识库可用后，从后台获取知识库 ID，填入检测请求的 RagId。

商品新增或更新后，应核对处理状态，再开展对应 SKU 的识别验证。

5.4 通过 API 维护内容

首次新建知识库必须在产品后台完成。 创建完成后，可通过 API 对已有陈列知识库中的商品图片记录进行增删改查。

使用 RagId 定位已有知识库，使用平台返回的 RecordId 定位单条图片记录。新增、修改操作受理后，通过查询接口检查记录状态。同一 SKU 多图的维护，需要分别核对各图片记录。

接口参数、状态和完整示例请查阅官方文档。

陈列检测知识库内容管理 API

6.1 参数说明

6.2 参数组合

通用客户首次接入采用 ImageUrl + Rule + RagId，便于明确检测范围和商品库范围。

参数校验逻辑如下。

1. 每次检测均需提供有效的 ImageUrl。

2. 传入非空 Rule 时进入自定义规则分支，此路径可省略 Type。

3. 使用商品知识库召回时，需通过请求或 ApiId 的默认配置提供有效的 RagId。

4. 未提供有效 Rule，且通过请求或 ApiId 默认配置也无法得到 Type 时，参数不完整。

5. 使用 ApiId 前，需在产品后台“智能巡检 → API 管理 → 我的 API”核对其功能和默认参数。

6.3 图片输入要求

• 使用公网或 OSS 可访问的 HTTP(S) 图片 URL，保证服务处理期间地址仍然有效。

• 图片响应包含有效的 Content-Length。

• 每次请求传入一张图片的 URL 字符串。

• 对带 EXIF 方向信息的图片，接入方应统一输入像素方向，并使展示、坐标换算和裁图采用同一方向。

6.4 Rule 示例

以下提示词适合从通用货架场景开始验证。

请检测图片中货架上的商品，一物一框。以JSON数组输出每件商品的边界框和商品名称。坐标按照整张图片归一化到0至1000。只返回JSON数组。输出格式示例：[{"bbox_2d":[100,200,250,600],"sku_name":"xxxx"}]

调整 Rule 时，明确标注对象、检测范围、一物一框要求和坐标格式。提示词中的 sku_name 是检测阶段的初步名称，召回结果从 Top1 读取。

6.5 自定义规则调用示例

{
  "ImageUrl": "https://<your-image-host>/shelf.jpg",
  "Rule": "请检测图片中货架上的商品，一物一框。以JSON数组输出每件商品的边界框和商品名称。坐标按照整张图片归一化到0至1000。只返回JSON数组。输出格式示例：[{\"bbox_2d\":[100,200,250,600],\"sku_name\":\"xxxx\"}]",
  "RagId": "<your-knowledge-base-id>"
}

6.6 内置规则调用示例

{
  "ImageUrl": "https://<your-image-host>/shelf.jpg",
  "Type": "<your-enabled-business-type>",
  "RagId": "<your-knowledge-base-id>"
}

以上 JSON 展示业务参数结构。通过官方 SDK 或 OpenAPI 调用工具完成签名和参数序列化，原始 HTTP 请求方式以对应 API 文档为准。

7.1 官方文档与小规模调试

查看 API 参数细节、各语言 SDK 代码示例，或进行小规模在线调试，请前往官方 API 页面。填写自己的图片 URL、Rule 和知识库 ID，先验证少量样本，再参考生成的代码接入业务系统。

MerchandisePlacementDetection 官方 API 文档与调试页面

7.2 安装依赖与配置凭据

Python SDK 使用 5.8.0 或更高版本，以支持 rule 字段。

pip install "alibabacloud_aidge20260428>=5.8.0"

运行前配置以下环境变量。

7.3 完整 Python 示例

import json
import os

from alibabacloud_aidge20260428.client import Client
from alibabacloud_aidge20260428.models import MerchandisePlacementDetectionRequest
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions


RULE = (
    '请检测图片中货架上的商品，一物一框。'
    '以JSON数组输出每件商品的边界框和商品名称。'
    '坐标按照整张图片归一化到0至1000。只返回JSON数组。'
    '输出格式示例：[{"bbox_2d":[100,200,250,600],"sku_name":"xxxx"}]'
)


def main():
    client = Client(Config(
        access_key_id=os.environ["ALIBABA_CLOUD_ACCESS_KEY_ID"],
        access_key_secret=os.environ["ALIBABA_CLOUD_ACCESS_KEY_SECRET"],
        endpoint="aidge.cn-beijing.aliyuncs.com",
        region_id="cn-beijing",
    ))

    request = MerchandisePlacementDetectionRequest(
        image_url=os.environ["AIDGE_IMAGE_URL"],
        rule=RULE,
        rag_id=os.environ["AIDGE_RAG_ID"],
    )

    try:
        response = client.merchandise_placement_detection_with_options(
            request,
            RuntimeOptions(read_timeout=60000, connect_timeout=15000),
        )
    except Exception as error:
        print("调用异常", str(error))
        raise

    body = response.body.to_map()
    print(json.dumps(body, ensure_ascii=False, indent=2))

    if body.get("Success") is not True:
        print(
            "识别调用失败",
            "Code", body.get("Code"),
            "Message", body.get("Message"),
            "RequestId", body.get("RequestId"),
        )
        return

    data = body.get("Data") or {}

    items = data.get("Data") or [ ]

    print("框数", data.get("BoxCount"))
    print("用量", data.get("UsageMap"))

    for item in items:
        top1 = item.get("Top1") or {}
        if item.get("Error"):
            print("单框失败", item.get("Idx"), item.get("Error"))
            continue

        print(
            "框编号", item.get("Idx"),
            "坐标", item.get("Bbox"),
            "SKU ID", top1.get("SkuId"),
            "名称", top1.get("SkuName"),
            "相似度", top1.get("Score"),
        )


if __name__ == "__main__":
    main()

保留完整响应和 RequestId，便于核对逐框结果与排查异常。

8.1 响应结构口径

本指南的主结构与当前公开 OpenAPI 返回参数、本机核对的 Python SDK 5.8.0 模型，以及已有线上调用结果一致。

响应体
├── Success
├── Code
├── Message
├── RequestId
└── Data
    ├── BoxCount
    ├── UsageMap

    └── Data[ ]

        ├── Idx
        ├── Bbox
        ├── Error
        ├── Top1
        │   ├── SkuId
        │   ├── SkuName
        │   └── Score

        └── Topk[ ]

            ├── Rank
            ├── SkuId
            ├── SkuName
            └── Score

陈列检测

8.2 顶层字段

HTTP 状态与业务状态分别检查。收到 HTTP 200 后，继续读取 Success、Code、Message，判断识别调用是否成功。

8.3 业务结果字段

UsageMap 中可包含 ProcessingCount，例如 {"ProcessingCount": 1}。用量与计费以服务实际返回及账单口径核对。

8.4 单框结果字段

以下字段以 Data.Data 数组中的单个商品对象为起点。Top1 为首位召回商品，Topk 为候选商品数组；表中“候选项”表示 Topk 数组中的一条记录。

当前公开接口将 Score 描述为 0–1 的相似度。客户端直接使用接口分数，阈值与该分数保持同一口径。

8.5 成功、空结果与逐框失败

1. 顶层 Success=false 时，按调用失败处理，记录错误信息和 RequestId。

2. 顶层成功且 Data.BoxCount=0 时，按空检测结果处理。

3. 顶层成功且存在检测框时，逐框检查 Error、Top1 和相似度。

4. 某个框发生错误时，可保留同次响应中其他已成功的框，并将异常框送复核。

5. 正常召回但低于业务阈值的框，由业务系统按低分规则归类。

如业务系统需要“成功召回数”，可在调用方统计无逐框错误且存在有效 Top1.SkuName 的框数，再单独统计达到业务阈值的框数。

8.6 坐标换算

设与坐标方向一致的原图宽为 W、高为 H，则像素坐标换算如下。

left   = x1 × W / 1000
top    = y1 × H / 1000
right  = x2 × W / 1000
bottom = y2 × H / 1000

横坐标和纵坐标分别按原图宽、高换算。显示图经过旋转、裁剪或缩放时，应同步变换坐标。

8.7 相似度阈值与业务判定

客户结合本品、其他品、相近包装和库外商品样本评估阈值。若项目约定阈值为 T，可在调用方使用以下规则。

阈值按项目验证结果配置。接口成功、检测框数量与最终业务确认数量分别统计。

9.1 正常识别并召回商品

{
  "Success": true,
  "Code": "success",
  "Message": "Success",
  "RequestId": "<request-id>",
  "Data": {
    "BoxCount": 2,
    "UsageMap": {"ProcessingCount": 1},
    "Data": [
      {
        "Idx": 0,
        "Bbox": [120.5, 88.0, 240.0, 360.5],
        "Top1": {
          "SkuId": "example-sku-001",
          "SkuName": "示例品牌保湿水200ml",
          "Score": 0.873
        },
        "Topk": [
          {
            "Rank": 1,
            "SkuId": "example-sku-001",
            "SkuName": "示例品牌保湿水200ml",
            "Score": 0.873
          }
        ]
      },
      {
        "Idx": 1,
        "Bbox": [240.0, 90.0, 360.0, 362.0],
        "Top1": {
          "SkuId": "example-sku-002",
          "SkuName": "示例品牌保湿乳150ml",
          "Score": 0.802
        },
        "Topk": [
          {
            "Rank": 1,
            "SkuId": "example-sku-002",
            "SkuName": "示例品牌保湿乳150ml",
            "Score": 0.802
          }
        ]
      }
    ]
  }
}

9.2 部分框处理失败

以下示例包含一个成功框和一个失败框，调用方逐框读取处理结果。

{
  "Success": true,
  "Code": "success",
  "Message": "Success",
  "RequestId": "<request-id>",
  "Data": {
    "BoxCount": 2,
    "UsageMap": {"ProcessingCount": 1},
    "Data": [
      {
        "Idx": 0,
        "Bbox": [120, 88, 240, 360],
        "Top1": {
          "SkuId": "example-sku-001",
          "SkuName": "示例品牌保湿水200ml",
          "Score": 0.861
        },
        "Topk": [
          {
            "Rank": 1,
            "SkuId": "example-sku-001",
            "SkuName": "示例品牌保湿水200ml",
            "Score": 0.861
          }
        ]
      },
      {
        "Idx": 1,
        "Bbox": [240, 90, 360, 362],
        "Top1": null,

        "Topk": [ ],

        "Error": "embedding_failed"
      }
    ]
  }
}

9.3 未检测到商品

{
  "Success": true,
  "Code": "success",
  "Message": "Success",
  "RequestId": "<request-id>",
  "Data": {
    "BoxCount": 0,
    "UsageMap": {"ProcessingCount": 1},

    "Data": [ ]

  }
}

9.4 知识库无效或不可用

{
  "Success": false,
  "Code": "InvalidParameter",
  "Message": "Invalid request parameter: ragId is invalid, not found or unavailable: <your-knowledge-base-id>",
  "RequestId": "<request-id>"
}

10.1 常见情况

10.2 批量调用与重试

批量任务为每张图片独立发送请求并保存结果。记录图片业务编号、调用时间、耗时、参数、RequestId、调用状态、框数和逐框错误，便于追溯。

遇到限流或临时服务异常时，降低发送频率并采用有上限的延迟重试。参数或权限错误在修正后重试。超时后重新发起请求属于新的调用，费用按服务实际计费规则核对。

大规模调用前，先在目标账号下验证实际发送速率、并发、耗时和成功率，再确定任务调度参数。

11.1 检测接口参考价格

陈列检测参考单价为 0.096 元/次。 每次请求处理一张图片，计费单位为次。正式结算价格、优惠和计费明细以产品计费页面、服务开通配置及商务约定为准。

计费说明

11.2 预算估算

按 0.096 元/次计算，预算示例如下。

估算费用 = 可计费调用次数 × 0.096 元/次

失败请求、超时请求、重试及其他能力的具体计费范围，以实际计费规则和账单为准。

11.3 月度和年度资源包

陈列检测提供月包和年包，可按预计调用量选择资源包。次数档位包括 1 万至 10 万次，以及 50 万次、100 万次，最高可享 19% 优惠。具体可选档位、有效期、价格和优惠以购买页面为准。

第 11.2 节的预算按 0.096 元/次估算，选购资源包时按对应套餐价格核算预算。

11.4 知识库维护计费

知识库内容管理接口的费用按服务实际开通配置或商务约定执行，需单独核对其计费规则。