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 e implementare un modello in AI Platform, devi svolgere diverse operazioni:

• Configura l'ambiente di sviluppo locale.
• Configura un progetto Google Cloud con la fatturazione e le API necessarie abilitate.
• Crea 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 notebook di esempio.

Salvataggio di un modello

Sono supportati 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. 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 le AI Explanations;IA e su come utilizzare l'SDK Explainable AI.

File di metadati della spiegazione

Prima di implementare il modello, devi inviare un file di metadati con informazioni su input, output e linea di base del modello, in modo che AI Explanations fornisca spiegazioni per le parti corrette del modello.

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

Creazione manuale del file dei metadati della spiegazione

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

• Identifica i nomi dei tensori di input e di output per i quali vuoi le spiegazioni. Consulta la sezione di seguito su come trovare manualmente i nomi dei tensori di input e output. Scopri di più su come identificare i tensori di input e output.
• Crea un baseline appropriato e specificalo in input_baselines.
• Specifica "tensorflow" per framework.
• Assegna al file il nome explanation_metadata.json.
• Carica il file explanation_metadata.json nello stesso bucket Cloud Storage in cui è archiviato il tuo SavedModel.

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 output che puoi assegnare durante la creazione e l'addestramento del modello. I nomi effettivi dei tensori di input e di output seguono il formato di name:index. Ad esempio, x:0 o Placeholder:0.

Per input_baselines, puoi iniziare specificando una linea di base. In questo esempio, [0] rappresenta un'immagine completamente nera. Puoi specificare più basi di riferimento per fornire informazioni aggiuntive. Scopri di più su come modificare le linee di base.

Individuare manualmente i nomi dei tensori di input e output

Nella maggior parte dei casi, puoi utilizzare l'SDK Explainable AI per generare gli input e gli output per il tuo modello. Devi trovare i nomi dei tensori di input e di output manualmente solo 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é dal modo in cui crei il modello. Per una spiegazione più approfondita di ciascun caso, nonché per esempi, consulta la guida su [informazioni su input e output][understanding-inputs-outputs].

Esegui il deployment di modelli e versioni

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

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

Crea una risorsa modello

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

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

Per utilizzare le AI Explanations, devi creare il tuo modello in un endpoint regionale.

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

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

Creare una versione del modello

Ora puoi creare una versione del modello con il modello addestrato caricato in precedenza su Cloud Storage. Quando crei una versione, specifica i seguenti parametri:

• name: deve essere univoco all'interno del modello AI Platform Prediction.
• deploymentUri: il percorso della directory SavedModel in Cloud Storage.
• framework (obbligatorio): solo tensorflow
• runtimeVersion: utilizza una delle seguenti versioni di runtime che supportano le 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 le versioni del runtime 1.15 e successive.
• machineType (obbligatorio): il tipo di macchina virtuale utilizzata da AI Platform Prediction per i nodi che forniscono previsioni ed spiegazioni. Seleziona un tipo di macchina supportato per le spiegazioni dell'IA.
• explanation-method: il tipo di metodo di attribuzione delle funzionalità da utilizzare: "sampled-shapley", "integrated-gradients" o "xrai".
• Percorsi o passaggi: utilizza --num-paths per i valori di Shapley campionati e --num-integral-steps per i gradienti integrati o XRAI.

Scopri di più su ciascuno di questi parametri nell'API AI Platform Training &API Prediction per una risorsa versione.

1. Imposta le variabili di ambiente per memorizzare il percorso della directory Cloud Storage in cui si trova il tuo SavedModel, il nome del modello, il nome della versione e il framework scelto.

   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 è tutto pronto, dovresti vedere il seguente output:

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

3. Controlla lo stato di implementazione 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 visualizzare 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 macchine supportati per le spiegazioni

Per le richieste di spiegazioni dell'IA, devi eseguire il deployment della versione del modello con uno dei seguenti tipi di macchine. Se non specifichi un tipo di macchina, il deployment non va a buon fine.

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

Questi tipi di macchine sono disponibili solo negli endpoint regionali. Scopri di più sul supporto per altre funzionalità di AI Platform Prediction.

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

Formattare i dati di input

Il formato di base per la previsione online è un elenco di istanze di dati. 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 per un modello TensorFlow:

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

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

• Il livello superiore dei dati dell'istanza deve essere un oggetto JSON: 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 mescolare valori numerici e di stringa.

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 nuova riga, con ogni istanza come 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 le tue previsioni e spiegazioni:

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

Informazioni sulla risposta alle spiegazioni

Dopo aver implementato il modello, puoi utilizzare l'SDK Explainable AI per richiedere spiegazioni e visualizzare i risultati dell'attribuzione delle funzionalità sia per i dati tabulari sia per quelli delle immagini:

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 vengono tracciate in un grafico a barre. Per i modelli di immagini, le attribuzioni vengono visualizzate sull'immagine di input utilizzando le stesse impostazioni di visualizzazione specificate durante il deployment del modello.

Per dettagli su ogni campo nella risposta delle spiegazioni, consulta la risposta di esempio completa nella documentazione di riferimento dell'API.

Scopri come analizzare la risposta alle spiegazioni consultando i notebook di esempio:

TensorFlow 2:

• Notebook di esempio per i dati tabulari
• Notebook di esempio per i dati delle immagini

TensorFlow 1.15:

• Notebook di esempio per i dati tabulari
• Notebook di esempio per i dati delle immagini

Controllare le spiegazioni

Il seguente esempio di codice ti aiuta a controllare un batch di spiegazioni e a capire se è necessario modificare le linee di base.

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 fosse "data", lo stesso valore sarà "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 che hai ricevuto:

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

Utilizzare l'errore di approssimazione per migliorare i risultati

I metodi di attribuzione delle funzionalità di AI Explanations (valori di Shapley campionati, gradienti integrati e XRAI) si basano tutti su varianti dei valori di Shapley. Poiché i valori di Shapley sono molto dispendiosi in termini di risorse di calcolo, AI Explanations fornisce approssimazione anziché valori esatti. Oltre ai risultati dell'attribuzione delle funzionalità, le AI Explanations restituiscono anche un errore di approssimazione. Se l'errore di approssimazione supera 0,05, valuta la possibilità di modificare gli input per ridurre l'errore.

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

• Aumentare il numero di passaggi per l'integrale o il numero di percorsi.
• Modifica delle linee di base di input selezionate.
• Aggiunta di altre basi degli input. Con i metodi di gradienti integrati e XRAI, l'utilizzo di soglie di riferimento aggiuntive aumenta la latenza. L'utilizzo di linee di base aggiuntive con il metodo del valore di Shapley campionato non aumenta la latenza.

Aumentare i passaggi o i percorsi

Per ridurre l'errore di approssimazione, puoi aumentare:

• il numero di percorsi per il valore di Shapley campionato
• il numero di passaggi per l'integrale per i gradienti integrati o XRAI

Imposti questi parametri quando crei una risorsa di versione durante il deployment del modello.

Modificare le linee di base

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

In generale:

• Inizia con una linea di base che rappresenti i valori mediani.
• Modifica questa base di riferimento in modo che rappresenti valori casuali.
• Prova due linee di base, che rappresentano i valori minimo e massimo.
• Aggiungi un'altra base di riferimento che rappresenti valori casuali.

Esempio per i dati tabulari

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

Tieni presente che input_baselines è un elenco in cui puoi specificare più linee di base. Questo esempio imposta una sola linea di riferimento. La base di riferimento è un elenco di valori mediana 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 linee di base 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 della spiegazione per i dati delle immagini. Puoi utilizzare i gradienti integrati per ottenere le attribuzioni delle caratteristiche per i dati delle immagini. Questo codice fa parte del notebook di esempio per i dati delle immagini.

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

In caso contrario, 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

• Scopri di più sulle limitazioni delle attribuzioni delle funzionalità
• Per visualizzare le spiegazioni, puoi utilizzare lo strumento What-If. Per saperne di più, consulta i notebook di esempio.
• Fai riferimento all'SDK AI Explanations.