feat: add Examples to Explanation related messages in aiplatform v1beta1 explanation.proto

protos/google/cloud/aiplatform/v1beta1/explanation.proto

@@ -47,6 +47,12 @@ message Explanation {
   // the attributions are stored by [Attribution.output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index] in the same
   // order as they appear in the output_indices.
   repeated Attribution attributions = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. List of the nearest neighbors for example-based explanations.
+  //
+  // For models deployed with the examples explanations feature enabled, the
+  // attributions field is empty and instead the neighbors field is populated.
+  repeated Neighbor neighbors = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Aggregated explanation metrics for a Model over a set of instances.
@@ -163,6 +169,15 @@ message Attribution {
   string output_name = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
+// Neighbors for example-based explanations.
+message Neighbor {
+  // Output only. The neighbor id.
+  string neighbor_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The neighbor distance.
+  double neighbor_distance = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
 // Specification of Model explanation.
 message ExplanationSpec {
   // Required. Parameters that configure explaining of the Model's predictions.
@@ -373,17 +388,57 @@ message BlurBaselineConfig {
 // Example-based explainability that returns the nearest neighbors from the
 // provided dataset.
 message Examples {
+  oneof config {
+    // The configuration for the generated index, the semantics are the same as
+    // [metadata][google.cloud.aiplatform.v1beta1.Index.metadata] and should match NearestNeighborSearchConfig.
+    google.protobuf.Value nearest_neighbor_search_config = 2;
+
+    // Preset config based on the desired query speed-precision trade-off
+    // and modality
+    Preset preset = 4;
+  }
+
   // The Cloud Storage location for the input instances.
   GcsSource gcs_source = 1;
 
-  // The configuration for the generated index, the semantics are the same as
-  // [metadata][google.cloud.aiplatform.v1beta1.Index.metadata] and should match NearestNeighborSearchConfig.
-  google.protobuf.Value nearest_neighbor_search_config = 2;
-
   // The number of neighbors to return.
   int32 neighbor_count = 3;
 }
 
+// Preset configuration for example-based explanations
+message Preset {
+  // Preset option controlling parameters for query speed-precision trade-off
+  enum Query {
+    // More precise neighbors as a trade-off against slower response.
+    // This is also the default value (field-number 0).
+    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 query speed-precision trade-off
+  optional Query query = 1;
+
+  // Preset option controlling parameters for different modalities
+  Modality modality = 2;
+}
+
 // The [ExplanationSpec][google.cloud.aiplatform.v1beta1.ExplanationSpec] entries that can be overridden at
 // [online explanation][google.cloud.aiplatform.v1beta1.PredictionService.Explain] time.
 message ExplanationSpecOverride {
@@ -394,6 +449,9 @@ message ExplanationSpecOverride {
 
   // The metadata to be overridden. If not specified, no metadata is overridden.
   ExplanationMetadataOverride metadata = 2;
+
+  // The example-based explanations parameter overrides.
+  ExamplesOverride examples_override = 3;
 }
 
 // The [ExplanationMetadata][google.cloud.aiplatform.v1beta1.ExplanationMetadata] entries that can be overridden at
@@ -418,3 +476,45 @@ message ExplanationMetadataOverride {
   // overridden.
   map<string, InputMetadataOverride> inputs = 1 [(google.api.field_behavior) = REQUIRED];
 }
+
+// Overrides for example-based explanations.
+message ExamplesOverride {
+  // Data format enum.
+  enum DataFormat {
+    // Unspecified format. Must not be used.
+    DATA_FORMAT_UNSPECIFIED = 0;
+
+    // Provided data is a set of model inputs.
+    INSTANCES = 1;
+
+    // Provided data is a set of embeddings.
+    EMBEDDINGS = 2;
+  }
+
+  // The number of neighbors to return.
+  int32 neighbor_count = 1;
+
+  // The number of neighbors to return that have the same crowding tag.
+  int32 crowding_count = 2;
+
+  // Restrict the resulting nearest neighbors to respect these constraints.
+  repeated ExamplesRestrictionsNamespace restrictions = 3;
+
+  // If true, return the embeddings instead of neighbors.
+  bool return_embeddings = 4;
+
+  // The format of the data being provided with each call.
+  DataFormat data_format = 5;
+}
+
+// Restrictions namespace for example-based explanations overrides.
+message ExamplesRestrictionsNamespace {
+  // The namespace name.
+  string namespace_name = 1;
+
+  // The list of allowed tags.
+  repeated string allow = 2;
+
+  // The list of deny tags.
+  repeated string deny = 3;
+}

protos/google/cloud/aiplatform/v1beta1/explanation_metadata.proto

@@ -392,4 +392,7 @@ message ExplanationMetadata {
   // than the one given on input. The output URI will point to a location where
   // the user only has a read access.
   string feature_attributions_schema_uri = 3;
+
+  // Name of the source to generate embeddings for example based explanations.
+  string latent_space_source = 5;
 }

protos/google/cloud/aiplatform/v1beta1/model_service.proto

@@ -20,6 +20,7 @@ import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/cloud/aiplatform/v1beta1/explanation.proto";
 import "google/cloud/aiplatform/v1beta1/io.proto";
 import "google/cloud/aiplatform/v1beta1/model.proto";
 import "google/cloud/aiplatform/v1beta1/model_evaluation.proto";
@@ -87,6 +88,19 @@ service ModelService {
     option (google.api.method_signature) = "model,update_mask";
   }
 
+  // Incremental update the dataset used for a examples model.
+  rpc UpdateExplanationDataset(UpdateExplanationDatasetRequest) returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1beta1/{model=projects/*/locations/*/models/*}:updateExplanationDataset"
+      body: "*"
+    };
+    option (google.api.method_signature) = "model";
+    option (google.longrunning.operation_info) = {
+      response_type: "UpdateExplanationDatasetResponse"
+      metadata_type: "UpdateExplanationDatasetOperationMetadata"
+    };
+  }
+
   // Deletes a Model.
   //
   // A model cannot be deleted if any [Endpoint][google.cloud.aiplatform.v1beta1.Endpoint] resource has a
@@ -233,6 +247,16 @@ message UploadModelResponse {
 message GetModelRequest {
   // Required. The name of the Model resource.
   // Format: `projects/{project}/locations/{location}/models/{model}`
+  //
+  // In order to retrieve a specific version of the model, also provide
+  // the version ID or version alias.
+  //   Example: projects/{project}/locations/{location}/models/{model}@2
+  //              or
+  //            projects/{project}/locations/{location}/models/{model}@golden
+  // If no version ID or alias is specified, the "default" version will be
+  // returned. The "default" version alias is created for the first version of
+  // the model, and can be moved to other versions later on. There will be
+  // exactly one default version.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -366,6 +390,29 @@ message UpdateModelRequest {
   google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
+// Request message for
+// [ModelService.UpdateExplanationDataset][google.cloud.aiplatform.v1beta1.ModelService.UpdateExplanationDataset].
+message UpdateExplanationDatasetRequest {
+  // Required. The resource name of the Model to update.
+  // Format: `projects/{project}/locations/{location}/models/{model}`
+  string model = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "aiplatform.googleapis.com/Model"
+    }
+  ];
+
+  // The example config containing the location of the dataset.
+  Examples examples = 2;
+}
+
+// Runtime operation information for
+// [ModelService.UpdateExplanationDataset][google.cloud.aiplatform.v1beta1.ModelService.UpdateExplanationDataset].
+message UpdateExplanationDatasetOperationMetadata {
+  // The common part of the operation metadata.
+  GenericOperationMetadata generic_metadata = 1;
+}
+
 // Request message for [ModelService.DeleteModel][google.cloud.aiplatform.v1beta1.ModelService.DeleteModel].
 message DeleteModelRequest {
   // Required. The name of the Model resource to be deleted.
@@ -448,6 +495,8 @@ message ExportModelRequest {
   }
 
   // Required. The resource name of the Model to export.
+  // The resource name may contain version id or version alias to specify the
+  // version, if no version is specified, the default version will be exported.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -481,6 +530,11 @@ message ExportModelOperationMetadata {
   OutputInfo output_info = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
+// Response message of [ModelService.UpdateExplanationDataset][google.cloud.aiplatform.v1beta1.ModelService.UpdateExplanationDataset] operation.
+message UpdateExplanationDatasetResponse {
+
+}
+
 // Response message of [ModelService.ExportModel][google.cloud.aiplatform.v1beta1.ModelService.ExportModel] operation.
 message ExportModelResponse {