使用QueryKnowledgeBasesContent从多个文档库检索向量与元数据并合并多路召回结果-云原生数据仓库AnalyticDB-阿里云

用自然语句从多个指定文档库检索向量和元数据，合并多路召回结果后返回。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
gpdb:QueryKnowledgeBasesContent	create	*Document `acs:gpdb:{#regionId}:{#accountId}:document/{#DBInstanceId}`	无	无

请求参数

名称	类型	必填	描述	示例值
DBInstanceId	string	是	实例 ID。说明您可以调用 DescribeDBInstances 接口查看目标地域下所有的 AnalyticDB PostgreSQL 实例的详情，包括实例 ID。	gp-xxxxxxxxx
RegionId	string	是	实例所在的地域 ID。	cn-beijing
Content	string	是	用于检索的文本内容。	ADBPG是什么？
MergeMethod	string	否	多知识库合并的方法，默认为 RRF，可选项： RRF Weight	RRF
MergeMethodArgs	object	否	各个 SourceCollection 的合并方法的参数。
Rrf	object	否	指定 MergeMethod 为 RRF 时，可配置的参数。
K	long	否	指定计算分数的算法的 1/(k+rank_i)中的 k 常数，范围大于 1 的正整数。	60
Weight	object	否	指定 MergeMethod 为 Weight 时，可配置的参数。
Weights	array	否	各个 SourceCollection 的权重数组。
	double	否	各个 SourceCollection 的权重。	0.5
RerankFactor	double	否	重排因子。当该值不为空时，会对向量检索结果再做一次重排。取值范围：1<RerankFactor<=5。说明当文档切分稀疏时，重排效率慢。建议重排个数（TopK*Factor（向上取整））不超过 50。	2
SourceCollection	array<object>	是	要检索的多个 Collection 信息。
	object	是	知识库
Collection	string	是	文档库名称。说明由 CreateDocumentCollection 接口创建。您可以调用 ListDocumentCollections 接口查看已经创建的文档库。	knowledge22
Namespace	string	否	命名空间。说明您可以通过 CreateNamespace 接口创建，通过 ListNamespaces 接口查看列表。	ns_cloud_index
NamespacePassword	string	是	命名空间对应的密码。说明本值为 CreateNamespace 接口指定。	ns_password
QueryParams	object	否	要更新的数据的过滤条件，格式为 SQL 的 WHERE 格式。
Filter	string	否	要查询的数据的过滤条件，格式为 SQL 的 WHERE 格式。是一个返回布尔值（真或假）的表达式，条件可以是简单的比较运算符，如等于(=)、不等于(<>或!=)、大于(>), 小于(<)、大于等于(>=)、小于等于(<=)，也可以是逻辑运算符（AND, OR, NOT）组合的更复杂的表达式，以及使用 IN、BETWEEN、LIKE 等关键字的条件。说明详细语法可参考：https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/	id = 'llm-52tvykqt6u67iw73_j6ovptwjk7_file_6ce3da1f7e69495d9f491f2180c86973_11967297'
GraphEnhance	boolean	否	是否开启知识图谱增强。默认值：false。	true
GraphSearchArgs	object	否	返回 top 数量的实体和关系边。默认值：60。
GraphTopK	long	否	返回 top 数量的实体和关系边。默认值：60。	60
HybridSearch	string	否	双路召回算法，默认为空(即直接将向量和全文的分数比较并排序)。可选值： RRF：倒数排序融合(Reciprocal rank fusion)，有一个参数 k 控制融合效果，详见 HybridSearchArgs 配置； Weight：比重排序，采用一个参数 alpha 控制向量和全文的分数比重，然后再排序，参数详见 HybridSearchArgs 配置； Cascaded：先全文检索再在其基础上进行向量检索；	Cascaded
HybridSearchArgs	object	否	双路召回的算法参数。目前支持 RRF 和 Weight 两种： RRF：指定计算分数的算法的`1/(k+rank_i)`中的 k 常数，范围大于 1 的正整数，格式为： `{ "RRF": { "k": 60 } }` Weight: 计算公式`alpha * vector_score + (1-alpha) * text_score`，参数 alpha 表示向量和全文的检索分数比重，范围为 0～1，其中 0 表示只全文，1 表示只向量： `{ "Weight": { "alpha": 0.5 } }`
	any	否	参数配置值。	{ "RRF": { "k": 60 } }
Metrics	string	否	向量构建索引时的方法。取值说明： l2：欧氏距离。 ip：点积（内积）距离。 cosine：余弦相似度。	cosine
RecallWindow	array	否	召回窗口。当该值不为空时，增加返回检索结果的上下文。格式为 2 个元素的数组：List<A, B>，其中-10<=A<=0，0<=B<=10。说明推荐当文档切分过碎、检索可能会丢失上下文信息时使用该参数。重排优先窗口化，即先 rerank，再窗口化处理。
	long	否	召回窗口范围值。	[0,0]
RerankFactor	double	否	重排因子。当该值不为空时，会对向量检索结果再做一次重排。取值范围：1<RerankFactor<=5。说明当文档切分稀疏时，重排效率慢。建议重排个数（TopK*Factor（向上取整））不超过 50。	2.0
TopK	long	否	设置返回 top 结果数量。	776
UseFullTextRetrieval	boolean	否	是否使用全文检索（双路召回）。默认为 false，仅采用向量检索。	false
OrderBy	string	否	默认为空，表示排序的依据字段。字段必须属于 metadata 或表里的默认字段比如 id，格式支持：单个字段，如 chunk_id；多个字段，用逗号连接，如 block_id, chunk_id；支持反序，如: block_id DESC, chunk_id DESC；	file_id,sort_num
Offset	integer	否	偏移量，用于分页查询	20
TopK	long	否	经过多路召回合并后，设置返回 top 结果数量。	10

返回参数

名称	类型	描述	示例值
	object
RequestId	string	请求 ID。	ABB39CC3-4488-4857-905D-2E4A051D0521
Message	string	返回信息。	success
Status	string	API 执行状态，取值如下： success：执行成功。 fail：执行失败。	success
Matches	array<object>	单条记录。
MatchList	object	单条记录。
Id	string	向量数据的唯一 Id。	doca-1234
Content	string	文本内容。	云原生数据仓库AnalyticDB PostgreSQL版提供简单、快速、经济高效的PB级云端数据仓库解决方案。
Metadata	object	元数据 Map。
	string	元数据 Map 值。	{\"pic_id\":\"text\",\"pic_name\":\"text\",\"pic_url\":\"text\"}
FileName	string	文件名。	my_doc.txt
Score	double	此条数据的相似度分数，其分数算法和创建索引时指定的算法(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	double	重排分数。	6.2345
EmbeddingTokens	string	向量化时使用的 token 数。说明 token 是指将输入的文本分割成的最小单位；token 可以是一个单词、一个词组、一个标点符号、一个字符等。	100
Usage	object	本次查询的资源使用量
EmbeddingTokens	string	向量化时使用的 token 数。说明 token 是指将输入的文本分割成的最小单位；token 可以是一个单词、一个词组、一个标点符号、一个字符等。	475
EmbeddingEntries	string	向量化时使用的条目数。说明条目是指对文字、图片做向量化处理时的处理数目，如对文字做一次处理，条目数是 1，对图片做一次处理是 2。	10
Entities	array<object>	实体详情。
entities	object	实体详情。
Id	string	实体 Id。	1
Entity	string	实体名称。	Dr. Wang
Type	string	实体类型。	人物
Description	string	实体描述。	A former advisor at DeepMind.
FileName	string	文件名。	my_doc.txt
Relations	array<object>	关系边详情。
relations	object	关系边详情。
Id	string	关系边 Id。	1
SourceEntity	string	源实体。	DeepMind前顾问
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 PostgreSQL版提供简单、快速、经济高效的PB级云端数据仓库解决方案。",
        "Metadata": {
          "key": "{\\\"pic_id\\\":\\\"text\\\",\\\"pic_name\\\":\\\"text\\\",\\\"pic_url\\\":\\\"text\\\"}"
        },
        "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
      }
    ]
  },
  "EmbeddingTokens": 100,
  "Usage": {
    "EmbeddingTokens": 475,
    "EmbeddingEntries": 10
  },
  "Entities": {
    "entities": [
      {
        "Id": 1,
        "Entity": "Dr. Wang",
        "Type": "人物",
        "Description": "A former advisor at DeepMind.",
        "FileName": "my_doc.txt"
      }
    ]
  },
  "Relations": {
    "relations": [
      {
        "Id": 1,
        "SourceEntity": "DeepMind前顾问",
        "TargetEntity": "Dr. Wang",
        "Description": "Dr. Wang previously served as an advisor at DeepMind.",
        "FileName": "my_doc.txt\n"
      }
    ]
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

变更时间	变更内容概要	操作
2025-10-30	新增 OpenAPI	查看变更详情