--- type: api title: Evaluate a trained model description: **All methods and paths for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-ml-infer-trained-model resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-ml-infer-trained-model products: - Elasticsearch --- # Evaluate a trained model Availability: 8.3+ ## Paths - `POST` `/_ml/trained_models/{model_id}/deployment/_infer` - `POST` `/_ml/trained_models/{model_id}/_infer` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth) #### Path Parameters - `model_id` (string Id) The unique identifier of the trained model. ## Query String Parameters - `timeout` (string Duration · default: 10s) Controls the amount of time to wait for inference results. ## Request Body `application/json` - `docs` ([] string to object) — required An array of objects to pass to the model for inference. The objects should contain a fields matching your configured trained model input. Typically, for NLP models, the field name is `text_field`. Currently, for NLP models, only a single value is allowed. - `inference_config` ({} InferenceConfigUpdateContainer) — optional The inference configuration updates to apply on the API call - `regression` ({} RegressionInferenceOptions) — optional Regression configuration for inference. - `results_field` (string Field) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `num_top_feature_importance_values` (number · default: 0) — optional Specifies the maximum number of feature importance values per document. - `classification` ({} ClassificationInferenceOptions) — optional Classification configuration for inference. - `num_top_classes` (number) — optional Specifies the number of top class predictions to return. Defaults to 0. - `num_top_feature_importance_values` (number · default: 0) — optional Specifies the maximum number of feature importance values per document. - `prediction_field_type` (string) — optional Specifies the type of the predicted field to write. Acceptable values are: string, number, boolean. When boolean is provided 1.0 is transformed to true and 0.0 to false. - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `top_classes_results_field` (string) — optional Specifies the field to which the top classes are written. Defaults to top_classes. - `text_classification` ({} TextClassificationInferenceUpdateOptions) — optional Text classification configuration for inference. - `num_top_classes` (number) — optional Specifies the number of top class predictions to return. Defaults to 0. - `tokenization` ({} NlpTokenizationUpdateOptions) — optional The tokenization options to update when inferring - `truncate` (enum TokenizationTruncate) — optional Truncate options to apply Values: `first`, `second`, `none` - `span` (number) — optional Span options to apply - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `classification_labels` ([] string) — optional Classification labels to apply other than the stored labels. Must have the same deminsions as the default configured labels - `zero_shot_classification` ({} ZeroShotClassificationInferenceUpdateOptions) — optional Zeroshot classification configuration for inference. - `tokenization` ({} NlpTokenizationUpdateOptions) — optional The tokenization options to update when inferring - `truncate` (enum TokenizationTruncate) — optional Truncate options to apply Values: `first`, `second`, `none` - `span` (number) — optional Span options to apply - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `multi_label` (boolean) — optional Update the configured multi label option. Indicates if more than one true label exists. Defaults to the configured value. - `labels` ([] string) — required The labels to predict. - `fill_mask` ({} FillMaskInferenceUpdateOptions) — optional Fill mask configuration for inference. - `num_top_classes` (number) — optional Specifies the number of top class predictions to return. Defaults to 0. - `tokenization` ({} NlpTokenizationUpdateOptions) — optional The tokenization options to update when inferring - `truncate` (enum TokenizationTruncate) — optional Truncate options to apply Values: `first`, `second`, `none` - `span` (number) — optional Span options to apply - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `ner` ({} NerInferenceUpdateOptions) — optional Named entity recognition configuration for inference. - `tokenization` ({} NlpTokenizationUpdateOptions) — optional The tokenization options to update when inferring - `truncate` (enum TokenizationTruncate) — optional Truncate options to apply Values: `first`, `second`, `none` - `span` (number) — optional Span options to apply - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `pass_through` ({} PassThroughInferenceUpdateOptions) — optional Pass through configuration for inference. - `tokenization` ({} NlpTokenizationUpdateOptions) — optional The tokenization options to update when inferring - `truncate` (enum TokenizationTruncate) — optional Truncate options to apply Values: `first`, `second`, `none` - `span` (number) — optional Span options to apply - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `text_embedding` ({} TextEmbeddingInferenceUpdateOptions) — optional Text embedding configuration for inference. - `tokenization` ({} NlpTokenizationUpdateOptions) — optional - `truncate` (enum TokenizationTruncate) — optional Truncate options to apply Values: `first`, `second`, `none` - `span` (number) — optional Span options to apply - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `text_expansion` ({} TextExpansionInferenceUpdateOptions) — optional Text expansion configuration for inference. - `tokenization` ({} NlpTokenizationUpdateOptions) — optional - `truncate` (enum TokenizationTruncate) — optional Truncate options to apply Values: `first`, `second`, `none` - `span` (number) — optional Span options to apply - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `question_answering` ({} QuestionAnsweringInferenceUpdateOptions) — optional Question answering configuration for inference - `question` (string) — required The question to answer given the inference context - `num_top_classes` (number) — optional Specifies the number of top class predictions to return. Defaults to 0. - `tokenization` ({} NlpTokenizationUpdateOptions) — optional The tokenization options to update when inferring - `truncate` (enum TokenizationTruncate) — optional Truncate options to apply Values: `first`, `second`, `none` - `span` (number) — optional Span options to apply - `results_field` (string) — optional The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. - `max_answer_length` (number) — optional The maximum answer length to consider for extraction ## Response `application/json` - `inference_results` ([] InferenceResponseResult) - `entities` ([] TrainedModelEntities) If the model is trained for named entity recognition (NER) tasks, the response contains the recognized entities. - `class_name` (string) - `class_probability` (number) - `entity` (string) - `start_pos` (number) - `end_pos` (number) - `is_truncated` (boolean) 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. - `predicted_value` (union oneOf) — nullable 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. For regression models, its a numerical value For classification models, it may be an integer, double, boolean or string depending on prediction type One of: `PredictedValue[]` or `PredictedValue` - `predicted_value_sequence` (string) For fill mask tasks, the response contains the input text sequence with the mask token replaced by the predicted value. Additionally - `prediction_probability` (number) Specifies a probability for the predicted value. - `prediction_score` (number) Specifies a confidence score for the predicted value. - `top_classes` ([] TopClassEntry) For fill mask, text classification, and zero shot classification tasks, the response contains a list of top class entries. - `class_name` (string) - `class_probability` (number) - `class_score` (number) - `warning` (string) If the request failed, the response contains the reason for the failure. - `feature_importance` ([] TrainedModelInferenceFeatureImportance) The feature importance for the inference results. Relevant only for classification or regression models - `feature_name` (string) - `importance` (number) - `classes` ([] TrainedModelInferenceClassImportance) - `class_name` (string) - `importance` (number) ## Code Examples #### Console ```console POST _ml/trained_models/lang_ident_model_1/_infer { "docs":[{"text": "The fool doth think he is wise, but the wise man knows himself to be a fool."}] } ``` #### JavaScript ```javascript const response = await client.ml.inferTrainedModel({ model_id: "lang_ident_model_1", docs: [ { text: "The fool doth think he is wise, but the wise man knows himself to be a fool.", }, ], }); ``` #### Python ```python resp = client.ml.infer_trained_model( model_id="lang_ident_model_1", docs=[ { "text": "The fool doth think he is wise, but the wise man knows himself to be a fool." } ], ) ``` #### curl ```curl curl -X POST "$ELASTICSEARCH_URL/_ml/trained_models/lang_ident_model_1/_infer" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "docs": [ { "text": "The fool doth think he is wise, but the wise man knows himself to be a fool." } ] }' ``` #### Java ```java client.ml().inferTrainedModel(i -> i .docs(Map.of("text", JsonData.fromJson("\"The fool doth think he is wise, but the wise man knows himself to be a fool.\""))) .modelId("lang_ident_model_1") ); ``` #### C# ```c# var response = await client.MachineLearning .InferTrainedModelAsync(modelId: "lang_ident_model_1", d1 => d1 .Docs([new Dictionary() { { "text", "The fool doth think he is wise, but the wise man knows himself to be a fool." } }]) ); ``` #### PHP ```php $resp = $client->ml()->inferTrainedModel([ "model_id" => "lang_ident_model_1", "body" => [ "docs" => array( [ "text" => "The fool doth think he is wise, but the wise man knows himself to be a fool.", ], ), ], ]); ``` #### Ruby ```ruby response = client.ml.infer_trained_model( model_id: "lang_ident_model_1", body: { "docs": [ { "text": "The fool doth think he is wise, but the wise man knows himself to be a fool." } ] } ) ```