# 重排序
在电商搜索或信息检索场景中，用户期望获取与查询高度相关的结果，但文本检索系统在"召回"阶段为保证效率，返回的结果可能不够精准。通过文本排序模型可对召回的文档进行二次精准排序。创建重排序API提供灵活的数据项排序功能，确保最相关结果优先展示，从而提升用户体验和应用准确率。
#### 前提条件
- 已在"模型推理 \> 在线推理 \> 预置服务"页签开通预置服务。详情请见[开通MaaS预置服务](https://support.huaweicloud.com/model-call-maas/model-call-052.html)。
- （可选）如果需要控制服务调用流量，可提前创建自定义接入点，详情请参见[MaaS创建自定义接入点](https://support.huaweicloud.com/model-call-maas/model-call-048.html)。
- 已获取API Key。详情请见[在MaaS管理API Key](https://support.huaweicloud.com/model-call-maas/model-call-049.html)。
- 已获取模型服务的model参数值。详情请见[重排序](https://support.huaweicloud.com/model-list-maas/model_list_0001.html#section4)。
 
#### 支持模型
重排序支持的模型请见[重排序](https://support.huaweicloud.com/model-list-maas/model_list_0001.html#section4)。
#### API说明
模型调用的完整参数列表请见[创建重排序](https://support.huaweicloud.com/model-call-maas/model-call-028.html)。
#### 快速开始
此处以使用BGE-Reranker-V2-M3模型通过Python脚本和Curl命令对文档进行重排序为例，展示重排序模型的基础用法。
- [Python]
  ```
  import requests
  import json
  if __name__ == '__main__':
      url = "https://api.modelarts-maas.com/v1/rerank"  # API地址
      api_key = "MAAS_API_KEY"  # 把MAAS_API_KEY替换成已获取的API Key
      # Send request.
      headers = {
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {api_key}'
      }
      data = {
          "model": "bge-reranker-v2-m3",
          "query": "如何冲泡一杯好喝的咖啡？",  # input类型可为string或string[]。
          "documents": [
              "咖啡豆的产地主要分布在赤道附近，被称为‘咖啡带’。",
              "法压壶的步骤：1. 研磨咖啡豆。2. 加入热水。3. 压下压杆。4. 倒入杯中。",
              "意式浓缩咖啡需要一台高压机器，在9个大气压下快速萃取。",
              "挑选咖啡豆时，要注意其烘焙日期，新鲜的豆子风味更佳。",
              "手冲咖啡的技巧：控制水流速度、均匀注水和合适的水温（90-96°C）是关键。"
          ]
      }
      response = requests.post(url, headers=headers, data=json.dumps(data), verify=False)
      # Print result.
      print(response.status_code)
      print(response.text)
  ```
  效果展示：
  ```
  手冲咖啡的技巧：控制水流速度、均匀注水和合适的水温（90-96°C）是关键。
  法压壶的步骤：1. 研磨咖啡豆。2. 加入热水。3. 压下压杆。4. 倒入杯中。
  意式浓缩咖啡需要一台高压机器，在9个大气压下快速萃取。
  挑选咖啡豆时，要注意其烘焙日期，新鲜的豆子风味更佳。
  咖啡豆的产地主要分布在赤道附近，被称为“咖啡带”。
  ```
- [Curl]
  ```
  curl -X POST "https://api.modelarts-maas.com/v1/rerank" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $MAAS_API_KEY" \
    -d '{
      "model": "bge-reranker-v2-m3",
      "query": "如何冲泡一杯好喝的咖啡？",
      "documents": [
        "咖啡豆的产地主要分布在赤道附近，被称为‘咖啡带’。",
        "法压壶的步骤：1. 研磨咖啡豆。2. 加入热水。3. 压下压杆。4. 倒入杯中。",
        "意式浓缩咖啡需要一台高压机器，在9个大气压下快速萃取。",
        "挑选咖啡豆时，要注意其烘焙日期，新鲜的豆子风味更佳。",
        "手冲咖啡的技巧：控制水流速度、均匀注水和合适的水温（90-96°C）是关键。"
      ]
    }'
  ```
  效果展示：
  ```
  手冲咖啡的技巧：控制水流速度、均匀注水和合适的水温（90-96°C）是关键。
  法压壶的步骤：1. 研磨咖啡豆。2. 加入热水。3. 压下压杆。4. 倒入杯中。
  意式浓缩咖啡需要一台高压机器，在9个大气压下快速萃取。
  挑选咖啡豆时，要注意其烘焙日期，新鲜的豆子风味更佳。
  咖啡豆的产地主要分布在赤道附近，被称为“咖啡带”。
  ```
- [Java]
  建议JDK版本为15+。
  ```
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.time.Duration;
  public class Rerank {
      public static void main(String[] args) throws Exception {
          // API 地址
          String url = "https://api.modelarts-maas.com/v1/rerank";
          String apiKey = "MAAS_API_KEY"; // 请替换为真实 API Key
          String modelName = "bge-reranker-v2-m3";
          // 构建请求体
          String jsonBody = String.format(
                  """
                          {
                              "model": "%s",
                               "query": "如何冲泡一杯好喝的咖啡？",
                              "documents": [
                                 "咖啡豆的产地主要分布在赤道附近，被称为‘咖啡带’。",
                                "法压壶的步骤：1. 研磨咖啡豆。2. 加入热水。3. 压下压杆。4. 倒入杯中。",
                                "意式浓缩咖啡需要一台高压机器，在9个大气压下快速萃取。",
                                "挑选咖啡豆时，要注意其烘焙日期，新鲜的豆子风味更佳。",
                                "手冲咖啡的技巧：控制水流速度、均匀注水和合适的水温（90-96°C）是关键。"
                              ]
                          }""", modelName);
              HttpClient client = HttpClient.newBuilder()
                      .connectTimeout(Duration.ofSeconds(10))
                      .build();
              // 构建 HTTP 请求
              HttpRequest request = HttpRequest.newBuilder()
                      .uri(URI.create(url))
                      .header("Content-Type", "application/json")
                      .header("Authorization", "Bearer " + apiKey)
                      .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                      .build();
              // 发送请求并获取响应
              HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
              int statusCode = response.statusCode();
              String responseBody = response.body();
              // 控制台输出
              System.out.println(statusCode);
              System.out.println(responseBody);
      }
  }
  ```
  效果展示：
  ```
  手冲咖啡的技巧：控制水流速度、均匀注水和合适的水温（90-96°C）是关键。
  法压壶的步骤：1. 研磨咖啡豆。2. 加入热水。3. 压下压杆。4. 倒入杯中。
  意式浓缩咖啡需要一台高压机器，在9个大气压下快速萃取。
  挑选咖啡豆时，要注意其烘焙日期，新鲜的豆子风味更佳。
  咖啡豆的产地主要分布在赤道附近，被称为“咖啡带”。
  ```