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:

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:

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:

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:

    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:

    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:

    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:

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

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

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:

    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:

    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:

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

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

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:

    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:

    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:

    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:

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

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

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.

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:

    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:

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

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

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.

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.

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:

    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

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

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