googleapis/google/cloud/aiplatform/v1beta1/endpoint.proto

// Copyright 2021 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/encryption_spec.proto";
import "google/cloud/aiplatform/v1beta1/explanation.proto";
import "google/cloud/aiplatform/v1beta1/machine_resources.proto";
import "google/cloud/aiplatform/v1beta1/model_deployment_monitoring_job.proto";
import "google/protobuf/timestamp.proto";
import "google/api/annotations.proto";

option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1";
option go_package = "google.golang.org/genproto/googleapis/cloud/aiplatform/v1beta1;aiplatform";
option java_multiple_files = true;
option java_outer_classname = "EndpointProto";
option java_package = "com.google.cloud.aiplatform.v1beta1";
option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1";
option ruby_package = "Google::Cloud::AIPlatform::V1beta1";

// Models are deployed into it, and afterwards Endpoint is called to obtain
// predictions and explanations.
message Endpoint {
  option (google.api.resource) = {
    type: "aiplatform.googleapis.com/Endpoint"
    pattern: "projects/{project}/locations/{location}/endpoints/{endpoint}"
  };

  // Output only. The resource name of the Endpoint.
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The display name of the Endpoint.
  // The name can be up to 128 characters long and can be consist of any UTF-8
  // characters.
  string display_name = 2 [(google.api.field_behavior) = REQUIRED];

  // The description of the Endpoint.
  string description = 3;

  // Output only. The models deployed in this Endpoint.
  // To add or remove DeployedModels use [EndpointService.DeployModel][google.cloud.aiplatform.v1beta1.EndpointService.DeployModel] and
  // [EndpointService.UndeployModel][google.cloud.aiplatform.v1beta1.EndpointService.UndeployModel] respectively.
  repeated DeployedModel deployed_models = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // A map from a DeployedModel's ID to the percentage of this Endpoint's
  // traffic that should be forwarded to that DeployedModel.
  //
  // If a DeployedModel's ID is not listed in this map, then it receives no
  // traffic.
  //
  // The traffic percentage values must add up to 100, or map must be empty if
  // the Endpoint is to not accept any traffic at a moment.
  map<string, int32> traffic_split = 5;

  // Used to perform consistent read-modify-write updates. If not set, a blind
  // "overwrite" update happens.
  string etag = 6;

  // The labels with user-defined metadata to organize your Endpoints.
  //
  // Label keys and values can be no longer than 64 characters
  // (Unicode codepoints), can only contain lowercase letters, numeric
  // characters, underscores and dashes. International characters are allowed.
  //
  // See https://goo.gl/xmQnxf for more information and examples of labels.
  map<string, string> labels = 7;

  // Output only. Timestamp when this Endpoint was created.
  google.protobuf.Timestamp create_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Timestamp when this Endpoint was last updated.
  google.protobuf.Timestamp update_time = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Customer-managed encryption key spec for an Endpoint. If set, this
  // Endpoint and all sub-resources of this Endpoint will be secured by
  // this key.
  EncryptionSpec encryption_spec = 10;

  // The full name of the Google Compute Engine
  // [network](/compute/docs/networks-and-firewalls#networks) to which the
  // Endpoint should be peered.
  //
  // Private services access must already be configured for the network. If left
  // unspecified, the Endpoint is not peered with any network.
  //
  // [Format](https://cloud.google.com/compute/docs/reference/rest/v1/networks/insert):
  // projects/{project}/global/networks/{network}.
  // Where {project} is a project number, as in '12345', and {network} is
  // network name.
  string network = 13 [(google.api.resource_reference) = {
                         type: "compute.googleapis.com/Network"
                       }];
}

// A deployment of a Model. Endpoints contain one or more DeployedModels.
message DeployedModel {
  // The prediction (for example, the machine) resources that the DeployedModel
  // uses. The user is billed for the resources (at least their minimal amount)
  // even if the DeployedModel receives no traffic.
  // Not all Models support all resources types. See
  // [Model.supported_deployment_resources_types][google.cloud.aiplatform.v1beta1.Model.supported_deployment_resources_types].
  oneof prediction_resources {
    // A description of resources that are dedicated to the DeployedModel, and
    // that need a higher degree of manual configuration.
    DedicatedResources dedicated_resources = 7;

    // A description of resources that to large degree are decided by AI
    // Platform, and require only a modest additional configuration.
    AutomaticResources automatic_resources = 8;
  }

  // Output only. The ID of the DeployedModel.
  string id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The name of the Model that this is the deployment of. Note that the Model
  // may be in a different location than the DeployedModel's Endpoint.
  string model = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/Model"
    }
  ];

  // The display name of the DeployedModel. If not provided upon creation,
  // the Model's display_name is used.
  string display_name = 3;

  // Output only. Timestamp when the DeployedModel was created.
  google.protobuf.Timestamp create_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Explanation configuration for this DeployedModel.
  //
  // When deploying a Model using [EndpointService.DeployModel][google.cloud.aiplatform.v1beta1.EndpointService.DeployModel], this value
  // overrides the value of [Model.explanation_spec][google.cloud.aiplatform.v1beta1.Model.explanation_spec]. All fields of
  // [explanation_spec][google.cloud.aiplatform.v1beta1.DeployedModel.explanation_spec] are optional in the request. If a field of
  // [explanation_spec][google.cloud.aiplatform.v1beta1.DeployedModel.explanation_spec] is not populated, the value of the same field of
  // [Model.explanation_spec][google.cloud.aiplatform.v1beta1.Model.explanation_spec] is inherited. If the corresponding
  // [Model.explanation_spec][google.cloud.aiplatform.v1beta1.Model.explanation_spec] is not populated, all fields of the
  // [explanation_spec][google.cloud.aiplatform.v1beta1.DeployedModel.explanation_spec] will be used for the explanation configuration.
  ExplanationSpec explanation_spec = 9;

  // The service account that the DeployedModel's container runs as. Specify the
  // email address of the service account. If this service account is not
  // specified, the container runs as a service account that doesn't have access
  // to the resource project.
  //
  // Users deploying the Model must have the `iam.serviceAccounts.actAs`
  // permission on this service account.
  string service_account = 11;

  // If true, the container of the DeployedModel instances will send `stderr`
  // and `stdout` streams to Stackdriver Logging.
  //
  // Only supported for custom-trained Models and AutoML Tabular Models.
  bool enable_container_logging = 12;

  // These logs are like standard server access logs, containing
  // information like timestamp and latency for each prediction request.
  //
  // Note that Stackdriver logs may incur a cost, especially if your project
  // receives prediction requests at a high queries per second rate (QPS).
  // Estimate your costs before enabling this option.
  bool enable_access_logging = 13;

  // Output only. Provide paths for users to send predict/explain/health requests directly to
  // the deployed model services running on Cloud via private services access.
  // This field is populated if [network][google.cloud.aiplatform.v1beta1.Endpoint.network] is configured.
  PrivateEndpoints private_endpoints = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// PrivateEndpoints is used to provide paths for users to send
// requests via private services access.
message PrivateEndpoints {
  // Output only. Http(s) path to send prediction requests.
  string predict_http_uri = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Http(s) path to send explain requests.
  string explain_http_uri = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Http(s) path to send health check requests.
  string health_http_uri = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}