API详情
SDK使用
前提条件
获取API-KEY:获取API-KEY。
已安装最新版SDK:安装DashScope SDK。
pip install dashscope
调用示例
以下示例展示了调用文档排序模型API的代码示例。
需要使用您的API-KEY替换示例中的 YOUR_DASHSCOPE_API_KEY,代码才能正常运行。
设置API-KEY
export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY
import dashscope
from http import HTTPStatus
def text_rerank():
resp = dashscope.TextReRank.call(
model=dashscope.TextReRank.Models.gte_rerank,
query="什么是文本排序模型",
documents=[
"文本排序模型广泛用于搜索引擎和推荐系统中,它们根据文本相关性对候选文本进行排序",
"量子计算是计算科学的一个前沿领域",
"预训练语言模型的发展给文本排序模型带来了新的进展"
],
top_n=10,
return_documents=True
)
if resp.status_code == HTTPStatus.OK:
print(resp)
else:
print(resp)
if __name__ == '__main__':
text_rerank()
输出示例
{
"status_code": 200, // 200 indicate success otherwise failed.
"request_id": "9676afe6-fa1a-9895-bf00-b8376333062a", // The request id.
"code": "", // If failed, the error code.
"message": "", // If failed, the error message.
"output": {
"results": [
{
"index": 0,
"relevance_score": 0.7314485774089865,
"document": {
"text": "文本排序模型广泛用于搜索引擎和推荐系统中,它们根据文本相关性对候选文本进行排序"
}
},
{
"index": 2,
"relevance_score": 0.5831720487049298,
"document": {
"text": "预训练语言模型的发展给文本排序模型带来了新的进展"
}
},
{
"index": 1,
"relevance_score": 0.04973238644524712,
"document": {
"text": "量子计算是计算科学的一个前沿领域"
}
}
]
},
"usage": {
"total_tokens": 79
}
}
参数详解
请求参数
参数名称
必选
示例值
描述
model
是
gte-rerank
取值:调用的模型名称,可以选择gte-rerank
说明:模型的英文名称
query
是
"什么是文本排序模型"
取值:字符串
说明:query最大长度不能超过4000个字符
documents
是
["文本排序模型广泛用于搜索引擎和推荐系统中,它们根据文本相关性对候选文本进行排序", "量子计算是计算科学的一个前沿领域", "预训练语言模型的发展给文本排序模型带来了新的进展"]
取值:字符串列表
说明:待排序的候选doc列表
top_n
否
10
取值:整数类型
说明:排序返回的top文档数量, 如果没有指定则返回全部候选doc,如果指定的top_n值大于输入的候选doc数量,返回全部doc
return_documents
否
False
取值:bool类型
说明:返回的排序结果列表里面是否返回每一条document原文,默认值False
响应参数
字段
类型
描述
示例值
output.results
Array
本次请求的算法输出内容,是一个由结构组成的数组,每一个数组中包含一个对应的输入 text的算法输出内容。
[ { "document": { "text": "文本排序模型广泛用于搜索引擎和推荐系统中,它们根据文本相关性对候选文本进行排序" }, "index": 0, "relevance_score": 0.7314485774089865 }, { "document": { "text": "预训练语言模型的发展给文本排序模型带来了新的进展" }, "index": 2, "relevance_score": 0.5831720487049298 }, { "document": { "text": "量子计算是计算科学的一个前沿领域" }, "index": 1, "relevance_score": 0.04973238644524712 } ]
output.results.index
Integer
本结构中的算法结果对应的doc在输入候选doc数组中的位置索引值
0,1,2,3...
output.results.relevance_score
Double
相似度分数
output.results.document
Dict
doc原文内容
usage
Dict
本次请求消耗的token数
{ "total_tokens": 79 }
request_id
String
本次请求的系统唯一码
7574ee8f-38a3-4b1e-9280-11c33ab46e51
HTTP使用说明
本模型还可通过HTTP的方式进行调用,以适用更灵活的业务开发,下方示例提供了CURL命令,其中用POST方式请求了接口:https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank
参数详解
请求参数
字段
类型
传参方式
必选
示例值
描述
Content-Type
String
Header
是
application/json
取值:固定值,无需更改
说明:请求类型
Authorization
String
Header
是
Bearer d1**2a
取值:需要填入您的API-KEY
说明:API-KEY的获取方式参考上方文档中的调用前准备
model
String
Body
是
gte-rerank
取值:调用模型名称
说明:指明需要调用的模型。
query
String
Body
是
"什么是文本排序模型"
取值:字符串
说明:query最大长度不能超过4000个字符
documents
Array
Body
是
[ "文本排序模型广泛用于搜索引擎和推荐系统中,它们根据文本相关性对候选文本进行排序", "量子计算是计算科学的一个前沿领域", "预训练语言模型的发展给文本排序模型带来了新的进展" ]
取值:字符串列表
说明:待排序的候选doc列表
parameters.top_n
Integer
Body
否
10
取值:整数类型
说明:排序返回的top文档数量,如果没有指定则返回全部候选doc,如果指定的top_n值大于输入的候选doc数量,返回全部doc
parameters.return_documents
Bool
Body
否
True
取值:bool类型
说明:返回的排序结果列表里面是否返回每一条document原文,默认值False
响应参数
字段
类型
描述
示例值
output.results
Array
本次请求的算法输出内容,是一个由结构组成的数组,每一个数组中包含一个对应的输入 text的算法输出内容。
[ { "document": { "text": "文本排序模型广泛用于搜索引擎和推荐系统中,它们根据文本相关性对候选文本进行排序" }, "index": 0, "relevance_score": 0.7314485774089865 }, { "document": { "text": "预训练语言模型的发展给文本排序模型带来了新的进展" }, "index": 2, "relevance_score": 0.5831720487049298 }, { "document": { "text": "量子计算是计算科学的一个前沿领域" }, "index": 1, "relevance_score": 0.04973238644524712 } ]
output.results.index
Integer
本结构中的算法结果对应的doc在输入候选doc数组中的位置索引值
0,1,2,3...
output.results.relevance_score
Double
相似度分数
output.results.document
Dict
doc原文内容
usage
Dict
本次请求消耗的token数
{ "total_tokens": 79 }
request_id
String
本次请求的系统唯一码
7574ee8f-38a3-4b1e-9280-11c33ab46e51
调用示例
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY> \
--header 'Content-Type: application/json' \
--data '{
"model": "gte-rerank",
"input":{
"query": "什么是文本排序模型",
"documents": [
"文本排序模型广泛用于搜索引擎和推荐系统中,它们根据文本相关性对候选文本进行排序",
"量子计算是计算科学的一个前沿领域",
"预训练语言模型的发展给文本排序模型带来了新的进展"
]
},
"parameters": {
"return_documents": true,
"top_n": 5
}
}'
输出示例
{
"output": {
"results": [
{
"document": {
"text": "文本排序模型广泛用于搜索引擎和推荐系统中,它们根据文本相关性对候选文本进行排序"
},
"index": 0,
"relevance_score": 0.7314485774089865
},
{
"document": {
"text": "预训练语言模型的发展给文本排序模型带来了新的进展"
},
"index": 2,
"relevance_score": 0.5831720487049298
},
{
"document": {
"text": "量子计算是计算科学的一个前沿领域"
},
"index": 1,
"relevance_score": 0.04973238644524712
}
]
},
"usage": {
"total_token": 79
},
"request_id": "d09e1029-e3a7-9fee-a7b0-d75af1c73932"
}
调用失败示例
在访问请求出错的情况下,输出的结果中会通过code
和message
指明出错原因。
{
"code":"InvalidApiKey",
"message":"Invalid API-key provided.",
"request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}
状态码说明
DashScope服务通用状态码请查阅:返回状态码说明。