Configurazione delle spiegazioni

Per utilizzare Vertex Explainable AI con un modello con addestramento personalizzato, devi configurare determinate opzioni al momento della creazione della risorsa Model da cui vuoi 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 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

Puoi configurare 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.

Configura le spiegazioni quando crei o importi i modelli

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

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

• Importa un Model.
• Crea una risorsa TrainingPipeline personalizzata che importa un elemento Model.

In entrambi i casi, puoi configurare Model in modo che supporti Vertex Explainable AI. Gli esempi presenti 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 quando esegui il deployment dei modelli o ricevi previsioni batch

Quando esegui il deployment di una risorsa Model in una risorsa Endpoint, viene creata una DeployedModel. Puoi impostare una configurazione della spiegazione predefinita per un DeployedModel compilando il relativo campo explanationSpec. Puoi utilizzare questo passaggio per eseguire l'override del set di configurazione quando hai creato Model.

Allo stesso modo, quando ricevi previsioni batch da un Model e richiedi spiegazioni come parte della tua richiesta di previsione batch, puoi eseguire l'override di alcune o tutte le configurazioni della spiegazione di Model, completando il campo di BatchPredictionJob risorse

Queste opzioni sono utili se originariamente non hai intenzione di visualizzare le spiegazioni (un campo explanationSpec omesso quando hai creato il modello), ma in un secondo momento decidi di fornire le spiegazioni per il modello.

Sostituisci la configurazione quando ricevi spiegazioni online

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

Quando invii una richiesta explain a Vertex AI, puoi sostituire alcune delle configurazioni di spiegazione che hai impostato in precedenza per Model o DeployedModel.

Nella richiesta explain, puoi sostituire i seguenti campi:

• Inserisci le basi per qualsiasi modello addestrato personalizzato
• Configurazione della visualizzazione per i modelli di immagine
• ExplanationParameters tranne per method

Sostituisci queste impostazioni nel campo esplicativo della richiesta di spiegazione.

Importa un modello con un campo explanationSpec

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

Container predefinito TensorFlow

Per Vertex Explainable AI puoi utilizzare uno qualsiasi dei seguenti metodi di attribuzione. Consulta il confronto tra i metodi di attribuzione delle caratteristiche per selezionare quello appropriato per i tuoi elementi Model:

Gli esempi seguenti presuppongono che il modello accetti una singola caratteristica di input; spesso questo si applica ai modelli sequenziali Keras e a molti altri modelli TensorFlow. Poiché la funzione è un tensore di qualsiasi forma, può infatti codificare molte informazioni. Quando richiedi spiegazioni, Vertex Explainable AI fornisce le attribuzioni per ogni elemento del tensore.

Se il modello accetta più tensori di input denominati, aggiungi le voci corrispondenti al campo inputs.

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. Quando arrivi al passaggio Explainable, procedi nel seguente modo:

1. Per il metodo di attribuzione delle caratteristiche, seleziona Sampled Formly (per i modelli tabulari).

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

   Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. 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 input. In caso contrario, Vertex Explainable AI sceglie le basi degli input per il tuo modello.

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

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila il nome del tensore di indice e/o il nome del 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 di immagine.

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

      5. Se applicabile, imposta il campo Nome gruppo.

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

   1. Imposta il nome di output della funzionalità.
   2. Imposta il nome del tensore di output della funzionalità.
   3. Se applicabile, imposta la mappatura dei nomi visualizzati nell'indice.
   4. Se applicabile, imposta la chiave di mappatura dei nomi visualizzati.

5. Una volta completata la configurazione delle impostazioni, fai clic sul pulsante Importa.

gcloud

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

   • FEATURE_NAME: qualsiasi nome facile da ricordare per la funzionalità di immissione.
   • 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.
   • 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 linee di base di input a ExplanationMetadata. In caso contrario, Vertex AI sceglie basi di input per Model.

2. Esegui il comando seguente per creare una risorsa Model che supporti Vertex Explainable AI. Sono evidenziati i flag più pertinenti per 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:

   • IMAGE_URI: URI di un contenitore predefinito TensorFlow per le previsioni di pubblicazione.

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

     Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 25.

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

REST &CMD LINE

Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:

• IMAGE_URI: URI di un contenitore predefinito TensorFlow per le previsioni di pubblicazione.

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

  Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 25.

• FEATURE_NAME: qualsiasi nome facile da ricordare per la funzionalità di immissione.
• 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.
• 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 informazioni sui valori appropriati per gli altri segnaposto, consulta Importazione di modelli.

Facoltativamente, puoi aggiungere linee di base di input a ExplanationMetadata. In caso contrario, Vertex AI sceglie 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 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:

Curling

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

$cred = gcloud auth application-default 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. Quando arrivi al passaggio Explainable, 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, procedi nel seguente modo:

   1. Imposta Tipo di visualizzazione e Mappa colori.

   2. Puoi lasciare le impostazioni Clip sotto, Clip sopra, Tipo di overlay e Numero di passaggi fondamentali alle impostazioni predefinite.

   Scopri di più sulle impostazioni di visualizzazione.

3. Imposta il numero di passaggi da usare per approssimare l'integrale sul percorso durante l'attribuzione della funzionalità. Deve essere un numero intero compreso nell'intervallo [1, 100].

   Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. 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 input. In caso contrario, Vertex Explainable AI sceglie le basi degli input per il tuo modello.

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

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila il nome del tensore di indice e/o il nome del 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 di immagine.

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

      5. Se applicabile, imposta il campo Nome gruppo.

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

   1. Imposta il nome di output della funzionalità.
   2. Imposta il nome del tensore di output della funzionalità.
   3. Se applicabile, imposta la mappatura dei nomi visualizzati nell'indice.
   4. Se applicabile, imposta la chiave di mappatura dei nomi visualizzati.

6. Una volta completata la configurazione delle impostazioni, fai clic sul pulsante Importa.

gcloud

1. Scrivi quanto segue ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome file non è importante, ma per questo esempio richiama 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: qualsiasi nome facile da ricordare per la funzionalità di immissione.
   • 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 completare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati 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 linee di base di input a ExplanationMetadata. In caso contrario, Vertex AI sceglie basi di input per Model.

2. Esegui il comando seguente per creare una risorsa Model che supporti Vertex Explainable AI. Sono evidenziati i flag più pertinenti per 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:

   • IMAGE_URI: URI di un contenitore predefinito TensorFlow per le previsioni di pubblicazione.
   • STEP_COUNT: il numero di passaggi da eseguire per approssimare l'integrazione del percorso durante l'attribuzione della funzionalità. Deve essere un numero intero compreso nell'intervallo [1, 100].

     Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 50.

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

   Se vuoi, puoi aggiungere flag per configurare l'approssimazione di gradienti FluidGrad.

REST &CMD LINE

Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:

• IMAGE_URI: URI di un contenitore predefinito TensorFlow per le previsioni di pubblicazione.
• STEP_COUNT: il numero di passaggi da eseguire per approssimare l'integrazione del percorso durante l'attribuzione della funzionalità. Deve essere un numero intero compreso nell'intervallo [1, 100].

  Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 50.

• FEATURE_NAME: qualsiasi nome facile da ricordare per la funzionalità di immissione.
• 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 completare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati 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 informazioni sui valori appropriati per gli altri segnaposto, consulta Importazione di modelli.

Facoltativamente, puoi aggiungere linee di base di input a ExplanationMetadata. In caso contrario, Vertex AI sceglie basi di input per Model.

Se vuoi, puoi aggiungere campi per configurare l'approssimazione dei gradienti FluidGrad in ExplanationParameters.

Metodo HTTP e URL:

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

Corpo JSON 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:

Curling

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

$cred = gcloud auth application-default 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. Quando arrivi al passaggio Explainable, procedi nel seguente modo:

1. Come 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 Clip sotto, Clip sopra, Tipo di overlay e Numero di passaggi fondamentali alle impostazioni predefinite.

      Scopri di più sulle impostazioni di visualizzazione.

3. Imposta il numero di passaggi da usare per approssimare l'integrale sul percorso durante l'attribuzione della funzionalità. Deve essere un numero intero compreso nell'intervallo [1, 100].

   Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. 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 input. In caso contrario, Vertex Explainable AI sceglie le basi degli input per il tuo modello.

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

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila il nome del tensore di indice e/o il nome del 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 di immagine.

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

      5. Se applicabile, imposta il campo Nome gruppo.

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

   1. Imposta il nome di output della funzionalità.
   2. Imposta il nome del tensore di output della funzionalità.
   3. Se applicabile, imposta la mappatura dei nomi visualizzati nell'indice.
   4. Se applicabile, imposta la chiave di mappatura dei nomi visualizzati.

6. Una volta completata la configurazione delle impostazioni, fai clic sul pulsante Importa.

gcloud

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

   • FEATURE_NAME: qualsiasi nome facile da ricordare per la funzionalità di immissione.
   • 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.
   • VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per informazioni su come completare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati immagine.
   • 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 linee di base di input a ExplanationMetadata. In caso contrario, Vertex AI sceglie basi di input per Model.

2. Esegui il comando seguente per creare una risorsa Model che supporti Vertex Explainable AI. Sono evidenziati i flag più pertinenti per 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:

   • IMAGE_URI: URI di un contenitore predefinito TensorFlow per le previsioni di pubblicazione.
   • STEP_COUNT: il numero di passaggi da eseguire per approssimare l'integrazione del percorso durante l'attribuzione della funzionalità. Deve essere un numero intero compreso nell'intervallo [1, 100].

     Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 50.

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

   Se vuoi, puoi aggiungere flag per configurare l'approssimazione di gradienti FluidGrad.

REST &CMD LINE

Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:

• IMAGE_URI: URI di un contenitore predefinito TensorFlow per le previsioni di pubblicazione.
• STEP_COUNT: il numero di passaggi da eseguire per approssimare l'integrazione del percorso durante l'attribuzione della funzionalità. Deve essere un numero intero compreso nell'intervallo [1, 100].

  Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 50.

• FEATURE_NAME: qualsiasi nome facile da ricordare per la funzionalità di immissione.
• 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.
• VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per informazioni su come completare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati immagine.
• 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 informazioni sui valori appropriati per gli altri segnaposto, consulta Importazione di modelli.

Facoltativamente, puoi aggiungere linee di base di input a ExplanationMetadata. In caso contrario, Vertex AI sceglie basi di input per Model.

Se vuoi, puoi aggiungere campi per configurare l'approssimazione dei gradienti FluidGrad in ExplanationParameters.

Metodo HTTP e URL:

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

Corpo JSON 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:

Curling

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

$cred = gcloud auth application-default 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 il tuo Model accetta dati tabulari come input e fornisce previsioni utilizzando un container scikit-learn o XGBoost predefinito per la previsione, puoi configurarlo per utilizzare il metodo di attribuzione Shapley campionato per le spiegazioni.

I seguenti esempi presuppongono che il tuo modello accetti una singola matrice 2-D come input; questo è spesso il caso dei modelli scikit-learn e XGBoost. Quando richiedi spiegazioni, Vertex Explainable AI fornisce attribuzioni per ogni elemento della matrice di input.

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. Quando arrivi al passaggio Explainable, procedi nel seguente modo:

1. Per il metodo di attribuzione delle caratteristiche, seleziona Sampled Formly (per i modelli tabulari).

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

   Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. 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 input. In caso contrario, Vertex Explainable AI sceglie le basi degli input per il tuo modello.

4. Imposta il nome di output della funzionalità.

5. Una volta completata la configurazione delle impostazioni, fai clic sul pulsante Importa.

gcloud

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

   explanation-metadata.json

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

   Sostituisci quanto segue:

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

   Se specifichi 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 base di input è una matrice 2-D di valore 0 della forma di input.

2. Esegui il comando seguente per creare una risorsa Model che supporti Vertex Explainable AI. Sono evidenziati i flag più pertinenti per 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:

   • IMAGE_URI: URI di un container predefinito per la pubblicazione delle previsioni.

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

     Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 25.

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

REST &CMD LINE

Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:

• IMAGE_URI: URI di un container predefinito per la pubblicazione delle previsioni.

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

  Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 25.

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

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

Se specifichi 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 base di input è una matrice 2-D di 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 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:

Curling

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

$cred = gcloud auth application-default 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

Contenitore 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 campionato per le spiegazioni.

Nota: le seguenti istruzioni non funzionano se utilizzi uno dei container predefiniti di Vertex AI per gestire le previsioni. Devi utilizzare un'immagine container personalizzata non gestita da Vertex AI e che soddisfa i requisiti dei container personalizzati.

Determinazione dei nomi delle funzionalità e degli output in corso...

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

Determinazione dei nomi delle funzionalità in corso...

Se l'elemento Model prevede che ogni istanza di input abbia determinate chiavi di primo livello, queste sono i nomi delle tue 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 seguenti passaggi. Quando richiedi spiegazioni, Vertex Explainable AI fornisce attribuzioni per ogni elemento nidificato delle funzionalità.

Se il tuo Model prevede un input senza chiave, Vertex Explainable AI considera che Model ha una singola funzionalità. Puoi usare qualsiasi stringa facile da ricordare 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à, ad esempio dimensions.

Nota: i seguenti esempi presuppongono che il tuo modello abbia una singola caratteristica di input. Se il tuo modello ha più caratteristiche, come descritto in questa sezione, aggiungi le voci corrispondenti al campo inputs.

Determinazione del nome di output in corso...

Se Model restituisce ogni istanza di previsione online con un output con chiave, la chiave è il tuo nome di output.

Ad esempio, prendi in considerazione 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 vengono visualizzate 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 per 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 l'elemento Model restituisce previsioni non chiave, puoi utilizzare qualsiasi stringa memorizzabile per il nome dell'output. Ad esempio, questo vale se il tuo Model restituisce un array o un 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. Quando arrivi al passaggio Explainable, procedi nel seguente modo:

1. Per il metodo di attribuzione delle caratteristiche, seleziona Sampled Formly (per i modelli tabulari).

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

   Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. 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 input. In caso contrario, Vertex Explainable AI sceglie le basi degli input per il tuo modello.

4. Imposta il nome di output della funzionalità.

5. Una volta completata la configurazione delle impostazioni, fai clic sul pulsante Importa.

gcloud

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

   explanation-metadata.json

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

   Sostituisci quanto segue:

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

   Facoltativamente, puoi aggiungere linee di base di input a ExplanationMetadata. In caso contrario, Vertex AI sceglie basi di input per Model.

   Se specifichi 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 base di input è una matrice 2-D di valore 0 della forma di input.

2. Esegui il comando seguente per creare una risorsa Model che supporti Vertex Explainable AI. Sono evidenziati i flag più pertinenti per 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:

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

     Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 25.

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

REST &CMD LINE

Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:

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

  Un valore più alto potrebbe ridurre l'errore di approssimazione, ma è più gravoso dal punto di vista computazionale. Se non sai quale valore utilizzare, prova 25.

• FEATURE_NAME: il nome dell'elemento, come descritto nella sezione "Determinare i nomi delle caratteristiche" 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 Importazione di modelli.

Facoltativamente, puoi aggiungere linee di base di input a ExplanationMetadata. In caso contrario, Vertex AI sceglie 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 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:

Curling

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

$cred = gcloud auth application-default 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

• Esegui il deployment del tuo Model in un Endpoint e visualizza le spiegazioni.