文本重排序 - DashScope 原生格式

接口概述

采用 DashScope 原生 Rerank 接口格式：给定查询（input.query）与候选文档列表（input.documents），按相关性从高到低输出排序结果，用于搜索引擎、RAG 等场景的结果优化。

本页说明 DashScope 原生格式（input 嵌套体）。重排序接口按模型支持两种报文格式，报文必须按所选模型的原生格式提交（用错格式会被判为参数错误）；本页格式适用于「可用模型」表中的模型。

计费按输入 tokens，费用可在控制台「费用中心」查看。

接口地址

POST https://ai.jw-info.com/v1/rerank

请求头

请求头是否必填说明
Content-Type是固定为 application/json
Authorization是Bearer {API_KEY}；也可用 x-api-key: {API_KEY}

请求参数

参数名类型是否必填默认值说明
modelstring是-模型名称，见「可用模型」
inputobject是-输入信息，结构见下
parametersobject否-配置参数，结构见下

input 结构：

参数名类型是否必填说明
input.querystring是查询文本
input.documentsarray是待排序的文档列表，每个元素为字符串

parameters 结构：

参数名类型是否必填默认值说明
parameters.return_documentsboolean否true是否在结果中返回原始文档文本
parameters.top_ninteger否全部返回最相关的前 N 条；不传则返回全部

请求示例

最简请求：

{
  "model": "gte-rerank-v2",
  "input": {
    "query": "什么是文本排序模型",
    "documents": [
      "文本排序模型广泛用于搜索引擎和推荐系统中",
      "量子计算是计算科学的一个前沿领域",
      "预训练语言模型的发展给文本排序模型带来了新的进展"
    ]
  }
}

指定返回数量：

{
  "model": "gte-rerank-v2",
  "input": {
    "query": "什么是文本排序模型",
    "documents": [
      "文本排序模型广泛用于搜索引擎和推荐系统中",
      "量子计算是计算科学的一个前沿领域",
      "预训练语言模型的发展给文本排序模型带来了新的进展"
    ]
  },
  "parameters": {
    "return_documents": true,
    "top_n": 2
  }
}

响应参数

参数名类型说明
outputobject输出信息
output.resultsarray排序结果列表（按相关性降序）
output.results[].indexinteger文档在原始 input.documents 数组中的索引
output.results[].relevance_scorefloat相关性得分（0~1），越高越相关
output.results[].documentobject原始文档（parameters.return_documents=true 时返回）
output.results[].document.textstring文档文本
usage.input_tokensinteger输入 token 数
usage.total_tokensinteger总 token 数
request_idstring请求唯一标识

响应示例

{
  "output": {
    "results": [
      {
        "index": 2,
        "relevance_score": 0.92,
        "document": { "text": "预训练语言模型的发展给文本排序模型带来了新的进展" }
      },
      {
        "index": 0,
        "relevance_score": 0.85,
        "document": { "text": "文本排序模型广泛用于搜索引擎和推荐系统中" }
      },
      {
        "index": 1,
        "relevance_score": 0.12,
        "document": { "text": "量子计算是计算科学的一个前沿领域" }
      }
    ]
  },
  "usage": { "input_tokens": 45, "total_tokens": 45 },
  "request_id": "rerank-abc123"
}

错误响应

参数不合法（模型名写错、缺少 input.query 或 input.documents 等）时返回错误对象：

{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error",
    "code": "invalid_request_error"
  }
}

完整状态码与排查建议见「错误码」页。

代码示例

cURL

curl https://ai.jw-info.com/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "gte-rerank-v2",
    "input": {
      "query": "什么是文本排序模型",
      "documents": [
        "文本排序模型广泛用于搜索引擎和推荐系统中",
        "量子计算是计算科学的一个前沿领域",
        "预训练语言模型的发展给文本排序模型带来了新的进展"
      ]
    },
    "parameters": {
      "return_documents": true,
      "top_n": 2
    }
  }'

Python

import requests

BASE = "https://ai.jw-info.com"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-你的密钥",
}


def rerank_gte(query, documents, model="gte-rerank-v2", top_n=None,
               return_documents=True):
    """用 DashScope 原生格式对文档重排序"""
    parameters = {"return_documents": return_documents}
    if top_n is not None:
        parameters["top_n"] = top_n
    payload = {
        "model": model,
        "input": {"query": query, "documents": documents},
        "parameters": parameters,
    }
    response = requests.post(f"{BASE}/v1/rerank", json=payload, headers=HEADERS)
    result = response.json()

    if response.status_code != 200:
        print("请求失败:", result.get("error", {}).get("message", result))
        return None

    results = result["output"]["results"]
    usage = result["usage"]
    print(f"返回结果数: {len(results)}")
    print(f"Token 用量: 总计 {usage.get('total_tokens')}")
    for r in results:
        text = r.get("document", {}).get("text", "") if return_documents else ""
        print(f"  [{r['index']}] 得分={r['relevance_score']:.4f}  {text[:50]}")
    return results


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

Java（OkHttp）

import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;

public class GteRerankExample {
    private static final String BASE = "https://ai.jw-info.com";
    private static final String API_KEY = "sk-你的密钥";
    private static final OkHttpClient CLIENT = new OkHttpClient();
    private static final ObjectMapper MAPPER = new ObjectMapper();

    public static void main(String[] args) throws Exception {
        String json = """
            {
              "model": "gte-rerank-v2",
              "input": {
                "query": "什么是文本排序模型",
                "documents": ["文本排序模型广泛用于搜索引擎和推荐系统中", "量子计算是计算科学的一个前沿领域"]
              },
              "parameters": {"return_documents": true, "top_n": 2}
            }
            """;

        Request request = new Request.Builder()
                .url(BASE + "/v1/rerank")
                .addHeader("Authorization", "Bearer " + API_KEY)
                .addHeader("Content-Type", "application/json")
                .post(RequestBody.create(json, MediaType.parse("application/json")))
                .build();

        try (Response response = CLIENT.newCall(request).execute()) {
            var result = MAPPER.readTree(response.body().string());
            if (!response.isSuccessful()) {
                System.out.println("请求失败: " + result.get("error").get("message").asText());
                return;
            }
            for (var r : result.get("output").get("results")) {
                System.out.println("  [" + r.get("index").asInt() + "] 得分="
                        + r.get("relevance_score").asDouble() + "  "
                        + r.get("document").get("text").asText());
            }
        }
    }
}

可用模型

模型 ID说明
gte-rerank-v2GTE 重排序模型 v2，使用本页格式

模型清单与单价以模型广场为准（含上架状态）。

注意事项

  • output.results[].index 是原始 input.documents 数组里的下标，不是排序后的序号——结果已按相关性降序，直接按下标回查原文即可。
  • input.documents 的每个元素为字符串；需要一起带回原文时保持 parameters.return_documents 为 true（默认值）。
  • 单次可提交的文档条数与单条长度上限由模型侧决定，超限会返回参数错误；建议单批不超过 500 条。

计费说明

  • 按输入 tokens 计费（未命中缓存的输入、命中缓存的输入分别计价；重排序模型一般只有输入腿）。
  • 每次调用的费用可在控制台「费用中心」查看，响应里不返回费用信息。
  • 调用报错记 0 费用，但仍会在调用明细里留一条失败记录。

在模型广场查看支持「重排序」的模型 →