Evaluate a trained model | Elasticsearch API documentation (8x-unreleased)

Evaluate a trained model Generally available; Added in 8.3.0

POST /_ml/trained_models/{model_id}/_infer

Path parameters

model_id string Required

The unique identifier of the trained model.

Query parameters

timeout string

Controls the amount of time to wait for inference results.

Values are -1 or 0.

application/json

Body Required

docs array[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.
Hide docs attribute Show docs attribute object
- * object Additional properties
inference_config object
Hide inference_config attributes Show inference_config attributes object
- regression object
  Hide regression attributes Show regression attributes object
  
  results_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  num_top_feature_importance_values number
  
  Specifies the maximum number of feature importance values per document.
- classification object
  Hide classification attributes Show classification attributes object
  
  num_top_classes number
  
  Specifies the number of top class predictions to return. Defaults to 0.
  
  num_top_feature_importance_values number
  
  Specifies the maximum number of feature importance values per document.
  
  prediction_field_type string
  
  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
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  top_classes_results_field string
  
  Specifies the field to which the top classes are written. Defaults to top_classes.
- text_classification object
  Hide text_classification attributes Show text_classification attributes object
  
  num_top_classes number
  
  Specifies the number of top class predictions to return. Defaults to 0.
  
  tokenization object
  
  Hide tokenization attributes Show tokenization attributes object
  
  truncate string
  
  Values are first, second, or none.
  
  span number
  
  Span options to apply
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  classification_labels array[string]
  
  Classification labels to apply other than the stored labels. Must have the same deminsions as the default configured labels
- zero_shot_classification object
  Hide zero_shot_classification attributes Show zero_shot_classification attributes object
  
  tokenization object
  
  Hide tokenization attributes Show tokenization attributes object
  
  truncate string
  
  Values are first, second, or none.
  
  span number
  
  Span options to apply
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  multi_label boolean
  
  Update the configured multi label option. Indicates if more than one true label exists. Defaults to the configured value.
  
  labels array[string] Required
  
  The labels to predict.
- fill_mask object
  Hide fill_mask attributes Show fill_mask attributes object
  
  num_top_classes number
  
  Specifies the number of top class predictions to return. Defaults to 0.
  
  tokenization object
  
  Hide tokenization attributes Show tokenization attributes object
  
  truncate string
  
  Values are first, second, or none.
  
  span number
  
  Span options to apply
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
- ner object
  Hide ner attributes Show ner attributes object
  
  tokenization object
  
  Hide tokenization attributes Show tokenization attributes object
  
  truncate string
  
  Values are first, second, or none.
  
  span number
  
  Span options to apply
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
- pass_through object
  Hide pass_through attributes Show pass_through attributes object
  
  tokenization object
  
  Hide tokenization attributes Show tokenization attributes object
  
  truncate string
  
  Values are first, second, or none.
  
  span number
  
  Span options to apply
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
- text_embedding object
  Hide text_embedding attributes Show text_embedding attributes object
  
  tokenization object
  
  Hide tokenization attributes Show tokenization attributes object
  
  truncate string
  
  Values are first, second, or none.
  
  span number
  
  Span options to apply
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
- text_expansion object
  Hide text_expansion attributes Show text_expansion attributes object
  
  tokenization object
  
  Hide tokenization attributes Show tokenization attributes object
  
  truncate string
  
  Values are first, second, or none.
  
  span number
  
  Span options to apply
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
- question_answering object
  Hide question_answering attributes Show question_answering attributes object
  
  question string Required
  
  The question to answer given the inference context
  
  num_top_classes number
  
  Specifies the number of top class predictions to return. Defaults to 0.
  
  tokenization object
  
  Hide tokenization attributes Show tokenization attributes object
  
  truncate string
  
  Values are first, second, or none.
  
  span number
  
  Span options to apply
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  max_answer_length number
  
  The maximum answer length to consider for extraction

Responses

200 application/json
Hide response attribute Show response attribute object
- inference_results array[object] Required
  
  Hide inference_results attributes Show inference_results attributes object
  
  entities array[object]
  
  If the model is trained for named entity recognition (NER) tasks, the response contains the recognized entities.
  
  Hide entities attributes Show entities attributes object
  
  class_name string Required
  
  class_probability number Required
  
  entity string Required
  
  start_pos number Required
  
  end_pos number Required
  
  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 number | string | boolean | null | array[number | string | boolean | null] | array[number | string | boolean | null | array]
  
  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:
  ScalarValue number ScalarValue number ScalarValue string ScalarValue boolean ScalarValue string | null PredictedValue array[number | string | boolean | null] array-2 array[number | string | boolean | null | array]
  
  A scalar value.
  
  A scalar value.
  
  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 array[object]
  
  For fill mask, text classification, and zero shot classification tasks, the response contains a list of top class entries.
  
  Hide top_classes attributes Show top_classes attributes object
  
  class_name string Required
  
  class_probability number Required
  
  class_score number Required
  
  warning string
  
  If the request failed, the response contains the reason for the failure.
  
  feature_importance array[object]
  
  The feature importance for the inference results. Relevant only for classification or regression models
  
  Hide feature_importance attributes Show feature_importance attributes object
  
  feature_name string Required
  
  importance number
  
  classes array[object]

POST /_ml/trained_models/{model_id}/_infer

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."}]
}

curl \
 --request POST 'http://api.example.com/_ml/trained_models/{model_id}/_infer' \
 --header "Content-Type: application/json" \
 --data '"{\n  \"docs\":[{\"text\": \"The fool doth think he is wise, but the wise man knows himself to be a fool.\"}]\n}"'

Request example

An example body for a `POST _ml/trained_models/lang_ident_model_1/_infer` request.

{
  "docs":[{"text": "The fool doth think he is wise, but the wise man knows himself to be a fool."}]
}

Documentation preview

This is a preview of your version @2025-06-09 which is not yet released.

View current documentation