調用Retrieve API檢索知識庫-大模型服務平台百鍊-阿里雲 - Alibaba Cloud Model Studio

在指定的知識庫中檢索資訊。

介面說明

調用方式：推薦使用最新版阿里雲百鍊 SDK調用，SDK 已封裝複雜的簽名計算邏輯，可簡化您的調用過程。
許可權要求：
- RAM 使用者（子帳號）：需先擷取阿里雲百鍊的 API 許可權（可使用AliyunBailianDataFullAccess策略，該策略已包含本介面所需的 sfm:Retrieve 許可權點），並加入一個業務空間後，才能調用本介面。
- 阿里雲帳號（主帳號）：預設擁有許可權，可直接調用。
響應延遲：由於介面調用包含複雜的檢索和匹配，回應時間可能較長，建議您合理佈建要求的逾時與重試策略。
等冪性：本介面具有等冪性。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

sfm:Retrieve

none

*全部資源

*

無

請求文法

POST /{WorkspaceId}/index/retrieve HTTP/1.1

路徑參數

名稱	類型	必填	描述	樣本值
WorkspaceId	string	是	知識庫所屬的業務空間 ID。擷取方式請參見如何使用業務空間。	llm-3shx2gu255oqxxxx

請求參數

名稱	類型	必填	描述	樣本值
Query	string	否	輸入文本（原始輸入 prompt）。Query 的長度和字元沒有限制。	阿里雲百鍊平台介紹
DenseSimilarityTopK	integer	否	向量檢索 Top K，通過產生輸入文本的向量並在知識庫中檢索與其向量表示最相似的 K 個文本切片。K 的取值範圍[0-100]。 `DenseSimilarityTopK`和`SparseSimilarityTopK`二者之和小於等於 200。預設值為 100。	100
EnableReranking	boolean	否	是否開啟重排序。更多資訊，請參見知識庫。取值範圍： true：開啟。 false：不開啟。預設值為 true。枚舉值： true : 開啟 false : 不開啟	true
EnableRewrite	boolean	否	是否開啟多輪對話改寫。取值範圍： true：開啟。 false：不開啟。預設值為 false。枚舉值： true : 開啟 false : 不開啟	false
Rerank	array<object>	否	重排序配置。
	object	否	重排序設定物件。
ModelName	string	否	使用指定的排序模型。此處指定值將覆蓋建立知識庫時所選擇的排序模型。取值範圍： gte-rerank-hybrid：官方排序。 gte-rerank：gte-rerank 排序。預設值為空白，使用建立知識庫時選擇的排序模型。說明如僅需語義排序，可使用`gte-rerank`；若同時需要語義排序和文本匹配特徵以確保相關性，建議使用`gte-rerank-hybrid`。枚舉值： gte-rerank-hybrid : gte-rerank(hybrid)排序 gte-rerank : gte-rerank 排序	gte-rerank-hybrid
RerankMode	string	否	該參數暫不開放，請勿傳入。枚舉值： similar: 相似模式。 : similar: 相似模式。 custom: 自訂模式。 : custom: 自訂模式。 qa:（預設值）問答模式。 : qa:（預設值）問答模式。	qa
RerankInstruct	string	否	該參數暫不開放，請勿傳入。
RerankMinScore	number	否	相似性閾值。該閾值表示允許召回的文本切片的最低相似性分數，用於篩選 Rank 模型返回的文本切片，即只有分數超過此數值的文本切片才會被召回。取值範圍[0.01-1.00]。此參數的優先順序大於知識庫相似性閾值配置。當未指定具體值時，預設採用該知識庫配置的相似性閾值。	0.20
RerankTopN	integer	否	重排序後的 Top N 返回資料。取值範圍[1-20]，預設值為 5。	5
Rewrite	array<object>	否	多輪對話改寫配置。
	object	否	多輪對話改寫設定物件。
ModelName	string	否	多輪對話改寫模型名稱。它會基於會話上下文自動調整原始輸入 prompt（使用者問題）以提升檢索效果。取值範圍： conv-rewrite-qwen-1.8b：conv-rewrite-qwen-1.8b 模型（目前只支援該模型）預設值為空白，採用 conv-rewrite-qwen-1.8b 模型。枚舉值： conv-rewrite-qwen-1.8b : conv-rewrite-qwen-1.8b 模型	conv-rewrite-qwen-1.8b
SparseSimilarityTopK	integer	否	關鍵詞檢索 TopK，即在知識庫中尋找與輸入文本的關鍵詞精確匹配的切片。它可以協助您過濾掉無關的文本切片，提供更準確的結果。取值範圍[0-100]。 `DenseSimilarityTopK`和`SparseSimilarityTopK`二者之和小於等於 200。預設值為：100。	100
IndexId	string	是	知識庫 ID，即 CreateIndex 介面返回的`Data.Id`。說明請確保對應知識庫已成功建立且未被刪除。	5pwe0mxxxx
SaveRetrieverHistory	boolean	否	是否儲存歷史文本切片召回測試資料。取值範圍： true：儲存。 false：不儲存。預設值為：false。	false
SearchFilters	array<object>	否	支援通過 SearchFilter 設定個人化的檢索條件（比如標籤），對語義檢索結果進行過濾，以排除與查詢 Query 無關的資訊。設定 is_displayed_chunk_content 參數為 true 生效篩選邏輯，具體內容請參見知識庫 SearchFilters。
	object	否	檢索條件對象。
	string	否
Images	array	否	支援在提問時傳入圖片 URL 地址。
	string	否	檢索圖片問答知識庫時您可傳入圖片 URL 地址。當該知識庫中存在圖片索引時，系統會將輸入圖片轉為向量並檢索到相關記錄；如果不存在圖片索引，則輸入的圖片不會用於檢索。說明本欄位不支援文檔搜尋/資料查詢知識庫（即使傳入也不生效）說明請確保連結公開可訪問且指向一個有效圖片檔案。格式樣本：https://example.com/downloads/pic.jpg	https://example.com/downloads/pic.jpg
QueryHistory	array<object>	否	多輪對話改寫支援您傳入自己管理的對話歷史。僅在 EnableRewrite=true 時生效（否則即使傳入也不生效）。
	object	否
role	string	否	角色。取值範圍： user：傳入此角色，此時 content 表示您輸入給阿里雲百鍊應用的文本。 assistant：傳入此角色，此時 content 表示阿里雲百鍊應用的回複。	user
content	string	否	對應角色的問題或者回答內容。	代表一段文本。
Extra	object	否
uniqueId	string	否

返回參數

名稱	類型	描述	樣本值
	object
Code	string	錯誤狀態代碼。	Index.InvalidParameter
Data	object	介面業務資料欄位。
Nodes	array<object>	命中的文本切片列表。
	object	文本切片對象。
Metadata	any	文本切片的中繼資料 Map。說明文檔搜尋類知識庫的中繼資料 Map 中`file_path`欄位無意義，請勿在業務代碼中使用。說明檢索文檔搜尋類知識庫時，若切片包含圖片，將通過中繼資料 Map 中`image_url`欄位透出，並附有到期時間。	{ "parent": "", "file_path": "https://*", "image_url": [ "http://" ], "nid": "", "title": "阿里雲百鍊文檔", "doc_id": "doc_", "content": "阿里雲百鍊是基於通義大模型、行業大模型以及三方大模型的一站式大模型開發平台。面向企業客戶和個人開發人員，提供完整的模型服務工具和全鏈路應用開發套件，預置豐富的能力外掛程式，提供API及SDK等便捷的整合方式，高效完成大模型應用構建", "workspace_id": "ws_", "hier_title": "阿里雲百鍊文檔", "doc_name": "阿里雲百鍊文檔介紹.pdpf", "pipeline_id": "rhd", "_id": "ws_**" }
Score	number	文本切片的相似性得分，可能值範圍：[0-1]。	0.3
Text	string	文本切片內容。	阿里雲百鍊是基於通義大模型、行業大模型以及三方大模型的一站式大模型開發平台。面向企業客戶和個人開發人員，提供完整的模型服務工具和全鏈路應用開發套件，預置豐富的能力外掛程式，提供API及SDK等便捷的整合方式，高效完成大模型應用構建。
Message	string	錯誤資訊。	Required parameter(%s) missing or invalid, please check the request parameters.
RequestId	string	請求 ID。	17204B98-7734-4F9A-8464-2446A84821CA
Status	string	介面返回的狀態代碼。	200
Success	boolean	介面調用是否成功，可能值為： true：成功。 false：失敗。	true

樣本

正常返回樣本

JSON格式

{
  "Code": "Index.InvalidParameter",
  "Data": {
    "Nodes": [
      {
        "Metadata": "{\n  \"parent\": \"\",\n  \"file_path\": \"https://***\",\n  \"image_url\": [\n    \"http://***\"\n  ],\n  \"nid\": \"***\",\n  \"title\": \"阿里雲百鍊文檔\",\n  \"doc_id\": \"doc_***\",\n  \"content\": \"阿里雲百鍊是基於通義大模型、行業大模型以及三方大模型的一站式大模型開發平台。面向企業客戶和個人開發人員，提供完整的模型服務工具和全鏈路應用開發套件，預置豐富的能力外掛程式，提供API及SDK等便捷的整合方式，高效完成大模型應用構建\",\n  \"workspace_id\": \"ws_***\",\n  \"hier_title\": \"阿里雲百鍊文檔\",\n  \"doc_name\": \"阿里雲百鍊文檔介紹.pdpf\",\n  \"pipeline_id\": \"rhd***\",\n  \"_id\": \"ws_***\"\n}",
        "Score": 0.3,
        "Text": "阿里雲百鍊是基於通義大模型、行業大模型以及三方大模型的一站式大模型開發平台。面向企業客戶和個人開發人員，提供完整的模型服務工具和全鏈路應用開發套件，預置豐富的能力外掛程式，提供API及SDK等便捷的整合方式，高效完成大模型應用構建。"
      }
    ]
  },
  "Message": "Required parameter(%s) missing or invalid, please check the request parameters.",
  "RequestId": "17204B98-7734-4F9A-8464-2446A84821CA",
  "Status": "200",
  "Success": true
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。