<commit_before>[role="xpack"]
[[start-trained-model-deployment]]
= Start trained model deployment API
[subs="attributes"]
++++
<titleabbrev>Start trained model deployment</titleabbrev>
++++

experimental::[]

Starts a new trained model deployment.

[[start-trained-model-deployment-request]]
== {api-request-title}

`POST _ml/trained_models/<model_id>/deployment/_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}

`<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}

`inference_threads`::
(Optional, integer)
Sets the number of threads used by the inference process. This generally increases
the inference speed. The inference process is a compute-bound process; any number 
greater than the number of available CPU cores on the machine does not increase the 
inference speed.
Defaults to 1.

`model_threads`::
(Optional, integer)
Indicates how many threads are used when sending inference requests to
the model. Increasing this value generally increases the throughput. Defaults to
1.

`queue_capacity`::
(Optional, integer)
Controls how many inference requests are allowed in the queue at a time. Once the
number of requests exceeds this value, new requests are rejected with a 429 error.
Defaults to 1024.

`timeout`::
(Optional, time)
Controls the amount of time to wait for the model to deploy. Defaults
to 20 seconds.
<commit_msg>[ML][DOCS] Add note about max values of thread settings (#81367)<commit_after>[role="xpack"]
[[start-trained-model-deployment]]
= Start trained model deployment API
[subs="attributes"]
++++
<titleabbrev>Start trained model deployment</titleabbrev>
++++

experimental::[]

Starts a new trained model deployment.

[[start-trained-model-deployment-request]]
== {api-request-title}

`POST _ml/trained_models/<model_id>/deployment/_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}

`<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}

`inference_threads`::
(Optional, integer)
Sets the number of threads used by the inference process. This generally increases
the inference speed. The inference process is a compute-bound process; any number
greater than the number of available hardware threads on the machine does not increase the
inference speed. If this setting is greater than the number of hardware threads
it will automatically be changed to a value less than the number of hardware threads.
Defaults to 1.

`model_threads`::
(Optional, integer)
The number of threads used when sending inference requests to the model.
Increasing this value generally increases the throughput.
If this setting is greater than the number of hardware threads
it will automatically be changed to a value less than the number of hardware threads.
Defaults to 1.

[NOTE]
=============================================
If the sum of `inference_threads` and `model_threads` is greater than the number of
hardware threads then the number of `inference_threads` will be reduced.
=============================================

`queue_capacity`::
(Optional, integer)
Controls how many inference requests are allowed in the queue at a time. Once the
number of requests exceeds this value, new requests are rejected with a 429 error.
Defaults to 1024.

`timeout`::
(Optional, time)
Controls the amount of time to wait for the model to deploy. Defaults
to 20 seconds.

{'fraction_non_alphanumeric': 0.11621497473587505, 'fraction_numerical': 0.006201194304088195, 'mean_word_length': 5.548872180451128, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5328213', 'n_tokens_mistral': 1247, 'n_tokens_neox': 1180, 'n_words': 476}