Configure explicações baseadas em exemplos

Para usar explicações baseadas em exemplos, tem de configurar as explicações especificando um explanationSpec quando importa ou carrega o recurso Model para o Model Registry.

Em seguida, quando pedir explicações online, pode substituir alguns desses valores de configuração especificando um ExplanationSpecOverride no pedido. Não pode pedir explicações em lote. Estas não são suportadas.

Esta página descreve como configurar e atualizar estas opções.

Configure as explicações quando importar ou carregar o modelo

Antes de começar, certifique-se de que tem o seguinte:

  1. Uma localização do Cloud Storage que contém os artefactos do seu modelo. O seu modelo tem de ser um modelo de rede neural profunda (DNN) em que fornece o nome de uma camada ou uma assinatura cuja saída pode ser usada como o espaço latente, ou pode fornecer um modelo que produz diretamente incorporações (representação do espaço latente). Este espaço latente capta as representações de exemplos que são usadas para gerar explicações.

  2. Uma localização do Cloud Storage que contém as instâncias a serem indexadas para a pesquisa de vizinhos mais próximos aproximada. Para mais informações, consulte os requisitos de dados de entrada.

Consola

Siga o guia para importar um modelo através da Google Cloud consola.

No separador Explicabilidade, selecione Explicação baseada em exemplos e preencha os campos.

Para ver informações sobre cada campo, consulte as sugestões na Google Cloud consola (mostradas abaixo), bem como a documentação de referência para Example e ExplanationMetadata.

Ecrã de importação de modelos na consola que mostra as opções disponíveis no separador Explicabilidade.

CLI 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:
{
  "inputs": {
    "my_input": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "encoding": "IDENTITY",
    },
    "id": {
      "inputTensorName": "id",
      "encoding": "IDENTITY"
    }
  },
  "outputs": {
    "embedding": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}
  1. (Opcional) Se estiver a especificar o NearestNeighborSearchConfig completo, escreva o seguinte num ficheiro JSON no seu ambiente local. O nome do ficheiro não importa, mas, para este exemplo, atribua o nome search_config.json ao ficheiro:
{
  "contentsDeltaUri": "",
  "config": {
      "dimensions": 50,
      "approximateNeighborsCount": 10,
      "distanceMeasureType": "SQUARED_L2_DISTANCE",
      "featureNormType": "NONE",
      "algorithmConfig": {
          "treeAhConfig": {
              "leafNodeEmbeddingCount": 1000,
              "fractionLeafNodesToSearch": 1.0
          }
      }
    }
  }
  1. Execute o seguinte comando para carregar o seu Model.

Se estiver a usar uma Presetconfiguração de pesquisa--explanation-nearest-neighbor-search-config-file, remova a flag --explanation-nearest-neighbor-search-config-file. Se estiver a especificar NearestNeighborSearchConfig, remova os indicadores --explanation-modality e --explanation-query.

As denúncias mais pertinentes para as explicações baseadas em exemplos estão em negrito.

gcloud ai models upload \
    --region=LOCATION \
    --display-name=MODEL_NAME \
    --container-image-uri=IMAGE_URI \
    --artifact-uri=MODEL_ARTIFACT_URI \
    --explanation-method=examples \
    --uris=[URI, ...] \
    --explanation-neighbor-count=NEIGHBOR_COUNT \
    --explanation-metadata-file=explanation-metadata.json \
    --explanation-modality=IMAGE|TEXT|TABULAR \
    --explanation-query=PRECISE|FAST \
    --explanation-nearest-neighbor-search-config-file=search_config.json

Consulte gcloud ai models upload para mais informações.

  1. A ação de carregamento devolve um OPERATION_ID que pode ser usado para verificar quando a operação estiver concluída. Pode sondar o estado da operação até que a resposta inclua "done": true. Use o comando gcloud ai operations describe para verificar o estado, por exemplo:

    gcloud ai operations describe <operation-id>

    Não pode pedir explicações até que a operação esteja concluída. Consoante o tamanho do conjunto de dados e a arquitetura do modelo, este passo pode demorar várias horas a criar o índice usado para consultar exemplos.

REST

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

  • PROJECT
  • LOCATION

Para saber mais sobre os outros marcadores de posição, consulte Model, explanationSpec e Examples.

Para saber mais sobre o carregamento de modelos, consulte o método upload e o artigo Importar modelos.

O corpo do pedido JSON abaixo especifica uma configuração de pesquisa Preset. Em alternativa, pode especificar o nome completoNearestNeighborSearchConfig.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "model": {
    "displayName": "my-model",
    "artifactUri": "gs://your-model-artifact-folder",
    "containerSpec": {
      "imageUri": "us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-11:latest",
    },
    "explanationSpec": {
      "parameters": {
        "examples": {
          "gcsSource": {
            "uris": ["gs://your-examples-folder"]
          },
          "neighborCount": 10,
          "presets": {
            "modality": "image"
          }
        }
      },
      "metadata": {
        "outputs": {
            "embedding": {
                "output_tensor_name": "embedding"
            }
        },
        "inputs": {
          "my_fancy_input": {
            "input_tensor_name": "input_tensor_name",
            "encoding": "identity",
            "modality": "image"
          },
          "id": {
            "input_tensor_name": "id",
            "encoding": "identity"
          }
        }
      }
    }
  }
}

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/models/MODEL_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UploadModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T01:21:10.147035Z",
      "updateTime": "2022-01-08T01:21:10.147035Z"
    }
  }
}

A ação de carregamento devolve um OPERATION_ID que pode ser usado para verificar quando a operação estiver concluída. Pode sondar o estado da operação até que a resposta inclua "done": true. Use o comando gcloud ai operations describe para verificar o estado, por exemplo:

gcloud ai operations describe <operation-id>

Não pode pedir explicações até que a operação esteja concluída. Consoante o tamanho do conjunto de dados e a arquitetura do modelo, este passo pode demorar várias horas a criar o índice usado para consultar exemplos.

Python

Consulte a secção Carregue o modelo no bloco de notas de explicações baseadas em exemplos de classificação de imagens.

NearestNeighborSearchConfig

O corpo do pedido JSON seguinte demonstra como especificar o elemento completo NearestNeighborSearchConfig (em vez de predefinições) num pedido upload.

{
  "model": {
    "displayName": displayname,
    "artifactUri": model_path_to_deploy,
    "containerSpec": {
      "imageUri": DEPLOY_IMAGE,
    },
    "explanationSpec": {
      "parameters": {
        "examples": {
          "gcsSource": {
            "uris": [DATASET_PATH]
          },
          "neighborCount": 5,
          "nearest_neighbor_search_config": {
            "contentsDeltaUri": "",
            "config": {
              "dimensions": dimensions,
              "approximateNeighborsCount": 10,
              "distanceMeasureType": "SQUARED_L2_DISTANCE",
              "featureNormType": "NONE",
              "algorithmConfig": {
                  "treeAhConfig": {
                      "leafNodeEmbeddingCount": 1000,
                      "fractionLeafNodesToSearch": 1.0
                  }
                }
              }
          }
        }
      },
      "metadata": { ... }
    }
  }
}

Estas tabelas listam os campos para NearestNeighborSearchConfig.

Campos
dimensions

int32

Obrigatório. O número de dimensões dos vetores de entrada. Usado apenas para incorporações densas.

approximateNeighborsCount

int32

Obrigatório se for usado o algoritmo tree-AH.

O número predefinido de vizinhos a encontrar através da pesquisa aproximada antes de ser realizada a reordenação exata. A reordenação exata é um procedimento em que os resultados devolvidos por um algoritmo de pesquisa aproximado são reordenados através de um cálculo de distância mais dispendioso.

ShardSize ShardSize

O tamanho de cada fragmento. Quando um índice é grande, é dividido em partições com base no tamanho da partição especificado. Durante a publicação, cada fragmento é publicado num nó separado e é dimensionado de forma independente.

distanceMeasureType

DistanceMeasureType

A medida de distância usada na pesquisa de vizinho mais próximo.
featureNormType

FeatureNormType

Tipo de normalização a realizar em cada vetor.

algorithmConfig oneOf:

A configuração dos algoritmos que a pesquisa vetorial usa para uma pesquisa eficiente. Usado apenas para incorporações densas.

  • TreeAhConfig: Opções de configuração para usar o algoritmo tree-AH. Para mais informações, consulte esta publicação no blogue Escalar a obtenção detalhada com o TensorFlow Recommenders e a pesquisa vetorial
  • BruteForceConfig: esta opção implementa a pesquisa linear padrão na base de dados para cada consulta. Não existem campos para configurar para uma pesquisa de força bruta. Para selecionar este algoritmo, transmita um objeto vazio para BruteForceConfig.

DistanceMeasureType

Enumerações
SQUARED_L2_DISTANCE Distância euclidiana (L2)
L1_DISTANCE Distância de Manhattan (L1)
DOT_PRODUCT_DISTANCE Valor predefinido. Definida como o negativo do produto escalar.
COSINE_DISTANCE Distância do cosseno. Recomendamos vivamente que use DOT_PRODUCT_DISTANCE + UNIT_L2_NORM em vez da distância COSINE. Os nossos algoritmos foram mais otimizados para a distância DOT_PRODUCT e, quando combinados com UNIT_L2_NORM, oferecem a mesma classificação e equivalência matemática que a distância COSINE.

FeatureNormType

Enumerações
UNIT_L2_NORM Tipo de normalização da unidade L2.
NONE Valor predefinido. Não foi especificado nenhum tipo de normalização.

TreeAhConfig

Estes são os campos a selecionar para o algoritmo tree-AH (Shallow tree + Asymmetric Hashing).

Campos
fractionLeafNodesToSearch double
A fração predefinida de nós folha que qualquer consulta pode pesquisar. Tem de estar no intervalo 0,0 a 1,0, exclusivo. O valor predefinido é 0,05 se não estiver definido.
leafNodeEmbeddingCount int32
Número de incorporações em cada nó folha. O valor predefinido é 1000 se não estiver definido.
leafNodesToSearchPercent int32
Descontinuado, use fractionLeafNodesToSearch.

A percentagem predefinida de nós folha que qualquer consulta pode pesquisar. Tem de estar no intervalo de 1 a 100, inclusive. O valor predefinido é 10 (o que significa 10%) se não estiver definido.

BruteForceConfig

Esta opção implementa a pesquisa linear padrão na base de dados para cada consulta. Não existem campos para configurar para uma pesquisa de força bruta. Para selecionar este algoritmo, transmita um objeto vazio para BruteForceConfig para algorithmConfig.

Requisitos de dados de entrada

Carregue o conjunto de dados para uma localização do Cloud Storage. Certifique-se de que os ficheiros estão no formato JSON Lines.

Os ficheiros têm de estar no formato JSON Lines. O exemplo seguinte é do bloco de notas de explicações baseadas em exemplos de classificação de imagens:

{"id": "0", "bytes_inputs": {"b64": "..."}}
{"id": "1", "bytes_inputs": {"b64": "..."}}
{"id": "2", "bytes_inputs": {"b64": "..."}}

Atualize o índice ou a configuração

O Vertex AI permite-lhe atualizar o índice do vizinho mais próximo de um modelo ou a configuração de Example. Isto é útil se quiser atualizar o modelo sem reindexar o respetivo conjunto de dados. Por exemplo, se o índice do seu modelo contiver 1000 instâncias e quiser adicionar mais 500 instâncias, pode chamar UpdateExplanationDataset para adicionar ao índice sem voltar a processar as 1000 instâncias originais.

Para atualizar o conjunto de dados de explicações:

Python

def update_explanation_dataset(model_id, new_examples):
    response = clients["model"].update_explanation_dataset(model=model_id,  examples=new_examples)
    update_dataset_response = response.result()
    return update_dataset_response

PRESET_CONFIG = {
    "modality": "TEXT",
    "query": "FAST"
}
NEW_DATASET_FILE_PATH = "new_dataset_path"
NUM_NEIGHBORS_TO_RETURN = 10

EXAMPLES = aiplatform.Examples(presets=PRESET_CONFIG,
                                    gcs_source=aiplatform.types.io.GcsSource(uris=[NEW_DATASET_FILE_PATH]),
                                      neighbor_count=NUM_NEIGHBORS_TO_RETURN)

MODEL_ID = 'model_id'
update_dataset_response = update_explanation_dataset(MODEL_ID, EXAMPLES)

Notas de utilização:

  • O model_id permanece inalterado após a operação UpdateExplanationDataset.

  • A operação UpdateExplanationDataset afeta apenas o recurso Model; não atualiza nenhum DeployedModel associado. Isto significa que o índice de um deployedModelcontém o conjunto de dados no momento em que foi implementado. Para atualizar o índice de um deployedModel, tem de voltar a implementar o modelo atualizado num ponto final.

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

Quando pede uma explicação, pode substituir alguns dos parâmetros em tempo real especificando o campo ExplanationSpecOverride.

Consoante a aplicação, algumas restrições podem ser desejáveis no tipo de explicações devolvidas. Por exemplo, para garantir a diversidade das explicações, um utilizador pode especificar um parâmetro de agrupamento que determina que nenhum tipo de exemplos está excessivamente representado nas explicações. Concretamente, se um utilizador estiver a tentar compreender por que motivo um pássaro foi etiquetado como um avião pelo respetivo modelo, pode não ter interesse em ver demasiados exemplos de pássaros como explicações para investigar melhor a causa principal.

A tabela seguinte resume os parâmetros que podem ser substituídos para um pedido de explicação baseado em exemplos:

Nome da propriedade Valor da propriedade Descrição
neighborCount int32 O número de exemplos a devolver como explicação
crowdingCount int32 Número máximo de exemplos a devolver com a mesma etiqueta de sobreposição
permitir String Array As etiquetas permitidas para as explicações
recusar String Array As etiquetas que não são permitidas para as explicações

A Filtragem de pesquisa vetorial descreve estes parâmetros mais detalhadamente.

Segue-se um exemplo de um corpo de pedido JSON com substituições:

{
  "instances":[
    {
      "id": data[0]["id"],
      "bytes_inputs": {"b64": bytes},
      "restricts": "",
      "crowding_tag": ""
    }
  ],
  "explanation_spec_override": {
    "examples_override": {
      "neighbor_count": 5,
      "crowding_count": 2,
      "restrictions": [
        {
          "namespace_name": "label",
          "allow": ["Papilloma", "Rift_Valley", "TBE", "Influenza", "Ebol"]
        }
      ]
    }
  }
}

O que se segue?

Segue-se um exemplo da resposta de um pedido explain baseado em exemplos:

[
   {
      "neighbors":[
         {
            "neighborId":"311",
            "neighborDistance":383.8
         },
         {
            "neighborId":"286",
            "neighborDistance":431.4
         }
      ],
      "input":"0"
   },
   {
      "neighbors":[
         {
            "neighborId":"223",
            "neighborDistance":471.6
         },
         {
            "neighborId":"55",
            "neighborDistance":392.7
         }
      ],
      "input":"1"
   }
]

Preços

Consulte a secção sobre explicações baseadas em exemplos na página de preços.