# 创建重排序
创建重排序API用于提供灵活的数据项排序功能，以提升用户体验和应用的可定制性。
#### 前提条件
- 预置服务：已在"模型推理 \> 在线推理 \> 预置服务"页签开通BGE-Reranker-V2-M3模型的预置服务。具体操作，请参见[MaaS开通预置服务](https://support.huaweicloud.com/model-call-maas/model-call-052.html)。
- 自定义接入点：已在"模型推理 \> 在线推理 \> 自定义接入点"页签为bge-reranker-v2-m3或Qwen3-Reranker-8B模型创建了自定义接入点。具体操作，请参见[使用自定义接入点](https://support.huaweicloud.com/model-call-maas/model-call-048.html#ZH-CN_TOPIC_0000002549717747)。
 
#### 约束限制
该功能仅支持"西南-贵阳一"区域。
#### 接口信息
表1接口信息 
| 名称      | 说明                                                                                                                            | 取值                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|:---|:---|:---|
| API地址   | 调用重排序的API地址。                                                                                                                  | https://api.modelarts-maas.com/v1/rerank                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| model参数 | model参数调用名称。  | 您可以任选以下方式获取model参数值。 - 从[表2]的"**model** **参数值**"列获取。  - 预置服务：在"预置服务"页签的服务名称左侧，单击![](https://support.huaweicloud.com/model-call-maas/figure/zh-cn_image_0000002449321738.png "点击放大")图标，在"model参数"列查看取值。具体操作，请参见[MaaS开通预置服务](https://support.huaweicloud.com/model-call-maas/model-call-052.html)。  - 自定义接入点：在"自定义接入点"页签的"model参数"列查看取值。更多信息，请参见[使用自定义接入点](https://support.huaweicloud.com/model-call-maas/model-call-048.html#ZH-CN_TOPIC_0000002549717747)。   |
   
#### 支持模型列表
 表2支持模型列表 
| **模型**             | 支持地域   | **model** **参数值**  | 应用场景    |
|:---|:---|:---|:---|
| BGE-Reranker-V2-M3 | 西南-贵阳一 | bge-reranker-v2-m3 | 检索结果再排序 |
   
#### 请求参数说明
表3请求body参数 
| 参数        | 是否必填 | 默认值 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|:---|:---|:---|:---|:---|
| model     | 是    | 无   | string | **参数解释：** 模型名称。 **约束限制：** 不涉及。 **取值范围**： bge-reranker-v2-m3 **默认值：** 不涉及。 |
| query     | 是    | 无   | string | **参数解释：** 用户输入的文本信息。 **约束限制：** 最大长度不能超过8K。 **取值范围**： 不涉及。 **默认值：** 不涉及。     |
| documents | 是    | 无   | array  | **参数解释：** 待排序文档列表。每个元素是一个字符串。 **约束限制：** 不涉及。 **取值范围**： 不涉及。 **默认值：** 不涉及。           |
   
#### 响应参数说明
**状态码：200**
| 参数                           | 参数类型       | 说明                                                                                                                                                                                                                                                                                                |
|:---|:---|:---|
| id                           | string     | **参数解释：** 请求ID。 **取值范围：** 不涉及。                             |
| model                        | string     | **参数解释：** 模型名称。 **取值范围：** bge-reranker-v2-m3                    |
| usage                        | object     | **参数解释：** 模型本次运行所消耗的Token信息。                                                                                                                                                                                             |
| usage.total_tokens           | integer    | **参数解释：** 本次请求使用的Token总数。 **取值范围：** 不涉及。                     |
| results                      | object\[\] | **参数解释：** 重排序结果集。                                                                                                                                                                                                     |
| results\[i\].index           | integer    | **参数解释：** 请求参数"documents"数组里的元素所在数组中的序号。 **取值范围：** 从0开始的整数。 |
| results\[i\].document        | object     | **参数解释：** 请求参数documents原始内容信息。                                                                                                                                                                                       |
| results\[i\].document.text   | number\[\] | **参数解释：** 具体文档内容（重排序后的）。                                                                                                                                                                                             |
| results\[i\].relevance_score | double     | **参数解释：** 相似度得分。 **取值范围：** 不涉及。                                 |
   
#### 请求示例
此处以使用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)
  ```
  
- 使用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）是关键。"
      ]
  }'
  ```
  
 
#### 响应示例
```
{
"id": "rerank-dc9e3495b71134e82c50651c32cde9f6",
"model": "bge-reranker-v2-m3",
"usage": {
"total_tokens": 211
},
"results": [{
"index": 4,
"document": {
"text": "手冲咖啡的技巧：控制水流速度、均匀注水和合适的水温（90-96°C）是关键。"
},
"relevance_score": 0.01898193359375
}, {
"index": 1,
"document": {
"text": "法压壶的步骤：1. 研磨咖啡豆。2. 加入热水。3. 压下压杆。4. 倒入杯中。"
},
"relevance_score": 0.007404327392578125
}, {
"index": 2,
"document": {
"text": "意式浓缩咖啡需要一台高压机器，在9个大气压下快速萃取。"
},
"relevance_score": 0.0003418922424316406
}, {
"index": 3,
"document": {
"text": "挑选咖啡豆时，要注意其烘焙日期，新鲜的豆子风味更佳。"
},
"relevance_score": 6.014108657836914e-05
}, {
"index": 0,
"document": {
"text": "咖啡豆的产地主要分布在赤道附近，被称为‘咖啡带’。"
},
"relevance_score": 3.349781036376953e-05
}]
}
```