ChatWithKnowledgeBase - AnalyticDB - Alibaba Cloud Documentation Center

Provides intelligent question-and-answer services by combining a knowledge base with a large language model.

Operation description

This API enables users to query a large language model with answers grounded in a specified knowledge base collection. You can configure multiple parameters to customize requests, including but not limited to database instance IDs, knowledge retrieval parameters, and model inference parameters. In addition, a default system prompt template is provided and users are allowed to customize the system prompt.

DBInstanceId: Required. This parameter specifies the ID of the database instance.
KnowledgeParams: optional. It contains parameters related to knowledge retrieval, such as retrieval content and merge policy.
ModelParams: required. It contains parameters related to model inference, such as the message list and the name of the model.
PromptTemplate: optional. It is used to customize the system prompt template.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- For mandatory resource types, indicate with a prefix of * .
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
gpdb:ChatWithKnowledgeBase	create	*DBInstance `acs:gpdb:{#regionId}:{#accountId}:dbinstance/{#DBInstanceId}`	none	none

Request parameters

Parameter	Type	Required	Description	Example
DBInstanceId	string	Yes	The cluster ID. Note You can call the DescribeDBInstances operation to query the information about all AnalyticDB for PostgreSQL instances within a region, including instance IDs.	gp-xxxxxxxxx
RegionId	string	No	实例所在的地域 ID	cn-hangzhou
KnowledgeParams	object	No	The knowledge retrieval parameter object. If you do not specify this parameter, only chat mode is enabled.
MergeMethod	string	No	The method used to merge multiple knowledge bases. Default value: RRF. Optional: RRF Weight	"RRF"
MergeMethodArgs	object	No	Parameters for multi-knowledge-base fusion.
Rrf	object	No	The parameter that can be configured when the MergeMethod parameter is set to RRF.
K	long	No	The smoothing constant k in the formula to calculate the score: 1/(k + rank_i). It must be a positive integer greater than 1.	60
Weight	object	No	The parameter that you can configure when you set the MergeMethod parameter to Weight.
Weights	array	No	An array of weights for each SourceCollection.
	double	No	The weight of each SourceCollection.	0.01
RerankFactor	double	No	The rerank factor. If you specify this parameter, the search result is reranked once again. Valid values: 1<RerankFactor<=5. Note If the document is segmented into sparse parts, reranking is inefficient. We recommend that the number of reranked results (the ceiling of TopK × RerankFactor) not exceed 50.	1.0001
SourceCollection	array<object>	Yes	Knowledge base.
	object	No
Collection	string	Yes	The name of the collection to be recalled.	adbpg_document_collection
Namespace	string	No	The name of the namespace. Default value: public. Note You can call the CreateNamespace operation to create a namespace and call the ListNamespaces operation to query a list of namespaces.	dukang
NamespacePassword	string	Yes	The password of the namespace. Note The value of this parameter is specified when you call the CreateNamespace operation.	namespacePasswd
QueryParams	object	No	Parameters related to the knowledge base retrieval.
Filter	string	No	The condition that is used to filter the data to be updated. Specify this parameter in a format that is the same as the WHERE clause.	id = 'llm-t87l87fxuhn56woc_8anu8j2d3f_file_e74635e2cc314e838543e724f6b3b1f2_10658020'
GraphEnhance	boolean	No	Whether to enable knowledge graph enhancement. Default value: false.	false
GraphSearchArgs	object	No	Returns the top number of entities and relationship edges. Default value: 60.
GraphTopK	long	No	Returns the top number of entities and relationship edges. Default value: 60.	60
HybridSearch	string	No	The dual-path retrieval algorithm. This parameter is empty by default, which specifies that scores of vector retrieval and full-text retrieval are directly compared and sorted together. Valid values: RRF: The reciprocal rank fusion (RRF) algorithm uses a constant k to control the fusion effect. For more information, see the description of the HybridSearchArgs parameter. Weight: This algorithm uses the alpha parameter to specify the proportion of the vector search score and the full-text search score and then sorts by weight. For more information, see the description of the HybridSearchArgs parameter. Cascaded: This algorithm performs first full-text retrieval and then vector retrieval.	RRF
HybridSearchArgs	object	No	The parameters of the dual-path retrieval algorithm. RRF and Weight are supported at this time: RRF: Specifies the smoothing constant k in the formula to calculate the score: `1/(k + rank_i)`. The k constant must be a positive integer greater than 1. The format: `{ "RRF": { "k": 60 } }` Weight: The score is computed as `alpha * vector_score + (1 - alpha) * text_score`. The parameter alpha controls the weighting between vector search and full-text search scores, with a valid range of [0, 1]. 0 specifies only full-text search score. 1 specifies only vector search score. `{ "Weight": { "alpha": 0.5 } }`
	any	No	The parameter values.	{ "RRF": { "k": 60 } }
Metrics	string	No	The method that is used to create vector indexes. Valid values: l2: Euclidean distance. ip: Inner product distance. cosine: Cosine similarity.	cosine
RecallWindow	array	No	The retrieval window. If you specify this parameter, the context of the retrieved result is added in the output. Format: List<A, B>. Valid values: -10<=A<=0 and 0<=B<=10. Note We recommend that you specify this parameter if the source document is segmented into large numbers of pieces, which may result in loss of contextual information during retrieval. Perform re-ranking before windowing.
	long	No	The retrieval window. If you specify this parameter, the context of the retrieved result is added in the output. Format: List<A, B>. Valid values: -10<=A<=0 and 0<=B<=10. Note We recommend that you specify this parameter if the source document is segmented into large numbers of pieces, which may result in loss of contextual information during retrieval. Perform re-ranking before windowing.	[-1,1]
RerankFactor	double	No	The rerank factor. If you specify this parameter, the search result is reranked once again. Valid values: 1<RerankFactor<=5. Note If the document is segmented into sparse parts, reranking is inefficient. We recommend that the number of reranked results (the ceiling of TopK × RerankFactor) not exceed 50.	1.5
TopK	long	No	The number of top results.	10
UseFullTextRetrieval	boolean	No	Specifies whether to use full-text retrieval (dual-path retrieval). The default value is false, which means only vector retrieval is used.	true
TopK	long	No	Specifies the number of top results to return after merging retrieved results from multiple vector collections.	10
PromptParams	string	No	The system prompt template, which should include {{ text_chunks }},{{ user_system_prompt }},{{ graph_entities },{{ graph_relations }}. If any of these placeholders are not specified, the corresponding section should have no effect.
ModelParams	object	Yes	The Large Language Model (LLM) invocation parameter object.
MaxTokens	long	No	Maximum number of tokens to generate.	8192
Messages	array<object>	Yes	Message list.
	object	No	Message list.
Content	string	No	The message content.
Role	string	No	The message role. Valid values: system user assistant	user
Model	string	Yes	The model name. See Model Studio Document for the available models.	qwen-plus
N	long	No	The number of candidate responses to generate.	1
PresencePenalty	double	No	Presence penalty coefficient (-2.0 to 2.0).	1.0
Seed	long	No	The random seed.	42
Stop	array	No	Stop words.
	string	No	Stop word.	"\n"
Temperature	double	No	Sampling temperature (0~2).	0.6
Tools	array<object>	No	Tools
	object	No	Tool details.
Function	object	No	The information about a function.
Description	string	No	The description of the function.
Name	string	No	The name of the function.	get_weather
Parameters	any	No	JSON Schema for function parameters.	{"type": "object", ...}
TopP	double	No	Top-p (nucleus) sampling threshold (0–1).	0.9
IncludeKnowledgeBaseResults	boolean	No	Whether to return the retrieved result. Default value: false.	false

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
RequestId	string	The unique ID of the request.	ABB39CC3-4488-4857-905D-2E4A051D0521
MultiCollectionRecallResult	object	Retrieve information from multiple knowledge bases.
Entities	array	The details of the entity.
entity	string	The entity type.	{'entities': []}
Matches	array<object>	The retrieved items.
match	object	The retrieved item.
Content	string	The content of the document.
FileName	string	The file name.	process_info_19b9df4dc9ad4bf2b30eb2faa4a9a987.txt
FileURL	string	The URL of the image result. By default, the URL is valid for 2 hours. You can use the UrlExpiration parameter to specify a validity period.	http://viapi-customer-pop.oss-cn-shanghai.aliyuncs.com/b4d8_207196811002111319_570c0e199f03428f812ab21fcc00dd6a
Id	string	The unique ID of the vector data.	273e3fc7-8f56-4167-a1bb-d35d2f3b9043
LoaderMetadata	any	Document loader metadata.	{"page":1}
Metadata	object	The metadata.
Source	long	The source of the document.	1
RerankScore	double	The rerank score.	0.1
RetrievalSource	long	The source of the retrieved results. 1 indicates vector retrieval, 2 indicates full-text retrieval, and 3 indicates dual-path retrieval.	3
Score	double	The similarity score of the data. It is related to the `l2, ip, or cosine` algorithm that is specified when you create an index.	12
Vector	array	The vector data.
vector	double	The vector data.	[]
Relations	array	The name of the file.
relation	string	The details of the relationship edge.	{'relations': []}
RequestId	string	Request ID.	6B9E3255-4543-5B3B-9E00-6490CA64742B
Status	string	The status of the operation. Valid values: success fail	success
Tokens	long	The number of tokens that are consumed.	42
Usage	object	The number of tokens that are consumed during document understanding or embedding.
EmbeddingTokens	long	The number of tokens that are used during vectorization. Note A token is the minimum unit for splitting text. A token can be a word, phrase, punctuation, or character.	21
ChatCompletion	object	model response.
Choices	array<object>	Text content generated in real time.
choice	object	Text content generated in real time.
FinishReason	string	Finish reason.	finish
Index	long	The sequence number of the reply.	0
Message	object	LLM response.
Content	string	The content of the document.
Role	string	Message role: system user assistant	user
ToolCalls	array<object>	Tool call response.
toolcall	object
Id	string	ID	"chatcmpl-c1bebafa-cc48-44e2-88c6-1a3572952f8e"
Function	object	Function call information.
Arguments	string	Arguments of the called function.	{"city":"hangzhou"}
Name	string	The name of the called function.	"get_weather"
Index	long	The position of this tool in the 'input' request parameter.	1
ReasoningContent	string	模型思维内容	逻辑推理过程
Created	long	The creation time.	1758529748
Id	string	The ID of the response.	273e3fc7-8f56-4167-a1bb-d35d2f3b9043
Model	string	The name of the model.	qwen-plus
Usage	object	The number of tokens used in LLM output.
CompletionTokens	long	The number of tokens consumed by the generated content.	42
PromptTokens	long	The number of tokens consumed by the prompt.	42
PromptTokensDetails	object	The details about the prompt token.
CachedTokens	long	The number of tokens from cache hits.	24
TotalTokens	long	The total number of tokens.	42
Message	string	The returned information.	Successful
Status	string	The status of the operation. Valid values: success fail	success

Examples

Sample success responses

JSONformat

{
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "MultiCollectionRecallResult": {
    "Entities": [
      "{'entities': []}"
    ],
    "Matches": [
      {
        "Content": "",
        "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": {
          "Source": 1
        },
        "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": "",
          "Role": "user",
          "ToolCalls": [
            {
              "Id": "chatcmpl-c1bebafa-cc48-44e2-88c6-1a3572952f8e",
              "Function": {
                "Arguments": {
                  "city": "hangzhou"
                },
                "Name": "get_weather"
              },
              "Index": 1
            }
          ],
          "ReasoningContent": "逻辑推理过程"
        }
      }
    ],
    "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

For a list of error codes, visit the Service error codes.