調用PushKnowledgeDocuments批量推送文檔 - OpenSearch

OpenSearch-LLM智能問答版支援通過API的方式批量推送文檔。

前提條件

擷取身份鑒權API Key：調用OpenSearch-LLM智能問答版服務時，需要對調用者身份進行鑒權，具體請參見管理API Key。
擷取服務調用地址：調用OpenSearch-LLM智能問答版服務時，需要提供服務的調用地址，具體請參見擷取服務調用地址。

介面資訊

要求方法	請求協議	請求資料格式
POST	HTTP	JSON

請求URL

{host}/v3/openapi/apps/[app_group_identity]/actions/knowledge-bulk

{host}：調用服務的地址，支援通過公網和VPC兩種方式調用API服務，可參見擷取服務調用地址。
{app_group_identity}：應用程式名稱，需要登入OpenSearch-LLM智能問答版控制台，在執行個體管理中查看對應執行個體的應用程式名稱。

請求參數

Header參數

參數	類型	是否必填	描述	樣本值
Content-Type	string	是	請求的資料格式，目前僅支援JSON格式，固定填寫"application/json"。	application/json
Authorization	string	是	請求鑒權的API Key，Bearer開頭。	Bearer OS-d1**2a

Body參數

參數	類型	是否必填	描述	樣本值
cmd	string	是	操作指令。	ADD/DELETE
fields	map	是	欄位組合。
fields.id	string	是	主鍵ID。	13579
fields.title	string	否	文檔標題。	Something interesting
fields.url	string	否	文檔的連結。	https://www.aliyun.com
fields.content	string	是	文檔的內容。	No, is not.

請求體樣本

1、上傳主表文檔

['{
    "cmd": "ADD",
    "fields": {
      "id": "13579",
      "title": "Something interesting",
      "url": "https://www.aliyun.com",
      "content": "No, is not."
      }
}']

上傳非結構化文檔（pdf/doc/txt/html）

['{
    "cmd" : "URL/BASE64",
    "fields": {
      "id": "文檔id(可選)",
      "type": "檔案類型，pdf/doc/txt/html...",
      "title": "檔案名稱(可選)",
      "content": "URL/Base64編碼資料",
      "url": "連結(可選)"
    }
 }']

說明

URL僅支援OSS的通過ossClient.generatePresignedUrl產生的資料訪問URL

2、上傳輔表

['{
    "cmd" : "ADD",
    "fields": {					# 資料體，根據表格schema定義
      "key1": "value1",
      "key2": "value2",
      "key3": "value3"
    },
    "table_name": "輔表表名"	# 表名，空預設為主表
  }']

3、刪除表

['{
    "cmd" : "DELETE",
    "fields": {
      "id": "13579333"
    }
}']

cmd : 必選欄位。定義該文檔的操作行為，可以為“add”、“delete”。建議在一個請求中進行批次更新操作，提高網路互動及處理效率。“add”表示新增文檔，如果該主鍵對應文檔已經存在，則會覆蓋原來文檔；“delete”表示刪除文檔，如果該主鍵對應文檔已經不存在，則認為刪除成功。
fields : 必選欄位。要操作的文檔內容，主鍵欄位必選，系統所有操作都是通過主鍵來進行的。對於“delete”只需要提供文檔主鍵即可。
注意：最外層是JsonArray類型，支援多個文檔大量操作。

返回參數

參數	類型	描述
errors	list	錯誤內容
status	string	status：執行結果，OK為成功，FAIL為失敗，請根據返回錯誤碼進行排查
request_id	string	當前請求的 request_id
result	boolean	執行成功返回該參數，值為true，報錯不返回該參數
total	int	上傳文檔的總數
success	int	上傳成功文檔數
failure	int	上傳失敗的文檔數
failed_ids	array	上傳失敗的文檔id

響應體樣本

{
  "request_id" : "abc123-ABC",
  "result" : {
    "total": 100,
    "success": 50,
    "failure": 50,
    "failed_ids": [
      "id1",
      "id2",
      "id3",
      "..."
    ]
  }
  "errors" : [
    {
      "code" : "如果有錯誤，這裡填錯誤碼",
      "message" : "如果有錯誤，這裡填錯誤資訊"
    }
  ]
}

注意事項

使用API/SDK推送資料時，應用的欄位名稱大小寫不敏感。
API/SDK推送資料有次數和大小的限制，目前無法修改上傳大小限制。不同應用的限制不同，請參閱使用限制。
資料上傳後請務必檢查傳回值，並對相關錯誤碼進行重試（尤其是3007錯誤），否則會出現資料丟失情況。同時，資料處理是非同步，系統返回“OK”後只表示系統接收資料成功，資料處理過程的錯誤會在控制台錯誤資訊中展示，請注意及時檢查。
POST的資料大小有限制，如果您上傳的文檔總量過大（編碼前2M），伺服器將拒絕接收任何參數，同時返回異常。
POST推送操作 body 部分的資料若包含中文必須要做 UTF-8 編碼，Header中的Content-MD5 參數也一樣，在計算資料 MD5 值前，必須要先進行 UTF-8 編碼，否則會出現推送報錯問題。
若介面調用返回錯誤碼 4016，此錯誤為使用者通過RAM使用者調用文檔推送時許可權不足，請為RAM使用者授予AliyunOpenSearchFullAccess許可權，具體操作請參見為RAM使用者授權。