Configurare le spiegazioni basate su caratteristiche

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

Se vuoi utilizzare Vertex Explainable AI con un modello tabulare AutoML, non devi eseguire alcuna configurazione; Vertex AI configura automaticamente il modello per Vertex Explainable AI. Salta questo documento e leggi Ricevere spiegazioni.

Quando e dove configurare le spiegazioni

Le spiegazioni vengono configurate quando crei o importi un modello. Puoi anche configurare le spiegazioni su un modello che hai già creato, anche se non lo hai fatto in precedenza.

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

Quando crei o importi un Model, puoi impostare una configurazione predefinita per tutte le sue spiegazioni utilizzando il explanationSpec campo del 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 Model. Per configurare Vertex Explainable AI quando crei un Model addestrato personalizzato utilizzando un TrainingPipeline, utilizza le impostazioni di configurazione descritte in questo documento nel modelToUpload campo del TrainingPipeline.

Configurare le spiegazioni durante il deployment dei modelli o la generazione di previsioni collettive

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 o meno. Questa opzione è utile se inizialmente non prevedevi di ricevere spiegazioni (e hai omesso il campo explanationSpec quando hai creato il modello), ma in un secondo momento decidi di volere spiegazioni per il modello o se vuoi eseguire l'override di alcune impostazioni di spiegazione.
  • Disattiva le spiegazioni. Questa opzione è utile se il modello è configurato per le spiegazioni, ma non prevedi di ricevere spiegazioni dall'endpoint. Per disabilitare le spiegazioni durante 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 collettive da un Model, puoi configurare le spiegazioni compilando il BatchPredictionJob.explanationSpec campo o disattivarle impostando BatchPredictionJob.generateExplanation su false.

Sostituire la configurazione quando si ricevono spiegazioni online

Indipendentemente dal fatto che tu abbia creato o importato Model con le impostazioni di spiegazione e indipendentemente dal fatto che tu abbia configurato le impostazioni di spiegazione durante il deployment, puoi sostituire le impostazioni di spiegazione iniziali di Model quando ricevi 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:

  • Basi di input per qualsiasi modello addestrato in base alle esigenze
  • Configurazione della visualizzazione per i modelli di immagini
  • ExplanationParameters tranne per method

Sostituisci queste impostazioni nel campo explanationSpecOverride della richiesta di spiegazione.

Importare un modello con un campo explanationSpec

A seconda che tu pubblichi le previsioni utilizzando un contenuto predefinito o un contenuto personalizzato, specifica dettagli leggermente diversi per ExplanationSpec. Seleziona la scheda corrispondente 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 caratteristiche per selezionare quello più adatto per il tuo Model:

Valore di Shapley campionato

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

Console

Segui la guida all'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Interpretabilità, svolgi i seguenti passaggi:

  1. Per il metodo di attribuzione delle funzionalità, seleziona Valore di Shapley campionato (per i modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di permutazioni delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso tra 0 e [1, 50].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un maggiore impegno computazionale. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

    2. Se vuoi, puoi aggiungere uno o più livelli di base per l'input. In caso contrario, Vertex Explainable AI sceglie una base di riferimento predefinita per gli input composta da valori tutti pari a zero, ovvero un'immagine nera per i dati immagine.

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

      1. Compila il nome del tensore di input.

      2. Se applicabile, compila il nome del tensore di indici e/o il nome del tensore di forma densa.

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

      4. Se applicabile, imposta il campo Codifica. Se non viene impostato, 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 dell'output della funzionalità.
    2. Imposta il nome del tensore di output della funzionalità.
    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 completato la configurazione delle impostazioni di esplicabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

    Scrivi quanto segue ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiamalo explanation-metadata.json:

    explanation-metadata.json

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

    Sostituisci quanto segue:

    • FEATURE_NAME: un nome facile da ricordare per la funzionalità di input.
    • INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi l'articolo Utilizzare TensorFlow con Vertex Explainable AI.
    • OUTPUT_NAME: un 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 l'articolo Utilizzare TensorFlow con Vertex Explainable AI.

    Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. In caso contrario, Vertex AI sceglie le linee di base di input per Model.

  2. Esegui il comando seguente per creare una risorsa Model che supporti la tecnologia Vertex Explainable AI. I flag più pertinenti a Vertex Explainable AI sono evidenziati. 

    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 conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

REST

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

Per conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. In caso contrario, Vertex AI sceglie le linee di base di input per Model.

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omessi, Vertex AI deducono 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, quindi esegui il comando seguente: 

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, quindi esegui il comando seguente: 

$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 il Model, seleziona una delle seguenti schede:

Console

Segui la guida all'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Interpretabilità, svolgi i seguenti passaggi:

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

  2. Se importi un modello di classificazione delle immagini:

    1. Imposta Tipo di visualizzazione e Mappa di colori.

    2. Puoi lasciare le impostazioni predefinite per Taglia sotto, Taglia 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 approssimare l'integrale sul percorso durante l'attribuzione delle funzionalità. Deve essere un numero intero compreso tra 0 e [1, 100].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un maggiore impegno computazionale. Se non sai quale valore utilizzare, prova 50.

  4. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

    2. Se vuoi, puoi aggiungere uno o più livelli di base per l'input. In caso contrario, Vertex Explainable AI sceglie una base di riferimento predefinita per gli input composta da valori tutti pari a zero, ovvero un'immagine nera per i dati immagine.

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

      1. Compila il nome del tensore di input.

      2. Se applicabile, compila il nome del tensore di indici e/o il nome del tensore di forma densa.

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

      4. Se applicabile, imposta il campo Codifica. Se non viene impostato, 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 dell'output della funzionalità.
    2. Imposta il nome del tensore di output della funzionalità.
    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 completato la configurazione delle impostazioni di esplicabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

    Scrivi quanto segue ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiamalo 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 facile da ricordare per la funzionalità di input.
    • INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi l'articolo Utilizzare 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 scoprire come compilare questo campo, leggi Configurare le impostazioni di visualizzazione per i dati delle immagini.

      Se ometti il campo modality o lo imposti su numeric, ometti del tutto il campo visualization.modality

    • OUTPUT_NAME: un 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 l'articolo Utilizzare TensorFlow con Vertex Explainable AI.

    Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. In caso contrario, Vertex AI sceglie le linee di base di input per Model.

  2. Esegui il comando seguente per creare una risorsa Model che supporti la tecnologia Vertex Explainable AI. I flag più pertinenti a Vertex Explainable AI sono evidenziati. 

    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 conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

    Se vuoi, puoi aggiungere flag per configurare l'approssimazione SmoothGrad dei gradienti.

REST

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

  • IMAGE_URI: l'URI di un contenitore predefinito di TensorFlow per la pubblicazione delle previsioni.
  • STEP_COUNT: il numero di passaggi da utilizzare per approssimare l'integrale sul percorso durante l'attribuzione delle funzionalità. Deve essere un numero intero compreso nell'intervallo [1, 100].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un maggiore impegno computazionale. Se non sai quale valore utilizzare, prova 50.

  • FEATURE_NAME: un nome facile da ricordare per la funzionalità di input.
  • INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi l'articolo Utilizzare 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 scoprire come compilare questo campo, leggi Configurare le impostazioni di visualizzazione per i dati delle immagini.

    Se ometti il campo modality o lo imposti su numeric, ometti del tutto il campo visualization.modality

  • OUTPUT_NAME: un 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 l'articolo Utilizzare TensorFlow con Vertex Explainable AI.

Per conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. In caso contrario, Vertex AI sceglie le linee di base di input per Model.

Se vuoi, puoi aggiungere campi per configurare l'approssimazione SmoothGrad dei gradienti al ExplanationParameters.

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omessi, Vertex AI deducono 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, quindi esegui il comando seguente: 

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, quindi esegui il comando seguente: 

$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 il Model, seleziona una delle seguenti schede:

Console

Segui la guida all'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Interpretabilità, svolgi i seguenti passaggi:

  1. Per il 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 di colori.

    2. Puoi lasciare le impostazioni predefinite per Taglia sotto, Taglia 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 approssimare l'integrale sul percorso durante l'attribuzione delle funzionalità. Deve essere un numero intero compreso tra 0 e [1, 100].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un maggiore impegno computazionale. Se non sai quale valore utilizzare, prova 50.

  4. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

    2. Se vuoi, puoi aggiungere uno o più livelli di base per l'input. In caso contrario, Vertex Explainable AI sceglie una base di riferimento predefinita per gli input composta da valori tutti pari a zero, ovvero un'immagine nera per i dati immagine.

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

      1. Compila il nome del tensore di input.

      2. Se applicabile, compila il nome del tensore di indici e/o il nome del tensore di forma densa.

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

      4. Se applicabile, imposta il campo Codifica. Se non viene impostato, 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 dell'output della funzionalità.
    2. Imposta il nome del tensore di output della funzionalità.
    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 completato la configurazione delle impostazioni di esplicabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

    Scrivi quanto segue ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiamalo 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:

    Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. In caso contrario, Vertex AI sceglie le linee di base di input per Model.

  2. Esegui il comando seguente per creare una risorsa Model che supporti la tecnologia Vertex Explainable AI. I flag più pertinenti a Vertex Explainable AI sono evidenziati. 

    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 conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

    Se vuoi, puoi aggiungere flag per configurare l'approssimazione SmoothGrad dei gradienti.

REST

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

Per conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. In caso contrario, Vertex AI sceglie le linee di base di input per Model.

Se vuoi, puoi aggiungere campi per configurare l'approssimazione SmoothGrad dei gradienti al ExplanationParameters.

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omessi, Vertex AI deducono 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, quindi esegui il comando seguente: 

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, quindi esegui il comando seguente: 

$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 di scikit-learn e XGBoost

Se Model accetta dati tabulari come input e genera previsioni utilizzando un container scikit-learn o XGBoost predefinito per la previsione, puoi configurarlo in modo da utilizzare il metodo di attribuzione di Shapley campionata per le spiegazioni.

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

Console

Segui la guida all'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Interpretabilità, svolgi i seguenti passaggi:

  1. Per il metodo di attribuzione delle funzionalità, seleziona Valore di Shapley campionato (per i modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di permutazioni delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso tra 0 e [1, 50].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un maggiore impegno computazionale. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

      Se gli elementi del modello non includono i nomi delle funzionalità, Vertex AI non è in grado di mappare i nomi delle funzionalità di input specificati al modello. In questo caso, devi fornire una sola funzionalità di input con un nome arbitrario e facile da ricordare, ad esempio input_features. Nella risposta della spiegazione, riceverai un elenco di attribuzioni di N dimensioni, dove N è il numero di funzionalità nel modello e gli elementi nell'elenco vengono visualizzati nello stesso ordine del set di dati di addestramento.

    2. Se vuoi, puoi aggiungere uno o più livelli di base per l'input. In caso contrario, Vertex Explainable AI sceglie una base di riferimento predefinita per gli input composta da valori tutti pari a zero, ovvero un'immagine nera per i dati immagine.

  4. Imposta il nome dell'output della funzionalità.

  5. Fai clic sul pulsante Importa dopo aver completato la configurazione delle impostazioni di esplicabilità.

gcloud

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

    explanation-metadata.json

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

    Sostituisci quanto segue:

    • FEATURE_NAME: un nome facile da ricordare per la funzionalità di input.
    • OUTPUT_NAME: un nome facile da ricordare per l'output del modello.

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

  2. Esegui il comando seguente per creare una risorsa Model che supporti la tecnologia Vertex Explainable AI. I flag più pertinenti a Vertex Explainable AI sono evidenziati. 

    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 conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

REST

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

Per conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

Se specifichi le linee di base di input, assicurati che corrispondano all'input del modello, in genere un elenco di matrici 2D. In caso contrario, il valore predefinito per la linea di base di input è una matrice 2D con valori pari a 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, quindi esegui il comando seguente: 

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, quindi esegui il comando seguente: 

$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 genera previsioni utilizzando un contenitore personalizzato, puoi configurarlo per utilizzare il metodo di attribuzione Shapley campionata per le spiegazioni.

Determinazione dei nomi delle funzionalità e dell'output

Nei passaggi che seguono, devi fornire a Vertex AI i nomi delle funzionalità che Model si aspetta come input. Devi anche specificare la chiave utilizzata per le uscite nelle previsioni di Model.

Determinazione dei nomi delle funzionalità

Se Model si aspetta che ogni istanza di input abbia determinate chiavi di primo livello, queste chiavi sono i nomi delle funzionalità.

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

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

In questo caso, i nomi delle funzionalità 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 spiegazioni, Vertex Explainable AI fornisce attribuzioni per ogni elemento nidificato delle tue funzionalità.

Se Model prevede un input non con chiave, Vertex Explainable AI considera che Model abbia una singola funzionalità. Puoi utilizzare qualsiasi stringa facile da ricordare per il nome della funzionalità.

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

[
  <value>,
  <value>
]

In questo caso, fornisci a Vertex Explainable AI un singolo nome di funzionalità a tua scelta, come dimensions.

Determinazione del nome dell'output

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

Ad esempio, considera un 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 le 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 che fornisca 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 mostrano queste opzioni.

Se Model restituisce previsioni non con chiavi, puoi utilizzare qualsiasi stringa memorabile per il nome dell'output. Ad esempio, questo vale se Model restituisce un array o un valore scalare per ogni previsione.

Creazione del file Model

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

Console

Segui la guida all'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Interpretabilità, svolgi i seguenti passaggi:

  1. Per il metodo di attribuzione delle funzionalità, seleziona Valore di Shapley campionato (per i modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di permutazioni delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso tra 0 e [1, 50].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un maggiore impegno computazionale. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

      Se gli elementi del modello non includono i nomi delle funzionalità, Vertex AI non è in grado di mappare i nomi delle funzionalità di input specificati al modello. In questo caso, devi fornire una sola funzionalità di input con un nome arbitrario e facile da ricordare, ad esempio input_features. Nella risposta della spiegazione, riceverai un elenco di attribuzioni di N dimensioni, dove N è il numero di funzionalità nel modello e gli elementi nell'elenco vengono visualizzati nello stesso ordine del set di dati di addestramento.

    2. Se vuoi, puoi aggiungere uno o più livelli di base per l'input. In caso contrario, Vertex Explainable AI sceglie una base di riferimento predefinita per gli input composta da valori tutti pari a zero, ovvero un'immagine nera per i dati immagine.

  4. Imposta il nome dell'output della funzionalità.

  5. Fai clic sul pulsante Importa dopo aver completato la configurazione delle impostazioni di esplicabilità.

gcloud

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

    explanation-metadata.json

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

    Sostituisci quanto segue:

    • FEATURE_NAME: il nome della funzionalità, come descritto nella sezione "Determinare i nomi delle funzionalità" di questo documento.
    • OUTPUT_NAME: il nome dell'output, come descritto nella sezione "Determinare il nome dell'output" di questo documento.

    Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. In caso contrario, Vertex AI sceglie le linee di base di input per Model.

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

  2. Esegui il comando seguente per creare una risorsa Model che supporti la tecnologia Vertex Explainable AI. I flag più pertinenti a Vertex Explainable AI sono evidenziati. 

    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 conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

REST

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

  • PATH_COUNT: il numero di permutazioni delle funzionalità da utilizzare per il metodo di attribuzione del valore di Shapley campionato. Deve essere un numero intero compreso tra 0 e [1, 50].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un maggiore impegno computazionale. Se non sai quale valore utilizzare, prova 25.

  • FEATURE_NAME: il nome della funzionalità, come descritto nella sezione "Determinare i nomi delle funzionalità" di questo documento.
  • OUTPUT_NAME: il nome dell'output, come descritto nella sezione "Determinare il nome dell'output" di questo documento.

Per conoscere i valori appropriati per gli altri segnaposto, consulta upload e Importare i modelli.

Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. In caso contrario, Vertex AI sceglie le linee di base 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, quindi esegui il comando seguente: 

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, quindi esegui il comando seguente: 

$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