Method: projects.locations.endpoints.explain

Perform an online explanation.

If deployedModelId is specified, the corresponding endpoints.deployModel must have explanationSpec populated. If deployedModelId is not specified, all DeployedModels must have explanationSpec populated.

Endpoint

post https://{endpoint}/v1beta1/{endpoint}:explain

Where {service-endpoint} is one of the supported service endpoints.

Path parameters

endpoint string

Required. The name of the Endpoint requested to serve the explanation. Format: projects/{project}/locations/{location}/endpoints/{endpoint}

Request body

The request body contains data with the following structure:

Fields
instances[] value (Value format)

Required. The instances that are the input to the explanation call. A DeployedModel may have an upper limit on the number of instances it supports per request, and when it is exceeded the explanation call errors in case of AutoML Models, or, in case of customer created Models, the behaviour is as documented by that Model. The schema of any single instance may be specified via Endpoint's DeployedModels' Model's PredictSchemata's instanceSchemaUri.

parameters value (Value format)

The parameters that govern the prediction. The schema of the parameters may be specified via Endpoint's DeployedModels' Model's PredictSchemata's parametersSchemaUri.

explanationSpecOverride object (ExplanationSpecOverride)

If specified, overrides the explanationSpec of the DeployedModel. Can be used for explaining prediction results with different configurations, such as: - Explaining top-5 predictions results as opposed to top-1; - Increasing path count or step count of the attribution methods to reduce approximate errors; - Using different baselines for explaining the prediction results.

concurrentExplanationSpecOverride map (key: string, value: object (ExplanationSpecOverride))

Optional. This field is the same as the one above, but supports multiple explanations to occur in parallel. The key can be any string. Each override will be run against the model, then its explanations will be grouped together.

Note - these explanations are run In Addition to the default Explanation in the deployed model.

deployedModelId string

If specified, this ExplainRequest will be served by the chosen DeployedModel, overriding Endpoint.traffic_split.

Response body

Response message for PredictionService.Explain.

If successful, the response body contains data with the following structure:

Fields
explanations[] object (Explanation)

The explanations of the Model's PredictResponse.predictions.

It has the same number of elements as instances to be explained.

concurrentExplanations map (key: string, value: object (ConcurrentExplanation))

This field stores the results of the explanations run in parallel with The default explanation strategy/method.

deployedModelId string

id of the Endpoint's DeployedModel that served this explanation.

predictions[] value (Value format)

The predictions that are the output of the predictions call. Same as PredictResponse.predictions.

JSON representation 
{
  "explanations": [
    {
      object (Explanation)
    }
  ],
  "concurrentExplanations": {
    string: {
      object (ConcurrentExplanation)
    },
    ...
  },
  "deployedModelId": string,
  "predictions": [
    value
  ]
}

ExplanationSpecOverride

The ExplanationSpec entries that can be overridden at online explanation time.

Fields
parameters object (ExplanationParameters)

The parameters to be overridden. Note that the attribution method cannot be changed. If not specified, no parameter is overridden.

metadata object (ExplanationMetadataOverride)

The metadata to be overridden. If not specified, no metadata is overridden.

examplesOverride object (ExamplesOverride)

The example-based explanations parameter overrides.

JSON representation 
{
  "parameters": {
    object (ExplanationParameters)
  },
  "metadata": {
    object (ExplanationMetadataOverride)
  },
  "examplesOverride": {
    object (ExamplesOverride)
  }
}

ExplanationMetadataOverride

The ExplanationMetadata entries that can be overridden at online explanation time.

Fields
inputs map (key: string, value: object (InputMetadataOverride))

Required. Overrides the input metadata of the features. The key is the name of the feature to be overridden. The keys specified here must exist in the input metadata to be overridden. If a feature is not specified here, the corresponding feature's input metadata is not overridden.

JSON representation 
{
  "inputs": {
    string: {
      object (InputMetadataOverride)
    },
    ...
  }
}

InputMetadataOverride

The input metadata entries to be overridden.

Fields
inputBaselines[] value (Value format)

baseline inputs for this feature.

This overrides the input_baseline field of the ExplanationMetadata.InputMetadata object of the corresponding feature's input metadata. If it's not specified, the original baselines are not overridden.

JSON representation 
{
  "inputBaselines": [
    value
  ]
}

ExamplesOverride

Overrides for example-based explanations.

Fields
neighborCount integer

The number of neighbors to return.

crowdingCount integer

The number of neighbors to return that have the same crowding tag.

restrictions[] object (ExamplesRestrictionsNamespace)

Restrict the resulting nearest neighbors to respect these constraints.

returnEmbeddings boolean

If true, return the embeddings instead of neighbors.

dataFormat enum (DataFormat)

The format of the data being provided with each call.

JSON representation 
{
  "neighborCount": integer,
  "crowdingCount": integer,
  "restrictions": [
    {
      object (ExamplesRestrictionsNamespace)
    }
  ],
  "returnEmbeddings": boolean,
  "dataFormat": enum (DataFormat)
}

ExamplesRestrictionsNamespace

Restrictions namespace for example-based explanations overrides.

Fields
namespaceName string

The namespace name.

allow[] string

The list of allowed tags.

deny[] string

The list of deny tags.

JSON representation 
{
  "namespaceName": string,
  "allow": [
    string
  ],
  "deny": [
    string
  ]
}

DataFormat

data format enum.

Enums
DATA_FORMAT_UNSPECIFIED Unspecified format. Must not be used.
INSTANCES Provided data is a set of model inputs.
EMBEDDINGS Provided data is a set of embeddings.

ConcurrentExplanation

This message is a wrapper grouping Concurrent Explanations.

Fields
explanations[] object (Explanation)

The explanations of the Model's PredictResponse.predictions.

It has the same number of elements as instances to be explained.

JSON representation 
{
  "explanations": [
    {
      object (Explanation)
    }
  ]
}