Perform reranking inference on the service

POST /_inference/rerank/{inference_id}

Auth

Required privileges

Cluster privileges monitor_inference

Path parameters

inference_id string required: The unique identifier for the inference endpoint.

Query parameters

timeout string · default: 30s: The amount of time to wait for the inference request to complete.

Request body

query union oneOf required

Query input. The query can be specified as a single string, or as an object. The object form additionally allows specifying non-text inputs, such as images.

Note

Only the elastic service currently supports non-text queries for the rerank task. For all other services, the query must be a string.

string example:

"query": "some query text"

object example:

		"query": {
  "type": "image",
  "format": "base64",
  "value": "data:image/jpeg;base64,..."
}
		
	

object example using the url format (available in Elasticsearch 9.6.0 and later):

		"query": {
  "type": "image",
  "format": "url",
  "value": "https://example.com/image.jpg"
}
		
	

One of:

input union oneOf required

The documents to rank. The input can be specified as a single string or an array of strings, or as an object or an array of objects. The object form additionally allows specifying non-text inputs, such as images.

Note

Only the elastic service currently supports non-text inputs for the rerank task. For all other services, the input must be a string or an array of strings.

string example:

"input": "some document text"

string array example:

"input": ["some document text", "some more document text"]

object example:

		"input": {
  "type": "image",
  "format": "base64",
  "value": "data:image/jpeg;base64,..."
}
		
	

object array example:

		"input": [
  {
    "type": "text",
    "format": "text",
    "value": "some document text"
  },
  {
    "type": "image",
    "format": "base64",
    "value": "data:image/jpeg;base64,..."
  }
]
		
	

object array example using the url format (available in Elasticsearch 9.6.0 and later):

		"input": [
  {
    "type": "image",
    "format": "url",
    "value": "https://example.com/image.jpg"
  }
]
		
	

One of:

Allows specifying text-only documents to rank for the rerank task.

return_documents boolean

Include the document text in the response.

top_n number

Limit the response to the top N documents.

task_settings object

Task settings for the individual inference request. These settings are specific to the task type you specified and override the task settings specified when initializing the service.

Response

application/json

rerank object[] required

Examples

Request Console 1 / 8 languages

Run POST _inference/rerank/cohere_rerank to perform reranking on the example input.

Console Kibana Dev Tools

POST _inference/rerank/cohere_rerank
{
  "input": ["luke", "like", "leia", "chewy","r2d2", "star", "wars"],
  "query": "star wars main character"
}

JavaScript Elasticsearch JavaScript Client

const response = await client.inference.rerank({
  inference_id: "cohere_rerank",
  input: ["luke", "like", "leia", "chewy", "r2d2", "star", "wars"],
  query: "star wars main character",
});

Python Elasticsearch Python Client

resp = client.inference.rerank(
    inference_id="cohere_rerank",
    input=[
        "luke",
        "like",
        "leia",
        "chewy",
        "r2d2",
        "star",
        "wars"
    ],
    query="star wars main character",
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_inference/rerank/cohere_rerank" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      "luke",
      "like",
      "leia",
      "chewy",
      "r2d2",
      "star",
      "wars"
    ],
    "query": "star wars main character"
  }'

Java Elasticsearch Java Client

client.inference().rerank(r -> r
    .inferenceId("cohere_rerank")
    .input(i -> i
        .string(List.of("luke","like","leia","chewy","r2d2","star","wars"))
    )
    .query(q -> q
        .string("star wars main character")
    )
);

C# Elasticsearch .NET Client

var response = await client.Inference
    .RerankAsync(inferenceId: "cohere_rerank", d1 => d1
        .Input(new string[] { "luke", "like", "leia", "chewy", "r2d2", "star", "wars" })
        .Query("star wars main character")
    );

PHP Elasticsearch PHP Client

$resp = $client->inference()->rerank([
    "inference_id" => "cohere_rerank",
    "body" => [
        "input" => array(
            "luke",
            "like",
            "leia",
            "chewy",
            "r2d2",
            "star",
            "wars",
        ),
        "query" => "star wars main character",
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.inference.rerank(
  inference_id: "cohere_rerank",
  body: {
    "input": [
      "luke",
      "like",
      "leia",
      "chewy",
      "r2d2",
      "star",
      "wars"
    ],
    "query": "star wars main character"
  }
)

Response

A successful response from POST _inference/rerank/bge-reranker-base-mkn.

{
  "rerank": [
    {
      "index": 6,
      "relevance_score": 0.50955844,
      "text": "wars"
    },
    {
      "index": 5,
      "relevance_score": 0.084341794,
      "text": "star"
    },
    {
      "index": 3,
      "relevance_score": 0.004520818,
      "text": "chewy"
    }
  ]
}

Request Console 1 / 6 languages

Run POST _inference/rerank/my-multimodal-rerank-endpoint to rank text documents against an image query referenced by URL. The url format is available in Elasticsearch 9.6.0 and later.

Console Kibana Dev Tools

POST _inference/rerank/my-multimodal-rerank-endpoint
{
  "query": {
    "type": "image",
    "format": "url",
    "value": "https://example.com/image.jpg"
  },
  "input": ["some document text", "some more document text"],
  "top_n": 2
}

JavaScript Elasticsearch JavaScript Client

const response = await client.inference.rerank({
  inference_id: "my-multimodal-rerank-endpoint",
  query: {
    type: "image",
    format: "url",
    value: "https://example.com/image.jpg",
  },
  input: ["some document text", "some more document text"],
  top_n: 2,
});

Python Elasticsearch Python Client

resp = client.inference.rerank(
    inference_id="my-multimodal-rerank-endpoint",
    query={
        "type": "image",
        "format": "url",
        "value": "https://example.com/image.jpg"
    },
    input=[
        "some document text",
        "some more document text"
    ],
    top_n=2,
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_inference/rerank/my-multimodal-rerank-endpoint" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "type": "image",
      "format": "url",
      "value": "https://example.com/image.jpg"
    },
    "input": [
      "some document text",
      "some more document text"
    ],
    "top_n": 2
  }'

PHP Elasticsearch PHP Client

$resp = $client->inference()->rerank([
    "inference_id" => "my-multimodal-rerank-endpoint",
    "body" => [
        "query" => [
            "type" => "image",
            "format" => "url",
            "value" => "https://example.com/image.jpg",
        ],
        "input" => array(
            "some document text",
            "some more document text",
        ),
        "top_n" => 2,
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.inference.rerank(
  inference_id: "my-multimodal-rerank-endpoint",
  body: {
    "query": {
      "type": "image",
      "format": "url",
      "value": "https://example.com/image.jpg"
    },
    "input": [
      "some document text",
      "some more document text"
    ],
    "top_n": 2
  }
)

Response

No example

Request Console 1 / 6 languages

Run POST _inference/rerank/my-multimodal-rerank-endpoint to rank image documents referenced by URL against a text query. The url format is available in Elasticsearch 9.6.0 and later.

Console Kibana Dev Tools

POST _inference/rerank/my-multimodal-rerank-endpoint
{
  "query": "a photo of a cat",
  "input": [
    {
      "type": "image",
      "format": "url",
      "value": "https://example.com/image1.jpg"
    },
    {
      "type": "image",
      "format": "url",
      "value": "https://example.com/image2.jpg"
    }
  ],
  "top_n": 2
}

JavaScript Elasticsearch JavaScript Client

const response = await client.inference.rerank({
  inference_id: "my-multimodal-rerank-endpoint",
  query: "a photo of a cat",
  input: [
    {
      type: "image",
      format: "url",
      value: "https://example.com/image1.jpg",
    },
    {
      type: "image",
      format: "url",
      value: "https://example.com/image2.jpg",
    },
  ],
  top_n: 2,
});

Python Elasticsearch Python Client

resp = client.inference.rerank(
    inference_id="my-multimodal-rerank-endpoint",
    query="a photo of a cat",
    input=[
        {
            "type": "image",
            "format": "url",
            "value": "https://example.com/image1.jpg"
        },
        {
            "type": "image",
            "format": "url",
            "value": "https://example.com/image2.jpg"
        }
    ],
    top_n=2,
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_inference/rerank/my-multimodal-rerank-endpoint" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "a photo of a cat",
    "input": [
      {
        "type": "image",
        "format": "url",
        "value": "https://example.com/image1.jpg"
      },
      {
        "type": "image",
        "format": "url",
        "value": "https://example.com/image2.jpg"
      }
    ],
    "top_n": 2
  }'

PHP Elasticsearch PHP Client

$resp = $client->inference()->rerank([
    "inference_id" => "my-multimodal-rerank-endpoint",
    "body" => [
        "query" => "a photo of a cat",
        "input" => array(
            [
                "type" => "image",
                "format" => "url",
                "value" => "https://example.com/image1.jpg",
            ],
            [
                "type" => "image",
                "format" => "url",
                "value" => "https://example.com/image2.jpg",
            ],
        ),
        "top_n" => 2,
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.inference.rerank(
  inference_id: "my-multimodal-rerank-endpoint",
  body: {
    "query": "a photo of a cat",
    "input": [
      {
        "type": "image",
        "format": "url",
        "value": "https://example.com/image1.jpg"
      },
      {
        "type": "image",
        "format": "url",
        "value": "https://example.com/image2.jpg"
      }
    ],
    "top_n": 2
  }
)

Response

No example