Reranking API-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

A reranking model rescores retrieved documents and promotes the most relevant results, improving search precision when initial retrieval prioritizes speed over accuracy.

NoteWhen 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

First obtain and configure an API key and set the API key as an environment variable. If you need to use an SDK, 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}.cn-beijing.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)

javascript

const OpenAI = require("openai");

const openai = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://{WorkspaceId}.cn-beijing.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();

bash

curl --request POST \
  --url https://{WorkspaceId}.cn-beijing.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 os
import dashscope

# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
  # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
  # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  workspace="{WorkspaceId}",
  region="cn-beijing",
)

resp = client.rerank.create(
  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
)

print(resp)

bash

curl --request POST \
  --url https://{WorkspaceId}.cn-beijing.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",
    "input": {
      "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."
      ]
    },
    "parameters": {
      "top_n": 2,
      "return_documents": true
    }
}'

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 text, images, and videos.

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

Python

import os
import dashscope
import json

# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
  # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
  # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  workspace="{WorkspaceId}",
  region="cn-beijing",
)

resp = client.rerank.create(
  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
)

print(json.dumps(resp.model_dump(), ensure_ascii=False, indent=4))

curl

curl --request POST \
  --url https://{WorkspaceId}.cn-beijing.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 can guide the model to use different ranking strategies. 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, unaffected by wording. For example, "How do I change my password?" matches "What if I forgot my password?" (FAQ scenarios).

Defaults to question answering retrieval if not set.

OpenAI compatible

curl --request POST \
  --url https://{WorkspaceId}.cn-beijing.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 os
import dashscope

# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
  # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
  # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  workspace="{WorkspaceId}",
  region="cn-beijing",
)

resp = client.rerank.create(
  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."
)

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

Model overview

ImportantThe gte-rerank model will be discontinued on May 30, 2026. We recommend using the qwen3-rerank model instead. For details, see the official announcement.

Model	Max documents	Max tokens per document	Max tokens per request	Supported languages	Use cases
qwen3.7-text-rerank	500	30,000	120,000 (recommended)	201 major languages and dialects, including Chinese, English, Spanish, and French	Semantic text search, RAG applications
qwen3-vl-rerank	Text: 100 Image: 40 Video: 4	8,000	120,000	33 languages, including Chinese, English, Japanese, and Korean	Multimodal search result reranking (text, image, video)
qwen3-rerank	500	4,000	120,000	100+ languages, including Chinese, English, Spanish, and French	Semantic text search, RAG applications
gte-rerank-v2	500	4,000	30,000	50+ languages, including Chinese, English, Japanese, Korean, and Thai	Semantic text search, RAG applications

Key terms:

Max tokens per document: Max tokens for a single query or document. If a query or document exceeds this limit, the API returns an HTTP 400 error and does not truncate the input.
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.