[DOCS] Drafts trained model deployment APIs (#75497)

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

@@ -18,8 +18,12 @@ include::get-dfanalytics.asciidoc[leveloffset=+2]
 include::get-dfanalytics-stats.asciidoc[leveloffset=+2]
 include::get-trained-models.asciidoc[leveloffset=+2]
 include::get-trained-models-stats.asciidoc[leveloffset=+2]
+//INFER
+include::infer-trained-model-deployment.asciidoc[leveloffset=+2]
 //PREVIEW
 include::preview-dfanalytics.asciidoc[leveloffset=+2]
 //SET/START/STOP
 include::start-dfanalytics.asciidoc[leveloffset=+2]
+include::start-trained-model-deployment.asciidoc[leveloffset=+2]
 include::stop-dfanalytics.asciidoc[leveloffset=+2]
+include::stop-trained-model-deployment.asciidoc[leveloffset=+2]

docs/reference/ml/df-analytics/apis/infer-trained-model-deployment.asciidoc

@@ -0,0 +1,116 @@
+[role="xpack"]
+[testenv="basic"]
+[[infer-trained-model-deployment]]
+= Infer trained model deployment API
+[subs="attributes"]
+++++
+<titleabbrev>Infer trained model deployment</titleabbrev>
+++++
+
+Evaluates a trained model.
+
+[[infer-trained-model-deployment-request]]
+== {api-request-title}
+
+`POST _ml/trained_models/<model_id>/deployment/_infer`
+
+////
+[[infer-trained-model-deployment-prereq]]
+== {api-prereq-title}
+
+////
+////
+[[infer-trained-model-deployment-desc]]
+== {api-description-title}
+
+////
+
+[[infer-trained-model-deployment-path-params]]
+== {api-path-parms-title}
+
+`<model_id>`::
+(Required, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]
+
+[[infer-trained-model-deployment-query-params]]
+== {api-query-parms-title}
+
+`timeout`::
+(Optional, time)
+Controls the amount of time to wait for {infer} results. Defaults to 10 seconds.
+
+[[infer-trained-model-request-body]]
+== {api-request-body-title}
+
+`input`::
+(Required,string)
+The input text for evaluation.
+
+////
+[[infer-trained-model-deployment-results]]
+== {api-response-body-title}
+////
+////
+[[ml-get-trained-models-response-codes]]
+== {api-response-codes-title}
+
+////
+
+[[infer-trained-model-deployment-example]]
+== {api-examples-title}
+
+The response depends on the task the model is trained for. If it is a 
+sentiment analysis task, the response is the score. For example:
+
+[source,console]
+--------------------------------------------------
+POST _ml/trained_models/model2/deployment/_infer
+{
+	"input": "The movie was awesome!!"
+}
+--------------------------------------------------
+// TEST[skip:TBD]
+
+The API returns scores in this case, for example:
+
+[source,console-result]
+----
+{
+  "positive" : 0.9998062667902223,
+  "negative" : 1.9373320977752957E-4	
+}
+----
+// NOTCONSOLE
+
+For named entity recognition (NER) tasks, the response contains the recognized
+entities and their type. For example:
+
+[source,console]
+--------------------------------------------------
+POST _ml/trained_models/model2/deployment/_infer
+{
+	"input": "Hi my name is Josh and I live in Berlin"
+}
+--------------------------------------------------
+// TEST[skip:TBD]
+
+The API returns scores in this case, for example:
+
+[source,console-result]
+----
+{
+  "entities" : [
+    {
+      "label" : "person",
+      "score" : 0.9988716330253505,
+      "word" : "Josh"
+    },
+    {
+      "label" : "location",
+      "score" : 0.9980872542990656,
+      "word" : "Berlin"
+    }
+  ]
+}
+----
+// NOTCONSOLE

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

@@ -3,34 +3,36 @@
 [[ml-df-analytics-apis]]
 = {ml-cap} {dfanalytics} APIs
 
-You can use the following APIs to perform {ml} {dfanalytics} activities.
+You can use the following APIs to perform {ml} {dfanalytics} activities:
 
-* <<preview-dfanalytics,Preview {dfanalytics}>>
 * <<put-dfanalytics,Create {dfanalytics-jobs}>>
-* <<update-dfanalytics,Update {dfanalytics-jobs}>>
 * <<delete-dfanalytics,Delete {dfanalytics-jobs}>>
 * <<get-dfanalytics,Get {dfanalytics-jobs} info>>
 * <<get-dfanalytics-stats,Get {dfanalytics-jobs} statistics>>
-* <<start-dfanalytics,Start {dfanalytics-jobs}>>
-* <<stop-dfanalytics,Stop {dfanalytics-jobs}>>
 * <<evaluate-dfanalytics,Evaluate {dfanalytics}>>
 * <<explain-dfanalytics,Explain {dfanalytics}>>
+* <<preview-dfanalytics,Preview {dfanalytics}>>
+* <<start-dfanalytics,Start {dfanalytics-jobs}>>
+* <<stop-dfanalytics,Stop {dfanalytics-jobs}>>
+* <<update-dfanalytics,Update {dfanalytics-jobs}>>
 
-
-You can use the following APIs to perform {infer} operations.
+You can use the following APIs to perform {infer} operations:
 
 * <<put-trained-models>>
-* <<get-trained-models>>
-* <<get-trained-models-stats>>
-* <<delete-trained-models>>
 * <<put-trained-models-aliases>>
+* <<delete-trained-models>>
 * <<delete-trained-models-aliases>>
+* <<get-trained-models>>
+* <<get-trained-models-stats>>
 
 You can deploy a trained model to make predictions in an ingest pipeline or in
-an aggregation. Refer to the following documentation to learn more.
+an aggregation. Refer to the following documentation to learn more:
 
-* <<inference-processor,{infer-cap} processor>>
 * <<search-aggregations-pipeline-inference-bucket-aggregation,{infer-cap} bucket aggregation>>
+* <<inference-processor,{infer-cap} processor>>
+* <<infer-trained-model-deployment>>
+* <<start-trained-model-deployment>>
+* <<stop-trained-model-deployment>>
 
 
 See also <<ml-apis>>.

docs/reference/ml/df-analytics/apis/start-trained-model-deployment.asciidoc

@@ -0,0 +1,54 @@
+[role="xpack"]
+[testenv="basic"]
+[[start-trained-model-deployment]]
+= Start trained model deployment API
+[subs="attributes"]
+++++
+<titleabbrev>Start trained model deployment</titleabbrev>
+++++
+
+[[start-trained-model-deployment-request]]
+== {api-request-title}
+
+`POST _ml/trained_models/<model_id>/deployent/_start` 
+////
+[[start-trained-model-deployment-prereq]]
+== {api-prereq-title}
+
+////
+////
+[[start-trained-model-deployment-desc]]
+== {api-description-title}
+
+////
+
+[[start-trained-model-deployment-path-params]]
+== {api-path-parms-title}
+
+`<model_id>`::
+(Required, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]
+
+[[start-trained-model-deployment-query-params]]
+== {api-query-parms-title}
+
+`timeout`::
+(Optional, time)
+Controls the amount of time to wait for the model to deploy. Defaults
+to 20 seconds.
+////
+[role="child_attributes"]
+[[start-trained-model-deployment-results]]
+== {api-response-body-title}
+
+////
+////
+[[ml-get-trained-models-response-codes]]
+== {api-response-codes-title}
+
+////
+////
+[[start-trained-model-deployment-example]]
+== {api-examples-title}
+
+////

docs/reference/ml/df-analytics/apis/stop-trained-model-deployment.asciidoc

@@ -0,0 +1,49 @@
+[role="xpack"]
+[testenv="basic"]
+[[stop-trained-model-deployment]]
+= Stop trained model deployment API
+[subs="attributes"]
+++++
+<titleabbrev>Stop trained model deployment</titleabbrev>
+++++
+
+[[stop-trained-model-deployment-request]]
+== {api-request-title}
+
+`POST _ml/trained_models/<model_id>/deployment/_stop`
+
+////
+[[stop-trained-model-deployment-prereq]]
+== {api-prereq-title}
+
+////
+////
+[[stop-trained-model-deployment-desc]]
+== {api-description-title}
+
+////
+[[stop-trained-model-deployment-path-params]]
+== {api-path-parms-title}
+
+`<model_id>`::
+(Required, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]
+
+////
+[[stop-trained-model-deployment-query-params]]
+== {api-query-parms-title}
+////
+////
+[role="child_attributes"]
+[[stop-trained-model-deployment-results]]
+== {api-response-body-title}
+////
+////
+[[ml-get-trained-models-response-codes]]
+== {api-response-codes-title}
+////
+
+////
+[[stop-trained-model-deployment-example]]
+== {api-examples-title}
+////

rest-api-spec/src/main/resources/rest-api-spec/api/ml.infer_trained_model_deployment.json

@@ -1,7 +1,7 @@
 {
   "ml.infer_trained_model_deployment":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-df-analytics-apis.html",
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/infer-trained-model-deployment.html",
       "description":"Evaluate a trained model."
     },
     "stability":"experimental",
@@ -20,7 +20,8 @@
           "parts":{
             "model_id":{
               "type":"string",
-              "description":"The ID of the model to perform inference on"
+              "description":"The unique identifier of the trained model.",
+              "required":true
             }
           }
         }
@@ -30,8 +31,13 @@
       "timeout":{
         "type":"time",
         "required":false,
-        "description":"Controls the time to wait for the inference result"
+        "description":"Controls the amount of time to wait for inference results.",
+        "default":"10s"
       }
+    },
+    "body":{
+      "description":"The input text to be evaluated.",
+      "required":true
     }
   }
 }

rest-api-spec/src/main/resources/rest-api-spec/api/ml.start_trained_model_deployment.json

@@ -1,7 +1,7 @@
 {
   "ml.start_trained_model_deployment":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-df-analytics-apis.html",
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/start-trained-model-deployment.html",
       "description":"Start a trained model deployment."
     },
     "stability":"experimental",
@@ -20,7 +20,8 @@
           "parts":{
             "model_id":{
               "type":"string",
-              "description":"The ID of the model to deploy"
+              "description":"The unique identifier of the trained model.",
+              "required":true
             }
           }
         }
@@ -30,7 +31,8 @@
       "timeout":{
         "type":"time",
         "required":false,
-        "description":"Controls the time to wait until the model is deployed"
+        "description":"Controls the amount of time to wait for the model to deploy.",
+        "default": "20s"
       }
     }
   }

rest-api-spec/src/main/resources/rest-api-spec/api/ml.stop_trained_model_deployment.json

@@ -1,7 +1,7 @@
 {
   "ml.stop_trained_model_deployment":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-df-analytics-apis.html",
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/stop-trained-model-deployment.html",
       "description":"Stop a trained model deployment."
     },
     "stability":"experimental",
@@ -20,7 +20,8 @@
           "parts":{
             "model_id":{
               "type":"string",
-              "description":"The ID of the model to undeploy"
+              "description":"The unique identifier of the trained model.",
+              "required":true
             }
           }
         }