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

Quando e dove configurare le spiegazioni

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

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

Quando crei o importi un elemento Model, puoi impostare una configurazione predefinita per tutte le spiegazioni utilizzando il campo 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 in modo personalizzato utilizzando un TrainingPipeline, utilizza le impostazioni di configurazione descritte in questo documento nel campo modelToUpload di TrainingPipeline.

Configura le spiegazioni durante il deployment di modelli o quando ricevi 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 configurato in precedenza per le spiegazioni. Questo è utile se inizialmente non avevi intenzione di ricevere spiegazioni (e hai omesso il campo explanationSpec al momento della creazione del modello), ma decidi in un secondo momento che vuoi ricevere spiegazioni per il modello o se vuoi sostituire alcune impostazioni delle spiegazioni.
  • Disattiva le spiegazioni. Questo è utile se il modello è configurato per le spiegazioni, ma non prevedi di ricevere spiegazioni 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 su true.

Allo stesso modo, quando ricevi previsioni batch da un Model, puoi configurare le spiegazioni compilando il campo BatchPredictionJob.explanationSpec o disabilitare le spiegazioni impostando BatchPredictionJob.generateExplanation sufalse.

Esegui l'override della configurazione quando ricevi 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 del Model quando ricevi 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 eseguire l'override dei seguenti campi:

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

Importa un modello con un campo explanationSpec

A seconda che tu esegua le previsioni utilizzando un container predefinito o un container personalizzato, specifica dettagli leggermente diversi per ExplanationSpec. Seleziona la scheda corrispondente al contenitore che stai utilizzando:

Container predefinito TensorFlow

Puoi utilizzare uno dei seguenti metodi di attribuzione per Vertex Explainable AI. Leggi il confronto dei metodi di attribuzione delle caratteristiche 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 l'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di permutazioni 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ù elevato potrebbe ridurre l'errore di approssimazione, ma è più impegnativo a livello di calcolo. 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. Facoltativamente, puoi aggiungere una o più base di riferimento dell'input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita con valori tutti pari a zero, ovvero un'immagine nera per i dati delle immagini.

    3. Se importi un modello TensorFlow, esistono campi di immissione aggiuntivi:

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila i campi Nome tensore indici e/o Nome 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 non viene configurato, 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 della funzionalità.
    2. Imposta il Nome tensore di output della funzionalità.
    3. Se applicabile, imposta 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 configurato le impostazioni di spiegabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

    Scrivi il seguente codice ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo 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: qualsiasi 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, consulta Utilizzare 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, consulta Utilizzare TensorFlow con Vertex Explainable AI.

    Facoltativamente, puoi aggiungere base di riferimento dell'input a 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. 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:

    Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

REST

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

Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Facoltativamente, puoi aggiungere base di riferimento dell'input a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli 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:

arricciatura

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 l'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 il più appropriato per il tuo modello.

  2. Se importi un modello di classificazione delle immagini:

    1. Imposta Tipo di visualizzazione e Mappa colori.

    2. Puoi lasciare le impostazioni predefinite nei campi Clip in basso, Clip in alto, Tipo di overlay e Numero di passaggi integrali.

    Scopri di più sulle impostazioni di visualizzazione.

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

    Un valore più elevato potrebbe ridurre l'errore di approssimazione, ma è più impegnativo a livello di calcolo. Se non sai quale valore utilizzare, prova 50.

  4. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

    2. Facoltativamente, puoi aggiungere una o più base di riferimento dell'input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita con valori tutti pari a zero, ovvero un'immagine nera per i dati delle immagini.

    3. Se importi un modello TensorFlow, esistono campi di immissione aggiuntivi:

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila i campi Nome tensore indici e/o Nome 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 non viene configurato, 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 della funzionalità.
    2. Imposta il Nome tensore di output della funzionalità.
    3. Se applicabile, imposta 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 configurato le impostazioni di spiegabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

    Scrivi il seguente codice ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo 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: qualsiasi 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, consulta Utilizzare TensorFlow con Vertex Explainable AI.
    • MODALITY: image se Model accetta immagini come input oppure numeric se Model accetta dati tabulari come input. Il valore predefinito è numeric.

    • VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per scoprire come compilare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati delle immagini.

      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, consulta Utilizzare TensorFlow con Vertex Explainable AI.

    Facoltativamente, puoi aggiungere base di riferimento dell'input a 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. 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:

    Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

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

REST

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

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

    Un valore più elevato potrebbe ridurre l'errore di approssimazione, ma è più impegnativo a livello di calcolo. Se non sai quale valore utilizzare, prova 50.

  • FEATURE_NAME: qualsiasi 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, consulta Utilizzare TensorFlow con Vertex Explainable AI.
  • MODALITY: image se Model accetta immagini come input oppure numeric se Model accetta dati tabulari come input. Il valore predefinito è numeric.

  • VIZUALIZATION_OPTIONS: opzioni per visualizzare le spiegazioni. Per scoprire come compilare questo campo, consulta Configurazione delle impostazioni di visualizzazione per i dati delle immagini.

    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, consulta Utilizzare TensorFlow con Vertex Explainable AI.

Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Facoltativamente, puoi aggiungere base di riferimento dell'input a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli input per Model.

Facoltativamente, puoi aggiungere campi per configurare l'approssimazione di UniformGrad dei gradienti a 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:

arricciatura

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 l'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  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 predefinite nei campi Clip in basso, Clip in alto, Tipo di overlay e Numero di passaggi integrali.

      Scopri di più sulle impostazioni di visualizzazione.

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

    Un valore più elevato potrebbe ridurre l'errore di approssimazione, ma è più impegnativo a livello di calcolo. Se non sai quale valore utilizzare, prova 50.

  4. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

    2. Facoltativamente, puoi aggiungere una o più base di riferimento dell'input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita con valori tutti pari a zero, ovvero un'immagine nera per i dati delle immagini.

    3. Se importi un modello TensorFlow, esistono campi di immissione aggiuntivi:

      1. Compila il campo Nome tensore di input.

      2. Se applicabile, compila i campi Nome tensore indici e/o Nome 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 non viene configurato, 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 della funzionalità.
    2. Imposta il Nome tensore di output della funzionalità.
    3. Se applicabile, imposta 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 configurato le impostazioni di spiegabilità.

gcloud

  1. Per TensorFlow 2, ExplanationMetadata è facoltativo.

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

    Facoltativamente, puoi aggiungere base di riferimento dell'input a 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. 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:

    Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

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

REST

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

Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Facoltativamente, puoi aggiungere base di riferimento dell'input a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli input per Model.

Facoltativamente, puoi aggiungere campi per configurare l'approssimazione di UniformGrad dei gradienti a 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:

arricciatura

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 la previsione, 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 l'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di permutazioni 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ù elevato potrebbe ridurre l'errore di approssimazione, ma è più impegnativo a livello di calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

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

    2. Facoltativamente, puoi aggiungere una o più base di riferimento dell'input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita con valori tutti pari a zero, ovvero un'immagine nera per i dati delle immagini.

  4. Imposta il Nome output della funzionalità.

  5. Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.

gcloud

  1. Scrivi il seguente codice ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama 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 input.
    • OUTPUT_NAME: qualsiasi nome facile da ricordare per l'output del modello.

    Se specifichi le base di riferimento dell'input, 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 con valore 0 della forma di input.

  2. Esegui questo comando 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:

    Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

REST

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

Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Se specifichi le base di riferimento dell'input, 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 con valore 0 della forma di input.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

arricciatura

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.

Determinare i nomi di funzionalità e output

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

Determinare i nomi delle funzionalità

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

Ad esempio, considera un valore 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 di cui hai bisogno per i passaggi seguenti. Quando richiedi spiegazioni, Vertex Explainable AI fornisce attribuzioni per ogni elemento nidificato delle caratteristiche.

Se Model prevede un input senza chiave, Vertex Explainable AI considera Model come una singola caratteristica. Puoi utilizzare qualsiasi stringa facile da ricordare per il nome dell'elemento.

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

[
  <value>,
  <value>
]

In questo caso, fornisci a Vertex Explainable AI con il nome di una singola funzionalità a tua scelta, come dimensions.

Determinazione del nome dell'output

Se l'Model restituisce ogni istanza di previsione online con output con chiave, questa chiave sarà il nome di output.

Ad esempio, considera un valore Model che restituisca 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 funzionalità 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 offrono queste opzioni.

Se Model restituisce previsioni senza chiave, puoi utilizzare qualsiasi stringa facile da ricordare per il nome dell'output. Ad esempio, questo si applica se Model restituisce un array o uno scalare per ogni previsione.

Creazione del 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 l'importazione di un modello utilizzando la console Google Cloud. Quando arrivi al passaggio Spiegabilità:

  1. Per il metodo di attribuzione delle caratteristiche, seleziona Shapely campionato (per modelli tabulari).

  2. Imposta il conteggio dei percorsi sul numero di permutazioni 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ù elevato potrebbe ridurre l'errore di approssimazione, ma è più impegnativo a livello di calcolo. Se non sai quale valore utilizzare, prova 25.

  3. Configura ogni funzionalità di input nel modello:

    1. Inserisci il nome della funzionalità di input.

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

    2. Facoltativamente, puoi aggiungere una o più base di riferimento dell'input. In caso contrario, Vertex Explainable AI sceglie una base di input predefinita con valori tutti pari a zero, ovvero un'immagine nera per i dati delle immagini.

  4. Imposta il Nome output della funzionalità.

  5. Fai clic sul pulsante Importa dopo aver configurato le impostazioni di spiegabilità.

gcloud

  1. Scrivi il seguente codice ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo 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 "Determinazione dei nomi delle funzionalità" 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 dell'input a ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli input per Model.

    Se specifichi le base di riferimento dell'input, 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 con valore 0 della forma di input.

  2. Esegui questo comando 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:

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

    Un valore più elevato potrebbe ridurre l'errore di approssimazione, ma è più impegnativo a livello di calcolo. Se non sai quale valore utilizzare, prova 25.

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

Per scoprire i valori appropriati per gli altri segnaposto, consulta upload e Importazione di modelli.

Facoltativamente, puoi aggiungere base di riferimento dell'input a 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:

arricciatura

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

Passaggi successivi