Configurar explicações com base em recursos

Para usar a Vertex Explainable AI com um modelo treinado de forma personalizada, é necessário configurar determinadas opções ao criar o recurso Model do qual você quer solicitar explicações, ao implantar o modelo ou ao enviar um job de explicação em lote. Nesta página, descrevemos a configuração dessas opções.

Se você quiser usar o Vertex Explainable AI com um modelo tabular do AutoML, não será necessário realizar nenhuma configuração. O Vertex AI configura automaticamente o modelo para o Vertex Explainable AI. Pule este documento e leia Como receber explicações.

Quando e onde configurar as explicações

Você configura as explicações ao criar ou importar um modelo. Também é possível configurar explicações em um modelo que você já criou, mesmo que não tenha configurado as explicações anteriormente.

Configurar explicações ao criar ou importar modelos

Ao criar ou importar um Model, é possível definir uma configuração padrão para todas as explicações usando o campo explanationSpec do Model.

É possível criar um Model treinado de maneira personalizada na Vertex AI das seguintes maneiras:

• Importe ou registre um Model no Registro de Modelo da Vertex AI
• Crie um recurso TrainingPipeline personalizado que importe um Model.
• Crie um modelo do BigQuery ML e especifique a configuração model_registry opcional na sintaxe CREATE MODEL. Essa configuração registra automaticamente o modelo no Vertex AI Model Registry e configura o explanationSpec.

Em ambos os casos, você pode configurar o Model para que seja compatível com a Vertex Explainable AI. Os exemplos neste documento presumem que você está importando um Model. Para configurar o Vertex Explainable AI ao criar um Model com treinamento personalizado usando um TrainingPipeline, use as definições de configuração descritas neste documento no campo modelToUpload do TrainingPipeline.

Configurar explicações ao implantar modelos ou receber previsões em lote

Ao implantar um Model em um recurso Endpoint, é possível fazer o seguinte:

• Configurar as explicações, independentemente de o modelo ter sido configurado anteriormente para explicações. Isso é útil se você não pretendia originalmente receber explicações (e omitiu explanationSpec quando criou o modelo), mas depois decide que quer explicações no modelo ou se quer substituir algumas das configurações.
• Desativar as explicações. Isso é útil quando o modelo está configurado para explicações, mas você não planeja receber explicações do endpoint. Para desativar as explicações ao implantar o modelo em um endpoint, desmarque as opções de explicação no Console do Cloud ou defina DeployedModel.disableExplanations como true.

Da mesma forma, ao receber previsões em lote de uma Model, você pode configurar as explicações preenchendo o campo BatchPredictionJob.explanationSpec ou desativar as explicações definindo BatchPredictionJob.generateExplanation como false.

Substituir a configuração ao receber explicações on-line

Independentemente de você ter criado ou importado o Model com configurações de explicação e independentemente de ter definido as configurações de explicação durante a implantação, é possível substituir as configurações iniciais de explicação do Model ao receber explicações on-line.

Ao enviar uma solicitação explain para a Vertex AI, é possível substituir algumas das configurações de explicação que você definiu anteriormente para Model ou DeployedModel.

Na solicitação explain, é possível modificar os seguintes campos:

• Linhas de base de entrada para qualquer modelo treinado de forma personalizada;
• Configuração de visualização para modelos de imagem;
• ExplanationParameters exceto para o method

Substitua essas configurações no campo explanationSpecOverride da solicitação de explicação.

Importar um modelo com um campo explanationSpec

Se você exibe previsões usando umcontêiner pré-criado ou um contêiner personalizado, especifique detalhes um pouco diferentes para a ExplanationSpec. Selecione a guia que corresponde ao contêiner que você está usando:

Contêiner pré-criado do TensorFlow

É possível usar qualquer um dos seguintes métodos de atribuição para o Vertex Explainable AI. Leia a comparação de métodos de atribuição de recursos para selecionar a opção adequada para sua Model:

Os exemplos a seguir presumem que o modelo aceita um único recurso de entrada. Esse costuma ser o caso de modelos Keras sequenciais e muitos outros modelos do TensorFlow. Como o recurso é um tensor de qualquer forma, ele pode codificar muitas informações. Quando você solicita as explicações, a Vertex Explainable AI fornece atribuições para cada elemento do tensor.

Se o modelo aceitar vários tensores de entrada nomeados, adicione entradas correspondentes ao campo inputs.

Para modelos do TensorFlow 2, ExplanationMetadata é opcional. Se omitido, a Vertex AI infere automaticamente os valores do modelo e usa os nomes de tensores como nomes de recursos. Este notebook demonstra como importar um modelo sem ExplanationMetadata.

Amostragem de Shapley

Dependendo de qual ferramenta você quer usar para criar ou importar o Model, selecione uma das seguintes guias:

Console

Siga o guia para importar um modelo usando o Console do Google Cloud. Quando você chegar à etapa de Explicabilidade, faça o seguinte:

1. No método de atribuição de recursos, selecione Sampled Shapely (para modelos tabulares).

2. Defina a contagem de caminhos como o número de permutações de recursos a ser usado no método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

   Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

3. Configure todos os recursos de entrada no modelo:

   Observação: para modelos do TensorFlow 2, o nome do atributo de entrada é opcional.

   1. Preencha o nome do recurso de entrada.

   2. Opcionalmente, é possível adicionar um ou mais valores de referência de entrada. Caso contrário, a Vertex Explainable AI vai escolher um valor de referência de entrada padrão de valores zero, que é uma imagem preta para dados de imagem.

   3. Se você estiver importando um modelo do TensorFlow, há outros campos de entrada:

      1. Preencha o Nome do tensor de entrada.

      2. Se aplicável, preencha o Nome do tensor de índices e/ou o Nome do tensor de forma densa.

      3. A Modalidade não pode ser atualizada aqui. Ela é definida automaticamente como NUMERIC para modelos tabulares ou IMAGE para modelos de imagem.

      4. Se aplicável, defina o campo Codificação. Se não for definido, o padrão será IDENTITY.

      5. Se aplicável, defina o campo Nome do grupo.

4. Se você estiver importando um modelo do TensorFlow, especifique os campos de saída:

   1. Defina o Nome da saída do recurso.
   2. Defina o Nome do tensor de saída do recurso.
   3. Se aplicável, defina o Mapeamento de nomes de exibição do índice.
   4. Se aplicável, defina a Chave de mapeamento de nome de exibição.

5. Clique no botão Importar quando terminar de definir as configurações de explicabilidade.

gcloud

1. Para o TensorFlow 2, ExplanationMetadata é opcional.

   Grave o seguinte ExplanationMetadata em um arquivo JSON no seu ambiente local. O nome de arquivo não importa, mas, neste exemplo, chame o arquivo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   Substitua:

   • FEATURE_NAME: qualquer nome memorável para o recurso de entrada.
   • INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.
   • OUTPUT_NAME: qualquer nome memorável para a saída do modelo.
   • OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.

   Se quiser, adicione valores de referência à ExplanationMetadata. Caso contrário, a Vertex AI escolhe valores de referência para Model.

2. Execute o seguinte comando para criar um recurso Model compatível com o Vertex Explainable AI. As sinalizações mais pertinentes à Vertex Explainable AI são destacadas.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Substitua:

   • IMAGE_URI: o URI de um contêiner pré-criado do TensorFlow para exibir previsões.

   • PATH_COUNT: o número de permutações de recursos a ser usado para o método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

     Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

   Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• IMAGE_URI: o URI de um contêiner pré-criado do TensorFlow para exibir previsões.

• PATH_COUNT: o número de permutações de recursos a ser usado para o método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

  Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

• FEATURE_NAME: qualquer nome memorável para o recurso de entrada.
• INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.
• OUTPUT_NAME: qualquer nome memorável para a saída do modelo.
• OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.

Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

Se quiser, adicione valores de referência à ExplanationMetadata. Caso contrário, a Vertex AI escolhe valores de referência para Model.

Para modelos do TensorFlow 2, o campo metadata é opcional. Se omitido, a Vertex AI infere automaticamente o inputs e o outputs do modelo.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON da solicitação:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "sampledShapleyAttribution": {
          "pathCount": PATH_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Gradientes integrados

Dependendo de qual ferramenta você quer usar para criar ou importar o Model, selecione uma das seguintes guias:

Console

Siga o guia para importar um modelo usando o Console do Google Cloud. Quando você chegar à etapa de Explicabilidade, faça o seguinte:

1. No método de atribuição de recursos, selecione Gradientes integrados (para modelos tabulares) ou Gradientes integrados (para modelos de classificação de imagem), dependendo de qual for mais apropriado para seu modelo.

2. Se você estiver importando um modelo de classificação de imagem:

   1. Defina o Tipo de visualização e o Mapa de cores.

   2. Você pode deixar o Clipe abaixo, o Clipe acima, o Tipo de substituição e o Número de etapas integrais nas configurações padrão.

   Saiba mais sobre as configurações de visualização.

3. Defina o número de etapas a serem usadas para aproximar o valor integral do caminho durante a atribuição de recursos. Precisa ser um número inteiro no intervalo [1, 100].

   Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 50.

4. Configure todos os recursos de entrada no modelo:

   Observação: para modelos do TensorFlow 2, o nome do atributo de entrada é opcional.

   1. Preencha o nome do recurso de entrada.

   2. Opcionalmente, é possível adicionar um ou mais valores de referência de entrada. Caso contrário, a Vertex Explainable AI vai escolher um valor de referência de entrada padrão de valores zero, que é uma imagem preta para dados de imagem.

   3. Se você estiver importando um modelo do TensorFlow, há outros campos de entrada:

      1. Preencha o Nome do tensor de entrada.

      2. Se aplicável, preencha o Nome do tensor de índices e/ou o Nome do tensor de forma densa.

      3. A Modalidade não pode ser atualizada aqui. Ela é definida automaticamente como NUMERIC para modelos tabulares ou IMAGE para modelos de imagem.

      4. Se aplicável, defina o campo Codificação. Se não for definido, o padrão será IDENTITY.

      5. Se aplicável, defina o campo Nome do grupo.

5. Se você estiver importando um modelo do TensorFlow, especifique os campos de saída:

   1. Defina o Nome da saída do recurso.
   2. Defina o Nome do tensor de saída do recurso.
   3. Se aplicável, defina o Mapeamento de nomes de exibição do índice.
   4. Se aplicável, defina a Chave de mapeamento de nome de exibição.

6. Clique no botão Importar quando terminar de definir as configurações de explicabilidade.

gcloud

1. Para o TensorFlow 2, ExplanationMetadata é opcional.

   Grave o seguinte ExplanationMetadata em um arquivo JSON no seu ambiente local. O nome de arquivo não importa, mas, neste exemplo, chame o arquivo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
         "modality": "MODALITY",
         "visualization": VISUALIZATION_SETTINGS
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   Substitua:

   • FEATURE_NAME: qualquer nome memorável para o recurso de entrada.
   • INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.
   • MODALITY: image se Model aceitar imagens como entrada ou numeric se Model aceitar dados tabulares como entrada. O padrão é numeric.

   • VIZUALIZATION_OPTIONS: opções para visualizar explicações. Para saber como preencher esse campo, leia Como definir configurações de visualização para dados de imagem.

     Se você omitir o campo modality ou definir o campo modality como numeric, omita o campo visualization por completo.

   • OUTPUT_NAME: qualquer nome memorável para a saída do modelo.
   • OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.

   Se quiser, adicione valores de referência à ExplanationMetadata. Caso contrário, a Vertex AI escolhe valores de referência para Model.

2. Execute o seguinte comando para criar um recurso Model compatível com o Vertex Explainable AI. As sinalizações mais pertinentes à Vertex Explainable AI são destacadas.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=integrated-gradients \
     --explanation-step-count=STEP_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Substitua:

   • IMAGE_URI: o URI de um contêiner pré-criado do TensorFlow para exibir previsões.
   • STEP_COUNT: o número de etapas a serem usadas para aproximar o caminho do caminho durante a atribuição de atributos. Precisa ser um número inteiro no intervalo [1, 100].

     Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 50.

   Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

   Você tem a opção de adicionar sinalizações para configurar a aproximação de gradientes suaves.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• IMAGE_URI: o URI de um contêiner pré-criado do TensorFlow para exibir previsões.
• STEP_COUNT: o número de etapas a serem usadas para aproximar o caminho do caminho durante a atribuição de atributos. Precisa ser um número inteiro no intervalo [1, 100].

  Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 50.

• FEATURE_NAME: qualquer nome memorável para o recurso de entrada.
• INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.
• MODALITY: image se Model aceitar imagens como entrada ou numeric se Model aceitar dados tabulares como entrada. O padrão é numeric.

• VIZUALIZATION_OPTIONS: opções para visualizar explicações. Para saber como preencher esse campo, leia Como definir configurações de visualização para dados de imagem.

  Se você omitir o campo modality ou definir o campo modality como numeric, omita o campo visualization por completo.

• OUTPUT_NAME: qualquer nome memorável para a saída do modelo.
• OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.

Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

Se quiser, adicione valores de referência à ExplanationMetadata. Caso contrário, a Vertex AI escolhe valores de referência para Model.

Como opção, é possível adicionar campos para configurar a aproximação de SmoothGrade dos gradientes com o ExplanationParameters.

Para modelos do TensorFlow 2, o campo metadata é opcional. Se omitido, a Vertex AI infere automaticamente o inputs e o outputs do modelo.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON da solicitação:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "integratedGradientsAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "MODALITY",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

XRAI

Dependendo de qual ferramenta você quer usar para criar ou importar o Model, selecione uma das seguintes guias:

Console

Siga o guia para importar um modelo usando o Console do Google Cloud. Quando você chegar à etapa de Explicabilidade, faça o seguinte:

1. No método de atribuição de recursos, selecione XRAI (para modelos de classificação de imagem).

2. Defina as seguintes opções de visualização:

   1. Defina o Mapa de cores.

   2. Você pode deixar o Clipe abaixo, o Clipe acima, o Tipo de substituição e o Número de etapas integrais nas configurações padrão.

      Saiba mais sobre as configurações de visualização.

3. Defina o número de etapas a serem usadas para aproximar o valor integral do caminho durante a atribuição de recursos. Precisa ser um número inteiro no intervalo [1, 100].

   Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 50.

4. Configure todos os recursos de entrada no modelo:

   Observação: para modelos do TensorFlow 2, o nome do atributo de entrada é opcional.

   1. Preencha o nome do recurso de entrada.

   2. Opcionalmente, é possível adicionar um ou mais valores de referência de entrada. Caso contrário, a Vertex Explainable AI vai escolher um valor de referência de entrada padrão de valores zero, que é uma imagem preta para dados de imagem.

   3. Se você estiver importando um modelo do TensorFlow, há outros campos de entrada:

      1. Preencha o Nome do tensor de entrada.

      2. Se aplicável, preencha o Nome do tensor de índices e/ou o Nome do tensor de forma densa.

      3. A Modalidade não pode ser atualizada aqui. Ela é definida automaticamente como NUMERIC para modelos tabulares ou IMAGE para modelos de imagem.

      4. Se aplicável, defina o campo Codificação. Se não for definido, o padrão será IDENTITY.

      5. Se aplicável, defina o campo Nome do grupo.

5. Se você estiver importando um modelo do TensorFlow, especifique os campos de saída:

   1. Defina o Nome da saída do recurso.
   2. Defina o Nome do tensor de saída do recurso.
   3. Se aplicável, defina o Mapeamento de nomes de exibição do índice.
   4. Se aplicável, defina a Chave de mapeamento de nome de exibição.

6. Clique no botão Importar quando terminar de definir as configurações de explicabilidade.

gcloud

1. Para o TensorFlow 2, ExplanationMetadata é opcional.

   Grave o seguinte ExplanationMetadata em um arquivo JSON no seu ambiente local. O nome de arquivo não importa, mas, neste exemplo, chame o arquivo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
         "modality": "image",
         "visualization": VISUALIZATION_SETTINGS
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   Substitua:

   • FEATURE_NAME: qualquer nome memorável para o recurso de entrada.
   • INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.
   • VIZUALIZATION_OPTIONS: opções para visualizar explicações. Para saber como preencher esse campo, leia Como definir configurações de visualização para dados de imagem.
   • OUTPUT_NAME: qualquer nome memorável para a saída do modelo.
   • OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.

   Se quiser, adicione valores de referência à ExplanationMetadata. Caso contrário, a Vertex AI escolhe valores de referência para Model.

2. Execute o seguinte comando para criar um recurso Model compatível com o Vertex Explainable AI. As sinalizações mais pertinentes à Vertex Explainable AI são destacadas.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=xrai \
     --explanation-step-count=STEP_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Substitua:

   • IMAGE_URI: o URI de um contêiner pré-criado do TensorFlow para exibir previsões.
   • STEP_COUNT: o número de etapas a serem usadas para aproximar o caminho do caminho durante a atribuição de atributos. Precisa ser um número inteiro no intervalo [1, 100].

     Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 50.

   Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

   Você tem a opção de adicionar sinalizações para configurar a aproximação de gradientes suaves.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• IMAGE_URI: o URI de um contêiner pré-criado do TensorFlow para exibir previsões.
• STEP_COUNT: o número de etapas a serem usadas para aproximar o caminho do caminho durante a atribuição de atributos. Precisa ser um número inteiro no intervalo [1, 100].

  Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 50.

• FEATURE_NAME: qualquer nome memorável para o recurso de entrada.
• INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.
• VIZUALIZATION_OPTIONS: opções para visualizar explicações. Para saber como preencher esse campo, leia Como definir configurações de visualização para dados de imagem.
• OUTPUT_NAME: qualquer nome memorável para a saída do modelo.
• OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto desse campo, leia Como usar o TensorFlow com Vertex Explainable AI.

Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

Se quiser, adicione valores de referência à ExplanationMetadata. Caso contrário, a Vertex AI escolhe valores de referência para Model.

Como opção, é possível adicionar campos para configurar a aproximação de SmoothGrade dos gradientes com o ExplanationParameters.

Para modelos do TensorFlow 2, o campo metadata é opcional. Se omitido, a Vertex AI infere automaticamente o inputs e o outputs do modelo.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON da solicitação:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "xraiAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "image",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Contêineres pré-criados scikit-learn e XGBoost

Se o Model aceitar dados tabulares como entrada e exibir previsões usando um contêiner predefinido scikit-learn ou XGBoost para previsão, será possível configurá-lo para usar o método de atribuição Sampled Shapley para explicações.

Nos exemplos a seguir, supomos que seu modelo aceita uma única matriz 2-D como entrada. Isso geralmente acontece com modelos scikit-learn e XGBoost. Quando você solicita explicações, a Vertex Explainable AI fornece atribuições para cada elemento da matriz de entrada.

Dependendo de qual ferramenta você quer usar para criar ou importar o Model, selecione uma das seguintes guias:

Console

Siga o guia para importar um modelo usando o Console do Google Cloud. Quando você chegar à etapa de Explicabilidade, faça o seguinte:

1. No método de atribuição de recursos, selecione Sampled Shapely (para modelos tabulares).

2. Defina a contagem de caminhos como o número de permutações de recursos a ser usado no método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

   Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

3. Configure todos os recursos de entrada no modelo:

   1. Preencha o nome do recurso de entrada.

      Se os artefatos do modelo não incluírem nomes de atributos, a Vertex AI não será possível mapear os nomes de atributos de entrada especificados para o modelo. Nesse caso, forneça apenas um recurso de entrada com qualquer nome arbitrário e fácil de usar, como input_features. Na resposta de explicação, você vai receber uma lista dimensional de atribuições, em que N é o número de recursos no modelo e os elementos da lista aparecem na mesma ordem que o conjunto de dados de treinamento.

   2. Opcionalmente, é possível adicionar um ou mais valores de referência de entrada. Caso contrário, a Vertex Explainable AI vai escolher um valor de referência de entrada padrão de valores zero, que é uma imagem preta para dados de imagem.

4. Defina o Nome da saída do recurso.

5. Clique no botão Importar quando terminar de definir as configurações de explicabilidade.

gcloud

1. Grave o seguinte ExplanationMetadata em um arquivo JSON no seu ambiente local. O nome de arquivo não importa, mas, neste exemplo, chame o arquivo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
       }
     }
   }
   

   Substitua:

   • FEATURE_NAME: qualquer nome memorável para o recurso de entrada.
   • OUTPUT_NAME: qualquer nome memorável para a saída do modelo.

   Se você especificar valores de referência de entrada, verifique se eles correspondem à entrada do modelo, geralmente uma lista de matrizes 2-D. Caso contrário, o valor padrão para o valor de referência da entrada é uma matriz 2-D de valor 0 da forma de entrada.

2. Execute o seguinte comando para criar um recurso Model compatível com o Vertex Explainable AI. As sinalizações mais pertinentes à Vertex Explainable AI são destacadas.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Substitua:

   • IMAGE_URI: o URI de um contêiner pré-criado do para exibir previsões.

   • PATH_COUNT: o número de permutações de recursos a ser usado para o método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

     Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

   Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• IMAGE_URI: o URI de um contêiner pré-criado do para exibir previsões.

• PATH_COUNT: o número de permutações de recursos a ser usado para o método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

  Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

• FEATURE_NAME: qualquer nome memorável para o recurso de entrada.
• OUTPUT_NAME: qualquer nome memorável para a saída do modelo.

Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

Se você especificar valores de referência de entrada, verifique se eles correspondem à entrada do modelo, geralmente uma lista de matrizes 2-D. Caso contrário, o valor padrão para o valor de referência da entrada é uma matriz 2-D de valor 0 da forma de entrada.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON da solicitação:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {
         }
       },
       "outputs": {
         "OUTPUT_NAME": {
         }
       }
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Contêiner personalizado

Se asModel aceita dados tabulares como entrada e exibe previsões usando umacontêiner personalizado, poderá configurá-la para usar a funçãoExemplo de método de atribuição Shapley para explicações.

Observação: as instruções a seguir não funcionarão se você estiver usando qualquer um dos contêineres predefinidos da Vertex AI para exibir previsões. Use uma imagem de contêiner personalizada que não seja gerenciada pela Vertex AI e que atenda aos requisitos de contêiner personalizado.

Como determinar os nomes de recursos e saídas

Nas etapas a seguir, você precisa fornecer à Vertex AI os nomes dos recursos que o Model espera como entrada. Você também precisa especificar a chave usada para saídas nas previsões do Model.

Como determinar os nomes dos recursos

Se a Model espera que cada instância de entrada tenha determinadas chaves de nível superior, essas chaves serão os nomes dos recursos.

Por exemplo, considere um Model que espera que cada instância de entrada tenha o seguinte formato:

{
  "length": <value>,
  "width": <value>
}

Neste caso, os nomes dos recursos são length e width. Mesmo que os valores desses campos contenham listas ou objetos aninhados, length e width são as únicas chaves necessárias para as etapas a seguir. Quando você solicita as explicações, a Vertex Explainable AI fornece atribuições para cada elemento aninhado dos seus recursos.

Se a Model espera uma entrada sem chave, a Vertex Explainable AI considera que Model tem um único recurso. Você pode usar qualquer string importante para o nome do recurso.

Por exemplo, considere um Model que espera que cada instância de entrada tenha o seguinte formato:

[
  <value>,
  <value>
]

Nesse caso, forneça a Vertex Explainable AI com um único nome de recurso de sua escolha, como dimensions.

Observação: os exemplos a seguir presumem que o modelo tem um único recurso de entrada. Se o modelo tiver vários atributos, conforme descrito nesta seção, adicione entradas correspondentes ao campo inputs.

Como determinar o nome da saída

Se Model retornar cada instância de previsão on-line com saída com chave, essa chave será o nome da saída.

Por exemplo, considere um Model que retorna cada previsão no seguinte formato:

{
  "scores": <value>
}

Neste caso, o nome da saída é scores. Se o valor do campo scores for uma matriz, quando você tiver explicações, a Vertex Explainable AI retornará atribuições de recurso para o elemento com o valor mais alto em cada previsão. Para configurar a Vertex Explainable AI para fornecer atribuições de recursos para elementos adicionais do campo de saída, especifique os campos topK ou outputIndices de ExplanationParameters. No entanto, os exemplos neste documento não demonstram essas opções.

Se a Model retornar previsões sem chave, você poderá usar qualquer string importante para o nome da saída. Por exemplo, isso se aplica se a Model retornar uma matriz ou um escalar para cada previsão.

Como criar o Model

Dependendo de qual ferramenta você quer usar para criar ou importar o Model, selecione uma das seguintes guias:

Console

Siga o guia para importar um modelo usando o Console do Google Cloud. Quando você chegar à etapa de Explicabilidade, faça o seguinte:

1. No método de atribuição de recursos, selecione Sampled Shapely (para modelos tabulares).

2. Defina a contagem de caminhos como o número de permutações de recursos a ser usado no método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

   Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

3. Configure todos os recursos de entrada no modelo:

   1. Preencha o nome do recurso de entrada.

      Se os artefatos do modelo não incluírem nomes de atributos, a Vertex AI não será possível mapear os nomes de atributos de entrada especificados para o modelo. Nesse caso, forneça apenas um recurso de entrada com qualquer nome arbitrário e fácil de usar, como input_features. Na resposta de explicação, você vai receber uma lista dimensional de atribuições, em que N é o número de recursos no modelo e os elementos da lista aparecem na mesma ordem que o conjunto de dados de treinamento.

   2. Opcionalmente, é possível adicionar um ou mais valores de referência de entrada. Caso contrário, a Vertex Explainable AI vai escolher um valor de referência de entrada padrão de valores zero, que é uma imagem preta para dados de imagem.

4. Defina o Nome da saída do recurso.

5. Clique no botão Importar quando terminar de definir as configurações de explicabilidade.

gcloud

1. Grave o seguinte ExplanationMetadata em um arquivo JSON no seu ambiente local. O nome de arquivo não importa, mas, neste exemplo, chame o arquivo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {}
     },
     "outputs": {
       "OUTPUT_NAME": {}
     }
   }
   

   Substitua:

   • FEATURE_NAME: o nome do recurso, conforme descrito na seção "Como determinar nomes de recurso" deste documento.
   • OUTPUT_NAME: o nome da saída, conforme descrito na seção "Como determinar o nome da saída" deste documento.

   Se quiser, adicione valores de referência à ExplanationMetadata. Caso contrário, a Vertex AI escolhe valores de referência para Model.

   Se você especificar valores de referência de entrada, verifique se eles correspondem à entrada do modelo, geralmente uma lista de matrizes 2-D. Caso contrário, o valor padrão para o valor de referência da entrada é uma matriz 2-D de valor 0 da forma de entrada.

2. Execute o seguinte comando para criar um recurso Model compatível com o Vertex Explainable AI. As sinalizações mais pertinentes à Vertex Explainable AI são destacadas.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Substitua:

   • PATH_COUNT: o número de permutações de recursos a ser usado para o método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

     Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

   Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• PATH_COUNT: o número de permutações de recursos a ser usado para o método de atribuição Sampled Shapley. Precisa ser um número inteiro no intervalo [1, 50].

  Um valor maior pode reduzir o erro de aproximação, mas é mais intensivo. Se você não souber qual valor usar, teste 25.

• FEATURE_NAME: o nome do recurso, conforme descrito na seção "Como determinar nomes de recurso" deste documento.
• OUTPUT_NAME: o nome da saída, conforme descrito na seção "Como determinar o nome da saída" deste documento.

Para saber mais sobre os valores apropriados para os outros marcadores, consulte upload e Como importar modelos.

Se quiser, adicione valores de referência à ExplanationMetadata. Caso contrário, a Vertex AI escolhe valores de referência para Model.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Corpo JSON da solicitação:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {}
       },
       "outputs": {
         "OUTPUT_NAME": {}
       }
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

A seguir

• Implante o Model em um Endpoint e receba explicações.