調用SearchKnowledge搜尋文檔 - OpenSearch

擷取知識庫的內容，進行文本問答查詢。

前提條件

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

介面資訊

要求方法

POST

請求協議

HTTP

請求URL

{host}/v3/openapi/apps/{app_group_identity}/actions/knowledge-search

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

請求資料格式

JSON

請求參數

Header參數

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

Body參數

參數	類型	是否必填	描述	樣本值
question	map	是	輸入的問題。	{ "text":"user question" "type": "TEXT", "session" : "" }
question.text	string	是	使用者輸入的問題常值內容。	user question
question.session	string	否	多輪對話的會話ID，用於標識多輪對話上下文。取值：不設或者為空白，則表示不開啟多輪對話。如設定非空的值，則表示開啟多輪對話，並且系統會將相同的session的對話進行保留，作為多輪對話的上下文。	1725530408586
question.type	string	否	輸入問題的類型，這裡指定為文本類型`TEXT`。	TEXT
options	map	否	用來設定額外的請求參數，使用者控制召回、模型、prompt等。
options.chat	map	否	用來設定訪問大模型相關的參數。
options.chat.disable	boolean	否	是否關閉大模型的訪問。 false：訪問大模型，對結果進行總結產生，預設為false。 true：不訪問大模型。	false
options.chat.stream	boolean	否	是否啟用流式返回結果。 true：流式返回，預設為true。 false：非流式返回。	true
options.chat.model	string	否	選擇的LLM（大語言模型）。可選：	opensearch-llama2-13b
options.chat.model_generation	integer	否	使用產品定製模型時，需要設定對應的模型版本，預設使用最老的版本進行訪問。	20
options.chat.prompt_template	string	否	設定使用者自訂的prompt模板名稱。預設為空白，使用系統內建的prompt模板。	user_defined_prompt_name
options.chat.prompt_config	object	否	使用者自訂prompt中配置的索引值對，參數格式為： `{ "String_key": "value", "Integer_key" : 1 }`	`{ "attitude": "normal", "rule" : "detailed", "noanswer": "sorry", "language": "Chinese", "role": false, "role_name": "AI小助手", }`
options.chat.prompt_config.attitude	string	否	系統內建模板的參數，用來控制對話內容的語氣，預設為normal。 normal：無。 polite：使用和藹和禮貌的語氣。 patience：使用委婉和耐心的語氣。	normal
options.chat.prompt_config.rule	string	否	對話內容的詳細程度，預設為detailed。 detailed：詳細和專業。 stepbystep：詳細且按步驟。	detailed
options.chat.prompt_config.noanswer	string	否	無法回答問題時的回複，預設為sorry。 sorry：抱歉，根據已知資訊無法回答該問題。 uncertain：我不知道。	sorry
options.chat.prompt_config.language	string	否	回答問題使用的語言，預設為Chinese。 Chinese：中文。 English：英語。 Thai：泰語。 Korean：韓語。	Chinese
options.chat.prompt_config.role	boolean	否	是否開啟回答角色。開啟後，將定製回答的角色。	false
options.chat.prompt_config.role_name	string	否	定製回答的角色，例如：AI Assistant。	AI Assistant
options.chat.prompt_config.out_format	string	否	輸出內容的形式，預設為text。 text：文本。 table：表格。 list：列項。 markdown：markdown。	text
options.chat.generate_config.repetition_penalty	float	否	用於控制模型產生時連續序列中的重複度。提高repetition_penalty時可以降低模型產生的重複度，1.0表示不做懲罰。沒有嚴格的取值範圍。	1.01
options.chat.generate_config.top_k	integer	否	產生時，採樣候選集的大小。例如，取值為50時，僅將單次產生中得分最高的50個token組成隨機採樣的候選集。取值越大，產生的隨機性越高；取值越小，產生的確定性越高。預設值為0，表示不啟用top_k策略，此時，僅有top_p策略生效。	50
options.chat.generate_config.top_p	float	否	產生過程中核採樣方法機率閾值，例如，取值為0.8時，僅保留機率加起來大於等於0.8的最可能token的最小集合作為候選集。取值範圍為（0,1.0)，取值越大，產生的隨機性越高；取值越低，產生的確定性越高。	0.5
options.chat.generate_config.temperature	float	否	用於控制隨機性和多樣性的程度。具體來說，temperature值控制了產生文本時對每個候選詞的機率分布進行平滑的程度。較高的temperature值會降低機率分布的峰值，使得更多的低機率詞被選擇，產生結果更加多樣化；而較低的temperature值則會增強機率分布的峰值，使得高機率詞更容易被選擇，產生結果更加確定。取值範圍：[0, 2)，不建議取值為0，無意義。 python version >=1.10.1 java version >= 2.5.1	0.7
options.chat.history_max	integer	否	多輪對話歷史最大輪數，最大20輪，預設是1。	20
options.chat.link	boolean	否	是否返回連結。控制模型產生的內容是否標識內容引用的來源。取值： true: 內容包含來源。 false: 不包含。預設為false。包含內容的返回資訊執行個體如下：可以通過線上擴容和離線擴容兩種方式擴容ECS雲端硬碟容量[^1^]。線上擴容無需重啟執行個體，離線擴容需要重啟執行個體[^1^]。具體操作步驟為：在ECS控制台上選擇待擴容的雲端硬碟，在操作列選擇擴容，然後根據需要選擇擴容方式[^1^]。如果需要擴容分區和檔案系統，可以通過控制台擷取或者通過控制台擷取[^2^]。擴容雲端硬碟容量後，新容量生效後無法再縮小，建議合理規劃儲存空間[^3^]。其中被`[^`和`^]`包起來的數字表示引用結果中reference裡的第幾個文檔。例如`[^1^]`表示應用reference中的第一個文檔。	false
options.chat.agent	map	否	設定RAG工具能力的選項，當開啟時，模型會根據已有的內容，輸出決定是否要執行對應的工具。目前支援該功能大模型有： qwen-plus qwen-max qwen2-72b-instruct
options.chat.agent.tools	list of string	否	設定使用的RAG工具名字，目前可用的工具： knowledge_search：知識庫檢索	["knowledge_search"]
options.retrieve	map	否	用來設定額外的請求參數，使用者控制召回、模型、prompt等。
options.retrieve.doc	map	否	用來設定控制召回相關的參數。
options.retrieve.doc.disable	boolean	否	是否關閉知識庫召回。 false：不關閉，預設為fasle。 true：關閉。	false
options.retrieve.doc.filter	string	否	從知識庫中召回篩選條件的資料時，需要明確指定相應的欄位及滿足的條件。預設為空白。filter使用樣本可參考：filter參數。支援的欄位： table：文檔所在表。 raw_pk：文檔主鍵。 category：文檔分類。 score：文檔分數。 timestamp：文檔時間。樣本格式： `"filter" : "raw_pk=\"123\"" # 只從id為123的doc中擷取資料 "filter" : "category=\"value1\"" # 只從category為value1的doc中擷取資料 "filter" : "category=\"value1\" OR category=\"value2\"" #只從category為value1和value2的doc中擷取資料 "filter" : "score>1.0" # 只從score大於1.0的doc中擷取資料 "filter" : "timestamp>1356969600" # 只從timestamp大於2013-1-1的doc中擷取資料`	category=\"value1\"
options.retrieve.doc.sf	float	否	控制向量召回的向量分的閾值。當沒有開啟稀疏向量時，取值範圍為[0, 2.0]，預設值是1.3，該值越小，結果越相關，但結果數會越少；反之，可能會召回不太相關的結果。但開啟了稀疏向量時，預設值是0.35。其值越大，召回的結果越相關，結果數會越少；反之，結果可能會不太相關。	1.3
options.retrieve.doc.top_n	integer	否	召回的文檔數量，預設為5個，取值範圍：(0, 50]。	5
options.retrieve.doc.formula	string	否	指定召回時，文檔排序的排序公式。說明文法請參考業務排序函數，其中的演算法相關性和地理位置相關性的特徵不支援。	-timestamp: 按文檔的timestamp欄位降序
options.retrieve.doc.rerank_size	integer	否	開啟rerank重排功能時，參與重排的文檔數。預設值為30，取值範圍：(0,100]。	30
options.retrieve.doc.operator	string	否	在知識庫召回時，question.text分詞後的term的關係。該參數只有在沒有啟用稀疏向量時生效。 AND：表示所有term都需要出現才能被召回。預設為AND。 OR：表示只要有一個term出現就可以召回。	AND
options.retrieve.doc.dense_weight	float	否	開啟稀疏向量後，控制文檔召回時，稠密向量的權重。取值範圍：(0.0, 1.0)，預設值為0.7。	0.7
options.retrieve.entry	map	否	用來控制從人工幹預資料中召回結果的相關參數
options.retrieve.entry.disable	boolean	否	是否關閉人工幹預資料的召回。 false：不關閉，預設為false。 true：關閉。	false
options.retrieve.entry.sf	float	否	控制召回人工幹預的向量分閾值。取值範圍：[0, 2.0]，預設值是0.3，該值越小，結果越相關，但結果數會越少；反之，可能會召回不太相關的結果。	0.3
options.retrieve.image	map	否	用來控制從知識庫中召回圖片結果的相關參數。
options.retrieve.image.disable	boolean	否	是否需要關閉圖片資料的召回，預設為false。 false：不關閉，預設為false。 true：關閉。	false
options.retrieve.image.sf	float	否	控制向量召回的向量分的閾值。當沒有開啟稀疏向量時，取值範圍：[0, 2.0]，預設值為1.0，該值越小，結果越相關，但結果數會越少；反之，可能會召回不太相關的結果。但開啟了稀疏向量時，預設值為0.5。其值越大，召回的結果越相關，結果數會越少；反之，結果可能會不太相關。	1.0
options.retrieve.image.dense_weight	float	否	開啟稀疏向量後，控製圖片召回時，稠密向量的權重。取值範圍：(0.0, 1.0)，預設值為0.7。	0.7
options.retrieve.qp	map	否	使用者query改寫的選項。
options.retrieve.qp.query_extend	boolean	否	是否對使用者query進行擴充，擴充query會用來在引擎中召迴文檔切片。預設為false。預設為false，和原來邏輯保持一致，即表示不進行query擴充。如果設定為true，則會多一次與大模型的互動，所以回複速度會變慢。對耗時敏感的應用請勿開啟。	false
options.retrieve.qp.query_extend_num	integer	否	開啟相似query擴充時，最多擴充幾個query，預設值為5。	5
options.retrieve.rerank	map	否	使用者佈建文檔召回時重排的選項。
options.retrieve.rerank.enable	boolean	否	是否對召回的結果用模型進行相關性的重排。取值： true：用模型對召回結果進行重排。 false：不用模型對召回結果進行重排。當options.retrieve.doc.formula不為空白時，預設為false，其他情況預設為true。	true
options.retrieve.rerank.model	string	否	用於重排的大模型名稱。 ops-bge-reranker-larger：bge-reranker模型（預設） ops-text-reranker-001：自研的reranker模型	ops-bge-reranker-larger
options.retrieve.return_hits	boolean	否	是否在結果中返迴文檔召回的結果，即response中的search_hits。	false

請求體樣本

{
    "question" : {
        "text" : "user question",
        "session" : "對話的session，設定了之後，會有多輪對話的功能",
        "type" : "TEXT"
    },
    "options": {
        "chat": {
            "disable" : false, # 是否不走chat模型，僅作文檔召回，預設為false。
            "stream" : false, # 是否流式返回，預設false。
            "model" : "Qwen", # 選擇的LLM模型
            "prompt_template" : "user_defined_prompt_name", # 使用者自定的prompt名稱
            "prompt_config" : { # 自訂prompt配置，可選
                "key" : "value" # key和value在實際使用時應替換為具體的索引值對
            },
            "generate_config" : {
                "repetition_penalty": 1.01,
                "top_k": 50,
                "top_p": 0.5,
                "temperature": 0.7
            },
            "history_max": 20, # 多輪對話歷史最大輪數,
            "link": false, # 返回連結,
            "agent":{
                "tools":["knowledge_search"]
            }
        },
        "retrieve": {
            "doc": {
                "disable": false, # 是否需要關閉文檔召回，預設false。
                "filter": "category=\"type\"", # 召回時根據category欄位做過濾，預設為空白
                "sf": 1.3,    # 向量召回閾值，預設1.3；閾值越大，文檔可能約不相關
                "top_n": 5,    # 文檔召回多少個文檔，預設是5個，取值返回(0, 50],
                "formula" : "", #預設為向量相似性
                "rerank_size" : 5,  #精排文檔數，預設不用設定，系統自己決定
                "operator":"OR"  # 表示文本召回時，文本token之間的關係是OR，預設是AND
            },
            "entry": {
                "disable": false, # 是否需要關閉人工幹預資料的召回，預設false。
                "sf": 0.3 # 幹預資料召回的向量相關性，預設0.3
            },
            "image": {
                "disable": false,  # 是否需要關閉圖片資料的召回，預設false。
                "sf": 1.0          # 圖片資料召回的向量相關性，預設1.0
            },
            "qp": {
                "query_extend": false, # 是否需要對使用者query進行query擴充
                "query_extend_num": 5 # 表示擴充query的數量，預設值為5
            },
            "rerank" : {
                "enable": true  # 召回後是否使用大模型進行重排，預設為true,
                "model":"model_name" # 實際使用時應替換為具體的模型名稱
            },
            "return_hits": false   # 是否在結果中返迴文檔召回的結果, 即response裡面的search_hits
        }
    }
}

返回參數

參數	類型	描述
request_id	string	請求ID。
status	string	請求的處理狀態。 OK：表示請求成功。 FAIL：表示請求失敗。
latency	float	請求成功時，伺服器處理請求所花費的時間，單位為毫秒。
id	integer	主鍵ID。
title	string	文檔的標題。
category	string	類目名。
url	string	文檔連結。
answer	string	問答結果。
type	string	返回結果類型。
scores	array	文檔內容分。
code	string	返回的錯誤碼。
message	string	返回的錯誤資訊。

響應體樣本

{
  "request_id": "6859E98D-D885-4AEF-B61C-9683A0184744",
  "status": "OK",
  "latency": 6684.410397,
  "result" : {
    "data" : [
      {
        "answer" : "answer text",
        "type" : "TEXT",
        "reference" : [
          {"url" : "http://....","title":"doc title"}
    		]
      },
      {
        "reference": [
          {"id": "16","title": "測試標題","category": "測試類別目","url": "測試連結"}
        ],
        "answer": "https://ecmb.bdimg.com/tam-ogel/-xxxx.jpg",
        "type": "IMAGE"
      }
    ],
    "search_hits" : [  // 查詢請求中設定了options.retrieve.return_hits才會有
      {
        "fields" : {
          "content" : "...."
          "key1" : "value1"
        },
        "scores" : ["10000.1234"],
        "type" : "doc"
      },
      {
        "fields"{
          "answer" : "...",
          "key1" : "value1"
        },
        "scores" : ["10000.1234"],
        "type" : "entry"
      }
    ]
  }
  "errors" : [
    {
      "code" : "如果有錯誤，這裡填錯誤碼",
      "message" : "如果有錯誤，這裡填錯誤資訊"
    }
  ]
}