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

1. 产品简介

本组 API 用于管理已有陈列商品知识库中的图片记录。一个商品可上传多张不同角度的参考图，每张图片为一条独立记录。客户无需生成额外的 primary_key，平台在新增和查询结果中返回 RecordId，用于后续修改、删除。

2. 适用场景

• 商品资料批量导入：将商品名称、编号和参考图批量导入已有知识库。

• 商品图片日常维护：更换包装图、补充多角度参考图、删除过期图片。

• 自建系统对接：在客户业务系统展示图片和入库状态，通过记录 ID 精确维护。

3. 功能介绍

四个接口均使用 HTTPS、POST，版本为 2026-04-28，认证方式为 AccessKey。调用域名和地域使用实际开通服务提供的配置，推荐在服务端通过正式 SDK／OpenAPI 调用工具完成签名和参数序列化。

四个接口均同步返回。 新增、修改结果中的逐条成功表示“是否受理”，不代表后续图片处理已全部完成；请通过查询接口查看记录状态。响应中的 TaskId 在同步接口中为空，无需通过任务 ID 轮询。

4. 标识与调用流程

同一商品多图可使用相同 SKU ID、名称；按 SkuId 查询获取所有匹配记录，再选择对应 RecordId 维护。建议客户为每个商品维护稳定的 SKU ID，不同商品尽量区分编号。

1. AddDisplayKnowledge：新增记录

新增 Records 数组中每条记录的字段

请为每张图片提供商品名称和有效图片地址。新增多角度参考图时，在 Records 中分别填写。

业务参数示例：

{
  "RagId": "your-rag-id",
  "Records": [
    {
      "SkuId": "SKU-001",
      "SkuName": "示例商品",
      "ImageUrl": "https://example.com/front.jpg"
    },
    {
      "SkuId": "SKU-001",
      "SkuName": "示例商品",
      "ImageUrl": "https://example.com/back.jpg"
    }
  ]
}

两个图片地址为占位示例，需替换成实际可下载的图片地址。

2. QueryDisplayKnowledge：查询内容

按商品编号查询：

{
  "RagId": "your-rag-id",
  "SkuId": "SKU-001",
  "PageNum": 1,
  "PageSize": 100
}

不填 SkuId、SkuName、Statuses 时，按分页读取库内内容。同一编号匹配多张图时，逐条读取返回记录；根据 TotalPage 继续请求后续页，不只取第一条。

只查询失败记录：

{
  "RagId": "your-rag-id",
  "Statuses": ["FAILED"],
  "PageNum": 1,
  "PageSize": 100
}

3. UpdateDisplayKnowledge：修改记录

先通过新增结果或查询结果取得要修改的 RecordId，再提交修改内容。

修改 Records 数组中每条记录的字段

建议带上该记录当前需要保留的名称和图片地址，再替换要修改的字段。SkuId 的明确规则是“非空时覆盖原值”，不能将省略或空值理解为清空原编号。

业务参数示例：

{
  "RagId": "your-rag-id",
  "Records": [
    {
      "RecordId": 10001,
      "SkuId": "SKU-001",
      "SkuName": "示例商品",
      "ImageUrl": "https://example.com/front-new.jpg"
    }
  ]
}

10001 为记录 ID 示例，需替换成平台实际返回的 ID。修改按 RecordId 定位，不会因为其他图片的 SkuId 相同就自动修改整组。

4. DeleteDisplayKnowledge：删除记录

业务参数示例：

{
  "RagId": "your-rag-id",
  "RecordIds": [10001, 10002]
}

仅删除明确指定的记录。如果要删除某商品的所有参考图，应先按 SkuId 查询并读完全部分页，核对记录后，再将相应 RecordId 分批提交。

请求说明

• 新增、修改时为每张图片提供名称和有效 HTTP(S) 地址。新增 SKU ID 为空时平台生成；修改 SKU ID 非空时覆盖原值，省略或空值不能视为清空编号。

• 修改、删除按 RecordId 定位，不按相同 SKU ID 自动操作整组图片。更换多张图时分别传入各自记录 ID，增加或减少图片分别使用新增、删除接口。

• 这组接口未定义按 SKU ID 原子替换整个图片集合，也未定义客户端幂等请求参数，不能假设多次调用自动合并、回滚或去重。

• 图片 URL 为临时地址时，须保证平台下载期间仍然有效。

• RecordId 为 int64，接入端应使用能够保留大整数精度的 SDK 或解析方式。

1. 顶层字段

2. Data 公共字段

3. 新增、修改的业务结果

Data.Results 数组中每条结果的字段

4. 删除的业务结果

除 AcceptedCount、FailedCount 和 Results 外，额外返回 Data.RemainingCount（int32），表示删除后可见记录数。

Results 字段结构与新增、修改相同，但 Results[ ].Success 表示是否删除；SkuId 和 Status 为空。删除时通过 RecordId、Success 及错误信息判断结果。

5. 查询的业务结果

Data.Records 数组中每条记录的字段

6. 状态与成功判断

记录状态枚举为 UPDATING、EMBEDDED、GENERATED、FAILED。请保留实际返回值，勿用历史方案的状态值替换。FAILED 时结合失败编码及说明处理；需要了解知识库检测可用性时，同时查看 KnowledgeBaseStatus。

判断顺序：顶层 Success／Code → Data.Success／业务错误 → 写操作 Results 的逐条结果。新增、修改中的受理成功不代表向量化已经完成，后续通过查询接口读取记录状态。

1. 新增／修改：记录已受理

{
  "RequestId": "request-example",
  "Code": "success",
  "Success": true,
  "Message": "Success",
  "Data": {
    "UsageMap": {},
    "TaskId": "",
    "Success": true,
    "ErrorCode": "",
    "ErrorMessage": "",
    "RagId": "your-rag-id",
    "KnowledgeBaseStatus": "UPDATING",
    "AcceptedCount": 1,
    "FailedCount": 0,
    "Results": [
      {
        "Index": 0,
        "Success": true,
        "RecordId": 10001,
        "SkuId": "SKU-001",
        "Status": "UPDATING",
        "ErrorCode": "",
        "ErrorMessage": ""
      }
    ]
  }
}

2. 查询：返回同一 SKU 的两张图片

{
  "RequestId": "request-example",
  "Code": "success",
  "Success": true,
  "Message": "Success",
  "Data": {
    "UsageMap": {},
    "TaskId": "",
    "Success": true,
    "ErrorCode": "",
    "ErrorMessage": "",
    "RagId": "your-rag-id",
    "Total": 2,
    "PageNum": 1,
    "PageSize": 20,
    "TotalPage": 1,
    "Records": [
      {
        "RecordId": 10001,
        "SkuId": "SKU-001",
        "SkuName": "示例商品",
        "Status": "UPDATING",
        "ImageUrl": "https://example.com/front.jpg?signature=example",
        "ImageUrlExpireTime": "2026-10-20T10:00:00+08:00",
        "GmtModified": "2026-10-19T10:00:00+08:00"
      },
      {
        "RecordId": 10002,
        "SkuId": "SKU-001",
        "SkuName": "示例商品",
        "Status": "UPDATING",
        "ImageUrl": "https://example.com/back.jpg?signature=example",
        "ImageUrlExpireTime": "2026-10-20T10:00:00+08:00",
        "GmtModified": "2026-10-19T10:00:00+08:00"
      }
    ]
  }
}

3. 删除：返回删除结果

{
  "RequestId": "request-example",
  "Code": "success",
  "Success": true,
  "Message": "Success",
  "Data": {
    "UsageMap": {},
    "TaskId": "",
    "Success": true,
    "ErrorCode": "",
    "ErrorMessage": "",
    "RagId": "your-rag-id",
    "KnowledgeBaseStatus": "UPDATING",
    "AcceptedCount": 1,
    "FailedCount": 0,
    "RemainingCount": 1,
    "Results": [
      {
        "Index": 0,
        "Success": true,
        "RecordId": 10001,
        "SkuId": "",
        "Status": "",
        "ErrorCode": "",
        "ErrorMessage": ""
      }
    ]
  }
}