From b5d0197dce43a7c81a38573b5c1efc8da14a27df Mon Sep 17 00:00:00 2001 From: Google APIs Date: Fri, 12 Apr 2024 14:11:49 -0700 Subject: [PATCH] feat: add model_monitor resource and APIs to public v1beta1 client library PiperOrigin-RevId: 624288685 --- google/cloud/aiplatform/v1beta1/BUILD.bazel | 6 + .../v1beta1/aiplatform_v1beta1.yaml | 7 + .../aiplatform/v1beta1/model_monitor.proto | 184 +++++++ .../v1beta1/model_monitoring_alert.proto | 91 ++++ .../v1beta1/model_monitoring_job.proto | 118 +++++ .../v1beta1/model_monitoring_service.proto | 475 ++++++++++++++++++ .../v1beta1/model_monitoring_spec.proto | 294 +++++++++++ .../v1beta1/model_monitoring_stats.proto | 137 +++++ .../cloud/aiplatform/v1beta1/schedule.proto | 5 + 9 files changed, 1317 insertions(+) create mode 100644 google/cloud/aiplatform/v1beta1/model_monitor.proto create mode 100644 google/cloud/aiplatform/v1beta1/model_monitoring_alert.proto create mode 100644 google/cloud/aiplatform/v1beta1/model_monitoring_job.proto create mode 100644 google/cloud/aiplatform/v1beta1/model_monitoring_service.proto create mode 100644 google/cloud/aiplatform/v1beta1/model_monitoring_spec.proto create mode 100644 google/cloud/aiplatform/v1beta1/model_monitoring_stats.proto diff --git a/google/cloud/aiplatform/v1beta1/BUILD.bazel b/google/cloud/aiplatform/v1beta1/BUILD.bazel index 37f5b4494439b..b5edf74c2f100 100644 --- a/google/cloud/aiplatform/v1beta1/BUILD.bazel +++ b/google/cloud/aiplatform/v1beta1/BUILD.bazel @@ -90,7 +90,13 @@ proto_library( "model_evaluation.proto", "model_evaluation_slice.proto", "model_garden_service.proto", + "model_monitor.proto", "model_monitoring.proto", + "model_monitoring_alert.proto", + "model_monitoring_job.proto", + "model_monitoring_service.proto", + "model_monitoring_spec.proto", + "model_monitoring_stats.proto", "model_service.proto", "nas_job.proto", "network_spec.proto", diff --git a/google/cloud/aiplatform/v1beta1/aiplatform_v1beta1.yaml b/google/cloud/aiplatform/v1beta1/aiplatform_v1beta1.yaml index 9bcbc4ab36c81..0014efe040042 100644 --- a/google/cloud/aiplatform/v1beta1/aiplatform_v1beta1.yaml +++ b/google/cloud/aiplatform/v1beta1/aiplatform_v1beta1.yaml @@ -23,6 +23,7 @@ apis: - name: google.cloud.aiplatform.v1beta1.MetadataService - name: google.cloud.aiplatform.v1beta1.MigrationService - name: google.cloud.aiplatform.v1beta1.ModelGardenService +- name: google.cloud.aiplatform.v1beta1.ModelMonitoringService - name: google.cloud.aiplatform.v1beta1.ModelService - name: google.cloud.aiplatform.v1beta1.NotebookService - name: google.cloud.aiplatform.v1beta1.PersistentResourceService @@ -67,6 +68,7 @@ types: - name: google.cloud.aiplatform.v1beta1.CreateIndexEndpointOperationMetadata - name: google.cloud.aiplatform.v1beta1.CreateIndexOperationMetadata - name: google.cloud.aiplatform.v1beta1.CreateMetadataStoreOperationMetadata +- name: google.cloud.aiplatform.v1beta1.CreateModelMonitorOperationMetadata - name: google.cloud.aiplatform.v1beta1.CreateNotebookRuntimeTemplateOperationMetadata - name: google.cloud.aiplatform.v1beta1.CreatePersistentResourceOperationMetadata - name: google.cloud.aiplatform.v1beta1.CreateRegistryFeatureOperationMetadata @@ -125,6 +127,7 @@ types: - name: google.cloud.aiplatform.v1beta1.UpdateFeaturestoreOperationMetadata - name: google.cloud.aiplatform.v1beta1.UpdateIndexOperationMetadata - name: google.cloud.aiplatform.v1beta1.UpdateModelDeploymentMonitoringJobOperationMetadata +- name: google.cloud.aiplatform.v1beta1.UpdateModelMonitorOperationMetadata - name: google.cloud.aiplatform.v1beta1.UpdatePersistentResourceOperationMetadata - name: google.cloud.aiplatform.v1beta1.UpdateSpecialistPoolOperationMetadata - name: google.cloud.aiplatform.v1beta1.UpdateTensorboardOperationMetadata @@ -814,6 +817,10 @@ authentication: oauth: canonical_scopes: |- https://www.googleapis.com/auth/cloud-platform + - selector: 'google.cloud.aiplatform.v1beta1.ModelMonitoringService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform - selector: 'google.cloud.aiplatform.v1beta1.ModelService.*' oauth: canonical_scopes: |- diff --git a/google/cloud/aiplatform/v1beta1/model_monitor.proto b/google/cloud/aiplatform/v1beta1/model_monitor.proto new file mode 100644 index 0000000000000..590c17746f190 --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/model_monitor.proto @@ -0,0 +1,184 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/cloud/aiplatform/v1beta1/explanation.proto"; +import "google/cloud/aiplatform/v1beta1/model_monitoring_spec.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ModelMonitorProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; + +// Vertex AI Model Monitoring Service serves as a central hub for the analysis +// and visualization of data quality and performance related to models. +// ModelMonitor stands as a top level resource for overseeing your model +// monitoring tasks. +message ModelMonitor { + option (google.api.resource) = { + type: "aiplatform.googleapis.com/ModelMonitor" + pattern: "projects/{project}/locations/{location}/modelMonitors/{model_monitor}" + }; + + // The monitoring target refers to the entity that is subject to analysis. + // e.g. Vertex AI Model version. + message ModelMonitoringTarget { + // Model in Vertex AI Model Registry. + message VertexModelSource { + // Model resource name. Format: + // projects/{project}/locations/{location}/models/{model}. + string model = 1 [(google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Model" + }]; + + // Model version id. + string model_version_id = 2; + } + + oneof source { + // Model in Vertex AI Model Registry. + VertexModelSource vertex_model = 1; + } + } + + // Optional default monitoring objective, it can be overridden in the + // ModelMonitoringJob objective spec. + oneof default_objective { + // Optional default tabular model monitoring objective. + ModelMonitoringObjectiveSpec.TabularObjective tabular_objective = 11; + } + + // Immutable. Resource name of the ModelMonitor. Format: + // `projects/{project}/locations/{location}/modelMonitors/{model_monitor}`. + string name = 1 [(google.api.field_behavior) = IMMUTABLE]; + + // The display name of the ModelMonitor. + // The name can be up to 128 characters long and can consist of any UTF-8. + string display_name = 2; + + // The entity that is subject to analysis. + // Currently only models in Vertex AI Model Registry are supported. If you + // want to analyze the model which is outside the Vertex AI, you could + // register a model in Vertex AI Model Registry using just a display name. + ModelMonitoringTarget model_monitoring_target = 3; + + // Optional training dataset used to train the model. + // It can serve as a reference dataset to identify changes in production. + ModelMonitoringInput training_dataset = 10; + + // Optional default notification spec, it can be overridden in the + // ModelMonitoringJob notification spec. + ModelMonitoringNotificationSpec notification_spec = 12; + + // Optional default monitoring metrics/logs export spec, it can be overridden + // in the ModelMonitoringJob output spec. + // If not specified, a default Google Cloud Storage bucket will be created + // under your project. + ModelMonitoringOutputSpec output_spec = 13; + + // Optional model explanation spec. It is used for feature attribution + // monitoring. + ExplanationSpec explanation_spec = 16; + + // Monitoring Schema is to specify the model's features, prediction outputs + // and ground truth properties. It is used to extract pertinent data from the + // dataset and to process features based on their properties. + // Make sure that the schema aligns with your dataset, if it does not, we will + // be unable to extract data from the dataset. + // It is required for most models, but optional for Vertex AI AutoML Tables + // unless the schem information is not available. + ModelMonitoringSchema model_monitoring_schema = 9; + + // Output only. Timestamp when this ModelMonitor was created. + google.protobuf.Timestamp create_time = 6 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Timestamp when this ModelMonitor was updated most recently. + google.protobuf.Timestamp update_time = 7 + [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// The Model Monitoring Schema definition. +message ModelMonitoringSchema { + // Schema field definition. + message FieldSchema { + // Field name. + string name = 1; + + // Supported data types are: + // `float` + // `integer` + // `boolean` + // `string` + // `categorical` + string data_type = 2; + + // Describes if the schema field is an array of given data type. + bool repeated = 3; + } + + // Feature names of the model. Vertex AI will try to match the features from + // your dataset as follows: + // * For 'csv' files, the header names are required, and we will extract the + // corresponding feature values when the header names align with the + // feature names. + // * For 'jsonl' files, we will extract the corresponding feature values if + // the key names match the feature names. + // Note: Nested features are not supported, so please ensure your features + // are flattened. Ensure the feature values are scalar or an array of + // scalars. + // * For 'bigquery' dataset, we will extract the corresponding feature values + // if the column names match the feature names. + // Note: The column type can be a scalar or an array of scalars. STRUCT or + // JSON types are not supported. You may use SQL queries to select or + // aggregate the relevant features from your original table. However, + // ensure that the 'schema' of the query results meets our requirements. + // * For the Vertex AI Endpoint Request Response Logging table or Vertex AI + // Batch Prediction Job results. If the + // [instance_type][google.cloud.aiplatform.v1beta1.ModelMonitoringSchema.instance_type] + // is an array, ensure that the sequence in + // [feature_fields][google.cloud.aiplatform.v1beta1.ModelMonitoringSchema.feature_fields] + // matches the order of features in the prediction instance. We will match + // the feature with the array in the order specified in [feature_fields]. + repeated FieldSchema feature_fields = 1; + + // Prediction output names of the model. The requirements are the same as the + // [feature_fields][google.cloud.aiplatform.v1beta1.ModelMonitoringSchema.feature_fields]. + // For AutoML Tables, the prediction output name presented in schema will be: + // `predicted_{target_column}`, the `target_column` is the one you specified + // when you train the model. + // For Prediction output drift analysis: + // * AutoML Classification, the distribution of the argmax label will be + // analyzed. + // * AutoML Regression, the distribution of the value will be analyzed. + repeated FieldSchema prediction_fields = 2; + + // Target /ground truth names of the model. + repeated FieldSchema ground_truth_fields = 3; + + // The prediction instance type that the Model accepts when serving. + // Supported values are: + // * `object`: Each input is a JSON object format. + // * `array`: Each input is a JSON array format. + string instance_type = 4; +} diff --git a/google/cloud/aiplatform/v1beta1/model_monitoring_alert.proto b/google/cloud/aiplatform/v1beta1/model_monitoring_alert.proto new file mode 100644 index 0000000000000..16bf84f24c458 --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/model_monitoring_alert.proto @@ -0,0 +1,91 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ModelMonitoringAlertProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; + +// Monitoring alert triggered condition. +message ModelMonitoringAlertCondition { + // Alert triggered condition. + oneof condition { + // A condition that compares a stats value against a threshold. Alert will + // be triggered if value above the threshold. + double threshold = 1; + } +} + +// Represents a single model monitoring anomaly. +message ModelMonitoringAnomaly { + // Tabular anomaly details. + message TabularAnomaly { + // Additional anomaly information. e.g. Google Cloud Storage uri. + string anomaly_uri = 1; + + // Overview of this anomaly. + string summary = 2; + + // Anomaly body. + google.protobuf.Value anomaly = 3; + + // The time the anomaly was triggered. + google.protobuf.Timestamp trigger_time = 4; + + // The alert condition associated with this anomaly. + ModelMonitoringAlertCondition condition = 5; + } + + oneof anomaly { + // Tabular anomaly. + TabularAnomaly tabular_anomaly = 1; + } + + // Model monitoring job resource name. + string model_monitoring_job = 2; + + // Algorithm used to calculated the metrics, eg: jensen_shannon_divergence, + // l_infinity. + string algorithm = 3; +} + +// Represents a single monitoring alert. This is currently used in the +// SearchModelMonitoringAlerts api, thus the alert wrapped in this message +// belongs to the resource asked in the request. +message ModelMonitoringAlert { + // The stats name. + string stats_name = 1; + + // One of the supported monitoring objectives: + // `raw-feature-drift` + // `prediction-output-drift` + // `feature-attribution` + string objective_type = 2; + + // Alert creation time. + google.protobuf.Timestamp alert_time = 3; + + // Anomaly details. + ModelMonitoringAnomaly anomaly = 4; +} diff --git a/google/cloud/aiplatform/v1beta1/model_monitoring_job.proto b/google/cloud/aiplatform/v1beta1/model_monitoring_job.proto new file mode 100644 index 0000000000000..d054e74443ae0 --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/model_monitoring_job.proto @@ -0,0 +1,118 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/cloud/aiplatform/v1beta1/job_state.proto"; +import "google/cloud/aiplatform/v1beta1/model_monitoring_spec.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; +import "google/type/interval.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ModelMonitoringJobProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; + +// Represents a model monitoring job that analyze dataset using different +// monitoring algorithm. +message ModelMonitoringJob { + option (google.api.resource) = { + type: "aiplatform.googleapis.com/ModelMonitoringJob" + pattern: "projects/{project}/locations/{location}/modelMonitors/{model_monitor}/modelMonitoringJobs/{model_monitoring_job}" + }; + + // Output only. Resource name of a ModelMonitoringJob. Format: + // `projects/{project_id}/locations/{location_id}/modelMonitors/{model_monitor_id}/modelMonitoringJobs/{model_monitoring_job_id}` + string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // The display name of the ModelMonitoringJob. + // The name can be up to 128 characters long and can consist of any UTF-8. + string display_name = 2; + + // Monitoring monitoring job spec. It outlines the specifications for + // monitoring objectives, notifications, and result exports. If left blank, + // the default monitoring specifications from the top-level resource + // 'ModelMonitor' will be applied. If provided, we will use the specification + // defined here rather than the default one. + ModelMonitoringSpec model_monitoring_spec = 3; + + // Output only. Timestamp when this ModelMonitoringJob was created. + google.protobuf.Timestamp create_time = 4 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Timestamp when this ModelMonitoringJob was updated most + // recently. + google.protobuf.Timestamp update_time = 5 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The state of the monitoring job. + // * When the job is still creating, the state will be 'JOB_STATE_PENDING'. + // * Once the job is successfully created, the state will be + // 'JOB_STATE_RUNNING'. + // * Once the job is finished, the state will be one of + // 'JOB_STATE_FAILED', 'JOB_STATE_SUCCEEDED', + // 'JOB_STATE_PARTIALLY_SUCCEEDED'. + JobState state = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Schedule resource name. It will only appear when this job is + // triggered by a schedule. + string schedule = 7 [ + (google.api.field_behavior) = OUTPUT_ONLY, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Schedule" + } + ]; + + // Output only. Execution results for all the monitoring objectives. + ModelMonitoringJobExecutionDetail job_execution_detail = 8 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Timestamp when this ModelMonitoringJob was scheduled. It will + // only appear when this job is triggered by a schedule. + google.protobuf.Timestamp schedule_time = 9 + [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// Represent the execution details of the job. +message ModelMonitoringJobExecutionDetail { + // Processed dataset information. + message ProcessedDataset { + // Actual data location of the processed dataset. + string location = 1; + + // Dataset time range information if any. + google.type.Interval time_range = 2; + } + + // Processed baseline datasets. + repeated ProcessedDataset baseline_datasets = 1; + + // Processed target datasets. + repeated ProcessedDataset target_datasets = 2; + + // Status of data processing for each monitoring objective. + // Key is the objective. + map objective_status = 3; + + // Additional job error status. + google.rpc.Status error = 4; +} diff --git a/google/cloud/aiplatform/v1beta1/model_monitoring_service.proto b/google/cloud/aiplatform/v1beta1/model_monitoring_service.proto new file mode 100644 index 0000000000000..c29d86744c33e --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/model_monitoring_service.proto @@ -0,0 +1,475 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +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/model_monitor.proto"; +import "google/cloud/aiplatform/v1beta1/model_monitoring_alert.proto"; +import "google/cloud/aiplatform/v1beta1/model_monitoring_job.proto"; +import "google/cloud/aiplatform/v1beta1/model_monitoring_stats.proto"; +import "google/cloud/aiplatform/v1beta1/operation.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/type/interval.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ModelMonitoringServiceProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; + +// A service for creating and managing Vertex AI Model moitoring. This includes +// `ModelMonitor` resources, `ModelMonitoringJob` resources. +service ModelMonitoringService { + option (google.api.default_host) = "aiplatform.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-platform"; + + // Creates a ModelMonitor. + rpc CreateModelMonitor(CreateModelMonitorRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/locations/*}/modelMonitors" + body: "model_monitor" + }; + option (google.api.method_signature) = "parent,model_monitor"; + option (google.longrunning.operation_info) = { + response_type: "ModelMonitor" + metadata_type: "CreateModelMonitorOperationMetadata" + }; + } + + // Updates a ModelMonitor. + rpc UpdateModelMonitor(UpdateModelMonitorRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + patch: "/v1beta1/{model_monitor.name=projects/*/locations/*/modelMonitors/*}" + body: "model_monitor" + }; + option (google.api.method_signature) = "model_monitor,update_mask"; + option (google.longrunning.operation_info) = { + response_type: "ModelMonitor" + metadata_type: "UpdateModelMonitorOperationMetadata" + }; + } + + // Gets a ModelMonitor. + rpc GetModelMonitor(GetModelMonitorRequest) returns (ModelMonitor) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/modelMonitors/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Lists ModelMonitors in a Location. + rpc ListModelMonitors(ListModelMonitorsRequest) + returns (ListModelMonitorsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*}/modelMonitors" + }; + option (google.api.method_signature) = "parent"; + } + + // Deletes a ModelMonitor. + rpc DeleteModelMonitor(DeleteModelMonitorRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/locations/*/modelMonitors/*}" + }; + option (google.api.method_signature) = "name"; + option (google.longrunning.operation_info) = { + response_type: "google.protobuf.Empty" + metadata_type: "DeleteOperationMetadata" + }; + } + + // Creates a ModelMonitoringJob. + rpc CreateModelMonitoringJob(CreateModelMonitoringJobRequest) + returns (ModelMonitoringJob) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/locations/*/modelMonitors/*}/modelMonitoringJobs" + body: "model_monitoring_job" + }; + option (google.api.method_signature) = "parent,model_monitoring_job"; + } + + // Gets a ModelMonitoringJob. + rpc GetModelMonitoringJob(GetModelMonitoringJobRequest) + returns (ModelMonitoringJob) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/modelMonitors/*/modelMonitoringJobs/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Lists ModelMonitoringJobs. + // Callers may choose to read across multiple Monitors as per + // [AIP-159](https://google.aip.dev/159) by using '-' (the hyphen or dash + // character) as a wildcard character instead of modelMonitor id in the + // parent. Format + // `projects/{project_id}/locations/{location}/moodelMonitors/-/modelMonitoringJobs` + rpc ListModelMonitoringJobs(ListModelMonitoringJobsRequest) + returns (ListModelMonitoringJobsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*/modelMonitors/*}/modelMonitoringJobs" + }; + option (google.api.method_signature) = "parent"; + } + + // Deletes a ModelMonitoringJob. + rpc DeleteModelMonitoringJob(DeleteModelMonitoringJobRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/locations/*/modelMonitors/*/modelMonitoringJobs/*}" + }; + option (google.api.method_signature) = "name"; + option (google.longrunning.operation_info) = { + response_type: "google.protobuf.Empty" + metadata_type: "DeleteOperationMetadata" + }; + } + + // Searches Model Monitoring Stats generated within a given time window. + rpc SearchModelMonitoringStats(SearchModelMonitoringStatsRequest) + returns (SearchModelMonitoringStatsResponse) { + option (google.api.http) = { + post: "/v1beta1/{model_monitor=projects/*/locations/*/modelMonitors/*}:searchModelMonitoringStats" + body: "*" + }; + option (google.api.method_signature) = "model_monitor"; + } + + // Returns the Model Monitoring alerts. + rpc SearchModelMonitoringAlerts(SearchModelMonitoringAlertsRequest) + returns (SearchModelMonitoringAlertsResponse) { + option (google.api.http) = { + post: "/v1beta1/{model_monitor=projects/*/locations/*/modelMonitors/*}:searchModelMonitoringAlerts" + body: "*" + }; + option (google.api.method_signature) = "model_monitor"; + } +} + +// Request message for +// [ModelMonitoringService.CreateModelMonitor][google.cloud.aiplatform.v1beta1.ModelMonitoringService.CreateModelMonitor]. +message CreateModelMonitorRequest { + // Required. The resource name of the Location to create the ModelMonitor in. + // Format: `projects/{project}/locations/{location}` + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "locations.googleapis.com/Location" + } + ]; + + // Required. The ModelMonitor to create. + ModelMonitor model_monitor = 2 [(google.api.field_behavior) = REQUIRED]; + + // Optional. The ID to use for the Model Monitor, which will become the final + // component of the model monitor resource name. + // + // The maximum length is 63 characters, and valid characters are + // `/^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/`. + string model_monitor_id = 3 [(google.api.field_behavior) = OPTIONAL]; +} + +// Runtime operation information for +// [ModelMonitoringService.CreateModelMonitor][google.cloud.aiplatform.v1beta1.ModelMonitoringService.CreateModelMonitor]. +message CreateModelMonitorOperationMetadata { + // The operation generic information. + GenericOperationMetadata generic_metadata = 1; +} + +// Request message for +// [ModelMonitoringService.UpdateModelMonitor][google.cloud.aiplatform.v1beta1.ModelMonitoringService.UpdateModelMonitor]. +message UpdateModelMonitorRequest { + // Required. The model monitoring configuration which replaces the resource on + // the server. + ModelMonitor model_monitor = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. Mask specifying which fields to update. + google.protobuf.FieldMask update_mask = 2 + [(google.api.field_behavior) = REQUIRED]; +} + +// Runtime operation information for +// [ModelMonitoringService.UpdateModelMonitor][google.cloud.aiplatform.v1beta1.ModelMonitoringService.UpdateModelMonitor]. +message UpdateModelMonitorOperationMetadata { + // The operation generic information. + GenericOperationMetadata generic_metadata = 1; +} + +// Request message for +// [ModelMonitoringService.GetModelMonitor][google.cloud.aiplatform.v1beta1.ModelMonitoringService.GetModelMonitor]. +message GetModelMonitorRequest { + // Required. The name of the ModelMonitor resource. + // Format: + // `projects/{project}/locations/{location}/modelMonitors/{model_monitor}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/ModelMonitor" + } + ]; +} + +// Request message for +// [ModelMonitoringService.ListModelMonitors][google.cloud.aiplatform.v1beta1.ModelMonitoringService.ListModelMonitors]. +message ListModelMonitorsRequest { + // Required. The resource name of the Location to list the ModelMonitors from. + // Format: `projects/{project}/locations/{location}` + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "locations.googleapis.com/Location" + } + ]; + + // The standard list filter. + // More detail in [AIP-160](https://google.aip.dev/160). + string filter = 2; + + // The standard list page size. + int32 page_size = 3; + + // The standard list page token. + string page_token = 4; + + // Mask specifying which fields to read. + google.protobuf.FieldMask read_mask = 5; +} + +// Response message for +// [ModelMonitoringService.ListModelMonitors][google.cloud.aiplatform.v1beta1.ModelMonitoringService.ListModelMonitors] +message ListModelMonitorsResponse { + // List of ModelMonitor in the requested page. + repeated ModelMonitor model_monitors = 1; + + // A token to retrieve the next page of results. + // Pass to + // [ListModelMonitorsRequest.page_token][google.cloud.aiplatform.v1beta1.ListModelMonitorsRequest.page_token] + // to obtain that page. + string next_page_token = 2; +} + +// Request message for +// [ModelMonitoringService.DeleteModelMonitor][google.cloud.aiplatform.v1beta1.ModelMonitoringService.DeleteModelMonitor]. +message DeleteModelMonitorRequest { + // Required. The name of the ModelMonitor resource to be deleted. + // Format: + // `projects/{project}/locations/{location}/modelMonitords/{model_monitor}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/ModelMonitor" + } + ]; + + // Optional. Force delete the model monitor with schedules. + bool force = 2 [(google.api.field_behavior) = OPTIONAL]; +} + +// Request message for +// [ModelMonitoringService.CreateModelMonitoringJob][google.cloud.aiplatform.v1beta1.ModelMonitoringService.CreateModelMonitoringJob]. +message CreateModelMonitoringJobRequest { + // Required. The parent of the ModelMonitoringJob. + // Format: + // `projects/{project}/locations/{location}/modelMoniitors/{model_monitor}` + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/ModelMonitor" + } + ]; + + // Required. The ModelMonitoringJob to create + ModelMonitoringJob model_monitoring_job = 2 + [(google.api.field_behavior) = REQUIRED]; + + // Optional. The ID to use for the Model Monitoring Job, which will become the + // final component of the model monitoring job resource name. + // + // The maximum length is 63 characters, and valid characters are + // `/^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/`. + string model_monitoring_job_id = 3 [(google.api.field_behavior) = OPTIONAL]; +} + +// Request message for +// [ModelMonitoringService.GetModelMonitoringJob][google.cloud.aiplatform.v1beta1.ModelMonitoringService.GetModelMonitoringJob]. +message GetModelMonitoringJobRequest { + // Required. The resource name of the ModelMonitoringJob. + // Format: + // `projects/{project}/locations/{location}/modelMonitors/{model_monitor}/modelMonitoringJobs/{model_monitoring_job}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/ModelMonitoringJob" + } + ]; +} + +// Request message for +// [ModelMonitoringService.ListModelMonitoringJobs][google.cloud.aiplatform.v1beta1.ModelMonitoringService.ListModelMonitoringJobs]. +message ListModelMonitoringJobsRequest { + // Required. The parent of the ModelMonitoringJob. + // Format: + // `projects/{project}/locations/{location}/modelMonitors/{model_monitor}` + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/ModelMonitor" + } + ]; + + // The standard list filter. + // More detail in [AIP-160](https://google.aip.dev/160). + string filter = 2; + + // The standard list page size. + int32 page_size = 3; + + // The standard list page token. + string page_token = 4; + + // Mask specifying which fields to read + google.protobuf.FieldMask read_mask = 5; +} + +// Response message for +// [ModelMonitoringService.ListModelMonitoringJobs][google.cloud.aiplatform.v1beta1.ModelMonitoringService.ListModelMonitoringJobs]. +message ListModelMonitoringJobsResponse { + // A list of ModelMonitoringJobs that matches the specified filter + // in the request. + repeated ModelMonitoringJob model_monitoring_jobs = 1; + + // The standard List next-page token. + string next_page_token = 2; +} + +// Request message for +// [ModelMonitoringService.DeleteModelMonitoringJob][google.cloud.aiplatform.v1beta1.ModelMonitoringService.DeleteModelMonitoringJob]. +message DeleteModelMonitoringJobRequest { + // Required. The resource name of the model monitoring job to delete. + // Format: + // `projects/{project}/locations/{location}/modelMonitors/{model_monitor}/modelMonitoringJobs/{model_monitoring_job}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/ModelMonitoringJob" + } + ]; +} + +// Request message for +// [ModelMonitoringService.SearchModelMonitoringStats][google.cloud.aiplatform.v1beta1.ModelMonitoringService.SearchModelMonitoringStats]. +message SearchModelMonitoringStatsRequest { + // Required. ModelMonitor resource name. + // Format: + // `projects/{project}/locations/{location}/modelMonitors/{model_monitor}` + string model_monitor = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/ModelMonitor" + } + ]; + + // Filter for search different stats. + SearchModelMonitoringStatsFilter stats_filter = 2; + + // The time interval for which results should be returned. + google.type.Interval time_interval = 3; + + // The standard list page size. + int32 page_size = 4; + + // A page token received from a previous + // [ModelMonitoringService.SearchModelMonitoringStats][google.cloud.aiplatform.v1beta1.ModelMonitoringService.SearchModelMonitoringStats] + // call. + string page_token = 5; +} + +// Response message for +// [ModelMonitoringService.SearchModelMonitoringStats][google.cloud.aiplatform.v1beta1.ModelMonitoringService.SearchModelMonitoringStats]. +message SearchModelMonitoringStatsResponse { + // Stats retrieved for requested objectives. + repeated ModelMonitoringStats monitoring_stats = 1; + + // The page token that can be used by the next + // [ModelMonitoringService.SearchModelMonitoringStats][google.cloud.aiplatform.v1beta1.ModelMonitoringService.SearchModelMonitoringStats] + // call. + string next_page_token = 2; +} + +// Request message for +// [ModelMonitoringService.SearchModelMonitoringAlerts][google.cloud.aiplatform.v1beta1.ModelMonitoringService.SearchModelMonitoringAlerts]. +message SearchModelMonitoringAlertsRequest { + // Required. ModelMonitor resource name. + // Format: + // `projects/{project}/locations/{location}/modelMonitors/{model_monitor}` + string model_monitor = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/ModelMonitor" + } + ]; + + // If non-empty, returns the alerts of this model monitoring job. + string model_monitoring_job = 2; + + // If non-empty, returns the alerts in this time interval. + google.type.Interval alert_time_interval = 3; + + // If non-empty, returns the alerts of this stats_name. + string stats_name = 4; + + // If non-empty, returns the alerts of this objective type. + // Supported monitoring objectives: + // `raw-feature-drift` + // `prediction-output-drift` + // `feature-attribution` + string objective_type = 5; + + // The standard list page size. + int32 page_size = 6; + + // A page token received from a previous + // [ModelMonitoringService.SearchModelMonitoringAlerts][google.cloud.aiplatform.v1beta1.ModelMonitoringService.SearchModelMonitoringAlerts] + // call. + string page_token = 7; +} + +// Response message for +// [ModelMonitoringService.SearchModelMonitoringAlerts][google.cloud.aiplatform.v1beta1.ModelMonitoringService.SearchModelMonitoringAlerts]. +message SearchModelMonitoringAlertsResponse { + // Alerts retrieved for the requested objectives. Sorted by alert time + // descendingly. + repeated ModelMonitoringAlert model_monitoring_alerts = 1; + + // The total number of alerts retrieved by the requested objectives. + int64 total_number_alerts = 2; + + // The page token that can be used by the next + // [ModelMonitoringService.SearchModelMonitoringAlerts][google.cloud.aiplatform.v1beta1.ModelMonitoringService.SearchModelMonitoringAlerts] + // call. + string next_page_token = 3; +} diff --git a/google/cloud/aiplatform/v1beta1/model_monitoring_spec.proto b/google/cloud/aiplatform/v1beta1/model_monitoring_spec.proto new file mode 100644 index 0000000000000..5b2ddf9687098 --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/model_monitoring_spec.proto @@ -0,0 +1,294 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +import "google/api/resource.proto"; +import "google/cloud/aiplatform/v1beta1/explanation.proto"; +import "google/cloud/aiplatform/v1beta1/io.proto"; +import "google/cloud/aiplatform/v1beta1/machine_resources.proto"; +import "google/cloud/aiplatform/v1beta1/model_monitoring_alert.proto"; +import "google/type/interval.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ModelMonitoringSpecProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; + +// Monitoring monitoring job spec. It outlines the specifications for monitoring +// objectives, notifications, and result exports. +message ModelMonitoringSpec { + // The monitoring objective spec. + ModelMonitoringObjectiveSpec objective_spec = 1; + + // The model monitoring notification spec. + ModelMonitoringNotificationSpec notification_spec = 2; + + // The Output destination spec for metrics, error logs, etc. + ModelMonitoringOutputSpec output_spec = 3; +} + +// Monitoring objectives spec. +message ModelMonitoringObjectiveSpec { + // Data drift monitoring spec. + // Data drift measures the distribution distance between the current dataset + // and a baseline dataset. A typical use case is to detect data drift between + // the recent production serving dataset and the training dataset, or to + // compare the recent production dataset with a dataset from a previous + // period. + message DataDriftSpec { + // Feature names / Prediction output names interested in monitoring. + // These should be a subset of the input feature names or prediction output + // names specified in the monitoring schema. + // If the field is not specified all features / prediction outputs outlied + // in the monitoring schema will be used. + repeated string features = 1; + + // Supported metrics type: + // * l_infinity + // * jensen_shannon_divergence + string categorical_metric_type = 2; + + // Supported metrics type: + // * jensen_shannon_divergence + string numeric_metric_type = 3; + + // Default alert condition for all the categorical features. + ModelMonitoringAlertCondition default_categorical_alert_condition = 4; + + // Default alert condition for all the numeric features. + ModelMonitoringAlertCondition default_numeric_alert_condition = 5; + + // Per feature alert condition will override default alert condition. + map feature_alert_conditions = 6; + } + + // Feature attribution monitoring spec. + message FeatureAttributionSpec { + // Feature names interested in monitoring. + // These should be a subset of the input feature names specified in the + // monitoring schema. If the field is not specified all features outlied in + // the monitoring schema will be used. + repeated string features = 1; + + // Default alert condition for all the features. + ModelMonitoringAlertCondition default_alert_condition = 2; + + // Per feature alert condition will override default alert condition. + map feature_alert_conditions = 3; + + // The config of resources used by the Model Monitoring during the batch + // explanation for non-AutoML models. If not set, `n1-standard-2` machine + // type will be used by default. + BatchDedicatedResources batch_explanation_dedicated_resources = 4; + } + + // Tabular monitoring objective. + message TabularObjective { + // Input feature distribution drift monitoring spec. + DataDriftSpec feature_drift_spec = 10; + + // Prediction output distribution drift monitoring spec. + DataDriftSpec prediction_output_drift_spec = 11; + + // Feature attribution monitoring spec. + FeatureAttributionSpec feature_attribution_spec = 12; + } + + // The monitoring objective. + oneof objective { + // Tabular monitoring objective. + TabularObjective tabular_objective = 1; + } + + // The explanation spec. + // This spec is required when the objectives spec includes feature attribution + // objectives. + ExplanationSpec explanation_spec = 3; + + // Baseline dataset. + // It could be the training dataset or production serving dataset from a + // previous period. + ModelMonitoringInput baseline_dataset = 4; + + // Target dataset. + ModelMonitoringInput target_dataset = 5; +} + +// Specification for the export destination of monitoring results, including +// metrics, logs, etc. +message ModelMonitoringOutputSpec { + // Google Cloud Storage base folder path for metrics, error logs, etc. + GcsDestination gcs_base_directory = 1; +} + +// Model monitoring data input spec. +message ModelMonitoringInput { + // Input dataset spec. + message ModelMonitoringDataset { + // Dataset spec for data stored in Google Cloud Storage. + message ModelMonitoringGcsSource { + // Supported data format. + enum DataFormat { + // Data format unspecified, used when this field is unset. + DATA_FORMAT_UNSPECIFIED = 0; + + // CSV files. + CSV = 1; + + // TfRecord files + TF_RECORD = 2; + + // JsonL files. + JSONL = 3; + } + + // Google Cloud Storage URI to the input file(s). May contain + // wildcards. For more information on wildcards, see + // https://cloud.google.com/storage/docs/gsutil/addlhelp/WildcardNames. + string gcs_uri = 1; + + // Data format of the dataset. + DataFormat format = 2; + } + + // Dataset spec for data sotred in BigQuery. + message ModelMonitoringBigQuerySource { + oneof connection { + // BigQuery URI to a table, up to 2000 characters long. All the columns + // in the table will be selected. Accepted forms: + // + // * BigQuery path. For example: + // `bq://projectId.bqDatasetId.bqTableId`. + string table_uri = 1; + + // Standard SQL to be used instead of the `table_uri`. + string query = 2; + } + } + + // Choose one of supported data location for columnized dataset. + oneof data_location { + // Resource name of the Vertex AI managed dataset. + string vertex_dataset = 1 [(google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Dataset" + }]; + + // Google Cloud Storage data source. + ModelMonitoringGcsSource gcs_source = 2; + + // BigQuery data source. + ModelMonitoringBigQuerySource bigquery_source = 6; + } + + // The timestamp field. Usually for serving data. + string timestamp_field = 7; + } + + // Data from Vertex AI Batch prediction job output. + message BatchPredictionOutput { + // Vertex AI Batch prediction job resource name. The job must match the + // model version specified in [ModelMonitor].[model_monitoring_target]. + string batch_prediction_job = 1 [(google.api.resource_reference) = { + type: "aiplatform.googleapis.com/BatchPredictionJob" + }]; + } + + // Data from Vertex AI Endpoint request response logging. + message VertexEndpointLogs { + // List of endpoint resource names. The endpoints must enable the logging + // with the [Endpoint].[request_response_logging_config], and must contain + // the deployed model corresponding to the model version specified in + // [ModelMonitor].[model_monitoring_target]. + repeated string endpoints = 1 [(google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Endpoint" + }]; + } + + // Time offset setting. + message TimeOffset { + // [offset] is the time difference from the cut-off time. + // For scheduled jobs, the cut-off time is the scheduled time. + // For non-scheduled jobs, it's the time when the job was created. + // Currently we support the following format: + // 'w|W': Week, 'd|D': Day, 'h|H': Hour + // E.g. '1h' stands for 1 hour, '2d' stands for 2 days. + string offset = 1; + + // [window] refers to the scope of data selected for analysis. + // It allows you to specify the quantity of data you wish to examine. + // Currently we support the following format: + // 'w|W': Week, 'd|D': Day, 'h|H': Hour + // E.g. '1h' stands for 1 hour, '2d' stands for 2 days. + string window = 2; + } + + // Dataset source. + oneof dataset { + // Columnized dataset. + ModelMonitoringDataset columnized_dataset = 1; + + // Vertex AI Batch prediction Job. + BatchPredictionOutput batch_prediction_output = 2; + + // Vertex AI Endpoint request & response logging. + VertexEndpointLogs vertex_endpoint_logs = 3; + } + + // Time specification for the dataset. + oneof time_spec { + // The time interval (pair of start_time and end_time) for which results + // should be returned. + google.type.Interval time_interval = 6; + + // The time offset setting for which results should be returned. + TimeOffset time_offset = 7; + } +} + +// Notification spec(email, notification channel) for model monitoring +// statistics/alerts. +message ModelMonitoringNotificationSpec { + // The config for email alerts. + message EmailConfig { + // The email addresses to send the alerts. + repeated string user_emails = 1; + } + + // Google Cloud Notification Channel config. + message NotificationChannelConfig { + // Resource names of the NotificationChannels. + // Must be of the format + // `projects//notificationChannels/` + string notification_channel = 1; + } + + // Email alert config. + EmailConfig email_config = 1; + + // Dump the anomalies to Cloud Logging. The anomalies will be put to json + // payload encoded from proto + // [google.cloud.aiplatform.logging.ModelMonitoringAnomaliesLogEntry][]. + // This can be further sinked to Pub/Sub or any other services supported + // by Cloud Logging. + bool enable_cloud_logging = 2; + + // Notification channel config. + repeated NotificationChannelConfig notification_channel_configs = 3; +} diff --git a/google/cloud/aiplatform/v1beta1/model_monitoring_stats.proto b/google/cloud/aiplatform/v1beta1/model_monitoring_stats.proto new file mode 100644 index 0000000000000..f5b595ee77346 --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/model_monitoring_stats.proto @@ -0,0 +1,137 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ModelMonitoringStatsProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; + +// Represents the collection of statistics for a metric. +message ModelMonitoringStats { + oneof stats { + // Generated tabular statistics. + ModelMonitoringTabularStats tabular_stats = 1; + } +} + +// Represents a single statistics data point. +message ModelMonitoringStatsDataPoint { + // Typed value of the statistics. + message TypedValue { + // Summary statistics for a population of values. + message DistributionDataValue { + // tensorflow.metadata.v0.DatasetFeatureStatistics format. + google.protobuf.Value distribution = 1; + + // Distribution distance deviation from the current dataset's statistics + // to baseline dataset's statistics. + // * For categorical feature, the distribution distance is calculated + // by L-inifinity norm or Jensen–Shannon divergence. + // * For numerical feature, the distribution distance is calculated by + // Jensen–Shannon divergence. + double distribution_deviation = 2; + } + + // The typed value. + oneof value { + // Double. + double double_value = 1; + + // Distribution. + DistributionDataValue distribution_value = 2; + } + } + + // Statistics from current dataset. + TypedValue current_stats = 1; + + // Statistics from baseline dataset. + TypedValue baseline_stats = 2; + + // Threshold value. + double threshold_value = 3; + + // Indicate if the statistics has anomaly. + bool has_anomaly = 4; + + // Model monitoring job resource name. + string model_monitoring_job = 5; + + // Schedule resource name. + string schedule = 6; + + // Statistics create time. + google.protobuf.Timestamp create_time = 7; + + // Algorithm used to calculated the metrics, eg: jensen_shannon_divergence, + // l_infinity. + string algorithm = 8; +} + +// A collection of data points that describes the time-varying values of a +// tabular metric. +message ModelMonitoringTabularStats { + // The stats name. + string stats_name = 1; + + // One of the supported monitoring objectives: + // `raw-feature-drift` + // `prediction-output-drift` + // `feature-attribution` + string objective_type = 2; + + // The data points of this time series. When listing time series, points are + // returned in reverse time order. + repeated ModelMonitoringStatsDataPoint data_points = 3; +} + +// Filter for searching ModelMonitoringStats. +message SearchModelMonitoringStatsFilter { + // Tabular statistics filter. + message TabularStatsFilter { + // If not specified, will return all the stats_names. + string stats_name = 1; + + // One of the supported monitoring objectives: + // `raw-feature-drift` + // `prediction-output-drift` + // `feature-attribution` + string objective_type = 2; + + // From a particular monitoring job. + string model_monitoring_job = 3; + + // From a particular monitoring schedule. + string model_monitoring_schedule = 4; + + // Specify the algorithm type used for distance calculation, eg: + // jensen_shannon_divergence, l_infinity. + string algorithm = 5; + } + + oneof filter { + // Tabular statistics filter. + TabularStatsFilter tabular_stats_filter = 1; + } +} diff --git a/google/cloud/aiplatform/v1beta1/schedule.proto b/google/cloud/aiplatform/v1beta1/schedule.proto index 266dc394db979..305aafa055dd4 100644 --- a/google/cloud/aiplatform/v1beta1/schedule.proto +++ b/google/cloud/aiplatform/v1beta1/schedule.proto @@ -18,6 +18,7 @@ package google.cloud.aiplatform.v1beta1; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; +import "google/cloud/aiplatform/v1beta1/model_monitoring_service.proto"; import "google/cloud/aiplatform/v1beta1/pipeline_service.proto"; import "google/protobuf/timestamp.proto"; @@ -86,6 +87,10 @@ message Schedule { // CreatePipelineJobRequest.parent field is required (format: // projects/{project}/locations/{location}). CreatePipelineJobRequest create_pipeline_job_request = 14; + + // Request for + // [ModelMonitoringService.CreateModelMonitoringJob][google.cloud.aiplatform.v1beta1.ModelMonitoringService.CreateModelMonitoringJob]. + CreateModelMonitoringJobRequest create_model_monitoring_job_request = 15; } // Immutable. The resource name of the Schedule.