Configura le spiegazioni basate sulle funzionalità

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 per un modello che hai già creato, anche se Non hai configurato le spiegazioni 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 tutti le sue spiegazioni utilizzando explanationSpec di Model .

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

In entrambi i casi, puoi configurare Model per supportare Vertex Explainable AI. Gli esempi in questo documento presuppongono che tu stia importando un 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. È utile se il tuo modello è configurato spiegazioni, ma non hai intenzione di riceverle dall'endpoint. A disabilita le spiegazioni quando esegui il deployment del modello in un endpoint, deseleziona le opzioni di spiegabilità nella console Cloud DeployedModel.disableExplanations a true.

Analogamente, quando ottieni previsioni batch da un Model, puoi configura le spiegazioni compilando il BatchPredictionJob.explanationSpec o disattiva le spiegazioni 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 ignorare 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 di visualizzazione per i modelli di immagine
  • ExplanationParameters ad eccezione di method

Sostituisci queste impostazioni nel campo explanationSpecOverride della richiesta di spiegazione.

Importare un modello con un campo explanationSpec

A seconda che tu pubblichi previsioni utilizzando un modello containerizzato o personalizzato container, specifica leggermente dettagli diversi per ExplanationSpec. Seleziona la scheda che corrisponde container 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 Model, seleziona una delle seguenti schede:

Console

Segui la guida all'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il tuo metodo di attribuzione delle caratteristiche, seleziona Forma fisica campionata (per i dati tabulari) modelli).

  2. Imposta il conteggio dei percorsi sul numero di caratteristiche permutazioni 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 calcolo più intensivo. 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. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita composta da valori tutti zero, che è un'immagine nera per i dati immagine.

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

      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 immagine.

      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 output dell'elemento.
    2. Imposta il Nome tensore di output della caratteristica.
    3. Se applicabile, imposta la mappatura del nome visualizzato dell'indice.
    4. Se applicabile, imposta la chiave di mappatura del nome visualizzato.

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

gcloud

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

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

    explanation-metadata.json

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

    Sostituisci quanto segue:

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

    Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli input per Model.

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

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

    Sostituisci quanto segue:

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

Se vuoi, puoi aggiungere base di riferimento ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli 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. ed esegui questo comando: 

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

PowerShell

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

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

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

Gradienti integrati

A seconda dello strumento che vuoi utilizzare per creare o importare 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 Spiegabilità:

  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 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 ottenere approssimativamente il l'integrale di percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo [1, 100].

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un calcolo più intensivo. 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. Se vuoi, puoi aggiungere uno o più input base di riferimento. 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 immissione:

      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 immagine.

      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 output dell'elemento.
    2. Imposta il Nome tensore di output della caratteristica.
    3. Se applicabile, imposta la mappatura del nome visualizzato dell'indice.
    4. Se applicabile, imposta la chiave di mappatura del nome visualizzato.

  6. Fai clic sul pulsante Importa dopo aver 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 esempio chiama il file explanation-metadata.json:

    explanation-metadata.json

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

    Sostituisci quanto segue:

    • FEATURE_NAME: un nome 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 apprendere come compilare questo campo, leggi Configurazione delle impostazioni di visualizzazione per l'immagine i tuoi dati.

      Se ometti il campo modality o imposti il campo modality su numeric: omettere del tutto il campo visualization.

    • 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 questo comando per creare una risorsa Model che supporti Vertex Explainable AI. Vengono evidenziati i flag più pertinenti a Vertex Explainable AI. 

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

    Sostituisci quanto segue:

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

    Facoltativamente, puoi aggiungere flag per configurare l'approssimazione smoothGrad di gradienti.

REST

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

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

Se vuoi, puoi aggiungere base di riferimento ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli 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 per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

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

  2. Imposta le seguenti opzioni di visualizzazione:

    1. Imposta la Mappa colori.

    2. Puoi lasciare i campi Clip sotto, Clip sopra, Tipo di overlay, e Numero di passaggi integrali secondo le impostazioni predefinite.

      Scopri di più sulle impostazioni di visualizzazione.

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

    Un valore più alto potrebbe ridurre l'errore di approssimazione, ma richiede un calcolo più intensivo. 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. 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 immissione:

      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 immagine.

      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 output dell'elemento.
    2. Imposta il Nome tensore di output della caratteristica.
    3. Se applicabile, imposta la mappatura del nome visualizzato dell'indice.
    4. Se applicabile, imposta la chiave di mappatura del nome visualizzato.

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

gcloud

  1. Per TensorFlow 2, il valore 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 base di riferimento ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli input per Model.

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

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

    Sostituisci quanto segue:

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

    Facoltativamente, puoi aggiungere flag per configurare l'approssimazione smoothGrad di gradienti.

REST

Prima di utilizzare i dati della richiesta, effettua 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. Altrimenti, Vertex AI sceglie le basi degli 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. ed esegui questo comando: 

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

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

Container predefiniti scikit-learn e XGBoost

Se Model accetta dati tabulari come input e fornisce previsioni utilizzando un un container scikit-learn o XGBoost predefinito previsione, puoi configurarla per utilizzare l'attribuzione di Shapley campionata per spiegazioni.

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

Console

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

  1. Per il tuo metodo di attribuzione delle caratteristiche, seleziona Forma fisica campionata (per i dati tabulari) modelli).

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

    Un valore più alto potrebbe ridurre di approssimazione, ma è più ad alta intensità di calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni caratteristica di input nel modello:

    1. Inserisci il nome della funzionalità di input.

      Se gli 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 spiegazione si ottiene un elenco dimensionale N di attribuzioni, dove N è vengono visualizzati il numero di caratteristiche nel modello e gli elementi nell'elenco nello stesso ordine del set di dati di addestramento.

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

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

  5. Al termine della configurazione, fai clic sul pulsante Importa le impostazioni di spiegabilità.

gcloud

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

    explanation-metadata.json

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

    Sostituisci quanto segue:

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

    Se specifichi basilari, assicurati che corrispondano l'input del modello, di solito un elenco di matrici 2-D. 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. Vengono evidenziati i flag più pertinenti a Vertex Explainable AI. 

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

    Sostituisci quanto segue:

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

REST

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

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

Se specifichi basilari, assicurati che corrispondano l'input del modello, di solito un elenco di matrici 2-D. 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. ed esegui questo comando: 

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

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

Container personalizzato

Se Model accetta dati tabulari come input e fornisce previsioni utilizzando un container personalizzato, puoi configurarlo per utilizzare l'attribuzione di Shapley campionata per spiegazioni.

Determinazione dei nomi delle funzionalità e dell'output

Nei passaggi seguenti, devi fornire a Vertex AI i nomi delle caratteristiche previste da Model come input. Devi anche specificare la chiave utilizzata per le uscite nelle previsioni di Model.

Determinazione dei nomi delle caratteristiche

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 valore Model che prevede che ogni istanza di input abbia 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 senza chiavi, 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 valore Model che prevede che ogni istanza di input abbia 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 previsione online di Compute Engine con con chiave, questa chiave sarà il nome dell'output.

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

{
  "scores": <value>
}

In questo caso, il nome dell'output è scores. Se il valore del campo scores è un array, quando ricevi 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 senza chiave, puoi utilizzare qualsiasi valore facile da ricordare per il nome dell'output. Ad esempio, questo vale se Model restituisce un array o un valore 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à:

  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 nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre di approssimazione, ma è più ad alta intensità di calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni caratteristica di input nel modello:

    1. Inserisci il nome della funzionalità di input.

      Se gli 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ù input base di riferimento. 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 esempio chiama il file 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 in "Determinazione del 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 basilari, assicurati che corrispondano l'input del modello, di solito un elenco di matrici 2-D. 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. Vengono evidenziati i flag più pertinenti a Vertex Explainable AI. 

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

    Sostituisci quanto segue:

    • 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 nell'intervallo [1, 50].

      Un valore più alto potrebbe ridurre di approssimazione, ma è più ad alta intensità di calcolo. Se non sai quale valore utilizzare, prova 25.

    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 elementi permutazioni da utilizzare il metodo di attribuzione di Shapley campionato. Deve essere un numero intero compreso nell'intervallo [1, 50].

    Un valore più alto potrebbe ridurre di approssimazione, ma è più ad alta intensità 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 in "Determinazione del nome dell'output" di questo documento.

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

Se vuoi, puoi aggiungere linee di base per l'input al ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli input per Model.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

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

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

PowerShell

Salva il corpo della richiesta in un file denominato request.json, 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