本文介紹關于查詢理解服務的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> | 否 | 開啟的功能及對應的參數 目前支持的功能有
注意：
| |
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 | 內部錯誤。 |
更多狀態碼說明，請參見狀態碼說明。