Per utilizzare Vertex Explainable AI con un modello con addestramento personalizzato, devi configurare determinate opzioni quando crei la risorsa Model
da cui prevedi di richiedere spiegazioni, quando esegui il deployment del modello o quando invii un job di spiegazione batch. In questa pagina viene descritta la configurazione di queste opzioni.
Se vuoi utilizzare Vertex Explainable AI con un modello tabulare AutoML, non devi eseguire nessuna configurazione: Vertex AI configura automaticamente il modello per Vertex Explainable AI. Salta questo documento e leggi Recupero delle spiegazioni.
Quando e dove configurare le spiegazioni
Le spiegazioni vengono configurate durante la creazione o l'importazione di un modello. Puoi anche configurare le spiegazioni su un modello che hai già creato, anche se non li hai configurati in precedenza.
Configura le spiegazioni durante la creazione o l'importazione dei modelli
Quando crei o importi un Model
, puoi impostare una configurazione predefinita per tutte le relative spiegazioni utilizzando il campo explanationSpec
di Model
.
Puoi creare un Model
con addestramento personalizzato in Vertex AI nei
seguenti modi:
- Importa o registra un
Model
in Vertex AI Model Registry - Crea una risorsa
TrainingPipeline
personalizzata che importi unModel
. - Crea un modello BigQuery ML e specifica
l'impostazione facoltativa
model_registry
nella sintassiCREATE MODEL
. Questa impostazione registra automaticamente il modello in Vertex AI Model Registry e configura il suoexplanationSpec
.
In entrambi i casi, puoi configurare Model
per supportare Vertex Explainable AI. Gli esempi in questo documento presuppongono che tu stia importando un elemento Model
. Per configurare Vertex Explainable AI quando crei un elemento Model
con addestramento personalizzato utilizzando un TrainingPipeline
, utilizza le impostazioni di configurazione descritte in questo documento nel campo modelToUpload
di TrainingPipeline
.
Configura le spiegazioni per il deployment di modelli o l'acquisizione di previsioni batch
Quando esegui il deployment di un Model
in una risorsa Endpoint
, puoi:
- Configura le spiegazioni, indipendentemente dal fatto che il modello sia stato precedentemente
configurato per le spiegazioni. Ciò è utile se all'inizio non avevi intenzione di
ottenere spiegazioni (e hai omesso il campo
explanationSpec
durante la creazione del modello), ma in un secondo momento decidi di volere spiegazioni per il modello o se vuoi sostituire alcune delle impostazioni di spiegazione. - Disattiva le spiegazioni. Ciò è utile se il modello è configurato per
le spiegazioni, ma non prevedi di riceverle dall'endpoint. Per disabilitare le spiegazioni quando esegui il deployment del modello in un endpoint, deseleziona le opzioni di spiegabilità nella console Cloud o imposta
DeployedModel.disableExplanations
sutrue
.
Analogamente, quando ottieni previsioni batch da un
Model
, puoi
configurare le spiegazioni compilando il campo
BatchPredictionJob.explanationSpec
o disabilitarle impostando BatchPredictionJob.generateExplanation
su
false
.
Sostituisci la configurazione per ricevere spiegazioni online
Indipendentemente dal fatto che tu abbia creato o importato Model
con le impostazioni di spiegazione e che tu abbia configurato le impostazioni di spiegazione durante il deployment, puoi eseguire l'override delle impostazioni di spiegazione iniziali di Model
quando ricevi le spiegazioni online.
Quando invii una richiesta explain
a
Vertex AI, puoi sostituire parte della configurazione della spiegazione
impostata in precedenza per Model
o DeployedModel
.
Nella richiesta explain
, puoi eseguire l'override dei seguenti campi:
- Basi di input per qualsiasi modello con addestramento personalizzato
- Configurazione di visualizzazione per i modelli di immagine
ExplanationParameters
trannemethod
Sostituisci queste impostazioni nel campo explanationSpecOverride della richiesta di spiegazione.
Importa un modello con un campo explanationSpec
A seconda che tu esegua previsioni utilizzando un container predefinito o un container personalizzato, specifica dettagli leggermente diversi per ExplanationSpec
. Seleziona la scheda che corrisponde al
contenitore che stai utilizzando:
Container predefinito TensorFlow
Puoi utilizzare uno qualsiasi dei seguenti metodi di attribuzione per Vertex Explainable AI. Leggi il confronto dei metodi di attribuzione delle funzionalità per selezionare quello appropriato per Model
:
Valore di Shapley campionato
A seconda dello strumento che vuoi utilizzare per creare o importare Model
, seleziona una delle seguenti schede:
Console
Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:
Per il tuo metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per i modelli tabulari).
Imposta il conteggio dei percorsi sul numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
.Configura ogni caratteristica di input nel modello:
-
Inserisci il nome della funzionalità di input.
-
Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.
-
Se importi un modello TensorFlow, sono disponibili altri campi di immissione:
Compila il campo Nome tensore di input.
Se applicabile, inserisci il Nome tensore indici e/o il Nome tensore di forma denso.
La modalità non può essere aggiornata qui. Viene impostato automaticamente su
NUMERIC
per i modelli tabulari o suIMAGE
per i modelli immagine.Se applicabile, imposta il campo Codifica. Se non è configurato, il valore predefinito è
IDENTITY
.Se applicabile, imposta il campo Nome gruppo.
-
Se importi un modello TensorFlow, specifica i campi di output:
- Imposta il Nome output dell'elemento.
- Imposta il Nome tensore di output della caratteristica.
- Se applicabile, imposta la Mappatura del nome visualizzato dell'indice.
- Se applicabile, imposta la Chiave di mappatura del nome visualizzato.
Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.
gcloud
Per TensorFlow 2, il valore
ExplanationMetadata
è facoltativo.Scrivi il codice
ExplanationMetadata
seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il fileexplanation-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 memorabile per l'elemento di input.
- INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
- OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
- OUTPUT_TENSOR_NAME: il nome del tensore di output in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
Facoltativamente, puoi aggiungere base di riferimento a
ExplanationMetadata
. Altrimenti, Vertex AI sceglie le basi di input perModel
.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:
- IMAGE_URI: l'URI di un container predefinito di TensorFlow per la distribuzione delle previsioni.
-
PATH_COUNT: il numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione di Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- IMAGE_URI: l'URI di un container predefinito di TensorFlow per la distribuzione delle previsioni.
-
PATH_COUNT: il numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione di Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
. - FEATURE_NAME: un nome memorabile per l'elemento di input.
- INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
- OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
- OUTPUT_TENSOR_NAME: il nome del tensore di output in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.
Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata
. Altrimenti, Vertex AI sceglie le basi di input
per Model
.
Per i modelli TensorFlow 2, il campo metadata
è facoltativo. Se omesso, Vertex AI deduce automaticamente inputs
e outputs
dal modello.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
Corpo JSON della richiesta:
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "sampledShapleyAttribution": { "pathCount": PATH_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } } } } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content
Gradienti integrati
A seconda dello strumento che vuoi utilizzare per creare o importare Model
, seleziona una delle seguenti schede:
Console
Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:
Per il tuo metodo di attribuzione delle caratteristiche, seleziona Gradi integrati (per i modelli tabulari) o Gradi integrati (per i modelli di classificazione delle immagini), a seconda di quale è più appropriato per il tuo modello.
Se importi un modello di classificazione delle immagini, segui questi passaggi:
Imposta il Tipo di visualizzazione e la Mappa colori.
Puoi lasciare le impostazioni predefinite per Clip qui sotto, Clip sopra, Tipo di overlay e Numero di passaggi integrali.
Scopri di più sulle impostazioni di visualizzazione.
Imposta il numero di passaggi da utilizzare per l'approssimazione dell'integrale del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo
[1, 100]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
50
.Configura ogni caratteristica di input nel modello:
-
Inserisci il nome della funzionalità di input.
-
Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.
-
Se importi un modello TensorFlow, sono disponibili altri campi di immissione:
Compila il campo Nome tensore di input.
Se applicabile, inserisci il Nome tensore indici e/o il Nome tensore di forma denso.
La modalità non può essere aggiornata qui. Viene impostato automaticamente su
NUMERIC
per i modelli tabulari o suIMAGE
per i modelli immagine.Se applicabile, imposta il campo Codifica. Se non è configurato, il valore predefinito è
IDENTITY
.Se applicabile, imposta il campo Nome gruppo.
-
Se importi un modello TensorFlow, specifica i campi di output:
- Imposta il Nome output dell'elemento.
- Imposta il Nome tensore di output della caratteristica.
- Se applicabile, imposta la Mappatura del nome visualizzato dell'indice.
- Se applicabile, imposta la Chiave di mappatura del nome visualizzato.
Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.
gcloud
Per TensorFlow 2, il valore
ExplanationMetadata
è facoltativo.Scrivi il codice
ExplanationMetadata
seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il fileexplanation-metadata.json
:explanation-metadata.json
{ "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", "modality": "MODALITY", "visualization": VISUALIZATION_SETTINGS } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } }
Sostituisci quanto segue:
- FEATURE_NAME: un nome memorabile per l'elemento di input.
- INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
-
MODALITY:
image
seModel
accetta immagini come input onumeric
seModel
accetta dati tabulari come input. Il valore predefinito ènumeric
. -
VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per informazioni su come compilare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati di immagine.
Se ometti il campo
modality
o imposti il campomodality
sunumeric
, ometti completamente il campovisualization
. - OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
- OUTPUT_TENSOR_NAME: il nome del tensore di output in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
Facoltativamente, puoi aggiungere base di riferimento a
ExplanationMetadata
. Altrimenti, Vertex AI sceglie le basi di input perModel
.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:
- IMAGE_URI: l'URI di un container predefinito di TensorFlow per la distribuzione delle previsioni.
-
STEP_COUNT: il numero di passaggi da utilizzare per l'approssimazione dell'integrazione del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo
[1, 100]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
50
.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.Facoltativamente, puoi aggiungere flag per configurare l'approssimazione dei gradienti in gradiente.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- IMAGE_URI: l'URI di un container predefinito di TensorFlow per la distribuzione delle previsioni.
-
STEP_COUNT: il numero di passaggi da utilizzare per l'approssimazione dell'integrazione del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo
[1, 100]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
50
. - FEATURE_NAME: un nome memorabile per l'elemento di input.
- INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
-
MODALITY:
image
seModel
accetta immagini come input onumeric
seModel
accetta dati tabulari come input. Il valore predefinito ènumeric
. -
VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per informazioni su come compilare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati di immagine.
Se ometti il campo
modality
o imposti il campomodality
sunumeric
, ometti completamente il campovisualization
. - OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
- OUTPUT_TENSOR_NAME: il nome del tensore di output in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.
Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata
. Altrimenti, Vertex AI sceglie le basi di input
per Model
.
In via facoltativa, puoi aggiungere campi per configurare l'approssimazione dei gradienti in gradiente in ExplanationParameters
.
Per i modelli TensorFlow 2, il campo metadata
è facoltativo. Se omesso, Vertex AI deduce automaticamente inputs
e outputs
dal modello.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
Corpo JSON della richiesta:
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "integratedGradientsAttribution": { "stepCount": STEP_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", "modality": "MODALITY", "visualization": VISUALIZATION_SETTINGS } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } } } } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content
XRAI
A seconda dello strumento che vuoi utilizzare per creare o importare Model
, seleziona una delle seguenti schede:
Console
Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:
Per il tuo metodo di attribuzione delle caratteristiche, seleziona XRAI (per i modelli di classificazione delle immagini).
Imposta le seguenti opzioni di visualizzazione:
Imposta la Mappa colori.
Puoi lasciare le impostazioni predefinite per Clip qui sotto, Clip sopra, Tipo di overlay e Numero di passaggi integrali.
Scopri di più sulle impostazioni di visualizzazione.
Imposta il numero di passaggi da utilizzare per l'approssimazione dell'integrale del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo
[1, 100]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
50
.Configura ogni caratteristica di input nel modello:
-
Inserisci il nome della funzionalità di input.
-
Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.
-
Se importi un modello TensorFlow, sono disponibili altri campi di immissione:
Compila il campo Nome tensore di input.
Se applicabile, inserisci il Nome tensore indici e/o il Nome tensore di forma denso.
La modalità non può essere aggiornata qui. Viene impostato automaticamente su
NUMERIC
per i modelli tabulari o suIMAGE
per i modelli immagine.Se applicabile, imposta il campo Codifica. Se non è configurato, il valore predefinito è
IDENTITY
.Se applicabile, imposta il campo Nome gruppo.
-
Se importi un modello TensorFlow, specifica i campi di output:
- Imposta il Nome output dell'elemento.
- Imposta il Nome tensore di output della caratteristica.
- Se applicabile, imposta la Mappatura del nome visualizzato dell'indice.
- Se applicabile, imposta la Chiave di mappatura del nome visualizzato.
Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.
gcloud
Per TensorFlow 2, il valore
ExplanationMetadata
è facoltativo.Scrivi il codice
ExplanationMetadata
seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il fileexplanation-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: un nome memorabile per l'elemento di input.
- INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
- VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per informazioni su come compilare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati di immagine.
- OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
- OUTPUT_TENSOR_NAME: il nome del tensore di output in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
Facoltativamente, puoi aggiungere base di riferimento a
ExplanationMetadata
. Altrimenti, Vertex AI sceglie le basi di input perModel
.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:
- IMAGE_URI: l'URI di un container predefinito di TensorFlow per la distribuzione delle previsioni.
-
STEP_COUNT: il numero di passaggi da utilizzare per l'approssimazione dell'integrazione del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo
[1, 100]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
50
.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.Facoltativamente, puoi aggiungere flag per configurare l'approssimazione dei gradienti in gradiente.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- IMAGE_URI: l'URI di un container predefinito di TensorFlow per la distribuzione delle previsioni.
-
STEP_COUNT: il numero di passaggi da utilizzare per l'approssimazione dell'integrazione del percorso durante l'attribuzione delle caratteristiche. Deve essere un numero intero compreso nell'intervallo
[1, 100]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
50
. - FEATURE_NAME: un nome memorabile per l'elemento di input.
- INPUT_TENSOR_NAME: il nome del tensore di input in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
- VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per informazioni su come compilare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati di immagine.
- OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
- OUTPUT_TENSOR_NAME: il nome del tensore di output in TensorFlow. Per trovare il valore corretto per questo campo, leggi Utilizzo di TensorFlow con Vertex Explainable AI.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.
Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata
. Altrimenti, Vertex AI sceglie le basi di input
per Model
.
In via facoltativa, puoi aggiungere campi per configurare l'approssimazione dei gradienti in gradiente in ExplanationParameters
.
Per i modelli TensorFlow 2, il campo metadata
è facoltativo. Se omesso, Vertex AI deduce automaticamente inputs
e outputs
dal modello.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
Corpo JSON della richiesta:
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "xraiAttribution": { "stepCount": STEP_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", "modality": "image", "visualization": VISUALIZATION_SETTINGS } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } } } } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content
Container predefiniti scikit-learn e XGBoost
Se Model
accetta dati tabulari come input e fornisce previsioni utilizzando un container scikit-learn o XGBoost predefinito per le previsioni, puoi configurarlo in modo che utilizzi il metodo di attribuzione Shapley campionato per le spiegazioni.
A seconda dello strumento che vuoi utilizzare per creare o importare Model
, seleziona una delle seguenti schede:
Console
Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:
Per il tuo metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per i modelli tabulari).
Imposta il conteggio dei percorsi sul numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
.Configura ogni caratteristica di input nel modello:
Inserisci il nome della funzionalità di input.
Se gli artefatti del modello non includono nomi delle caratteristiche, Vertex AI non è in grado di mappare i nomi delle caratteristiche di input specificate al modello. In questo caso, devi fornire una sola caratteristica di input con un qualsiasi nome arbitrario facile per l'utente, come
input_features
. Nella risposta di spiegazione, otterrai un elenco dimensionale N di attribuzioni, dove N è il numero di caratteristiche nel modello e gli elementi nell'elenco vengono visualizzati nello stesso ordine del set di dati di addestramento.Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.
Imposta il Nome output dell'elemento.
Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.
gcloud
Scrivi il codice
ExplanationMetadata
seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il fileexplanation-metadata.json
:explanation-metadata.json
{ "inputs": { "FEATURE_NAME": { } }, "outputs": { "OUTPUT_NAME": { } } }
Sostituisci quanto segue:
- FEATURE_NAME: un nome memorabile per l'elemento di input.
- OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
Se specifichi le base di riferimento, assicurati che corrispondano all'input del modello, in genere un elenco di matrici 2-D. In caso contrario, il valore predefinito per la base di input è una matrice 2D del valore 0 della forma di input.
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:
- IMAGE_URI: l'URI di un container predefinito per la pubblicazione delle previsioni.
-
PATH_COUNT: il numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione di Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- IMAGE_URI: l'URI di un container predefinito per la pubblicazione delle previsioni.
-
PATH_COUNT: il numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione di Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
. - FEATURE_NAME: un nome memorabile per l'elemento di input.
- OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.
Se specifichi le base di riferimento, assicurati che corrispondano all'input del modello, in genere un elenco di matrici 2-D. In caso contrario, il valore predefinito per la base di input è una matrice 2D del valore 0 della forma di input.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
Corpo JSON della richiesta:
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "sampledShapleyAttribution": { "pathCount": PATH_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": { } }, "outputs": { "OUTPUT_NAME": { } } } } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content
Container personalizzato
Se Model
accetta dati tabulari come input e fornisce previsioni utilizzando un container personalizzato, puoi configurarlo in modo che utilizzi il metodo di attribuzione Shapley campionato per le spiegazioni.
Determinazione dei nomi delle caratteristiche e degli output
Nei passaggi seguenti, devi fornire a Vertex AI i nomi
delle caratteristiche che Model
prevede come input. Devi anche specificare la chiave utilizzata per gli output nelle previsioni del Model
.
Determinazione dei nomi delle caratteristiche
Se Model
prevede che ogni istanza di input abbia determinate chiavi di primo livello, quelle chiavi saranno i nomi delle tue caratteristiche.
Ad esempio, considera un valore Model
che prevede che ogni istanza di input abbia il formato seguente:
{
"length": <value>,
"width": <value>
}
In questo caso, i nomi delle caratteristiche sono length
e width
. Anche se i valori di questi campi contengono elenchi o oggetti nidificati, length
e width
sono le uniche chiavi necessarie per i passaggi successivi. Quando richiedi le spiegazioni, Vertex Explainable AI fornisce le attribuzioni per ogni elemento nidificato delle tue caratteristiche.
Se Model
prevede un input senza chiave, Vertex Explainable AI considera Model
una singola caratteristica. Puoi utilizzare qualsiasi stringa facile da ricordare per il nome della caratteristica.
Ad esempio, considera un valore Model
che prevede che ogni istanza di input abbia il formato seguente:
[
<value>,
<value>
]
In questo caso, fornisci a Vertex Explainable AI con un nome di funzionalità a tua scelta,
ad esempio dimensions
.
Determinazione del nome dell'output
Se Model
restituisce ogni istanza di previsione online con output con chiave, questa chiave corrisponde al nome dell'output.
Ad esempio, considera un valore Model
che restituisce ogni previsione nel seguente formato:
{
"scores": <value>
}
In questo caso, il nome dell'output è scores
. Se il valore del campo scores
è un array, quando ricevi spiegazioni, Vertex Explainable AI restituisce le attribuzioni delle caratteristiche per l'elemento con il valore più alto in ogni previsione. Per configurare Vertex Explainable AI in modo da fornire attribuzioni delle caratteristiche per elementi aggiuntivi del campo di output, puoi specificare i campi topK
o outputIndices
di ExplanationParameters
.
Tuttavia, gli esempi in questo documento non dimostrano queste opzioni.
Se Model
restituisce previsioni senza chiave, puoi utilizzare qualsiasi stringa facile da ricordare per il nome dell'output. Ad esempio, questo vale se Model
restituisce un array o uno scalare per ogni previsione.
Creazione di Model
in corso...
A seconda dello strumento che vuoi utilizzare per creare o importare Model
, seleziona una delle seguenti schede:
Console
Segui la guida per importare un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:
Per il tuo metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per i modelli tabulari).
Imposta il conteggio dei percorsi sul numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
.Configura ogni caratteristica di input nel modello:
Inserisci il nome della funzionalità di input.
Se gli artefatti del modello non includono nomi delle caratteristiche, Vertex AI non è in grado di mappare i nomi delle caratteristiche di input specificate al modello. In questo caso, devi fornire una sola caratteristica di input con un qualsiasi nome arbitrario facile per l'utente, come
input_features
. Nella risposta di spiegazione, otterrai un elenco dimensionale N di attribuzioni, dove N è il numero di caratteristiche nel modello e gli elementi nell'elenco vengono visualizzati nello stesso ordine del set di dati di addestramento.Facoltativamente, puoi aggiungere una o più base di riferimento. Altrimenti, Vertex Explainable AI sceglie una base di input predefinita di valori tutti zero, che è un'immagine nera per i dati di immagine.
Imposta il Nome output dell'elemento.
Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.
gcloud
Scrivi il codice
ExplanationMetadata
seguente in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il fileexplanation-metadata.json
:explanation-metadata.json
{ "inputs": { "FEATURE_NAME": {} }, "outputs": { "OUTPUT_NAME": {} } }
Sostituisci quanto segue:
- FEATURE_NAME: il nome della caratteristica, come descritto nella sezione "Determinazione dei nomi delle caratteristiche" di questo documento.
- OUTPUT_NAME: il nome dell'output, come descritto nella sezione "Determinazione del nome dell'output" di questo documento.
Facoltativamente, puoi aggiungere base di riferimento a
ExplanationMetadata
. Altrimenti, Vertex AI sceglie le basi di input perModel
.Se specifichi le base di riferimento, assicurati che corrispondano all'input del modello, in genere un elenco di matrici 2-D. In caso contrario, il valore predefinito per la base di input è una matrice 2D del valore 0 della forma di input.
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:
-
PATH_COUNT: il numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione di Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.-
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
-
PATH_COUNT: il numero di modifiche delle caratteristiche da utilizzare per il metodo di attribuzione di Shapley campionato. Deve essere un numero intero compreso nell'intervallo
[1, 50]
.Un valore più alto potrebbe ridurre l'errore approssimativo, ma è più intensivo dal punto di vista del calcolo. Se non sai quale valore utilizzare, prova
25
. - FEATURE_NAME: il nome della caratteristica, come descritto nella sezione "Determinazione dei nomi delle caratteristiche" di questo documento.
- OUTPUT_NAME: il nome dell'output, come descritto nella sezione "Determinazione del nome dell'output" di questo documento.
Per scoprire di più sui valori appropriati per gli altri segnaposto, consulta
upload
e Importazione di modelli.
Facoltativamente, puoi aggiungere base di riferimento a ExplanationMetadata
. Altrimenti, Vertex AI sceglie le basi di input
per Model
.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
Corpo JSON della richiesta:
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "sampledShapleyAttribution": { "pathCount": PATH_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": {} }, "outputs": { "OUTPUT_NAME": {} } } } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content