調用SearchKnowledge搜尋文檔，文本問答 - OpenSearch

文本問答主要用於從知識庫中擷取內容並進行文本問答查詢。支援多輪對話，可以設定會話ID來保持對話上下文。此外，還可以選擇不同的大語言模型（LLM）來產生回答，並對產生的內容進行定製。

前提條件

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

重要

本介面面向服務端調用設計，不建議在瀏覽器、H5、小程式、App 等前端環境直接調用。原因有二：一是介面通過 Authorization: Bearer <API Key> 鑒權，API Key 為長期有效憑證，寫入前端代碼會暴露給終端使用者、存在被盜用風險；二是該介面通常不支援瀏覽器跨域（CORS），前端直連大機率會被攔截。請由您自己的服務端儲存 API Key 並發起調用，再將結果返回前端。

介面資訊

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

請求URL

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

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

請求參數

Header參數

參數	類型	是否必填	描述	樣本值
Content-Type	string	是	請求的資料格式，"application/json"。	application/json
Authorization	string	是	請求鑒權的API Key，Bearer開頭。	Bearer OS-d1**2a
accept	String	否	SSE請求填寫"text/event-stream"	text/event-stream

Body參數

參數	類型	是否必填	描述	樣本值
question	map	是	輸入的問題。	{ "text":"user question", "type": "TEXT", "session" : "" }
question.text	string	是	使用者輸入的問題常值內容。	user question
question.session	string	否	多輪對話的會話ID，用於標識多輪對話上下文。取值：不設或者為空白，則表示不開啟多輪對話。如設定非空的值，則表示開啟多輪對話，並且系統會將相同的session的對話進行保留，作為多輪對話的上下文。預設保留7天內的最近20輪。	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 opensearch-falcon-7b qwen-turbo qwen-plus qwen-max qwen2-72b-instruct	opensearch-llama2-13b
options.chat.enable_deep_search	boolean	否	是否開啟深度搜尋。 true：開啟深度搜尋，需要多輪推理綜合資料返回結果，單次對話消耗的時間和計算資源相對較多。 false：關閉深度搜尋。	false
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.rich_text_strategy	string	否	富文本LLM輸出後處理方式（如果不存在這個配置或者為空白則不開富文本，預設行為）： inside_response: 回答中的tag直接還原到原文裡，markdown格式（注意表格直接以html形式插入markdown）。 extend_response: 回答中存在富文本tag，每個tag實際內容單獨在rich_text_ref返回：圖片內容url，表格內容html格式，代碼文字格式設定。	inside_response
options.chat.agent	map	否	設定RAG工具能力的選項，當開啟時，模型會根據已有的內容，輸出決定是否要執行對應的工具。目前支援該功能大模型有： qwen-plus qwen-max qwen2-72b-instruct
options.chat.agent.think_process	boolean	否	是否返回思考過程。	true
options.chat.agent.max_think_round	integer	否	思考輪數（最大不超過20）。	10
options.chat.agent.language	string	否	思考過程及回答語言。 AUTO：根據使用者query判斷使用中文還是英文。 CN：中文。 EN：英文。	AUTO
options.chat.agent.tools	list of string	否	設定使用的RAG工具名字，目前可用的工具： knowledge_search：知識庫檢索	["knowledge_search"]
options.retrieve	map	否	用來設定額外的請求參數，使用者控制召回、模型、prompt等。
options.retrieve.web_search.enable	boolean	否	是否開啟連網搜尋。 true：開啟連網搜尋，將根據連網搜尋資料返回結果，單次對話消耗的時間和計算資源相對較多。 false：關閉連網搜尋。	false
doc	map	否	用來設定控制召回相關的參數。
options.retrieve.doc.disable	boolean	否	是否關閉知識庫召回。 false：不關閉，預設為false。 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。其值越大，召回的結果越相關，結果數會越少；反之，結果可能會不太相關。	0.35
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": "什麼是阿里雲OpenSearch？",
    "session": "session_001",
    "type": "TEXT"
  },
  "options": {
    "chat": {
      "disable": false,
      "stream": false,
      "model": "Qwen",
      "history_max": 20,
      "link": false,
      "agent": {
        "tools": ["knowledge_search"]
      }
    },
    "retrieve": {
      "doc": {
        "disable": false,
        "filter": "category=\"type\"",
        "sf": 0.35,
        "top_n": 5,
        "operator": "OR"
      },
      "web_search": { "enable": false },
      "entry": { "disable": false, "sf": 0.3 },
      "image": { "disable": false, "sf": 1.0 },
      "rerank": {
        "enable": true,
        "model": "ops-bge-reranker-larger"
      },
      "return_hits": false
    }
  }
}

關鍵參數說明：

question.session：設定後啟用多輪對話上下文。
options.chat.disable：設為true可跳過LLM，直接返回召回結果。
options.retrieve.doc.top_n：控制召迴文檔數量（預設5）。
options.retrieve.return_hits：設為true時返回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	文檔內容分。
event	string	思考事件。 THINK+ACTION+ANSWER為一輪思考過程（THINK不保證一定返回）。THINK表示思考，ACTION表示執行的動作，ANSWER表示本輪思考結論。SUMMARY為最終回答結果，文本類型的只有一個。
event_status	string	該結果是否完成。 PROCESSING：回答中； FINISHED：回答結束。
code	string	返回的錯誤碼（若無報錯則不返回）。
message	string	返回的錯誤資訊（若無報錯則不返回）。

響應體樣本

成功響應

{
  "request_id": "6859E98D-D885-4AEF-B61C-9683A0184744",
  "status": "OK",
  "latency": 6684.41,
  "result": {
    "data": [
      {
        "answer": "阿里雲OpenSearch是一款結構化資料搜尋託管服務...",
        "type": "TEXT",
        "reference": [
          {"url": "https://www.alibabacloud.com/help/document_detail/463469.html", "title": "OpenSearch產品介紹"}
        ]
      }
    ],
    "search_hits": [
      {
        "fields": {"content": "OpenSearch相關文檔內容...", "title": "OpenSearch介紹"},
        "scores": ["0.9778"],
        "type": "DOC"
      }
    ]
  }
}

錯誤響應

{
  "request_id": "e579a090bf99dc787d29d878b40c8367",
  "status": "FAIL",
  "errors": [
    {"code": 3005, "message": "topN[51] is not in (0, 50]"}
  ]
}