Query Knowledge Base Chunks via ListChunks API - Model Studio - Alibaba Cloud - Alibaba Cloud Model Studio

Queries the list and information of text chunks.

Operation description

For document search knowledge bases, this operation queries all chunks of a specified file. For data query or image Q&A knowledge bases, this operation retrieves information about all text chunks.
Resource Access Management (RAM) users must first obtain API permissions for Model Studio (requires AliyunBailianDataFullAccess, which includes the sfm:ChunkList permission), and join a workspace before invoking this operation. Alibaba Cloud accounts can invoke this operation directly without authorization. Use the latest Model Studio SDK to invoke this operation.
Before invoking this operation, make sure that your knowledge base has been created and has not been deleted (that is, the knowledge base ID IndexId is valid).
This operation has idempotence.

Rate limit: This operation is throttled if called too frequently. Do not exceed 10 calls per second. If you are throttled, retry later.

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

list

*All Resource

*

None

Request syntax

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

Path Parameters

Parameter	Type	Required	Description	Example
WorkspaceId	string	Yes	The workspace ID of the knowledge base. For information about how to obtain the workspace ID, see How to use a workspace.	llm-3z7uw7fwz0vxxxx

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	The body of the request parameters.
Fields	array	No	An array of field names used to filter non-private fields (those not prefixed with an underscore _) in the Metadata field returned by this operation. By default, Fields is empty, and all non-private fields in Metadata are returned. To return only specific non-private fields in Metadata, such as title, pass title in this parameter. Default value: empty.
	string	No	The field name.	name
Filed	string	No	The file ID field in the legacy Model Studio SDK. The usage and default value are identical to those of the `FileId` field. If you are using the following versions (or later) of the Model Studio SDK, use the `FileId` field instead. If you are using the SWIFT Model Studio SDK, continue to use this field. Java (async): 1.0.18 Java: 1.10.2 TypeScript: 1.10.2 Go: 1.10.2 PHP: 1.10.2 Python: 1.10.2 C#: 1.10.2 C++: 1.10.17 Note How to check the Model Studio SDK version: Visit the Model Studio SDK center, click "Install" in the left-side navigation pane, set the API version to "2023-12-29", select your programming language, and then click "History Versions" to view the version.	file_5f03dfea56da4050ab68d61871fc4cb3_xxxxxxxx
FileId	string	No	The file ID, which is the `FileId` returned by the AddFile operation. This field is not required for data query or image Q&A knowledge bases. This field is required for document search knowledge bases. You can also obtain the file ID by clicking the ID icon next to the file name on the Files tab of Application Data. You can use the file ID to filter the returned chunks. Default value: empty. .	file_5f03dfea56da4050ab68d61871fc4cb3_xxxxxxxx
IndexId	string	Yes	The knowledge base ID, which is the `Data.Id` returned by the CreateIndex operation.	otoru9xxxx
PageNum	integer	No	The page number to query. Minimum value: 1. Default value: 1.	1
PageSize	integer	No	The number of text chunks to display per page in a paged query. Maximum value: 100. Default value: 10.	10

Response elements

Element	Type	Description	Example
	object
Code	string	The error status code.	Index.InvalidParameter
Data	object	The business data returned by the operation.
Nodes	array<object>	The list of text chunks.
	object	The text chunk object.
Metadata	any	The metadata map of the chunk.	{ "file_path": "https://bailian-*", "parent": "阿里云百炼是一站式的大模型开发及应用构建平台。不论是开发者还是业务人员，都能深入参与大模型应用的设计和构建。您可以通过简单的界面操作，在 5分钟内开发出一款大模型应用，或在几小时内训练出一个专属模型，从而将更多精力专注于应用创新。", "is_displayed_chunk_content": "true", "image_url": [], "nid": "83", "source": "0", "_score": 0, "title": "", "doc_id": "file_24e", "content": "阿里云百炼是一站式的大模型开发及应用构建平台。不论是开发者还是业务人员，都能深入参与大模型应用的设计和构建。您可以通过简单的界面操作，在 5分钟内开发出一款大模型应用，或在几小时内训练出一个专属模型，从而将更多精力专注于应用创新。", "_rc_score": 0, "workspace_id": "llm-zna", "hier_title": "", "doc_name": "什么是阿里云百炼", "pipeline_id": "j6b", "_id": "llm-zna5*" }
Score	number	The similarity score of the chunk.	0
Text	string	The text of the chunk.	阿里云百炼是一站式的大模型开发及应用构建平台。不论是开发者还是业务人员，都能深入参与大模型应用的设计和构建。您可以通过简单的界面操作，在 5分钟内开发出一款大模型应用，或在几小时内训练出一个专属模型，从而将更多精力专注于应用创新。
Total	integer	The total number of returned results.	1
Message	string	The error message.	Required parameter(%s) missing or invalid, please check the request parameters.
RequestId	string	The request ID.	8F97A63B-xxxx-527F-9D6E-467B6A7E8CF1
Status	string	The status code returned by the operation.	200
Success	boolean	Indicates whether the operation was successful. Valid values: true: Successful. false: Failed.	true

Examples

Success response

JSON format

{
  "Code": "Index.InvalidParameter",
  "Data": {
    "Nodes": [
      {
        "Metadata": "{\n  \"file_path\": \"https://bailian-***\",\n  \"parent\": \"阿里云百炼是一站式的大模型开发及应用构建平台。不论是开发者还是业务人员，都能深入参与大模型应用的设计和构建。您可以通过简单的界面操作，在 5分钟内开发出一款大模型应用，或在几小时内训练出一个专属模型，从而将更多精力专注于应用创新。\",\n  \"is_displayed_chunk_content\": \"true\",\n  \"image_url\": [],\n  \"nid\": \"83***\",\n  \"source\": \"0\",\n  \"_score\": 0,\n  \"title\": \"\",\n  \"doc_id\": \"file_24e***\",\n  \"content\": \"阿里云百炼是一站式的大模型开发及应用构建平台。不论是开发者还是业务人员，都能深入参与大模型应用的设计和构建。您可以通过简单的界面操作，在 5分钟内开发出一款大模型应用，或在几小时内训练出一个专属模型，从而将更多精力专注于应用创新。\",\n  \"_rc_score\": 0,\n  \"workspace_id\": \"llm-zna***\",\n  \"hier_title\": \"\",\n  \"doc_name\": \"什么是阿里云百炼\",\n  \"pipeline_id\": \"j6b***\",\n  \"_id\": \"llm-zna5***\"\n}",
        "Score": 0,
        "Text": "阿里云百炼是一站式的大模型开发及应用构建平台。不论是开发者还是业务人员，都能深入参与大模型应用的设计和构建。您可以通过简单的界面操作，在 5分钟内开发出一款大模型应用，或在几小时内训练出一个专属模型，从而将更多精力专注于应用创新。"
      }
    ],
    "Total": 1
  },
  "Message": "Required parameter(%s) missing or invalid, please check the request parameters.",
  "RequestId": "8F97A63B-xxxx-527F-9D6E-467B6A7E8CF1",
  "Status": "200",
  "Success": true
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.