检索系统在“召回”阶段为保证效率，返回的结果可能不够精准。排序模型能对召回的文档进行二次精准排序，确保将与用户查询最相关的结果排在最前，有效提升应用准确率。
模型概览
重要gte-rerank模型将于2026年05月30日下线，推荐使用qwen3-rerank模型替代。
新加坡
模型名称 | 最大文档数 | 单条最大输入Token | 请求最大输入Token | 语种支持 | 应用场景 |
|---|---|---|---|---|---|
qwen3-rerank | 500 | 4,000 | 120,000 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种 |
|
北京
模型名称 | 最大文档数 | 单条最大输入Token | 请求最大输入Token | 语种支持 | 应用场景 |
|---|---|---|---|---|---|
qwen3-rerank | 500 | 4,000 | 120,000 | 中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种 |
|
qwen3-vl-rerank | 文本：100 图片：40 视频：4 | 8,000 | 120,000 | 中、英、日、韩、法、德等33种主流语言 |
|
gte-rerank-v2 | 500 | 4,000 | 30,000 | 中、英、日、韩、泰语、西、法、葡、德、印尼语、阿拉伯语等50余语种 |
|
dashscope CLI
通过 dashscope 命令行调用。
export DASHSCOPE_API_KEY="your-api-key"
# 将 {WorkspaceId} 替换为业务空间ID，ap-southeast-1 替换为对应地域（美东: us-east-1, 德国: eu-central-1）
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
dashscope rerank create -m gte-rerank-v2 -q "机器学习" -d "机器学习是AI分支" -d "今天天气真好"
重要SDK Expert 交互式助手可按自然语言完成同样的开发与排障，见
DashScope SDK Expert。完整地域表见 Base URL 总览。
- 单条最大输入Token：每个Query或Document的最大Token数量。单条 Query 或 Document 的输入超过该限制时，API 会返回 HTTP 400 错误，不会截断输入内容。
- 单次请求最大文档数：单次请求允许的最大文档数量。对于 qwen3-vl-rerank 模型，该限制会根据文档类型（文本、图片、视频、混合模态）的不同而有所差异。
- 请求最大输入Token：计算公式为
Query Tokens × Document 数量 + Document Tokens 总和，该值不得超过请求最大输入Token。
输入格式限制：
模型 | 图片 | 视频 |
|---|---|---|
qwen3-vl-rerank | JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI（支持URL或Base64） | MP4, AVI, MOV（仅支持URL） |
前提条件
您需要已获取 API Key并配置API Key到环境变量DASHSCOPE_API_KEY。如果通过SDK调用，还需要安装DashScope SDK。
HTTP调用
调用时请将{WorkspaceId}替换为真实的业务空间ID。
本节介绍 DashScope HTTP 接口。
qwen3-rerank和qwen3.7-text-rerank还支持 OpenAI 兼容接口，参见OpenAI 兼容接口。
请求请求头（Headers）Content-Type 请求内容类型。此参数必须设置为 Authorization 请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。 请求体（Request Body）model 模型名称。支持的模型：qwen3-rerank、gte-rerank-v2、qwen3-vl-rerank。 input 输入内容。
parameters 可选参数。
| qwen3-rerank
qwen3-vl-rerank文本查询 图片查询 gte-rerank-v2 |
响应request_id 请求唯一标识。可用于请求明细溯源和问题排查。 output 任务输出信息。 usage 输出信息统计。 code 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误码。 message 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误码。 | 成功响应失败响应在访问请求出错的情况下，输出的结果中会通过 |
OpenAI 兼容接口
qwen3-rerank和qwen3.7-text-rerank支持通过 OpenAI 兼容接口调用；gte-rerank-v2和qwen3-vl-rerank不支持，调用时会返回model_not_supported错误。
请求地址：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks
与 DashScope HTTP 接口的差异：
- 请求体为扁平结构，
query、documents、top_n、instruct、return_documents与model同级，不嵌套在input和parameters中。 - 排序结果位于响应的
results数组中，每项包含index（文档在请求中的序号）和relevance_score（相关性得分）；return_documents为true时额外返回document.text。
请求示例
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": "什么是重排序模型",
"documents": [
"重排序模型广泛应用于搜索引擎和推荐系统",
"量子计算是计算科学的前沿领域"
],
"top_n": 2,
"return_documents": true
}'
响应示例
{
"object": "list",
"results": [
{
"document": {
"text": "重排序模型广泛应用于搜索引擎和推荐系统"
},
"index": 0,
"relevance_score": 0.8019987834170111
},
{
"document": {
"text": "量子计算是计算科学的前沿领域"
},
"index": 1,
"relevance_score": 0.33869324986016763
}
],
"model": "qwen3-rerank",
"id": "1a295f99-89ff-901f-a57f-9a38a6d963fa",
"usage": {
"total_tokens": 59
}
}
Python 和 Node.js 调用示例请参见重排序。
SDK调用
调用示例
以下示例展示了调用文档排序模型API的代码示例。
SDK 的参数命名与HTTP接口基本一致，参数结构进行了一定封装。比如 HTTP 使用嵌套的
input和parameters结构，但SDK 使用扁平参数。请在开发时注意区分。
import os
import dashscope
# The following 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 the following line with your Model Studio API key: api_key="sk-xxx"
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
def text_rerank():
resp = client.rerank.create(
model="gte-rerank-v2",
query="什么是文本排序模型",
documents=[
"文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序",
"量子计算是计算科学的一个前沿领域",
"预训练语言模型的发展给文本排序模型带来了新的进展"
],
top_n=2,
return_documents=True
)
print(resp)
if __name__ == '__main__':
text_rerank()
以下示例展示了使用qwen3-vl-rerank模型进行多模态排序（以图片作为查询）的代码示例。
import os
import dashscope
import json
# The following 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 the following line with your Model Studio API key: api_key="sk-xxx"
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
def vl_rerank():
resp = client.rerank.create(
model="qwen3-vl-rerank",
query={"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
documents=[
{"text": "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序"},
{"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))
if __name__ == '__main__':
vl_rerank()
输出示例
说明SDK 2.0 返回结构化响应对象，排序结果通过 resp.results 访问（resp.results[i].index / .relevance_score / .document）；请求失败时抛出 DashScopeError 异常。
{
"request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
"output": {
"results": [
{
"index": 0,
"relevance_score": 0.9334521178273196,
"document": {
"text": "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序"
}
},
{
"index": 2,
"relevance_score": 0.34100082626411193,
"document": {
"text": "预训练语言模型的发展给文本排序模型带来了新的进展"
}
}
]
},
"usage": {
"total_tokens": 79
}
}
错误码
如果模型调用失败并返回报错信息，请参见错误码进行解决。