1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.aiplatform.v1beta1; 18 19import "google/api/field_behavior.proto"; 20import "google/api/resource.proto"; 21import "google/cloud/aiplatform/v1beta1/explanation.proto"; 22import "google/cloud/aiplatform/v1beta1/model_monitoring_spec.proto"; 23import "google/protobuf/timestamp.proto"; 24 25option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; 26option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; 27option java_multiple_files = true; 28option java_outer_classname = "ModelMonitorProto"; 29option java_package = "com.google.cloud.aiplatform.v1beta1"; 30option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; 31option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; 32 33// Vertex AI Model Monitoring Service serves as a central hub for the analysis 34// and visualization of data quality and performance related to models. 35// ModelMonitor stands as a top level resource for overseeing your model 36// monitoring tasks. 37message ModelMonitor { 38 option (google.api.resource) = { 39 type: "aiplatform.googleapis.com/ModelMonitor" 40 pattern: "projects/{project}/locations/{location}/modelMonitors/{model_monitor}" 41 }; 42 43 // The monitoring target refers to the entity that is subject to analysis. 44 // e.g. Vertex AI Model version. 45 message ModelMonitoringTarget { 46 // Model in Vertex AI Model Registry. 47 message VertexModelSource { 48 // Model resource name. Format: 49 // projects/{project}/locations/{location}/models/{model}. 50 string model = 1 [(google.api.resource_reference) = { 51 type: "aiplatform.googleapis.com/Model" 52 }]; 53 54 // Model version id. 55 string model_version_id = 2; 56 } 57 58 oneof source { 59 // Model in Vertex AI Model Registry. 60 VertexModelSource vertex_model = 1; 61 } 62 } 63 64 // Optional default monitoring objective, it can be overridden in the 65 // ModelMonitoringJob objective spec. 66 oneof default_objective { 67 // Optional default tabular model monitoring objective. 68 ModelMonitoringObjectiveSpec.TabularObjective tabular_objective = 11; 69 } 70 71 // Immutable. Resource name of the ModelMonitor. Format: 72 // `projects/{project}/locations/{location}/modelMonitors/{model_monitor}`. 73 string name = 1 [(google.api.field_behavior) = IMMUTABLE]; 74 75 // The display name of the ModelMonitor. 76 // The name can be up to 128 characters long and can consist of any UTF-8. 77 string display_name = 2; 78 79 // The entity that is subject to analysis. 80 // Currently only models in Vertex AI Model Registry are supported. If you 81 // want to analyze the model which is outside the Vertex AI, you could 82 // register a model in Vertex AI Model Registry using just a display name. 83 ModelMonitoringTarget model_monitoring_target = 3; 84 85 // Optional training dataset used to train the model. 86 // It can serve as a reference dataset to identify changes in production. 87 ModelMonitoringInput training_dataset = 10; 88 89 // Optional default notification spec, it can be overridden in the 90 // ModelMonitoringJob notification spec. 91 ModelMonitoringNotificationSpec notification_spec = 12; 92 93 // Optional default monitoring metrics/logs export spec, it can be overridden 94 // in the ModelMonitoringJob output spec. 95 // If not specified, a default Google Cloud Storage bucket will be created 96 // under your project. 97 ModelMonitoringOutputSpec output_spec = 13; 98 99 // Optional model explanation spec. It is used for feature attribution 100 // monitoring. 101 ExplanationSpec explanation_spec = 16; 102 103 // Monitoring Schema is to specify the model's features, prediction outputs 104 // and ground truth properties. It is used to extract pertinent data from the 105 // dataset and to process features based on their properties. 106 // Make sure that the schema aligns with your dataset, if it does not, we will 107 // be unable to extract data from the dataset. 108 // It is required for most models, but optional for Vertex AI AutoML Tables 109 // unless the schem information is not available. 110 ModelMonitoringSchema model_monitoring_schema = 9; 111 112 // Output only. Timestamp when this ModelMonitor was created. 113 google.protobuf.Timestamp create_time = 6 114 [(google.api.field_behavior) = OUTPUT_ONLY]; 115 116 // Output only. Timestamp when this ModelMonitor was updated most recently. 117 google.protobuf.Timestamp update_time = 7 118 [(google.api.field_behavior) = OUTPUT_ONLY]; 119} 120 121// The Model Monitoring Schema definition. 122message ModelMonitoringSchema { 123 // Schema field definition. 124 message FieldSchema { 125 // Field name. 126 string name = 1; 127 128 // Supported data types are: 129 // `float` 130 // `integer` 131 // `boolean` 132 // `string` 133 // `categorical` 134 string data_type = 2; 135 136 // Describes if the schema field is an array of given data type. 137 bool repeated = 3; 138 } 139 140 // Feature names of the model. Vertex AI will try to match the features from 141 // your dataset as follows: 142 // * For 'csv' files, the header names are required, and we will extract the 143 // corresponding feature values when the header names align with the 144 // feature names. 145 // * For 'jsonl' files, we will extract the corresponding feature values if 146 // the key names match the feature names. 147 // Note: Nested features are not supported, so please ensure your features 148 // are flattened. Ensure the feature values are scalar or an array of 149 // scalars. 150 // * For 'bigquery' dataset, we will extract the corresponding feature values 151 // if the column names match the feature names. 152 // Note: The column type can be a scalar or an array of scalars. STRUCT or 153 // JSON types are not supported. You may use SQL queries to select or 154 // aggregate the relevant features from your original table. However, 155 // ensure that the 'schema' of the query results meets our requirements. 156 // * For the Vertex AI Endpoint Request Response Logging table or Vertex AI 157 // Batch Prediction Job results. If the 158 // [instance_type][google.cloud.aiplatform.v1beta1.ModelMonitoringSchema.instance_type] 159 // is an array, ensure that the sequence in 160 // [feature_fields][google.cloud.aiplatform.v1beta1.ModelMonitoringSchema.feature_fields] 161 // matches the order of features in the prediction instance. We will match 162 // the feature with the array in the order specified in [feature_fields]. 163 repeated FieldSchema feature_fields = 1; 164 165 // Prediction output names of the model. The requirements are the same as the 166 // [feature_fields][google.cloud.aiplatform.v1beta1.ModelMonitoringSchema.feature_fields]. 167 // For AutoML Tables, the prediction output name presented in schema will be: 168 // `predicted_{target_column}`, the `target_column` is the one you specified 169 // when you train the model. 170 // For Prediction output drift analysis: 171 // * AutoML Classification, the distribution of the argmax label will be 172 // analyzed. 173 // * AutoML Regression, the distribution of the value will be analyzed. 174 repeated FieldSchema prediction_fields = 2; 175 176 // Target /ground truth names of the model. 177 repeated FieldSchema ground_truth_fields = 3; 178} 179