Skip to content

取得推薦結果 (Recommendation)

對使用者取得商品推薦 (/recommend-items-to-user)

使用範例

呼叫 API:

curl -request POST 'https://api.raas.kklab.com/recommend-items-to-user' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "1",
    "attributes": [
        "title",
        "genres"
    ],
    "filter_query": null,
    "limit": 2
}'

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/recommend-items-to-user"])

url = "https://api.raas.kklab.com/recommend-items-to-user"

data={
    "user_id": "1",
    "attributes": [
        "title",
        "genres"
    ],
    "filter_query": None,
    "limit": 2
}

response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值：

{
  "user_id": "1",
  "limit": 2,
  "attributes": ["title", "genres"],
  "filter_query": null,
  "results": [
    {
      "item_id": "1",
      "title": "Toy Story (1995)",
      "genres": ["Adventure", "Animation", "Children", "Comedy", "Fantasy"]
    },
    {
      "item_id": "2",
      "title": "Jumanji (1995)",
      "genres": ["Adventure", "Children", "Fantasy"]
    }
  ]
}

欄位說明

  • user_id: 要被推薦的使用者 id。
  • attributes: 對應專案的商品資料集中的商品 attributes 欄位，在回傳推薦結果時一起回傳。
  • limit: 回傳幾筆推薦商品，最多 200 筆。
  • filter_query: 字串，推薦結果過濾規則，可參考下面的過濾規則的部分。
  • generator_model_args: 候選產生模型推薦參數。為非必填欄位，每個演算法類型，有其可支援的推薦參數，請參考演算法的說明。
  • ranker_model_args: 排序模型推薦參數。非必填欄位，每個演算法類型，有其可支援的推薦參數，請參考演算法的說明。
  • results: 推薦結果，每一筆資料為一個推薦商品和其 attributes。

支援專案類型

  • 對使用者推薦商品 (RECOMMEND_ITEMS_TO_USER)

批次對使用者取得商品推薦 (/batch-recommend-items-to-user)

批次推薦不會即時得到結果，而是當模型算出推薦結果後，使用 HTTP POST Request 呼叫 callback_url 將結果回拋。

使用範例

呼叫 API:

curl --request POST 'https://api.raas.kklab.com/batch-recommend-items-to-user' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "requests": [
        {
            "user_id": "1",
            "attributes": [
                "title",
                "genres"
            ],
            "limit": 1
        }
    ],
    "callback_url": "https://www.example.com/kkraas-callback-items-to-user",
    "payload": {
        "data_key": "data_value"
    }
}'

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/batch-recommend-items-to-user"])

url = "https://api.raas.kklab.com/batch-recommend-items-to-user"

data={
    "requests": [
        {
            "user_id": "1",
            "attributes": [
                "title",
                "genres"
            ],
            "limit": 1
        }
    ],
    "callback_url": "https://www.example.com/kkraas-callback-items-to-user",
    "payload": {
        "data_key": "data_value"
    }
}

response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值：

{
  "batch_request_id": "$BATCH_REQUEST_ID"
}

欄位說明

  • requests: 可將多個 /recommend-items-to-user 的請求放入此陣列中。
  • callback_url: 推薦結果回拋網址。
  • payload: 會隨結果一起回拋，不得大於 1 kb。
  • batch_request_id: 此次請求的 id，會與推薦結果一起回拋。

接收結果 (callback)

模型每算出一部分推薦後，會將推薦結果使用 HTTP POST Request 呼叫 callback_url 將結果回拋。Body 的範例如下：

{
  "batch_request_id": "$BATCH_REQUEST_ID",
  "payload": {
    "data_key": "data_value"
  },
  "responses": [
    {
      "user_id": "1",
      "response": {
        "user_id": "1",
        "limit": 1,
        "attributes": ["title", "genres"],
        "filter_query": null,
        "results": [
          {
            "item_id": "1",
            "title": "Toy Story (1995)",
            "genres": [
              "Adventure",
              "Animation",
              "Children",
              "Comedy",
              "Fantasy"
            ]
          }
        ]
      }
    }
  ]
}

接收結果欄位說明 (callback)

  • responses: 每一筆 request 的對應回傳值。
  • responses 列表內對每個 item_id 的 response: 若該 API request 不合法則為 null。

單個 batch_request_id 有可能分多次將推薦結果回拋。

支援專案類型

  • 對使用者推薦商品 (RECOMMEND_ITEMS_TO_USER)

對使用者取得商品排序 (/rank-items-to-user)

使用範例

呼叫 API:

curl --request POST 'https://api.raas.kklab.com/rank-items-to-user' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "1",
    "rank_item_ids": [
        "1",
        "2",
        "3"
    ]
}'

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/rank-items-to-user"])

url = "https://api.raas.kklab.com/rank-items-to-user"

data={
    "user_id": "1",
    "rank_item_ids": [
        "1",
        "2",
        "3"
    ]
}

response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值：

{
  "user_id": "1",
  "results": [
    {
      "item_id": "1"
    },
    {
      "item_id": "2"
    },
    {
      "item_id": "3"
    }
  ]
}

支援專案類型

  • 對使用者推薦商品 (RECOMMEND_ITEMS_TO_USER)

對商品取得商品推薦 (/recommend-items-to-item)

使用範例

呼叫 API:

curl -request POST 'https://api.raas.kklab.com/recommend-items-to-item' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "item_id": "1",
    "attributes": [
        "title",
        "genres"
    ],
    "filter_query": null,
    "limit": 1
}'

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/recommend-items-to-item"])

url = "https://api.raas.kklab.com/recommend-items-to-item"

data={
    "item_id": "1",
    "attributes": [
        "title",
        "genres"
    ],
    "filter_query": None,
    "limit": 1
}

response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值：

{
  "item_id": "1",
  "limit": 1,
  "attributes": ["title", "genres"],
  "filter_query": null,
  "results": [
    {
      "item_id": "2",
      "title": "Jumanji (1995)",
      "genres": ["Adventure", "Children", "Fantasy"]
    }
  ]
}

欄位說明

  • item_id: 要被推薦的商品 id。
  • attributes: 對應專案的商品資料集中的商品 attributes 欄位，在回傳推薦結果時一起回傳。
  • limit: 回傳幾筆推薦商品，最多 200 筆。
  • filter_query: 字串，推薦結果過濾規則，可參考下面的過濾規則的部分。
  • generator_model_args: 候選產生模型推薦參數。為非必填欄位，每個演算法類型，有其可支援的推薦參數，請參考演算法的說明。
  • ranker_model_args: 排序模型推薦參數。非必填欄位，每個演算法類型，有其可支援的推薦參數，請參考演算法的說明。
  • results: 推薦結果，每一筆資料為一個推薦商品和其 attributes。

支援專案類型

  • 對商品推薦商品 (RECOMMEND_ITEMS_TO_ITEM)

批次對商品取得商品推薦 (/batch-recommend-items-to-item)

批次推薦不會即時得到結果，而是當模型算出推薦結果後，使用 HTTP POST Request 呼叫 callback_url 將結果回拋。

使用範例

呼叫 API:

curl --request POST 'https://api.raas.kklab.com/batch-recommend-items-to-item' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "requests": [
        {
            "item_id": "2",
            "attributes": [
                "title",
                "genres"
            ],
            "limit": 1
        }
    ],
    "callback_url": "https://www.example.com/kkraas-callback-items-to-item",
    "payload": {
        "data_key": "data_value"
    }
}'

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/batch-recommend-items-to-item"])

url = "https://api.raas.kklab.com/batch-recommend-items-to-item"

data={
    "requests": [
        {
            "item_id": "2",
            "attributes": [
                "title",
                "genres"
            ],
            "limit": 1
        }
    ],
    "callback_url": "https://www.example.com/kkraas-callback-items-to-item",
    "payload": {
        "data_key": "data_value"
    }
}

response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值：

{
  "batch_request_id": "$BATCH_REQUEST_ID"
}

欄位說明

  • requests: 可將多個 /recommend-items-to-item 的請求放入此陣列中。
  • callback_url: 推薦結果回拋網址。
  • payload: 會隨結果一起回拋，不得大於 1 kb。
  • batch_request_id: 此次請求的 id，會與推薦結果一起回拋。

接收結果

模型每算出一部分推薦後，會將推薦結果使用 HTTP POST Request 呼叫 callback_url 將結果回拋。Body 的範例如下：

{
  "batch_request_id": "$BATCH_REQUEST_ID",
  "payload": {
    "data_key": "data_value"
  },
  "responses": [
    {
      "item_id": "2",
      "response": {
        "item_id": "2",
        "limit": 1,
        "attributes": ["title", "genres"],
        "filter_query": null,
        "results": [
          {
            "item_id": "1",
            "title": "Toy Story (1995)",
            "genres": [
              "Adventure",
              "Animation",
              "Children",
              "Comedy",
              "Fantasy"
            ]
          }
        ]
      }
    }
  ]
}

單個 batch_request_id 有可能分多次將推薦結果回拋。

接收結果欄位說明 (callback)

  • responses: 每一筆 request 的對應回傳值。
  • responses 列表內對每個 user_id 的 response: 若該 API request 不合法則為 null。

支援專案類型

  • 對商品推薦商品 (RECOMMEND_ITEMS_TO_ITEM)

對商品取得商品排序 (/rank-items-to-item)

使用範例

呼叫 API:

curl --request POST 'https://api.raas.kklab.com/rank-items-to-item' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "item_id": "1",
    "rank_item_ids": [
        "2",
        "3",
        "4"
    ]
}'

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/rank-items-to-item"])

url = "https://api.raas.kklab.com/rank-items-to-item"

data={
    "item_id": "1",
    "rank_item_ids": [
        "2",
        "3",
        "4"
    ]
}

response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值：

{
  "item_id": "1",
  "results": [
    {
      "item_id": "2"
    },
    {
      "item_id": "3"
    },
    {
      "item_id": "4"
    }
  ]
}

支援專案類型

  • 對商品推薦商品 (RECOMMEND_ITEMS_TO_ITEM)

關於過濾規則

過濾規則可透過 filter_query 參數傳給 API 推薦或 Batch 推薦來過濾推薦結果。

過濾規則語法說明

可參考 SQL 語言中的 WHERE 子句，僅支援 AND、OR、括號 的邏輯運算。對字串資料僅支援 = 運算，對數字資料則支援 >, >=, =, <, <=運算。

例如：

  • genres = 'Adventure' OR (genres = 'Children' AND genres = 'Animation')
  • price <= 1000 AND category = 'Monitor'