調用QueryContent API以自然語言檢索文檔中的向量和中繼資料-雲原生資料倉儲AnalyticDB-阿里雲 -

用自然語句從指定文件庫檢索向量和中繼資料。

調試

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

調試

授權資訊

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

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

操作

存取層級

資源類型

條件關鍵字

關聯操作

gpdb:QueryContent

create

*Document

acs:gpdb:{#regionId}:{#accountId}:document/{#DBInstanceId}

無

請求參數

名稱	類型	必填	描述	樣本值
DBInstanceId	string	是	執行個體 ID。說明您可以調用 DescribeDBInstances 介面查看目標地區下所有的 AnalyticDB PostgreSQL 執行個體的詳情，包括執行個體 ID。	gp-xxxxxxxxx
Namespace	string	否	命名空間，預設為 public。說明您可以通過 CreateNamespace 介面建立，通過 ListNamespaces 介面查看列表。	mynamespace
Collection	string	是	文件庫名稱。說明由 CreateDocumentCollection 介面建立。您可以調用 ListDocumentCollections 介面查看已經建立的文件庫。	document
RegionId	string	是	執行個體所在的地區 ID。	cn-hangzhou
NamespacePassword	string	是	命名空間對應的密碼。說明本值為 CreateNamespace 介面指定。	testpassword
Content	string	否	用於檢索的常值內容。	What is AnalyticDB for PostgreSQL?
Filter	string	否	要查詢的資料的過濾條件，格式為 SQL 的 WHERE 格式。是一個返回布爾值（真或假）的運算式，條件可以是簡單的比較子，如等於(=)、不等於(<>或!=)、大於(>), 小於(<)、大於等於(>=)、小於等於(<=)，也可以是邏輯運算子（AND, OR, NOT）組合的更複雜的運算式，以及使用 IN、BETWEEN、LIKE 等關鍵字的條件。說明詳細文法可參考：https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/	title = 'test' AND name like 'test%'
RecallWindow	array	否	召回視窗。當該值不為空白時，增加返回檢索結果的上下文。格式為 2 個元素的數組：List<A, B>，其中-10<=A<=0，0<=B<=10。說明推薦當文檔切分過碎、檢索可能會丟失上下文資訊時使用該參數。重排優先視窗化，即先 rerank，再視窗化處理。
	integer	否	召回視窗大小。	[-5, 5]
TopK	integer	否	返回 top 數量的結果。	10
RerankFactor	number	否	重排因子。當該值不為空白時，會對向量檢索結果再做一次重排。取值範圍：1<RerankFactor<=5。說明當文檔切分稀疏時，重排效率慢。建議重排個數（TopK*Factor（向上取整））不超過 50。	2
UseFullTextRetrieval	boolean	否	（參數廢棄）是否使用全文檢索索引（雙路召回）。預設為 false，僅採用向量檢索。	true
Metrics	string	否	檢索時的相似性演算法。此值為空白時則採用建立知識庫時指定的演算法，建議如無特殊需求不需設定。說明取值說明： l2：歐氏距離。 ip：點積（內積）距離。 cosine：餘弦相似性。	cosine
FileName	string	否	以圖搜圖情境中，待搜尋的圖片源檔案名稱。說明圖片檔案必須帶有檔案尾碼，當前支援的圖片尾碼：bmp、jpg、jpeg、png、 tiff。	test.jpg
FileUrl	string	否	以圖搜圖情境中，公網可訪問的圖片檔案 URL 地址。說明圖片檔案必須帶有檔案尾碼，當前支援的圖片尾碼：bmp、jpg、jpeg、png、tiff。	https://xx/myImage.jpg
IncludeVector	boolean	否	是否返迴向量。預設為 false。說明 false：不返迴向量。 true：返迴向量。	true
HybridSearch	string	否	多路召回演算法，預設為空白(即直接將稠密向量和全文的分數比較並排序)。可選值： RRF：倒數排序融合(Reciprocal rank fusion)，有一個參數 k 控制融合效果，詳見 HybridSearchArgs 配置； Weight：比重排序，採用參數控制向量和全文的分數比重，然後再排序，參數詳見 HybridSearchArgs 配置； Cascaded：先全文檢索索引再在其基礎上進行向量檢索；	RRF
HybridSearchArgs	object	否	多路召回的演算法參數。目前支援 RRF 和 Weight 兩種。HybridPathsSetting 可以指定召回稠密向量（dense）、稀疏向量（sparse）和全文檢索索引（fulltext），如果值為空白，預設召回稠密向量（dense）和全文檢索索引（fulltext）。 RRF：指定計算分數的演算法的`1/(k+rank_i)`中的 k 常數，範圍大於 1 的正整數，格式為： `{ "HybridPathsSetting": { "paths": "dense,fulltext" }, "RRF": { "k": 60 } }` Weight: 雙路召回（不指定 HybridPathsSetting，僅指定 alpha）：計算公式：alpha * dense_score + (1-alpha) * fulltext_score，參數 alpha 表示稠密向量和全文的檢索分數比重，範圍為 0～1，其中 0 表示只全文，1 表示只稠密向量： `{ "Weight": { "alpha": 0.5 } }` 三路召回模式：計算公式：normalized_dense * dense_score + normalized_sparse * sparse_score + normalized_fulltext * fulltext_score。其中 dense、sparse、fulltext 分別代表稠密向量、稀疏向量、全文檢索索引的權重，取值範圍大於等於 0。系統會自動將權重歸一化到 0～1（即 normalized_x = x / (dense + sparse + fulltext)）。 `{ "HybridPathsSetting": { "paths": "dense,sparse,fulltext" }, "Weight": { "dense": 0.5, "sparse": 0.3, "fulltext": 0.2 } }`
	object	否	多路召回的參數名。
	any	否	參數值。	{ "HybridPathsSetting": { "paths": "dense,fulltext" }, "RRF": { "k": 60 } }
IncludeMetadataFields	string	否	預設為空白，表示要返回的 metadata 欄位，多個欄位用逗號分隔。	title,page
IncludeFileUrl	boolean	否	是否同步返迴文檔的連結地址，預設不返回。	false
UrlExpiration	string	否	返回圖片 URL 的有效期間。說明取值說明支援以秒（s）和日（d）為單位。例如 300s 代錶鏈接有效期間為 300 秒，60d 代錶鏈接有效期間為 60 天。取值範圍在 60s ~ 365d 之間。預設值：7200s，即 2 小時	7200s
GraphEnhance	boolean	否	是否開啟知識圖譜增強。預設值：false。	false
GraphSearchArgs	object	否	知識圖譜檢索參數。
GraphTopK	integer	否	返回 top 數量的實體和關係邊。預設值：60。	60
RerankModel	object	否	重排模型參數
Name	string	否	重排模型名，可選：qwen3-rerank, gte-rerank-v2	qwen3-rerank
Instruct	string	否	當 RerankModel.Name 為 qwen3-rerank 時可設定。添加自訂排序任務類型說明，通過該參數可以指導模型採用不同的排序策略。	Given a web search query, retrieve relevant passages that answer the query
OrderBy	string	否	預設為空白，表示排序的依據欄位。欄位必須屬於 metadata 或表裡的預設欄位比如 id，格式支援：單個欄位，如 chunk_id；多個欄位，用逗號串連，如 block_id, chunk_id；支援反序，如: block_id DESC, chunk_id DESC；	created_at
Offset	integer	否	位移量，用於分頁查詢	0

返回參數

名稱	類型	描述	樣本值
	object
RequestId	string	請求 ID。	ABB39CC3-4488-4857-905D-2E4A051D0521
Message	string	返回資訊。	success
Status	string	狀態，取值如下： success：成功。 fail：失敗。	success
Matches	object
MatchList	array<object>	匹配到的列表。
	array<object>	單條記錄。
Id	string	向量資料的唯一 Id。	doca-1234
Content	string	常值內容。	AnalyticDB for PostgreSQL is a massively parallel processing (MPP) data warehouse service compatible with ANSI SQL 2003, the PostgreSQL ecosystem, and the Oracle database ecosystem.
Metadata	object	中繼資料 Map。
	string	中繼資料。	{"title":"test"}
Vector	object
VectorList	array	向量資料 List。
	number	向量資料。	[1.2123,-0.12314,...]
FileName	string	檔案名稱。	my_doc.txt
Score	number	此條資料的相似性分數，其分數演算法和建立索引時指定的演算法(l2/ip/cosine)相關。	0.12345
RetrievalSource	integer	檢索結果的來源。1 表示向量檢索，2 表示全文檢索索引，3 表示雙路召回。	1
LoaderMetadata	string	文檔載入器載入時的元資訊。	{"page_pos": 1}
FileURL	string	查詢結果圖片的公網 URL 地址，有效時間長度預設為 2 小時。可通過入參 UrlExpiration 自行指定有效時間長度	https://xxx-cn-beijing.aliyuncs.com/image/test.png
RerankScore	number	重排分數。	6.2345
WindowMatches	object
windowMatches	array<object>	視窗化匹配到的列表。
	array<object>
WindowMatch	object
windowMatch	array<object>	單個 top 視窗化匹配到的列表。
	array<object>
Id	string	向量資料的唯一 ID。	doca-2345
Content	string	常值內容。	AnalyticDB for PostgreSQL is a massively parallel processing (MPP) data warehouse service compatible with ANSI SQL 2003, the PostgreSQL ecosystem, and the Oracle database ecosystem.
Metadata	object	中繼資料 Map。
	string	中繼資料。	{"title":"test"}
FileName	string	檔案名稱。	my_doc.txt
LoaderMetadata	string	文檔載入器載入時的元資訊。	{"page_pos": 2}
EmbeddingTokens	string	向量化時使用的 token 數。說明 token 是指將輸入的文本分割成的最小單位；token 可以是一個單詞、一個片語、一個標點符號、一個字元等。	100
Usage	object	本次查詢的資源使用量
EmbeddingTokens	string	向量化時使用的 token 數。說明 token 是指將輸入的文本分割成的最小單位；token 可以是一個單詞、一個片語、一個標點符號、一個字元等。	100
EmbeddingEntries	string	向量化時使用的條目數。說明條目是指對文字、圖片做向量化處理時的處理數目，如對文字做一次處理，條目數是 1，對圖片做一次處理是 2。	10
Entities	object
entities	array<object>	實體列表。
	object	實體詳情。
Id	string	實體 Id。	1
Entity	string	實體名稱。	Dr. Wang
Type	string	實體類型。	person
Description	string	實體描述。	A former advisor at DeepMind.
FileName	string	檔案名稱。	my_doc.txt
Relations	object
relations	array<object>	關係邊列表。
	object	關係邊詳情。
Id	string	關係邊 Id。	1
SourceEntity	string	源實體。	DeepMind consultant
TargetEntity	string	目標實體。	Dr. Wang
Description	string	關係邊描述。	Dr. Wang previously served as an advisor at DeepMind.
FileName	string	檔案名稱。	my_doc.txt

樣本

正常返回樣本

JSON格式

{
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "Message": "success",
  "Status": "success",
  "Matches": {
    "MatchList": [
      {
        "Id": "doca-1234",
        "Content": "AnalyticDB for PostgreSQL is a massively parallel processing (MPP) data warehouse service compatible with ANSI SQL 2003, the PostgreSQL ecosystem, and the Oracle database ecosystem.",
        "Metadata": {
          "key": "{\"title\":\"test\"}"
        },
        "Vector": {
          "VectorList": [
            0
          ]
        },
        "FileName": "my_doc.txt",
        "Score": 0.12345,
        "RetrievalSource": 1,
        "LoaderMetadata": "{\"page_pos\": 1}",
        "FileURL": "https://xxx-cn-beijing.aliyuncs.com/image/test.png",
        "RerankScore": 6.2345
      }
    ]
  },
  "WindowMatches": {
    "windowMatches": [
      {
        "WindowMatch": {
          "windowMatch": [
            {
              "Id": "doca-2345",
              "Content": "AnalyticDB for PostgreSQL is a massively parallel processing (MPP) data warehouse service compatible with ANSI SQL 2003, the PostgreSQL ecosystem, and the Oracle database ecosystem.",
              "Metadata": {
                "key": "{\"title\":\"test\"}"
              },
              "FileName": "my_doc.txt",
              "LoaderMetadata": "{\"page_pos\": 2}"
            }
          ]
        }
      }
    ]
  },
  "EmbeddingTokens": "100",
  "Usage": {
    "EmbeddingTokens": "100",
    "EmbeddingEntries": "10"
  },
  "Entities": {
    "entities": [
      {
        "Id": "1",
        "Entity": "Dr. Wang",
        "Type": "person",
        "Description": "A former advisor at DeepMind.",
        "FileName": "my_doc.txt"
      }
    ]
  },
  "Relations": {
    "relations": [
      {
        "Id": "1",
        "SourceEntity": "DeepMind consultant",
        "TargetEntity": "Dr. Wang",
        "Description": "Dr. Wang previously served as an advisor at DeepMind.",
        "FileName": "my_doc.txt\n"
      }
    ]
  }
}

錯誤碼

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

變更歷史

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