Configure example-based explanations

To use example-based explanations, you must configure certain options when you create the Model resource that you plan to request explanations from, when you deploy the model, or when you request explanations. This page describes configuring these options.

When and where to configure explanations

You must configure explanations when you create a model. Some explanation parameters can also be specified when you request explanations.

Configure explanations when creating or importing models

When you create a Model, you can set a default configuration for all its explanations using the Model's explanationSpec field.

For creating example-based explanations, your model will either need to be a deep neural network (DNN) model where you provide the name of a layer, or signature, whose output can be used as the latent space, or you can provide a model that directly outputs embeddings (latent space representation). This latent space captures the example representations that are used for generating explanations.

Override the configuration when getting online explanations

Some of the explanation parameters can also be provided when the explanation request is issued. During model creation, these parameters that mostly affect the characteristics of the final explanations are set to generic defaults. When an explanation request is issued, these parameters can be overridden on the fly for each individual request using the ExplanationSpecOverride field.

Import a model with an `explanationSpec` field

Before explanations can be requested, the following prerequisites need to be met:

For a DNN model the layer that outputs the latent space, or in general a model that generates a latent space representation, saved in a Cloud Storage bucket. The model also needs to output an id for each example which is what's returned as explanations.
A training dataset saved in a Cloud Storage bucket.

gcloud CLI

Write the following ExplanationMetadata to a JSON file in your local environment. The filename does not matter, but for this example, call the file explanation-metadata.json:

{
  "inputs": {
    "my_input": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "encoding": "IDENTITY",
    },
    "id": {
      "inputTensorName": "id",
      "encoding": "IDENTITY"
    }
  },
  "outputs": {
    "embedding": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

(Optional) To manually specify the search configuration settings, write the following to a JSON file in your local environment. The filename does not matter, but for this example, call the file search_config.json:

{
  "contentsDeltaUri": "",
  "config": {
      "dimensions": 50,
      "approximateNeighborsCount": 10,
      "distanceMeasureType": "SQUARED_L2_DISTANCE",
      "featureNormType": "NONE",
      "algorithmConfig": {
          "treeAhConfig": {
              "leafNodeEmbeddingCount": 1000,
              "leafNodesToSearchPercent": 100
          }
      }
    }
  }

Run the following command to create your Model.

If you are using a preset search configuration, remove the --explanation-nearest-neighbor-search-config-file flag. If you are specifying the search configuration manually, remove the --explanation-modality and --explanation-query flags.

The flags most pertinent to example-based explanations are bolded.

gcloud beta 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

See gcloud beta ai models upload for more information.

The upload action returns an OPERATION_ID that can be used to check when the operation is finished. You can poll for the status of the operation until the response includes "done": true. Use the gcloud ai operations describe command to poll the status, for example:
```
gcloud ai operations describe <operation-id>
```
You will not be able to request explanations until the operation is done. Depending on the size of the dataset and model architecture, this step can take several hours to build the index used to query for examples.

REST

Before using any of the request data, make the following replacements:

PROJECT
LOCATION

To learn about the other placeholders, see Model and explanationSpec. To learn more about importing models, see the upload method and Importing models.

The request JSON body below uses presets and contains only the necessary fields for using example-based explanation. Alternatively, you can specify the full treeAhConfig as shown in the Full configuration example.

HTTP method and URL:

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

Request JSON body:

{
  "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"
          }
        }
      }
    }
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

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/locations/LOCATION/models:upload"

PowerShell (Windows)

Save the request body in a file named request.json, and execute the following command:

$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/locations/LOCATION/models:upload" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "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"
    }
  }
}

The upload action returns an OPERATION_ID that can be used to check when the operation is finished. You can poll for the status of the operation until the response includes "done": true. Use the gcloud ai operations describe command to poll the status, for example:

gcloud ai operations describe <operation-id>

You will not be able to request explanations until the operation is done. Depending on the size of the dataset and model architecture, this step can take several hours to build the index used to query for examples.

Override parameters with an `explanationSpecOverride` field

Depending on the application, some constraints might be desirable on the kind of explanations that are returned. For example, to ensure diversity of explanations, a user can specify a crowding parameter which dictates that no single type of examples are over-represented in the explanations. Concretely, if a user is trying to understand why a bird was labeled as a plane by their model, they might not be interested in seeing too many bird examples as explanations to better investigate the root cause.

The following table summarizes the parameters that can be overridden during the explanation request:

Property Name	Property Value	Description
neighborCount	`int32`	The number of examples to return as explanation
crowdingCount	`int32`	Maximum number of examples to return with the same crowding tag
allow	`String Array`	The tags that are allowed for explanations to have
deny	`String Array`	The tags that are not allowed for explanations to have

The Matching Engine Filtering describes these parameters in more details.

Here's an example of a request payload with overrides:

{
  "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"]
        }
      ]
    }
  }
}

Configuration settings

The table below lists the properties specific to example-based explanations with the required ones in bold. For other fields, see the model import section for feature-based explanations.

Property Name	Property Value	Description
uris	`String Array`	List of Cloud Storage bucket paths where training data is stored
neighborCount	`int32`	The number of items to return when querying for examples
modality	{`tabular`,`image`,`text`}	The modality of the uploaded model, which automatically configures the distance measurement and feature normalization for the underlying example index and queries. If your model does not precisely fit one of these types, it is okay to choose the closest type.
query¹	{`precise`, `fast`}	The configuration to use when querying for examples. Defaults to `precise` if not specified
dimensions	`int32`	The dimension of the embedding
approximateNeighborsCount	`int32`	The number of approximate neighbors to consider. The final neighbors are computed from these candidates.
distanceMeasureType¹	{`SQUARED_L2_DISTANCE`, `L1_DISTANCE`, `COSINE_DISTANCE`, `DOT_PRODUCT_DISTANCE` }	The distance metric by which to measure nearness of examples.
featureNormType¹	{`UNIT_L2_NORM`, `NONE`}	Normalize the embeddings so that it has a unit length
treeAhConfig¹	`Dict`	Parameters controlling the trade-off between quality of approximation and speed. See this paper for technical details. Internally, the service creates a shallow tree where the number of leaves is controlled by `leafNodeEmbeddingCount` and the search recall/speed tradeoff is controlled by `leafNodesToSearchPercent`.
leafNodeEmbeddingCount¹	`int64`	Number of embeddings in each leaf of the search tree
leafNodesToSearchPercent¹	`int32`	Percentage of leaves to search for each query

¹ This property is not yet final and can potentially be modified or removed for GA.

Full configuration example

This example shows all of the example-based explanation fields set, including the optional ones:

{
  "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,
                      "leafNodesToSearchPercent": 100
                  }
                }
              }
          }
        }
      },
      "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"
          }
        }
      }
    }
  }
}

What's next

Deploy your Model to an Endpoint and get example-based explanations.

Here's an example of the response:

[
   {
      "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"
   }
]

Pricing

While the feature is in preview, there is no charge for example-based explanations.

However, the usage Batch Prediction during Model Upload to generate latent space representations of examples will be charged at same rate as normal batch prediction. Online Prediction usage, for example, by deploying an endpoint to request explanations, will be charged at the same rate as normal online prediction usage. For more information, see the Prediction and explanation section for Custom-trained models in the Pricing page.

During preview, there is a limit of ~10M examples per uploaded model. If you require this limit to be increased, please contact xai-support@google.com or Google Cloud Support.