DocsICP FilingConsole
官方文档
首页

QueryKnowledgeBasesContent

更新时间：
复制 MD 格式
我的收藏

Retrieves vectors and metadata from multiple specified document collections by using natural language statements, merges multi-channel recall results, and returns the combined results.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

gpdb:QueryKnowledgeBasesContent

create

*Document

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

 None None

Request parameters

Parameter

Type

Required

Description

Example
DBInstanceId

string

Yes

The instance ID.

Note

You can call the DescribeDBInstances operation to query the details of all AnalyticDB for PostgreSQL instances in a region, including instance IDs.

gp-xxxxxxxxx
RegionId

string

Yes

The region ID of the instance.

cn-beijing
Content

string

Yes

The text content used for retrieval.

What is ADBPG?
MergeMethod

string

No

The method used to merge results from multiple knowledge bases. Default value: RRF. Valid values:

  • RRF

  • Weight.

RRF
MergeMethodArgs

object

No

The parameters for the merge method of each SourceCollection.

Rrf

object

No

The configurable parameters when MergeMethod is set to RRF.

K

integer

No

The k constant in the scoring algorithm 1/(k+rank_i). The value must be a positive integer greater than 1.

60
Weight

object

No

The configurable parameters when MergeMethod is set to Weight.

Weights

array

No

The weight array for each SourceCollection.

number

No

The weight of each SourceCollection.

0.5
RerankFactor

number

No

The reranking factor. If this parameter is not empty, the vector retrieval results are reranked. Valid values: 1 < RerankFactor <= 5.

Note

  • Reranking is slow when document chunks are sparse.

  • The recommended reranking count (TopK × Factor, rounded up) should not exceed 50.

2
RerankModel

object

No

The reranking model parameters for performing an additional reranking on the overall results after multi-channel merging.

Name

string

No

The name of the reranking model. Valid values: qwen3-rerank, gte-rerank-v2.

qwen3-rerank
Instruct

string

No

This parameter can be set when RerankModel.Name is set to qwen3-rerank. Specifies a custom ranking task type description that guides the model to adopt different ranking strategies.

Given a web search query, retrieve relevant passages that answer the query

SourceCollection

array<object>

Yes

The information about the multiple collections to retrieve.

array<object>

No

The knowledge base.

Collection

string

Yes

The name of the document collection.

Note

The document collection is created by calling the CreateDocumentCollection operation. You can call the ListDocumentCollections operation to view existing document collections.

knowledge22
Namespace

string

No

The namespace.

Note

You can create a namespace by calling the CreateNamespace operation and view the list by calling the ListNamespaces operation.

ns_cloud_index
NamespacePassword

string

Yes

The password of the namespace.

Note

This value is specified by the CreateNamespace operation.

ns_password
QueryParams

object

No

The filter conditions for the data to query, in SQL WHERE clause format.

Filter

string

No

The filter conditions for the data to query, in SQL WHERE clause format. This is an expression that returns a Boolean value (true or false). The conditions can be simple comparison operators such as equal to (=), not equal to (<> or !=), greater than (>), less than (<), greater than or equal to (>=), and less than or equal to (<=). They can also be more complex expressions combined with logical operators (AND, OR, NOT), as well as conditions that use keywords such as IN, BETWEEN, and LIKE.

Note

  • For detailed syntax, refer to: https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/.

id = 'llm-52tvykqt6u67iw73_j6ovptwjk7_file_6ce3da1f7e69495d9f491f2180c86973_11967297'
GraphEnhance

boolean

No

Specifies whether to enable knowledge graph enhancement. Default value: false.

true
GraphSearchArgs

object

No

The number of top entities and relationship edges to return. Default value: 60.

GraphTopK

integer

No

The number of top entities and relationship edges to return. The default value is 60.

60
HybridSearch

string

No

The multi-channel recall algorithm. Default value: empty (the scores from dense vectors and full-text retrieval are directly compared and sorted).

Valid values:

  • RRF: reciprocal rank fusion. A parameter k controls the fusion effect. For more information, see the HybridSearchArgs configuration.

  • Weight: weighted ranking. Parameters control the score weights of vector retrieval and full-text retrieval before sorting. For more information, see the HybridSearchArgs configuration.

  • Cascaded: full-text retrieval is performed first, followed by vector retrieval on the full-text results.

Cascaded
HybridSearchArgs

object

No

The algorithm parameters for multi-channel recall. RRF and Weight are supported. HybridPathsSetting specifies the recall paths: dense vectors (dense), sparse vectors (sparse), and full-text retrieval (fulltext). If this value is empty, dense vectors (dense) and full-text retrieval (fulltext) are used by default.

  • RRF: specifies the k constant in the scoring algorithm 1/(k+rank_i). The value must be a positive integer greater than 1. Format:

{
  "HybridPathsSetting": {
    "paths": "dense,fulltext"
  },
  "RRF": {
    "k": 60
  }
}
  • Weight:
    • Dual-path recall (without specifying HybridPathsSetting, only specifying alpha):

      • Formula: alpha * dense_score + (1-alpha) * fulltext_score. The alpha parameter specifies the score weight between dense vectors and full-text retrieval. Valid values: 0 to 1, where 0 indicates full-text retrieval only and 1 indicates dense vectors only:

{ 
   "Weight": {
    "alpha": 0.5
   }
}
  • Three-path recall pattern:

    • Formula: normalized_dense * dense_score + normalized_sparse * sparse_score + normalized_fulltext * fulltext_score. dense, sparse, and fulltext represent the weights for dense vectors, sparse vectors, and full-text retrieval respectively. Valid values: greater than or equal to 0. The system automatically performs normalization on the weights to 0 to 1 (normalized_x = x / (dense + sparse + fulltext)).

{
  "HybridPathsSetting": {
     "paths": "dense,sparse,fulltext"
   },
  "Weight": {
    "dense": 0.5,
    "sparse": 0.3,
    "fulltext": 0.2
  }
}

any

No

Metrics

string

No

The method used to build the vector index. Valid values:

  • l2: Euclidean distance.

  • ip: inner product distance.

  • cosine: cosine similarity.

cosine
RecallWindow

array

No

The recall window. If this value is not empty, the context of the retrieval results is included. The format is a two-element array: List<A, B>, where -10 <= A <= 0 and 0 <= B <= 10.

Note

  • Use this parameter when document chunks are too small and retrieval may lose context information.

  • Reranking takes priority over windowing. Reranking is performed first, followed by windowing.

integer

No

The recall window range value.

[0,0]
RerankFactor

number

No

The reranking factor. If this parameter is not empty, the vector retrieval results are reranked. Valid values: 1 < RerankFactor <= 5.

Note

  • Reranking is slow when document chunks are sparse.

  • The recommended reranking count (TopK × Factor, rounded up) should not exceed 50.

2.0
RerankModel

object

No

The reranking model parameters.

Name

string

No

The name of the rerank model. Valid values: qwen3-rerank and gte-rerank-v2.

qwen3-rerank
Instruct

string

No

This parameter can be set only when RerankModel.Name is qwen3-rerank. Use this parameter to provide a custom instruction that guides the model's ranking strategy.

Given a web search query, retrieve relevant passages that answer the query

RerankMetadataFields

string

No

TopK

integer

No

The number of top results to return.

776
UseFullTextRetrieval

boolean

No

Specifies whether to use full-text retrieval (dual-path recall). Default value: false, which indicates that only vector retrieval is used.

false
OrderBy

string

No

The field used for sorting. Default value: empty.

The field must belong to metadata or a default field in the table, such as id. Supported formats:

A single field, such as chunk_id. Multiple fields separated by commas, such as block_id, chunk_id. Descending order is supported, such as block_id DESC, chunk_id DESC.

file_id,sort_num
Offset

integer

No

The offset for paging query.

20
TopK

integer

No

The number of top results to return after multi-channel recall merging.

10

Response elements

Element

Type

Description

Example

object

RequestId

string

The request ID.

ABB39CC3-4488-4857-905D-2E4A051D0521
Message

string

The returned message.

success
Status

string

The API execution status. Valid values:

  • success: The execution is successful.

  • fail: The execution failed.

success
Matches

object

MatchList

array<object>

The individual record.

array<object>

The individual record.

Id

string

The unique ID of the vector data.

doca-1234
Content

string

The text content.

AnalyticDB for PostgreSQL provides a simple, fast, and cost-effective PB-level cloud data warehousing solution.
Metadata

object

The metadata.

string

The value of a metadata entry.

{\"pic_id\":\"text\",\"pic_name\":\"text\",\"pic_url\":\"text\"}
FileName

string

The file name.

my_doc.txt
Score

number

The similarity score. The scoring algorithm depends on the distance metric (l2, ip, or cosine) that you specified when you created the index.

0.12345
RetrievalSource

integer

The retrieval source. Valid values: 1 (vector retrieval), 2 (full-text search), and 3 (dual-path retrieval).

1
LoaderMetadata

string

The metadata from the document loader.

{"page_pos": 1}
FileURL

string

The public URL of the file. The URL is valid for 2 hours by default.

You can specify a custom validity period by using the UrlExpiration parameter.

https://xxx-cn-beijing.aliyuncs.com/image/test.png
RerankScore

number

The reranking score.

6.2345
EmbeddingTokens

string

The number of tokens used during vectorization.

Note

A token is the smallest unit into which the input text is split. A token can be a word, a phrase, a punctuation mark, or a character.

100
Usage

object

The resource usage of this query.

EmbeddingTokens

string

The number of tokens used during vectorization.

Note

A token is the smallest unit into which the input text is split. A token can be a word, a phrase, a punctuation mark, or a character.

475
EmbeddingEntries

string

The number of entries used during vectorization.

Note

An entry refers to the number of items processed during vectorization of text or images. For example, processing text once counts as 1 entry, and processing an image once counts as 2 entries.

10
Entities

object

entities

array<object>

The entity details.

object

The entity details.

Id

string

The entity ID.

1
Entity

string

The entity name.

Dr. Wang
Type

string

The entity type.

Person
Description

string

The entity description.

A former advisor at DeepMind.
FileName

string

The file name.

my_doc.txt
Relations

object

relations

array<object>

The relationship edge details.

object

The relationship edge details.

Id

string

The ID of the relationship edge.

1
SourceEntity

string

The source entity.

Former DeepMind advisor
TargetEntity

string

The target entity.

Dr. Wang
Description

string

The description of the relationship edge.

Dr. Wang previously served as an advisor at DeepMind.
FileName

string

The file name.

my_doc.txt

Examples

Success response

JSON format

{
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "Message": "success",
  "Status": "success",
  "Matches": {
    "MatchList": [
      {
        "Id": "doca-1234",
        "Content": "AnalyticDB for PostgreSQL provides a simple, fast, and cost-effective PB-level cloud data warehousing solution.",
        "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": "Person",
        "Description": "A former advisor at DeepMind.",
        "FileName": "my_doc.txt"
      }
    ]
  },
  "Relations": {
    "relations": [
      {
        "Id": "1",
        "SourceEntity": "Former DeepMind advisor",
        "TargetEntity": "Dr. Wang",
        "Description": "Dr. Wang previously served as an advisor at DeepMind.",
        "FileName": "my_doc.txt\n"
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.