API详情

OpenSearch搜索开发工作台支持通过API的方式调用文档相关性打分服务，您可以将服务集成到您的业务处理链路中，来提升检索或处理效率。

前提条件

当前API支持2种鉴权方式，您可选择以下任一种方式进行鉴权：

API-KEY鉴权，前提条件：

• 已开通服务并获得API-KEY：开通服务并创建API-KEY。

AccessKey鉴权，前提条件：

• 已开通服务并配置环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET：创建AccessKey并配置环境变量。

请求说明

公共说明

• 请求body最大不能超过8MB。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/ranker/{service_id} 

参数说明：

• host：调用服务的地址，可参考控制台-API-KEY管理页面的生产API域名，例： http://******.hangzhou.opensearch.aliyuncs.com

• workspace_name：工作空间名称，例：default

• service_id： 系统内置服务id，例：ops-bge-reranker-larger

入参描述

Header参数

• API-KEY鉴权

• AccessKey鉴权请参考：v3 API 签名机制

Body参数

出参描述

请求示例

curl示例

curl -XPOST -H"Content-Type: application/json" \http://****.hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/ranker/ops-bge-reranker-larger\
    -H "Authorization: Bearer 你的API-KEY" \
    -d '{"query":"什么是召回量","docs":["应用: 应用是用户的一套数据配置，包括应用的数据源结构，索引结构及其它一些数据属性配置。一个应用即一个搜索服务。文档：文档是可搜索的结构化数据单元。文档包含一个或多个字段，但必须有主键字段，OpenSearch通过主键值来确定唯一的文档。  主键重复则文档会被覆盖。字段：字段是文档的组成单元，包含字段名称和字段内容","索引：索引是一种用于加速文档检索速度的数据结构，一个用户可以创建多个索引。组合索引：允许用户将多个TEXT、SHORT_TEXT等文本类型的源字段索引到同一个字段，用来做组合索引。如一个论坛搜索，需要提供基于标题(title)的搜索及基于标题(title)和内容(body)的综合搜索，那么可以将title建立title_search、default的索引，将body建立default索引。那么，在title_search上查询即可实现基于标题的搜索，在default上查询即可实现基于标题和内容的综合搜索。默认展示字段；用来做结果展示使用，同时可以通过API参数fetch_fields来控制每次结果的返回字段，需注意在程序中配置fetch_fields该参数后会覆盖应用中默认展示字段配置，以程序中的fetch_fields设置为主，若程序中不设置fetch_fields参数则以应用中默认展示字段为主。分词；对推送上来的文档进行词组切分，TEXT类型为按检索单元进行切分，SHORT_TEXT为按单字进行切分。如“浙江大学”，TEXT类型会切分成2个词组：“浙江”、“大学”。SHORT_TEXT会切分成4个词组：“浙”、“江”、“大”、“学”。Term：分词后的词组称为term。","构建索引：分完词后会进行索引构建操作，以便根据用户查询，快速定位到具体的文档。搜索引擎一般会构建出两种类型的链表：倒排和正排链表。倒排：词组到文档的对应关系组成的链表，query子句用的就是这种排序方式，查询效率高。例如：term1->doc1,doc2,doc3；term2->doc1,doc2正排：文档到字段对应关系组成的链表，filter子句用的就是这种排序方式，性能略慢于倒排。例如：doc1->id,type,create_time…召回：通过用户查询的关键词进行分词，将分词后的词组通过查找倒排链表快速定位到文档，这个过程称为召回。召回量：召回得到的文档数为召回量。","排序表达式：排序表达式是用于控制搜索结果文档排序的数学表达式，支持基本数学运算、数学函数和内置函数。粗排表达式； 对搜索结果进行第一轮的海选， 因为要遍历所有的文档（ 目前上限为100万）， 所以粗排要尽量简单（ 选取对文档最重要的几项内容， 如新闻类可以选用文本性及时效性）， 按照表达式对文档进行算分， 并按照算分结果进行排序。 精排表达式； 对第一轮的排序结果选取前N个按照精排表达式进行第二轮更细节的分值计算， 按照分值进行最终的排序， 并返回给用户。 结果摘要： 文本内容一般会很长， 在搜索结果展示的时候可以只展示部分匹配的内容， 方便用户快速了解文档主要内容。 查询分析： 可以配置若干分析规则， 目前支持拼写检查、 停用词、 词权重等功能， 可以让用户更好的干预搜索行为， 获得更好的搜索体验。 "]}'

windows系统curl示例

curl -XPOST -H"Content-Type: application/json" http://****.hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/ranker/ops-bge-reranker-larger -H "Authorization: Bearer 你的API-KEY" -d "{\"query\":\"什么是召回量\",\"docs\":[\"应用:应用是用户的一套数据配置，包括应用的数据源结构，索引结构及其它一些数据属性配置。一个应用即一个搜索服务。文档：文档是可搜索的结构化数据单元。文档包含一个或多个字段，但必须有主键字段，OpenSearch通过主键值来确定唯一的文档。主键重复则文档会被覆盖。字段：字段是文档的组成单元，包含字段名称和字段内容\",\"索引：索引是一种用于加速文档检索速度的数据结构，一个用户可以创建多个索引。组合索引：允许用户将多个TEXT、SHORT_TEXT等文本类型的源字段索引到同一个字段，用来做组合索引。如一个论坛搜索，需要提供基于标题(title)的搜索及基于标题(title)和内容(body)的综合搜索，那么可以将title建立title_search、default的索引，将body建立default索引。那么，在title_search上查询即可实现基于标题的搜索，在default上查询即可实现基于标题和内容的综合搜索。默认展示字段；用来做结果展示使用，同时可以通过API参数fetch_fields来控制每次结果的返回字段，需注意在程序中配置fetch_fields该参数后会覆盖应用中默认展示字段配置，以程序中的fetch_fields设置为主，若程序中不设置fetch_fields参数则以应用中默认展示字段为主。分词；对推送上来的文档进行词组切分，TEXT类型为按检索单元进行切分，SHORT_TEXT为按单字进行切分。如“浙江大学”，TEXT类型会切分成2个词组：“浙江”、“大学”。SHORT_TEXT会切分成4个词组：“浙”、“江”、“大”、“学”。Term：分词后的词组称为term。\",\"构建索引：分完词后会进行索引构建操作，以便根据用户查询，快速定位到具体的文档。搜索引擎一般会构建出两种类型的链表：倒排和正排链表。倒排：词组到文档的对应关系组成的链表，query子句用的就是这种排序方式，查询效率高。例如：term1->doc1,doc2,doc3；term2->doc1,doc2正排：文档到字段对应关系组成的链表，filter子句用的就是这种排序方式，性能略慢于倒排。例如：doc1->id,type,create_time…召回：通过用户查询的关键词进行分词，将分词后的词组通过查找倒排链表快速定位到文档，这个过程称为召回。召回量：召回得到的文档数为召回量。\",\"排序表达式：排序表达式是用于控制搜索结果文档排序的数学表达式，支持基本数学运算、数学函数和内置函数。粗排表达式；对搜索结果进行第一轮的海选，因为要遍历所有的文档（目前上限为100万），所以粗排要尽量简单（选取对文档最重要的几项内容，如新闻类可以选用文本性及时效性），按照表达式对文档进行算分，并按照算分结果进行排序。精排表达式；对第一轮的排序结果选取前N个按照精排表达式进行第二轮更细节的分值计算，按照分值进行最终的排序，并返回给用户。结果摘要：文本内容一般会很长，在搜索结果展示的时候可以只展示部分匹配的内容，方便用户快速了解文档主要内容。查询分析：可以配置若干分析规则，目前支持拼写检查、停用词、词权重等功能，可以让用户更好的干预搜索行为，获得更好的搜索体验。\"]}"

响应示例

正常响应示例

{
  "request_id": "450fcb80-f796-46c1-8d69-e1e86d29aa9f",
  "latency": 564.903929,
  "usage": {
    "doc_count": 2
  }
  "result": {
   "scores":[
     {
       "index":1,
       "score": 1.37
     },
     {
       "index":0,
       "score": -0.3
     }
   ]
  }
}

异常响应示例

在访问请求出错的情况下，输出的结果中会通过 code 和 message 指明出错原因。

{
    "request_id": "45C8C9E5-6BCB-43DD-80D3-E298F788512B",
    "latency": 0,
    "code": "InvalidParameter",
    "message": "JSON parse error: Unexpected character ..."
}

状态码说明

更多状态码说明，请参考：状态码说明。