Addestrare e valutare un modello utilizzando l'API Sensei Machine Learning

In questo esercitazione viene illustrato come creare, addestrare e valutare un modello utilizzando le chiamate API. Fare riferimento a questo documento per un elenco dettagliato della documentazione API.

Prerequisiti

Segui Importa una ricetta in pacchetti utilizzando l'API per creare un motore, necessario per addestrare e valutare un modello utilizzando l'API.

Segui l'esercitazione sull'autenticazione API Experience Platform per iniziare ad effettuare chiamate API.

Dall’esercitazione ora dovrebbero essere presenti i seguenti valori:

Flusso di lavoro API

Utilizzeremo le API per creare un’esecuzione di esperimento per la formazione. Per questo tutorial, ci concentreremo sugli endpoint "Engines", "MLInstance" ed "Experiments". Il grafico seguente illustra la relazione tra i tre e introduce anche l'idea di un modello e di un'esecuzione.

Creare un'istanza MLI

La creazione di un’istanza MLI può essere eseguita utilizzando la seguente richiesta. Si utilizzerà {ENGINE_ID} restituito durante la creazione di un motore da Importare una composizione in pacchetti utilizzando l'esercitazione API.

Richiesta

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}: il valore specifico del token portatore fornito dopo l'autenticazione.
{ORG_ID}: credenziali dell'organizzazione trovate nell'integrazione univoca del Adobe Experience Platform.
{API_KEY}: valore chiave API specifico trovato nell'integrazione univoca di Adobe Experience Platform.
{JSON_PAYLOAD}: configurazione dell'istanza MLI. L’esempio utilizzato nel nostro tutorial è mostrato qui:

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

La risposta contiene {INSTANCE_ID} che rappresenta l'istanza MLI creata. È possibile creare più istanze del modello MLI con configurazioni diverse.

Risposta

{
    "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}: questo ID rappresenta il motore in cui viene creata l'istanza MLI.
{INSTANCE_ID}: ID che rappresenta l'istanza MLI.

Creare un esperimento

Un esperimento viene utilizzato da uno scienziato dei dati per arrivare a un modello ad alte prestazioni durante la formazione. Gli esperimenti multipli includono la modifica di set di dati, funzioni, parametri di apprendimento e hardware. L’esempio seguente illustra come creare un esperimento.

Richiesta

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}: credenziali organizzazione trovate nell'integrazione univoca di Adobe Experience Platform.
{ACCESS_TOKEN}: il valore del token Bearer specifico fornito dopo l'autenticazione.
{API_KEY}: il valore specifico della chiave API trovato nell'integrazione Adobe Experience Platform univoca.
{JSON_PAYLOAD}: oggetto esperimento creato. L'esempio che usiamo nel nostro esercitazione è mostrato qui:

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

{INSTANCE_ID}: ID che rappresenta l'istanza MLI.

La risposta dalla creazione dell’esperimento è simile alla seguente.

Risposta

{
    "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 che rappresenta l'esperimento appena creato.
{INSTANCE_ID}: ID che rappresenta l'istanza MLI.

Creare un esperimento pianificato per la formazione

Gli esperimenti pianificati vengono utilizzati in modo da non dover creare ogni singola esecuzione di esperimenti tramite una chiamata API. Invece, forniamo tutti i parametri necessari durante la creazione dell'esperimento e ogni esecuzione verrà creata periodicamente.

Per indicare la creazione di un esperimento pianificato, è necessario aggiungere una sezione template nel corpo della richiesta. In template sono inclusi tutti i parametri necessari per la pianificazione delle esecuzioni, ad esempio tasks, che indica l'azione, e schedule, che indica la tempistica delle esecuzioni pianificate.

Richiesta

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}: credenziali organizzazione trovate nell'integrazione univoca di Adobe Experience Platform.
{ACCESS_TOKEN}: il valore specifico del token portatore fornito dopo l'autenticazione.
{API_KEY}: il valore specifico della chiave API trovato nell'integrazione Adobe Experience Platform univoca.
{JSON_PAYLOAD}: Set di dati da inviare. L'esempio che usiamo nel nostro esercitazione è mostrato qui:

{
    "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 creiamo un esperimento, il corpo, {JSON_PAYLOAD}, dovrebbe contenere il mlInstanceId parametro o il mlInstanceQuery parametro. In questo esempio, un esperimento pianificato richiamerà un'esecuzione cron ogni 20 minuti, impostata nel parametro, a partire da fino a startTime .endTime

Risposta

{
    "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 che rappresenta l'esperimento.
{INSTANCE_ID}: ID che rappresenta l'istanza MLI.

Creare un’esecuzione di esperimento per l’apprendimento

Una volta creata un’entità esperimento, è possibile creare ed eseguire un’esecuzione di addestramento utilizzando la chiamata seguente. Sarà necessario {EXPERIMENT_ID} e specificare lo stato di mode che si desidera attivare nel corpo della richiesta.

Richiesta

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 corrispondente all'esperimento di cui desideri eseguire il targeting. Questo si trova nella risposta durante la creazione dell’esperimento.
{ORG_ID}: credenziali organizzazione trovate nell'integrazione univoca di Adobe Experience Platform.
{ACCESS_TOKEN}: il valore del token Bearer specifico fornito dopo l'autenticazione.
{API_KEY}: valore chiave API specifico trovato nell'integrazione univoca di Adobe Experience Platform.
{JSON_PAYLOAD}: per creare un'esecuzione di addestramento, è necessario includere nel corpo quanto segue:

{
    "mode":"Train"
}

È inoltre possibile ignorare i parametri di configurazione includendo un array tasks:

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

Riceverai la seguente risposta che ti farà sapere {EXPERIMENT_RUN_ID} e la configurazione in tasks.

Risposta

{
    "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 che rappresenta l'esecuzione dell'esperimento.
{EXPERIMENT_ID}: ID che rappresenta l'esperimento in cui si trova l'esecuzione dell'esperimento.

Recuperare lo stato di esecuzione di un esperimento

È possibile eseguire una query sullo stato dell'esecuzione dell'esperimento con {EXPERIMENT_RUN_ID}.

Richiesta

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 che rappresenta l'esperimento.
{EXPERIMENT_RUN_ID}: ID che rappresenta l'esecuzione dell'esperimento.
{ACCESS_TOKEN}: il valore del token Bearer specifico fornito dopo l'autenticazione.
{ORG_ID}: credenziali organizzazione trovate nell'integrazione univoca di Adobe Experience Platform.
{API_KEY}: il valore specifico della chiave API trovato nell'integrazione Adobe Experience Platform univoca.

Risposta

La chiamata GET fornirà lo stato nel state parametro, come mostrato di seguito:

{
    "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}: l'ID che rappresenta l'esecuzione dell'esperimento.
{EXPERIMENT_ID}: ID che rappresenta l'esperimento in cui si trova l'esecuzione dell'esperimento.

Oltre allo stato DONE, gli altri stati includono:

Per ulteriori informazioni, i registri dettagliati si trovano sotto il parametro tasklogs.

Recupera il modello addestrato

Per ottenere il modello addestrato creato in precedenza durante la formazione, effettuiamo la seguente richiesta:

Richiesta

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 corrispondente all'esecuzione dell'esperimento di cui si desidera eseguire il targeting. Questo si trova nella risposta durante la creazione dell’esecuzione dell’esperimento.
{ACCESS_TOKEN}: il valore del token Bearer specifico fornito dopo l'autenticazione.
{ORG_ID}: credenziali organizzazione trovate nell'integrazione univoca di Adobe Experience Platform.

La risposta rappresenta il modello addestrato che è stato creato.

Risposta

{
    "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 corrispondente al modello.
{EXPERIMENT_ID}: l'ID corrispondente all'esperimento eseguito.
{EXPERIMENT_RUN_ID}: ID corrispondente all'esecuzione dell'esperimento.

Interruzione ed eliminare un esperimento pianificato

Se si desidera interrompere l'esecuzione di un esperimento pianificato prima della sua endTime, è possibile eseguire questa operazione interrogando un richiesta DELETE al {EXPERIMENT_ID}

Richiesta

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 corrispondente all'esperimento.
{ACCESS_TOKEN}: il valore del token Bearer specifico fornito dopo l'autenticazione.
{ORG_ID}: credenziali organizzazione trovate nell'integrazione univoca di Adobe Experience Platform.

Di seguito è riportata la risposta che notifica che l'esperimento è stato eliminato correttamente.

Risposta

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

Passaggi successivi

Questo tutorial illustra come utilizzare le API per creare un motore, un esperimento, esecuzioni di esperimenti pianificate e modelli addestrati. Nell'esercizio successivo, effettuerai delle previsioni assegnando un punteggio a un nuovo set di dati utilizzando il modello addestrato con le prestazioni migliori.