商品推荐

1. 接口介绍

该接口面向对话场景下的商品推荐。系统会先判断当前对话是否需要推荐，再基于用户原始问题和意图识别结果中的关键信息进行多路召回，经过过滤与重排后返回完整商品结果。

2. 请求地址

POST https://openapi.wisediag.com/api/recommend/product

3. 请求参数

字段名	类型	必填	说明
`agentId`	String	✅	客户或代理标识，用于定位推荐商品集合
`messages`	Array	✅	对话消息数组，需包含 `user` 与 `assistant` 消息
`limitFinal`	Number	可选	最终返回商品数，默认 `5`

4. 请求示例

curl --location 'https://openapi.wisediag.com/api/recommend/product ' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-***************' \
--data '{
  "agentId": "demo",
  "limitFinal": 5,
  "messages": [
    {"role": "user", "content": "我最近总是失眠，怎么办？"},
    {"role": "assistant", "content": "可以先从作息和压力管理入手。"},
    {"role": "user", "content": "推荐一些适合缓解失眠的产品"}
  ]
}'

5. 响应说明

接口返回标准 JSON：

字段名	类型	说明
`recommendationState`	String	推荐状态，如 `recommend` / `nonRecommend` / `failRecommend`
`finalRecommendations`	Array	最终推荐商品列表，返回完整商品对象，元素结构见下表
`intentRecognizeResult`	Object	结构化意图识别结果

finalRecommendations 中每个商品对象的字段说明：

字段名	类型	说明
`itemId`	String	商品唯一标识（对应入库时的 `primaryId`）
`searchScore`	Number	多路召回阶段得分
`recReason`	String	召回来源/原因，如 `基于向量`
`keyword`	String	命中关键词，多个以空格分隔
`rankScore`	Number	重排阶段最终得分，值越大越靠前
`skuId`	String	SKU 标识
`status`	String	商品状态，最终推荐仅保留 `active`
`productName`	String	商品名称
`skuInfoText`	String	商品描述文本，用于构建召回向量
`link`	String	商品详情链接
`imgLink`	String	商品图片链接
`extraInfo`	Object	入库时写入的自定义扩展字段集合

响应示例：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "agentId": "demo",
    "recommendationState": "recommend",
    "finalRecommendations": [
      {
        "itemId": "sku_001",
        "searchScore": 1.0,
        "recReason": "基于向量",
        "keyword": "失眠 睡前助眠 缓解失眠",
        "rankScore": 0.98,
        "skuId": "sku_001",
        "status": "active",
        "productName": "褪黑素片",
        "skuInfoText": "适合睡前使用，帮助改善睡眠节律",
        "link": "https://example.com/p/sku_001",
        "imgLink": "https://example.com/p/sku_001.jpg",
        "extraInfo": {
          "brand": "示例品牌"
        }
      }
    ],
    "intentRecognizeResult": {
      "currentQuery": "推荐一些适合缓解失眠的产品",
      "currentAnswer": "可以先从作息和压力管理入手。",
      "recommendScore": 8.0,
      "focusDepartment": ["精神心理科"],
      "relatedEntities": ["失眠"],
      "targetAudience": [],
      "scenarioBased": ["睡前助眠"],
      "problemSolving": ["缓解失眠"],
      "threshold": 6.0
    }
  }
}

6. 推荐商品入库接口调用指南

6.1 接口地址

POST https://openapi.wisediag.com/api/recommend/database

6.2 适用场景

用于按 agentId 创建或加载商品 collection，并批量写入商品数据。系统会自动：

使用固定 collection 名 recommend_items_{agentId}
基于 skuInfoText 自动生成向量
将客户自定义字段作为动态字段存储

6.3 请求参数

字段名	类型	必填	说明
`agentId`	String	✅	客户或代理标识
`data`	Array	✅	待写入商品数据列表，元素字段说明见下表

data 数组中每个商品对象的字段说明：

字段名	类型	必填	说明
`primaryId`	String	✅	商品主键，唯一标识；`upsert` 模式下按该值去重更新，最大长度 64
`skuInfoText`	String	✅	商品描述文本，用于生成召回向量，不能为空，最大长度 65535
`status`	String	可选	商品状态，受控值 `active` / `inactive`，缺省为 `inactive`；仅 `active` 进入最终推荐，最大长度 32
`skuId`	String	✅	SKU 标识，最大长度 64
`productName`	String	✅	商品名称，最大长度 512
`link`	String	✅	商品详情链接，最大长度 2048
`imgLink`	String	✅	商品图片链接，最大长度 2048
其他自定义字段	Any	可选	无需声明 schema，作为动态字段随 `data` 一并写入

6.4 请求示例

curl --location 'https://openapi.wisediag.com/api/recommend/database' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-***************' \
--data '{
  "agentId": "demo",
  "data": [
    {
      "primaryId": "sku_001",
      "skuId": "sku_001",
      "status": "active",
      "productName": "褪黑素片",
      "skuInfoText": "适合睡前使用，帮助改善睡眠节律",
      "link": "https://example.com/p/sku_001",
      "imgLink": "https://example.com/p/sku_001.jpg",
      "brand": "示例品牌",
      "categoryLevel1": "保健品"
    }
  ]
}'

6.5 响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "agentId": "demo",
    "requestId": "db_001",
    "summary": {
      "agentId": "demo",
      "dbName": "recommend_items_toB",
      "collectionName": "recommend_items_demo",
      "createdDatabase": false,
      "createdCollection": true,
      "loadedCollection": true,
      "writeMode": "upsert",
      "writeCount": 1,
      "vectorFieldName": "Complex_Text_Vector",
      "embeddingSourceField": "skuInfoText",
      "vectorDim": 1024,
      "metricType": "COSINE"
    }
  }
}

6.6 注意事项

skuInfoText 不能为空，否则无法生成召回向量
status 建议使用受控值，当前推荐链路仅保留 active
自定义字段无需单独声明 schema，直接随 data 写入即可

6.7 频率与并发限制

接口本身不限制调用频率，但写入时会对每条 data 的 skuInfoText 生成向量，向量服务的并发上限为 10（服务级共享信号量），与商品推荐接口共用。当并发请求超过该上限时，多余请求会排队等待，而非被拒绝。
建议单次请求采用批量写入（一个请求携带多条 data），并将并发写入控制在 10 以内，以获得稳定的吞吐与时延。

7. 请求头

Content-Type: application/json

8. Messages 格式

messages 为当前对话上下文，系统会读取：

最后一条 user 消息作为 currentQuery
最后一条 assistant 消息作为 currentAnswer

[
  {"role": "user", "content": "用户问题"},
  {"role": "assistant", "content": "助手回答"},
  {"role": "user", "content": "当前推荐请求"}
]

role	说明
`user`	用户消息
`assistant`	助手消息

9. 注意事项

collection 名固定为 recommend_items_{agentId}
商品向量仅由 skuInfoText 构建
当前仅保留 status=active 的商品进入最终推荐
系统会基于原始 query 与意图字段进行多路召回，再统一重排
正式环境中使用的 agentId，请联系技术支持团队进行确认

10. 技术支持

如有问题，请联系技术支持团队。

本页目录