Reranking API - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

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

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

Python

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)

Node.js

const OpenAI = require("openai");

const openai = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.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

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": "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

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)

curl

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

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

curl

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

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."
}'

DashScope

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="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 codes.

Rate limiting

See Rate limiting.