AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 大模型服务平台百炼 API参考（模型） 更多模型 文本排序

文本排序

更新时间：
产品详情
我的收藏

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

模型概览

模型名称

最大Document数量

单条最大输入Token

请求最大输入Token

语种支持

单价（每千输入Token）

免费额度

应用场景

qwen3-rerank

500

4,000

30,000

中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种

0.0005元

100万Token

有效期：百炼开通后90天内

  • 文本语义检索

  • RAG应用

gte-rerank-v2

中、英、日、韩、泰语、西、法、葡、德、印尼语、阿拉伯语等50余语种

0.0008元

  • 单条最大输入Token：每个Query或Document的最大Token数量为4,000。输入内容超长将被截断。API仅基于截断后的内容计算，这可能导致排序结果不准确。

  • 最大Document数量：每次请求中Document的最大数量为500。

  • 请求最大输入Token：每次请求中所有Query和Document的Token总数不得超过30,000。

前提条件

您需要已获取 API Key并配置API Key到环境变量DASHSCOPE_API_KEY。如果通过SDK调用，还需要安装DashScope SDK。

HTTP调用

POST https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank

请求

文本排序

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

请求头（Headers）

Content-Type string （必选）

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

Authorization string（必选）

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

请求体（Request Body）

model string（必选）

模型名称。当前接口必须设置为gte-rerank-v2。

input object （必选）

输入内容。

属性

query string（必选）

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

documents array（必选）

待排序的候选文档列表。每个元素是一个字符串。最多包含500个文档，每个文档长度不超过4,000个Token。

instruct string 可选

添加自定义排序任务类型说明，仅在使用 qwen3-rerank 模型时生效。建议使用英文撰写。

parameters object （可选）

可选参数。

属性

top_n int（可选）

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

return_documents bool（可选）

是否在排序结果中返回文档原文。默认值false，以减少网络传输开销。

响应

成功响应

{
    "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"
}

request_id string

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

output object

任务输出信息。

属性

results array

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

属性

document dict

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

index int

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

relevance_score double

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

说明

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

usage object

输出信息统计。

属性

total_tokens int

本次请求消耗的总 Token 数量。

code string

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

message string

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

SDK调用

调用示例

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

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

def text_rerank():
    resp = dashscope.TextReRank.call(
        model="gte-rerank-v2",
        query="什么是文本排序模型",
        documents=[
            "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序",
            "量子计算是计算科学的一个前沿领域",
            "预训练语言模型的发展给文本排序模型带来了新的进展"
        ],
        top_n=2,
        return_documents=True
    )
    print(resp)

if __name__ == '__main__':
    text_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,
                "document": {
                    "text": "文本排序模型广泛用于搜索引擎和推荐系统中，它们根据文本相关性对候选文本进行排序"
                }
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193,
                "document": {
                    "text": "预训练语言模型的发展给文本排序模型带来了新的进展"
                }
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    }
}

错误码

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

限流

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

上一篇：更多模型下一篇：通义法睿