查詢理解API - OpenSearch

本文介紹關於查詢理解服務的API詳情。

服務名稱

服務ID

服務描述

API調用QPS限制（含主帳號與RAM子帳號）

查詢分析服務

ops-query-analyze-001

提供Query內容分析服務，基於大語言模型及NLP能力，可對使用者輸入的查詢內容進行意圖識別、相似問題擴充、NL2SQL處理等，有效提升RAG情境中檢索問答效果。

針對NL2SQL服務，您需要先通過控制台配置查詢分析-NL2SQL服務中使用的表結構資訊、查詢樣本等，再參照本文檔資訊通過API調用查詢分析-NL2SQL服務。

說明

如需擴充QPS，請通過工單聯絡支援人員協助。

擷取身份鑒權資訊
通過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	內部錯誤。

更多狀態代碼說明，請參見狀態代碼說明。