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.
Get an API key and set it as an environment variable. To use the SDK, install it.
Pass a query and a list of candidate documents to the API. The model returns the documents ranked by relevance.
The
Use
For media documents, the
Key terms:
If a call fails, see Error messages.
See Rate limits.
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
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.
- OpenAI compatible
- DashScope
curl
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.
fps parameter sets the number of frames sampled per second of video.
Supported models
| Model | Regions | Max documents | Max tokens per document | Max tokens per request | Languages | Use cases |
|---|---|---|---|---|---|---|
| qwen3-rerank | Singapore, China North 2 (Beijing) | 500 | 4,000 | 120,000 | 100+ languages: Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, Russian, etc. | Semantic text search, RAG applications |
| qwen3-vl-rerank | China North 2 (Beijing) | 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) |
No reranking model is offered in Germany (Frankfurt), China (Hong Kong), Japan (Tokyo), or US (Virginia).
- 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.