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.

You need to provide the prerequisites and you can also provide other fields, like the ones that control the trade-off between the quality and speed of explanations. 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`	Number of neighbors to return
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.

Here is an example of the JSON representation of a Model Upload request payload with only the necessary example-based explanation fields set. Note that you can either specify the presets config based on modality and the desired speed/accuracy trade-off (precise or fast) as shown below, or specify the full treeAhConfig.

MODEL_PAYLOAD = json.dumps(
{
      "model": {
        "displayName": displayname,
        "artifactUri": model_path_to_deploy,
        "containerSpec": {
          "imageUri": DEPLOY_IMAGE,
        },
        "explanationSpec": {
          "parameters": {
            "examples": {
              "gcsSource": {
                "uris": [DATASET_PATH]
              },
              "neighborCount": 10,
              "presets": {
                "modality": "tabular"
              }
            }
          }
        }
      }
    }
  )

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

MODEL_PAYLOAD = json.dumps(
{
      "model": {
        "displayName": displayname,
        "artifactUri": model_path_to_deploy,
        "containerSpec": {
          "imageUri": DEPLOY_IMAGE,
        },
        "explanationSpec": {
          "parameters": {
            "examples": {
              "gcsSource": {
                "uris": [DATASET_PATH]
              },
              "neighborCount": 50,
              "nearest_neighbor_search_config": {
                "contentsDeltaUri": "",
                "config": {
                  "dimensions": dimensions,
                  "approximateNeighborsCount": 10,
                  "distanceMeasureType": "SQUARED_L2_DISTANCE",
                  "featureNormType": "NONE",
                  "algorithmConfig": {
                      "treeAhConfig": {
                          "leafNodeEmbeddingCount": 1000,
                          "leafNodesToSearchPercent": 100
                      }
                    }
                  }
              }
            }
          }
        }
      }
    }
  )

The model can then be uploaded using the HTTP command:

  !curl \
  -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/models:upload \
  -d '{MODEL_PAYLOAD}'

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.

NOTE: You will not be able to request explanations until this step is finished.

The upload action returns an OPERATION_ID that can be used to check when the operation is finished. The following command returns ("done": true) once the model is uploaded:

!curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/operations/{OPERATION_ID}

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:

REQUEST_PAYLOAD = json.dumps({
    "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"]
              }
            ]
          }
        }
      }
    )

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.