Rerank

Retrieval systems prioritize speed, which can sometimes compromise the precision of search results. A reranking model improves search accuracy by scoring an initial set of retrieved documents and promoting the most relevant results to the top. Note

When reranking adds the most value: Reranking is most effective when the initial retrieval returns a broad set of 20 to 100+ candidate results with mixed relevance. It is less valuable when the initial search already yields highly relevant results, such as exact keyword matching. A typical Retrieval-Augmented Generation (RAG) workflow first retrieves 50--100 candidate results with an embedding model, then uses reranking to select the top 5--10 results to pass to a large language model.

Prerequisites

Create an API key, set it as an environment variable, and install the SDK.

Rerank documents

Pass a query and a list of candidate documents to the API. The model returns the documents sorted by relevance.

Text reranking (qwen3-rerank)

OpenAI compatible

Python

HELPCODEESCAPE-python
import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope-intl.aliyuncs.com/compatible-api/v1",
)

results = client.post(
  "/reranks",
  body={
    "model": "qwen3-rerank",
    "query": "What is a reranking model?",
    "documents": [
      "Reranking models are widely used in search engines and recommendation systems to sort candidate texts by relevance.",
      "Quantum computing is a cutting-edge field in computer science.",
      "The development of pretrained language models has led to new advancements in reranking models."
    ],
    "top_n": 2
  },
  cast_to=object
)

print(results)

Node.js

HELPCODEESCAPE-nodejs
const OpenAI = require("openai");

const openai = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope-intl.aliyuncs.com/compatible-api/v1",
});

async function rerank() {
  const results = await openai.post("/reranks", {
    body: {
      model: "qwen3-rerank",
      query: "What is a reranking model?",
      documents: [
        "Reranking models are widely used in search engines and recommendation systems to sort candidate texts by relevance.",
        "Quantum computing is a cutting-edge field in computer science.",
        "The development of pretrained language models has led to new advancements in reranking models.",
      ],
      top_n: 2,
    },
  });

  console.log(JSON.stringify(results, null, 2));
}

rerank();

curl

HELPCODEESCAPE-curl
curl --request POST \
  --url https://dashscope-intl.aliyuncs.com/compatible-api/v1/reranks \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "qwen3-rerank",
    "query": "What is a reranking model?",
    "documents": [
      "Reranking models are widely used in search engines and recommendation systems to sort candidate texts by relevance.",
      "Quantum computing is a cutting-edge field in computer science.",
      "The development of pretrained language models has led to new advancements in reranking models."
    ],
    "top_n": 2
}'

DashScope

Python

HELPCODEESCAPE-python
import dashscope
from http import HTTPStatus

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

resp = dashscope.TextReRank.call(
  model="qwen3-rerank",
  query="What is a reranking model?",
  documents=[
    "Reranking models are widely used in search engines and recommendation systems to sort candidate texts by relevance.",
    "Quantum computing is a cutting-edge field in computer science.",
    "The development of pretrained language models has led to new advancements in reranking models."
  ],
  top_n=2,
  return_documents=True
)

if resp.status_code == HTTPStatus.OK:
  print(resp)

curl

HELPCODEESCAPE-curl
curl --request POST \
  --url https://dashscope-intl.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "qwen3-rerank",
    "query": "What is a reranking model?",
    "documents": [
      "Reranking models are widely used in search engines and recommendation systems to sort candidate texts by relevance.",
      "Quantum computing is a cutting-edge field in computer science.",
      "The development of pretrained language models has led to new advancements in reranking models."
    ],
    "top_n": 2
}'

Multimodal reranking (qwen3-vl-rerank)

The qwen3-vl-rerank model supports multimodal reranking of text, images, and videos. The query can be text or an image, and the documents can contain text, images, and videos. Note

Multimodal reranking is available only through the DashScope SDK or API, not the OpenAI-compatible endpoint.

Python

HELPCODEESCAPE-python
import dashscope
from http import HTTPStatus
import json

resp = dashscope.TextReRank.call(
  model="qwen3-vl-rerank",
  query={"text": "What is a text reranking model"},
  documents=[
    {"text": "Text reranking models are widely used in search engines and recommender systems."},
    {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
    {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"}
  ],
  top_n=2,
  return_documents=True
)

if resp.status_code == HTTPStatus.OK:
  print(json.dumps(resp, default=str, ensure_ascii=False, indent=4))

curl

HELPCODEESCAPE-curl
curl --request POST \
  --url https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "qwen3-vl-rerank",
    "input": {
      "query": {"text": "What is a text reranking model"},
      "documents": [
        {"text": "Text reranking models are widely used in search engines and recommender systems."},
        {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
        {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"}
      ]
    },
    "parameters": {
      "return_documents": true,
      "top_n": 2,
      "fps": 1.0
    }
}'

Core features

Reranking with instructions (instruct)

The instruct parameter guides the model to use different sorting strategies. Write the instructions in English.

Question answering retrieval (default) : "Given a web search query, retrieve relevant passages that answer the query."
Focuses on finding answers. For the query "How to prevent a cold?", the document "Washing hands frequently can prevent colds" receives a higher score than "A cold is a common illness," which is topically relevant but does not answer the question.
Semantic similarity : "Retrieve semantically similar text."
Focuses on semantic equivalence and is robust to wording changes. For example, "How do I change my password?" matches "What if I forgot my password?", which is useful for FAQ scenarios.

If this parameter is not set, the model defaults to the question answering retrieval strategy.

OpenAI compatible

HELPCODEESCAPE-curl
curl --request POST \
  --url https://dashscope-intl.aliyuncs.com/compatible-api/v1/reranks \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "qwen3-rerank",
    "query": "How do I change my password?",
    "documents": [
      "Go to Settings > Security > Change Password to update your credentials.",
      "What if I forgot my password?",
      "Our platform supports two-factor authentication."
    ],
    "instruct": "Retrieve semantically similar text."
}'

DashScope

HELPCODEESCAPE-python
import dashscope
from http import HTTPStatus

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

resp = dashscope.TextReRank.call(
  model="qwen3-rerank",
  query="How do I change my password?",
  documents=[
    "Go to Settings > Security > Change Password to update your credentials.",
    "What if I forgot my password?",
    "Our platform supports two-factor authentication."
  ],
  instruct="Retrieve semantically similar text."
)

if resp.status_code == HTTPStatus.OK:
  print(resp)

Return the top N results (top_n)

Use top_n to return only the highest-ranked documents. If top_n is not set, all documents are returned, sorted by relevance. If top_n exceeds the number of documents in the input, all documents are returned.

Model overview

Important

The gte-rerank model will be discontinued on May 30, 2026. We recommend switching to qwen3-rerank.

Singapore

Model	Max documents	Max tokens per document	Max tokens per request	Supported languages	Use cases
qwen3-rerank	500	4,000	120,000	100+ languages	Semantic text search, RAG applications

Beijing

Model	Max documents	Max tokens per document	Max tokens per request	Supported languages	Use cases
qwen3-vl-rerank	Text: 100 Image: 40 Video: 4	8,000	120,000	33 languages	Multimodal search result reranking (text, image, video)
gte-rerank-v2	500	4,000	30,000	50+ languages	Semantic text search, RAG applications

Key terms:

Max tokens per document: Max tokens for a single query or document. Content beyond this limit is truncated, which may affect accuracy.
Max documents: The maximum number of documents per request. For qwen3-vl-rerank, this limit varies by document type (text, image, video, or mixed modalities).
Max tokens per request : Calculated as Query Tokens × Number of Documents + Total Document Tokens.

API reference

See Rerank API reference.

Error codes

If a call fails, see Error messages.

Rate limiting

See Rate limiting.

Rerank ​

Prerequisites ​

Rerank documents ​

Text reranking (qwen3-rerank) ​

OpenAI compatible ​

DashScope ​

Multimodal reranking (qwen3-vl-rerank) ​

Python ​

curl ​

Core features ​

Reranking with instructions (instruct) ​

OpenAI compatible ​

DashScope ​

Return the top N results (top_n) ​

Model overview ​

Singapore ​

Beijing ​

API reference ​

Error codes ​

Rate limiting ​

Rerank

Prerequisites

Rerank documents

Text reranking (qwen3-rerank)

OpenAI compatible

DashScope

Multimodal reranking (qwen3-vl-rerank)

Python

curl

Core features

Reranking with instructions (instruct)

OpenAI compatible

DashScope

Return the top N results (top_n)

Model overview

Singapore

Beijing

API reference

Error codes

Rate limiting