issaxyz / recommendation

推荐（&搜索）引擎接口对接文档

本推荐引擎通过对用户行为和物品标签的统计、建模，实现对用户的精准个性化推荐。本文档将推荐系统看作一个整体，从输出和输入两个方面分别讲解所有接口的使用方式。

一、系统输入（数据收集）

[http://localhost:7070/events.json?accessKey=hTt_--U-8V5lWcFVYaG14NBRqYbWC9HTUxUcAeYfo3IThpuYbGGEr2CNTS0fV7G1]

1.上传物品属性 [POST]

传入物品唯一识别码xxx1，和所属标签（categories: "xxx2", "xxx3", "xxx4"），同时带上可用时间、失效时间和当前时间。（available和date可设置为当前时间，失效时间根据视频源过期时间经验进行设置） 如果服务器正常，将返回201。

• Request (application/json)

    {
        "event" : "$set",
        "entityType" : "item",
        "entityId" : "xxx1",
        "properties" : {
            "categories" : ["xxx2", "xxx3", "xxx4"],
            "available" : "2017-05-13T21:39:45.618+08:00",
            "date" : "2017-05-13T21:39:45.618+08:00",
            "expires": "2017-12-13T21:39:45.618+08:00"
        }
    }
  

• Response 201 (application/json)

  • Body

      {"eventId":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
    

2.上传用户行为 [POST]

传入用户唯一识别码xxx1，和物品唯一识别码xxx2，同时带上当前时间。 如果服务器正常，将返回201。

• Request (application/json)

    {
        "event" : "viewed",
        "entityType" : "user",
        "entityId" : "xxx1",
        "targetEntityType" : "item",
        "targetEntityId" : "xxx2",
        "properties" : {}
        "date": "2017-05-13T21:39:45.618+08:00"
    }
  

• Response 201 (application/json)

  • Body

      {"eventId":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
    

二、系统输出（推荐内容）

[http://113.207.44.2:8000/queries.json]

1.获取个性化推荐 [POST]

传入用户唯一识别码xxx1，如果需要某标签下的推荐。 如果服务器正常，将返回200和推荐结果（物品唯一识别码和评分）。

• Request (application/json)

    {
        "user": "xxx1"
    }
  

• Response 200 (application/json)

  • Body

      {
          "itemScores": [
              {
                  "item": "xxx2",
                  "score": 0.24548225104808807
              },
              {
                  "item": "xxx3",
                  "score": 0.24548225104808807
              },
              {
                  "item": "xxx4",
                  "score": 0.24548225104808807
              },
              {
                  "item": "xxx5",
                  "score": 0
              }
          ]
      }
    

2.获取相似内容 [POST]

传入物品唯一识别码xxx1，如果需要某标签下的推荐。 如果服务器正常，将返回200和推荐结果（物品唯一识别码和评分）。

• Request (application/json)

    {
        "item": "xxx1"
    }
  

• Response 200 (application/json)

  • Body

      {
          "itemScores": [
              {
                  "item": "xxx2",
                  "score": 0.24548225104808807
              },
              {
                  "item": "xxx3",
                  "score": 0.24548225104808807
              },
              {
                  "item": "xxx4",
                  "score": 0.24548225104808807
              },
              {
                  "item": "xxx5",
                  "score": 0
              }
          ]
      }
    

3.取多个分类下最热门的内容（过滤，类似MUST） [POST]

传入标签数组（"xxx1", "xxx2"），可以结合bias使用（参考BIAS说明）。 如果服务器正常，将返回200和推荐结果（物品唯一识别码和评分）。

• Request (application/json)

    {
        "fields": [{
            "name": "categories",
            "values": ["xxx1", "xxx2"],
            "bias": -1
        }]
    }
  

• Response 200 (application/json)

  • Body

      {
          "itemScores": [
              {
                  "item": "xxx3",
                  "score": 0
              },
              {
                  "item": "xxx4",
                  "score": 0
              }
          ]
      }
    

4.获取多个分类下最热门的内容（提升，类似SHOULD，并提升分数） [POST]

传入标签数组（"xxx1", "xxx2", "xxx3"），可以结合bias使用（参考BIAS说明）。 如果服务器正常，将返回200和推荐结果（物品唯一识别码和评分）。

• Request (application/json)

    {
        "fields": [{
            "name": "categories",
            "values": ["xxx1", "xxx2", "xxx3"],
            "bias": 1.05
        }]
    }
  

• Response 200 (application/json)

  • Body

      {
          "itemScores": [
              {
                  "item": "xxx4",
                  "score": 0.204568549990654
              },
              {
                  "item": "xxx5",
                  "score": 0.204568549990654
              },
              {
                  "item": "xxx6",
                  "score": 0
              },
              {
                  "item": "xxx7",
                  "score": 0
              }
          ]
      }
    

三、其他说明

bias偏差值

• 当bias=-1时，只输出指定categories的热门推荐。
• 当bias>0时，将对指定categories的评分做*bias运算，排序输出结果（指定的categories做运算后，放到全局categories中按得分排序）。
• 例如：bias>1，表示提权；0<bias<1时，表示降权。