Treinar e avaliar um modelo usando a Sensei Machine Learning API

Esta tutorial mostrará como criar, treinar e avaliar um modelo usando chamadas de API. Consulte esta documento para obter uma lista detalhada da documentação da API.

Pré-requisitos

Siga a Importar uma fórmula empacotada usando a API para criar um Mecanismo, necessário para treinar e avaliar um Modelo usando a API.

Siga o tutorial de autenticação da API de Experience Platform para começar a fazer chamadas de API.

No tutorial, agora você deve ter os seguintes valores:

Fluxo de trabalho da API

Estaremos consumindo as APIs para criar uma Execução de experimento para treinamento. Neste tutorial, estaremos focados nos endpoints de Mecanismos, Instâncias do MLI e Experimentos. O gráfico a seguir descreve a relação entre os três e também introduz a ideia de uma Execução e um Modelo.

Criar uma MLInstance

A criação de uma MLInstance pode ser feita usando a solicitação a seguir. Você usará o {ENGINE_ID} que foi retornado ao criar um Mecanismo a partir do Tutorial de importação de fórmula empacotada usando a API.

Solicitação

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}: seu valor de token portador específico fornecido após a autenticação.
{ORG_ID}: suas credenciais de organização encontradas na integração exclusiva do Adobe Experience Platform.
{API_KEY}: O valor da sua chave de API específica foi encontrado na sua integração exclusiva do Adobe Experience Platform.
{JSON_PAYLOAD}: A configuração de nossa MLInstance. O exemplo que usamos em nosso tutorial é mostrado aqui:

{
    "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"
                }
            ]
        }
    ]
}

A resposta contém o {INSTANCE_ID} que representa a MLInstance criada. Várias MLInstances de modelo com configurações diferentes podem ser criadas.

Resposta

{
    "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}: esta ID que representa o Mecanismo no qual a MLInstance é criada.
{INSTANCE_ID}: a ID que representa a MLInstance.

Criar um experimento

Um experimento é usado por um cientista de dados para chegar a um modelo de alto desempenho durante o treinamento. Vários experimentos incluem a alteração de conjuntos de dados, recursos, parâmetros de aprendizado e hardware. Veja a seguir um exemplo de como criar um experimento.

Solicitação

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}: as credenciais da sua organização foram encontradas em sua integração exclusiva com o Adobe Experience Platform.
{ACCESS_TOKEN}: Seu valor de token de portador específico fornecido após a autenticação.
{API_KEY}: seu valor de chave de API específico encontrado na integração exclusiva do Adobe Experience Platform.
{JSON_PAYLOAD}: Experimento objeto criado. O exemplo que usamos em nosso tutorial é mostrado aqui:

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

{INSTANCE_ID}: a ID que representa a MLInstance.

A resposta da criação do experimento é semelhante a esta.

Resposta

{
    "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}: a ID que representa o experimento recém-criado.
{INSTANCE_ID}: a ID que representa a MLInstance.

Criar um experimento programado para treinamento

Os Experimentos agendados são usados para que não precisemos criar cada um Experimento Corre por meio de uma chamada de API. Em vez disso, fornecemos todos os parâmetros necessários durante Experimento criação e cada execução será criada periodicamente.

Para indicar a criação de um experimento agendado, devemos adicionar uma seção template no corpo da solicitação. Em template, todos os parâmetros necessários para execuções de agendamento estão incluídos, como tasks, que indica qual ação, e schedule, que indica o tempo das execuções agendadas.

Solicitação

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}: as credenciais da sua organização foram encontradas em sua integração exclusiva com o Adobe Experience Platform.
{ACCESS_TOKEN}: seu valor de token portador específico fornecido após a autenticação.
{API_KEY}: seu valor de chave de API específico encontrado na integração exclusiva do Adobe Experience Platform.
{JSON_PAYLOAD}: conjunto de dados a ser publicado. O exemplo que usamos em nosso tutorial é mostrado aqui:

{
    "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"
        }
    }
}

Quando criamos uma Experimento, o corpo, {JSON_PAYLOAD}deve conter o parâmetro ou o mlInstanceId mlInstanceQuery parâmetro. Neste exemplo, uma Experimento programada executará uma execução a cron cada 20 minutos, definida no parâmetro, começando a startTime partir do até o endTime.

Resposta

{
    "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}: a ID que representa o Experimento.
{INSTANCE_ID}: a ID que representa a MLInstance.

Criar uma execução de experimento para treinamento

Com uma entidade de experimento criada, uma execução de treinamento pode ser criada e executada usando a chamada abaixo. Você precisará do {EXPERIMENT_ID} e indicará qual mode deseja acionar no corpo da solicitação.

Solicitação

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}: a ID correspondente ao Experimento que você deseja direcionar. Isso pode ser encontrado na resposta ao criar o experimento.
{ORG_ID}: as credenciais da sua organização foram encontradas em sua integração exclusiva com o Adobe Experience Platform.
{ACCESS_TOKEN}: Seu valor de token de portador específico fornecido após a autenticação.
{API_KEY}: O valor da sua chave de API específica foi encontrado na sua integração exclusiva do Adobe Experience Platform.
{JSON_PAYLOAD}: Para criar uma execução de treinamento, você terá que incluir o seguinte no corpo:

{
    "mode":"Train"
}

Você também pode substituir os parâmetros de configuração incluindo uma matriz tasks:

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

Você receberá a seguinte resposta, que permitirá que você saiba o {EXPERIMENT_RUN_ID} e a configuração em tasks.

Resposta

{
    "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}: a identificação que representa a execução do experimento.
{EXPERIMENT_ID}: a identificação que representa o experimento sob o qual a execução do experimento está.

Recuperar um status de Execução de experimento

O status da execução do experimento pode ser consultado com o {EXPERIMENT_RUN_ID}.

Solicitação

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}: a ID que representa o Experimento.
{EXPERIMENT_RUN_ID}: a identificação que representa a execução do experimento.
{ACCESS_TOKEN}: Seu valor de token de portador específico fornecido após a autenticação.
{ORG_ID}: as credenciais da sua organização foram encontradas em sua integração exclusiva com o Adobe Experience Platform.
{API_KEY}: seu valor de chave de API específico encontrado na integração exclusiva do Adobe Experience Platform.

Resposta

A chamada GET fornecerá o status no state parâmetro, conforme mostrado abaixo:

{
    "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}: a ID que representa o Experimento Execução.
{EXPERIMENT_ID}: a identificação que representa o experimento sob o qual a execução do experimento está.

Além do estado DONE, outros estados incluem:

Para obter mais informações, os logs detalhados podem ser encontrados sob o parâmetro tasklogs.

Recuperar o modelo treinado

Para obter o modelo treinado criado acima durante o treinamento, fazemos a seguinte solicitação:

Solicitação

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}: a ID correspondente à Execução do experimento que você deseja direcionar. Isso pode ser encontrado na resposta ao criar a Execução de experimento.
{ACCESS_TOKEN}: Seu valor de token de portador específico fornecido após a autenticação.
{ORG_ID}: as credenciais da sua organização foram encontradas em sua integração exclusiva com o Adobe Experience Platform.

A resposta representa o modelo treinado que foi criado.

Resposta

{
    "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}: a ID correspondente ao Modelo.
{EXPERIMENT_ID}: a ID correspondente ao experimento em que a execução do experimento está.
{EXPERIMENT_RUN_ID}: a ID correspondente ao Experimento Run.

Interrupção e excluir uma Experimento agendada

Se você quiser interromper a execução de um Experimento agendado antes de sua execução endTime, isso pode ser feito consultando um solicitação DELETE para a {EXPERIMENT_ID}

Solicitação

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}: a ID correspondente ao experimento.
{ACCESS_TOKEN}: Seu valor de token de portador específico fornecido após a autenticação.
{ORG_ID}: as credenciais da sua organização foram encontradas em sua integração exclusiva com o Adobe Experience Platform.

A seguir está a notificação de Resposta de que o Experimento foi excluído com sucesso.

Resposta

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

Próximas etapas

Este tutorial abordou como consumir as APIs para criar um mecanismo, um experimento, execuções de experimentos programadas e modelos treinados. No próximo exercício, você fará previsões pontuando um novo conjunto de dados usando o modelo treinado de melhor desempenho.