使用训练和评估模型 Sensei Machine Learning API

本教程将演示如何使用API调用创建、训练和评估模型。请参阅本文档以查看API文档的详细列表。

先决条件

请遵循使用API导入打包的处方创建引擎时，需要使用API来训练和评估模型。

请遵循 Experience PlatformAPI身份验证教程以开始进行API调用。

在本教程中，您现在应具有以下值：

{ACCESS_TOKEN}：在身份验证后提供的特定持有者令牌值。
{ORG_ID}：在独特的Adobe Experience Platform集成中找到您的组织凭据。
{API_KEY}：在独特的Adobe Experience Platform集成中找到的特定API密钥值。
链接到智能服务的Docker图像

API工作流

我们将使用API来创建用于训练的试验运行。在本教程中，我们将重点介绍“引擎”、“实例”和“试验”端点。下表概述了三者之间的关系，还介绍了运行和模型的想法。

注意

术语“引擎”、“MLInstance”、“MLService”、“Experiment”和“Model”在UI中称为不同的术语。如果您来自UI，下表将映射这些差异。

UI术语	API术语
方法	引擎
模型	MLInstance
训练运行	试验
服务	MLService

创建MLInstance

可以使用以下请求来创建MLInstance。您将使用 {ENGINE_ID} 从创建引擎时返回的使用API导入打包的处方教程。

请求

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: {ORG_ID}' \
  -d `{JSON_PAYLOAD}`

{ACCESS_TOKEN}：在身份验证后提供的特定持有者令牌值。
{ORG_ID}：在独特的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: {ORG_ID}' \
  -H 'x-api-key: {API_KEY' \
  -d `{JSON PAYLOAD}`

{ORG_ID}：在独特的Adobe Experience Platform集成中找到您的组织凭据。
{ACCESS_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 部分。 In 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: {ORG_ID}' \
  -H 'x-api-key: {API_KEY}' \
  -d '{JSON_PAYLOAD}`

{ORG_ID}：在独特的Adobe Experience Platform集成中找到您的组织凭据。
{ACCESS_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: {ORG_ID}' \
  -H 'x-api-key: {API_KEY}' \
  -d '{JSON_PAYLOAD}'

{EXPERIMENT_ID}：与要定位的试验相对应的ID。这可以在创建试验时的响应中找到。
{ORG_ID}：在独特的Adobe Experience Platform集成中找到您的组织凭据。
{ACCESS_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: {ORG_ID}' \
  -H 'x-api-key: {API_KEY}'

{EXPERIMENT_ID}：表示试验的ID。
{EXPERIMENT_RUN_ID}：表示试验运行的ID。
{ACCESS_TOKEN}：在身份验证后提供的特定持有者令牌值。
{ORG_ID}：在独特的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: {ORG_ID}'

{EXPERIMENT_RUN_ID}：与要定位的试验运行相对应的ID。这可以在创建试验运行时的响应中找到。
{ACCESS_TOKEN}：在身份验证后提供的特定持有者令牌值。
{ORG_ID}：在独特的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}：对应于模型的ID。
{EXPERIMENT_ID}：与试验运行所依据的试验相对应的ID。
{EXPERIMENT_RUN_ID}：与试验运行对应的ID。

停止并删除计划的试验

如果您想在计划试验之前停止执行该试验 endTime，这可以通过向查询DELETE请求来完成 {EXPERIMENT_ID}

请求

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

{EXPERIMENT_ID}：对应于试验的ID。
{ACCESS_TOKEN}：在身份验证后提供的特定持有者令牌值。
{ORG_ID}：在独特的Adobe Experience Platform集成中找到您的组织凭据。

注意

API调用将禁用创建新的试验运行。但是，它不会停止执行已运行的试验运行。

以下是响应，通知已成功删除试验。

响应

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

后续步骤

本教程介绍了如何使用API创建引擎、实验、计划的实验运行和经过训练的模型。在下一个练习，您将通过使用表现最佳的经过训练的模型来评分新数据集来进行预测。

Business.Adobe.com 资源

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