重要提示
cohere 的 Rerank 模型接口和 Jina的Rerank模型接口格式 是一样的。
官方文档
📝 简介¶
给定查询和文本列表，重排序API将根据与查询的相关性对文本进行排序。每个文本都会被分配一个相关性分数，从而产生一个有序的数组结果。此功能特别适用于搜索和检索应用，可以优化文档的排序，帮助用户更快找到相关信息。
💡 请求示例¶
基础重排序请求 ✅¶
curl https://地址/v1/rerank \ -H "Authorization: Bearer $NEWAPI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "rerank-v3.5", "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 } }}使用结构化数据 ✅¶
curl https://地址/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 }'响应示例:
{ "results": [ { "index": 1, "relevance_score": 0.918472 }, { "index": 0, "relevance_score": 0.854321 }, { "index": 2, "relevance_score": 0.423156 } ], "id": "8f734bd2-2473-4f07-94e1-0d9f0e68ebfa", "meta": { "api_version": { "version": "2" }, "billed_units": { "search_units": 1 } }}📮 请求¶
端点¶
POST /v1/rerank根据与查询的相关性对文本列表进行重新排序。
鉴权方法¶
在请求头中包含以下内容进行 API 密钥认证：
Authorization: Bearer $NEWAPI_API_KEY其中 $NEWAPI_API_KEY 是您的 API 密钥。
请求头参数¶
X-Client-Name¶
类型：字符串
必需：否
说明：发起请求的项目名称。
请求体参数¶
model¶
类型：字符串
必需：是
说明：要使用的模型标识符，例如 rerank-v3.5。
query¶
类型：字符串
必需：是
说明：搜索查询文本。这是用户输入的问题或查询内容。
documents¶
类型：字符串数组
必需：是
说明：将与查询进行比较的文本列表。为获得最佳性能，建议单个请求中不要发送超过1,000个文档。
注意事项：
长文档将自动截断为 max_tokens_per_doc 指定的值
结构化数据应格式化为YAML字符串以获得最佳性能
top_n¶
类型：整数
必需：否
说明：限制返回的重排结果数量。如果不指定，将返回所有重排结果。
max_tokens_per_doc¶
类型：整数
必需：否
默认值：4096
说明：长文档将自动截断为指定的令牌数量。
📥 响应¶
成功响应¶
返回一个包含排序后文档列表的对象。
results¶
类型：对象数组
说明：排序后的文档列表，按相关性降序排列
属性：
index: 整数，对应于原始文档列表中文档的索引relevance_score: 浮点数，相关性分数范围为[0, 1]。接近1的分数表示与查询高度相关，接近0的分数表示相关性较低
id¶
类型：字符串
说明：请求的唯一标识符
meta¶
类型：对象
说明：包含关于请求的元数据
属性：
api_version: 对象，包含API版本信息version: 字符串，API版本号is_deprecated: 布尔值，是否已弃用is_experimental: 布尔值，是否为实验性功能billed_units: 对象，包含计费信息search_units: 浮点数，计费的搜索单位数tokens: 对象，包含令牌使用统计input_tokens: 浮点数，作为模型输入的令牌数output_tokens: 浮点数，模型产生的令牌数
warnings¶
类型：字符串数组
必需：否
说明：API返回的警告信息
错误响应¶
当请求出现问题时，API可能返回以下HTTP状态码及相应错误：
400 Bad Request: 请求格式或参数错误401 Unauthorized: 未提供有效的API密钥403 Forbidden: 没有权限访问此资源404 Not Found: 请求的资源不存在422 Unprocessable Entity: 请求格式正确但包含语义错误429 Too Many Requests: 请求频率超过限制500 Internal Server Error: 服务器内部错误503 Service Unavailable: 服务暂时不可用
🌟 最佳实践¶
文档准备建议¶
文档长度：每个文档保持简洁明了，避免过长。长文档会被自动截断。
结构化数据：将结构化数据格式化为YAML字符串，以获得最佳性能。例如：
title: 产品名称price: 9999元features: - 特性1 - 特性2
文档数量：单次请求中不要超过1,000个文档，以获得最佳性能。
查询优化¶
明确具体：制定明确、具体的查询，以获得更准确的排序结果。
避免模糊查询：尽量避免过于模糊或通用的查询词，这可能导致相关性分数差异不明显。
理解相关性分数¶
相关性分数是归一化到[0, 1]范围内的值：
接近1的分数表示与查询高度相关
接近0的分数表示相关性低
注意：不能简单地认为分数0.9的文档比分数0.45的文档相关性高2倍。相关性分数是一个相对指标，用于排序，而非绝对比较。
