Get trained model configuration info

  • GET /_ml/trained_models/{model_id}
  • GET /_ml/trained_models
Auth

Required authorization

Cluster privileges monitor_ml

Path parameters

model_id union string | string[] optional

The unique identifier of the trained model or a model alias.

You can get information for multiple trained models in a single API request by using a comma-separated list of model IDs or a wildcard expression.

Leave it out to use /_ml/trained_models.

Query parameters

allow_no_match boolean · default: true

Specifies what to do when the request:

  • Contains wildcard expressions and there are no models that match.
  • Contains the _all string or no identifiers and there are no matches.
  • Contains wildcard expressions and there are only partial matches.

If true, it returns an empty array when there are no matches and the subset of results when there are partial matches.

decompress_definition boolean · default: true

Specifies whether the included model definition should be returned as a JSON map (true) or in a custom compressed format (false).

exclude_generated boolean · default: false

Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.

from number · default: 0

Skips the specified number of models.

include enum

A comma delimited string of optional fields to include in the response body.

Supported values include:

  • definition: Includes the model definition.
  • feature_importance_baseline: Includes the baseline for feature importance values.
  • hyperparameters: Includes the information about hyperparameters used to train the model. This information consists of the value, the absolute and relative importance of the hyperparameter as well as an indicator of whether it was specified by the user or tuned during hyperparameter optimization.
  • total_feature_importance: Includes the total feature importance for the training data set. The baseline and total feature importance values are returned in the metadata field in the response body.
  • definition_status: Includes the model definition status.
Values: definition feature_importance_baseline hyperparameters total_feature_importance definition_status
include_model_definition boolean deprecated

parameter is deprecated! Use [include=definition] instead

size number · default: 100

Specifies the maximum number of models to obtain.

tags union string | string[]

A comma delimited string of tags. A trained model can have many tags, or none. When supplied, only trained models that contain all the supplied tags are returned.

Response

application/json
count number required
trained_model_configs object[] required

An array of trained model resources, which are sorted by the model_id value in ascending order.

model_id string required

Identifier for the trained model.

model_type enum

The model type

Supported values include:

  • tree_ensemble: The model definition is an ensemble model of decision trees.
  • lang_ident: A special type reserved for language identification models.
  • pytorch: The stored definition is a PyTorch (specifically a TorchScript) model. Currently only NLP models are supported.
Values: tree_ensemble lang_ident pytorch
tags string[] required

A comma delimited string of tags. A trained model can have many tags, or none.

version string

The Elasticsearch version number in which the trained model was created.

compressed_definition string
created_by string

Information on the creator of the trained model.

create_time union oneOf

The time when the trained model was created.

One of: string or number
default_field_map map string to string

Any field map described in the inference configuration takes precedence.

description string

The free-text description of the trained model.

estimated_heap_memory_usage_bytes number

The estimated heap usage in bytes to keep the trained model in memory.

estimated_operations number

The estimated number of operations to use the trained model.

fully_defined boolean

True if the full model definition is present.

inference_config object

The default configuration for inference. This can be either a regression, classification, or one of the many NLP focused configurations. It must match the underlying definition.trained_model's target_type. For pre-packaged models such as ELSER the config is not required.

regression object

Regression configuration for inference.

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 · default: 0

Specifies the maximum number of feature importance values per document.

classification object

Classification configuration for inference.

num_top_classes number

Specifies the number of top class predictions to return. Defaults to 0.

num_top_feature_importance_values number · default: 0

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

Text classification configuration for inference.

num_top_classes number

Specifies the number of top class predictions to return. Defaults to 0.

tokenization object

The tokenization options

bert object

Indicates BERT tokenization and its options

do_lower_case boolean · default: false

Should the tokenizer lower case the text

max_sequence_length number · default: 512

Maximum input sequence length for the model

span number · default: -1

Tokenization spanning options. Special value of -1 indicates no spanning takes place

truncate enum · default: first

Should tokenization input be automatically truncated before sending to the model for inference

Values: first second none
with_special_tokens boolean · default: true

Is tokenization completed with special tokens

bert_ja object

Indicates BERT Japanese tokenization and its options

do_lower_case boolean · default: false

Should the tokenizer lower case the text

max_sequence_length number · default: 512

Maximum input sequence length for the model

span number · default: -1

Tokenization spanning options. Special value of -1 indicates no spanning takes place

truncate enum · default: first

Should tokenization input be automatically truncated before sending to the model for inference

Values: first second none
with_special_tokens boolean · default: true

Is tokenization completed with special tokens

mpnet object

Indicates MPNET tokenization and its options

do_lower_case boolean · default: false

Should the tokenizer lower case the text

max_sequence_length number · default: 512

Maximum input sequence length for the model

span number · default: -1

Tokenization spanning options. Special value of -1 indicates no spanning takes place

truncate enum · default: first

Should tokenization input be automatically truncated before sending to the model for inference

Values: first second none
with_special_tokens boolean · default: true

Is tokenization completed with special tokens

roberta object

Indicates RoBERTa tokenization and its options

do_lower_case boolean · default: false

Should the tokenizer lower case the text

max_sequence_length number · default: 512

Maximum input sequence length for the model

span number · default: -1

Tokenization spanning options. Special value of -1 indicates no spanning takes place

truncate enum · default: first

Should tokenization input be automatically truncated before sending to the model for inference

Values: first second none
with_special_tokens boolean · default: true

Is tokenization completed with special tokens

add_prefix_space boolean · default: false

Should the tokenizer prefix input with a space character

xlm_roberta object
do_lower_case boolean · default: false

Should the tokenizer lower case the text

max_sequence_length number · default: 512

Maximum input sequence length for the model

span number · default: -1

Tokenization spanning options. Special value of -1 indicates no spanning takes place

truncate enum · default: first

Should tokenization input be automatically truncated before sending to the model for inference

Values: first second none
with_special_tokens boolean · default: true

Is tokenization completed with special tokens

results_field string

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

classification_labels string[]

Classification labels to apply other than the stored labels. Must have the same deminsions as the default configured labels

vocabulary object
index string required
zero_shot_classification object

Zeroshot classification configuration for inference.

tokenization object

The tokenization options to update when inferring

Same fields as tokenization in text_classification
hypothesis_template string · default: "This example is {}."

Hypothesis template used when tokenizing labels for prediction

classification_labels string[] required

The zero shot classification labels indicating entailment, neutral, and contradiction Must contain exactly and only entailment, neutral, and contradiction

results_field string

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

multi_label boolean · default: false

Indicates if more than one true label exists.

labels string[]

The labels to predict.

fill_mask object

Fill mask configuration for inference.

mask_token string

The string/token which will be removed from incoming documents and replaced with the inference prediction(s). In a response, this field contains the mask token for the specified model/tokenizer. Each model and tokenizer has a predefined mask token which cannot be changed. Thus, it is recommended not to set this value in requests. However, if this field is present in a request, its value must match the predefined value for that model/tokenizer, otherwise the request will fail.

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

Same fields as tokenization in text_classification
results_field string

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

vocabulary object
index string required
learning_to_rank object
default_params map string to object
feature_extractors string to object[]
num_top_feature_importance_values number required
ner object

Named entity recognition configuration for inference.

tokenization object

The tokenization options

Same fields as tokenization in text_classification
results_field string

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

classification_labels string[]

The token classification labels. Must be IOB formatted tags

vocabulary object
index string required
pass_through object

Pass through configuration for inference.

tokenization object

The tokenization options

Same fields as tokenization in text_classification
results_field string

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

vocabulary object
index string required
text_embedding object

Text embedding configuration for inference.

embedding_size number

The number of dimensions in the embedding output

tokenization object

The tokenization options

Same fields as tokenization in text_classification
results_field string

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

vocabulary object
index string required
text_expansion object

Text expansion configuration for inference.

tokenization object

The tokenization options

Same fields as tokenization in text_classification
results_field string

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

vocabulary object
index string required
question_answering object

Question answering configuration for inference.

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

Same fields as tokenization in text_classification
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

input object required

The input field names for the model definition.

field_names string[] required

An array of input field names for the model.

license_level string

The license level of the trained model.

metadata object

An object containing metadata about the trained model. For example, models created by data frame analytics contain analysis_config and input objects.

model_aliases string[]
feature_importance_baseline map string to string

An object that contains the baseline for feature importance values. For regression analysis, it is a single value. For classification analysis, there is a value for each class.

hyperparameters object[]

List of the available hyperparameters optimized during the fine_parameter_tuning phase as well as specified by the user.

absolute_importance number

A positive number showing how much the parameter influences the variation of the loss function. For hyperparameters with values that are not specified by the user but tuned during hyperparameter optimization.

name string required

Name of the hyperparameter.

relative_importance number

A number between 0 and 1 showing the proportion of influence on the variation of the loss function among all tuned hyperparameters. For hyperparameters with values that are not specified by the user but tuned during hyperparameter optimization.

supplied boolean required

Indicates if the hyperparameter is specified by the user (true) or optimized (false).

value number required

The value of the hyperparameter, either optimized or specified by the user.

total_feature_importance object[]

An array of the total feature importance for each feature used from the training data set. This array of objects is returned if data frame analytics trained the model and the request includes total_feature_importance in the include request parameter.

feature_name string required

The feature for which this importance was calculated.

importance object[] required

A collection of feature importance statistics related to the training data set for this particular feature.

mean_magnitude number required

The average magnitude of this feature across all the training data. This value is the average of the absolute values of the importance for this feature.

max number required

The maximum importance value across all the training data for this feature.

min number required

The minimum importance value across all the training data for this feature.

classes object[] required

If the trained model is a classification model, feature importance statistics are gathered per target class value.

class_name string required

The target class value. Could be a string, boolean, or number.

importance object[] required

A collection of feature importance statistics related to the training data set for this particular feature.

mean_magnitude number required

The average magnitude of this feature across all the training data. This value is the average of the absolute values of the importance for this feature.

max number required

The maximum importance value across all the training data for this feature.

min number required

The minimum importance value across all the training data for this feature.

model_size_bytes number | string
model_package object
create_time number
description string
inference_config map string to object
metadata object
minimum_version string
model_repository string
model_type string
packaged_model_id string required
platform_architecture string
prefix_strings object
ingest string

String prepended to input at ingest

String prepended to input at search

size number | string
sha256 string
tags string[]
vocabulary_file string
location object
index object required
name string required
platform_architecture string
prefix_strings object
ingest string

String prepended to input at ingest

String prepended to input at search