Configura le spiegazioni basate sulle funzionalità

Per utilizzare Vertex Explainable AI con un modello con addestramento personalizzato, devi configurare opzioni quando crei la risorsa Model che prevedi di richiedere le spiegazioni, quando esegui il deployment del modello o quando invii un job di spiegazione. In questa pagina viene descritta la configurazione di queste opzioni.

Se vuoi utilizzare Vertex Explainable AI con un modello tabulare AutoML, non dovrai eseguire alcuna configurazione, Vertex AI configura automaticamente il modello per Vertex Explainable AI. Salta questo documento e leggilo 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 per un modello che hai già creato, anche se Non hai configurato le spiegazioni 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 tutti le sue spiegazioni utilizzando explanationSpec di Model .

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

In entrambi i casi, puoi configurare Model per supportare Vertex Explainable AI. La Gli esempi di questo documento presuppongono che l'importazione venga eseguita un Model. Per configurare Vertex Explainable AI durante la creazione di un asset Model con addestramento personalizzato utilizzando un TrainingPipeline, utilizza le impostazioni di configurazione descritte in documento nella modelToUpload di TrainingPipeline campo.

Configura le spiegazioni per il deployment di modelli o l'acquisizione di previsioni batch

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

  • Configura le spiegazioni, indipendentemente dal fatto che il modello sia stato o meno in precedenza configurate per le spiegazioni. È utile se non avevi intenzione di farlo inizialmente visualizzare le spiegazioni (e omettere il campo explanationSpec durante la creazione il modello), ma in seguito decidi se vuoi ricevere spiegazioni per il modello o se vuoi sostituire 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.

Sostituisci la configurazione per ricevere spiegazioni online

Indipendentemente dal fatto che tu abbia creato o importato Model con la spiegazione e a prescindere dalla configurazione delle impostazioni di spiegazione durante puoi eseguire l'override delle impostazioni di spiegazione iniziali di Model quando per ricevere spiegazioni online.

Quando invii una richiesta explain a Vertex AI, puoi sostituire parte della configurazione della spiegazione impostato 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 ad eccezione di method

Sostituisci queste impostazioni nella richiesta di spiegazione campo explanationSpecOverride.

Importa 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 confronto tra attribuzione delle caratteristiche per selezionare quello appropriato 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 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.

    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.

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

      1. Compila il campo Nome tensore di input.

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

      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. Il valore predefinito è IDENTITY se non è impostato.

      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. Al termine della configurazione, fai clic sul pulsante Importa le impostazioni di spiegabilità.

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 memorabile per l'elemento 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: qualsiasi 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 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=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, 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.

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à:

  1. Per il tuo metodo di attribuzione delle caratteristiche, seleziona Gradienti integrati (per i modelli) 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, segui questi passaggi:

    1. Imposta il Tipo di visualizzazione e la Mappa colori.

    2. Puoi lasciare i campi Clip below, Clip above (Clip sopra), Overlay type (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 di approssimazione, ma è più ad alta intensità di calcolo. 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. 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 campo Nome tensore di input.

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

      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. Il valore predefinito è IDENTITY se non è impostato.

      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. Al termine della configurazione, fai clic sul pulsante Importa le impostazioni di spiegabilità.

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",
      "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. A per trovare il valore corretto per questo campo, leggi l'articolo Using TensorFlow with 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 ulteriori informazioni 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: qualsiasi 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 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=integrated-gradients \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Sostituisci quanto segue:

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

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

REST

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

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

    Un valore più alto potrebbe ridurre di approssimazione, ma è più ad alta intensità di 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. A per trovare il valore corretto per questo campo, leggi l'articolo Using TensorFlow with 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 ulteriori informazioni 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: qualsiasi 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.

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.

In via facoltativa, puoi aggiungere campi per configurare l'approssimazione del valore gradienti 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à:

  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 below, Clip above (Clip sopra), Overlay type (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 di approssimazione, ma è più ad alta intensità di calcolo. 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. 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 campo Nome tensore di input.

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

      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. Il valore predefinito è IDENTITY se non è impostato.

      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. Al termine della configurazione, fai clic sul pulsante Importa le impostazioni di spiegabilità.

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",
      "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 informazioni sui valori appropriati per gli altri segnaposto, consulta upload e Importazione di 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.

In via facoltativa, puoi aggiungere campi per configurare l'approssimazione del valore gradienti 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 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 artefatti del tuo modello non includono nomi delle caratteristiche, Vertex AI non è in grado di mappare i nomi delle caratteristiche di input specificate al modello. In questo nel caso in cui sia necessario fornire una sola caratteristica di input con qualsiasi un nome semplice, 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 output dell'elemento.

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

gcloud

  1. 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": {
    }
  },
  "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. Altrimenti, l'impostazione predefinita per la base di input è una matrice 2D di valori 0 della forma di input.

  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, effettua le seguenti sostituzioni:

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

Se specifichi basilari, assicurati che corrispondano l'input del modello, di solito un elenco di matrici 2-D. Altrimenti, l'impostazione predefinita per la base di input è una matrice 2D di valori 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 per utilizzare l'attribuzione di Shapley campionata per spiegazioni.

Determinazione dei nomi delle caratteristiche e degli output

Nei passaggi seguenti, devi fornire a Vertex AI i nomi delle caratteristiche previste da Model come input. Devi inoltre specificare chiave utilizzata per gli output nelle previsioni di Model.

Determinazione dei nomi delle caratteristiche

Se Model prevede ogni input a alcune chiavi di primo livello, queste sono i nomi delle tue caratteristiche.

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 caratteristiche sono length e width. Anche se i valori di questi campi contengono elenchi o oggetti nidificati, length e width sono gli unici le chiavi necessarie per i passaggi successivi. Quando richiedi spiegazioni, Vertex Explainable AI fornisce attribuzioni per ogni elemento nidificato delle tue caratteristiche.

Se Model prevede un input senza chiave, Vertex Explainable AI considera Model per avere 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 seguente formato:

[
  <value>,
  <value>
]

In questo caso, fornisci a Vertex Explainable AI un nome di funzionalità a tua scelta, come dimensions.

Determinazione del nome dell'output

Se Model restituisce ogni previsione online istanza 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 e quando ottieni le spiegazioni, Vertex Explainable AI restituisce la caratteristica attribuzioni dell'elemento con il valore più alto in ogni previsione. A configurare Vertex Explainable AI per fornire attribuzioni delle caratteristiche per elementi aggiuntivi del campo di output, puoi specificare i campi topK o outputIndices di ExplanationParameters. Tuttavia, gli esempi in questo documento non dimostrano queste opzioni.

Se Model restituisce previsioni senza chiave, puoi utilizzare qualsiasi valore facile da ricordare per il nome dell'output. Ad esempio, ciò si applica se i resi di Model 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à:

  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 artefatti del tuo modello non includono nomi delle caratteristiche, Vertex AI non è in grado di mappare i nomi delle caratteristiche di input specificate al modello. In questo nel caso in cui sia necessario fornire una sola caratteristica di input con qualsiasi un nome semplice, 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 output dell'elemento.

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

gcloud

  1. 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": {}
  },
  "outputs": {
    "OUTPUT_NAME": {}
  }
}

    Sostituisci quanto segue:

    • FEATURE_NAME: il nome dell'elemento, come descritto in "Determinazione dei nomi delle caratteristiche" di questo documento.
    • OUTPUT_NAME: il nome dell'output, come descritto in "Determinazione del nome dell'output" di questo documento.

    Se vuoi, puoi aggiungere base di riferimento ExplanationMetadata. Altrimenti, Vertex AI sceglie le basi degli input per Model.

    Se specifichi basilari, assicurati che corrispondano l'input del modello, di solito un elenco di matrici 2-D. Altrimenti, l'impostazione predefinita per la base di input è una matrice 2D di valori 0 della forma di input.

  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:

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

    Per informazioni 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 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 dell'elemento, come descritto in "Determinazione dei nomi delle caratteristiche" 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 base di riferimento 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. 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