feat: add examples to ExplanationParameters in aiplatform v1 explanation.proto

PiperOrigin-RevId: 532270918

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.