商品推荐

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`	推荐状态，如 `recommend` / `nonRecommend` / `failRecommend`
`finalRecommendations`	最终推荐商品列表，返回完整商品对象
`intentRecognizeResult`	结构化意图识别结果

响应示例：

{
  "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. database_workflow 调用指南

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	可选	待写入商品数据列表

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 写入即可

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 与意图字段进行多路召回，再统一重排

10. 技术支持

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

本页目录