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 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 Ottenere spiegazioni.

Quando e dove configurare le spiegazioni

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

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

Quando crei o importi un Model, puoi impostare una configurazione predefinita per tutte le relative spiegazioni utilizzando il campo explanationSpec 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 campo modelToUpload del TrainingPipeline.

Configurare le spiegazioni durante il deployment dei modelli o l'ottenimento di inferenze batch

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

  • Configura le spiegazioni, indipendentemente dal fatto che il modello sia stato configurato in precedenza per le spiegazioni. Ciò è utile se inizialmente non avevi pianificato di ottenere 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 ignorare alcune impostazioni di spiegazione.
  • Disattiva le spiegazioni. È utile se il modello è configurato per le spiegazioni, ma non prevedi di ottenerle dall'endpoint. Per disattivare 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 inferenze batch da un Model, puoi configurare le spiegazioni compilando il campo BatchPredictionJob.explanationSpec o disabilitarle impostando BatchPredictionJob.generateExplanation su false.

Ignorare la configurazione quando si ottengono spiegazioni online

Indipendentemente dal fatto che tu abbia creato o importato le impostazioni di Model con spiegazione e indipendentemente dal fatto che tu abbia configurato le impostazioni di spiegazione durante l'implementazione, puoi ignorare le impostazioni di spiegazione iniziali di Model quando ottieni spiegazioni online.

Quando invii una richiesta explain a Vertex AI, puoi ignorare parte della configurazione della spiegazione che hai impostato in precedenza per Model o DeployedModel.

Nella richiesta explain, puoi ignorare i seguenti campi:

Esegui l'override di queste impostazioni nel campo explanationSpecOverride della richiesta di spiegazione.

Importare un modello con un campo explanationSpec

A seconda che fornisci inferenze utilizzando un container predefinito o un container 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 tra i metodi di attribuzione delle caratteristiche per selezionare quello più appropriato 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 per importare un modello utilizzando la console Google Cloud . Quando arrivi al passaggio Spiegabilità, procedi nel seguente modo:

  1. Per il metodo di attribuzione delle funzionalità, seleziona Valore di Shapley campione (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 nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede più risorse di calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della caratteristica di input.

    2. (Facoltativo) Puoi aggiungere una o più baseline di input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita di valori tutti pari a zero, che è un'immagine nera per i dati immagine.

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

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila il campo Nome tensore degli indici e/o il campo Nome tensore di forma denso.

      3. La modalità non può essere aggiornata qui. Viene impostato automaticamente su NUMERIC per i modelli tabellari 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 terminato di configurare le impostazioni di interpretabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

    Scrivi il seguente 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:

    Puoi anche aggiungere input baselines a ExplanationMetadata. In caso contrario, Vertex AI sceglie le baseline di input per Model.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. I flag più pertinenti per 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 informazioni sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

REST

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

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

Puoi anche aggiungere input baselines a ExplanationMetadata. In caso contrario, Vertex AI sceglie le baseline di input per Model.

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omessi, 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 di queste 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 per importare un modello utilizzando la console Google Cloud . Quando arrivi al passaggio Spiegabilità, procedi nel seguente modo:

  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 il Tipo di visualizzazione e la Mappa dei colori.

    2. Puoi lasciare le impostazioni predefinite per Clip 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 approssimare l'integrale sui cammini 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 più risorse di calcolo. Se non sai quale valore utilizzare, prova 50.

  4. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della caratteristica di input.

    2. (Facoltativo) Puoi aggiungere una o più baseline di input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita di valori tutti pari a zero, che è un'immagine nera per i dati immagine.

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

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila il campo Nome tensore degli indici e/o il campo Nome tensore di forma denso.

      3. La modalità non può essere aggiornata qui. Viene impostato automaticamente su NUMERIC per i modelli tabellari 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 terminato di configurare le impostazioni di interpretabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

    Scrivi il seguente 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 memorabile 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 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 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 completamente il campo visualization.modality

    • OUTPUT_NAME: un nome memorabile 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.

    Puoi anche aggiungere input baselines a ExplanationMetadata. In caso contrario, Vertex AI sceglie le baseline di input per Model.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. I flag più pertinenti per 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 informazioni sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

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

REST

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

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

Puoi anche aggiungere input baselines a ExplanationMetadata. In caso contrario, Vertex AI sceglie le baseline di input per Model.

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

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omessi, 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 di queste 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 per importare un modello utilizzando la console Google Cloud . Quando arrivi al passaggio Spiegabilità, procedi nel seguente modo:

  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 dei colori.

    2. Puoi lasciare le impostazioni predefinite per Clip 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 approssimare l'integrale sui cammini 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 più risorse di calcolo. Se non sai quale valore utilizzare, prova 50.

  4. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della caratteristica di input.

    2. (Facoltativo) Puoi aggiungere una o più baseline di input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita di valori tutti pari a zero, che è un'immagine nera per i dati immagine.

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

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila il campo Nome tensore degli indici e/o il campo Nome tensore di forma denso.

      3. La modalità non può essere aggiornata qui. Viene impostato automaticamente su NUMERIC per i modelli tabellari 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 terminato di configurare le impostazioni di interpretabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

    Scrivi il seguente 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:

    Puoi anche aggiungere input baselines a ExplanationMetadata. In caso contrario, Vertex AI sceglie le baseline di input per Model.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. I flag più pertinenti per 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 informazioni sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

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

REST

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

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

Puoi anche aggiungere input baselines a ExplanationMetadata. In caso contrario, Vertex AI sceglie le baseline di input per Model.

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

Per i modelli TensorFlow 2, il campo metadata è facoltativo. Se omessi, 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 di queste 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 scikit-learn e XGBoost

Se il tuo Model accetta dati tabulari come input e fornisce previsioni utilizzando un container predefinito scikit-learn o XGBoost per la previsione, puoi configurarlo per utilizzare il metodo di attribuzione Sampled Shapley 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 per importare un modello utilizzando la console Google Cloud . Quando arrivi al passaggio Spiegabilità, procedi nel seguente modo:

  1. Per il metodo di attribuzione delle funzionalità, seleziona Valore di Shapley campione (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 nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede più risorse di calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della caratteristica di input.

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

    2. (Facoltativo) Puoi aggiungere una o più baseline di input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita di valori tutti pari a zero, che è un'immagine nera per i dati immagine.

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

  5. Fai clic sul pulsante Importa dopo aver terminato di configurare le impostazioni di interpretabilità.

gcloud

  1. Scrivi il seguente 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 memorabile per la funzionalità di input.
    • OUTPUT_NAME: un nome memorabile per l'output del modello.

    Se specifichi baseline di input, assicurati che corrispondano all'input del modello, di solito un elenco di matrici bidimensionali. In caso contrario, il valore predefinito per la baseline di input è una matrice bidimensionale con valore 0 della forma di input.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. I flag più pertinenti per 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 informazioni sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

REST

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

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

Se specifichi baseline di input, assicurati che corrispondano all'input del modello, di solito un elenco di matrici bidimensionali. In caso contrario, il valore predefinito per la baseline di input è una matrice bidimensionale con 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 di queste 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 il tuo Model accetta dati tabulari come input e fornisce previsioni utilizzando un container personalizzato, puoi configurarlo per utilizzare il metodo di attribuzione Shapley campionata per le spiegazioni.

Determinare i nomi delle funzionalità e degli output

Nei passaggi successivi, devi fornire a Vertex AI i nomi delle funzionalità che il tuo Model prevede come input. Devi anche specificare la chiave utilizzata per gli output nelle previsioni di Model.

Determinare i nomi delle funzionalità

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

Ad esempio, considera un Model che prevede 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 caratteristiche.

Se il tuo Model prevede un input senza chiave, Vertex Explainable AI considera Model come una singola funzionalità. Puoi utilizzare qualsiasi stringa memorizzabile per il nome della funzionalità.

Ad esempio, considera un Model che prevede 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, ad esempio dimensions.

Determinare il nome dell'output

Se il tuo 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 ottieni 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 il tuo Model restituisce previsioni non associate a una chiave, puoi utilizzare qualsiasi stringa memorizzabile per il nome dell'output. Ad esempio, questo vale se il tuo 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 il Model, seleziona una delle seguenti schede:

Console

Segui la guida per importare un modello utilizzando la console Google Cloud . Quando arrivi al passaggio Spiegabilità, procedi nel seguente modo:

  1. Per il metodo di attribuzione delle funzionalità, seleziona Valore di Shapley campione (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 nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede più risorse di calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della caratteristica di input.

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

    2. (Facoltativo) Puoi aggiungere una o più baseline di input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita di valori tutti pari a zero, che è un'immagine nera per i dati immagine.

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

  5. Fai clic sul pulsante Importa dopo aver terminato di configurare le impostazioni di interpretabilità.

gcloud

  1. Scrivi il seguente 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.

    Puoi anche aggiungere input baselines a ExplanationMetadata. In caso contrario, Vertex AI sceglie le baseline di input per Model.

    Se specifichi baseline di input, assicurati che corrispondano all'input del modello, di solito un elenco di matrici bidimensionali. In caso contrario, il valore predefinito per la baseline di input è una matrice bidimensionale con valore 0 della forma di input.

  2. Esegui questo comando per creare una risorsa Model che supporti Vertex Explainable AI. I flag più pertinenti per 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 informazioni sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di 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 Sampled Shapley. Deve essere un numero intero compreso nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede più risorse di calcolo. 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 informazioni sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Puoi anche aggiungere input baselines a ExplanationMetadata. In caso contrario, Vertex AI sceglie le baseline 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 di queste 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