重排序API文档教程 – 智能文档排序接口调用指南

文本是《工具配置（共27篇）》专题的第 25 篇。阅读本文前，建议先阅读前面的文章：

1. 资源准备

API Key：此项配置填写在一步API官网创建API令牌，一键直达API令牌创建页面
创建API令牌步骤请参考API Key的获取和使用
API Host：此项配置填写https://yibuapi.com/v1
查看支持的模型请参在这里复制模型在线查询

2. 📝 简介

给定查询和文本列表，重排序API将根据与查询的相关性对文本进行排序。每个文本都会被分配一个相关性分数，从而产生一个有序的数组结果。此功能特别适用于搜索和检索应用，可以优化文档的排序，帮助用户更快找到相关信息。

3. 💡 请求示例

3.1 基础重排序请求（shell）

curl https://yibuapi.com/v1/rerank \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-reranker-v2-m3",
    "query": "什么是美国的首都？",
    "documents": [
      "内华达州的首府是卡森城。",
      "北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。",
      "华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。",
      "英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。",
      "自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。"
    ],
    "top_n": 3
  }'

响应示例：

{
  "results": [
    {
      "index": 2,
      "relevance_score": 0.999071
    },
    {
      "index": 0,
      "relevance_score": 0.32713068
    },
    {
      "index": 1,
      "relevance_score": 0.1867867
    }
  ],
  "id": "07734bd2-2473-4f07-94e1-0d9f0e6843cf",
  "meta": {
    "api_version": {
      "version": "2",
      "is_experimental": false
    },
    "billed_units": {
      "search_units": 1
    }
  }
}

3.2 使用结构化数据（shell）

curl https://yibuapi.com/v1/rerank \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-reranker-v2-m3",
    "query": "寻找适合初学者的高性价比单反相机",
    "documents": [
      "型号: Canon EOS 800D\n价格: 4299元\n功能: 2410万像素, 光学取景器, Wi-Fi\n适合人群: 初学者, 爱好者",
      "型号: Nikon D3500\n价格: 3099元\n功能: 2416万像素, 光学取景器, 长达1550张的电池续航\n适合人群: 新手, 学生",
      "型号: Sony A7III\n价格: 12999元\n功能: 2420万像素, 全画幅, 4K视频\n适合人群: 专业摄影师, 视频创作者"
    ],
    "max_tokens_per_doc": 512
  }'

响应示例：

curl https://yibuapi.com/v1/rerank \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "寻找适合初学者的高性价比单反相机",
    "documents": [
      "型号: Canon EOS 800D\n价格: 4299元\n功能: 2410万像素, 光学取景器, Wi-Fi\n适合人群: 初学者, 爱好者",
      "型号: Nikon D3500\n价格: 3099元\n功能: 2416万像素, 光学取景器, 长达1550张的电池续航\n适合人群: 新手, 学生",
      "型号: Sony A7III\n价格: 12999元\n功能: 2420万像素, 全画幅, 4K视频\n适合人群: 专业摄影师, 视频创作者"
    ],
    "max_tokens_per_doc": 512
  }'

3.3 Python代码实现(共三种方式，可选择任意一种方式)

import json

import requests

# 方式一：使用 requests 库（推荐）
def call_rerank_api_requests():
    """使用 requests 库调用排序模型API"""

    # API配置
    url = "https://yibuapi.com/v1/rerank"
    headers = {
        "Authorization": "Bearer sk-xxxxx",
        "Content-Type": "application/json"
    }

    # 请求数据
    data = {
        "model": "BAAI/bge-reranker-v2-m3",
        "query": "什么是美国的首都？",
        "documents": [
            "内华达州的首府是卡森城。",
            "北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。",
            "华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。",
            "英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。",
            "自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。"
        ],
        "top_n": 3
    }

    try:
        # 发送POST请求
        response = requests.post(url, headers=headers, json=data)

        # 检查响应状态
        if response.status_code == 200:
            result = response.json()
            print("API调用成功！")
            print(f"响应数据: {json.dumps(result, ensure_ascii=False, indent=2)}")
            return result
        else:
            print(f"API调用失败，状态码: {response.status_code}")
            print(f"错误信息: {response.text}")
            return None

    except requests.exceptions.RequestException as e:
        print(f"请求异常: {e}")
        return None

# 方式二：使用 urllib（标准库，无需额外安装）
def call_rerank_api_urllib():
    """使用 urllib 库调用排序模型API"""

    import urllib.request
    import urllib.parse

    # API配置
    url = "https://yibuapi.com/v1/rerank"
    headers = {
        "Authorization": "Bearer sk-xxxxx",
        "Content-Type": "application/json"
    }

    # 请求数据
    data = {
        "model": "BAAI/bge-reranker-v2-m3",
        "query": "什么是美国的首都？",
        "documents": [
            "内华达州的首府是卡森城。",
            "北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。",
            "华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。",
            "英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。",
            "自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。"
        ],
        "top_n": 3
    }

    try:
        # 将数据转换为JSON字符串并编码
        json_data = json.dumps(data, ensure_ascii=False).encode('utf-8')

        # 创建请求对象
        req = urllib.request.Request(url, data=json_data, headers=headers)

        # 发送请求
        with urllib.request.urlopen(req) as response:
            result_data = response.read().decode('utf-8')
            result = json.loads(result_data)

            print("API调用成功！")
            print(f"响应数据: {json.dumps(result, ensure_ascii=False, indent=2)}")
            return result

    except Exception as e:
        print(f"请求异常: {e}")
        return None

# 封装成类的形式（更适合集成到项目中）
class RerankAPI:
    def __init__(self, api_key, base_url="https://yibuapi.com/v1"):
        self.api_key = api_key
        self.base_url = base_url

    def rerank(self, query, documents, model="BAAI/bge-reranker-v2-m3", top_n=3):
        """
        调用排序模型API

        Args:
            query (str): 查询字符串
            documents (list): 文档列表
            model (str): 模型名称
            top_n (int): 返回前N个结果

        Returns:
            dict: API响应结果
        """
        url = f"{self.base_url}/rerank"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

        data = {
            "model": model,
            "query": query,
            "documents": documents,
            "top_n": top_n
        }

        try:
            response = requests.post(url, headers=headers, json=data)

            if response.status_code == 200:
                return response.json()
            else:
                raise Exception(f"API调用失败，状态码: {response.status_code}, 错误信息: {response.text}")

        except requests.exceptions.RequestException as e:
            raise Exception(f"请求异常: {e}")

# 主函数 - 运行示例
if __name__ == "__main__":
    print("=== 方式一：使用 requests 库 ===")
    result1 = call_rerank_api_requests()

    print("\n=== 方式二：使用 urllib 库 ===")
    result2 = call_rerank_api_urllib()

    print("\n=== 方式三：使用类封装 ===")
    # 创建API实例
    api = RerankAPI("sk-xxxxx")

    # 调用API
    try:
        result3 = api.rerank(
            query="什么是美国的首都？",
            documents=[
                "内华达州的首府是卡森城。",
                "北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。",
                "华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。",
                "英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。",
                "自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。"
            ],
            top_n=3
        )
        print("API调用成功！")
        print(f"响应数据: {json.dumps(result3, ensure_ascii=False, indent=2)}")
    except Exception as e:
        print(f"API调用失败: {e}")

您已阅读完《工具配置（共27篇）》专题的第 25 篇。请继续阅读该专题下面的文章：