Como preparar metadados para o AI Explanations

Ao implantar o modelo, é necessário enviar um arquivo de metadados de explicação para configurar a solicitação de explicações. Esse arquivo de metadados precisa incluir as entradas e saídas do seu modelo para selecionar recursos para a solicitação de explicações. Também é possível incluir valores de referência de entrada e definir configurações de visualização para dados de imagem.

Este guia explica como usar o SDK do Explainable AI para criar seu arquivo de metadados de explicação enquanto você cria um novo modelo com o TensorFlow 2.x ou o TensorFlow 1.15 ou usando um modelo existente do TensorFlow 2.x. Para solicitar explicações para um modelo existente do TensorFlow 1.x, crie o arquivo de metadados de explicação manualmente.

Visão geral dos metadados de explicação

O arquivo de metadados de explicação é necessário para a implantação do modelo no AI Explanations. Especificar as entradas e saídas do modelo permite selecionar recursos específicos para a solicitação de explicações. Você cria um arquivo chamado explanation_metadata.json e o envia para o bucket do Cloud Storage no mesmo diretório do SavedModel. O SDK do Explainable AI cuida desse processo para você enquanto você cria e salva o modelo.

Também é possível adicionar configurações opcionais ao seu arquivo de metadados de explicação:

Saiba mais sobre o arquivo de metadados de explicação na Referência da API.

Como instalar o SDK do Explainable AI

O SDK do Explainable AI é um SDK Python compatível com modelos criados usando:

  • TensorFlow 1.15 e TensorFlow 2.x;
  • Python 3.7 ou posterior.

Instale o SDK do Explainable AI:

pip3 install explainable_ai_sdk

Como encontrar entradas e saídas com o SDK do Explainable AI

O SDK do Explainable AI ajuda a encontrar as entradas e saídas ao criar ou treinar um modelo do TensorFlow. Em cada um desses casos, você cria o arquivo de metadados de explicação logo depois de criar o modelo. Para os modelos Keras e Estimator, o SDK do Explainable AI infere entradas e saídas do grafo do modelo.

Antes de salvar o arquivo de metadados, atualize todos os valores de entrada e saída gerados pelo SDK do Explainable AI e adicione outros campos, como valores de referência de entrada e preferências de visualização.

Exemplos de SDK do Explainable AI para o TensorFlow 2.x

O SavedModelMetadataBuilder funciona com qualquer SavedModel criado com o TensorFlow 2.x. Neste exemplo, o SDK do Explainable AI cria e faz upload do arquivo de metadados de explicação para o mesmo diretório do bucket do Cloud Storage que seu modelo:

from explainable_ai_sdk.metadata.tf.v2 import SavedModelMetadataBuilder
builder = SavedModelMetadataBuilder(
    model_path)
builder.save_model_with_metadata('gs://my_bucket/model')  # Save the model and the metadata.

Também é possível usar a função get_metadata() para verificar os metadados gerados antes de salvá-los e fazer upload deles.

Se você estiver usando uma função do TensorFlow para salvar e fazer upload do modelo, use save_metadata() para criar e exportar apenas os metadados de explicação:

from explainable_ai_sdk.metadata.tf.v2 import SavedModelMetadataBuilder
# We want to explain 'xai_model' signature.
builder = SavedModelMetadataBuilder(export_path, signature_name='xai_model')
random_baseline = np.random.rand(192, 192, 3)
builder.set_image_metadata(
    'numpy_inputs',
    input_baselines=[random_baseline.tolist()])
builder.save_metadata(export_path)

Este exemplo também mostra como definir um valor de referência de entrada para dados de imagem, usando ruído aleatório como o valor de referência. Use um valor de referência de entrada que seja mais apropriado com o conjunto de dados. Como ponto de partida, consulte os exemplos de valores de referência do AI Explanations. Para atualizar os metadados e adicionar mais campos, use a função setter que corresponda ao tipo dos seus dados: set_numeric_metadata(), set_categorical_metadata() ou set_image_metadata().

Exemplos de SDK do Explainable AI para o TensorFlow 1.15

O SDK do Explainable AI é compatível com modelos do TensorFlow 1.15 criados com tf.keras, tf.estimator ou tf.Graph.

Keras

O SDK do Explainable AI é compatível com modelos Keras criados com as APIs Sequential e Functional, bem como modelos personalizados criados com a criação de subclasses da classe Model. Saiba mais sobre os diferentes tipos de modelos Keras.

import tensorflow.compat.v1.keras as keras
from explainable_ai_sdk.metadata.tf.v1 import KerasGraphMetadataBuilder

# Build a model.
model = keras.models.Sequential()
model.add(keras.layers.Dense(32, activation='relu', input_dim=10))
model.add(keras.layers.Dense(1, activation='sigmoid'))
model.compile(loss='binary_crossentropy', metrics=['accuracy'])
model.fit(
    np.random.random((1, 10)),
    np.random.randint(2, size=(1, 1)),
    epochs=10,
    batch_size=32)

# Set the path to your model.
model_path = MODEL_PATH

# Build the metadata.
builder = KerasGraphMetadataBuilder(model)
builder.save_model_with_metadata(model_path)

Depois de criar seu modelo, use o criador de metadados para receber as entradas e saídas.

Estimator

O SDK do Explainable AI é compatível com modelos Estimator. Para o builder de metadados, especifique as colunas de atributo de entrada, a função de entrada de exibição e uma chave de saída.

import tensorflow.compat.v1 as tf
from explainable_ai_sdk.metadata.tf.v1 import EstimatorMetadataBuilder


# Build a model.
language = tf.feature_column.categorical_column_with_vocabulary_list(
    key='language',
    vocabulary_list=('english', 'korean'),
    num_oov_buckets=1)
language_indicator = tf.feature_column.indicator_column(language)
class_identity = tf.feature_column.categorical_column_with_identity(
    key='class_identity', num_buckets=4)
class_id_indicator = tf.feature_column.indicator_column(class_identity)
age = tf.feature_column.numeric_column(key='age', default_value=0.0)
classifier_dnn = tf.estimator.DNNClassifier(
    hidden_units=[4],
    feature_columns=[age, language_indicator, language_embedding, class_id_indicator])
classifier_dnn.train(input_fn=_train_input_fn, steps=5)

# Build the metadata.
md_builder = EstimatorMetadataBuilder(
    classifier_dnn, [age, language, class_identity],  _get_json_serving_input_fn, 'logits')
model_path = MODEL_PATH

Grafo

O SDK de IA explicável também é compatível com modelos do TensorFlow criados sem as APIs Keras ou Estimator.

import tensorflow.compat.v1 as tf
from explainable_ai_sdk.metadata.tf.v1 import GraphMetadataBuilder

# Build a model.
sess = tf.Session(graph=tf.Graph())
with sess.graph.as_default():
  x = tf.placeholder(shape=[None, 10], dtype=tf.float32, name='inp')
  weights = tf.constant(1., shape=(10, 2), name='weights')
  bias_weight = tf.constant(1., shape=(2,), name='bias')
  linear_layer = tf.add(tf.matmul(x, weights), bias_weight)
  prediction = tf.nn.relu(linear_layer)

# Build the metadata.
builder = GraphMetadataBuilder(
    session=sess, tags=['serve'])
builder.add_numeric_metadata(x)
builder.add_output_metadata(prediction)
model_path = os.path.join('gs://', 'BUCKET_NAME', 'PATH_TO_MODEL')
builder.save_model_with_metadata(model_path)

Depois de criar o grafo, crie os metadados de explicação com uma ou mais entradas do modelo e uma saída. O SDK do Explainable AI fornece uma função para ajudar você a adicionar metadados para cada tipo de entrada: numérico, categórico, imagem e texto.

O arquivo explanation_metadata.json resultante é semelhante a este:

{
  "outputs": {
    "Relu": {
      "output_tensor_name": "Relu:0"
    }
  },
  "inputs": {
    "inp": {
      "input_tensor_name": "inp:0",
      "encoding": "identity",
      "modality": "numeric"
    }
  },
  "framework": "Tensorflow",
  "tags": [
    "explainable_ai_sdk"
  ]
}

Configurações opcionais de metadados de explicação

Por padrão, o SDK do Explainable AI produz um arquivo de metadados de explicação com apenas as informações necessárias sobre as entradas e saídas do seu modelo. Antes de salvar o arquivo de metadados de explicação, inclua definições opcionais para valores de referência de entrada e configurações de visualização da imagem. Também é possível editar o arquivo de metadados de explicação depois de criá-lo.

Como definir valores de referência de entrada

Os valores de referência de entrada representam um recurso que não fornece mais informações. Os valores de referência para modelos tabulares podem ser valores médios, mínimos, máximos ou aleatórios em relação aos dados de treinamento. Da mesma forma, para modelos de imagem, os valores de referência podem ser uma imagem preta, branca ou cinza ou uma imagem com valores de pixel aleatórios.

Recomendamos começar com um valor de referência. É possível alterar o valor de referência ou usar vários, se for necessário. Veja exemplos de como ajustar o valor de referência.

Como definir configurações de visualização para dados de imagem

Se estiver trabalhando com dados de imagem, será possível configurar como os resultados de explicação serão exibidos adicionando uma configuração de visualização ao arquivo de metadados de explicação. Se você não fizer isso, o AI Explanations usará configurações padrão.

Veja exemplos das opções de visualização ou saiba mais sobre as configurações na Referência da API.

A seguir