Copy

When reranking adds the most value: Reranking works best when initial retrieval returns 20–100+ candidates with mixed relevance, and adds little when results are already precise (such as exact keyword matches). A typical RAG workflow retrieves 50–100 candidates with an embedding model, then reranks to select the top 5–10 for a large language model.

Prerequisites

Obtain 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
DashScope

import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.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)

import dashscope
from http import HTTPStatus

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.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)

Multimodal reranking (qwen3-vl-rerank)

The qwen3-vl-rerank model reranks text, images, and videos. The query can be text or an image, and documents can contain any combination of these modalities.

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

Python

import dashscope
from http import HTTPStatus
import json

# China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The configuration varies by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

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))

Core features

Reranking with instructions (instruct)

The instruct parameter sets the ranking strategy. Write instructions in English.

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

Defaults to question answering retrieval if not set.

OpenAI compatible

curl --request POST \
  --url https://{WorkspaceId}.ap-southeast-1.maas.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."
}'

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 input document count, all documents are returned.

Model overview

The gte-rerank model was discontinued on May 30, 2026. Switch to qwen3-rerank.

Singapore
Beijing

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

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

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. Excess content is truncated, which may reduce accuracy.
Max documents: Maximum documents per request. For qwen3-vl-rerank, this limit varies by document type (text, image, video, or mixed).
Max tokens per request: Calculated as Query Tokens × Number of Documents + Total Document Tokens.

API reference

Rerank API reference.

Error codes

If a call fails, see Error codes.

Rate limiting

Rate limiting.

​Prerequisites

​Rerank documents

​Text reranking (qwen3-rerank)

​Multimodal reranking (qwen3-vl-rerank)

​Core features

​Reranking with instructions (instruct)

​Return the top N results (top_n)

​Model overview

​API reference

​Error codes

​Rate limiting

Prerequisites

Rerank documents

Text reranking (qwen3-rerank)

Multimodal reranking (qwen3-vl-rerank)

Core features

Reranking with instructions (instruct)

Return the top N results (top_n)

Model overview

API reference

Error codes

Rate limiting