From 5fdf151ee0d0a630c07a75dc8f19906e7ad1aa8a Mon Sep 17 00:00:00 2001 From: yan283 <104038473+yan283@users.noreply.github.com> Date: Wed, 11 May 2022 14:26:37 -0700 Subject: [PATCH] fix: check in service proto file (#1174) Co-authored-by: Ivan Cheung --- .../_protos/match_service.proto | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 google/cloud/aiplatform/matching_engine/_protos/match_service.proto diff --git a/google/cloud/aiplatform/matching_engine/_protos/match_service.proto b/google/cloud/aiplatform/matching_engine/_protos/match_service.proto new file mode 100644 index 0000000000..158b0f146a --- /dev/null +++ b/google/cloud/aiplatform/matching_engine/_protos/match_service.proto @@ -0,0 +1,136 @@ +syntax = "proto3"; + +package google.cloud.aiplatform.container.v1beta1; + +import "google/rpc/status.proto"; + +// MatchService is a Google managed service for efficient vector similarity +// search at scale. +service MatchService { + // Returns the nearest neighbors for the query. If it is a sharded + // deployment, calls the other shards and aggregates the responses. + rpc Match(MatchRequest) returns (MatchResponse) {} + + // Returns the nearest neighbors for batch queries. If it is a sharded + // deployment, calls the other shards and aggregates the responses. + rpc BatchMatch(BatchMatchRequest) returns (BatchMatchResponse) {} +} + +// Parameters for a match query. +message MatchRequest { + // The ID of the DeploydIndex that will serve the request. + // This MatchRequest is sent to a specific IndexEndpoint of the Control API, + // as per the IndexEndpoint.network. That IndexEndpoint also has + // IndexEndpoint.deployed_indexes, and each such index has an + // DeployedIndex.id field. + // The value of the field below must equal one of the DeployedIndex.id + // fields of the IndexEndpoint that is being called for this request. + string deployed_index_id = 1; + + // The embedding values. + repeated float float_val = 2; + + // The number of nearest neighbors to be retrieved from database for + // each query. If not set, will use the default from + // the service configuration. + int32 num_neighbors = 3; + + // The list of restricts. + repeated Namespace restricts = 4; + + // Crowding is a constraint on a neighbor list produced by nearest neighbor + // search requiring that no more than some value k' of the k neighbors + // returned have the same value of crowding_attribute. + // It's used for improving result diversity. + // This field is the maximum number of matches with the same crowding tag. + int32 per_crowding_attribute_num_neighbors = 5; + + // The number of neighbors to find via approximate search before + // exact reordering is performed. If not set, the default value from scam + // config is used; if set, this value must be > 0. + int32 approx_num_neighbors = 6; + + // The fraction of the number of leaves to search, set at query time allows + // user to tune search performance. This value increase result in both search + // accuracy and latency increase. The value should be between 0.0 and 1.0. If + // not set or set to 0.0, query uses the default value specified in + // NearestNeighborSearchConfig.TreeAHConfig.leaf_nodes_to_search_percent. + int32 leaf_nodes_to_search_percent_override = 7; +} + +// Response of a match query. +message MatchResponse { + message Neighbor { + // The ids of the matches. + string id = 1; + + // The distances of the matches. + double distance = 2; + } + // All its neighbors. + repeated Neighbor neighbor = 1; +} + +// Parameters for a batch match query. +message BatchMatchRequest { + // Batched requests against one index. + message BatchMatchRequestPerIndex { + // The ID of the DeploydIndex that will serve the request. + string deployed_index_id = 1; + + // The requests against the index identified by the above deployed_index_id. + repeated MatchRequest requests = 2; + + // Selects the optimal batch size to use for low-level batching. Queries + // within each low level batch are executed sequentially while low level + // batches are executed in parallel. + // This field is optional, defaults to 0 if not set. A non-positive number + // disables low level batching, i.e. all queries are executed sequentially. + int32 low_level_batch_size = 3; + } + + // The batch requests grouped by indexes. + repeated BatchMatchRequestPerIndex requests = 1; +} + +// Response of a batch match query. +message BatchMatchResponse { + // Batched responses for one index. + message BatchMatchResponsePerIndex { + // The ID of the DeployedIndex that produced the responses. + string deployed_index_id = 1; + + // The match responses produced by the index identified by the above + // deployed_index_id. This field is set only when the query against that + // index succeed. + repeated MatchResponse responses = 2; + + // The status of response for the batch query identified by the above + // deployed_index_id. + google.rpc.Status status = 3; + } + + // The batched responses grouped by indexes. + repeated BatchMatchResponsePerIndex responses = 1; +} + +// Namespace specifies the rules for determining the datapoints that are +// eligible for each matching query, overall query is an AND across namespaces. +message Namespace { + // The string name of the namespace that this proto is specifying, + // such as "color", "shape", "geo", or "tags". + string name = 1; + + // The allowed tokens in the namespace. + repeated string allow_tokens = 2; + + // The denied tokens in the namespace. + // The denied tokens have exactly the same format as the token fields, but + // represents a negation. When a token is denied, then matches will be + // excluded whenever the other datapoint has that token. + // + // For example, if a query specifies {color: red, blue, !purple}, then that + // query will match datapoints that are red or blue, but if those points are + // also purple, then they will be excluded even if they are red/blue. + repeated string deny_tokens = 3; +}