IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Infer trained model deployment API Stop trained model deployment API »
Elastic Docs ›Elasticsearch Guide [8.2] ›REST APIs ›Machine learning trained model APIs

Start trained model deployment API

edit

Start trained model deployment API

edit

Starts a new trained model deployment.

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Request

edit

POST _ml/trained_models/<model_id>/deployment/_start

Prerequisites

edit

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

Description

edit

Currently only pytorch models are supported for deployment. When deployed, the model attempts allocation to every machine learning node. Once deployed the model can be used by the Inference processor in an ingest pipeline or directly in the Infer trained model deployment API.

Path parameters

edit
<model_id>
(Required, string) The unique identifier of the trained model.

Query parameters

edit
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.

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. Every machine learning node in the cluster where the model can be allocated has a queue of this size; when the number of requests exceeds the total 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.
wait_for
(Optional, string) 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.

Examples

edit

The following example starts a new deployment for a elastic__distilbert-base-uncased-finetuned-conll03-english trained model:

POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_start?wait_for=started&timeout=1m

The API returns the following results:

{
    "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",
        "start_time": "2021-11-02T11:50:34.766591Z"
    }
}
« Infer trained model deployment API Stop trained model deployment API »