使用Sensei Machine Learning API來訓練和評估模型

本教學課程將示範如何使用API呼叫建立、訓練和評估模型。請參閱本檔案以取得API檔案的詳細清單。

必要條件

請遵循使用API匯入封裝配方以建立引擎，此引擎是使用API來訓練和評估模型所需的。

請依照Experience Platform API驗證教學課程開始進行API呼叫。

在教學課程中，您現在應該有下列值：

{ACCESS_TOKEN}:驗證後提供的您特定的載體Token值。
{IMS_ORG}:您的IMS組織認證可在您獨特的Adobe Experience Platform整合中找到。
{API_KEY}:您獨特的Adobe Experience Platform整合中提供您的特定API金鑰價值。
連結至智慧型服務的Docker影像

API工作流程

我們將使用API來建立實驗執行以進行訓練。在本教學課程中，我們將重點討論引擎、MLInstances和實驗端點。下圖概述這三者之間的關係，並介紹「執行」(Run)和「模型」(Model)的概念。

注意

「引擎」、「MLInstance」、「MLService」、「實驗」和「模型」在UI中稱為不同的詞語。如果您是來自UI，下表將對應差異。

UI詞語	API期限
配方	引擎
模型	MLInstance
訓練課程	實驗
服務	MLService

建立MLInstance

您可使用下列請求來建立MLInstance。您將使用從使用API教學課程匯入封裝配方建立引擎時傳回的{ENGINE_ID}。

請求

curl -X POST \
  https://platform.adobe.io/data/sensei/mlInstances \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/vnd.adobe.platform.sensei+json;profile=mlInstance.v1.json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -d `{JSON_PAYLOAD}`

{ACCESS_TOKEN}:驗證後提供的您特定的載體Token值。
{IMS_ORG}:您的IMS組織認證可在您獨特的Adobe Experience Platform整合中找到。
{API_KEY}:您獨特的Adobe Experience Platform整合中提供您的特定API金鑰價值。
{JSON_PAYLOAD}:MLInstance的配置。我們在教學課程中使用的範例如下所示：

{
    "name": "Retail - Instance",
    "description": "Instance for ML Instance",
    "engineId": "{ENGINE_ID}",
    "createdBy": {
        "displayName": "John Doe",
        "userId": "johnd"
    },
    "tags": {
        "purpose": "tutorial"
    },
    "tasks": [
        {
            "name": "train",
            "parameters": [
                {
                    "key": "numFeatures",
                    "value": "10"
                },
                {
                    "key": "maxIter",
                    "value": "2"
                },
                {
                    "key": "regParam",
                    "value": "0.15"
                },
                {
                    "key": "trainingDataLocation",
                    "value": "sample_training_data.csv"
                }
            ]
        },
        {
            "name": "score",
            "parameters": [
                {
                    "key": "scoringDataLocation",
                    "value": "sample_scoring_data.csv"
                },
                {
                    "key": "scoringResultsLocation",
                    "value": "scoring_results.net"
                }
            ]
        }
    ]
}

注意

在{JSON_PAYLOAD}中，我們定義tasks陣列中用於訓練和計分的參數。 {ENGINE_ID}是您要使用之引擎的ID，而tag欄位是用來識別例項的選用參數。

響應將包含{INSTANCE_ID} ，該代表所建立的MLInstance。可以建立具有不同配置的多模型MLI實例。

回應

{
    "id": "{INSTANCE_ID}",
    "name": "Retail - Instance",
    "description": "Instance for ML Instance",
    "engineId": "{ENGINE_ID}",
    "created": "2018-21-21T11:11:11.111Z",
    "createdBy": {
        "displayName": "John Doe",
        "userId": "johnd"
    },
    "updated": "2018-21-01T11:11:11.111Z",
    "deleted": false,
    "tags": {
        "purpose": "tutorial"
    },
    "tasks": [
        {
            "name": "train",
            "parameters": [...]
        },
        {
            "name": "score",
            "parameters": [...]
        }
    ]
}

{ENGINE_ID}:此ID代表在下建立MLInstance的引擎。
{INSTANCE_ID}:代表MLInstance的ID。

建立實驗

資料科學家在訓練時使用實驗來獲得高效能模型。多項實驗包括變更資料集、功能、學習參數和硬體。以下是建立實驗的示例。

請求

curl -X POST \
  https://platform.adobe.io/data/sensei/experiments \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/vnd.adobe.platform.sensei+json;profile=experiment.v1.json' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-api-key: {API_KEY' \
  -d `{JSON PAYLOAD}`

{IMS_ORG}:您的IMS組織認證可在您獨特的Adobe Experience Platform整合中找到。
{ACCESS_TOKEN}:驗證後提供的您特定的載體Token值。
{API_KEY}:您獨特的Adobe Experience Platform整合中提供您的特定API金鑰價值。
{JSON_PAYLOAD}:實驗所建立的物件。我們在教學課程中使用的範例如下所示：

{
    "name": "Experiment for Retail ",
    "mlInstanceId": "{INSTANCE_ID}",
    "tags": {
        "test": "guide"
    }
}

{INSTANCE_ID}:代表MLInstance的ID。

「實驗」建立的回應如下所示。

回應

{
    "id": "{EXPERIMENT_ID}",
    "name": "Experiment for Retail",
    "mlInstanceId": "{INSTANCE_ID}",
    "created": "2018-01-01T11:11:11.111Z",
    "updated": "2018-01-01T11:11:11.111Z",
    "deleted": false,
    "tags": {
        "test": "guide"
    }
}

{EXPERIMENT_ID}:代表您剛建立之實驗的ID。{INSTANCE_ID}:代表MLInstance的ID。

建立計畫的訓練實驗

使用「排程實驗」，因此我們不需要透過API呼叫建立每個「實驗執行」。我們會在「實驗」建立期間提供所有必要的參數，並定期建立每個執行。

若要指出已排程實驗的建立，我們必須在請求正文中新增template區段。在template中，計畫執行的所有必要參數都包含在內，例如tasks（表示執行的動作）和schedule（表示排程執行的時間）。

請求

curl -X POST \
  https://platform.adobe.io/data/sensei/experiments \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/vnd.adobe.platform.sensei+json;profile=experiment.v1.json' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-api-key: {API_KEY}' \
  -d '{JSON_PAYLOAD}`

{IMS_ORG}:您的IMS組織認證可在您獨特的Adobe Experience Platform整合中找到。
{ACCESS_TOKEN}:驗證後提供的您特定的載體Token值。
{API_KEY}:您獨特的Adobe Experience Platform整合中提供您的特定API金鑰價值。
{JSON_PAYLOAD}:要張貼的資料集。我們在教學課程中使用的範例如下所示：

{
    "name": "Experiment for Retail",
    "mlInstanceId": "{INSTANCE_ID}",
    "template": {
        "tasks": [{
            "name": "train",
            "parameters": [
                   {
                        "value": "1000",
                        "key": "numFeatures"
                    }
            ],
            "specification": {
                "type": "SparkTaskSpec",
                "executorCores": 5,
                "numExecutors": 5
            }
        }],
        "schedule": {
            "cron": "*/20 * * * *",
            "startTime": "2018-11-11",
            "endTime": "2019-11-11"
        }
    }
}

當我們建立實驗時，主體{JSON_PAYLOAD}應包含mlInstanceId或mlInstanceQuery參數。在此範例中，排程的「實驗」會每20分鐘叫用一次執行，在cron參數中設定，從startTime開始，直到endTime。

回應

{
    "id": "{EXPERIMENT_ID}",
    "name": "Experiment for Retail",
    "mlInstanceId": "{INSTANCE_ID}",
    "created": "2018-11-11T11:11:11.111Z",
    "updated": "2018-11-11T11:11:11.111Z",
    "deleted": false,
    "workflowId": "endid123_0379bc0b_8f7e_4706_bcd9_1a2s3d4f5g_abcdf",
    "template": {
        "tasks": [
            {
                "name": "train",
                "parameters": [...],
                "specification": {
                    "type": "SparkTaskSpec",
                    "executorCores": 5,
                    "numExecutors": 5
                }
            }
        ],
        "schedule": {
            "cron": "*/20 * * * *",
            "startTime": "2018-07-04",
            "endTime": "2018-07-06"
        }
    }
}

{EXPERIMENT_ID}:代表實驗的ID。
{INSTANCE_ID}:代表MLInstance的ID。

建立訓練的實驗執行

建立實驗實體後，就可使用下列呼叫建立並執行訓練執行。您需要{EXPERIMENT_ID}，並在請求內文中指出您要觸發的mode。

請求

curl -X POST \
  https://platform.adobe.io/data/sensei/experiments/{EXPERIMENT_ID}/runs \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/vnd.adobe.platform.sensei+json;profile=experimentRun.v1.json' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-api-key: {API_KEY}' \
  -d '{JSON_PAYLOAD}'

{EXPERIMENT_ID}:與您要定位的「實驗」對應的ID。這可在建立實驗時的回應中找到。
{IMS_ORG}:您的IMS組織認證可在您獨特的Adobe Experience Platform整合中找到。
{ACCESS_TOKEN}:驗證後提供的您特定的載體Token值。
{API_KEY}:您獨特的Adobe Experience Platform整合中提供您的特定API金鑰價值。
{JSON_PAYLOAD}:若要建立訓練執行，您必須將下列項目納入內文：

{
    "mode":"Train"
}

您也可以通過包含tasks陣列來覆蓋配置參數：

{
   "mode":"Train",
   "tasks": [
        {
           "name": "train",
           "parameters": [
                {
                   "key": "numFeatures",
                   "value": "2"
                }
            ]
        }
    ]
}

您會收到下列回應，其中會告知您{EXPERIMENT_RUN_ID}和tasks下的設定。

回應

{
    "id": "{EXPERIMENT_RUN_ID}",
    "mode": "train",
    "experimentId": "{EXPERIMENT_ID}",
    "created": "2018-01-01T11:11:11.903Z",
    "updated": "2018-01-01T11:11:11.903Z",
    "deleted": false,
    "tasks": [
        {
            "name": "Train",
            "parameters": [...]
        }
    ]
}

{EXPERIMENT_RUN_ID}:代表「實驗執行」的ID。
{EXPERIMENT_ID}:代表「實驗執行」所在實驗的ID。

擷取實驗執行狀態

可以使用{EXPERIMENT_RUN_ID}查詢實驗運行的狀態。

請求

curl -X GET \
  https://platform.adobe.io/data/sensei/experiments/{EXPERIMENT_ID}/runs/{EXPERIMENT_RUN_ID}/status \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-api-key: {API_KEY}'

{EXPERIMENT_ID}:代表實驗的ID。
{EXPERIMENT_RUN_ID}:代表「實驗執行」的ID。
{ACCESS_TOKEN}:驗證後提供的您特定的載體Token值。
{IMS_ORG}:您的IMS組織認證可在您獨特的Adobe Experience Platform整合中找到。
{API_KEY}:您獨特的Adobe Experience Platform整合中提供您的特定API金鑰價值。

回應

GET呼叫將提供state參數中的狀態，如下所示：

{
    "id": "{EXPERIMENT_ID}",
    "name": "RunStatus for experimentRunId {EXPERIMENT_RUN_ID}",
    "experimentRunId": "{EXPERIMENT_RUN_ID}",
    "deleted": false,
    "status": {
        "tasks": [
            {
                "id": "{MODEL_ID}",
                "state": "DONE",
                "tasklogs": [
                    {
                        "name": "execution",
                        "url": "https://mlbaprod1sapwd7jzid.file.core.windows.net/..."
                    },
                    {
                        "name": "stderr",
                        "url": "https://mlbaprod1sapwd7jzid.file.core.windows.net/..."
                    },
                    {
                        "name": "stdout",
                        "url": "https://mlbaprod1sapwd7jzid.file.core.windows.net/..."
                    }
                ]
            }
        ]
    }
}

{EXPERIMENT_RUN_ID}:代表「實驗執行」的ID。
{EXPERIMENT_ID}:代表「實驗執行」所在實驗的ID。

除了DONE狀態外，其他狀態還包括：

PENDING
RUNNING
FAILED

若要取得詳細資訊，請在tasklogs參數下找到詳細的記錄檔。

檢索已訓練的模型

為了在培訓期間獲得上面建立的培訓模型，我們提出以下請求：

請求

curl -X GET \
  'https://platform.adobe.io/data/sensei/models/?property=experimentRunId=={EXPERIMENT_RUN_ID}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'

{EXPERIMENT_RUN_ID}:與您要定位的「實驗執行」對應的ID。這可在建立「實驗執行」時的回應中找到。
{ACCESS_TOKEN}:驗證後提供的您特定的載體Token值。
{IMS_ORG}:您的IMS組織認證可在您獨特的Adobe Experience Platform整合中找到。

響應表示已建立的受訓模型。

回應

{
    "children": [
        {
            "id": "{MODEL_ID}",
            "name": "Tutorial trained Model",
            "experimentId": "{EXPERIMENT_ID}",
            "experimentRunId": "{EXPERIMENT_RUN_ID}",
            "description": "trained model for ID",
            "modelArtifactUri": "wasb://test-models@mlpreprodstorage.blob.core.windows.net/{MODEL_ID}",
            "created": "2018-01-01T11:11:11.011Z",
            "updated": "2018-01-01T11:11:11.011Z",
            "deleted": false
        }
    ],
    "_page": {
        "property": "ExperimentRunId=={EXPERIMENT_RUN_ID},deleted!=true",
        "count": 1
    }
}

{MODEL_ID}:與「模型」(Model)對應的ID。
{EXPERIMENT_ID}:與「實驗運行」對應的ID在「實驗運行」下。
{EXPERIMENT_RUN_ID}:與「實驗執行」對應的ID。

停止和刪除排程的實驗

如果要在計畫實驗的endTime之前停止執行，則可以通過向{EXPERIMENT_ID}查詢DELETE請求來完成此操作

請求

curl -X DELETE \
  'https://platform.adobe.io/data/sensei/experiments/{EXPERIMENT_ID}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'

{EXPERIMENT_ID}:與實驗對應的ID。
{ACCESS_TOKEN}:驗證後提供的您特定的載體Token值。
{IMS_ORG}:您的IMS組織認證可在您獨特的Adobe Experience Platform整合中找到。

注意

API呼叫會停用建立新實驗執行的功能。但是，它不會停止執行已執行的Enperity Runs。

以下是回應，通知實驗已成功刪除。

回應

{
    "title": "Success",
    "status": 200,
    "detail": "Experiment successfully deleted"
}

後續步驟

本教學課程說明如何使用API來建立引擎、實驗、排程實驗執行和訓練的模型。在下一練習中，您將使用表現最佳的訓練模型對新資料集評分，以進行預測。

adobe.com 上的資源

Omnichannel Personalization Website Personalization Style System Dynamic Forms Audio Analytics Identity Management