diff --git a/google/cloud/aiplatform/v1/explanation.proto b/google/cloud/aiplatform/v1/explanation.proto index c1e3545c9c484..4b7b5c7272584 100644 --- a/google/cloud/aiplatform/v1/explanation.proto +++ b/google/cloud/aiplatform/v1/explanation.proto @@ -18,6 +18,7 @@ package google.cloud.aiplatform.v1; import "google/api/field_behavior.proto"; import "google/cloud/aiplatform/v1/explanation_metadata.proto"; +import "google/cloud/aiplatform/v1/io.proto"; import "google/protobuf/struct.proto"; option csharp_namespace = "Google.Cloud.AIPlatform.V1"; @@ -241,6 +242,10 @@ message ExplanationParameters { // like a lab or manufacturing line, or from diagnostic equipment, like // x-rays or quality-control cameras, use Integrated Gradients instead. XraiAttribution xrai_attribution = 3; + + // Example-based explanations that returns the nearest neighbors from the + // provided dataset. + Examples examples = 7; } // If populated, returns attributions for top K indices of outputs @@ -415,6 +420,86 @@ message BlurBaselineConfig { float max_blur_sigma = 1; } +// Example-based explainability that returns the nearest neighbors from the +// provided dataset. +message Examples { + // The Cloud Storage input instances. + message ExampleGcsSource { + // The format of the input example instances. + enum DataFormat { + // Format unspecified, used when unset. + DATA_FORMAT_UNSPECIFIED = 0; + + // Examples are stored in JSONL files. + JSONL = 1; + } + + // The format in which instances are given, if not specified, assume it's + // JSONL format. Currently only JSONL format is supported. + DataFormat data_format = 1; + + // The Cloud Storage location for the input instances. + GcsSource gcs_source = 2; + } + + oneof source { + // The Cloud Storage input instances. + ExampleGcsSource example_gcs_source = 5; + } + + oneof config { + // The full configuration for the generated index, the semantics are the + // same as [metadata][google.cloud.aiplatform.v1.Index.metadata] and should + // match + // [NearestNeighborSearchConfig](https://cloud.google.com/vertex-ai/docs/explainable-ai/configuring-explanations-example-based#nearest-neighbor-search-config). + google.protobuf.Value nearest_neighbor_search_config = 2; + + // Simplified preset configuration, which automatically sets configuration + // values based on the desired query speed-precision trade-off and modality. + Presets presets = 4; + } + + // The number of neighbors to return when querying for examples. + int32 neighbor_count = 3; +} + +// Preset configuration for example-based explanations +message Presets { + // Preset option controlling parameters for query speed-precision trade-off + enum Query { + // More precise neighbors as a trade-off against slower response. + PRECISE = 0; + + // Faster response as a trade-off against less precise neighbors. + FAST = 1; + } + + // Preset option controlling parameters for different modalities + enum Modality { + // Should not be set. Added as a recommended best practice for enums + MODALITY_UNSPECIFIED = 0; + + // IMAGE modality + IMAGE = 1; + + // TEXT modality + TEXT = 2; + + // TABULAR modality + TABULAR = 3; + } + + // Preset option controlling parameters for speed-precision trade-off when + // querying for examples. If omitted, defaults to `PRECISE`. + optional Query query = 1; + + // 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. + Modality modality = 2; +} + // The [ExplanationSpec][google.cloud.aiplatform.v1.ExplanationSpec] entries // that can be overridden at [online // explanation][google.cloud.aiplatform.v1.PredictionService.Explain] time.