Create a trained model

Auth

Enable you to supply a trained model that is not created by data frame analytics.

Required privileges

Cluster privileges manage_ml

Path parameters

model_id string required

The unique identifier of the trained model.

Query parameters

defer_definition_decompression boolean · default: false

If set to true and a compressed_definition is provided, the request defers definition decompression and skips relevant validations.

wait_for_completion boolean · default: false

Whether to wait for all child operations (e.g. model download) to complete.

Request body

compressed_definition string

The compressed (GZipped and Base64 encoded) inference definition of the model. If compressed_definition is specified, then definition cannot be specified.

definition object

The inference definition for the model. If definition is specified, then compressed_definition cannot be specified.

preprocessors object[]

Collection of preprocessors

frequency_encoding object
field string required
feature_name string required
frequency_map map string to number required
one_hot_encoding object
field string required
hot_map map string to string required
target_mean_encoding object
field string required
feature_name string required
target_map map string to number required
default_value number required
trained_model object required

The definition of the trained model.

tree object

The definition for a binary decision tree.

classification_labels string[]
feature_names string[] required
target_type string
tree_structure object[] required
decision_type string
default_left boolean
leaf_value number
left_child number
node_index number required
right_child number
split_feature number
split_gain number
threshold number
tree_node object

The definition of a node in a tree. There are two major types of nodes: leaf nodes and not-leaf nodes.

  • Leaf nodes only need node_index and leaf_value defined.
  • All other nodes need split_feature, left_child, right_child, threshold, decision_type, and default_left defined.
decision_type string
default_left boolean
leaf_value number
left_child number
node_index number required
right_child number
split_feature number
split_gain number
threshold number
ensemble object

The definition for an ensemble model

aggregate_output object
logistic_regression object
weights number required
weighted_sum object
weights number required
weighted_mode object
weights number required
exponent object
weights number required
classification_labels string[]
feature_names string[]
target_type string
trained_models object[] required
Same fields as trained_model in definition
description string

A human-readable description of the inference trained model.

inference_config object

The default configuration for inference. This can be either a regression or classification configuration. 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

The input field names for the model definition.

field_names union oneOf required
One of: string[] or string
metadata object

An object map that contains metadata about the model.

model_type enum · default: tree_ensemble

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
model_size_bytes number

The estimated memory usage in bytes to keep the trained model in memory. This property is supported only if defer_definition_decompression is true or the model definition is not supplied.

platform_architecture string

The platform architecture (if applicable) of the trained mode. If the model only works on one platform, because it is heavily optimized for a particular processor architecture and OS combination, then this field specifies which. The format of the string must match the platform identifiers used by Elasticsearch, so one of, linux-x86_64, linux-aarch64, darwin-aarch64, or windows-x86_64. For portable models (those that work independent of processor architecture or OS features), leave this field unset.

tags string[]

An array of tags to organize the model.

prefix_strings object

Optional prefix strings applied at inference

ingest string

String prepended to input at ingest

String prepended to input at search

Response

application/json
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.

Same fields as inference_config
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