DocsICP FilingConsole
官方文档
首页

Retrieve

更新时间：
复制 MD 格式
产品详情
我的收藏

Retrieves information from a specified knowledge base.

Operation description

  • How to call: To retrieve information from a knowledge base, use the latest Alibaba Cloud Model Studio SDK with an AccessKey or Spring AI Alibaba with an Alibaba Cloud Model Studio API key. Both tools simplify your 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

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<object>

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:

  • qwen3-rerank-hybrid: Performs reranking by using the qwen3-rerank (hybrid) model.

  • qwen3-rerank: Performs reranking by using the qwen3-rerank model.

  • 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 qwen3-rerank for semantic ranking only. We recommend qwen3-rerank-hybrid if you require both semantic ranking and text matching features for higher relevance.

Note

The gte-rerank-hybrid and gte-rerank models are no longer updated and are not recommended for use.

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

Specifies the instruction intervention mode for the reranking model. This mode determines the model's scoring preference.

Valid values:

  • qa: (Default) Q&A mode. The model assigns higher scores to candidates that directly answer the query. Recommended for Q&A scenarios.

  • similar: Similarity mode. The model assigns higher scores to candidates with high content similarity to the query. Recommended for match-based retrieval scenarios.

  • custom: Custom mode. The model's ranking behavior is determined by the instructions in the RerankInstruct parameter.

Valid values:

  • similar: 相似模式。 :

    similar: Similarity mode.

  • custom: 自定义模式。 :

    custom: Custom mode.

  • qa:（默认值） 问答模式。 :

    qa: (Default) Q&A mode.

qa

RerankInstruct

string

No

A natural language instruction to fine-tune the behavior of the reranking model.

Important

This parameter takes effect only when RerankMode is set to custom.

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<object>

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<object>

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, data query, or audio/video search 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<object>

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<object>

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.

Note

When you retrieve data from an audio/video search knowledge base, if a text chunk contains audio, its URL is returned in the audio_url field of the metadata map. This URL expires.

Note

When you retrieve data from an audio/video search knowledge base, if a text chunk contains video, its URL is returned in the video_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

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