Utilizzo di AI Explains 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 fatturazione e le API necessarie abilitate.
  • Crea un bucket Cloud Storage per archiviare il tuo pacchetto di addestramento addestrato al modello.

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 per l'utilizzo con AI Explanations e come utilizzare l'SDK Explainable AI.

File di metadati delle spiegazioni

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 tuo modello, in modo che AI Explanations fornisca le spiegazioni per le parti corrette del modello.

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

Creazione manuale del file dei 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 di 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 l'input e tensori di output che è possibile assegnare durante il processo di creazione e addestramento un modello di machine learning. 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 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 regolare le basi di riferimento.

Localizzazione manuale dei nomi dei tensori di input e output

Nella maggior parte dei casi, puoi utilizzare l'SDK Explainable AI per generare gli input e 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].

Tipi di dati di input Tipo di dati di output Altri criteri Approcci consigliati
Numerico o stringa Numerico Gli input non sono in formato serializzato. Le uscite non sono dati numerici trattati come dati categorici (ad es. ID classe numerici). Utilizza l'interfaccia a riga di comando SavedModel per trovare i nomi dei tensori di input e output. In alternativa, crea il file di metadati esplicativi durante l'addestramento e salvare il modello, dove il programma o l'ambiente ha ancora accesso al codice di addestramento.
Qualsiasi dato serializzato Qualsiasi Aggiungi un'operazione di analisi TensorFlow alla funzione di input di pubblicazione quando puoi esportare il modello. Utilizza l'output dell'operazione di analisi per semplificare 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 preelaborazione, utilizza la proprietà name di tf.Tensor per ottenere i nomi dei tensori di input.
Qualsiasi Non probabilità, logit o altri tipi di tensori in virgola mobile Vuoi ottenere spiegazioni per gli output che non sono probabilità, logit o altri tipi di tensori a virgola mobile. Esamina il grafico con TensorBoard per trovare i tensori di output corretti.
Qualsiasi dato non differenziabile Qualsiasi Vuoi utilizzare i 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 dei metadati della spiegazione.

Esegui il deployment di modelli e versioni

AI Platform Prediction organizza i modelli addestrati utilizzando modello e Risorse della versione. Un modello AI Platform Prediction è un container per più versioni del tuo 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, poi collegala al file del modello archiviato di archiviazione ideale 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.

Devi creare il modello in una regione dell'endpoint 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 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 spiegazioni dell'IA: 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: usa "3,7" per il runtime versioni 1.15 e successive.
  • (Obbligatorio) machineType: il tipo di macchina virtuale utilizzato da AI Platform Prediction per i nodi che forniscono previsioni e spiegazioni. Seleziona uno tipo di macchina supportato per AI Explains.
  • explanation-method: il tipo di metodo di attribuzione delle funzionalità da utilizzare: "sampled-shapley", "integrated-gradients" o "xrai".
  • Percorsi o passaggi: usa --num-paths per i valori di Shapley campionati e usa --num-integral-steps per gradienti integrati o XRAI.

Scopri di più su ciascuno di questi parametri in l'API AI Platform Training and API Prediction per una risorsa di 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. Al termine, 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 riesce.

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

Nome vCPU 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 negli endpoint regionali. Scopri di più sul loro supporto per altre applicazioni AI Platform Prediction funzionalità.

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

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 configurato gli input nell'applicazione di addestramento. Scopri come formattare input complessi e dati binari per la previsione.

L'esempio seguente 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, a condizione che segua queste regole:

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

  • I singoli valori di 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 projects.explain. Scopri di più sui requisiti di formattazione del corpo della richiesta di previsione.

  1. Per inviare la richiesta a gcloud, assicurati che il file di input sia un file JSON delimitato da nuova riga, con ogni istanza come oggetto JSON, uno o istanza per riga.

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

Richiedi 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

Comprendere la risposta delle 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 ciascun campo nella risposta delle spiegazioni, consulta la risposta di esempio completa nella documentazione di riferimento dell'API.

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

TensorFlow 2:

TensorFlow 1.15:

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 la chiave di input in base a 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.')

Quando analizzi le 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 costosi dal punto di vista dell'elaborazione, AI Explanations delle approssimazioni anziché dei valori esatti. Oltre ai risultati dell'attribuzione delle funzionalità, le spiegazioni dell'IA restituiscono anche un errore di approssimazione. Se le tue di errore di approssimazione superiore a 0,05, ti consigliamo di modificare gli input per ridurre .

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 gradienti integrati e i metodi XRAI, l'utilizzo di basi di riferimento aggiuntive aumenta la latenza. L'utilizzo di basi di riferimento aggiuntive con il metodo 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.

Regolazione delle basi di riferimento

Puoi impostare input_baselines nel file explanation_metadata.json. Questo fornisce esempi di dati tabulari e di immagine. Le basi di input possono rappresenta il valore mediano, minimo, massimo o casuale in relazione dati di addestramento.

In generale:

  • Inizia con una base di riferimento che rappresenta 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 rappresenta valori casuali.

Esempio di dati tabulari

Il seguente codice Python crea i contenuti di un file di metadati della spiegazione per i dati tabulari. Puoi usare valori di Shapley campionati o gradienti integrati per le attribuzioni delle caratteristiche 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ù base di riferimento. Questo esempio imposta una sola base di riferimento. Il valore di riferimento è un elenco di valori medi 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 spiegazione per i dati di immagine. Puoi utilizzare i gradienti integrati per ottenere le attribuzioni delle caratteristiche 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 una sola base di riferimento. La base di riferimento è un elenco di valori random. L'utilizzo di valori casuali per una base di riferimento di un'immagine è un buon approccio nel caso in cui nel set di dati di addestramento contengono molte immagini in bianco e nero.

In caso contrario, imposta input_baselines su [0, 1] per rappresentare il bianco e nero in formato Docker.

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