[ML] adding some initial document for our pytorch NLP model support (#78270)

Adding docs for:

put vocab
put model definition part
start deployment
all the new NLP configuration objects for trained model configurations

docs/reference/ml/df-analytics/apis/get-trained-models.asciidoc

@@ -31,12 +31,8 @@ Requires the `monitor_ml` cluster privilege. This privilege is included in the
 `machine_learning_user` built-in role.
 
 
-[[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-desc]]
+//== {api-description-title}
 
 [[ml-get-trained-models-path-params]]
 == {api-path-parms-title}
@@ -44,7 +40,9 @@ using a comma-separated list of model IDs or a wildcard expression.
 `<model_id>`::
 (Optional, string)
 include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id-or-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.
 
 [[ml-get-trained-models-query-params]]
 == {api-query-parms-title}
@@ -168,6 +166,155 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-results-field]
 (string)
 include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-top-classes-results-field]
 ======
+
+`fill_mask`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-fill-mask]
++
+.Properties of fill_mask inference
+[%collapsible%open]
+======
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+=======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+========
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
+
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+========
+=======
+`vocabulary`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-vocabulary]
++
+.Properties of vocabulary
+[%collapsible%open]
+=======
+`index`::::
+(Required, string)
+The index where the vocabulary is stored.
+=======
+======
+
+`ner`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-ner]
++
+.Properties of ner inference
+[%collapsible%open]
+======
+`classification_labels`::::
+(Optional, string) 
+An array of classification labels. NER supports only 
+Inside-Outside-Beginning labels (IOB) and only persons, organizations, locations,
+and miscellaneous. For example:
+`["O", "B-PER", "I-PER", "B-ORG", "I-ORG", "B-LOC", "I-LOC", "B-MISC", "I-MISC"]`.
+
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+=======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+========
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
+
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+========
+=======
+`vocabulary`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-vocabulary]
++
+.Properties of vocabulary
+[%collapsible%open]
+=======
+`index`::::
+(Required, string)
+The index where the vocabulary is stored
+=======
+======
+
+`pass_through`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-pass-through]
++
+.Properties of pass_through inference
+[%collapsible%open]
+======
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+=======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+========
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
+
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+========
+=======
+`vocabulary`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-vocabulary]
++
+.Properties of vocabulary
+[%collapsible%open]
+=======
+`index`::::
+(Required, string)
+The index where the vocabulary is stored.
+=======
+======
+
 `regression`::::
 (object)
 Regression configuration for inference.
@@ -183,11 +330,112 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-regression-num
 (string)
 include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-results-field]
 ======
+`text_classification`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-text-classification]
++
+.Properties of text_classification inference
+[%collapsible%open]
+======
+`classification_labels`::::
+(Optional, string) 
+An array of classification labels.
+
+`num_top_classes`::::
+(Optional, integer)
+Specifies the number of top class predictions to return. Defaults to all classes (-1).
+
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+=======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+========
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
+
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+========
+=======
+
+`vocabulary`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-vocabulary]
++
+.Properties of vocabulary
+[%collapsible%open]
+=======
+`index`::::
+(Required, string)
+The index where the vocabulary is stored.
+=======
+======
+`text_embedding`::::
+(Object, optional)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-text-embedding]
++
+.Properties of text_embedding inference
+[%collapsible%open]
+======
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+=======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+========
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
+
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+========
+=======
+`vocabulary`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-vocabulary]
++
+.Properties of vocabulary
+[%collapsible%open]
+=======
+`index`::::
+(Required, string)
+The index where the vocabulary is stored.
+=======
+======
 =====
 
 `input`:::
 (object)
-The input field names for the model definition.+
+The input field names for the model definition.
 +
 .Properties of `input`
 [%collapsible%open]
@@ -197,11 +445,27 @@ The input field names for the model definition.+
 An array of input field names for the model.
 =====
 
-`license_level`:::
+// Begin location
+`location`::
+(Optional, object)
+The model definition location. Must be provided if the `definition` or `compressed_definition` are not
+provided.
++
+.Properties of `location`
+[%collapsible%open]
+=====
+`index`:::
+(Required, object)
+Indicates that the model definition is stored in an index. It is required to be empty as 
+the index for storing model definitions is configured automatically.
+=====
+// End location
+
+`license_level`::
 (string)
 The license level of the trained model.
 
-`metadata`:::
+`metadata`::
 (object)
 An object containing metadata about the trained model. For example, models
 created by {dfanalytics} contain `analysis_config` and `input` objects.
@@ -331,15 +595,27 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-impo
 ======
 =====
 
-`model_id`:::
+`model_id`::
 (string)
 Identifier for the trained model.
 
-`tags`:::
+`model_type`::
+(Optional, string)
+The created model type. By default the model type is `tree_ensemble`.
+Appropriate types are: 
++
+--
+* `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.
+--
+
+`tags`::
 (string)
 A comma delimited string of tags. A trained model can have many tags, or none.
 
-`version`:::
+`version`::
 (string)
 The {es} version number in which the trained model was created.
 

docs/reference/ml/df-analytics/apis/put-trained-model-definition-part.asciidoc

@@ -52,7 +52,33 @@ The total uncompressed definition length.
 (Required, number)
 The total number of parts that will be uploaded. Must be greater than 0.
 
-////
 [[ml-put-trained-model-definition-part-example]]
 == {api-examples-title}
-////
+
+The following example creates a model definition part for a previously
+stored model configuration. The definition part is stored in the index
+that is configured by the `location.index.name`.
+ 
+
+NOTE: The value of the `definition` object is elided from the example 
+as it is a very large base64 encoded string.
+
+[source,console]
+--------------------------------------------------
+PUT _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/part/0
+{
+    "definition": "...",
+    "total_definition_length": 265632637,
+    "total_parts": 64
+}
+--------------------------------------------------
+// TEST[skip:TBD]
+
+The API returns the following results:
+
+[source,console-result]
+----
+{
+    "acknowledged": true
+}
+----

docs/reference/ml/df-analytics/apis/put-trained-model-vocabulary.asciidoc

@@ -8,7 +8,7 @@
 ++++
 
 Creates a trained model vocabulary.
-This is only supported on NLP type models.
+This is supported only for natural language processing (NLP) models.
 
 experimental::[]
 
@@ -25,6 +25,13 @@ Requires the `manage_ml` cluster privilege. This privilege is included in the
 `machine_learning_admin` built-in role.
 
 
+[[ml-put-trained-model-vocabulary-desc]]
+== {api-description-title}
+
+The vocabulary is stored in the index as described in
+`inference_config.*.vocabulary` of the trained model definition.
+
+
 [[ml-put-trained-model-vocabulary-path-params]]
 == {api-path-parms-title}
 
@@ -39,7 +46,30 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]
 (array)
 The model vocabulary. Must not be empty.
 
-////
 [[ml-put-trained-model-vocabulary-example]]
 == {api-examples-title}
-////
+
+The following example shows how to create a model vocabulary for a 
+previously stored trained model configuration.
+
+[source,js]
+--------------------------------------------------
+PUT _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/vocabulary
+{
+  "vocabulary": [
+    "[PAD]",
+    "[unused0]",
+    ...
+  ]
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+The API returns the following results:
+
+[source,console-result]
+----
+{
+    "acknowledged": true
+}
+----

docs/reference/ml/df-analytics/apis/put-trained-models.asciidoc

@@ -376,13 +376,157 @@ A human-readable description of the {infer} trained model.
 //Begin inference_config
 `inference_config`::
 (Required, 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`.
+The default configuration for inference. This can be: `regression`,
+`classification`, `fill_mask`, `ner`, `text_classification`, or `text_embedding`. 
+If `regression` or `classification`, it must match the `target_type` of the
+underlying `definition.trained_model`. If `fill_mask`, `ner`,
+`text_classification`, or `text_embedding`; the `model_type` must be `pytorch`.
 +
 .Properties of `inference_config`
 [%collapsible%open]
 ====
+`classification`:::
+(Optional, object)
+Classification configuration for inference.
++
+.Properties of classification inference
+[%collapsible%open]
+=====
+`num_top_classes`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-num-top-classes]
+
+`num_top_feature_importance_values`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-num-top-feature-importance-values]
+
+`prediction_field_type`::::
+(Optional, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-prediction-field-type]
+
+`results_field`::::
+(Optional, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-results-field]
+
+`top_classes_results_field`::::
+(Optional, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-top-classes-results-field]
+=====
+
+`fill_mask`:::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-fill-mask]
++
+.Properties of fill_mask inference
+[%collapsible%open]
+=====
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+=======
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
+
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+=======
+======
+=====
+
+`ner`:::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-ner]
++
+.Properties of ner inference
+[%collapsible%open]
+=====
+`classification_labels`::::
+(Optional, string) 
+An array of classification labels. NER only supports Inside-Outside-Beginning labels (IOB)
+and only persons, organizations, locations, and miscellaneous.
+Example: ["O", "B-PER", "I-PER", "B-ORG", "I-ORG", "B-LOC", "I-LOC", "B-MISC", "I-MISC"]
+
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+=======
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
+
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+=======
+======
+=====
+
+`pass_through`:::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-pass-through]
++
+.Properties of pass_through inference
+[%collapsible%open]
+=====
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+=======
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
+
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+=======
+======
+=====
+
 `regression`:::
 (Optional, object)
 Regression configuration for inference.
@@ -399,32 +543,82 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-regression-num
 include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-results-field]
 =====
 
-`classification`:::
+`text_classification`:::
 (Optional, object)
-Classification configuration for inference.
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-text-classification]
 +
-.Properties of classification inference
+.Properties of text_classification inference
 [%collapsible%open]
 =====
+`classification_labels`::::
+(Optional, string) An array of classification labels.
+
 `num_top_classes`::::
 (Optional, integer)
-include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-num-top-classes]
+Specifies the number of top class predictions to return. Defaults to all classes (-1).
 
-`num_top_feature_importance_values`::::
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+=======
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
+
+`max_sequence_length`::::
 (Optional, integer)
-include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-num-top-feature-importance-values]
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
 
-`prediction_field_type`::::
-(Optional, string)
-include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-prediction-field-type]
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+=======
+======
+=====
+`text_embedding`:::
+(Object, optional)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-text-embedding]
++
+.Properties of text_embedding inference
+[%collapsible%open]
+=====
+`tokenization`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
++
+.Properties of tokenization
+[%collapsible%open]
+======
+`bert`::::
+(Optional, object)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
++
+.Properties of bert
+[%collapsible%open]
+=======
+`do_lower_case`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-do-lower-case]
 
-`results_field`::::
-(Optional, string)
-include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-results-field]
+`max_sequence_length`::::
+(Optional, integer)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-max-sequence-length]
 
-`top_classes_results_field`::::
-(Optional, string)
-include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-classification-top-classes-results-field]
+`with_special_tokens`::::
+(Optional, boolean)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert-with-special-tokens]
+=======
+======
 =====
 ====
 //End of inference_config
@@ -443,10 +637,38 @@ An array of input field names for the model.
 ====
 //End input
 
+// Begin location
+`location`::
+(Optional, object)
+The model definition location. If the `definition` or `compressed_definition`
+are not specified, the `location` is required.
++
+.Properties of `location`
+[%collapsible%open]
+====
+`index`:::
+(Required, object)
+Indicates that the model definition is stored in an index. This object must be
+empty as the index for storing model definitions is configured automatically.
+====
+// End location
+
 `metadata`::
 (Optional, object)
 An object map that contains metadata about the model.
 
+`model_type`::
+(Optional, string)
+The created model type. By default the model type is `tree_ensemble`.
+Appropriate types are: 
++
+--
+* `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.
+--
+
 `tags`::
 (Optional, string)
 An array of tags to organize the model.

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

@@ -7,20 +7,23 @@
 <titleabbrev>Start trained model deployment</titleabbrev>
 ++++
 
+Starts a new trained model deployment.
+
 [[start-trained-model-deployment-request]]
 == {api-request-title}
 
 `POST _ml/trained_models/<model_id>/deployent/_start`
-////
+
 [[start-trained-model-deployment-prereq]]
 == {api-prereq-title}
+Requires the `manage_ml` cluster privilege. This privilege is included in the
+`machine_learning_admin` built-in role.
 
-////
-////
 [[start-trained-model-deployment-desc]]
 == {api-description-title}
 
-////
+Currently only `pytorch` models are supported for deployment. When deployed,
+the model attempts allocation to every machine learning node.
 
 [[start-trained-model-deployment-path-params]]
 == {api-path-parms-title}
@@ -39,25 +42,41 @@ to 20 seconds.
 
 `wait_for`::
 (Optional, string)
-Which allocation status to wait for before returning. Defaults to "started".
-Valid values are: "starting", "started", and "fully_allocated". Each
-indicating, respectively, deployment is starting but not yet on any
-node, the model has started on at least one node, the deployment has
-started on all valid nodes.
-
-////
-[role="child_attributes"]
-[[start-trained-model-deployment-results]]
-== {api-response-body-title}
-////
-
-////
-[[start-trained-models-response-codes]]
-== {api-response-codes-title}
-////
-
-////
+Specifies the allocation status to wait for before returning. Defaults to
+`started`. The value `starting` indicates deployment is starting but not yet on
+any node. The value `started` indicates the model has started on at least one
+node. The value `fully_allocated` indicates the deployment has started on all
+valid nodes.
+
 [[start-trained-model-deployment-example]]
 == {api-examples-title}
 
-////
+The following example starts a new deployment for a
+`elastic__d`istilbert-base-uncased-finetuned-conll03-english` trained model: 
+
+[source,console]
+--------------------------------------------------
+POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_start?wait_for=started&timeout=1m
+--------------------------------------------------
+// TEST[skip:TBD]
+
+The API returns the following results:
+
+[source,console-result]
+----
+{
+    "allocation": {
+        "task_parameters": {
+            "model_id": "elastic__distilbert-base-uncased-finetuned-conll03-english",
+            "model_bytes": 265632637
+        },
+        "routing_table": {
+            "uckeG3R8TLe2MMNBQ6AGrw": {
+                "routing_state": "started",
+                "reason": ""
+            }
+        },
+        "allocation_state": "started"
+    }
+}
+----

docs/reference/ml/ml-shared.asciidoc

@@ -912,6 +912,75 @@ Acceptable values are: `string`, `number`, `boolean`. When `boolean` is provided
 `1.0` is transformed to `true` and `0.0` to `false`.
 end::inference-config-classification-prediction-field-type[]
 
+tag::inference-config-nlp-tokenization[]
+Indicates the tokenization to perform and the desired settings.
+end::inference-config-nlp-tokenization[]
+
+tag::inference-config-nlp-tokenization-bert[]
+BERT-style tokenization is to be performed with the enclosed settings.
+end::inference-config-nlp-tokenization-bert[]
+
+tag::inference-config-nlp-tokenization-bert-do-lower-case[]
+Should the tokenization lower case the text sequence when building 
+the tokens.
+end::inference-config-nlp-tokenization-bert-do-lower-case[]
+
+tag::inference-config-nlp-tokenization-bert-with-special-tokens[]
+Tokenize with special tokens. The tokens typically included in BERT-style tokenization are:
++
+--
+* `[CLS]`: The first token of the sequence being classified.
+* `[SEP]`: Indicates sequence separation. 
+--
+end::inference-config-nlp-tokenization-bert-with-special-tokens[]
+
+tag::inference-config-nlp-tokenization-bert-max-sequence-length[]
+The maximum number of tokens allowed to be output by the tokenizer.
+The default for BERT-style tokenization is `512`.
+end::inference-config-nlp-tokenization-bert-max-sequence-length[]
+
+tag::inference-config-nlp-vocabulary[]
+The configuration for retreiving the model's vocabulary. The vocabulary is then
+used at inference time. This information is usually provided automatically by
+storing vocabulary in a known, internally managed index.
+end::inference-config-nlp-vocabulary[]
+
+tag::inference-config-nlp-fill-mask[]
+Configuration for a fill_mask NLP task. The fill_mask task works with models
+optimized for a fill mask action. For example, for BERT models, the following
+text may be provided: "The capital of France is [MASK].". The response indicates
+the value most likely to replace `[MASK]`. In this instance, the
+most probable token is `paris`.
+end::inference-config-nlp-fill-mask[]
+
+tag::inference-config-ner[]
+Configures a named entity recognition (NER) task. NER is a special case of token
+classification. Each token in the sequence is classified according to the
+provided classification labels. Currently, the NER task requires the
+`classification_labels` Inside-Outside-Beginning formatted labels. Only
+person, organization, location, and miscellaneous are supported.
+end::inference-config-ner[]
+
+tag::inference-config-pass-through[]
+Configures a `pass_through` task. This task is useful for debugging as no
+post-processing is done to the inference output and the raw pooling layer
+results are returned to the caller.
+end::inference-config-pass-through[]
+
+tag::inference-config-text-classification[]
+A text classification task. Text classification classifies a provided text
+sequence into previously known target classes. A specific example of this is
+sentiment analysis, which returns the likely target classes indicating text
+sentiment, such as "sad", "happy", or "angry".
+end::inference-config-text-classification[]
+
+tag::inference-config-text-embedding[]
+Text embedding takes an input sequence and transforms it into a vector of
+numbers. These embeddings capture not simply tokens, but semantic meanings and
+context. These embeddings can then be used in a <<dense-vector,dense vector>>
+field for powerful insights.
+end::inference-config-text-embedding[]
+
 tag::inference-config-regression-num-top-feature-importance-values[]
 Specifies the maximum number of
 {ml-docs}/ml-feature-importance.html[{feat-imp}] values per document.