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.
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 fileexplanation-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:
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. |
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 |
The number of approximate neighbors to consider. The final neighbors are computed from these candidates. |
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 |
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
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.