查询理解API_智能开放搜索 OpenSearch(Open Search)-阿里云帮助中心

本文介绍关于查询理解服务的API详情。

服务名称	服务ID	服务描述
查询分析服务	ops-query-analyze-001	提供Query内容分析服务，基于大语言模型及NLP能力，可对用户输入的查询内容进行意图识别、相似问题扩展、NL2SQL处理等，有效提升RAG场景中检索问答效果。

前提条件

获取身份鉴权信息
通过API调用AI搜索开放平台服务时，需要对调用者身份进行鉴权，如何获取鉴权信息请参见获取API-KEY。
获取服务调用地址
支持通过公网和VPC两种方式调用服务，详情请参见获取服务接入地址。

公共说明

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

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/query-analyze/{service_id}

host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。
service_id：系统内置服务ID，例如ops-query-analyze-001。

请求参数

Header参数

API-KEY认证

参数	类型	必填	描述	示例值
Content-Type	String	是	请求类型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body参数

参数	类型	必填	描述	示例值
query	String	是	本次请求内容。	有多少人口？
history	List<Message>	否	历史消息。	[{ "content": "中国的首都在哪", "role": "user" }, { "content": "北京", "role": "assistant" }]
history.content	String	否	消息内容。	中国的首都在哪
history.role	String	否	消息发送者，角色当前可选值：system、user、assistant。	user
functions	List<Function>	否	开启的功能及对应的参数目前支持的功能有 pre：预处理 intent：意图识别 similar_query: 相似query扩展 nl2sql: 自然语言转sql 注意：默认开启的功能有pre，intent，similar_query。当启用nl2sql时，默认关闭intent和similar_query功能。
functions[].name	String	否	如有设置function时，则name必须设置。
functions[].parameters	Map	否	设置功能的参数
functions[].parameters.enable	boolean	否	是否启用改功能	true

返回参数

参数	类型	描述	示例值
request_id	String	系统对一次API调用赋予的唯一标识。	A5B25952-4406-45BF-99EC-E8020246****
latency	Float/Int	请求耗时，单位ms。	10
result.query	String	处理后的请求。	有多少人口
result.queries	List<String>	生成的相似问题。	[ "北京有多少人口" ]
result.intent	String	意图识别结果。	问答
result.sql	Map	nl2sql的结果

Curl请求示例

curl -XPOST -H"Content-Type: application/json" 
\http://****.opensearch.aliyuncs.com/v3/openapi/workspaces/default/query-analyze/ops-query-analyze-001\
    -H "Authorization: Bearer 您的API-Key" \
    -d'{
      "query":"张三在哪个班",
      "history":[
          {
            "role":"user",
            "content":"中国的首都在哪里"
          },
          {
            "role":"assistant",
            "content":"北京"
          }
        ],
        "functions":[
          {
            "name":"pre",
            "parameters":
              {
                "enable":true
              }
          },
          {
            "name":"intent",
            "parameters":
              {
                "enable":true
              }
            },
            {
              "name":"similar_query",
              "parameters":
                {
                  "enable":true
                }
              },
              {
                "name":"nl2sql",
                "parameters":
                  {
                    "enable":true,
                    "config_name":"n_1726047726"
                  }
                }
              ]
            }'

响应示例

正常响应示例

{
  "request_id":"023FC760-E273-4163-B2DA-5CF28E2A****",
  "latency":6383,
  "usage":{
      "total_tokens":1082,
      "output_tokens":41,
      "input_tokens":1041
    },
    "result":{
      "query":"张三在哪个班",
      "queries":[
          "张三所在班级"
      ],
      "intent":"问答",
      "sql":{
          "text":"SELECT students.class FROM students WHERE students.name = 10002;"
      }
    }
}

异常响应示例

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

{
  "request_id":"19C54DAA-AD50-4B37-A48C-912A8F82****",
  "latency":0,
  "code":"InvalidParameter",
  "message":"Required parameter: query missing or invalid, please check the request parameter."
}

状态码说明

HTTP 状态码	错误码	描述
200	-	请求成功，包括任务失败场景，实际任务状态需从result.status中判断。
404	BadRequest.TaskNotExist	任务不存在。
400	InvalidParameter	不合法请求。
500	InternalServerError	内部错误。

更多状态码说明，请参见状态码说明。