ChatWithKnowledgeBase-阿里云帮助中心

Provides intelligent Q&A services by combining knowledge bases with large models.

Operation description

This API allows users to interact with a large model through specified knowledge base collections to obtain answers based on knowledge base content. It supports configuring various parameters to customize requests, including but not limited to database instance ID, knowledge retrieval parameters, model inference parameters, etc. Additionally, it provides a default system prompt template and allows users to customize system prompts.

DBInstanceId: Required. Specifies the database instance ID.
KnowledgeParams: Optional. Contains parameters related to knowledge retrieval, such as retrieval content, merge strategies, etc.
ModelParams: Required. Contains parameters related to model inference, such as message list, model name, etc.
PromptTemplate: Optional. Used to customize the system prompt template.

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:ChatWithKnowledgeBase

create

*DBInstance

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

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 instances in the target region, including the instance ID.	gp-xxxxxxxxx
RegionId	string	Yes	The region ID of the instance.	cn-hangzhou
KnowledgeParams	object	No	The knowledge retrieval parameter object. If not specified, only chat is performed.
MergeMethod	string	No	The method for merging multiple knowledge bases. Default is RRF. Valid values: RRF Weight	"RRF"
MergeMethodArgs	object	No	The parameters for multi-knowledge base fusion.
Rrf	object	No	The configurable parameters when MergeMethod is set to RRF.
K	integer	No	The constant `k` in the reciprocal rank fusion formula `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	An array of weights corresponding to each collection specified in `SourceCollection`.
	number	No	The weight for a collection.	0.01
RerankFactor	number	No	The reranking factor. When this value is not empty, the vector retrieval results are reranked. Value range: 1 < RerankFactor <= 5. Note Reranking is slow when document segmentation is sparse. It is recommended that the number of items to rerank (TopK * Factor, rounded up) does not exceed 50.	1.0001
RerankModel	object	No
Name	string	No		qwen3-rerank
Instruct	string	No		Given a web search query, retrieve relevant passages that answer the query
SourceCollection	array<object>	Yes	The list of knowledge bases.
	array<object>	No	A knowledge base.
Collection	string	Yes	The name of the collection to recall.	adbpg_document_collection
Namespace	string	No	The namespace. Default value: public. Note You can create a namespace by calling the CreateNamespace operation, and view the list by calling the ListNamespaces operation.	dukang
NamespacePassword	string	Yes	The password corresponding to the namespace. Note This value is specified in the CreateNamespace operation.	namespacePasswd
QueryParams	object	No	The parameters related to knowledge base retrieval.
Filter	string	No	A filter to apply to the search, specified as a SQL `WHERE` clause.	id = 'llm-t87l87fxuhn56woc_8anu8j2d3f_file_e74635e2cc314e838543e724f6b3b1f2_10658020'
GraphEnhance	boolean	No	Whether to enhance the search with a knowledge graph. Default: `false`.	false
GraphSearchArgs	object	No	Parameters for the knowledge graph search, used when `GraphEnhance` is `true`.
GraphTopK	integer	No	The maximum number of entities and relationship edges to return from the knowledge graph search. Default: 60.	60
HybridSearch	string	No	The multi-channel recall algorithm. If omitted, the system directly compares and sorts scores from dense vector retrieval and full-text search. Valid values: `RRF`: Uses reciprocal rank fusion. The fusion effect is controlled by the `k` parameter in `HybridSearchArgs`. `Weight`: Uses weighted sorting. The weights for vector retrieval and full-text search scores are controlled by parameters in `HybridSearchArgs`. `Cascaded`: Performs a full-text search first, followed by a vector retrieval on the results.	RRF
HybridSearchArgs	object	No	Parameters for the multi-channel recall algorithm. `RRF` and `Weight` are supported. The `HybridPathsSetting` parameter can specify the recall channels: `dense` (dense vector), `sparse` (sparse vector), and `fulltext` (full-text search). If this parameter is empty, `dense` and `fulltext` are used by default. `RRF`: Specifies the constant `k` in the formula `1/(k+rank_i)`. The value must be a positive integer greater than 1. Format: `{ "HybridPathsSetting": { "paths": "dense,fulltext" }, "RRF": { "k": 60 } }` `Weight`: Two-channel recall (if `HybridPathsSetting` is not specified, only `alpha` is required): Formula: `alpha * dense_score + (1-alpha) * fulltext_score`. The `alpha` parameter represents the weight of the dense vector score relative to the full-text search score. The value must be in the range [0, 1]. A value of 0 uses only full-text search. A value of 1 uses only dense vector retrieval. `{ "Weight": { "alpha": 0.5 } }` Three-channel recall: Formula: `normalized_dense * dense_score + normalized_sparse * sparse_score + normalized_fulltext * fulltext_score`. The `dense`, `sparse`, and `fulltext` parameters represent the weights for each channel and must be greater than or equal to 0. The system automatically normalizes these weights (for example, `normalized_x = x / (dense + sparse + fulltext)`). `{ "HybridPathsSetting": { "paths": "dense,sparse,fulltext" }, "Weight": { "dense": 0.5, "sparse": 0.3, "fulltext": 0.2 } }`
	any	No	The specific arguments for the chosen `HybridSearch` method, such as `RRF` or `Weight`.	{ "HybridPathsSetting": { "paths": "dense,fulltext" }, "RRF": { "k": 60 } }
Metrics	string	No	The distance metric used for vector indexing. Valid values: `l2`: euclidean distance. `ip`: Inner product (dot product) distance. `cosine`: cosine similarity.	cosine
RecallWindow	array	No	The recall window. If specified, expands the context around retrieved text chunks. Must be an array of two integers, `[A, B]`, where `A` is the number of preceding chunks to include (from -10 to 0) and `B` is the number of following chunks (from 0 to 10). Note We recommend that you use this parameter when document chunks are highly fragmented and retrieval might result in a loss of context. Reranking is performed before windowing is applied.
	integer	No	The number of preceding (negative or zero) or following (positive or zero) chunks to include. Note We recommend that you use this parameter when document chunks are highly fragmented and retrieval might result in a loss of context. Reranking is performed before windowing is applied.	[-1,1]
RerankFactor	number	No	The reranking factor for this collection, which overrides the top-level `RerankFactor`. If specified, it reranks the initial retrieval results to improve relevance. Valid range: (1, 5]. Note Reranking may be less efficient if document chunks are sparse. We recommend that the number of items to rerank, calculated as `Ceiling(TopK * RerankFactor)`, does not exceed 50.	1.5
RerankModel	object	No	The model to use for reranking.
Name	string	No	The name of the reranking model.	qwen3-rerank
Instruct	string	No	The instruction or prompt for the reranking model.	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 from this collection before merging.	10
UseFullTextRetrieval	boolean	No	Whether to enable full-text search in addition to vector retrieval. Default: `false` (uses only vector retrieval).	true
TopK	integer	No	The number of top results to return after merging the recall results from multiple vector collections.	10
PromptParams	string	No	The system prompt template, which must include {{ text_chunks }}, {{ user_system_prompt }}, {{ graph_entities }}, and {{ graph_relations }}. If not specified, this part does not take effect.	"Answer the question based on the following knowledge: {{ text_chunks }}"
ModelParams	object	Yes	The large language model (LLM) invocation parameter object.
MaxTokens	integer	No	The maximum number of tokens to generate.	8192
Messages	array<object>	Yes	The message list.
	object	Yes	The message list.
Content	string	Yes	The message content.	You are a helpful assistant.
Role	string	Yes	The message role. Valid values: system user assistant	user
Model	string	Yes	The name of the large model to use. For valid values, see: Bailian Help Documentation	qwen-plus
N	integer	No	The number of candidate replies to generate.	1
PresencePenalty	number	No	The presence penalty coefficient (-2.0 to 2.0).	1.0
Seed	integer	No	The random seed.	42
Stop	array	No	The stop word list.
	string	No	A stop word.	"\n"
Temperature	number	No	The sampling temperature (0 to 2).	0.6
Tools	array<object>	No	The tool list.
	array<object>	No	Tool details.
Function	object	No	The function information.
Description	string	No	The description of the function tool.	Get the weather.
Name	string	No	The name of the function tool.	get_weather
Parameters	any	No	The JSON schema of the function parameters.	{"type": "object", ...}
TopP	number	No	The nucleus sampling probability threshold (0 to 1).	0.9
IncludeKnowledgeBaseResults	boolean	No	Specifies whether to return the recall results. Default value: false.	false

Response elements

Element	Type	Description	Example
	object	The response body.
RequestId	string	The request ID.	ABB39CC3-4488-4857-905D-2E4A051D0521
MultiCollectionRecallResult	object	The multi-knowledge base recall information.
Entities	array	The entity details.
	string	An entity type.	{'entities': []}
Matches	array<object>	The recall items.
	array<object>	A recall item.
Content	string	The document content.	AnalyticDB PostgreSQL vector database.
FileName	string	The file name.	process_info_19b9df4dc9ad4bf2b30eb2faa4a9a987.txt
FileURL	string	The public URL of the file. By default, the URL is valid for 2 hours. You can specify a custom validity period by using the `UrlExpiration` request parameter.	http://viapi-customer-pop.oss-cn-shanghai.aliyuncs.com/b4d8_207196811002111319_570c0e199f03428f812ab21fcc00dd6a
Id	string	The unique ID of the vector.	273e3fc7-8f56-4167-a1bb-d35d2f3b9043
LoaderMetadata	any	The metadata generated when the document was loaded.	{"page":1}
Metadata	object	The metadata.
	any	User-defined metadata as key-value pairs.	{"update_time":1749348435357,"title":"example"}
RerankScore	number	The reranking score.	0.1
RetrievalSource	integer	The retrieval source. Valid values: `1` for vector retrieval, `2` for full-text search, and `3` for two-channel recall.	3
Score	number	The similarity score. The score is based on the algorithm `(l2/ip/cosine)` specified when the index was created.	12
Vector	array	The vector data.
	number	A value in the vector.	[]
Relations	array	The relationship edge details.
	string	The relationship edge details.	{'relations': []}
RequestId	string	The request ID.	6B9E3255-4543-5B3B-9E00-6490CA64742B
Status	string	The API execution status. Valid values: success: Execution succeeded. fail: Execution failed.	success
Tokens	integer	The number of tokens consumed.	42
Usage	object	The tokens or items consumed by document understanding or embedding.
EmbeddingTokens	integer	The number of tokens used for vectorization. Note A token is the smallest unit of text. A token can be a word, a phrase, a punctuation mark, or a character.	21
ChatCompletion	object	The model response.
Choices	array<object>	The real-time generated text content.
	array<object>	A role identifier.
FinishReason	string	The reason the model stopped generating tokens.	finish
Index	integer	The index of this choice in the `Choices` array.	0
Message	object	The message generated by the large language model.
Content	string	The content of the message.	The weather in Hangzhou is sunny.
Role	string	The role of the message: `system` `user` `assistant`	user
ToolCalls	array<object>	A list of tool calls generated by the model.
	array<object>	A tool call that the model wants to make.
Id	string	The ID of the tool call.	"chatcmpl-c1bebafa-cc48-44e2-88c6-1a3572952f8e"
Function	object	The function that the model wants to call.
Arguments	string	The arguments to pass to the function.	{"city":"hangzhou"}
Name	string	The name of the function to call.	"get_weather"
Index	integer	The index of the tool call.	1
ReasoningContent	string	The model's reasoning process.	Logical reasoning process
Created	integer	The creation time.	1758529748
Id	string	The response ID.	273e3fc7-8f56-4167-a1bb-d35d2f3b9043
Model	string	The model name used.	qwen-plus
Usage	object	The token usage of the large model output.
CompletionTokens	integer	The number of tokens in the generated response.	42
PromptTokens	integer	The number of tokens in the input prompt.	42
PromptTokensDetails	object	Details of the prompt tokens.
CachedTokens	integer	The number of prompt tokens that resulted in a cache hit.	24
TotalTokens	integer	The total number of tokens used in the request (prompt tokens + completion tokens).	42
Message	string	The return message.	Successful
Status	string	The status. Valid values: success: Succeeded. fail: Failed.	success

Examples

Success response

JSON format

{
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "MultiCollectionRecallResult": {
    "Entities": [
      "{'entities': []}"
    ],
    "Matches": [
      {
        "Content": "AnalyticDB PostgreSQL vector database.",
        "FileName": "process_info_19b9df4dc9ad4bf2b30eb2faa4a9a987.txt",
        "FileURL": "http://viapi-customer-pop.oss-cn-shanghai.aliyuncs.com/b4d8_207196811002111319_570c0e199f03428f812ab21fcc00dd6a",
        "Id": "273e3fc7-8f56-4167-a1bb-d35d2f3b9043",
        "LoaderMetadata": "{\"page\":1}",
        "Metadata": {
          "key": "{\"update_time\":1749348435357,\"title\":\"example\"}"
        },
        "RerankScore": 0.1,
        "RetrievalSource": 3,
        "Score": 12,
        "Vector": [
          0
        ]
      }
    ],
    "Relations": [
      "{'relations': []}"
    ],
    "RequestId": "6B9E3255-4543-5B3B-9E00-6490CA64742B",
    "Status": "success",
    "Tokens": 42,
    "Usage": {
      "EmbeddingTokens": 21
    }
  },
  "ChatCompletion": {
    "Choices": [
      {
        "FinishReason": "finish",
        "Index": 0,
        "Message": {
          "Content": "The weather in Hangzhou is sunny.",
          "Role": "user",
          "ToolCalls": [
            {
              "Id": "\"chatcmpl-c1bebafa-cc48-44e2-88c6-1a3572952f8e\"",
              "Function": {
                "Arguments": "{\"city\":\"hangzhou\"}",
                "Name": "\"get_weather\""
              },
              "Index": 1
            }
          ],
          "ReasoningContent": "Logical reasoning process"
        }
      }
    ],
    "Created": 1758529748,
    "Id": "273e3fc7-8f56-4167-a1bb-d35d2f3b9043",
    "Model": "qwen-plus",
    "Usage": {
      "CompletionTokens": 42,
      "PromptTokens": 42,
      "PromptTokensDetails": {
        "CachedTokens": 24
      },
      "TotalTokens": 42
    }
  },
  "Message": "Successful",
  "Status": "success"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.