Utilizzo di AI Explanations con AI Platform Prediction

Questa è una guida generale su come eseguire il deployment e utilizzare un modello su AI Platform Prediction con AI Explanations.

Prima di iniziare

Prima di poter addestrare ed eseguire il deployment di un modello in AI Platform, devi eseguire diverse operazioni:

  • Configura l'ambiente di sviluppo locale.
  • Configura un progetto Google Cloud con fatturazione e le API necessarie abilitate.
  • Creare un bucket Cloud Storage per archiviare il pacchetto di addestramento e il modello addestrato.

Per configurare il progetto Google Cloud, segui le istruzioni fornite nei blocchi note di esempio.

Salvataggio di un modello

TensorFlow 1.15, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10 e 2.11 sono supportati. Utilizza tf.saved_model.save per salvare i modelli in TensorFlow 2.11, ma non per TensorFlow 1.15.

Scopri di più su come salvare i modelli da utilizzare con AI Explanations e su come utilizzare l'SDK Explainable AI.

File di metadati spiegazione

Prima di eseguire il deployment del modello, devi inviare un file di metadati con informazioni sugli input, sugli output e sulla base di riferimento del modello, in modo che AI Explanations fornisca spiegazioni per le parti corrette del modello.

Ti consigliamo di utilizzare l'SDK Explainable AI per rilevare automaticamente gli input e gli output del modello. Nella maggior parte dei casi, questo consente di risparmiare tempo e fatica, poiché l'SDK Explainable AI crea e carica il file di metadati spiegazione per te.

Creazione manuale del file di metadati della spiegazione

Se hai un caso d'uso avanzato, potresti preferire specificare manualmente gli input e gli output del modello. Per creare manualmente il file di metadati della spiegazione:

L'esempio seguente mostra l'aspetto di un file explanation_metadata.json:

{
    "inputs": {
      "data": {
        "input_tensor_name": "YOUR_INPUT_TENSOR_NAME"
        "input_baselines": [0]
      }
    },
    "outputs": {
      "duration": {
        "output_tensor_name": "YOUR_OUTPUT_TENSOR_NAME"
      }
    },
    "framework": "tensorflow"
}

In questo esempio, "data" e "duration" sono nomi significativi per i tensori di input e di output che puoi assegnare durante il processo di creazione e addestramento del modello. I nomi effettivi dei tensori di input e output seguono il formato name:index. Ad esempio, x:0 o Placeholder:0.

Per input_baselines, puoi iniziare specificando una base di riferimento. In questo esempio, [0] rappresenta un'immagine completamente nera. Puoi specificare più basi per fornire ulteriori informazioni. Scopri di più sulla regolazione delle basi di riferimento.

Individuazione manuale dei nomi dei tensori di input e di output

Nella maggior parte dei casi, puoi utilizzare l'SDK Explainable AI per generare gli input e gli output per il modello. Devi trovare i nomi dei tensori di input e di output manualmente se utilizzi un modello TensorFlow 1.15 preaddestrato.

Il modo migliore per trovare i nomi dei tensori di input e di output dipende dai tipi di dati di input e di output, nonché da come crei il modello. Per una spiegazione più approfondita di ciascun caso, oltre ad esempi, consulta la guida su [comprendere input e output].

Tipi di dati di input Tipo di dati di output Altri criteri Approcci consigliati
Numerico o stringa Numerico Gli input non sono in forma serializzata. Gli output non sono dati numerici trattati come dati categorici (ad esempio, ID classe numerici). Utilizza l'interfaccia a riga di comando SaveModel per trovare i nomi dei tensori di input e di output. In alternativa, crea il file di metadati della spiegazione durante l'addestramento e il salvataggio del modello, laddove il tuo programma o ambiente abbia ancora accesso al codice di addestramento.
Qualsiasi dato serializzato Qualsiasi Quando esporti il modello, aggiungi un'operazione di analisi TensorFlow alla funzione di input di gestione. Utilizza l'output dell'operazione di analisi per identificare i tensori di input.
Qualsiasi Qualsiasi Il modello include operazioni di pre-elaborazione Per ottenere i nomi dei tensori di input dopo i passaggi di pre-elaborazione, utilizza la proprietà name di tf.Tensor per ottenere i nomi dei tensori di input.
Qualsiasi Non probabilità, logit o altri tipi di tensori a virgola mobile Vuoi ottenere spiegazioni per output che non sono probabilità, logit o altri tipi di tensori in virgola mobile. Esamina il grafico con TensorBoard per trovare i tensori di output corretti.
Tutti i dati non differenziabili Qualsiasi Vuoi utilizzare gradienti integrati, che richiedono input differenziabili. Codifica gli input non differenziabili come tensori differenziabili. Aggiungi i nomi sia del tensore di input originale sia del tensore di input codificato al file di metadati della spiegazione.

Esegui il deployment di modelli e versioni

AI Platform Prediction organizza i modelli addestrati utilizzando le risorse di model e model. Un modello di previsione di AI Platform è un container per le versioni del modello di machine learning.

Per eseguire il deployment di un modello, crea una risorsa del modello in AI Platform Prediction, crea una versione del modello e collega la versione del modello al file del modello archiviato in Cloud Storage.

Crea una risorsa del modello

AI Platform Prediction utilizza le risorse del modello per organizzare le diverse versioni del modello.

Creare una risorsa del modello per le versioni del modello. Nel seguente comando di Google Cloud CLI, sostituisci MODEL_NAME con il nome che preferisci per il modello. Il nome del modello deve iniziare con una lettera e contenere solo lettere, numeri e trattini bassi.

Devi creare il modello in un endpoint a livello di regione per utilizzare AI Explanations.

gcloud ai-platform models create MODEL_NAME \
  --region us-central1

Per ulteriori dettagli, consulta l'API del modello AI Platform Prediction.

Crea una versione del modello

Ora è tutto pronto per creare una versione del modello con il modello addestrato che hai caricato in precedenza su Cloud Storage. Quando crei una versione, specifica i seguenti parametri:

  • name: deve essere univoco all'interno del modello di AI Platform Prediction.
  • deploymentUri: il percorso della directory SaveModel in Cloud Storage.
  • framework (obbligatorio): solo tensorflow
  • runtimeVersion: utilizza una delle seguenti versioni di runtime che supportano AI Explanations: 1.15, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10 e 2.11.
  • pythonVersion: utilizza "3.7" per il runtime 1.15 e versioni successive.
  • machineType (obbligatorio): il tipo di macchina virtuale utilizzata da AI Platform Prediction per i nodi che forniscono previsioni e spiegazioni. Seleziona un tipo di macchina supportato per AI Explanations.
  • explanation-method: il tipo di metodo di attribuzione delle caratteristiche da utilizzare: "sampled-shapley", "integrated-gradients" o "xrai".
  • Percorsi o passaggi: utilizza --num-paths per il valore di Shapley campionato e utilizza --num-integral-steps per gradienti integrati o XRAI.

Leggi ulteriori informazioni su ciascuno di questi parametri nell'API AI Platform Training and API Prediction per una risorsa della versione.

  1. Imposta le variabili di ambiente per archiviare il percorso della directory Cloud Storage in cui si trova il savedModel, il nome del modello, il nome della versione e la scelta del framework.

    MODEL=your_model_name
MODEL_DIR="gs://your_bucket_name/"
VERSION=your_version_name
FRAMEWORK=tensorflow

  2. Crea la versione:

    EXPLAIN_METHOD="integrated-gradients"
gcloud beta ai-platform versions create $VERSION \
--model $MODEL \
--origin $MODEL_DIR \
--runtime-version 1.15 \
--framework $FRAMEWORK \
--python-version 3.7 \
--machine-type n1-standard-4 \
--explanation-method $EXPLAIN_METHOD \
--num-integral-steps 25 \
--region us-central1

    La creazione della versione richiede alcuni minuti. Quando è pronto, dovresti vedere il seguente output:

    Creating version (this might take a few minutes)......done.

  3. Controlla lo stato del deployment del modello e assicurati che sia stato eseguito correttamente:

    gcloud ai-platform versions describe $VERSION_NAME \
  --model $MODEL_NAME \
  --region us-central1

    Verifica che lo stato sia READY. Dovresti vedere un output simile al seguente:

    createTime: '2018-02-28T16:30:45Z'
deploymentUri: gs://your_bucket_name
framework: TENSORFLOW
machineType: n1-standard-4
name: projects/your_project_id/models/your_model_name/versions/your_version_name
pythonVersion: '3.7'
runtimeVersion: '1.15'
state: READY

Tipi di macchina supportati per le spiegazioni

Per le richieste AI Explanations, devi eseguire il deployment della versione del modello con uno dei seguenti tipi di macchina. Se non specifichi un tipo di macchina, il deployment non riesce.

La tabella seguente mette a confronto i tipi di macchina disponibili:

Nome vCPUs Memoria (GB)
n1-standard-2 2 7.5
n1-standard-4 4 15
n1-standard-8 8 30
n1-standard-16 16 60
n1-standard-32 32 120

Questi tipi di macchine sono disponibili solo su endpoint a livello di regione. Scopri di più sul supporto per altre funzionalità di AI Platform Prediction.

Scopri di più sui prezzi per ciascun tipo di macchina. Scopri di più sulle specifiche dettagliate dei tipi di macchine di Compute Engine (N1) nella documentazione di Compute Engine.

Formatta i dati di input

Il formato di base per la previsione online è un elenco di istanze di dati. Questi possono essere semplici elenchi di valori o membri di un oggetto JSON, a seconda di come hai configurato gli input nell'applicazione di addestramento. Scopri come formattare input complessi e dati binari per la previsione.

Questo esempio mostra un tensore di input e una chiave di istanza in un modello TensorFlow:

{"values": [1, 2, 3, 4], "key": 1}

La composizione della stringa JSON può essere complessa, purché segua queste regole:

  • Il livello superiore dei dati dell'istanza deve essere un oggetto JSON, ovvero un dizionario di coppie chiave/valore.

  • I singoli valori in un oggetto istanza possono essere stringhe, numeri o elenchi. Non puoi incorporare oggetti JSON.

  • Gli elenchi devono contenere solo elementi dello stesso tipo (inclusi altri elenchi). Non puoi combinare valori stringa e numerici.

Le istanze di input per la previsione online vengono passate come corpo del messaggio per la chiamata projects.explain. Scopri di più sui requisiti di formattazione del corpo della richiesta di previsione.

  1. Per inviare la richiesta con gcloud, assicurati che il file di input sia un file JSON delimitato da una nuova riga, con ogni istanza sotto forma di oggetto JSON, un'istanza per riga.

    {"values": [1, 2, 3, 4], "key": 1}
{"values": [5, 6, 7, 8], "key": 2}

Richiedere previsioni e spiegazioni

Richiedi previsioni e spiegazioni:

gcloud beta ai-platform explain \
  --model $MODEL \
  --version $VERSION \
  --json-instances='your-data.txt' \
  --region us-central1

Comprendere la risposta alle spiegazioni

Dopo aver eseguito il deployment del modello, puoi utilizzare l'SDK Explainable AI per richiedere spiegazioni e visualizzare i risultati di attribuzione delle caratteristiche per i dati tabulari e di immagine:

import explainable_ai_sdk

m = explainable_ai_sdk.load_model_from_ai_platform(PROJECT_ID, MODEL_NAME, VERSION, region=REGION)
explanations = m.explain([instance_dict])
explanations[0].visualize_attributions()

Per i modelli tabulari, le attribuzioni sono tracciate in un grafico a barre. Per i modelli immagine, le attribuzioni vengono mostrate nell'immagine di input, utilizzando le stesse impostazioni di visualizzazione specificate al momento del deployment del modello.

Per i dettagli su ciascun campo nella risposta alle spiegazioni, consulta la risposta di esempio completa nel riferimento API.

Scopri come analizzare la risposta alle spiegazioni facendo riferimento ai blocchi note di esempio:

TensorFlow 2:

TensorFlow 1.15:

Controllare le spiegazioni

Il seguente esempio di codice consente di controllare un gruppo di spiegazioni e verificare se è necessario modificare le basi.

Nel codice devi solo aggiornare il valore della chiave di input in base a quanto specificato nel file explanation_metadata.json.

{
    "inputs": {
      "YOUR_INPUT_KEY_VALUE": {
        "input_tensor_name": "YOUR_INPUT_TENSOR_NAME"
        "input_baselines": [0]
      }
    ...
}

Ad esempio, se il valore della chiave di input era "data", lo stesso valore sarebbe "data" nella riga 4 del seguente snippet di codice:

def check_explanations(example, mean_tgt_value=None, variance_tgt_value=None):
  passed_test = 0
  total_test = 1
  attribution_vals = example['attributions_by_label'][0]['attributions']['YOUR-INPUT-KEY-VALUE']

  baseline_score = example['attributions_by_label'][0]['baseline_score']
  sum_with_baseline = np.sum(attribution_vals) + baseline_score
  predicted_val = example['attributions_by_label'][0]['example_score']

  # Check 1
  # The prediction at the input is equal to that at the baseline.
  #  Please use a different baseline. Some suggestions are: random input, training
  #  set mean.
  if abs(predicted_val - baseline_score) <= 0.05:
    print('Warning: example score and baseline score are too close.')
    print('You might not get attributions.')
  else:
    passed_test += 1

  # Check 2 (only for models using Integrated Gradient explanations)
  # Ideally, the sum of the integrated gradients must be equal to the difference
  # in the prediction probability at the input and baseline. Any discrepancy in
  # these two values is due to the errors in approximating the integral.
  if explain_method == 'integrated-gradients':
    total_test += 1
    want_integral = predicted_val - baseline_score
    got_integral = sum(attribution_vals)
    if abs(want_integral-got_integral)/abs(want_integral) > 0.05:
        print('Warning: Integral approximation error exceeds 5%.')
        print('Please try increasing the number of integrated gradient steps.')
    else:
        passed_test += 1

  print(passed_test, ' out of ', total_test, ' sanity checks passed.')

Durante l'analisi delle spiegazioni, puoi eseguire questi controlli su ogni attribuzione ricevuta:

for i in attributions_resp['explanations']:
  check_explanations(i)

Uso dell'errore di approssimazione per migliorare i risultati

I metodi di attribuzione delle funzionalità di AI Explanations (shapley campionato, gradienti integrati e XRAI) si basano tutti su varianti dei valori di Shapley. Poiché i valori di Shapley sono molto costosi dal punto di vista del calcolo, AI Explanations fornisce approssimazioni invece dei valori esatti. Insieme ai risultati di attribuzione delle caratteristiche, AI Explanations restituisce anche un errore di approssimazione. Se l'errore di approssimazione supera 0,05, ti consigliamo di modificare gli input per ridurre l'errore.

Puoi ridurre l'errore di approssimazione e avvicinarti ai valori esatti modificando i seguenti input:

  • Aumento del numero di passaggi integrali o del numero di percorsi.
  • Modifica delle basi di input selezionate.
  • Aggiunta di altre basi di input. Con i gradienti e i metodi XRAI integrati, l'utilizzo di basi di riferimento aggiuntive aumenta la latenza. L'utilizzo di basi di riferimento aggiuntive con il metodo di Shapley campionato non aumenta la latenza.

Aumento di passi o percorsi

Per ridurre l'errore di approssimazione, puoi aumentare:

  • il numero di percorsi per il valore di Shapley campionato
  • il numero di passaggi integrali per gradienti integrati o XRAI

Puoi impostare questi parametri quando crei una risorsa della versione durante il deployment del modello.

Aggiustamento delle basi

Puoi impostare input_baselines nel file explanation_metadata.json. Questa sezione fornisce esempi di dati tabulari e di immagine. Le basi di input possono rappresentare valori mediani, minimi, massimi o casuali in relazione ai dati di addestramento.

In generale:

  • Iniziare con una base di riferimento che rappresenta i valori mediani.
  • Modifica questa base di riferimento impostandola su una che rappresenti valori casuali.
  • Prova due basi, che rappresentano i valori minimo e massimo.
  • Aggiungi un'altra base di riferimento che rappresenti valori casuali.

Esempio di dati tabulari

Il seguente codice Python crea i contenuti di un file di metadati di spiegazione per i dati tabulari. Puoi utilizzare Shapley campionato o gradienti integrati per ottenere le attribuzioni delle caratteristiche per i dati tabulari. Questo codice fa parte del blocco note di esempio per i dati tabulari.

Tieni presente che input_baselines è un elenco in cui puoi specificare più base di riferimento. Questo esempio imposta solo una base di riferimento. La base di riferimento è un elenco di valori mediani per i dati di addestramento (train_data in questo esempio).

explanation_metadata = {
    "inputs": {
      "data": {
        "input_tensor_name": model.input.name,
        "input_baselines": [train_data.median().values.tolist()],
        "encoding": "bag_of_features",
        "index_feature_mapping": train_data.columns.tolist()
      }
    },
    "outputs": {
      "duration": {
        "output_tensor_name": model.output.name
      }
    },
  "framework": "tensorflow"
  }

Per impostare due basi che rappresentano i valori minimo e massimo, imposta input_baselines come segue: [train_data.min().values.tolist(), train_data.max().values.tolist()]

Esempio per i dati delle immagini

Il seguente codice Python crea i contenuti di un file di metadati di spiegazione per i dati dell'immagine. Puoi utilizzare gradienti integrati per ottenere attribuzioni delle funzionalità per i dati delle immagini. Questo codice fa parte del blocco note di esempio per i dati immagine.

Tieni presente che input_baselines è un elenco in cui puoi specificare più base di riferimento. Questo esempio imposta solo una base di riferimento. La base di riferimento è un elenco di valori casuali. L'utilizzo di valori casuali per una base di immagini è un buon approccio se le immagini nel set di dati di addestramento contengono molto bianco e nero.

Altrimenti, imposta input_baselines su [0, 1] per rappresentare le immagini in bianco e nero.

random_baseline = np.random.rand(192,192,3)

explanation_metadata = {
    "inputs": {
      "data": {
        "input_tensor_name": "input_pixels:0",
        "modality": "image",
        "input_baselines": [random_baseline.tolist()]
      }
    },
    "outputs": {
      "probability": {
        "output_tensor_name": "dense/Softmax:0"
      }
    },
  "framework": "tensorflow"
  }

Passaggi successivi