Como usar o AI Explanations com o AI Platform Prediction

Este é um guia geral sobre como implantar e usar um modelo no AI Platform Prediction com o AI Explanations.

Antes de começar

É necessário realizar várias etapas antes de treinar e implantar um modelo no AI Platform:

  • Configure o ambiente de desenvolvimento local.
  • Configure um projeto do GCP com faturamento e ative as APIs necessárias.
  • Crie um bucket do Cloud Storage para armazenar o pacote de treinamento e o modelo treinado.

Para configurar seu projeto do GCP, siga as instruções fornecidas nos notebooks de exemplo.

Como salvar um modelo

As versões 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 do TensorFlow são compatíveis. Use tf.saved_model.save para salvar modelos no TensorFlow 2.11, mas não para o TensorFlow 1.15.

Saiba mais sobre como salvar modelos para usar com o AI Explanations e como usar o SDK da Explainable AI.

Arquivo de metadados de explicações

Antes de implantar o modelo, é preciso enviar um arquivo de metadados com informações sobre as entradas, as saídas e o valor de referência do seu modelo. Assim, o AI Explanations fornecerá explicações sobre as partes corretas do modelo.

Recomendamos usar o SDK do Explainable AI para descobrir automaticamente as entradas e saídas do seu modelo. Na maioria dos casos, isso economiza tempo e esforço, já que o SDK do Explainable AI cria e faz upload do arquivo de metadados de explicação para você.

Como criar manualmente o arquivo de metadados de explicação

Se você tiver um caso de uso avançado, talvez prefira especificar manualmente as entradas e saídas do modelo. Para criar manualmente seu arquivo de metadados de explicação, siga estas etapas:

O exemplo a seguir mostra a aparência de um arquivo 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"
}

Neste exemplo, "data" e "duration" são nomes significativos para os tensores de entrada e saída que podem ser atribuídos no processo de criação e treinamento do modelo. Os nomes reais dos tensores de entrada e saída seguem o formato name:index. Por exemplo, x:0 ou Placeholder:0.

Para input_baselines, comece especificando uma linha de base. Neste exemplo, [0] representa uma imagem totalmente em preto. É possível especificar vários valor de referência para fornecer informações adicionais. Saiba mais sobre ajuste das linhas de base.

Como localizar nomes de tensores de entrada e saída manualmente

Na maioria dos casos, é possível usar o SDK do Explainable AI para gerar as entradas e saídas do modelo. Você só precisará encontrar manualmente os nomes de tensores de entrada e saída se estiver usando um modelo pré-treinado do TensorFlow 1.15.

A melhor maneira de encontrar os nomes de tensores de entrada e saída depende dos tipos de dados de entrada e saída, e também de como você cria o modelo. Para uma explicação mais detalhada de cada caso, bem como ver exemplos, consulte o guia sobre [Noções básicas sobre entradas e saídas][understanding-inputs-outputs].

Tipos de dados de entrada Tipo de dados de saída Outros critérios Abordagens recomendadas
Numérico ou string Numérico As entradas não estão em formato serializado. As saídas não são dados numéricos tratados como dados categóricos (por exemplo, códigos de classe numérica). Use a CLI do SavedModel para encontrar os nomes dos tensores de entrada e saída. Como alternativa, crie o arquivo de metadados de explicação enquanto treina e salva o modelo, quando o programa ou ambiente ainda tem acesso ao código de treinamento.
Todos os dados serializados Tudo Adicione uma operação de análise do TensorFlow à função de entrada de serviço quando você exportar o modelo. Use a saída da operação de análise para ajudar a identificar os tensores de entrada.
Tudo Tudo O modelo inclui operações de pré-processamento Para saber os nomes dos tensores de entrada após as etapas de pré-processamento, use a propriedade name de tf.Tensor.
Tudo Não são probabilidades, logits ou outros tipos de tensores de ponto flutuante Você quer ter explicações para saídas que não sejam probabilidades, logits ou outros tipos de tensores de ponto flutuante. Inspecione seu gráfico com o TensorBoard para encontrar os tensores de saída corretos.
Todos os dados não diferenciais Tudo Você quer usar gradientes integrados, que exigem entradas diferenciais. Codifique entradas não diferenciais como tensores diferenciais. Adicione os nomes dos tensores de entrada original e codificado ao arquivo de metadados de explicação.

Implantar modelos e versões

O AI Platform Prediction organiza seus modelos treinados usando recursos de model e model. Um modelo do AI Platform Prediction é um contêiner para as versões do seu modelo de machine learning.

Para implantar um modelo, crie no AI Platform Prediction um recurso e uma versão desse modelo. Depois, vincule essa versão ao arquivo de modelo armazenado no Cloud Storage.

Criar um recurso de modelo

O AI Platform Prediction usa recursos de modelo para organizar versões diferentes do seu modelo.

Crie um recurso de modelo para as versões de modelo. Neste comando da Google Cloud CLI, substitua MODEL_NAME pelo nome desejado para o modelo. O nome do modelo precisa começar com uma letra e conter apenas letras, números e sublinhados.

Você precisa criar seu modelo em um endpoint regional para usar o AI Explanations.

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

Consulte a API de modelo do AI Platform Prediction para mais detalhes.

Criar uma versão de modelo

Agora você está pronto para criar uma versão do modelo com o modelo treinado enviado anteriormente para o Cloud Storage. Ao criar uma versão, especifique os seguintes parâmetros:

  • name: precisa ser exclusivo no modelo do AI Platform Prediction.
  • deploymentUri: o caminho para o diretório do SavedModel no Cloud Storage.
  • framework (obrigatório): somente tensorflow
  • runtimeVersion: use qualquer uma das versões de ambiente de execução a seguir compatíveis com o 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: use "3.7" para as versões de ambiente de execução 1.15 e posteriores.
  • machineType (obrigatório): o tipo de máquina virtual que o AI Platform Prediction usa para os nós que exibem previsões e explicações. Selecione um tipo de máquina compatível com o AI Explanations.
  • explanation-method: o tipo de método de atribuição de recurso a ser usado (sampled-shapley, integrated-gradients ou xrai).
  • Caminhos ou etapas: use --num-paths para amostra de Shapley e use --num-integral-steps para gradientes integrados ou XRAI.

Veja mais informações sobre cada um desses parâmetros em API AI Platform Training and Prediction para um recurso de versão.

  1. Defina variáveis de ambiente para armazenar o caminho para o diretório do Cloud Storage em que o SavedModel está localizado, o nome do modelo, o nome da versão e a opção de framework.

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

  2. Crie a versão:

    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

    A criação da versão leva alguns minutos. Quando ela estiver pronta, você verá a resposta abaixo:

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

  3. Verifique o status da implantação do modelo e confirme se o modelo foi implantado corretamente:

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

    Verifique se o estado é READY. A resposta será parecida com esta:

    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

Tipos de máquina compatíveis para explicações

Para solicitações do AI Explanations, implante a versão do seu modelo com um dos tipos de máquina a seguir. Se você não especificar um tipo de máquina, a implantação falhará.

Veja na tabela a seguir uma comparação dos tipos de máquina disponíveis:

Nome vCPUs Memória (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

Esses tipos de máquinas estão disponíveis somente em endpoints regionais. Saiba mais sobre a compatibilidade com outros recursos do AI Platform Prediction.

Saiba mais sobre os preços de cada tipo de máquina. Leia mais sobre as especificações detalhadas dos tipos de máquina N1 do Compute Engine na documentação relacionada.

Formatar dados de entrada

O formato básico da previsão on-line é uma lista de instâncias de dados. Ela pode ser uma lista simples de valores ou membros de um objeto JSON, dependendo de como você configurou as entradas no aplicativo de treinamento. Saiba como formatar entradas complexas e dados binários para previsão.

Este exemplo mostra um Tensor de entrada e uma chave de instância para a um modelo do TensorFlow:

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

A composição da string JSON pode ser complexa, contanto que siga estas regras:

  • O nível superior dos dados da instância precisa ser um objeto JSON, um dicionário de pares de chave-valor.

  • Os valores individuais em um objeto de instância podem ser strings, números ou listas. Não é possível incorporar objetos JSON.

  • As listas devem conter apenas itens do mesmo tipo (incluindo outras listas). Não é possível misturar strings e valores numéricos.

Você passa as instâncias de entrada de previsão on-line como o corpo da mensagem para a chamada projects.explain. Saiba mais sobre os requisitos de formatação do corpo da solicitação de previsão.

  1. Para enviar sua solicitação com gcloud, verifique se o arquivo de entrada é um arquivo JSON delimitado por linha nova, com cada instância como um objeto JSON, uma instância por linha.

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

Solicitar previsões e explicações

Solicite suas previsões e explicações:

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

Compreender a resposta de explicações

Depois de implantar o modelo, use o SDK de Explainable AI para solicitar explicações e visualizar os resultados de atribuição de recursos para dados tabulares e de imagem:

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()

Para modelos tabulares, as atribuições são traçadas em um gráfico de barras. Para modelos de imagem, as atribuições são exibidas na imagem de entrada, usando as mesmas configurações de visualização especificadas quando você implantou o modelo.

Para detalhes sobre cada campo na resposta de explicações, consulte a resposta de exemplo completa na referência da API.

Saiba como analisar a resposta das explicações consultando os notebooks de exemplo:

TensorFlow 2:

TensorFlow 1.15:

Verificar suas explicações

O exemplo de código a seguir ajuda você a verificar um lote de explicações e ver se precisa ajustar os valores de referência.

No código, só é preciso atualizar o valor da chave de entrada de acordo com o que foi especificado por você no arquivo explanation_metadata.json.

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

Por exemplo, se o valor da chave de entrada for "data", o mesmo valor será "data" na linha 4 do snippet de código a seguir:

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.')

Ao analisar as explicações, é possível executar estas verificações em cada atribuição que recebeu:

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

Como usar o erro de aproximação para melhorar os resultados

Os métodos de atribuição do AI Explanations (amostrados por Shapley, gradientes integrados e XRAI) são baseados em variantes de valores de Shapley. Como os valores de Shapley são computacionalmente caros, o AI Explanations fornece aproximações em vez dos valores exatos. Junto com os resultados da atribuição de atributos, o AI Explanations também retorna um erro de aproximação. Se o erro de aproximação for maior que 0,05, ajuste as entradas para reduzí-lo.

É possível reduzir o erro de aproximação e se aproximar dos valores exatos alterando as seguintes entradas:

  • aumentando o número de etapas integrais ou o número de caminhos;
  • alterando a linha de base de entrada que você selecionou;
  • adicionando mais linhas de base de entrada. Com os gradientes integrados e os métodos de XRAI, o uso de linhas de base extras aumenta a latência. Usar linhas de base extras com o método Sampled Shapley não aumenta a latência.

Como aumentar etapas ou caminhos

Para reduzir o erro de aproximação, aumente:

  • o número de caminhos para o Sampled Shapley;
  • o número de etapas integrais para gradientes integrados ou XRAI.

Você define esses parâmetros quando cria um recurso de versão durante a implantação do modelo.

Como ajustar as linhas de base

É possível definir as input_baselines no seu arquivo explanation_metadata.json. Esta seção fornece exemplos de dados tabulares e de imagem. As linhas de base de entrada podem representar valores médios, mínimos, máximos ou aleatórios em relação aos dados de treinamento.

Em geral:

  • comece com uma linha de base que representa valores médios;
  • altere essa linha de base para uma representando valores aleatórios;
  • tente duas linhas de base, representando os valores mínimo e máximo;
  • adicione outra linha de base que representa valores aleatórios.

Exemplo de dados tabulares

O código Python a seguir cria o conteúdo de um arquivo de metadados de explicação para dados tabulares. É possível usar Sampled Shapley ou gradientes integrados para conseguir atribuições de recursos para dados tabulares. Esse código faz parte do notebook de exemplo para dados tabulares.

Observe que input_baselines é uma lista na qual é possível especificar várias linhas de base. Este exemplo define apenas uma linha de base. A linha de base é uma lista de valores médios para os dados de treinamento (train_data neste exemplo).

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"
  }

Para definir duas linhas de base que representam valores mínimo e máximo, defina input_baselines da seguinte forma: [train_data.min().values.tolist(), train_data.max().values.tolist()]

Exemplo de dados de imagem

O código Python a seguir cria o conteúdo de um arquivo de metadados de explicação para dados de imagem. É possível usar gradientes integrados para conseguir atribuições de recursos para dados de imagem. Esse código faz parte do notebook de exemplo para dados de imagem.

Observe que input_baselines é uma lista na qual é possível especificar várias linhas de base. Este exemplo define apenas uma linha de base. A linha de base é uma lista de valores aleatórios. Usar valores aleatórios para uma linha de base de imagem é uma boa abordagem se as imagens em seu conjunto de dados de treinamento tiverem muito preto e branco.

Caso contrário, defina input_baselines como [0, 1] para representar imagens em preto e branco.

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"
  }

A seguir