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 umModel
. - Crie um modelo do BigQuery ML e especifique a configuração
model_registry
opcional na sintaxeCREATE MODEL
. Essa configuração registra automaticamente o modelo no Vertex AI Model Registry e configura oexplanationSpec
.
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
comotrue
.
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 omethod
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:
No método de atribuição de recursos, selecione Sampled Shapely (para modelos tabulares).
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
.Configure todos os recursos de entrada no modelo:
-
Preencha o nome do recurso de entrada.
-
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.
-
Se você estiver importando um modelo do TensorFlow, há outros campos de entrada:
Preencha o Nome do tensor de entrada.
Se aplicável, preencha o Nome do tensor de índices e/ou o Nome do tensor de forma densa.
A Modalidade não pode ser atualizada aqui. Ela é definida automaticamente como
NUMERIC
para modelos tabulares ouIMAGE
para modelos de imagem.Se aplicável, defina o campo Codificação. Se não for definido, o padrão será
IDENTITY
.Se aplicável, defina o campo Nome do grupo.
-
Se você estiver importando um modelo do TensorFlow, especifique os campos de saída:
- Defina o Nome da saída do recurso.
- Defina o Nome do tensor de saída do recurso.
- Se aplicável, defina o Mapeamento de nomes de exibição do índice.
- Se aplicável, defina a Chave de mapeamento de nome de exibição.
Clique no botão Importar quando terminar de definir as configurações de explicabilidade.
gcloud
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 arquivoexplanation-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 paraModel
.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
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:
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.
Se você estiver importando um modelo de classificação de imagem:
Defina o Tipo de visualização e o Mapa de cores.
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.
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
.Configure todos os recursos de entrada no modelo:
-
Preencha o nome do recurso de entrada.
-
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.
-
Se você estiver importando um modelo do TensorFlow, há outros campos de entrada:
Preencha o Nome do tensor de entrada.
Se aplicável, preencha o Nome do tensor de índices e/ou o Nome do tensor de forma densa.
A Modalidade não pode ser atualizada aqui. Ela é definida automaticamente como
NUMERIC
para modelos tabulares ouIMAGE
para modelos de imagem.Se aplicável, defina o campo Codificação. Se não for definido, o padrão será
IDENTITY
.Se aplicável, defina o campo Nome do grupo.
-
Se você estiver importando um modelo do TensorFlow, especifique os campos de saída:
- Defina o Nome da saída do recurso.
- Defina o Nome do tensor de saída do recurso.
- Se aplicável, defina o Mapeamento de nomes de exibição do índice.
- Se aplicável, defina a Chave de mapeamento de nome de exibição.
Clique no botão Importar quando terminar de definir as configurações de explicabilidade.
gcloud
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 arquivoexplanation-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
seModel
aceitar imagens como entrada ounumeric
seModel
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 campomodality
comonumeric
, omita o campovisualization
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 paraModel
.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
seModel
aceitar imagens como entrada ounumeric
seModel
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 campomodality
comonumeric
, omita o campovisualization
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
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:
No método de atribuição de recursos, selecione XRAI (para modelos de classificação de imagem).
Defina as seguintes opções de visualização:
Defina o Mapa de cores.
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.
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
.Configure todos os recursos de entrada no modelo:
-
Preencha o nome do recurso de entrada.
-
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.
-
Se você estiver importando um modelo do TensorFlow, há outros campos de entrada:
Preencha o Nome do tensor de entrada.
Se aplicável, preencha o Nome do tensor de índices e/ou o Nome do tensor de forma densa.
A Modalidade não pode ser atualizada aqui. Ela é definida automaticamente como
NUMERIC
para modelos tabulares ouIMAGE
para modelos de imagem.Se aplicável, defina o campo Codificação. Se não for definido, o padrão será
IDENTITY
.Se aplicável, defina o campo Nome do grupo.
-
Se você estiver importando um modelo do TensorFlow, especifique os campos de saída:
- Defina o Nome da saída do recurso.
- Defina o Nome do tensor de saída do recurso.
- Se aplicável, defina o Mapeamento de nomes de exibição do índice.
- Se aplicável, defina a Chave de mapeamento de nome de exibição.
Clique no botão Importar quando terminar de definir as configurações de explicabilidade.
gcloud
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 arquivoexplanation-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 paraModel
.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
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:
No método de atribuição de recursos, selecione Sampled Shapely (para modelos tabulares).
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
.Configure todos os recursos de entrada no modelo:
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.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.
Defina o Nome da saída do recurso.
Clique no botão Importar quando terminar de definir as configurações de explicabilidade.
gcloud
Grave o seguinte
ExplanationMetadata
em um arquivo JSON no seu ambiente local. O nome de arquivo não importa, mas, neste exemplo, chame o arquivoexplanation-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.
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
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:
No método de atribuição de recursos, selecione Sampled Shapely (para modelos tabulares).
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
.Configure todos os recursos de entrada no modelo:
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.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.
Defina o Nome da saída do recurso.
Clique no botão Importar quando terminar de definir as configurações de explicabilidade.
gcloud
Grave o seguinte
ExplanationMetadata
em um arquivo JSON no seu ambiente local. O nome de arquivo não importa, mas, neste exemplo, chame o arquivoexplanation-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 paraModel
.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.
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
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