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

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

    The inference configuration updates to apply on the API call

    Hide inference_config attributes Show inference_config attributes object
    • regression object

      Regression configuration for inference.

      Hide regression attributes Show regression attributes object
      • results_field string

        The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.

      • num_top_feature_importance_values number

        Specifies the maximum number of feature importance values per document.

        Default value is 0.0.

    • classification object

      Classification configuration for inference.

      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.

        Default value is 0.0.

      • 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

      Text classification configuration for inference.

      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

        The tokenization options to update when inferring

        Hide tokenization attribute Show tokenization attribute object
        • 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

      Zeroshot classification configuration for inference.

      Hide zero_shot_classification attributes Show zero_shot_classification attributes object
      • tokenization object

        The tokenization options to update when inferring

        Hide tokenization attribute Show tokenization attribute object
        • 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

      Fill mask configuration for inference.

      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

        The tokenization options to update when inferring

        Hide tokenization attribute Show tokenization attribute object
        • 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

      Named entity recognition configuration for inference.

      Hide ner attributes Show ner attributes object
      • tokenization object

        The tokenization options to update when inferring

        Hide tokenization attribute Show tokenization attribute object
        • 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

      Pass through configuration for inference.

      Hide pass_through attributes Show pass_through attributes object
      • tokenization object

        The tokenization options to update when inferring

        Hide tokenization attribute Show tokenization attribute object
        • 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

      Text embedding configuration for inference.

      Hide text_embedding attributes Show text_embedding attributes object
      • tokenization object
        Hide tokenization attribute Show tokenization attribute object
        • 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

      Text expansion configuration for inference.

      Hide text_expansion attributes Show text_expansion attributes object
      • tokenization object
        Hide tokenization attribute Show tokenization attribute object
        • 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

      Question answering configuration for inference

      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

        The tokenization options to update when inferring

        Hide tokenization attribute Show tokenization attribute object
        • 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:
        number-1 number number-2 number string-3 string boolean-4 boolean string-5 string | null array-2 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 
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."}]
}