Retrieve - Alibaba Cloud Model Studio

Operation description

How to call: Use the latest Alibaba Cloud Model Studio SDK to call this API. The SDK handles signature calculation automatically.
Required permissions:
- RAM user (sub-account): A RAM user must have API permissions for Model Studio and join a workspace. The AliyunBailianDataFullAccess policy 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: Retrieval operations may have longer response times. Configure appropriate 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

Action

Access level

Resource type

Condition key

Dependent action

sfm:Retrieve

none

*All Resource

*

None

Request syntax

POST /{WorkspaceId}/index/retrieve HTTP/1.1

Path Parameters

Parameter	Type	Required	Description	Example
WorkspaceId	string	Yes	The workspace ID. How to use workspaces.	llm-3shx2gu255oqxxxx

Request parameters

Parameter	Type	Required	Description	Example
Query	string	No	The input query (original user prompt). No length limit.	阿里云百炼平台介绍
DenseSimilarityTopK	integer	No	Number of text chunks to retrieve using vector search. Valid values: 0 to 100. The sum of `DenseSimilarityTopK` and `SparseSimilarityTopK` must not exceed 200. Default value: 100.	100
EnableReranking	boolean	No	Enables reranking (Knowledge base). Valid values: `true`: Enables reranking. `false`: Disables reranking. Default value: `true`. Valid values: true : Enabled false : Disabled	true
EnableRewrite	boolean	No	Enables 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<object>	No	The reranking configurations.
	object	No	An object containing reranking configurations.
ModelName	string	No	The reranking model. Overrides the default model configured for the knowledge base. Valid values: `gte-rerank-hybrid`: Performs reranking by using the gte-rerank (hybrid) model. `gte-rerank`: Performs reranking by using the gte-rerank model. Default: the model configured for the knowledge base. 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	Minimum similarity score for reranking results. Valid values: 0.01 to 1.00. Overrides the threshold configured for the knowledge base. Default: the threshold configured for the knowledge base.	0.20
RerankTopN	integer	No	Number of top-ranked text chunks to return after reranking. Valid values: 1 to 20. Default: 5.	5
Rewrite	array<object>	No	Configuration for conversational query rewriting.
	object	No	An object containing configurations for conversational query rewriting.
ModelName	string	No	The model for conversational query rewriting. Rewrites the query based on conversation context to improve retrieval. Valid value: `conv-rewrite-qwen-1.8b`: The only model currently supported for this feature. Default: `conv-rewrite-qwen-1.8b`. Valid values: conv-rewrite-qwen-1.8b : The conv-rewrite-qwen-1.8b model	conv-rewrite-qwen-1.8b
SparseSimilarityTopK	integer	No	Number of text chunks to retrieve using keyword matching. Valid values: 0 to 100. The sum of `DenseSimilarityTopK` and `SparseSimilarityTopK` must not exceed 200. Default value: 100.	100
IndexId	string	Yes	The knowledge base ID, returned as `Data.Id` by `CreateIndex`. Ensure the specified knowledge base exists and has not been deleted.	5pwe0mxxxx
SaveRetrieverHistory	boolean	No	Saves retrieval history for testing. Valid values: `true`: Saves the retrieval history. `false`: Does not save the retrieval history. Default value: `false`.	false
SearchFilters	array<object>	No	Custom retrieval conditions (such as tags) to filter results. Applies only when `is_displayed_chunk_content` is `true`. 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	For image-based Q&A knowledge bases, provide image URLs. The system vectorizes the input image for retrieval if an image index exists. Otherwise, the input image is ignored. This field is not supported for knowledge bases of the document search or data query type. This field has no effect if specified. 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<object>	No	Conversation history for conversational query rewriting. Takes effect only when `EnableRewrite` is `true`.
	object	No
role	string	No	The message sender's role. 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`.	What is Alibaba Cloud Model Studio?

Response elements

Element	Type	Description	Example
	object
Code	string	The error code.	Index.InvalidParameter
Data	object	The data returned by the API.
Nodes	array<object>	An array of retrieved text chunks.
	object	A text chunk object.
Metadata	any	A map of metadata for the text chunk. 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. 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	Whether the API call succeeded. Valid values: true: The call succeeded. false: The call failed.	true

Examples

Success response JSON format

{
  "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.

​Operation description

​Try it now

​RAM authorization

​Request syntax

​Path Parameters

​Request parameters

​Response elements

​Examples

​Error codes

​Release notes