ExplanationSpec

Specification of Model explanation.

Fields
parametersobject (ExplanationParameters)

Required. Parameters that configure explaining of the Model's predictions.

metadataobject (ExplanationMetadata)

Optional. metadata describing the Model's input and output for explanation.

JSON representation
{"parameters":{object (ExplanationParameters)},"metadata":{object (ExplanationMetadata)}}

ExplanationParameters

Parameters to configure explaining for Model's predictions.

Fields
topKinteger

If populated, returns attributions for top K indices of outputs (defaults to 1). Only applies to Models that predicts more than one outputs (e,g, multi-class Models). When set to -1, returns explanations for all outputs.

outputIndicesarray (ListValue format)

If populated, only returns attributions that haveoutputIndex contained in outputIndices. It must be an ndarray of integers, with the same shape of the output it's explaining.

If not populated, returns attributions fortopK indices of outputs. If neither topK nor outputIndices is populated, returns the argmax index of the outputs.

Only applicable to Models that predict multiple outputs (e,g, multi-class Models that predict multiple classes).

methodUnion type
method can be only one of the following:
sampledShapleyAttributionobject (SampledShapleyAttribution)

An attribution method that approximates Shapley values for features that contribute to the label being predicted. A sampling strategy is used to approximate the value rather than considering all subsets of features. Refer to this paper for model details:https://arxiv.org/abs/1306.4265.

integratedGradientsAttributionobject (IntegratedGradientsAttribution)

An attribution method that computes Aumann-Shapley values taking advantage of the model's fully differentiable structure. Refer to this paper for more details:https://arxiv.org/abs/1703.01365

xraiAttributionobject (XraiAttribution)

An attribution method that redistributes Integrated Gradients attribution to segmented regions, taking advantage of the model's fully differentiable structure. Refer to this paper for more details:https://arxiv.org/abs/1906.02825

XRAI currently performs better on natural images, like a picture of a house or an animal. If the images are taken in artificial environments, like a lab or manufacturing line, or from diagnostic equipment, like x-rays or quality-control cameras, use Integrated Gradients instead.

examplesobject (Examples)

Example-based explanations that returns the nearest neighbors from the provided dataset.

JSON representation
{"topK":integer,"outputIndices":array,// method"sampledShapleyAttribution":{object (SampledShapleyAttribution)},"integratedGradientsAttribution":{object (IntegratedGradientsAttribution)},"xraiAttribution":{object (XraiAttribution)},"examples":{object (Examples)}// Union type}

SampledShapleyAttribution

An attribution method that approximates Shapley values for features that contribute to the label being predicted. A sampling strategy is used to approximate the value rather than considering all subsets of features.

Fields
pathCountinteger

Required. The number of feature permutations to consider when approximating the Shapley values.

Valid range of its value is [1, 50], inclusively.

JSON representation
{"pathCount":integer}

IntegratedGradientsAttribution

An attribution method that computes the Aumann-Shapley value taking advantage of the model's fully differentiable structure. Refer to this paper for more details:https://arxiv.org/abs/1703.01365

Fields
stepCountinteger

Required. The number of steps for approximating the path integral. A good value to start is 50 and gradually increase until the sum to diff property is within the desired error range.

Valid range of its value is [1, 100], inclusively.

smoothGradConfigobject (SmoothGradConfig)

Config for SmoothGrad approximation of gradients.

When enabled, the gradients are approximated by averaging the gradients from noisy samples in the vicinity of the inputs. Adding noise can help improve the computed gradients. Refer to this paper for more details:https://arxiv.org/pdf/1706.03825.pdf

blurBaselineConfigobject (BlurBaselineConfig)

Config for IG with blur baseline.

When enabled, a linear path from the maximally blurred image to the input image is created. Using a blurred baseline instead of zero (black image) is motivated by the BlurIG approach explained here:https://arxiv.org/abs/2004.03383

JSON representation
{"stepCount":integer,"smoothGradConfig":{object (SmoothGradConfig)},"blurBaselineConfig":{object (BlurBaselineConfig)}}

SmoothGradConfig

Config for SmoothGrad approximation of gradients.

When enabled, the gradients are approximated by averaging the gradients from noisy samples in the vicinity of the inputs. Adding noise can help improve the computed gradients. Refer to this paper for more details:https://arxiv.org/pdf/1706.03825.pdf

Fields
noisySampleCountinteger

The number of gradient samples to use for approximation. The higher this number, the more accurate the gradient is, but the runtime complexity increases by this factor as well. Valid range of its value is [1, 50]. Defaults to 3.

GradientNoiseSigmaUnion type
Represents the standard deviation of the gaussian kernel that will be used to add noise to the interpolated inputs prior to computing gradients.GradientNoiseSigma can be only one of the following:
noiseSigmanumber

This is a single float value and will be used to add noise to all the features. Use this field when all features are normalized to have the same distribution: scale to range [0, 1], [-1, 1] or z-scoring, where features are normalized to have 0-mean and 1-variance. Learn more aboutnormalization.

For best results the recommended value is about 10% - 20% of the standard deviation of the input feature. Refer to section 3.2 of the SmoothGrad paper:https://arxiv.org/pdf/1706.03825.pdf. Defaults to 0.1.

If the distribution is different per feature, setfeatureNoiseSigma instead for each feature.

featureNoiseSigmaobject (FeatureNoiseSigma)

This is similar tonoiseSigma, but provides additional flexibility. A separate noise sigma can be provided for each feature, which is useful if their distributions are different. No noise is added to features that are not set. If this field is unset,noiseSigma will be used for all features.

JSON representation
{"noisySampleCount":integer,// GradientNoiseSigma"noiseSigma":number,"featureNoiseSigma":{object (FeatureNoiseSigma)}// Union type}

FeatureNoiseSigma

Noise sigma by features. Noise sigma represents the standard deviation of the gaussian kernel that will be used to add noise to interpolated inputs prior to computing gradients.

Fields
noiseSigma[]object (NoiseSigmaForFeature)

Noise sigma per feature. No noise is added to features that are not set.

JSON representation
{"noiseSigma":[{object (NoiseSigmaForFeature)}]}

NoiseSigmaForFeature

Noise sigma for a single feature.

Fields
namestring

The name of the input feature for which noise sigma is provided. The features are defined inexplanation metadata inputs.

sigmanumber

This represents the standard deviation of the Gaussian kernel that will be used to add noise to the feature prior to computing gradients. Similar tonoiseSigma but represents the noise added to the current feature. Defaults to 0.1.

JSON representation
{"name":string,"sigma":number}

BlurBaselineConfig

Config for blur baseline.

When enabled, a linear path from the maximally blurred image to the input image is created. Using a blurred baseline instead of zero (black image) is motivated by the BlurIG approach explained here:https://arxiv.org/abs/2004.03383

Fields
maxBlurSigmanumber

The standard deviation of the blur kernel for the blurred baseline. The same blurring parameter is used for both the height and the width dimension. If not set, the method defaults to the zero (i.e. black for images) baseline.

JSON representation
{"maxBlurSigma":number}

XraiAttribution

An explanation method that redistributes Integrated Gradients attributions to segmented regions, taking advantage of the model's fully differentiable structure. Refer to this paper for more details:https://arxiv.org/abs/1906.02825

Supported only by image Models.

Fields
stepCountinteger

Required. The number of steps for approximating the path integral. A good value to start is 50 and gradually increase until the sum to diff property is met within the desired error range.

Valid range of its value is [1, 100], inclusively.

smoothGradConfigobject (SmoothGradConfig)

Config for SmoothGrad approximation of gradients.

When enabled, the gradients are approximated by averaging the gradients from noisy samples in the vicinity of the inputs. Adding noise can help improve the computed gradients. Refer to this paper for more details:https://arxiv.org/pdf/1706.03825.pdf

blurBaselineConfigobject (BlurBaselineConfig)

Config for XRAI with blur baseline.

When enabled, a linear path from the maximally blurred image to the input image is created. Using a blurred baseline instead of zero (black image) is motivated by the BlurIG approach explained here:https://arxiv.org/abs/2004.03383

JSON representation
{"stepCount":integer,"smoothGradConfig":{object (SmoothGradConfig)},"blurBaselineConfig":{object (BlurBaselineConfig)}}

Examples

Example-based explainability that returns the nearest neighbors from the provided dataset.

Fields
neighborCountinteger

The number of neighbors to return when querying for examples.

sourceUnion type
source can be only one of the following:
exampleGcsSourceobject (ExampleGcsSource)

The Cloud Storage input instances.

configUnion type
config can be only one of the following:
nearestNeighborSearchConfigvalue (Value format)

The full configuration for the generated index, the semantics are the same asmetadata and should matchNearestNeighborSearchConfig.

presetsobject (Presets)

Simplified preset configuration, which automatically sets configuration values based on the desired query speed-precision trade-off and modality.

JSON representation
{"neighborCount":integer,// source"exampleGcsSource":{object (ExampleGcsSource)}// Union type// config"nearestNeighborSearchConfig":value,"presets":{object (Presets)}// Union type}

ExampleGcsSource

The Cloud Storage input instances.

Fields
dataFormatenum (DataFormat)

The format in which instances are given, if not specified, assume it's JSONL format. Currently only JSONL format is supported.

gcsSourceobject (GcsSource)

The Cloud Storage location for the input instances.

JSON representation
{"dataFormat":enum (DataFormat),"gcsSource":{object (GcsSource)}}

DataFormat

The format of the input example instances.

Enums
DATA_FORMAT_UNSPECIFIEDFormat unspecified, used when unset.
JSONLExamples are stored in JSONL files.

Presets

Preset configuration for example-based explanations

Fields
modalityenum (Modality)

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.

queryenum (Query)

Preset option controlling parameters for speed-precision trade-off when querying for examples. If omitted, defaults toPRECISE.

JSON representation
{"modality":enum (Modality),"query":enum (Query)}

Query

Preset option controlling parameters for query speed-precision trade-off

Enums
PRECISEMore precise neighbors as a trade-off against slower response.
FASTFaster response as a trade-off against less precise neighbors.

Modality

Preset option controlling parameters for different modalities

Enums
MODALITY_UNSPECIFIEDShould not be set. Added as a recommended best practice for enums
IMAGEIMAGE modality
TEXTTEXT modality
TABULARTABULAR modality

ExplanationMetadata

metadata describing the Model's input and output for explanation.

Fields
inputsmap (key: string, value: object (InputMetadata))

Required. Map from feature names to feature input metadata. Keys are the name of the features. Values are the specification of the feature.

An empty InputMetadata is valid. It describes a text feature which has the name specified as the key inExplanationMetadata.inputs. The baseline of the empty feature is chosen by Vertex AI.

For Vertex AI-provided Tensorflow images, the key can be any friendly name of the feature. Once specified,featureAttributions are keyed by this key (if not grouped with another feature).

For custom images, the key must match with the key ininstance.

outputsmap (key: string, value: object (OutputMetadata))

Required. Map from output names to output metadata.

For Vertex AI-provided Tensorflow images, keys can be any user defined string that consists of any UTF-8 characters.

For custom images, keys are the name of the output field in the prediction to be explained.

Currently only one key is allowed.

featureAttributionsSchemaUristring

Points to a YAML file stored on Google Cloud Storage describing the format of thefeature attributions. The schema is defined as an OpenAPI 3.0.2Schema Object. AutoML tabular Models always have this field populated by Vertex AI. Note: The URI given on output may be different, including the URI scheme, than the one given on input. The output URI will point to a location where the user only has a read access.

latentSpaceSourcestring

name of the source to generate embeddings for example based explanations.

JSON representation
{"inputs":{string:{object (InputMetadata)},...},"outputs":{string:{object (OutputMetadata)},...},"featureAttributionsSchemaUri":string,"latentSpaceSource":string}

InputMetadata

metadata of the input of a feature.

Fields other thanInputMetadata.input_baselines are applicable only for Models that are using Vertex AI-provided images for Tensorflow.

Fields
inputBaselines[]value (Value format)

baseline inputs for this feature.

If no baseline is specified, Vertex AI chooses the baseline for this feature. If multiple baselines are specified, Vertex AI returns the average attributions across them inAttribution.feature_attributions.

For Vertex AI-provided Tensorflow images (both 1.x and 2.x), the shape of each baseline must match the shape of the input tensor. If a scalar is provided, we broadcast to the same shape as the input tensor.

For custom images, the element of the baselines must be in the same format as the feature's input in theinstance[]. The schema of any single instance may be specified via Endpoint's DeployedModels'Model'sPredictSchemata'sinstanceSchemaUri.

inputTensorNamestring

name of the input tensor for this feature. Required and is only applicable to Vertex AI-provided images for Tensorflow.

encodingenum (Encoding)

Defines how the feature is encoded into the input tensor. Defaults to IDENTITY.

modalitystring

Modality of the feature. Valid values are: numeric, image. Defaults to numeric.

featureValueDomainobject (FeatureValueDomain)

The domain details of the input feature value. Like min/max, original mean or standard deviation if normalized.

indicesTensorNamestring

Specifies the index of the values of the input tensor. Required when the input tensor is a sparse representation. Refer to Tensorflow documentation for more details:https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor.

denseShapeTensorNamestring

Specifies the shape of the values of the input if the input is a sparse representation. Refer to Tensorflow documentation for more details:https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor.

indexFeatureMapping[]string

A list of feature names for each index in the input tensor. Required when the inputInputMetadata.encoding is BAG_OF_FEATURES, BAG_OF_FEATURES_SPARSE, INDICATOR.

encodedTensorNamestring

Encoded tensor is a transformation of the input tensor. Must be provided if choosingIntegrated Gradients attribution orXRAI attribution and the input tensor is not differentiable.

An encoded tensor is generated if the input tensor is encoded by a lookup table.

encodedBaselines[]value (Value format)

A list of baselines for the encoded tensor.

The shape of each baseline should match the shape of the encoded tensor. If a scalar is provided, Vertex AI broadcasts to the same shape as the encoded tensor.

visualizationobject (Visualization)

Visualization configurations for image explanation.

groupNamestring

name of the group that the input belongs to. Features with the same group name will be treated as one feature when computing attributions. Features grouped together can have different shapes in value. If provided, there will be one single attribution generated inAttribution.feature_attributions, keyed by the group name.

JSON representation
{"inputBaselines":[value],"inputTensorName":string,"encoding":enum (Encoding),"modality":string,"featureValueDomain":{object (FeatureValueDomain)},"indicesTensorName":string,"denseShapeTensorName":string,"indexFeatureMapping":[string],"encodedTensorName":string,"encodedBaselines":[value],"visualization":{object (Visualization)},"groupName":string}

Encoding

Defines how a feature is encoded. Defaults to IDENTITY.

Enums
ENCODING_UNSPECIFIEDDefault value. This is the same as IDENTITY.
IDENTITYThe tensor represents one feature.
BAG_OF_FEATURES

The tensor represents a bag of features where each index maps to a feature.InputMetadata.index_feature_mapping must be provided for this encoding. For example:

input = [27, 6.0, 150]indexFeatureMapping = ["age", "height", "weight"]
BAG_OF_FEATURES_SPARSE

The tensor represents a bag of features where each index maps to a feature. Zero values in the tensor indicates feature being non-existent.InputMetadata.index_feature_mapping must be provided for this encoding. For example:

input = [2, 0, 5, 0, 1]indexFeatureMapping = ["a", "b", "c", "d", "e"]
INDICATOR

The tensor is a list of binaries representing whether a feature exists or not (1 indicates existence).InputMetadata.index_feature_mapping must be provided for this encoding. For example:

input = [1, 0, 1, 0, 1]indexFeatureMapping = ["a", "b", "c", "d", "e"]
COMBINED_EMBEDDING

The tensor is encoded into a 1-dimensional array represented by an encoded tensor.InputMetadata.encoded_tensor_name must be provided for this encoding. For example:

input = ["This", "is", "a", "test", "."]encoded = [0.1, 0.2, 0.3, 0.4, 0.5]
CONCAT_EMBEDDING

Select this encoding when the input tensor is encoded into a 2-dimensional array represented by an encoded tensor.InputMetadata.encoded_tensor_name must be provided for this encoding. The first dimension of the encoded tensor's shape is the same as the input tensor's shape. For example:

input = ["This", "is", "a", "test", "."]encoded = [[0.1, 0.2, 0.3, 0.4, 0.5],           [0.2, 0.1, 0.4, 0.3, 0.5],           [0.5, 0.1, 0.3, 0.5, 0.4],           [0.5, 0.3, 0.1, 0.2, 0.4],           [0.4, 0.3, 0.2, 0.5, 0.1]]

FeatureValueDomain

domain details of the input feature value. Provides numeric information about the feature, such as its range (min, max). If the feature has been pre-processed, for example with z-scoring, then it provides information about how to recover the original feature. For example, if the input feature is an image and it has been pre-processed to obtain 0-mean and stddev = 1 values, then originalMean, and originalStddev refer to the mean and stddev of the original feature (e.g. image tensor) from which input feature (with mean = 0 and stddev = 1) was obtained.

Fields
minValuenumber

The minimum permissible value for this feature.

maxValuenumber

The maximum permissible value for this feature.

originalMeannumber

If this input feature has been normalized to a mean value of 0, the originalMean specifies the mean value of the domain prior to normalization.

originalStddevnumber

If this input feature has been normalized to a standard deviation of 1.0, the originalStddev specifies the standard deviation of the domain prior to normalization.

JSON representation
{"minValue":number,"maxValue":number,"originalMean":number,"originalStddev":number}

Visualization

Visualization configurations for image explanation.

Fields
typeenum (Type)

type of the image visualization. Only applicable toIntegrated Gradients attribution. OUTLINES shows regions of attribution, while PIXELS shows per-pixel attribution. Defaults to OUTLINES.

polarityenum (Polarity)

Whether to only highlight pixels with positive contributions, negative or both. Defaults to POSITIVE.

colorMapenum (ColorMap)

The color scheme used for the highlighted areas.

Defaults to PINK_GREEN forIntegrated Gradients attribution, which shows positive attributions in green and negative in pink.

Defaults to VIRIDIS forXRAI attribution, which highlights the most influential regions in yellow and the least influential in blue.

clipPercentUpperboundnumber

Excludes attributions above the specified percentile from the highlighted areas. Using the clipPercentUpperbound and clipPercentLowerbound together can be useful for filtering out noise and making it easier to see areas of strong attribution. Defaults to 99.9.

clipPercentLowerboundnumber

Excludes attributions below the specified percentile, from the highlighted areas. Defaults to 62.

overlayTypeenum (OverlayType)

How the original image is displayed in the visualization. Adjusting the overlay can help increase visual clarity if the original image makes it difficult to view the visualization. Defaults to NONE.

JSON representation
{"type":enum (Type),"polarity":enum (Polarity),"colorMap":enum (ColorMap),"clipPercentUpperbound":number,"clipPercentLowerbound":number,"overlayType":enum (OverlayType)}

Type

type of the image visualization. Only applicable toIntegrated Gradients attribution.

Enums
TYPE_UNSPECIFIEDShould not be used.
PIXELSShows which pixel contributed to the image prediction.
OUTLINESShows which region contributed to the image prediction by outlining the region.

Polarity

Whether to only highlight pixels with positive contributions, negative or both. Defaults to POSITIVE.

Enums
POLARITY_UNSPECIFIEDDefault value. This is the same as POSITIVE.
POSITIVEHighlights the pixels/outlines that were most influential to the model's prediction.
NEGATIVESetting polarity to negative highlights areas that does not lead to the models's current prediction.
BOTHShows both positive and negative attributions.

ColorMap

The color scheme used for highlighting areas.

Enums
COLOR_MAP_UNSPECIFIEDShould not be used.
PINK_GREENPositive: green. Negative: pink.
VIRIDISViridis color map: A perceptually uniform color mapping which is easier to see by those with colorblindness and progresses from yellow to green to blue. Positive: yellow. Negative: blue.
REDPositive: red. Negative: red.
GREENPositive: green. Negative: green.
RED_GREENPositive: green. Negative: red.
PINK_WHITE_GREENPiYG palette.

OverlayType

How the original image is displayed in the visualization.

Enums
OVERLAY_TYPE_UNSPECIFIEDDefault value. This is the same as NONE.
NONENo overlay.
ORIGINALThe attributions are shown on top of the original image.
GRAYSCALEThe attributions are shown on top of grayscaled version of the original image.
MASK_BLACKThe attributions are used as a mask to reveal predictive parts of the image and hide the un-predictive parts.

OutputMetadata

metadata of the prediction output to be explained.

Fields
outputTensorNamestring

name of the output tensor. Required and is only applicable to Vertex AI provided images for Tensorflow.

display_name_mappingUnion type

Defines how to mapAttribution.output_index toAttribution.output_display_name.

If neither of the fields are specified,Attribution.output_display_name will not be populated.display_name_mapping can be only one of the following:

indexDisplayNameMappingvalue (Value format)

Static mapping between the index and display name.

Use this if the outputs are a deterministic n-dimensional array, e.g. a list of scores of all the classes in a pre-defined order for a multi-classification Model. It's not feasible if the outputs are non-deterministic, e.g. the Model produces top-k classes or sort the outputs by their values.

The shape of the value must be an n-dimensional array of strings. The number of dimensions must match that of the outputs to be explained. TheAttribution.output_display_name is populated by locating in the mapping withAttribution.output_index.

displayNameMappingKeystring

Specify a field name in the prediction to look for the display name.

Use this if the prediction contains the display names for the outputs.

The display names in the prediction must have the same shape of the outputs, so that it can be located byAttribution.output_index for a specific output.

JSON representation
{"outputTensorName":string,// display_name_mapping"indexDisplayNameMapping":value,"displayNameMappingKey":string// Union type}

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-06-27 UTC.