Skip to content

Commit 50e26d4

Browse files
szabostevelcawl
szabosteve
and
lcawl
authored
[DOCS] Adds GET, GET stats and DELETE inference APIs (#50224)
Co-Authored-By: Lisa Cawley <[email protected]>
1 parent 046595d commit 50e26d4

5 files changed

+323
-0
lines changed

‎docs/reference/ml/df-analytics/apis/delete-inference-trained-model.asciidoc

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[delete-inference]]
4+
=== Delete {infer} trained model API
5+
[subs="attributes"]
6+
++++
7+
<titleabbrev>Delete {infer} trained model</titleabbrev>
8+
++++
9+
10+
Deletes an existing trained {infer} model that is currently not referenced by an
11+
ingest pipeline.
12+
13+
experimental[]
14+
15+
16+
[[ml-delete-inference-request]]
17+
==== {api-request-title}
18+
19+
`DELETE _ml/inference/<model_id>`
20+
21+
22+
[[ml-delete-inference-prereq]]
23+
==== {api-prereq-title}
24+
25+
* You must have `machine_learning_admin` built-in role to use this API. For more
26+
information, see <<security-privileges>> and <<built-in-roles>>.
27+
28+
29+
[[ml-delete-inference-path-params]]
30+
==== {api-path-parms-title}
31+
32+
`<model_id>`::
33+
(Optional, string)
34+
include::{docdir}/ml/ml-shared.asciidoc[tag=model-id]
35+
36+
37+
[[ml-delete-inference-response-codes]]
38+
==== {api-response-codes-title}
39+
40+
`409`::
41+
The code indicates that the trained {infer} model is referenced by an ingest
42+
pipeline and cannot be deleted.
43+
44+
45+
[[ml-delete-inference-example]]
46+
==== {api-examples-title}
47+
48+
The following example deletes the `regression-job-one-1574775307356` trained
49+
model:
50+
51+
[source,console]
52+
--------------------------------------------------
53+
DELETE _ml/inference/regression-job-one-1574775307356
54+
--------------------------------------------------
55+
// TEST[skip:TBD]
56+
57+
The API returns the following result:
58+
59+
60+
[source,console-result]
61+
----
62+
{
63+
"acknowledged" : true
64+
}
65+
----
66+
67+

‎docs/reference/ml/df-analytics/apis/get-inference-trained-model-stats.asciidoc

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[get-inference-stats]]
4+
=== Get {infer} trained model statistics API
5+
[subs="attributes"]
6+
++++
7+
<titleabbrev>Get {infer} trained model stats</titleabbrev>
8+
++++
9+
10+
Retrieves usage information for trained {infer} models.
11+
12+
experimental[]
13+
14+
15+
[[ml-get-inference-stats-request]]
16+
==== {api-request-title}
17+
18+
`GET _ml/inference/_stats` +
19+
20+
`GET _ml/inference/_all/_stats` +
21+
22+
`GET _ml/inference/<model_id>/_stats` +
23+
24+
`GET _ml/inference/<model_id>,<model_id_2>/_stats` +
25+
26+
`GET _ml/inference/<model_id_pattern*>,<model_id_2>/_stats`
27+
28+
29+
[[ml-get-inference-stats-prereq]]
30+
==== {api-prereq-title}
31+
32+
* You must have `monitor_ml` privilege to use this API. For more information,
33+
see <<security-privileges>> and <<built-in-roles>>.
34+
35+
36+
[[ml-get-inference-stats-desc]]
37+
==== {api-description-title}
38+
39+
You can get usage information for multiple trained models in a single API
40+
request by using a comma-separated list of model IDs or a wildcard expression.
41+
42+
43+
[[ml-get-inference-stats-path-params]]
44+
==== {api-path-parms-title}
45+
46+
`<model_id>`::
47+
(Optional, string)
48+
include::{docdir}/ml/ml-shared.asciidoc[tag=model-id]
49+
50+
51+
[[ml-get-inference-stats-query-params]]
52+
==== {api-query-parms-title}
53+
54+
`allow_no_match`::
55+
(Optional, boolean)
56+
include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-match]
57+
58+
`from`::
59+
(Optional, integer)
60+
include::{docdir}/ml/ml-shared.asciidoc[tag=from]
61+
62+
`size`::
63+
(Optional, integer)
64+
include::{docdir}/ml/ml-shared.asciidoc[tag=size]
65+
66+
67+
[[ml-get-inference-stats-response-codes]]
68+
==== {api-response-codes-title}
69+
70+
`404` (Missing resources)::
71+
If `allow_no_match` is `false`, this code indicates that there are no
72+
resources that match the request or only partial matches for the request.
73+
74+
75+
[[ml-get-inference-stats-example]]
76+
==== {api-examples-title}
77+
78+
The following example gets usage information for all the trained models:
79+
80+
[source,console]
81+
--------------------------------------------------
82+
GET _ml/inference/_stats
83+
--------------------------------------------------
84+
// TEST[skip:TBD]
85+
86+
87+
The API returns the following results:
88+
89+
[source,console-result]
90+
----
91+
{
92+
"count": 2,
93+
"trained_model_stats": [
94+
{
95+
"model_id": "flight-delay-prediction-1574775339910",
96+
"pipeline_count": 0
97+
},
98+
{
99+
"model_id": "regression-job-one-1574775307356",
100+
"pipeline_count": 1,
101+
"ingest": {
102+
"total": {
103+
"count": 178,
104+
"time_in_millis": 8,
105+
"current": 0,
106+
"failed": 0
107+
},
108+
"pipelines": {
109+
"flight-delay": {
110+
"count": 178,
111+
"time_in_millis": 8,
112+
"current": 0,
113+
"failed": 0,
114+
"processors": [
115+
{
116+
"inference": {
117+
"type": "inference",
118+
"stats": {
119+
"count": 178,
120+
"time_in_millis": 7,
121+
"current": 0,
122+
"failed": 0
123+
}
124+
}
125+
}
126+
]
127+
}
128+
}
129+
}
130+
}
131+
]
132+
}
133+
----
134+
// NOTCONSOLE

‎docs/reference/ml/df-analytics/apis/get-inference-trained-model.asciidoc

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[get-inference]]
4+
=== Get {infer} trained model API
5+
[subs="attributes"]
6+
++++
7+
<titleabbrev>Get {infer} trained model</titleabbrev>
8+
++++
9+
10+
Retrieves configuration information for a trained {infer} model.
11+
12+
experimental[]
13+
14+
15+
[[ml-get-inference-request]]
16+
==== {api-request-title}
17+
18+
`GET _ml/inference/` +
19+
20+
`GET _ml/inference/<model_id>` +
21+
22+
`GET _ml/inference/_all` +
23+
24+
`GET _ml/inference/<model_id1>,<model_id2>` +
25+
26+
`GET _ml/inference/<model_id_pattern*>`
27+
28+
29+
[[ml-get-inference-prereq]]
30+
==== {api-prereq-title}
31+
32+
* You must have `monitor_ml` privilege to use this API. For more information,
33+
see <<security-privileges>> and <<built-in-roles>>.
34+
35+
36+
[[ml-get-inference-desc]]
37+
==== {api-description-title}
38+
39+
You can get information for multiple trained models in a single API request by
40+
using a comma-separated list of model IDs or a wildcard expression.
41+
42+
43+
[[ml-get-inference-path-params]]
44+
==== {api-path-parms-title}
45+
46+
`<model_id>`::
47+
(Optional, string)
48+
include::{docdir}/ml/ml-shared.asciidoc[tag=model-id]
49+
50+
51+
[[ml-get-inference-query-params]]
52+
==== {api-query-parms-title}
53+
54+
`allow_no_match`::
55+
(Optional, boolean)
56+
include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-match]
57+
58+
`decompress_definition`::
59+
(Optional, boolean)
60+
include::{docdir}/ml/ml-shared.asciidoc[tag=decompress-definition]
61+
62+
`from`::
63+
(Optional, integer)
64+
include::{docdir}/ml/ml-shared.asciidoc[tag=from]
65+
66+
`include_model_definition`::
67+
(Optional, boolean)
68+
include::{docdir}/ml/ml-shared.asciidoc[tag=include-model-definition]
69+
70+
`size`::
71+
(Optional, integer)
72+
include::{docdir}/ml/ml-shared.asciidoc[tag=size]
73+
74+
75+
[[ml-get-inference-response-codes]]
76+
==== {api-response-codes-title}
77+
78+
`400`::
79+
If `include_model_definition` is `true`, this code indicates that more than
80+
one models match the ID pattern.
81+
82+
`404` (Missing resources)::
83+
If `allow_no_match` is `false`, this code indicates that there are no
84+
resources that match the request or only partial matches for the request.
85+
86+
87+
[[ml-get-inference-example]]
88+
==== {api-examples-title}
89+
90+
The following example gets configuration information for all the trained models:
91+
92+
[source,console]
93+
--------------------------------------------------
94+
GET _ml/inference/
95+
--------------------------------------------------
96+
// TEST[skip:TBD]

‎docs/reference/ml/df-analytics/apis/index.asciidoc

+11
Original file line numberDiff line numberDiff line change
@@ -16,19 +16,30 @@ You can use the following APIs to perform {ml} {dfanalytics} activities.
1616

1717
For the `analysis` object resources, check <<ml-dfa-analysis-objects>>.
1818

19+
20+
You can use the following APIs to perform {infer} operations.
21+
22+
* <<get-inference>>
23+
* <<get-inference-stats>>
24+
* <<delete-inference>>
25+
26+
1927
See also <<ml-apis>>.
2028

2129
//CREATE
2230
include::put-dfanalytics.asciidoc[]
2331
//DELETE
2432
include::delete-dfanalytics.asciidoc[]
33+
include::delete-inference-trained-model.asciidoc[]
2534
//EVALUATE
2635
include::evaluate-dfanalytics.asciidoc[]
2736
//ESTIMATE_MEMORY_USAGE
2837
include::explain-dfanalytics.asciidoc[]
2938
//GET
3039
include::get-dfanalytics.asciidoc[]
3140
include::get-dfanalytics-stats.asciidoc[]
41+
include::get-inference-trained-model.asciidoc[]
42+
include::get-inference-trained-model-stats.asciidoc[]
3243
//SET/START/STOP
3344
include::start-dfanalytics.asciidoc[]
3445
include::stop-dfanalytics.asciidoc[]

‎docs/reference/ml/ml-shared.asciidoc

+15
Original file line numberDiff line numberDiff line change
@@ -483,6 +483,11 @@ Identifier for the {dfeed}. It can be a {dfeed} identifier or a wildcard
483483
expression.
484484
end::datafeed-id-wildcard[]
485485

486+
tag::decompress-definition[]
487+
Specifies whether the included model definition should be returned as a JSON map (`true`) or
488+
in a custom compressed format (`false`). Defaults to `true`.
489+
end::decompress-definition[]
490+
486491
tag::delayed-data-check-config[]
487492
Specifies whether the {dfeed} checks for missing data and the size of the
488493
window. For example: `{"enabled": true, "check_window": "1h"}`.
@@ -688,6 +693,12 @@ tag::groups[]
688693
A list of job groups. A job can belong to no groups or many.
689694
end::groups[]
690695

696+
tag::include-model-definition[]
697+
Specifies if the model definition should be returned in the response. Defaults
698+
to `false`. When `true`, only a single model must match the ID patterns
699+
provided, otherwise a bad request is returned.
700+
end::include-model-definition[]
701+
691702
tag::indices[]
692703
An array of index names. Wildcards are supported. For example:
693704
`["it_ops_metrics", "server*"]`.
@@ -828,6 +839,10 @@ recommended value.
828839
--
829840
end::mode[]
830841

842+
tag::model-id[]
843+
The unique identifier of the trained {infer} model.
844+
end::model-id[]
845+
831846
tag::model-memory-limit[]
832847
The approximate maximum amount of memory resources that are required for
833848
analytical processing. Once this limit is approached, data pruning becomes

0 commit comments

Comments
 (0)