Configura le spiegazioni basate sulle funzionalità

Per utilizzare Vertex Explainable AI con un modello con addestramento personalizzato, devi configurare determinate opzioni quando crei la risorsa Model da cui prevedi di richiedere spiegazioni, quando esegui il deployment del modello o quando invii un job di spiegazione batch. In questa pagina viene descritta la configurazione di queste opzioni.

Se vuoi utilizzare Vertex Explainable AI con un modello tabulare AutoML, non devi eseguire nessuna configurazione: Vertex AI configura automaticamente il modello per Vertex Explainable AI. Salta questo documento e leggi Recupero delle spiegazioni.

Quando e dove configurare le spiegazioni

Le spiegazioni vengono configurate durante la creazione o l'importazione di un modello. Puoi anche configurare le spiegazioni su un modello che hai già creato, anche se non li hai configurati in precedenza.

Configura le spiegazioni durante la creazione o l'importazione dei modelli

Quando crei o importi un Model, puoi impostare una configurazione predefinita per tutte le relative spiegazioni utilizzando il campo explanationSpec di Model.

Puoi creare un Model con addestramento personalizzato in Vertex AI nei seguenti modi:

In entrambi i casi, puoi configurare Model per supportare Vertex Explainable AI. Gli esempi in questo documento presuppongono che tu stia importando un elemento Model. Per configurare Vertex Explainable AI quando crei un elemento Model con addestramento personalizzato utilizzando un TrainingPipeline, utilizza le impostazioni di configurazione descritte in questo documento nel campo modelToUpload di TrainingPipeline.

Configura le spiegazioni per il deployment di modelli o l'acquisizione di previsioni batch

Quando esegui il deployment di un Model in una risorsa Endpoint, puoi:

  • Configura le spiegazioni, indipendentemente dal fatto che il modello sia stato precedentemente configurato per le spiegazioni. Ciò è utile se all'inizio non avevi intenzione di ottenere spiegazioni (e hai omesso il campo explanationSpec durante la creazione del modello), ma in un secondo momento decidi di volere spiegazioni per il modello o se vuoi sostituire alcune delle impostazioni di spiegazione.
  • Disattiva le spiegazioni. Ciò è utile se il modello è configurato per le spiegazioni, ma non prevedi di riceverle dall'endpoint. Per disabilitare le spiegazioni quando esegui il deployment del modello in un endpoint, deseleziona le opzioni di spiegabilità nella console Cloud o imposta DeployedModel.disableExplanations su true.

Analogamente, quando ottieni previsioni batch da un Model, puoi configurare le spiegazioni compilando il campo BatchPredictionJob.explanationSpec o disabilitarle impostando BatchPredictionJob.generateExplanation su false.

Sostituisci la configurazione per ricevere spiegazioni online

Indipendentemente dal fatto che tu abbia creato o importato Model con le impostazioni di spiegazione e che tu abbia configurato le impostazioni di spiegazione durante il deployment, puoi eseguire l'override delle impostazioni di spiegazione iniziali di Model quando ricevi le spiegazioni online.

Quando invii una richiesta explain a Vertex AI, puoi sostituire parte della configurazione della spiegazione impostata in precedenza per Model o DeployedModel.

Nella richiesta explain, puoi eseguire l'override dei seguenti campi:

Sostituisci queste impostazioni nel campo explanationSpecOverride della richiesta di spiegazione.

Importa un modello con un campo explanationSpec

A seconda che tu esegua previsioni utilizzando un container predefinito o un container personalizzato, specifica dettagli leggermente diversi per ExplanationSpec. Seleziona la scheda che corrisponde al contenitore che stai utilizzando:

Container predefinito TensorFlow

Puoi utilizzare uno qualsiasi dei seguenti metodi di attribuzione per Vertex Explainable AI. Leggi il confronto dei metodi di attribuzione delle funzionalità per selezionare quello appropriato per Model:

Valore di Shapley campionato

A seconda dello strumento che vuoi utilizzare per creare o importare Model, seleziona una delle seguenti schede:

Console

Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il tuo metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per i modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni caratteristica di input nel modello:

    1. Inserisci il nome della funzionalità di input.

    2. Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.

    3. Se importi un modello TensorFlow, sono disponibili altri campi di immissione:

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, inserisci il Nome tensore indici e/o il Nome tensore di forma denso.

      3. La modalità non può essere aggiornata qui. Viene impostato automaticamente su NUMERIC per i modelli tabulari o su IMAGE per i modelli immagine.

      4. Se applicabile, imposta il campo Codifica. Se non è configurato, il valore predefinito è IDENTITY.

      5. Se applicabile, imposta il campo Nome gruppo.

  4. Se importi un modello TensorFlow, specifica i campi di output:

    1. Imposta il Nome output dell'elemento.
    2. Imposta il Nome tensore di output della caratteristica.
    3. Se applicabile, imposta la Mappatura del nome visualizzato dell'indice.
    4. Se applicabile, imposta la Chiave di mappatura del nome visualizzato.

  5. Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.

gcloud

  1. Per TensorFlow 2, il valore ExplanationMetadata è facoltativo.

    Scrivi il codice ExplanationMetadata seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Sostituisci quanto segue:

    Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi di input per Model.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. Vengono evidenziati i flag più pertinenti a Vertex Explainable AI. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Sostituisci quanto segue:

    Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

REST

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi di input per Model.

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omesso, Vertex AI deduce automaticamente inputs e outputs dal modello.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON della richiesta: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "sampledShapleyAttribution": {
          "pathCount": PATH_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Gradienti integrati

A seconda dello strumento che vuoi utilizzare per creare o importare Model, seleziona una delle seguenti schede:

Console

Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il tuo metodo di attribuzione delle caratteristiche, seleziona Gradi integrati (per i modelli tabulari) o Gradi integrati (per i modelli di classificazione delle immagini), a seconda di quale è più appropriato per il tuo modello.

  2. Se importi un modello di classificazione delle immagini, segui questi passaggi:

    1. Imposta il Tipo di visualizzazione e la Mappa colori.

    2. Puoi lasciare le impostazioni predefinite per Clip qui sotto, Clip sopra, Tipo di overlay e Numero di passaggi integrali.

    Scopri di più sulle impostazioni di visualizzazione.

  3. Imposta il numero di passaggi da utilizzare per l'approssimazione dell'integrale del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo [1, 100].

    Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova 50.

  4. Configura ogni caratteristica di input nel modello:

    1. Inserisci il nome della funzionalità di input.

    2. Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.

    3. Se importi un modello TensorFlow, sono disponibili altri campi di immissione:

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, inserisci il Nome tensore indici e/o il Nome tensore di forma denso.

      3. La modalità non può essere aggiornata qui. Viene impostato automaticamente su NUMERIC per i modelli tabulari o su IMAGE per i modelli immagine.

      4. Se applicabile, imposta il campo Codifica. Se non è configurato, il valore predefinito è IDENTITY.

      5. Se applicabile, imposta il campo Nome gruppo.

  5. Se importi un modello TensorFlow, specifica i campi di output:

    1. Imposta il Nome output dell'elemento.
    2. Imposta il Nome tensore di output della caratteristica.
    3. Se applicabile, imposta la Mappatura del nome visualizzato dell'indice.
    4. Se applicabile, imposta la Chiave di mappatura del nome visualizzato.

  6. Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.

gcloud

  1. Per TensorFlow 2, il valore ExplanationMetadata è facoltativo.

    Scrivi il codice ExplanationMetadata seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "modality": "MODALITY",
      "visualization": VISUALIZATION_SETTINGS
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Sostituisci quanto segue:

    • FEATURE_NAME: un nome memorabile per l'elemento di input.
    • INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
    • MODALITY: image se Model accetta immagini come input o numeric se Model accetta dati tabulari come input. Il valore predefinito è numeric.

    • VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per informazioni su come compilare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati di immagine.

      Se ometti il campo modality o imposti il campo modality su numeric, ometti completamente il campo visualization.

    • OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
    • OUTPUT_TENSOR_NAME: il nome del tensore di output in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.

    Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi di input per Model.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. Vengono evidenziati i flag più pertinenti a Vertex Explainable AI. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=integrated-gradients \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Sostituisci quanto segue:

    Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

    Facoltativamente, puoi aggiungere flag per configurare l'approssimazione dei gradienti in gradiente.

REST

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • IMAGE_URI: l'URI di un container predefinito di TensorFlow per la distribuzione delle previsioni.
  • STEP_COUNT: il numero di passaggi da utilizzare per l'approssimazione dell'integrazione del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo [1, 100].

    Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova 50.

  • FEATURE_NAME: un nome memorabile per l'elemento di input.
  • INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
  • MODALITY: image se Model accetta immagini come input o numeric se Model accetta dati tabulari come input. Il valore predefinito è numeric.

  • VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per informazioni su come compilare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati di immagine.

    Se ometti il campo modality o imposti il campo modality su numeric, ometti completamente il campo visualization.

  • OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
  • OUTPUT_TENSOR_NAME: il nome del tensore di output in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.

Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi di input per Model.

In via facoltativa, puoi aggiungere campi per configurare l'approssimazione dei gradienti in gradiente in ExplanationParameters.

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omesso, Vertex AI deduce automaticamente inputs e outputs dal modello.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON della richiesta: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "integratedGradientsAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "MODALITY",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

XRAI

A seconda dello strumento che vuoi utilizzare per creare o importare Model, seleziona una delle seguenti schede:

Console

Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il tuo metodo di attribuzione delle caratteristiche, seleziona XRAI (per i modelli di classificazione delle immagini).

  2. Imposta le seguenti opzioni di visualizzazione:

    1. Imposta la Mappa colori.

    2. Puoi lasciare le impostazioni predefinite per Clip qui sotto, Clip sopra, Tipo di overlay e Numero di passaggi integrali.

      Scopri di più sulle impostazioni di visualizzazione.

  3. Imposta il numero di passaggi da utilizzare per l'approssimazione dell'integrale del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo [1, 100].

    Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova 50.

  4. Configura ogni caratteristica di input nel modello:

    1. Inserisci il nome della funzionalità di input.

    2. Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.

    3. Se importi un modello TensorFlow, sono disponibili altri campi di immissione:

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, inserisci il Nome tensore indici e/o il Nome tensore di forma denso.

      3. La modalità non può essere aggiornata qui. Viene impostato automaticamente su NUMERIC per i modelli tabulari o su IMAGE per i modelli immagine.

      4. Se applicabile, imposta il campo Codifica. Se non è configurato, il valore predefinito è IDENTITY.

      5. Se applicabile, imposta il campo Nome gruppo.

  5. Se importi un modello TensorFlow, specifica i campi di output:

    1. Imposta il Nome output dell'elemento.
    2. Imposta il Nome tensore di output della caratteristica.
    3. Se applicabile, imposta la Mappatura del nome visualizzato dell'indice.
    4. Se applicabile, imposta la Chiave di mappatura del nome visualizzato.

  6. Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.

gcloud

  1. Per TensorFlow 2, il valore ExplanationMetadata è facoltativo.

    Scrivi il codice ExplanationMetadata seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "modality": "image",
      "visualization": VISUALIZATION_SETTINGS
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Sostituisci quanto segue:

    Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi di input per Model.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. Vengono evidenziati i flag più pertinenti a Vertex Explainable AI. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=xrai \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Sostituisci quanto segue:

    Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

    Facoltativamente, puoi aggiungere flag per configurare l'approssimazione dei gradienti in gradiente.

REST

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi di input per Model.

In via facoltativa, puoi aggiungere campi per configurare l'approssimazione dei gradienti in gradiente in ExplanationParameters.

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omesso, Vertex AI deduce automaticamente inputs e outputs dal modello.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON della richiesta: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "xraiAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "image",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Container predefiniti scikit-learn e XGBoost

Se Model accetta dati tabulari come input e fornisce previsioni utilizzando un container scikit-learn o XGBoost predefinito per le previsioni, puoi configurarlo in modo che utilizzi il metodo di attribuzione Shapley campionato per le spiegazioni.

A seconda dello strumento che vuoi utilizzare per creare o importare Model, seleziona una delle seguenti schede:

Console

Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il tuo metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per i modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni caratteristica di input nel modello:

    1. Inserisci il nome della funzionalità di input.

      Se gli artefatti del modello non includono nomi delle caratteristiche, Vertex AI non è in grado di mappare i nomi delle caratteristiche di input specificate al modello. In questo caso, devi fornire una sola caratteristica di input con un qualsiasi nome arbitrario facile per l'utente, come input_features. Nella risposta di spiegazione, otterrai un elenco dimensionale N di attribuzioni, dove N è il numero di caratteristiche nel modello e gli elementi nell'elenco vengono visualizzati nello stesso ordine del set di dati di addestramento.

    2. Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.

  4. Imposta il Nome output dell'elemento.

  5. Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.

gcloud

  1. Scrivi il codice ExplanationMetadata seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
    }
  }
}

    Sostituisci quanto segue:

    • FEATURE_NAME: un nome memorabile per l'elemento di input.
    • OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.

    Se specifichi le base di riferimento, assicurati che corrispondano all'input del modello, in genere un elenco di matrici 2-D. In caso contrario, il valore predefinito per la base di input è una matrice 2D del valore 0 della forma di input.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. Vengono evidenziati i flag più pertinenti a Vertex Explainable AI. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Sostituisci quanto segue:

    Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

REST

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Se specifichi le base di riferimento, assicurati che corrispondano all'input del modello, in genere un elenco di matrici 2-D. In caso contrario, il valore predefinito per la base di input è una matrice 2D del valore 0 della forma di input.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON della richiesta: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {
         }
       },
       "outputs": {
         "OUTPUT_NAME": {
         }
       }
    }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Container personalizzato

Se Model accetta dati tabulari come input e fornisce previsioni utilizzando un container personalizzato, puoi configurarlo in modo che utilizzi il metodo di attribuzione Shapley campionato per le spiegazioni.

Determinazione dei nomi delle caratteristiche e degli output

Nei passaggi seguenti, devi fornire a Vertex AI i nomi delle caratteristiche che Model prevede come input. Devi anche specificare la chiave utilizzata per gli output nelle previsioni del Model.

Determinazione dei nomi delle caratteristiche

Se Model prevede che ogni istanza di input abbia determinate chiavi di primo livello, quelle chiavi saranno i nomi delle tue caratteristiche.

Ad esempio, considera un valore Model che prevede che ogni istanza di input abbia il formato seguente:

{
  "length": <value>,
  "width": <value>
}

In questo caso, i nomi delle caratteristiche sono length e width. Anche se i valori di questi campi contengono elenchi o oggetti nidificati, length e width sono le uniche chiavi necessarie per i passaggi successivi. Quando richiedi le spiegazioni, Vertex Explainable AI fornisce le attribuzioni per ogni elemento nidificato delle tue caratteristiche.

Se Model prevede un input senza chiave, Vertex Explainable AI considera Model una singola caratteristica. Puoi utilizzare qualsiasi stringa facile da ricordare per il nome della caratteristica.

Ad esempio, considera un valore Model che prevede che ogni istanza di input abbia il formato seguente:

[
  <value>,
  <value>
]

In questo caso, fornisci a Vertex Explainable AI con un nome di funzionalità a tua scelta, ad esempio dimensions.

Determinazione del nome dell'output

Se Model restituisce ogni istanza di previsione online con output con chiave, questa chiave corrisponde al nome dell'output.

Ad esempio, considera un valore Model che restituisce ogni previsione nel seguente formato:

{
  "scores": <value>
}

In questo caso, il nome dell'output è scores. Se il valore del campo scores è un array, quando ricevi spiegazioni, Vertex Explainable AI restituisce le attribuzioni delle caratteristiche per l'elemento con il valore più alto in ogni previsione. Per configurare Vertex Explainable AI in modo da fornire attribuzioni delle caratteristiche per elementi aggiuntivi del campo di output, puoi specificare i campi topK o outputIndices di ExplanationParameters. Tuttavia, gli esempi in questo documento non dimostrano queste opzioni.

Se Model restituisce previsioni senza chiave, puoi utilizzare qualsiasi stringa facile da ricordare per il nome dell'output. Ad esempio, questo vale se Model restituisce un array o uno scalare per ogni previsione.

Creazione di Model in corso...

A seconda dello strumento che vuoi utilizzare per creare o importare Model, seleziona una delle seguenti schede:

Console

Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il tuo metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per i modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni caratteristica di input nel modello:

    1. Inserisci il nome della funzionalità di input.

      Se gli artefatti del modello non includono nomi delle caratteristiche, Vertex AI non è in grado di mappare i nomi delle caratteristiche di input specificate al modello. In questo caso, devi fornire una sola caratteristica di input con un qualsiasi nome arbitrario facile per l'utente, come input_features. Nella risposta di spiegazione, otterrai un elenco dimensionale N di attribuzioni, dove N è il numero di caratteristiche nel modello e gli elementi nell'elenco vengono visualizzati nello stesso ordine del set di dati di addestramento.

    2. Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.

  4. Imposta il Nome output dell'elemento.

  5. Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.

gcloud

  1. Scrivi il codice ExplanationMetadata seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {}
  },
  "outputs": {
    "OUTPUT_NAME": {}
  }
}

    Sostituisci quanto segue:

    • FEATURE_NAME: il nome della caratteristica, come descritto nella sezione "Determinazione dei nomi delle caratteristiche" di questo documento.
    • OUTPUT_NAME: il nome dell'output, come descritto nella sezione "Determinazione del nome dell'output" di questo documento.

    Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi di input per Model.

    Se specifichi le base di riferimento, assicurati che corrispondano all'input del modello, in genere un elenco di matrici 2-D. In caso contrario, il valore predefinito per la base di input è una matrice 2D del valore 0 della forma di input.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. Vengono evidenziati i flag più pertinenti a Vertex Explainable AI. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Sostituisci quanto segue:

    Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

REST

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PATH_COUNT: il numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione di Shapley campionato. Deve essere un numero intero compreso nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova 25.

  • FEATURE_NAME: il nome della caratteristica, come descritto nella sezione "Determinazione dei nomi delle caratteristiche" di questo documento.
  • OUTPUT_NAME: il nome dell'output, come descritto nella sezione "Determinazione del nome dell'output" di questo documento.

Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi di input per Model.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON della richiesta: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {}
       },
       "outputs": {
         "OUTPUT_NAME": {}
       }
    }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Passaggi successivi