Skip to main content
Embedding

Reranking

Improve search accuracy

Retrieval systems prioritize speed, so results may lack precision. Reranking models re-score retrieved documents to place the most relevant results at the top, significantly improving search accuracy.
The gte-rerank model was discontinued on May 30, 2026. Switch to qwen3-rerank for text reranking, or to qwen3-vl-rerank (China North 2 (Beijing) only) for multimodal reranking.
When reranking helps most: Reranking gives the biggest accuracy boost when your initial retrieval returns 20-100+ candidates with mixed relevance. If your retrieval already returns highly relevant results (such as exact keyword match), reranking adds less value. A typical RAG pipeline: retrieve 50-100 candidates with embeddings, rerank to top 5-10, then pass those to the LLM.

Prerequisites

Get an API key and set it as an environment variable. To use the SDK, install it.

Rerank documents

Pass a query and a list of candidate documents to the API. The model returns the documents ranked by relevance.
  • OpenAI compatible
  • DashScope
import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
  # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
  base_url="https://ap-southeast-1.maas.qwencloudapi.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 rank candidate texts by relevance",
      "Quantum computing is a frontier field of computational science",
      "The development of pre-trained language models has brought new advances to reranking models"
    ],
    "top_n": 2
  },
  cast_to=object
)

print(results)

Core features

Use instructions to improve ranking (instruct)

The instruct parameter guides the model to use different ranking strategies. Write instructions in English.
  • QA retrieval (default): "Given a web search query, retrieve relevant passages that answer the query."
    • Focus: finding answers. For the query "How to prevent colds?", "Washing hands frequently prevents colds" scores higher than "The common cold is a widespread illness" (topically related but doesn't answer the question).
  • Semantic similarity: "Retrieve semantically similar text."
    • Focus: semantic equivalence regardless of wording. Example: "How to change my password?" matches "What if I forgot my password?" in an FAQ scenario.
If unset, the model defaults to QA retrieval. For more task instruction examples, see the model repository.
  • OpenAI compatible
  • DashScope
curl
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl --request POST \
  --url https://ap-southeast-1.maas.qwencloudapi.com/compatible-api/v1/reranks \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "qwen3-rerank",
    "query": "How to change my password?",
    "documents": [
      "Click 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 top results (top_n)

Use top_n to return only the highest-ranked documents. If omitted, all documents are returned sorted by relevance. If top_n exceeds the total document count, all documents are returned.

Multimodal reranking (qwen3-vl-rerank)

qwen3-vl-rerank ranks a mix of text, images, and videos. The query can be text or an image, and documents can combine any of these modalities. Supported regions: China North 2 (Beijing) only. Use https://cn-beijing.maas.qwencloudapi.com and an API key created in that region.
Multimodal reranking is available only through the DashScope SDK or the DashScope HTTP endpoint, not the OpenAI-compatible endpoint.
import os
import dashscope
import json

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = dashscope.Client(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://cn-beijing.maas.qwencloudapi.com/api/v1",
)

resp = client.rerank.create(
  model="qwen3-vl-rerank",
  query={"text": "What is a reranking model"},
  documents=[
    {"text": "Reranking models are widely used in search engines and recommendation 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))
For media documents, the fps parameter sets the number of frames sampled per second of video.

Supported models

ModelRegionsMax documentsMax tokens per documentMax tokens per requestLanguagesUse cases
qwen3-rerankSingapore, China North 2 (Beijing)5004,000120,000100+ languages: Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, Russian, etc.Semantic text search, RAG applications
qwen3-vl-rerankChina North 2 (Beijing)Text: 100; image: 40; video: 48,000120,00033 languages, including Chinese, English, Japanese, and KoreanMultimodal search result reranking (text, image, video)
No reranking model is offered in Germany (Frankfurt), China (Hong Kong), Japan (Tokyo), or US (Virginia).
Key terms:
  • Max tokens per document: Maximum token count per 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 number of documents per request. For qwen3-vl-rerank, the limit depends on the document modalities in the request.
  • Max tokens per request: Calculated as Query Tokens x Document Count + Total Document Tokens. This value must not exceed the per-request limit.

API reference

Error codes

If a call fails, see Error messages.

Rate limits

See Rate limits.
Reranking - QwenCloud