From 04a9498c8c930df9915b3c472e2e31b4b09ba4b5 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 30 Nov 2021 08:48:50 -0800 Subject: [PATCH] Add ML infer trained model deployment API Co-authored-by: David Kyle --- output/schema/schema.json | 325 +++++++++++++++++- output/schema/validation-errors.json | 6 - output/typescript/types.ts | 34 ++ specification/ml/_types/TrainedModel.ts | 14 + .../MlInferTrainedModelDeploymentRequest.ts | 52 +++ .../MlInferTrainedModelDeploymentResponse.ts | 65 ++++ 6 files changed, 488 insertions(+), 8 deletions(-) create mode 100644 specification/ml/infer_trained_model_deployment/MlInferTrainedModelDeploymentRequest.ts create mode 100644 specification/ml/infer_trained_model_deployment/MlInferTrainedModelDeploymentResponse.ts diff --git a/output/schema/schema.json b/output/schema/schema.json index f075274876..9e6b2ca209 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -7129,9 +7129,16 @@ "description": "Evaluate a trained model.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/infer-trained-model-deployment.html", "name": "ml.infer_trained_model_deployment", - "request": null, + "request": { + "name": "Request", + "namespace": "ml.infer_trained_model_deployment" + }, "requestBodyRequired": true, - "response": null, + "response": { + "name": "Response", + "namespace": "ml.infer_trained_model_deployment" + }, + "since": "8.0.0", "stability": "experimental", "urls": [ { @@ -114479,6 +114486,32 @@ } ] }, + { + "kind": "type_alias", + "name": { + "name": "PredictedValue", + "namespace": "ml._types" + }, + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "internal" + } + }, + { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + } + ], + "kind": "union_of" + } + }, { "kind": "enum", "members": [ @@ -114603,6 +114636,48 @@ } ] }, + { + "kind": "interface", + "name": { + "name": "TopClassEntry", + "namespace": "ml._types" + }, + "properties": [ + { + "name": "class_name", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "internal" + } + } + }, + { + "name": "class_probability", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + } + }, + { + "name": "class_score", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + } + } + ] + }, { "kind": "interface", "name": { @@ -115170,6 +115245,70 @@ } ] }, + { + "kind": "interface", + "name": { + "name": "TrainedModelEntities", + "namespace": "ml._types" + }, + "properties": [ + { + "name": "class_name", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "internal" + } + } + }, + { + "name": "class_probability", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + } + }, + { + "name": "entity", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "internal" + } + } + }, + { + "name": "start_pos", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + }, + { + "name": "end_pos", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + } + ] + }, { "kind": "interface", "name": { @@ -120385,6 +120524,188 @@ "namespace": "ml.get_trained_models_stats" } }, + { + "attachedBehaviors": [ + "CommonQueryParameters" + ], + "body": { + "kind": "properties", + "properties": [ + { + "description": "An array of objects to pass to the model for inference. The objects should contain a field matching your\nconfigured trained model input. Typically, the field name is `text_field`. Currently, only a single value is allowed.", + "name": "docs", + "required": true, + "type": { + "kind": "array_of", + "value": { + "key": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "internal" + } + }, + "kind": "dictionary_of", + "singleKey": false, + "value": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "internal" + } + } + } + } + } + ] + }, + "description": "Evaluates a trained model.", + "inherits": { + "type": { + "name": "RequestBase", + "namespace": "_types" + } + }, + "kind": "request", + "name": { + "name": "Request", + "namespace": "ml.infer_trained_model_deployment" + }, + "path": [ + { + "description": "The unique identifier of the trained model.", + "name": "model_id", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "Id", + "namespace": "_types" + } + } + } + ], + "query": [ + { + "description": "Controls the amount of time to wait for inference results.", + "name": "timeout", + "required": false, + "serverDefault": "10s", + "type": { + "kind": "instance_of", + "type": { + "name": "Time", + "namespace": "_types" + } + } + } + ] + }, + { + "body": { + "kind": "properties", + "properties": [ + { + "description": "If the model is trained for named entity recognition (NER) tasks, the response contains the recognized entities.", + "name": "entities", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TrainedModelEntities", + "namespace": "ml._types" + } + } + } + }, + { + "description": "Indicates whether the input text was truncated to meet the model's maximum sequence length limit. This property\nis present only when it is true.", + "name": "is_truncated", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "internal" + } + } + }, + { + "description": "If the model is trained for a text classification or zero shot classification task, the response is the\npredicted class.\nFor named entity recognition (NER) tasks, it contains the annotated text output.\nFor fill mask tasks, it contains the top prediction for replacing the mask token.\nFor text embedding tasks, it contains the raw numerical text embedding values.", + "name": "predicted_value", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "PredictedValue", + "namespace": "ml._types" + } + } + } + }, + { + "description": "For fill mask tasks, the response contains the input text sequence with the mask token replaced by the predicted\nvalue.", + "name": "predicted_value_sequence", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "internal" + } + } + }, + { + "description": "Specifies a confidence score for the predicted value.", + "name": "prediction_probability", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + } + }, + { + "description": "For fill mask, text classification, and zero shot classification tasks, the response contains a list of top\nclass entries.", + "name": "top_classes", + "required": true, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TopClassEntry", + "namespace": "ml._types" + } + } + } + }, + { + "description": "If the request failed, the response contains the reason for the failure.", + "name": "warning", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "internal" + } + } + } + ] + }, + "kind": "response", + "name": { + "name": "Response", + "namespace": "ml.infer_trained_model_deployment" + } + }, { "kind": "interface", "name": { diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index 2a6e4529f8..dc32018b8e 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -1302,12 +1302,6 @@ ], "response": [] }, - "ml.infer_trained_model_deployment": { - "request": [ - "Missing request & response" - ], - "response": [] - }, "ml.info": { "request": [ "Request: should not have a body" diff --git a/output/typescript/types.ts b/output/typescript/types.ts index e4f407b0bb..5c4b04cde0 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -11621,6 +11621,8 @@ export interface MlPerPartitionCategorization { stop_on_warn?: boolean } +export type MlPredictedValue = string | double + export type MlRoutingState = 'failed' | 'started' | 'starting' | 'stopped' | 'stopping' export type MlRuleAction = 'skip_result' | 'skip_model_update' @@ -11636,6 +11638,12 @@ export interface MlTimingStats { iteration_time?: integer } +export interface MlTopClassEntry { + class_name: string + class_probability: double + class_score: double +} + export interface MlTotalFeatureImportance { feature_name: Name importance: MlTotalFeatureImportanceStatistics[] @@ -11699,6 +11707,14 @@ export interface MlTrainedModelConfigMetadata { total_feature_importance?: MlTotalFeatureImportance[] } +export interface MlTrainedModelEntities { + class_name: string + class_probability: double + entity: string + start_pos: integer + end_pos: integer +} + export interface MlTrainedModelInferenceStats { failure_count: long inference_count: long @@ -12284,6 +12300,24 @@ export interface MlGetTrainedModelsStatsResponse { trained_model_stats: MlTrainedModelStats[] } +export interface MlInferTrainedModelDeploymentRequest extends RequestBase { + model_id: Id + timeout?: Time + body?: { + docs: Record[] + } +} + +export interface MlInferTrainedModelDeploymentResponse { + entities?: MlTrainedModelEntities[] + is_truncated?: boolean + predicted_value?: MlPredictedValue[] + predicted_value_sequence?: string + prediction_probability?: double + top_classes: MlTopClassEntry[] + warning?: string +} + export interface MlInfoAnomalyDetectors { categorization_analyzer: MlCategorizationAnalyzer categorization_examples_limit: integer diff --git a/specification/ml/_types/TrainedModel.ts b/specification/ml/_types/TrainedModel.ts index 5e72689f3a..2c59c11a7f 100644 --- a/specification/ml/_types/TrainedModel.ts +++ b/specification/ml/_types/TrainedModel.ts @@ -235,3 +235,17 @@ export class TrainedModelAllocation { start_time: DateString task_parameters: TrainedModelAllocationTaskParameters } +export class TrainedModelEntities { + class_name: string + class_probability: double + entity: string + start_pos: integer + end_pos: integer +} +export class TopClassEntry { + class_name: string + class_probability: double + class_score: double +} + +export type PredictedValue = string | double diff --git a/specification/ml/infer_trained_model_deployment/MlInferTrainedModelDeploymentRequest.ts b/specification/ml/infer_trained_model_deployment/MlInferTrainedModelDeploymentRequest.ts new file mode 100644 index 0000000000..60a7b9a47e --- /dev/null +++ b/specification/ml/infer_trained_model_deployment/MlInferTrainedModelDeploymentRequest.ts @@ -0,0 +1,52 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you 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. + */ + +import { RequestBase } from '@_types/Base' +import { Id } from '@_types/common' +import { Time } from '@_types/Time' +import { Dictionary } from '@spec_utils/Dictionary' + +/** + * Evaluates a trained model. + * @rest_spec_name ml.infer_trained_model_deployment + * @since 8.0.0 + * @stability experimental + */ +export interface Request extends RequestBase { + path_parts: { + /** + * The unique identifier of the trained model. + */ + model_id: Id + } + query_parameters: { + /** + * Controls the amount of time to wait for inference results. + * @server_default 10s + */ + timeout?: Time + } + body: { + /** + * An array of objects to pass to the model for inference. The objects should contain a field matching your + * configured trained model input. Typically, the field name is `text_field`. Currently, only a single value is allowed. + */ + docs: Dictionary[] + } +} diff --git a/specification/ml/infer_trained_model_deployment/MlInferTrainedModelDeploymentResponse.ts b/specification/ml/infer_trained_model_deployment/MlInferTrainedModelDeploymentResponse.ts new file mode 100644 index 0000000000..88c4543fe8 --- /dev/null +++ b/specification/ml/infer_trained_model_deployment/MlInferTrainedModelDeploymentResponse.ts @@ -0,0 +1,65 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you 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. + */ + +import { double } from '@_types/Numeric' +import { + PredictedValue, + TopClassEntry, + TrainedModelEntities +} from '@ml/_types/TrainedModel' + +export class Response { + body: { + /** + * If the model is trained for named entity recognition (NER) tasks, the response contains the recognized entities. + */ + entities?: TrainedModelEntities[] + /** + * Indicates whether the input text was truncated to meet the model's maximum sequence length limit. This property + * is present only when it is true. + */ + is_truncated?: boolean + /** + * If the model is trained for a text classification or zero shot classification task, the response is the + * predicted class. + * For named entity recognition (NER) tasks, it contains the annotated text output. + * For fill mask tasks, it contains the top prediction for replacing the mask token. + * For text embedding tasks, it contains the raw numerical text embedding values. + */ + predicted_value?: PredictedValue[] + /** + * For fill mask tasks, the response contains the input text sequence with the mask token replaced by the predicted + * value. + */ + predicted_value_sequence?: string + /** + * Specifies a confidence score for the predicted value. + */ + prediction_probability?: double + /** + * For fill mask, text classification, and zero shot classification tasks, the response contains a list of top + * class entries. + */ + top_classes: TopClassEntry[] + /** + * If the request failed, the response contains the reason for the failure. + */ + warning?: string + } +}