mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-30 10:23:41 -04:00
b9dc522cb4
* [ML] adding for_export flag for ml plugin GET resource APIs (#63092) This adds the new `for_export` flag to the following APIs: - GET _ml/anomaly_detection/<job_id> - GET _ml/datafeeds/<datafeed_id> - GET _ml/data_frame/analytics/<analytics_id> The flag is designed for cloning or exporting configuration objects to later be put into the same cluster or a separate cluster. The following fields are not returned in the objects: - any field that is not user settable (e.g. version, create_time) - any field that is a calculated default value (e.g. datafeed chunking_config) - any field that would effectively require changing to be of use (e.g. datafeed job_id) - any field that is automatically set via another Elastic stack process (e.g. anomaly job custom_settings.created_by) closes https://github.com/elastic/elasticsearch/issues/63055 * [ML] adding new flag exclude_generated that removes generated fields in GET config APIs (#63899) When exporting and cloning ml configurations in a cluster it can be frustrating to remove all the fields that were generated by the plugin. Especially as the number of these fields change from version to version. This flag, exclude_generated, allows the GET config APIs to return configurations with these generated fields removed. APIs supporting this flag: - GET _ml/anomaly_detection/<job_id> - GET _ml/datafeeds/<datafeed_id> - GET _ml/data_frame/analytics/<analytics_id> The following fields are not returned in the objects: - any field that is not user settable (e.g. version, create_time) - any field that is a calculated default value (e.g. datafeed chunking_config) - any field that is automatically set via another Elastic stack process (e.g. anomaly job custom_settings.created_by) relates to #63055
262 lines
6.6 KiB
Text
262 lines
6.6 KiB
Text
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[get-trained-models]]
|
|
= Get trained models API
|
|
[subs="attributes"]
|
|
++++
|
|
<titleabbrev>Get trained models</titleabbrev>
|
|
++++
|
|
|
|
Retrieves configuration information for a trained model.
|
|
|
|
experimental[]
|
|
|
|
|
|
[[ml-get-trained-models-request]]
|
|
== {api-request-title}
|
|
|
|
`GET _ml/trained_models/` +
|
|
|
|
`GET _ml/trained_models/<model_id>` +
|
|
|
|
`GET _ml/trained_models/_all` +
|
|
|
|
`GET _ml/trained_models/<model_id1>,<model_id2>` +
|
|
|
|
`GET _ml/trained_models/<model_id_pattern*>`
|
|
|
|
|
|
[[ml-get-trained-models-prereq]]
|
|
== {api-prereq-title}
|
|
|
|
If the {es} {security-features} are enabled, you must have the following
|
|
privileges:
|
|
|
|
* cluster: `monitor_ml`
|
|
|
|
For more information, see <<security-privileges>> and
|
|
{ml-docs-setup-privileges}.
|
|
|
|
|
|
[[ml-get-trained-models-desc]]
|
|
== {api-description-title}
|
|
|
|
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.
|
|
|
|
|
|
[[ml-get-trained-models-path-params]]
|
|
== {api-path-parms-title}
|
|
|
|
`<model_id>`::
|
|
(Optional, string)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]
|
|
|
|
|
|
[[ml-get-trained-models-query-params]]
|
|
== {api-query-parms-title}
|
|
|
|
`allow_no_match`::
|
|
(Optional, boolean)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=allow-no-match-models]
|
|
|
|
`decompress_definition`::
|
|
(Optional, boolean)
|
|
Specifies whether the included model definition should be returned as a JSON map
|
|
(`true`) or in a custom compressed format (`false`). Defaults to `true`.
|
|
|
|
`exclude_generated`::
|
|
(Optional, boolean)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=exclude-generated]
|
|
|
|
`from`::
|
|
(Optional, integer)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=from-models]
|
|
|
|
`include`::
|
|
(Optional, string)
|
|
A comma delimited string of optional fields to include in the response body. The
|
|
default value is empty, indicating no optional fields are included. Valid
|
|
options are:
|
|
- `definition`: Includes the model definition
|
|
- `feature_importance_baseline`: Includes the baseline for {feat-imp} values.
|
|
- `total_feature_importance`: Includes the total {feat-imp} for the training
|
|
data set.
|
|
The baseline and total {feat-imp} values are returned in the `metadata` field
|
|
in the response body.
|
|
|
|
`size`::
|
|
(Optional, integer)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=size-models]
|
|
|
|
`tags`::
|
|
(Optional, string)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=tags]
|
|
|
|
[role="child_attributes"]
|
|
[[ml-get-trained-models-results]]
|
|
== {api-response-body-title}
|
|
|
|
`trained_model_configs`::
|
|
(array)
|
|
An array of trained model resources, which are sorted by the `model_id` value in
|
|
ascending order.
|
|
+
|
|
.Properties of trained model resources
|
|
[%collapsible%open]
|
|
====
|
|
`created_by`:::
|
|
(string)
|
|
Information on the creator of the trained model.
|
|
|
|
`create_time`:::
|
|
(<<time-units,time units>>)
|
|
The time when the trained model was created.
|
|
|
|
`default_field_map` :::
|
|
(object)
|
|
A string to string object that contains the default field map to use
|
|
when inferring against the model. For example, data frame analytics
|
|
may train the model on a specific multi-field `foo.keyword`.
|
|
The analytics job would then supply a default field map entry for
|
|
`"foo" : "foo.keyword"`.
|
|
+
|
|
Any field map described in the inference configuration takes precedence.
|
|
|
|
`estimated_heap_memory_usage_bytes`:::
|
|
(integer)
|
|
The estimated heap usage in bytes to keep the trained model in memory.
|
|
|
|
`estimated_operations`:::
|
|
(integer)
|
|
The estimated number of operations to use the trained 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 {dfanalytics} contain `analysis_config` and `input` objects.
|
|
+
|
|
.Properties of metadata
|
|
[%collapsible%open]
|
|
=====
|
|
`feature_importance_baseline`:::
|
|
(object)
|
|
An object that contains the baseline for {feat-imp} values. For {reganalysis},
|
|
it is a single value. For {classanalysis}, there is a value for each class.
|
|
|
|
`total_feature_importance`:::
|
|
(array)
|
|
An array of the total {feat-imp} for each feature used from
|
|
the training data set. This array of objects is returned if {dfanalytics} trained
|
|
the model and the request includes `total_feature_importance` in the `include`
|
|
request parameter.
|
|
+
|
|
.Properties of total {feat-imp}
|
|
[%collapsible%open]
|
|
======
|
|
|
|
`feature_name`:::
|
|
(string)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-feature-name]
|
|
|
|
`importance`:::
|
|
(object)
|
|
A collection of {feat-imp} statistics related to the training data set for this particular feature.
|
|
+
|
|
.Properties of {feat-imp}
|
|
[%collapsible%open]
|
|
=======
|
|
`mean_magnitude`:::
|
|
(double)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-magnitude]
|
|
|
|
`max`:::
|
|
(int)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-max]
|
|
|
|
`min`:::
|
|
(int)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-min]
|
|
|
|
=======
|
|
|
|
`classes`:::
|
|
(array)
|
|
If the trained model is a classification model, {feat-imp} statistics are gathered
|
|
per target class value.
|
|
+
|
|
.Properties of class {feat-imp}
|
|
[%collapsible%open]
|
|
|
|
=======
|
|
|
|
`class_name`:::
|
|
(string)
|
|
The target class value. Could be a string, boolean, or number.
|
|
|
|
`importance`:::
|
|
(object)
|
|
A collection of {feat-imp} statistics related to the training data set for this particular feature.
|
|
+
|
|
.Properties of {feat-imp}
|
|
[%collapsible%open]
|
|
========
|
|
`mean_magnitude`:::
|
|
(double)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-magnitude]
|
|
|
|
`max`:::
|
|
(int)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-max]
|
|
|
|
`min`:::
|
|
(int)
|
|
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-min]
|
|
|
|
========
|
|
|
|
=======
|
|
|
|
======
|
|
=====
|
|
|
|
`model_id`:::
|
|
(string)
|
|
Idetifier for the trained model.
|
|
|
|
`tags`:::
|
|
(string)
|
|
A comma delimited string of tags. A trained model can have many tags, or none.
|
|
|
|
`version`:::
|
|
(string)
|
|
The {es} version number in which the trained model was created.
|
|
====
|
|
|
|
[[ml-get-trained-models-response-codes]]
|
|
|
|
== {api-response-codes-title}
|
|
|
|
`400`::
|
|
If `include_model_definition` is `true`, this code indicates that more than
|
|
one models match the ID pattern.
|
|
|
|
`404` (Missing resources)::
|
|
If `allow_no_match` is `false`, this code indicates that there are no
|
|
resources that match the request or only partial matches for the request.
|
|
|
|
|
|
[[ml-get-trained-models-example]]
|
|
== {api-examples-title}
|
|
|
|
The following example gets configuration information for all the trained models:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET _ml/trained_models/
|
|
--------------------------------------------------
|
|
// TEST[skip:TBD]
|