通用文本排序模型API使用详情-大模型服务平台百炼(Model Studio)-阿里云帮助中心

检索系统在“召回”阶段为保证效率，返回的结果可能不够精准。排序模型能对召回的文档进行二次精准排序，确保将与用户查询最相关的结果排在最前，有效提升应用准确率。

模型概览

重要gte-rerank模型将于2026年05月30日下线，推荐使用qwen3-rerank模型替代。详情请参见官网公告。

模型名称	最大文档数	单条最大输入Token	请求最大输入Token	语种支持	应用场景
qwen3.7-text-rerank	500	30,000	120,000（建议）	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等201种主流语种与方言	文本语义检索 RAG应用
qwen3-vl-rerank	文本：100 图片：40 视频：4	8,000	120,000	中、英、日、韩、法、德等33种主流语言	图像聚类跨模态搜索图片检索
qwen3-rerank	500	4,000	120,000	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种	文本语义检索 RAG应用
gte-rerank-v2	500	4,000	30,000	中、英、日、韩、泰语、西、法、葡、德、印尼语、阿拉伯语等50余语种	文本语义检索 RAG应用

单条最大输入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调用

不同模型使用不同的API接口：

qwen3-rerank：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks
qwen3.7-text-rerank / qwen3-vl-rerank / gte-rerank-v2：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank

调用时请将{WorkspaceId}替换为真实的业务空间ID。

两种接口的请求体结构和响应格式不同，请参考对应模型的请求示例和响应示例。

请求

请求头（Headers）

Content-Typestring（必选）

请求内容类型。此参数必须设置为application/json。

Authorizationstring（必选）

请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。

请求体（Request Body）

modelstring（必选）

模型名称。支持的模型：qwen3.7-text-rerank、qwen3-rerank、gte-rerank-v2、qwen3-vl-rerank。

inputobject（必选）

输入内容。

当使用 qwen3-rerank 模型时，无需使用 input 对象参数。此时，query 和 documents 参数需与 model 等参数位于同一层级。

属性

querystring | object（必选）

查询内容。最大长度不能超过4,000个Token。

当使用qwen3-vl-rerank模型时，query支持以下两种格式：

字符串格式：直接传入文本字符串，例如"query": "什么是文本排序模型"。
对象格式：传入字典指定模态类型和值，格式为{"模态类型": "输入内容"}。支持text和image两种模态类型。
- 文本查询："query": {"text": "什么是文本排序模型"}
- 图片查询："query": {"image": "图片URL或Base64"}

documentsarray（必选）

待排序的候选文档列表。每个元素是一个字符串。

当使用qwen3-vl-rerank模型时，每个元素是一个字典或者字符串，用于指定内容的类型和值。格式为{"模态类型": "输入字符串或图像、视频url"}。支持text, image, video三种模态类型。

文本：key为text。value为字符串形式。也可不通过dict直接传入字符串。
图片：key为image。value可以是公开可访问的URL，或Base64编码的Data URI。Base64格式为 data:image/{format};base64,{data}，其中 {format} 是图片格式（如 jpeg、png），{data} 是Base64编码字符串。
视频：key为video，value必须是公开可访问的URL。

parametersobject（可选）

可选参数。

当使用 qwen3-rerank 模型时，无需使用 parameters 对象参数。此时，top_n 和 instruct 参数需与 model 等参数位于同一层级。

属性

top_nint（可选）

返回排序后的top_n个文档。默认返回全部文档。如果指定的值大于文档总数，将返回全部文档。

return_documentsbool（可选）

是否在排序结果中返回文档原文。默认值false，以减少网络传输开销。支持的模型：gte-rerank-v2、qwen3-vl-rerank。

instruct string 可选

添加自定义排序任务类型说明，仅在使用 qwen3.7-text-rerank、qwen3-rerank 及qwen3-vl-rerank模型时生效。通过该参数可以指导模型采用不同的排序策略，例如：

问答检索任务（默认）："Given a web search query, retrieve relevant passages that answer the query."
- 侧重点：寻找问题的答案。模型会优先评估文档是否解答了Query中的问题。
- 示例：对于Query“如何预防感冒？”，文档“勤洗手是预防感冒的有效方法”会获得高分；而文档“感冒是一种常见疾病”虽然主题相关，但因未提供答案，得分会显著更低。
语义相似度排序任务："Retrieve semantically similar text."
- 侧重点：判断语义的等价性。模型会评估Query和文档的核心含义是否一致，而不管具体措辞或句式。
- 示例：在FAQ场景中，用户Query“如何修改密码？”与候选问题“忘记密码怎么办？”在语义上高度相似，应获得高分。模型会关注两者是否指向同一个用户意图。

建议使用英文撰写。如不指定该参数，将默认按问答检索任务进行排序。更多任务指令可参考模型仓库中的示例。

fps float 可选

仅qwen3-vl-rerank模型支持此参数。控制视频的帧数，比例越小，实际抽取的帧数越少，范围为 [0,1]。默认值为1.0。

qwen3.7-text-rerank

curl --location '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.7-text-rerank",
    "input": {
        "query": "什么是文本排序模型",
        "documents": [
            "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序",
            "量子计算是计算科学的一个前沿领域",
            "预训练语言模型的发展给文本排序模型带来了新的进展"
        ]
    },
    "parameters": {
        "top_n": 2,
        "instruct": "Given a web search query, retrieve relevant passages that answer the query."
    }
}'

qwen3-rerank

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",
        "documents": [
                "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序",
                "量子计算是计算科学的一个前沿领域",
                "预训练语言模型的发展给文本排序模型带来了新的进展"
        ],
        "query": "什么是文本排序模型",
        "top_n": 2,
        "instruct": "Given a web search query, retrieve relevant passages that answer the query."
}'

qwen3-vl-rerank

文本查询

curl --location '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": "什么是文本排序模型"},
         "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"}
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 2,
        "fps": 1.0
    }
}'

图片查询

curl --location '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": {"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"}
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 2,
        "fps": 1.0
    }
}'

gte-rerank-v2

curl --location '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": "gte-rerank-v2",
    "input":{
         "query": "什么是文本排序模型",
         "documents": [
         "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序",
         "量子计算是计算科学的一个前沿领域",
         "预训练语言模型的发展给文本排序模型带来了新的进展"
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 2
    }
}'

dashscope CLI

通过 dashscope 命令行调用。

export DASHSCOPE_API_KEY="your-api-key"
# 将 {WorkspaceId} 替换为业务空间ID，cn-beijing 替换为对应地域（新加坡: ap-southeast-1, 美东: us-east-1）
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
dashscope rerank create -m gte-rerank-v2 -q "机器学习" -d "机器学习是AI分支" -d "今天天气真好"

重要SDK Expert 交互式助手可按自然语言完成同样的开发与排障，见

DashScope SDK Expert。

完整地域表见 Base URL 总览。

响应

request_idstring

请求唯一标识。可用于请求明细溯源和问题排查。

outputobject

任务输出信息。

当使用 qwen3-rerank 模型时，响应中不包含 output 对象，results 直接位于响应顶层。

属性

resultsarray

排序结果列表。按 relevance_score 从高到低排列。

属性

documentdict

文档原文对象。仅在请求参数 return_documents 为 true 时返回。结构为 {"text": "文档原文"}。

indexint

表示该结果对应于输入 documents 列表中的原始索引位置。

relevance_scoredouble

该文档与查询的语义相关性得分，取值范围为 0.0 到 1.0。分数越高，相关性越强。

说明此分数为当前请求中的相对分数，主要用于对本次请求内的文档排序，不可作为跨请求比较的绝对值。

usageobject

输出信息统计。

属性

prompt_tokensint

仅 qwen3.7-text-rerank 返回。表示本次请求输入内容的 Token 总数。

total_tokensint

本次请求消耗的 Token 总数，用于计量计费和审计。

codestring

请求失败的错误码。请求成功时不会返回此参数，详情请参见错误码。

messagestring

请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误码。

成功响应

qwen3.7-text-rerank

{
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "usage": {
        "prompt_tokens": 79,
        "total_tokens": 79
    },
    "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1"
}

qwen3-rerank

{
    "object": "list",
    "results": [
        {
            "index": 0,
            "relevance_score": 0.9334521178273196
        },
        {
            "index": 2,
            "relevance_score": 0.34100082626411193
        }
    ],
    "model": "qwen3-rerank",
    "id": "85ba5752-1900-47d2-8896-23f99b13f6e1",
    "usage": {
        "total_tokens": 79
    }
}

qwen3-vl-rerank / gte-rerank-v2

{
    "output": {
        "results": [
            {
                "document": {
                    "text": "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序"
                },
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "document": {
                    "text": "预训练语言模型的发展给文本排序模型带来了新的进展"
                },
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    },
    "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1"
}

失败响应

在访问请求出错的情况下，输出的结果中会通过code和message指明出错原因。

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

SDK调用

调用示例

以下示例展示了调用文档排序模型API的代码示例。

SDK 的参数命名与HTTP接口基本一致，参数结构进行了一定封装。比如 HTTP 使用嵌套的 input 和 parameters 结构，但SDK 使用扁平参数。请在开发时注意区分。

import dashscope
from http import HTTPStatus
# 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

def text_rerank():
    resp = dashscope.TextReRank.call(
        model="qwen3.7-text-rerank",
        query="什么是文本排序模型",
        documents=[
            "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序",
            "量子计算是计算科学的一个前沿领域",
            "预训练语言模型的发展给文本排序模型带来了新的进展"
        ],
        top_n=10,
        instruct="Given a web search query, retrieve relevant passages that answer the query."
    )
    if resp.status_code == HTTPStatus.OK:
        print(resp)
    else:
        print(resp)

if __name__ == '__main__':
    text_rerank()

以下示例展示了使用qwen3-vl-rerank模型进行多模态排序（以图片作为查询）的代码示例。

import dashscope
from http import HTTPStatus
import json
# 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

def vl_rerank():
    resp = dashscope.TextReRank.call(
        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
    )
    if resp.status_code == HTTPStatus.OK:
        print(json.dumps(resp, default=str, ensure_ascii=False, indent=4))
    else:
        print(resp)

if __name__ == '__main__':
    vl_rerank()

输出示例

说明SDK对原始HTTP响应进行了封装，成功时会固定返回code和message字段，值为空字符串。

{
    "status_code": 200,
    "request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
    "code": "",
    "message": "",
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "usage": {
        "prompt_tokens": 79,
        "total_tokens": 79
    }
}

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

限流

模型限流触发条件请参考限流。