模型 (Model)

提交訓練工作 (/submit-training-job)

視資料集的大小和模型的複雜度，訓練模型一般需要10~300分鐘，故訓練模型API會取得一個 job_id 提供進度查詢。模型訓練完成後也會出現在模型列表中。

使用範例

呼叫API

curl

curl --request POST 'https://api.raas.kklab.com/submit-training-job' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "$PROJECT_ID",
    "algorithm_id": "$ALGORITHM_ID",
    "name": "my model"
}'

python

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/submit-training-job"])

url = "https://api.raas.kklab.com/submit-training-job"

data={
    "project_id": "$PROJECT_ID",
    "algorithm_id": "$ALGORITHM_ID",
    "name": "my model"
}

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

pprint(response.json())

回傳值如下：

{
    "job_id": "$TRAINING_JOB_ID"
}

欄位說明

• name: 模型名稱，僅供開發者辨識使用，無其他用途。訓練完成的模型也會有這個名稱。
• job_id: 可使用這個工作id查詢工作進度。

查詢訓練工作進度 (/get-job)

使用範例

呼叫API:

curl

curl --request GET 'https://api.raas.kklab.com/get-job?project_id=$PROJECT_ID&job_id=$TRAINING_JOB_ID' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'

python

import requests
from pprint import pprint

headers = create_headers(scopes=["/get-job"])

url = "https://api.raas.kklab.com/get-job"

params = {
    "project_id": "$PROJECT_ID",
    "job_id": "$TRAINING_JOB_ID"
}

response = requests.request("GET", url, headers=headers, params=params)

pprint(response.json())

回傳值如下：

{
    "project_id": "$PROJECT_ID",
    "job_id": "$TRAINING_JOB_ID",
    "job_type": "TRAINING",
    "created_ts": 1624287847047,
    "name": "my model",
    "job_data": {
        "algorithm_type": "G1",
        "algorithm_parameters": {}
    },
    "job_result": {
        "model_id": "$MODEL_ID"
    },
    "job_status": "SUCCEED",
    "retry_count": 0
}

欄位說明

• job_data: 工作資料，模型類型與相關演算法參數。
• job_result: 工作結果，訓練完成的模型id。
• job_status: 工作目前的狀態，SUCCEED 代表工作已成功完成。
• retry_count: 如有非預期的錯誤，工作會自動進行重試，最多重複三次。失敗的工作不會消耗開發者帳號的訓練時數。

修改模型資訊 (/update-model)

使用範例

呼叫API:

curl

curl --request PUT 'https://api.raas.kklab.com/update-model' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "name": "new model name"
}'

python

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/update-model"])

url = "https://api.raas.kklab.com/update-model"

data={
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "name": "new model name"
}

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

pprint(response.json())

回傳值:

{
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "name": "new model name",
    "algorithm_type": "G1",
    "algorithm_parameters": {},
    "created_ts": 1624288594215
}

可修改欄位

• name

取得單一模型資料 (/get-model)

使用範例

呼叫API：

curl

curl --request GET 'https://api.raas.kklab.com/get-model?project_id=$PROJECT_ID&model_id=$MODEL_ID' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'

python

import requests
from pprint import pprint

headers = create_headers(scopes=["/get-model"])

url = "https://api.raas.kklab.com/get-model"

params = {
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID"
}

response = requests.request("POST", url, headers=headers, params=params)

pprint(response.json())

回傳值：

{
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "name": "my model",
    "algorithm_type": "G1",
    "algorithm_parameters": {},
    "created_ts": 1624288594215
}

取得模型列表 (/list-models)

使用範例

呼叫API：

curl

curl --request GET 'https://api.raas.kklab.com/list-models?project_id=$PROJECT_ID' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'

python

import requests
from pprint import pprint

headers = create_headers(scopes=["/list-models"])

url = "https://api.raas.kklab.com/list-models"

params = {
    "project_id": "$PROJECT_ID"
}

response = requests.request("GET", url, headers=headers, params=params)

pprint(response.json())

回傳值：

{
    "models": [
        {
            "project_id": "$PROJECT_ID",
            "model_id": "$MODEL_ID",
            "name": "my model",
            "algorithm_type": "G1",
            "algorithm_parameters": {},
            "created_ts": 1624288594215
        }
    ]
}

刪除模型 (/delete-model)

使用範例

呼叫API：

curl

curl --request DELETE 'https://api.raas.kklab.com/delete-model' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID"
}'

python

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/delete-model"])

url = "https://api.raas.kklab.com/delete-model"

data={
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID"
}

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

pprint(response.json())

回傳值：

{
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "name": "my model",
    "algorithm_type": "G1",
    "algorithm_parameters": {},
    "created_ts": 1624288594215
}

API回傳該模型被刪除前的最後設定。

限制與注意事項

• 僅能刪除沒有被部署的模型，如果欲刪除已部署的模型，需要先下架模型。

提交模型部署工作 (/submit-deployment-job)

視資料集的大小和模型的複雜度，部署模型一般需要10~60分鐘，故部署模型API會取得一個 job_id 提供進度查詢。在部署模型到專案時，可選擇兩個模式：

• 僅有 generator_model
• 同時有 generator_model 與 ranker_model

故 ranker_model_id 欄位可以不給。

使用範例

呼叫API:

curl

curl --request POST 'https://api.raas.kklab.com/submit-deployment-job' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "$PROJECT_ID",
    "generator_model_id": "$GENERATOR_MODEL_ID",
    "ranker_model_id": "$RANKER_MODEL_ID",
    "qps": 1,
    "name": "my deployment job"
}'

python

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/submit-deployment-job"])

url = "https://api.raas.kklab.com/submit-deployment-job"

data={
    "project_id": "$PROJECT_ID",
    "generator_model_id": "$GENERATOR_MODEL_ID",
    "ranker_model_id": "$RANKER_MODEL_ID",
    "qps": 1,
    "name": "my deployment job"
}

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

pprint(response.json())

回傳值如下：

{
    "job_id": "$DEPLOYMENT_JOB_ID"
}

欄位說明

• name: 部署工作名稱，僅供開發者在工作列表上辨識之用。
• generator_model_id: 負責產生推薦結果的模型id。
• ranker_model_id: 負責對 generator_model 產生的結果再排序的模型id。非必填。
• qps: 部署完後的推薦API能使用之QPS (Queries Per Second)，預設為1。
• job_id: 可使用這個工作id查詢工作進度。

取得部署工作進度 (/get-job)

使用範例

呼叫API:

curl

curl --request GET 'https://api.raas.kklab.com/get-job?project_id=$PROJECT_ID&job_id=$DEPLOYMENT_JOB_ID' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'

python

import requests
from pprint import pprint

headers = create_headers(scopes=["/get-job"])

url = "https://api.raas.kklab.com/get-job?project_id=$PROJECT_ID&job_id=$DEPLOYMENT_JOB_ID'"

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

pprint(response.json())

回傳值如下：

{
    "project_id": "$PROJECT_ID",
    "job_id": "$DEPLOYMENT_JOB_ID",
    "job_type": "DEPLOYMENT",
    "created_ts": 1624341750746,
    "name": "my deployment job",
    "job_data": {
        "generator_model_id": "$GENERATOR_MODEL_ID",
        "ranker_model_id": "$RANKER_MODEL_ID"
    },
    "job_result": {
        "serving_uri": "$SERVING_URI"
    },
    "job_status": "SUCCEED",
    "retry_count": 0
}

欄位說明

• job_data: 工作資料，被部署的模型id。
• job_result: 工作結果，該專案的推薦服務網址。
• job_status: 工作目前的狀態，SUCCEED 代表工作已成功完成。
• retry_count: 如有非預期的錯誤，工作會自動進行重試，最多重複三次。失敗的工作不會消耗開發者帳號的訓練時數。

下架模型 (/shutdown-deployment)

如欲部署新的模型，並不需要下架模型，僅需呼叫部署模型的API部署新的模型即可。模型一旦下架，該專案的推薦服務API將不再提供服務直到有模型被部署為止。

使用範例

呼叫API：

curl

curl --request DELETE 'https://api.raas.kklab.com/shutdown-deployment' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "$PROJECT_ID"
}'

python

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/shutdown-deployment"])

url = "https://api.raas.kklab.com/shutdown-deployment"

data={
    "project_id": "$PROJECT_ID"
}

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

pprint(response.json())

回傳值：

{
    "project_id": "$PROJECT_ID",
}

提交模型查詢工作 (/submit-querying-job)

視查詢的複雜度，一般需要10~60分鐘，故模型查詢工作 API 會取得一個 job_id 提供進度查詢。模型查詢可選擇兩個類型:

• user_list : 產生符合查詢條件的使用者 ID 清單。
• user_distribution : 對單一商品屬性的值，產生使用者用量分佈圖。橫軸為用量，縱軸為人數。

使用範例

呼叫API (user_list):

curl

curl --request POST 'https://api.raas.kklab.com/submit-querying-job' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "my querying user list job",
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "query_type": "user_list",
    "queries": [
        {
            "conditions": [
                {
                    "attribute": "$ATTRIBUTE1",
                    "value": $VALUE1,
                    "lower_bound": $LOWER_BOUND1,
                    "upper_bound": $UPPER_BOUND1
                },
                {
                    "attribute": "$ATTRIBUTE2",
                    "value": $VALUE2,
                    "lower_bound": $LOWER_BOUND2,
                    "upper_bound": $UPPER_BOUND2
                }
            ]
        }
    ]
}'

python

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/submit-querying-job"])

url = "https://api.raas.kklab.com/submit-querying-job"

data = {
    "name": "my querying user list job",
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "query_type": "user_list",
    "queries": [
        {
            "conditions": [
                {
                    "attribute": "$ATTRIBUTE1",
                    "value": $VALUE1,
                    "lower_bound": $LOWER_BOUND1,
                    "upper_bound": $UPPER_BOUND1
                },
                {
                    "attribute": "$ATTRIBUTE2",
                    "value": $VALUE2,
                    "lower_bound": $LOWER_BOUND2,
                    "upper_bound": $UPPER_BOUND2
                }
            ]
        }
    ]
}
response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值如下：

{
    "job_id": "$QUERYING_JOB_ID"
}

呼叫API (user_distribution):

curl

curl --request POST 'https://api.raas.kklab.com/submit-querying-job' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "my querying user distribution job",
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "query_type": "user_distribution",
    "queries": [
        {
            "attribute": "$ATTRIBUTE1",
            "value": $VALUE1,
            "bins": $BINS1
        },
        {
            "attribute": "$ATTRIBUTE2",
            "value": $VALUE2,
            "bins": $BINS2
        }
    ]
}'

python

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/submit-querying-job"])

url = "https://api.raas.kklab.com/submit-querying-job"

data = {
    "name": "my querying user distribution job",
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "query_type": "user_distribution",
    "queries": [
        {
            "attribute": "$ATTRIBUTE1",
            "value": $VALUE1,
            "bins": $BINS1
        },
        {
            "attribute": "$ATTRIBUTE2",
            "value": $VALUE2,
            "bins": $BINS2
        }
    ]
}
response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值如下：

{
    "job_id": "$QUERYING_JOB_ID"
}

欄位說明

• name: 查詢工作名稱，僅供開發者在工作列表上辨識之用。
• project_id: 專案 id。
• model_id: 負責產生查詢結果的模型id。
• query_type: 查詢工作的類型，包含: user_list / user_distribution。
• queries: 查詢條件。根據不同類型有對應的查詢條件。
• query type為user_list
  • conditions: 查詢條件列表，一個查詢條件，包含商品的 attribute / value / lower_bound / upper_bound
  • attribute: 商品屬性。
  • value: 商品屬性的值。
  • lower_bound: 該商品屬性數用者的使用量下限。
  • upper_bound: 該商品屬性數用者的使用量上限。
• query type為user_distribution
  • attribute: 商品屬性。
  • value: 商品屬性的值。
  • bins : 直方圖的分箱數量，預設值為 20 。
• job_id: 可使用這個工作id查詢工作進度。

取得模型查詢工作進度 (/get-job)

使用範例

呼叫API:

curl

curl --request GET 'https://api.raas.kklab.com/get-job?project_id=$PROJECT_ID&job_id=$QUERYING_JOB_ID' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'

python

import requests
from pprint import pprint

headers = create_headers(scopes=["/get-job"])

url = "https://api.raas.kklab.com/get-job?project_id=$PROJECT_ID&job_id=$QUERYING_JOB_ID'"

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

pprint(response.json())

回傳值如下：

{
    "project_id": "$PROJECT_ID",
    "job_id": "$QUERYING_JOB_ID",
    "job_type": "QUERYING",
    "created_ts": 1624341750746,
    "name": "my querying job",
    "job_data": {
        "model_id": "$MODEL_ID",
        "query_type": "user_distribution",
        "queries": [
            ...
        ]
    },
    "job_result": {
        "download_url": "$DOWNLOAD_URL",
        "expired_at_sec": 1648182987,
        "message": null
    },
    "job_status": "SUCCEED",
    "retry_count": 0
}

欄位說明

• job_data: 查詢工作的資料，包含: 模型 id / 查詢工作的類型 / 查詢條件
• job_result: 工作結果，包含: 下載 url / url 失效的 timestamp / 訊息。
• job_status: 工作目前的狀態，SUCCEED 代表工作已成功完成。
• retry_count: 如有非預期的錯誤，工作會自動進行重試，最多重複三次。失敗的工作不會消耗開發者帳號的訓練時數。

提交模型分群工作 (/submit-clustering-job)

視用戶資料 (user profile) 的多寡和分群方法，一般需要10~60分鐘，故模型分群工作 API 會取得一個 job_id 提供進度查詢。

使用範例

呼叫API:

curl

curl --request POST 'https://api.raas.kklab.com/submit-clustering-job' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "my user clustering job",
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "cluster_type": "user",
    "parameters": {
        "min_user_num": $MIN_USER_NUM
    }
}'

python

import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/submit-clustering-job"])

url = "https://api.raas.kklab.com/submit-clustering-job"

data={
    "name": "my user clustering job",
    "project_id": "$PROJECT_ID",
    "model_id": "$MODEL_ID",
    "cluster_type": "user",
    "parameters": {
        "min_user_num": $MIN_USER_NUM
    }
}

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

pprint(response.json())

回傳值如下：

{
    "job_id": "$CLUSTERING_JOB_ID"
}

欄位說明

• name: 分群工作名稱，僅供開發者在工作列表上辨識之用。
• project_id: 專案 id。
• model_id: 負責產生分群結果的模型id。
• cluster_type: 分群工作的類型，包含: user。
• parameters: 分群工作的參數。
• min_user_num: 一群最小人數限制，小於該人數的群組會被刪除。
• job_id: 可使用這個工作id查詢工作進度。

取得模型分群工作進度 (/get-job)

使用範例

呼叫API:

curl

curl --request GET 'https://api.raas.kklab.com/get-job?project_id=$PROJECT_ID&job_id=$CLUSTERING_JOB_ID' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'

python

import requests
from pprint import pprint

headers = create_headers(scopes=["/get-job"])

url = "https://api.raas.kklab.com/get-job?project_id=$PROJECT_ID&job_id=$CLUSTERING_JOB_ID'"

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

pprint(response.json())

回傳值如下：

{
    "project_id": "$PROJECT_ID",
    "job_id": "$CLUSTERING_JOB_ID",
    "job_type": "CLUSTERING",
    "created_ts": 1624341750746,
    "name": "my clustering job",
    "job_data": {
        "model_id": "$MODEL_ID",
        "cluster_type": "user",
        "parameters": {
            "min_user_num": $MIN_USER_NUM
        }
    },
    "job_result": {
        "download_url": "$DOWNLOAD_URL",
        "expired_at_sec": 1648182987,
        "message": null
    },
    "job_status": "SUCCEED",
    "retry_count": 0
}

欄位說明

• job_data: 查詢工作的資料，包含: 模型 id / 分群工作的類型 / 分群參數。
• job_result: 工作結果，包含: 下載 url / url 失效的 timestamp / 訊息。
• job_status: 工作目前的狀態，SUCCEED 代表工作已成功完成。
• retry_count: 如有非預期的錯誤，工作會自動進行重試，最多重複三次。失敗的工作不會消耗開發者帳號的訓練時數。