Evaluate a trained model Generally available; Added in 8.3.0

POST /_ml/trained_models/{model_id}/_infer
Api key auth Basic auth Bearer auth

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 
curl \
 --request POST 'http://api.example.com/_ml/trained_models/{model_id}/_infer' \
 --header "Authorization: $API_KEY" \
 --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."}]
}