Retrieve - 檢索知識索引 -

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

介面說明

RAM 使用者（子帳號）需要首先擷取阿里雲百鍊的 API 許可權（需要AliyunBailianDataFullAccess，已包括 sfm:Retrieve 許可權點），並加入一個業務空間後，方可調用本介面。阿里雲帳號（主帳號）可直接調用無須授權。建議您通過最新版阿里雲百鍊 SDK來調用本介面。
調用本介面前，請確保您的知識庫已經建立完成且未被刪除（即知識庫 IDIndexId有效）。
由於介面調用包含複雜的檢索和匹配，回應時間可能較長，建議您合理佈建要求的逾時與重試策略。
本介面具有等冪性。

限流說明： 本介面頻繁調用會被限流，頻率請勿超過 20 次/秒。如遇限流，請稍後重試。

調試

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

調試

授權資訊

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

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

操作

存取層級

資源類型

條件關鍵字

關聯操作

sfm:Retrieve

none

*全部資源

*

無

請求文法

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

請求參數

名稱	類型	必填	描述	樣本值
Query	string	否	輸入文本（原始輸入 prompt）。Query 的長度和字元沒有限制。	阿里雲百鍊平台介紹
DenseSimilarityTopK	integer	否	向量檢索 Top K，通過產生輸入文本的向量並在知識庫中檢索與其向量表示最相似的 K 個文本切片。K 的取值範圍[0-100]。 `DenseSimilarityTopK`和`SparseSimilarityTopK`二者之和小於等於 200。預設值為 100。	100
EnableReranking	boolean	否	是否開啟 Rerank 重排序。更多資訊，請參見知識庫。取值範圍： true：開啟。 false：不開啟。預設值為 true。	true
EnableRewrite	boolean	否	是否開啟多輪會話改寫。取值範圍： true：開啟。 false：不開啟。預設值為 false。	false
Rerank	array<object>	否	Rank 配置。
	object	否	Rank 設定物件。
ModelName	string	否	Rank 模型名稱。更多資訊，請參見知識庫。取值範圍： gte-rerank-hybrid：官方推薦。 gte-rerank：GTE 排序模型。	gte-rerank-hybrid
RerankMinScore	number	否	相似性閾值。該閾值表示允許召回的文本切片的最低相似性分數，用於篩選 Rank 模型返回的文本切片，即只有分數超過此數值的文本切片才會被召回。更多資訊，請參見知識庫。取值範圍[0.01-1.00]。此參數的優先順序大於知識庫相似性閾值配置。當未指定具體值時，預設採用該知識庫配置的相似性閾值。	0.20
RerankTopN	integer	否	Rerank 後的 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
SparseSimilarityTopK	integer	否	關鍵詞檢索 TopK，即在知識庫中尋找與輸入文本的關鍵詞精確匹配的切片。它可以協助您過濾掉無關的文本切片，提供更準確的結果。取值範圍[0-100]。 `DenseSimilarityTopK`和`SparseSimilarityTopK`二者之和小於等於 200。預設值為：100。	100
WorkspaceId	string	是	知識庫所屬的業務空間 ID。擷取方式請參見如何使用業務空間。	llm-3shx2gu255oqxxxx
IndexId	string	是	知識庫 ID，即 CreateIndex 介面返回的`Data.Id`。	5pwe0mxxxx
SaveRetrieverHistory	boolean	否	是否儲存歷史文本切片召回測試資料。取值範圍： true：儲存。 false：不儲存。預設值為：false。	false
SearchFilters	array<object>	否	支援通過 SearchFilter 設定個人化的檢索條件（比如標籤），對語義檢索結果進行過濾，以排除與查詢 Query 無關的資訊。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	否	對應角色的問題或者回答內容。	代表一段文本。

SearchFilters 文法

檢索條件支援子分組，子分組之間預設是 AND 語義，且不可更改。
- 子分組內欄位支援 _operator = AND/OR 邏輯運算子，預設是 AND 語義（大小寫不敏感）。
- 子分組內欄位支援 _conditions =［］嵌套子條件，子條件間邏輯關係預設繼承於父分組的 _operator 邏輯運算子，也可通過 _conditions_operator = AND/OR 自訂。
子分組內過檢索件欄位支援singleQuery單值、multiQuery多值及rangeQuery範圍查詢。
- 單值查詢：數值、字串。
- 多值查詢：數值、字串組成的數組。
- 範圍查詢：支援 eq、neq、like 屬性，一個欄位不可配置多個（大小寫不敏感）區間：支援 gt、gte、lt、lte 屬性，其值建議為數實值型別（大小寫不敏感）。

樣本：

{
  "search_filters": [
    {
      "singleQuery": "stringValue",  // 單值查詢
      "multiQuery": [                // 多值查詢
        "stringValue1",
        "stringValue2"
      ],
      "logicQuery": {                // 邏輯查詢
        "like": "prefix"
      },
      "rangeQuery": {                // 範圍查詢
        "gte": intValue,
        "lte": intValue
      },
      "_conditions": [                // 嵌套子查詢條件
        {
          "singleQuery": intValue
        }
      ]
    },
    {
      "_operator": "OR",                // 多條件查詢
      "singleQuery": "stringValue"
    }
  ]
}

返回參數

名稱	類型	描述	樣本值
	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\t\"parent\": \"\",\n\t\"file_path\": \"https://***\",\n\t\"image_url\": [\n\t  \"http://***\"\n\t],\n\t\"nid\": \"***\",\n\t\t\"title\": \"阿里雲百鍊文檔\",\n\t\"doc_id\": \"doc_***\",\n\t\"content\": \"阿里雲百鍊是基於通義大模型、行業大模型以及三方大模型的一站式大模型開發平台。面向企業客戶和個人開發人員，提供完整的模型服務工具和全鏈路應用開發套件，預置豐富的能力外掛程式，提供API及SDK等便捷的整合方式，高效完成大模型應用構建\",\n\t\"workspace_id\": \"ws_***\",\n\t\"hier_title\": \"阿里雲百鍊文檔\",\n\t\"doc_name\": \"阿里雲百鍊文檔介紹.pdpf\",\n\t\"pipeline_id\": \"rhd***\",\n\t\"_id\": \"ws_***\"\n\t}",
        "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
}

錯誤碼

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

變更歷史

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