[role="xpack"]
[[update-trained-model-deployment]]
= Update trained model deployment API

[subs="attributes"]
++++
<titleabbrev>Update trained model deployment</titleabbrev>
++++

Updates certain properties of a trained model deployment.

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

`POST _ml/trained_models/<deployment_id>/deployment/_update`


[[update-trained-model-deployments-prereqs]]
== {api-prereq-title}

Requires the `manage_ml` cluster privilege. This privilege is included in the
`machine_learning_admin` built-in role.

[[update-trained-model-deployment-desc]]
== {api-description-title}

You can update a trained model deployment whose `assignment_state` is `started`.
You can enable adaptive allocations to automatically scale model allocations up
and down based on the actual resource requirement of the processes.
Or you can manually increase or decrease the number of allocations of a model
deployment.


[[update-trained-model-deployments-path-parms]]
== {api-path-parms-title}

`<deployment_id>`::
(Required, string)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=deployment-id]

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

`adaptive_allocations`::
(Optional, object)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=adaptive-allocation]

`enabled`:::
(Optional, Boolean)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=adaptive-allocation-enabled]

`max_number_of_allocations`:::
(Optional, integer)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=adaptive-allocation-max-number]

`min_number_of_allocations`:::
(Optional, integer)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=adaptive-allocation-min-number]

`number_of_allocations`::
(Optional, integer)
The total number of allocations this model is assigned across {ml} nodes.
Increasing this value generally increases the throughput.
If `adaptive_allocations` is enabled, do not set this value, because it's automatically set.


[[update-trained-model-deployment-example]]
== {api-examples-title}

The following example updates the deployment for a
`elastic__distilbert-base-uncased-finetuned-conll03-english` trained model to have 4 allocations:

[source,console]
--------------------------------------------------
POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_update
{
  "number_of_allocations": 4
}
--------------------------------------------------
// TEST[skip:TBD]

The API returns the following results:

[source,console-result]
----
{
    "assignment": {
        "task_parameters": {
            "model_id": "elastic__distilbert-base-uncased-finetuned-conll03-english",
            "model_bytes": 265632637,
            "threads_per_allocation" : 1,
            "number_of_allocations" : 4,
            "queue_capacity" : 1024
        },
        "routing_table": {
            "uckeG3R8TLe2MMNBQ6AGrw": {
                "current_allocations": 1,
                "target_allocations": 4,
                "routing_state": "started",
                "reason": ""
            }
        },
        "assignment_state": "started",
        "start_time": "2022-11-02T11:50:34.766591Z"
    }
}
----

The following example updates the deployment for a
`elastic__distilbert-base-uncased-finetuned-conll03-english` trained model to
enable adaptive allocations with the minimum number of 3 allocations and the
maximum number of 10:

[source,console]
--------------------------------------------------
POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_update
{
  "adaptive_allocations": {
    "enabled": true,
    "min_number_of_allocations": 3,
    "max_number_of_allocations": 10
  }
}
--------------------------------------------------
// TEST[skip:TBD]