Create an ELSER inference endpoint

deprecated

PUT /_inference/{task_type}/{elser_inference_id}

Create an inference endpoint to perform an inference task with the elser service. You can also deploy ELSER by using the Elasticsearch inference integration.

info Your Elasticsearch deployment contains a preconfigured ELSER inference endpoint, you only need to create the enpoint using the API if you want to customize the settings.

The API request will automatically download and deploy the ELSER model if it isn't already downloaded.

info You might see a 502 bad gateway error in the response when using the Kibana Console. This error usually just reflects a timeout, while the model downloads in the background. You can check the download progress in the Machine Learning UI. If using the Python client, you can set the timeout parameter to a higher value.

After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Required authorization

Cluster privileges: manage_inference

Path Parameters

Query Parameters

timeout string Duration · default: 30s: Specifies the amount of time to wait for the inference endpoint to be created.

Request

Response

application/json

Examples

Run PUT _inference/sparse_embedding/my-elser-model to create an inference endpoint that performs a sparse_embedding task. The request will automatically download the ELSER model if it isn't already downloaded and then deploy the model.

Request Console 1 / 8 languages

Console Kibana Dev Tools

PUT _inference/sparse_embedding/my-elser-model
{
    "service": "elser",
    "service_settings": {
        "num_allocations": 1,
        "num_threads": 1
    }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.inference.put({
  task_type: "sparse_embedding",
  inference_id: "my-elser-model",
  inference_config: {
    service: "elser",
    service_settings: {
      num_allocations: 1,
      num_threads: 1,
    },
  },
});

Python Elasticsearch Python Client

resp = client.inference.put(
    task_type="sparse_embedding",
    inference_id="my-elser-model",
    inference_config={
        "service": "elser",
        "service_settings": {
            "num_allocations": 1,
            "num_threads": 1
        }
    },
)

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_inference/sparse_embedding/my-elser-model" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "elser",
    "service_settings": {
      "num_allocations": 1,
      "num_threads": 1
    }
  }'

Java Elasticsearch Java Client

client.inference().put(p -> p
    .inferenceId("my-elser-model")
    .taskType(TaskType.SparseEmbedding)
    .inferenceConfig(i -> i
        .service("elser")
        .serviceSettings(JsonData.fromJson("{\"num_allocations\":1,\"num_threads\":1}"))
    )
);

C# Elasticsearch .NET Client

var response = await client.Inference
    .PutAsync(new PutInferenceRequest()
    {
        InferenceId = "my-elser-model",
        TaskType = TaskType.SparseEmbedding,
        InferenceConfig = new()
        {
            Service = "elser",
            ServiceSettings = JsonSerializer.Deserialize<JsonElement>("""
            {
              "num_allocations": 1,
              "num_threads": 1
            }
            """)
        }
    });

PHP Elasticsearch PHP Client

$resp = $client->inference()->put([
    "task_type" => "sparse_embedding",
    "inference_id" => "my-elser-model",
    "body" => [
        "service" => "elser",
        "service_settings" => [
            "num_allocations" => 1,
            "num_threads" => 1,
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.inference.put(
  task_type: "sparse_embedding",
  inference_id: "my-elser-model",
  body: {
    "service": "elser",
    "service_settings": {
      "num_allocations": 1,
      "num_threads": 1
    }
  }
)

Response

{
  "inference_id": "my-elser-model",
  "task_type": "sparse_embedding",
  "service": "elser",
  "service_settings": {
    "num_allocations": 1,
    "num_threads": 1
  },
  "task_settings": {}
}

Run PUT _inference/sparse_embedding/my-elser-model to create an inference endpoint that performs a sparse_embedding task with adaptive allocations. When adaptive allocations are enabled, the number of allocations of the model is set automatically based on the current load.

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT _inference/sparse_embedding/my-elser-model
{
    "service": "elser",
    "service_settings": {
        "adaptive_allocations": {
            "enabled": true,
            "min_number_of_allocations": 3,
            "max_number_of_allocations": 10
        },
        "num_threads": 1
    }
}

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_inference/sparse_embedding/my-elser-model" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "elser",
    "service_settings": {
        "adaptive_allocations": {
            "enabled": true,
            "min_number_of_allocations": 3,
            "max_number_of_allocations": 10
        },
        "num_threads": 1
    }
}'

Response

{
  "inference_id": "my-elser-model",
  "task_type": "sparse_embedding",
  "service": "elser",
  "service_settings": {
    "num_allocations": 1,
    "num_threads": 1
  },
  "task_settings": {}
}

Required authorization

Path Parameters { task_type , elser_inference_id , }

Query Parameters

Request { chunking_settings , service , service_settings , }

Response

Path Parameters

Request