Configure explicações baseadas em funcionalidades

Para usar a Vertex AI explicável com um modelo preparado de forma personalizada, tem de configurar determinadas opções quando cria o recurso Model do qual planeia pedir explicações, quando implementa o modelo ou quando envia uma tarefa de explicação em lote. Esta página descreve a configuração destas opções.

Se quiser usar o Vertex Explainable AI com um modelo tabular do AutoML, não precisa de fazer nenhuma configuração. O Vertex AI configura automaticamente o modelo para o Vertex Explainable AI. Ignorar este documento e ler o artigo Receber explicações.

Quando e onde configurar as explicações

Configura as explicações quando cria ou importa um modelo. Também pode configurar explicações num modelo que já criou, mesmo que não o tenha feito anteriormente.

Configure explicações quando cria ou importa modelos

Quando cria ou importa um Model, pode definir uma configuração predefinida para todas as respetivas explicações através do campo explanationSpec do Model.

Pode criar um Model preparado de forma personalizada no Vertex AI das seguintes formas:

Em qualquer dos casos, pode configurar o Model para suportar a IA explicável do Vertex. Os exemplos neste documento pressupõem que está a importar um ficheiro Model. Para configurar o Vertex AI explicável quando cria um Model preparado de forma personalizada com um TrainingPipeline, use as definições de configuração descritas neste documento no campo modelToUpload do TrainingPipeline.

Configure explicações ao implementar modelos ou obter inferências em lote

Quando implementa um Model num recurso Endpoint, pode:

  • Configurar explicações, independentemente de o modelo ter sido configurado anteriormente para explicações. Isto é útil se não planeou originalmente receber explicações (e omitiu o campo explanationSpec quando criou o modelo), mas decidiu mais tarde que quer explicações para o modelo ou se quiser substituir algumas das definições de explicação.
  • Desative as explicações. Isto é útil se o seu modelo estiver configurado para explicações, mas não planeia receber explicações do ponto final. Para desativar as explicações quando implementar o modelo num ponto final, desmarque as opções de interpretabilidade na Cloud Console ou defina DeployedModel.disableExplanations como true.

Da mesma forma, quando obtém inferências em lote a partir de um Model, pode configurar explicações preenchendo o campo BatchPredictionJob.explanationSpec ou desativar as explicações definindo BatchPredictionJob.generateExplanation como false.

Substitua a configuração quando receber explicações online

Independentemente de ter criado ou importado as definições Model com explicação e de ter configurado as definições de explicação durante a implementação, pode substituir as definições de explicação iniciais do Model quando obtém explicações online.

Quando envia um pedido explain para o Vertex AI, pode substituir algumas das configurações de explicação que definiu anteriormente para o Model ou o DeployedModel.

Na solicitação explain, pode substituir os seguintes campos:

Substitua estas definições no campo explanationSpecOverride do pedido de explicação.

Importe um modelo com um campo explanationSpec

Consoante sirva inferências com um contentor pré-criado ou um contentor personalizado, especifique detalhes ligeiramente diferentes para o ExplanationSpec. Selecione o separador que corresponde ao contentor que está a usar:

Contentor pré-criado do TensorFlow

Pode usar qualquer um dos seguintes métodos de atribuição para o Vertex Explainable AI. Leia a comparação dos métodos de atribuição de funcionalidades para selecionar o adequado para o seu Model:

Shapley com amostragem

Consoante a ferramenta que quer usar para criar ou importar o Model, selecione um dos seguintes separadores:

Consola

Siga o guia para importar um modelo através da Google Cloud consola. Quando chegar ao passo Explicabilidade, faça o seguinte:

  1. Para o método de atribuição de funcionalidades, selecione Shapely com amostragem (para modelos tabulares).

  2. Defina a contagem de caminhos para o número de permutações de caraterísticas a usar para o método de atribuição de Shapley com amostragem. Tem de ser um número inteiro no intervalo [1, 50].

    Um valor mais elevado pode reduzir o erro de aproximação, mas é mais intensivo em termos de computação. Se não souber que valor usar, experimente 25.

  3. Configure cada funcionalidade de entrada no seu modelo:

    1. Preencha o nome da funcionalidade de entrada.

    2. Opcionalmente, pode adicionar uma ou mais referências de entrada. Caso contrário, a Vertex Explainable AI escolhe uma base de referência de entrada predefinida de valores zero, que é uma imagem preta para dados de imagem.

    3. Se estiver a importar um modelo do TensorFlow, existem campos de entrada adicionais:

      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. Não é possível atualizar a modalidade aqui. É definida automaticamente como NUMERIC para modelos tabulares ou IMAGE para modelos de imagens.

      4. Se aplicável, defina o campo Codificação. A predefinição é IDENTITY em caso de não definição.

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

  4. Se estiver a importar um modelo do TensorFlow, especifique os campos de saída:

    1. Defina o Nome de saída da sua funcionalidade.
    2. Defina o nome do tensor de saída da sua caraterística.
    3. Se aplicável, defina o mapeamento do nome a apresentar do índice.
    4. Se aplicável, defina a chave de mapeamento do nome a apresentar.

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

gcloud

  1. Para o TensorFlow 2, o ExplanationMetadata é opcional.

    Escreva o seguinte ExplanationMetadata num ficheiro JSON no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome explanation-metadata.json ao ficheiro:

    explanation-metadata.json

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

    Substitua o seguinte:

    • FEATURE_NAME: qualquer nome memorável para a sua funcionalidade de entrada.
    • INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto para este campo, leia o artigo Usar o TensorFlow com a IA explicável do Vertex.
    • OUTPUT_NAME: qualquer nome memorável para o resultado do seu modelo.
    • OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto para este campo, leia o artigo Usar o TensorFlow com a IA explicável do Vertex.

    Opcionalmente, pode adicionar linhas de base de entrada ao elemento ExplanationMetadata. Caso contrário, o Vertex AI escolhe as bases de referência de entrada para o Model.

  2. Execute o seguinte comando para criar um recurso Model que suporte a IA explicável do Vertex. As flags mais pertinentes para a Vertex Explainable AI estão realçadas. 

    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 o seguinte:

    Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

Opcionalmente, pode adicionar linhas de base de entrada ao elemento ExplanationMetadata. Caso contrário, o Vertex AI escolhe as bases de referência de entrada para o Model.

Para modelos do TensorFlow 2, o campo metadata é opcional. Se forem omitidos, o Vertex AI infere automaticamente os valores inputs e outputs do modelo.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "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 o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Consoante a ferramenta que quer usar para criar ou importar o Model, selecione um dos seguintes separadores:

Consola

Siga o guia para importar um modelo através da Google Cloud consola. Quando chegar ao passo Explicabilidade, faça o seguinte:

  1. Para o método de atribuição de funcionalidades, selecione Gradientes integrados (para modelos tabulares) ou Gradientes integrados (para modelos de classificação de imagens), consoante o que for mais adequado para o seu modelo.

  2. Se estiver a importar um modelo de classificação de imagens, faça o seguinte:

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

    2. Pode deixar as opções Clipe abaixo, Clipe acima, Tipo de sobreposição e Número de passos integrais nas respetivas definições predefinidas.

    Saiba mais acerca das definições de visualização.

  3. Defina o número de passos a usar para aproximar a integral de caminho durante a atribuição de funcionalidades. Tem de ser um número inteiro no intervalo [1, 100].

    Um valor mais elevado pode reduzir o erro de aproximação, mas é mais intensivo em termos de computação. Se não souber que valor usar, experimente 50.

  4. Configure cada funcionalidade de entrada no seu modelo:

    1. Preencha o nome da funcionalidade de entrada.

    2. Opcionalmente, pode adicionar uma ou mais referências de entrada. Caso contrário, a Vertex Explainable AI escolhe uma base de referência de entrada predefinida de valores zero, que é uma imagem preta para dados de imagem.

    3. Se estiver a importar um modelo do TensorFlow, existem campos de entrada adicionais:

      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. Não é possível atualizar a modalidade aqui. É definida automaticamente como NUMERIC para modelos tabulares ou IMAGE para modelos de imagens.

      4. Se aplicável, defina o campo Codificação. A predefinição é IDENTITY em caso de não definição.

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

  5. Se estiver a importar um modelo do TensorFlow, especifique os campos de saída:

    1. Defina o Nome de saída da sua funcionalidade.
    2. Defina o nome do tensor de saída da sua caraterística.
    3. Se aplicável, defina o mapeamento do nome a apresentar do índice.
    4. Se aplicável, defina a chave de mapeamento do nome a apresentar.

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

gcloud

  1. Para o TensorFlow 2, o ExplanationMetadata é opcional.

    Escreva o seguinte ExplanationMetadata num ficheiro JSON no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome explanation-metadata.json ao ficheiro:

    explanation-metadata.json

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

    Substitua o seguinte:

    • FEATURE_NAME: qualquer nome memorável para a sua funcionalidade de entrada.
    • INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto para este campo, leia o artigo Usar o TensorFlow com a IA explicável do Vertex.
    • MODALITY: image se o Model aceitar imagens como entrada ou numeric se o Model aceitar dados tabulares como entrada. A predefinição é numeric.

    • VIZUALIZATION_OPTIONS: opções para visualizar explicações. Para saber como preencher este campo, leia o artigo Configurar as definições de visualização para dados de imagens.

      Se omitir o campo modality ou definir o campo modality como numeric, então omita o campo visualization por completo.

    • OUTPUT_NAME: qualquer nome memorável para o resultado do seu modelo.
    • OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto para este campo, leia o artigo Usar o TensorFlow com a IA explicável do Vertex.

    Opcionalmente, pode adicionar linhas de base de entrada ao elemento ExplanationMetadata. Caso contrário, o Vertex AI escolhe as bases de referência de entrada para o Model.

  2. Execute o seguinte comando para criar um recurso Model que suporte a IA explicável do Vertex. As flags mais pertinentes para a Vertex Explainable AI estão realçadas. 

    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 o seguinte:

    Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

    Opcionalmente, pode adicionar flags para configurar a aproximação SmoothGrad dos gradientes.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • IMAGE_URI: o URI de um contentor pré-criado do TensorFlow para publicar previsões.
  • STEP_COUNT: o número de passos a usar para aproximar o integral do caminho durante a atribuição de caraterísticas. Tem de ser um número inteiro no intervalo [1, 100].

    Um valor mais elevado pode reduzir o erro de aproximação, mas é mais intensivo em termos de computação. Se não souber que valor usar, experimente 50.

  • FEATURE_NAME: qualquer nome memorável para a sua funcionalidade de entrada.
  • INPUT_TENSOR_NAME: o nome do tensor de entrada no TensorFlow. Para encontrar o valor correto para este campo, leia o artigo Usar o TensorFlow com a IA explicável do Vertex.
  • MODALITY: image se o Model aceitar imagens como entrada ou numeric se o Model aceitar dados tabulares como entrada. A predefinição é numeric.

  • VIZUALIZATION_OPTIONS: opções para visualizar explicações. Para saber como preencher este campo, leia o artigo Configurar as definições de visualização para dados de imagens.

    Se omitir o campo modality ou definir o campo modality como numeric, então omita o campo visualization por completo.

  • OUTPUT_NAME: qualquer nome memorável para o resultado do seu modelo.
  • OUTPUT_TENSOR_NAME: o nome do tensor de saída no TensorFlow. Para encontrar o valor correto para este campo, leia o artigo Usar o TensorFlow com a IA explicável do Vertex.

Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

Opcionalmente, pode adicionar linhas de base de entrada ao elemento ExplanationMetadata. Caso contrário, o Vertex AI escolhe as bases de referência de entrada para o Model.

Opcionalmente, pode adicionar campos para configurar a aproximação SmoothGrad dos gradientes ao ExplanationParameters.

Para modelos do TensorFlow 2, o campo metadata é opcional. Se forem omitidos, o Vertex AI infere automaticamente os valores inputs e outputs do modelo.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "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 o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Consoante a ferramenta que quer usar para criar ou importar o Model, selecione um dos seguintes separadores:

Consola

Siga o guia para importar um modelo através da Google Cloud consola. Quando chegar ao passo Explicabilidade, faça o seguinte:

  1. Para o método de atribuição de funcionalidades, selecione XRAI (para modelos de classificação de imagens).

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

    1. Defina o Mapa de cores.

    2. Pode deixar as opções Clipe abaixo, Clipe acima, Tipo de sobreposição e Número de passos integrais nas respetivas definições predefinidas.

      Saiba mais acerca das definições de visualização.

  3. Defina o número de passos a usar para aproximar a integral de caminho durante a atribuição de funcionalidades. Tem de ser um número inteiro no intervalo [1, 100].

    Um valor mais elevado pode reduzir o erro de aproximação, mas é mais intensivo em termos de computação. Se não souber que valor usar, experimente 50.

  4. Configure cada funcionalidade de entrada no seu modelo:

    1. Preencha o nome da funcionalidade de entrada.

    2. Opcionalmente, pode adicionar uma ou mais referências de entrada. Caso contrário, a Vertex Explainable AI escolhe uma base de referência de entrada predefinida de valores zero, que é uma imagem preta para dados de imagem.

    3. Se estiver a importar um modelo do TensorFlow, existem campos de entrada adicionais:

      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. Não é possível atualizar a modalidade aqui. É definida automaticamente como NUMERIC para modelos tabulares ou IMAGE para modelos de imagens.

      4. Se aplicável, defina o campo Codificação. A predefinição é IDENTITY em caso de não definição.

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

  5. Se estiver a importar um modelo do TensorFlow, especifique os campos de saída:

    1. Defina o Nome de saída da sua funcionalidade.
    2. Defina o nome do tensor de saída da sua caraterística.
    3. Se aplicável, defina o mapeamento do nome a apresentar do índice.
    4. Se aplicável, defina a chave de mapeamento do nome a apresentar.

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

gcloud

  1. Para o TensorFlow 2, o ExplanationMetadata é opcional.

    Escreva o seguinte ExplanationMetadata num ficheiro JSON no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome explanation-metadata.json ao ficheiro:

    explanation-metadata.json

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

    Substitua o seguinte:

    Opcionalmente, pode adicionar linhas de base de entrada ao elemento ExplanationMetadata. Caso contrário, o Vertex AI escolhe as bases de referência de entrada para o Model.

  2. Execute o seguinte comando para criar um recurso Model que suporte a IA explicável do Vertex. As flags mais pertinentes para a Vertex Explainable AI estão realçadas. 

    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 o seguinte:

    Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

    Opcionalmente, pode adicionar flags para configurar a aproximação SmoothGrad dos gradientes.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

Opcionalmente, pode adicionar linhas de base de entrada ao elemento ExplanationMetadata. Caso contrário, o Vertex AI escolhe as bases de referência de entrada para o Model.

Opcionalmente, pode adicionar campos para configurar a aproximação SmoothGrad dos gradientes ao ExplanationParameters.

Para modelos do TensorFlow 2, o campo metadata é opcional. Se forem omitidos, o Vertex AI infere automaticamente os valores inputs e outputs do modelo.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "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 o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Contentores pré-criados do scikit-learn e XGBoost

Se o seu Modelaceitar dados tabulares como entrada e fornecer previsões através de um contentor pré-criado do scikit-learn ou XGBoost para previsão, pode configurá-lo para usar o método de atribuição de Shapley com amostragem para explicações.

Consoante a ferramenta que quer usar para criar ou importar o Model, selecione um dos seguintes separadores:

Consola

Siga o guia para importar um modelo através da Google Cloud consola. Quando chegar ao passo Explicabilidade, faça o seguinte:

  1. Para o método de atribuição de funcionalidades, selecione Shapely com amostragem (para modelos tabulares).

  2. Defina a contagem de caminhos para o número de permutações de caraterísticas a usar para o método de atribuição de Shapley com amostragem. Tem de ser um número inteiro no intervalo [1, 50].

    Um valor mais elevado pode reduzir o erro de aproximação, mas é mais intensivo em termos de computação. Se não souber que valor usar, experimente 25.

  3. Configure cada funcionalidade de entrada no seu modelo:

    1. Preencha o nome da funcionalidade de entrada.

      Se os artefactos do modelo não incluírem nomes de funcionalidades, o Vertex AI não consegue mapear os nomes das funcionalidades de entrada especificados para o modelo. Nesse caso, deve fornecer apenas uma funcionalidade de entrada com qualquer nome arbitrário e fácil de usar, como input_features. Na resposta de explicação, recebe uma lista de atribuições de N dimensões, em que N é o número de caraterísticas no modelo e os elementos na lista aparecem pela mesma ordem que no conjunto de dados de preparação.

    2. Opcionalmente, pode adicionar uma ou mais referências de entrada. Caso contrário, a Vertex Explainable AI escolhe uma base de referência de entrada predefinida de valores zero, que é uma imagem preta para dados de imagem.

  4. Defina o Nome de saída da sua funcionalidade.

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

gcloud

  1. Escreva o seguinte ExplanationMetadata num ficheiro JSON no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome explanation-metadata.json ao ficheiro:

    explanation-metadata.json

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

    Substitua o seguinte:

    • FEATURE_NAME: qualquer nome memorável para a sua funcionalidade de entrada.
    • OUTPUT_NAME: qualquer nome memorável para o resultado do seu modelo.

    Se especificar input baselines, certifique-se de que correspondem à entrada do seu modelo, normalmente uma lista de matrizes 2D. Caso contrário, o valor predefinido para a base de referência de entrada é uma matriz 2D de valor 0 da forma de entrada.

  2. Execute o seguinte comando para criar um recurso Model que suporte a IA explicável do Vertex. As flags mais pertinentes para a Vertex Explainable AI estão realçadas. 

    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 o seguinte:

    Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

Se especificar input baselines, certifique-se de que correspondem à entrada do seu modelo, normalmente uma lista de matrizes 2D. Caso contrário, o valor predefinido para a base de referência de entrada é uma matriz 2D 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 do pedido: 

{
  "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 o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Contentor personalizado

Se o seu Modelaceitar dados tabulares como entrada e publicar previsões através de um contentor personalizado, pode configurá-lo para usar o método de atribuição de Shapley com amostragem para explicações.

Determinar os nomes das funcionalidades e dos resultados

Nos passos seguintes, tem de fornecer ao Vertex AI os nomes das funcionalidades que o Model espera como entrada. Também tem de especificar a chave usada para as saídas nas previsões do Model.

Determinar nomes de funcionalidades

Se o seu Model esperar que cada instância de entrada tenha determinadas chaves de nível superior, essas chaves são os nomes das suas funcionalidades.

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 das funcionalidades são length e width. Mesmo que os valores destes campos contenham listas ou objetos aninhados, length e width são as únicas chaves necessárias para os passos seguintes. Quando pede explicações, a Vertex AI Explainable AI fornece atribuições para cada elemento aninhado das suas caraterísticas.

Se o seu Model esperar uma entrada sem chave, o Vertex Explainable AI considera que o Model tem uma única funcionalidade. Pode usar qualquer string memorável para o nome da funcionalidade.

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

[
  <value>,
  <value>
]

Neste caso, forneça ao Vertex Explainable AI um único nome de funcionalidade à sua escolha, como dimensions.

Determinar o nome do resultado

Se os seus Modelretornos de cada instância de previsão online com saída com chave, essa chave é o nome da saída.

Por exemplo, considere um Model que devolve 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 obtiver explicações, o Vertex Explainable AI devolve atribuições de caraterísticas para o elemento com o valor mais elevado em cada previsão. Para configurar a IA explicável do Vertex para fornecer atribuições de caraterísticas para elementos adicionais do campo de saída, pode especificar os campos topK ou outputIndices de ExplanationParameters. No entanto, os exemplos neste documento não demonstram estas opções.

Se o seu Model devolver previsões sem chave, pode usar qualquer string memorável para o nome de saída. Por exemplo, isto aplica-se se a função Modelretornar uma matriz ou um escalar para cada previsão.

A criar o Model

Consoante a ferramenta que quer usar para criar ou importar o Model, selecione um dos seguintes separadores:

Consola

Siga o guia para importar um modelo através da Google Cloud consola. Quando chegar ao passo Explicabilidade, faça o seguinte:

  1. Para o método de atribuição de funcionalidades, selecione Shapely com amostragem (para modelos tabulares).

  2. Defina a contagem de caminhos para o número de permutações de caraterísticas a usar para o método de atribuição de Shapley com amostragem. Tem de ser um número inteiro no intervalo [1, 50].

    Um valor mais elevado pode reduzir o erro de aproximação, mas é mais intensivo em termos de computação. Se não souber que valor usar, experimente 25.

  3. Configure cada funcionalidade de entrada no seu modelo:

    1. Preencha o nome da funcionalidade de entrada.

      Se os artefactos do modelo não incluírem nomes de funcionalidades, o Vertex AI não consegue mapear os nomes das funcionalidades de entrada especificados para o modelo. Nesse caso, deve fornecer apenas uma funcionalidade de entrada com qualquer nome arbitrário e fácil de usar, como input_features. Na resposta de explicação, recebe uma lista de atribuições de N dimensões, em que N é o número de caraterísticas no modelo e os elementos na lista aparecem pela mesma ordem que no conjunto de dados de preparação.

    2. Opcionalmente, pode adicionar uma ou mais referências de entrada. Caso contrário, a Vertex Explainable AI escolhe uma base de referência de entrada predefinida de valores zero, que é uma imagem preta para dados de imagem.

  4. Defina o Nome de saída da sua funcionalidade.

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

gcloud

  1. Escreva o seguinte ExplanationMetadata num ficheiro JSON no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome explanation-metadata.json ao ficheiro:

    explanation-metadata.json

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

    Substitua o seguinte:

    • FEATURE_NAME: o nome da funcionalidade, conforme descrito na secção "Determinar nomes de funcionalidades" deste documento.
    • OUTPUT_NAME: o nome da saída, conforme descrito na secção "Determinar o nome da saída" deste documento.

    Opcionalmente, pode adicionar linhas de base de entrada ao elemento ExplanationMetadata. Caso contrário, o Vertex AI escolhe as bases de referência de entrada para o Model.

    Se especificar input baselines, certifique-se de que correspondem à entrada do seu modelo, normalmente uma lista de matrizes 2D. Caso contrário, o valor predefinido para a base de referência de entrada é uma matriz 2D de valor 0 da forma de entrada.

  2. Execute o seguinte comando para criar um recurso Model que suporte a IA explicável do Vertex. As flags mais pertinentes para a Vertex Explainable AI estão realçadas. 

    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 o seguinte:

    Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PATH_COUNT: o número de permutações de características a usar para o método de atribuição de Shapley com amostragem. Tem de ser um número inteiro no intervalo [1, 50].

    Um valor mais elevado pode reduzir o erro de aproximação, mas é mais intensivo em termos de computação. Se não souber que valor usar, experimente 25.

  • FEATURE_NAME: o nome da funcionalidade, conforme descrito na secção "Determinar nomes de funcionalidades" deste documento.
  • OUTPUT_NAME: o nome da saída, conforme descrito na secção "Determinar o nome da saída" deste documento.

Para saber mais sobre os valores adequados para os outros marcadores de posição, consulte upload e Importar modelos.

Opcionalmente, pode adicionar linhas de base de entrada ao elemento ExplanationMetadata. Caso contrário, o Vertex AI escolhe as bases de referência de entrada para o Model.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "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 o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

O que se segue?