Retrieve

Retrieves information from a specified knowledge base.

Operation description

How to call : We recommend using the latest Alibaba Cloud Model Studio SDK to call this API. The SDK simplifies API calls by handling the complex signature calculation.
Required permissions:
- RAM user (sub-account) : To call this API, a RAM user must be granted API permissions for Alibaba Cloud Model Studio and join a workspace. You can use the AliyunBailianDataFullAccess policy, which includes the required sfm:Retrieve permission.
- Alibaba Cloud account (main account): This account has the required permissions by default and can call the API directly.
Response latency: This API call involves complex retrieval and matching operations, which can cause longer response times. We recommend configuring appropriate request timeouts and retry strategies.
Idempotency: This API is idempotent.

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
sfm:Retrieve	none	All Resource``	None	None

Request syntax

HELPCODEESCAPE-plaintext
POST /{WorkspaceId}/index/retrieve HTTP/1.1

Path Parameters

Parameter	Type	Required	Description	Example
WorkspaceId	string	Yes	The ID of the workspace that contains the knowledge base. For more information, see How to use workspaces.	llm-3shx2gu255oqxxxx

Request parameters

Parameter	Type	Required	Description	Example
Query	string	No	The query, which is the original user prompt. There are no limits on the length of the query.	阿里云百炼平台介绍
DenseSimilarityTopK	integer	No	The number of top-K similar text chunks to retrieve using vector retrieval. This is achieved by generating a vector representation of the query and searching the knowledge base for the K text chunks with the most similar vectors. The value must be an integer from 0 to 100. The sum of `DenseSimilarityTopK` and `SparseSimilarityTopK` must not exceed 200. Default value: 100.	100
EnableReranking	boolean	No	Specifies whether to enable reranking. For more information, see Knowledge base. Valid values: - `true`: Enables reranking. - `false`: Disables reranking. Default value: `true`. Valid values: - true : Enabled - false : Disabled	true
EnableRewrite	boolean	No	Specifies whether to enable conversational query rewriting. Valid values: - `true`: Enables conversational query rewriting. - `false`: Disables conversational query rewriting. Default value: `false`. Valid values: - true : Enabled - false : Disabled	false
Rerank	array	No	The reranking configurations.
	object	No	An object containing reranking configurations.
ModelName	string	No	The reranking model to use. Specifying a model here overrides the default model selected when the knowledge base was created. Valid values: - `gte-rerank-hybrid`: Performs reranking by using the gte-rerank (hybrid) model. - `gte-rerank`: Performs reranking by using the gte-rerank model. If you do not specify this parameter, the model configured for the knowledge base is used. Note Use `gte-rerank` for semantic ranking only. We recommend `gte-rerank-hybrid` if you require both semantic ranking and text matching features for higher relevance. Valid values:** - gte-rerank-hybrid : Performs reranking by using the gte-rerank (hybrid) model. - gte-rerank : Performs reranking by using the gte-rerank model.	gte-rerank-hybrid
RerankMode	string	No	This parameter is not yet available. Do not specify a value for it. Valid values: - similar: 相似模式。 : `similar`: Similarity mode. - custom: 自定义模式。 : `custom`: Custom mode. - qa:（默认值）问答模式。 : `qa`: (Default) Q&A mode.	qa
RerankInstruct	string	No	This parameter is not yet available. Do not specify a value for it.
RerankMinScore	number	No	The similarity threshold for reranking. Only text chunks with a similarity score greater than this value are returned. The value must be between 0.01 and 1.00, inclusive. This parameter overrides the similarity threshold setting of the knowledge base. If not specified, the threshold configured for the knowledge base is used.	0.20
RerankTopN	integer	No	The number of top-ranked text chunks to return after reranking. The value must be an integer from 1 to 20. Default value: 5.	5
Rewrite	array	No	Configuration for conversational query rewriting.
	object	No	An object containing configurations for conversational query rewriting.
ModelName	string	No	Specifies the model for conversational query rewriting, which automatically rewrites the original query based on the conversation context to improve retrieval results. Valid value: - `conv-rewrite-qwen-1.8b`: The only model currently supported for this feature. If this parameter is not specified, `conv-rewrite-qwen-1.8b` is used by default. Valid values: - conv-rewrite-qwen-1.8b : The conv-rewrite-qwen-1.8b model	conv-rewrite-qwen-1.8b
SparseSimilarityTopK	integer	No	The number of top-K text chunks to retrieve using keyword retrieval. This feature finds text chunks in the knowledge base that exactly match the keywords in the query. It helps filter out irrelevant text chunks and provide more accurate results. The value must be an integer from 0 to 100. The sum of `DenseSimilarityTopK` and `SparseSimilarityTopK` must not exceed 200. Default value: 100.	100
IndexId	string	Yes	The ID of the knowledge base. This is the `Data.Id` value returned by the `CreateIndex` operation. Note ** - Ensure the specified knowledge base exists and has not been deleted.	5pwe0mxxxx
SaveRetrieverHistory	boolean	No	Specifies whether to save the retrieval history for testing purposes. Valid values: - `true`: Saves the retrieval history. - `false`: Does not save the retrieval history. Default value: `false`.	false
SearchFilters	array	No	Specifies custom retrieval conditions, such as tags, to filter semantic retrieval results and exclude irrelevant information. The filtering logic is applied only when the `is_displayed_chunk_content` parameter is set to `true`. For more information, see SearchFilters for a knowledge base.
	object	No	A search condition object.
	string	No
Images	array	No	The URLs of images to include in the query.
	string	No	When you retrieve information from an image-based Q&A knowledge base, you can provide image URLs. If an image index exists in the knowledge base, the system converts the input image into a vector to retrieve relevant records. If no image index exists, the input image is not used for retrieval. Note This field is not supported for knowledge bases of the document search or data query type. This field has no effect if specified. Note Make sure that the link is publicly accessible and points to a valid image file. Example: https://example.com/downloads/pic.jpg	https://example.com/downloads/pic.jpg
QueryHistory	array	No	The conversation history, used for conversational query rewriting. This parameter is effective only when `EnableRewrite` is set to `true`.
	object	No
role	string	No	The role of the entity that sent the message. Valid values: - `user`: Indicates that the `content` is from the end user. - `assistant`: Indicates that the `content` is a response from the Model Studio application.	user
content	string	No	The content of the message for the specified `role`.	代表一段文本。

Response elements

Element	Type	Description	Example
	object
Code	string	The error code.	Index.InvalidParameter
Data	object	The business data returned by the API.
Nodes	array	An array of retrieved text chunks.
	object	A text chunk object.
Metadata	any	A map of metadata for the text chunk. Note For document search knowledge bases, the `file_path` field in the metadata map is not applicable and should not be used in your application code. Note When you retrieve data from a document search knowledge base, if a text chunk contains an image, its URL is returned in the `image_url` field of the metadata map. This URL expires.	{ "parent": "", "file_path": "https://", "image_url": [ "http://" ], "nid": "", "title": "阿里云百炼文档", "doc_id": "doc_", "content": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建", "workspace_id": "ws_", "hier_title": "阿里云百炼文档", "doc_name": "阿里云百炼文档介绍.pdpf", "pipeline_id": "rhd", "id": "ws***" }
Score	number	The similarity score of the text chunk, ranging from 0 to 1.	0.3
Text	string	The content of the text chunk.	阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建。
Message	string	The error message.	Required parameter(%s) missing or invalid, please check the request parameters.
RequestId	string	The request ID.	17204B98-7734-4F9A-8464-2446A84821CA
Status	string	The HTTP status code of the response.	200
Success	boolean	Indicates whether the API call was successful. Valid values: - true: The call succeeded. - false: The call failed.	true

Examples

Success response

JSON format

HELPCODEESCAPE-json
{
  "Code": "Index.InvalidParameter",
  "Data": {
    "Nodes": [
      {
        "Metadata": "{\n  \"parent\": \"\",\n  \"file_path\": \"https://***\",\n  \"image_url\": [\n    \"http://***\"\n  ],\n  \"nid\": \"***\",\n  \"title\": \"阿里云百炼文档\",\n  \"doc_id\": \"doc_***\",\n  \"content\": \"阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建\",\n  \"workspace_id\": \"ws_***\",\n  \"hier_title\": \"阿里云百炼文档\",\n  \"doc_name\": \"阿里云百炼文档介绍.pdpf\",\n  \"pipeline_id\": \"rhd***\",\n  \"_id\": \"ws_***\"\n}",
        "Score": 0.3,
        "Text": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建。"
      }
    ]
  },
  "Message": "Required parameter(%s) missing or invalid, please check the request parameters.",
  "RequestId": "17204B98-7734-4F9A-8464-2446A84821CA",
  "Status": "200",
  "Success": true
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.

Retrieve ​

Operation description ​

Try it now ​

RAM authorization ​

Request syntax ​

Path Parameters ​

Request parameters ​

Response elements ​

Examples ​

Error codes ​

Release notes ​