Skip to content
This repository was archived by the owner on Jul 20, 2023. It is now read-only.

Commit c69ac2b

Browse files
gcf-owl-bot[bot]gcf-owl-bot[bot]
authored
feat: add Examples to Explanation related messages in aiplatform v1beta1 explanation.proto (#307)
* feat: add Examples to Explanation related messages in aiplatform v1beta1 explanation.proto
1 parent 13beaa9 commit c69ac2b

14 files changed

Lines changed: 3498 additions & 40 deletions

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

Lines changed: 104 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,12 @@ message Explanation {
4747
// the attributions are stored by [Attribution.output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index] in the same
4848
// order as they appear in the output_indices.
4949
repeated Attribution attributions = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
50+
51+
// Output only. List of the nearest neighbors for example-based explanations.
52+
//
53+
// For models deployed with the examples explanations feature enabled, the
54+
// attributions field is empty and instead the neighbors field is populated.
55+
repeated Neighbor neighbors = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
5056
}
5157

5258
// Aggregated explanation metrics for a Model over a set of instances.
@@ -163,6 +169,15 @@ message Attribution {
163169
string output_name = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
164170
}
165171

172+
// Neighbors for example-based explanations.
173+
message Neighbor {
174+
// Output only. The neighbor id.
175+
string neighbor_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
176+
177+
// Output only. The neighbor distance.
178+
double neighbor_distance = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
179+
}
180+
166181
// Specification of Model explanation.
167182
message ExplanationSpec {
168183
// Required. Parameters that configure explaining of the Model's predictions.
@@ -373,17 +388,57 @@ message BlurBaselineConfig {
373388
// Example-based explainability that returns the nearest neighbors from the
374389
// provided dataset.
375390
message Examples {
391+
oneof config {
392+
// The configuration for the generated index, the semantics are the same as
393+
// [metadata][google.cloud.aiplatform.v1beta1.Index.metadata] and should match NearestNeighborSearchConfig.
394+
google.protobuf.Value nearest_neighbor_search_config = 2;
395+
396+
// Preset config based on the desired query speed-precision trade-off
397+
// and modality
398+
Preset preset = 4;
399+
}
400+
376401
// The Cloud Storage location for the input instances.
377402
GcsSource gcs_source = 1;
378403

379-
// The configuration for the generated index, the semantics are the same as
380-
// [metadata][google.cloud.aiplatform.v1beta1.Index.metadata] and should match NearestNeighborSearchConfig.
381-
google.protobuf.Value nearest_neighbor_search_config = 2;
382-
383404
// The number of neighbors to return.
384405
int32 neighbor_count = 3;
385406
}
386407

408+
// Preset configuration for example-based explanations
409+
message Preset {
410+
// Preset option controlling parameters for query speed-precision trade-off
411+
enum Query {
412+
// More precise neighbors as a trade-off against slower response.
413+
// This is also the default value (field-number 0).
414+
PRECISE = 0;
415+
416+
// Faster response as a trade-off against less precise neighbors.
417+
FAST = 1;
418+
}
419+
420+
// Preset option controlling parameters for different modalities
421+
enum Modality {
422+
// Should not be set. Added as a recommended best practice for enums
423+
MODALITY_UNSPECIFIED = 0;
424+
425+
// IMAGE modality
426+
IMAGE = 1;
427+
428+
// TEXT modality
429+
TEXT = 2;
430+
431+
// TABULAR modality
432+
TABULAR = 3;
433+
}
434+
435+
// Preset option controlling parameters for query speed-precision trade-off
436+
optional Query query = 1;
437+
438+
// Preset option controlling parameters for different modalities
439+
Modality modality = 2;
440+
}
441+
387442
// The [ExplanationSpec][google.cloud.aiplatform.v1beta1.ExplanationSpec] entries that can be overridden at
388443
// [online explanation][google.cloud.aiplatform.v1beta1.PredictionService.Explain] time.
389444
message ExplanationSpecOverride {
@@ -394,6 +449,9 @@ message ExplanationSpecOverride {
394449

395450
// The metadata to be overridden. If not specified, no metadata is overridden.
396451
ExplanationMetadataOverride metadata = 2;
452+
453+
// The example-based explanations parameter overrides.
454+
ExamplesOverride examples_override = 3;
397455
}
398456

399457
// The [ExplanationMetadata][google.cloud.aiplatform.v1beta1.ExplanationMetadata] entries that can be overridden at
@@ -418,3 +476,45 @@ message ExplanationMetadataOverride {
418476
// overridden.
419477
map<string, InputMetadataOverride> inputs = 1 [(google.api.field_behavior) = REQUIRED];
420478
}
479+
480+
// Overrides for example-based explanations.
481+
message ExamplesOverride {
482+
// Data format enum.
483+
enum DataFormat {
484+
// Unspecified format. Must not be used.
485+
DATA_FORMAT_UNSPECIFIED = 0;
486+
487+
// Provided data is a set of model inputs.
488+
INSTANCES = 1;
489+
490+
// Provided data is a set of embeddings.
491+
EMBEDDINGS = 2;
492+
}
493+
494+
// The number of neighbors to return.
495+
int32 neighbor_count = 1;
496+
497+
// The number of neighbors to return that have the same crowding tag.
498+
int32 crowding_count = 2;
499+
500+
// Restrict the resulting nearest neighbors to respect these constraints.
501+
repeated ExamplesRestrictionsNamespace restrictions = 3;
502+
503+
// If true, return the embeddings instead of neighbors.
504+
bool return_embeddings = 4;
505+
506+
// The format of the data being provided with each call.
507+
DataFormat data_format = 5;
508+
}
509+
510+
// Restrictions namespace for example-based explanations overrides.
511+
message ExamplesRestrictionsNamespace {
512+
// The namespace name.
513+
string namespace_name = 1;
514+
515+
// The list of allowed tags.
516+
repeated string allow = 2;
517+
518+
// The list of deny tags.
519+
repeated string deny = 3;
520+
}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -392,4 +392,7 @@ message ExplanationMetadata {
392392
// than the one given on input. The output URI will point to a location where
393393
// the user only has a read access.
394394
string feature_attributions_schema_uri = 3;
395+
396+
// Name of the source to generate embeddings for example based explanations.
397+
string latent_space_source = 5;
395398
}

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import "google/api/annotations.proto";
2020
import "google/api/client.proto";
2121
import "google/api/field_behavior.proto";
2222
import "google/api/resource.proto";
23+
import "google/cloud/aiplatform/v1beta1/explanation.proto";
2324
import "google/cloud/aiplatform/v1beta1/io.proto";
2425
import "google/cloud/aiplatform/v1beta1/model.proto";
2526
import "google/cloud/aiplatform/v1beta1/model_evaluation.proto";
@@ -87,6 +88,19 @@ service ModelService {
8788
option (google.api.method_signature) = "model,update_mask";
8889
}
8990

91+
// Incremental update the dataset used for a examples model.
92+
rpc UpdateExplanationDataset(UpdateExplanationDatasetRequest) returns (google.longrunning.Operation) {
93+
option (google.api.http) = {
94+
post: "/v1beta1/{model=projects/*/locations/*/models/*}:updateExplanationDataset"
95+
body: "*"
96+
};
97+
option (google.api.method_signature) = "model";
98+
option (google.longrunning.operation_info) = {
99+
response_type: "UpdateExplanationDatasetResponse"
100+
metadata_type: "UpdateExplanationDatasetOperationMetadata"
101+
};
102+
}
103+
90104
// Deletes a Model.
91105
//
92106
// A model cannot be deleted if any [Endpoint][google.cloud.aiplatform.v1beta1.Endpoint] resource has a
@@ -233,6 +247,16 @@ message UploadModelResponse {
233247
message GetModelRequest {
234248
// Required. The name of the Model resource.
235249
// Format: `projects/{project}/locations/{location}/models/{model}`
250+
//
251+
// In order to retrieve a specific version of the model, also provide
252+
// the version ID or version alias.
253+
// Example: projects/{project}/locations/{location}/models/{model}@2
254+
// or
255+
// projects/{project}/locations/{location}/models/{model}@golden
256+
// If no version ID or alias is specified, the "default" version will be
257+
// returned. The "default" version alias is created for the first version of
258+
// the model, and can be moved to other versions later on. There will be
259+
// exactly one default version.
236260
string name = 1 [
237261
(google.api.field_behavior) = REQUIRED,
238262
(google.api.resource_reference) = {
@@ -366,6 +390,29 @@ message UpdateModelRequest {
366390
google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
367391
}
368392

393+
// Request message for
394+
// [ModelService.UpdateExplanationDataset][google.cloud.aiplatform.v1beta1.ModelService.UpdateExplanationDataset].
395+
message UpdateExplanationDatasetRequest {
396+
// Required. The resource name of the Model to update.
397+
// Format: `projects/{project}/locations/{location}/models/{model}`
398+
string model = 1 [
399+
(google.api.field_behavior) = REQUIRED,
400+
(google.api.resource_reference) = {
401+
type: "aiplatform.googleapis.com/Model"
402+
}
403+
];
404+
405+
// The example config containing the location of the dataset.
406+
Examples examples = 2;
407+
}
408+
409+
// Runtime operation information for
410+
// [ModelService.UpdateExplanationDataset][google.cloud.aiplatform.v1beta1.ModelService.UpdateExplanationDataset].
411+
message UpdateExplanationDatasetOperationMetadata {
412+
// The common part of the operation metadata.
413+
GenericOperationMetadata generic_metadata = 1;
414+
}
415+
369416
// Request message for [ModelService.DeleteModel][google.cloud.aiplatform.v1beta1.ModelService.DeleteModel].
370417
message DeleteModelRequest {
371418
// Required. The name of the Model resource to be deleted.
@@ -448,6 +495,8 @@ message ExportModelRequest {
448495
}
449496

450497
// Required. The resource name of the Model to export.
498+
// The resource name may contain version id or version alias to specify the
499+
// version, if no version is specified, the default version will be exported.
451500
string name = 1 [
452501
(google.api.field_behavior) = REQUIRED,
453502
(google.api.resource_reference) = {
@@ -481,6 +530,11 @@ message ExportModelOperationMetadata {
481530
OutputInfo output_info = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
482531
}
483532

533+
// Response message of [ModelService.UpdateExplanationDataset][google.cloud.aiplatform.v1beta1.ModelService.UpdateExplanationDataset] operation.
534+
message UpdateExplanationDatasetResponse {
535+
536+
}
537+
484538
// Response message of [ModelService.ExportModel][google.cloud.aiplatform.v1beta1.ModelService.ExportModel] operation.
485539
message ExportModelResponse {
486540

0 commit comments

Comments
 (0)