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 alatent space
representation, saved in a Cloud Storage bucket. The model also needs to output anid
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. |
query1 | {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 |
distanceMeasureType1 | {SQUARED_L2_DISTANCE ,L1_DISTANCE ,COSINE_DISTANCE ,DOT_PRODUCT_DISTANCE } |
The distance metric by which to measure nearness of examples. |
featureNormType1 | {UNIT_L2_NORM , NONE } |
Normalize the embeddings so that it has a unit length |
treeAhConfig1 | 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 . |
leafNodeEmbeddingCount1 | int64 |
Number of embeddings in each leaf of the search tree |
leafNodesToSearchPercent1 | int32 |
Percentage of leaves to search for each query |
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
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.