|
| 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 | + |
| 15 | +syntax = "proto3"; |
| 16 | + |
| 17 | +package google.cloud.aiplatform.v1beta1; |
| 18 | + |
| 19 | +import "google/api/annotations.proto"; |
| 20 | +import "google/api/client.proto"; |
| 21 | +import "google/api/field_behavior.proto"; |
| 22 | +import "google/api/resource.proto"; |
| 23 | +import "google/cloud/aiplatform/v1beta1/index.proto"; |
| 24 | + |
| 25 | +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; |
| 26 | +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; |
| 27 | +option java_multiple_files = true; |
| 28 | +option java_outer_classname = "MatchServiceProto"; |
| 29 | +option java_package = "com.google.cloud.aiplatform.v1beta1"; |
| 30 | +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; |
| 31 | +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; |
| 32 | + |
| 33 | +// MatchService is a Google managed service for efficient vector similarity |
| 34 | +// search at scale. |
| 35 | +service MatchService { |
| 36 | + option (google.api.default_host) = "aiplatform.googleapis.com"; |
| 37 | + option (google.api.oauth_scopes) = |
| 38 | + "https://www.googleapis.com/auth/cloud-platform"; |
| 39 | + |
| 40 | + // Finds the nearest neighbors of each vector within the request. |
| 41 | + rpc FindNeighbors(FindNeighborsRequest) returns (FindNeighborsResponse) { |
| 42 | + option (google.api.http) = { |
| 43 | + post: "/v1beta1/{index_endpoint=projects/*/locations/*/indexEndpoints/*}:findNeighbors" |
| 44 | + body: "*" |
| 45 | + }; |
| 46 | + } |
| 47 | + |
| 48 | + // Reads the datapoints/vectors of the given IDs. |
| 49 | + // A maximum of 1000 datapoints can be retrieved in a batch. |
| 50 | + rpc ReadIndexDatapoints(ReadIndexDatapointsRequest) |
| 51 | + returns (ReadIndexDatapointsResponse) { |
| 52 | + option (google.api.http) = { |
| 53 | + post: "/v1beta1/{index_endpoint=projects/*/locations/*/indexEndpoints/*}:readIndexDatapoints" |
| 54 | + body: "*" |
| 55 | + }; |
| 56 | + } |
| 57 | +} |
| 58 | + |
| 59 | +// The request message for |
| 60 | +// [MatchService.FindNeighbors][google.cloud.aiplatform.v1beta1.MatchService.FindNeighbors]. |
| 61 | +message FindNeighborsRequest { |
| 62 | + // A query to find a number of the nearest neighbors (most similar vectors) |
| 63 | + // of a vector. |
| 64 | + message Query { |
| 65 | + // Required. The datapoint/vector whose nearest neighbors should be searched |
| 66 | + // for. |
| 67 | + IndexDatapoint datapoint = 1 [(google.api.field_behavior) = REQUIRED]; |
| 68 | + |
| 69 | + // The number of nearest neighbors to be retrieved from database for each |
| 70 | + // query. If not set, will use the default from the service configuration |
| 71 | + // (https://cloud.google.com/vertex-ai/docs/matching-engine/configuring-indexes#nearest-neighbor-search-config). |
| 72 | + int32 neighbor_count = 2; |
| 73 | + |
| 74 | + // Crowding is a constraint on a neighbor list produced by nearest neighbor |
| 75 | + // search requiring that no more than some value k' of the k neighbors |
| 76 | + // returned have the same value of crowding_attribute. |
| 77 | + // It's used for improving result diversity. |
| 78 | + // This field is the maximum number of matches with the same crowding tag. |
| 79 | + int32 per_crowding_attribute_neighbor_count = 3; |
| 80 | + |
| 81 | + // The number of neighbors to find via approximate search before |
| 82 | + // exact reordering is performed. If not set, the default value from scam |
| 83 | + // config is used; if set, this value must be > 0. |
| 84 | + int32 approximate_neighbor_count = 4; |
| 85 | + |
| 86 | + // The fraction of the number of leaves to search, set at query time allows |
| 87 | + // user to tune search performance. This value increase result in both |
| 88 | + // search accuracy and latency increase. The value should be between 0.0 |
| 89 | + // and 1.0. If not set or set to 0.0, query uses the default value specified |
| 90 | + // in |
| 91 | + // NearestNeighborSearchConfig.TreeAHConfig.fraction_leaf_nodes_to_search. |
| 92 | + double fraction_leaf_nodes_to_search_override = 5; |
| 93 | + } |
| 94 | + |
| 95 | + // Required. The name of the index endpoint. |
| 96 | + // Format: |
| 97 | + // `projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}` |
| 98 | + string index_endpoint = 1 [ |
| 99 | + (google.api.field_behavior) = REQUIRED, |
| 100 | + (google.api.resource_reference) = { |
| 101 | + type: "aiplatform.googleapis.com/IndexEndpoint" |
| 102 | + } |
| 103 | + ]; |
| 104 | + |
| 105 | + // The ID of the DeploydIndex that will serve the request. This request is |
| 106 | + // sent to a specific IndexEndpoint, as per the IndexEndpoint.network. That |
| 107 | + // IndexEndpoint also has IndexEndpoint.deployed_indexes, and each such index |
| 108 | + // has a DeployedIndex.id field. |
| 109 | + // The value of the field below must equal one of the DeployedIndex.id |
| 110 | + // fields of the IndexEndpoint that is being called for this request. |
| 111 | + string deployed_index_id = 2; |
| 112 | + |
| 113 | + // The list of queries. |
| 114 | + repeated Query queries = 3; |
| 115 | + |
| 116 | + // If set to true, the full datapoints (including all vector values and |
| 117 | + // restricts) of the nearest neighbors are returned. |
| 118 | + // Note that returning full datapoint will significantly increase the |
| 119 | + // latency and cost of the query. |
| 120 | + bool return_full_datapoint = 4; |
| 121 | +} |
| 122 | + |
| 123 | +// The response message for |
| 124 | +// [MatchService.FindNeighbors][google.cloud.aiplatform.v1beta1.MatchService.FindNeighbors]. |
| 125 | +message FindNeighborsResponse { |
| 126 | + // A neighbor of the query vector. |
| 127 | + message Neighbor { |
| 128 | + // The datapoint of the neighbor. |
| 129 | + // Note that full datapoints are returned only when "return_full_datapoint" |
| 130 | + // is set to true. Otherwise, only the "datapoint_id" and "crowding_tag" |
| 131 | + // fields are populated. |
| 132 | + IndexDatapoint datapoint = 1; |
| 133 | + |
| 134 | + // The distance between the neighbor and the query vector. |
| 135 | + double distance = 2; |
| 136 | + } |
| 137 | + |
| 138 | + // Nearest neighbors for one query. |
| 139 | + message NearestNeighbors { |
| 140 | + // The ID of the query datapoint. |
| 141 | + string id = 1; |
| 142 | + |
| 143 | + // All its neighbors. |
| 144 | + repeated Neighbor neighbors = 2; |
| 145 | + } |
| 146 | + |
| 147 | + // The nearest neighbors of the query datapoints. |
| 148 | + repeated NearestNeighbors nearest_neighbors = 1; |
| 149 | +} |
| 150 | + |
| 151 | +// The request message for |
| 152 | +// [MatchService.ReadIndexDatapoints][google.cloud.aiplatform.v1beta1.MatchService.ReadIndexDatapoints]. |
| 153 | +message ReadIndexDatapointsRequest { |
| 154 | + // Required. The name of the index endpoint. |
| 155 | + // Format: |
| 156 | + // `projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}` |
| 157 | + string index_endpoint = 1 [ |
| 158 | + (google.api.field_behavior) = REQUIRED, |
| 159 | + (google.api.resource_reference) = { |
| 160 | + type: "aiplatform.googleapis.com/IndexEndpoint" |
| 161 | + } |
| 162 | + ]; |
| 163 | + |
| 164 | + // The ID of the DeploydIndex that will serve the request. |
| 165 | + string deployed_index_id = 2; |
| 166 | + |
| 167 | + // IDs of the datapoints to be searched for. |
| 168 | + repeated string ids = 3; |
| 169 | +} |
| 170 | + |
| 171 | +// The response message for |
| 172 | +// [MatchService.ReadIndexDatapoints][google.cloud.aiplatform.v1beta1.MatchService.ReadIndexDatapoints]. |
| 173 | +message ReadIndexDatapointsResponse { |
| 174 | + // The result list of datapoints. |
| 175 | + repeated IndexDatapoint datapoints = 1; |
| 176 | +} |
![gcf-owl-bot[bot]](https://avatars.githubusercontent.com/in/99011?v=4&size=40){kind=avatar}
0 commit comments