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

Commit

Permalink
feat: add Examples to Explanation related messages in aiplatform v1be…
Browse files Browse the repository at this point in the history 
…ta1 explanation.proto (#307)

* feat: add Examples to Explanation related messages in aiplatform v1beta1 explanation.proto
  • Loading branch information
@gcf-owl-bot
gcf-owl-bot[bot] authored May 20, 2022
1 parent 13beaa9 commit c69ac2b
Show file tree
Hide file tree
Showing 14 changed files with 3,498 additions and 40 deletions.
108 changes: 104 additions & 4 deletions protos/google/cloud/aiplatform/v1beta1/explanation.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 {
Expand All @@ -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
Expand All @@ -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;
}
3 changes: 3 additions & 0 deletions protos/google/cloud/aiplatform/v1beta1/explanation_metadata.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
54 changes: 54 additions & 0 deletions protos/google/cloud/aiplatform/v1beta1/model_service.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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) = {
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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) = {
Expand Down Expand Up @@ -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 {

Expand Down
Loading

0 comments on commit c69ac2b

Please sign in to comment.