Improve Search Relevance with the Re-rank API - OpenSearch - Alibaba Cloud - OpenSearch

Available models

Service name	Service ID	Description	QPS limit
BGE reranking model	`ops-bge-reranker-larger`	Ranks documents by query-document relevance using the BGE model. Supports Chinese and English. Maximum input: 512 tokens (query + document combined).	20 (Alibaba Cloud account and RAM users combined). To request a higher limit, submit a ticket.
OpenSearch text reranking model-001	`ops-text-reranker-001`	Ranks documents by semantic relevance, trained on multiple industry datasets. Supports Chinese and English. Maximum input: 512 tokens (query + document combined).	—
Qwen3 ranking service-0.6B	`ops-qwen3-reranker-0.6b`	Qwen3 series reranking model with 0.6B parameters. Supports 100+ languages. Maximum input: 32k tokens (query + document combined).	—

Prerequisites

Before you begin, ensure that you have:

An API key for authentication. For details on how to obtain one, refer to the authentication documentation for AI Search Open Platform.
A service endpoint (Internet or virtual private cloud (VPC)). See Get service registration address

Request syntax

POST {host}/v3/openapi/workspaces/{workspace_name}/ranker/{service_id}

Path parameters:

Parameter	Description
`host`	The service endpoint. Supports Internet and VPC access. See Get service registration address.
`workspace_name`	The name of the workspace. Example: `default`.
`service_id`	The ID of the reranking model to use. Example: `ops-bge-reranker-larger`.

Limits:

Maximum request body size: 8 MB.

Request parameters

Header parameters

Parameter	Type	Required	Description	Example
`Content-Type`	String	Yes	The request content type. Set to `application/json`.	`application/json`
`Authorization`	String	Yes	The API key used for authentication. Format: `Bearer <your-api-key>`.	`Bearer OS-d1**2a`

Body parameters

Parameter	Type	Required	Description	Example
`query`	String	Yes	The search query to score documents against.	`What are the fun places in Shanghai?`
`docs`	List<String>	Yes	The list of candidate documents to rerank.	`["There are many fun places in Shanghai", "There are many fun places in Beijing"]`

Response parameters

Parameter	Type	Description	Example
`request_id`	String	The request ID.	`A5B25952-4406-45BF-99EC-E8020246****`
`latency`	Float/Int	The request processing time, in milliseconds.	`10`
`usage.doc_count`	Int	The number of documents scored in this request.	`2`
`result.scores`	List<score>	The reranked documents, ordered from highest to lowest relevance score.	`[{"index":1,"score":0.99},{"index":2,"score":0.05}]`
`result.scores[].index`	Int	The zero-based position of the document in the input `docs` array.	`1`
`result.scores[].score`	Float	The relevance score. Higher values indicate greater relevance to the query.	`0.99`

Examples

Request

curl -X POST \
  "http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/ranker/ops-bge-reranker-larger" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "query": "opensearch documentation",
    "docs": [
      "what is opensearch",
      "what is LLM-based conversational search edition",
      "What is the advantage of LLM-based conversational search edition"
    ]
  }'

Response

Success:

{
  "request_id": "24B004E0-ADEF-****-879B-F28359BFAD1D",
  "latency": 19,
  "usage": {
    "doc_count": 3
  },
  "result": {
    "scores": [
      { "index": 0, "score": 0.45026873385713345 },
      { "index": 1, "score": 1.1412238544346029E-4 },
      { "index": 2, "score": 8.029784284533197E-5 }
    ]
  }
}

Error:

When a request fails, the response includes code and message fields describing the error.

{
  "request_id": "45C8C9E5-6BCB-****-80D3-E298F788512B",
  "latency": 0,
  "code": "InvalidParameter",
  "message": "JSON parse error: Unexpected character ..."
}

What's next

Status codes