CreateIndex-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Use this API to create two types of knowledge bases: unstructured knowledge bases for documents, audio, or video, and structured knowledge bases for data queries or image Q&A.

Operation description

Permissions:
- RAM user (sub-account): You must first obtain the API permissions for Alibaba Cloud Model Studio (you can use the AliyunBailianDataFullAccess policy, which includes the sfm:CreateIndex permission required for this operation) and join a workspace before you can call this operation.
- Alibaba Cloud account (primary account): By default, an Alibaba Cloud account has the required permissions and can call this operation directly.
How to call: We recommend that you use the latest version of the Alibaba Cloud Model Studio SDK to call this operation. The SDK encapsulates the complex signature calculation logic to simplify the process.
What to do next: This operation only initializes the knowledge base creation job. After you call this operation, you must call the SubmitIndexJob operation to complete the creation. Otherwise, you will get an empty knowledge base. For related code examples, see Knowledge base API guide.
Idempotence: This operation is not idempotent. Repeated calls may create multiple knowledge bases with the same name. We recommend that you implement idempotent calls by using the "query first, then create" logic.

Rate limiting: Frequent calls to this operation are subject to rate limiting. Do not exceed a frequency of 10 calls per second. If you encounter rate limiting, retry the call later.

Try it now

You can run this operation directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After a successful call, OpenAPI Explorer can automatically generate SDK code examples.

RAM authorization

The following table describes the authorization information of this API. You can use it in the Action element of a RAM policy statement to grant RAM users or RAM roles the permission to call this API. The details are as follows:

Action: The specific permission point.
Access level: The access level of each action. Valid values: Write, Read, or List.
Resource type: The resource types that support authorization for the action. The details are as follows:
- Required resource types are marked with an asterisk (*) before them.
- For operations that do not support resource-level authorization, All Resources is used.
Condition key: The condition keys defined by the cloud service itself.
Dependent action: The other permissions required to successfully perform the operation. The caller must have the permissions of all dependent actions for the operation to succeed.

Action	Access level	Resource type	Condition key	Dependent action
sfm:CreateIndex	create	All Resources ``	None	None

Action

Access level

Resource type

Condition key

Dependent action

sfm:CreateIndex

create

*All Resources

*

None

Request syntax

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

Path Parameters

Parameter	Type	Required	Description	Example
WorkspaceId	string	Yes	The workspace ID. The knowledge base is created in this workspace. For more information about how to obtain the workspace ID, see How to use workspaces.	llm-3z7uw7fwz0vexxxx

Request parameters

Parameter	Type	Required	Description	Example
Name	string	Yes	The name of the knowledge base. The name can be 1 to 20 characters in length and can contain Chinese characters, letters, digits, underscores (_), hyphens (-), periods (.), and colons (:).	Enterprise doc lib
StructureType	string	Yes	The type of the knowledge base. Valid values: unstructured: A knowledge base for document search, audio, or video. The default scenario for the document search type is basic document Q&A.To create a knowledge base for other scenarios, you must also specify the knowledgeType and knowledgeScene parameters. structured: A knowledge base for data query or image Q&A. Note that the type of a knowledge base cannot be changed after the knowledge base is created. Valid values: unstructured : unstructured	unstructured
EmbeddingModelName	string	No	The vector model used by the knowledge base. A vector model converts the original input prompt and knowledge text into numerical vectors so that the two can be compared for similarity. The text-embedding-v4 model is a comprehensive upgrade over the text-embedding-v3 model in terms of language support, vectorization of code snippets, and vector dimension selection. It is suitable for most scenarios. For more information, see Vectorization. Valid values: text-embedding-v4 text-embedding-v3 The default value is empty, in which case the text-embedding-v3 model is used. text-embedding-v2 The default value is empty, in which case the text-embedding-v2 model is used.	text-embedding-v4
RerankModelName	string	No	The reranking model used by the knowledge base. The reranking model is an external scoring system that calculates a similarity score between the user's question and each text chunk in the knowledge base, sorts the text chunks in descending order of the score, and returns the top K text chunks with the highest scores. Valid values: qwen3-rerank-hybrid: qwen3-rerank (hybrid) reranking. qwen3-rerank: qwen3-rerank reranking. gte-rerank-hybrid: gte-rerank (hybrid) reranking. gte-rerank: gte-rerank reranking. The default value is empty, in which case qwen3-rerank is used. Use `qwen3-rerank` if you only need semantic sorting. Use `qwen3-rerank-hybrid` if you need both semantic sorting and text-matching features to ensure relevance. `gte-rerank-hybrid` and `gte-rerank` will no longer be updated and are not recommended. Valid values: gte-rerank-hybrid : Official reranking gte-rerank : gte-rerank reranking	gte-rerank-hybrid
RerankMinScore	number	No	The similarity threshold. Only text chunks with a similarity score higher than this value are recalled. This parameter is used to filter the text chunks returned by the reranking model. Valid range: [0.01-1.00]. If you do not specify this parameter, the default value 0.01 is used.	0.20
ChunkSize	integer	No	The chunk size, which is the maximum number of characters in each text chunk. If this length is exceeded: Smart chunking (`chunkMode` not specified): The text is likely to be truncated. Custom chunking (`chunkMode` specified): The text is forcibly truncated. Valid range: [1-6000]. If you do not specify this parameter, the default value 500 is used. If you set `ChunkSize` to a value less than 100, you must also set `OverlapSize`. You can also leave both parameters unspecified, and the system will use the default values.	128
OverlapSize	integer	No	The chunk overlap size, which is the number of overlapping characters between the current text chunk and the previous one. Valid range: [0-1024]. If you do not specify this parameter, the default value 100 is used. `OverlapSize` must be smaller than `ChunkSize`. Otherwise, chunking errors will occur.	16
Separator	string	No	The sentence separator, which takes effect only when `chunkMode` is set to regex (it is ignored in other modes even if specified). You can specify a regular expression (only one is supported) to split the file into smaller text chunks. For smart chunking (the `chunkMode` parameter is not specified), you can leave this parameter at the default empty value.	(?<=。)
SourceType	string	No	This parameter has become required in the latest SDK version. Otherwise, calling the SubmitIndexJob operation will fail with the error: Required parameter(data_sources) missing or invalid. The source of the imported data. Valid values: DATA_CENTER_CATEGORY: Category type. Imports all files under the specified categories in Application Data. You can import multiple categories at the same time. DATA_CENTER_FILE: File type. Imports the specified files from Application Data. You can import multiple files at the same time. If you set this parameter to DATA_CENTER_CATEGORY, you must specify the `CategoryIds` parameter. If you set this parameter to DATA_CENTER_FILE, you must specify the `DocumentIds` parameter. To create an empty knowledge base, use an empty category that contains no files: set this parameter to DATA_CENTER_CATEGORY and specify the ID of the empty category for `CategoryIds`. Valid values: DATA_CENTER_CATEGORY : Category type DATA_CENTER_FILE : File type	DATA_CENTER_FILE
DocumentIds	array	No	You can import files when you create a knowledge base. Specify the list of files to import (by file ID). We recommend importing no more than 10,000 files. If you have more files, you can call the SubmitIndexAddDocumentsJob operation later to import them.
	string	No	The file ID, which is the `FileId` returned by the AddFile operation. You can also obtain it on the Files tab of the file connector under Data Connections by clicking the ID icon next to the file name.	file_9a65732555b54d5ea10796ca5742ba22_xxxxxxxx
CategoryIds	array	No	You can import files when you create a knowledge base. Specify category IDs to import all files under the corresponding categories. We recommend importing no more than 500 files. If you have more files, you can call the SubmitIndexAddDocumentsJob operation later to import them.
	string	No	The category ID, which is the `CategoryId` returned by the AddCategory operation. You can also obtain it on the Files tab of the file connector under Data Connections by clicking the ID icon next to the category.	ca_hiu2383nfxxxx
TableIds	array	No	Obtain the table ID on the Tables tab of the table connector under Data Connections by clicking the ID icon next to the table name. If the list contains multiple IDs, only the first one is used.
	string	No
SinkType	string	Yes	The vector storage type of the knowledge base. For more information, see Knowledge bases. Valid values: BUILT_IN: The vector data is hosted on the Alibaba Cloud Model Studio platform. ADB: AnalyticDB for PostgreSQL database. If you need advanced features such as database management, auditing, and monitoring, we recommend choosing ADB. If you have not used ADB storage on Alibaba Cloud Model Studio, go to the Create Knowledge Base page, set the vector storage type to ADB-PG, and follow the on-screen instructions to complete the authorization. If you specify ADB for this parameter, you must specify the `SinkInstanceId` and `SinkRegion` parameters. Valid values: BUILT_IN : BUILT_IN ADB : ADB	BUILT_IN
SinkInstanceId	string	No	The ID of the AnalyticDB for PostgreSQL instance (required only when `SinkType` is set to ADB). Go to the AnalyticDB for PostgreSQL instance list page to obtain this ID.	gp-bp32109xxxx
SinkRegion	string	No	The region where the AnalyticDB for PostgreSQL instance is located (required only when `SinkType` is set to ADB). You can call DescribeRegions to obtain a list of regions.	cn-hangzhou
Columns	array<object>	No	The structure of the data table (column names, types, etc.).
	object	No	This parameter is not available yet. Do not specify it.
Column	string	No	This parameter is not available yet. Do not specify it.	school
IsRecall	boolean	No	Specifies whether the column participates in model responses. If enabled, the retrieval results of this column are used as input for the LLM to generate answers. Valid values: true: Enabled. false: Disabled.	true
IsSearch	boolean	No	Specifies whether the column participates in knowledge base retrieval. If enabled, the knowledge base is allowed to search this column for data. Valid values: true: Enabled. false: Disabled.	true
Name	string	No	The field name. It must be consistent with the header of the data table created in Application Data.	School
Type	string	No	The field type. It must be consistent with the header of the data table created in Application Data. Valid values: string double long datetime image_url	string
Description	string	No	The description of the knowledge base. The description can be 0 to 1,000 English or Chinese characters in length. The default value is empty.	Enterprise doc lib includes important materials such as company policies and product lists.
metaExtractColumns	array<object>	No	The metadata extraction configuration. Metadata is a series of additional attributes related to unstructured data content. These attributes are integrated into text chunks as key-value pairs. For more information, see Knowledge bases.
	object	No
Key	string	No	The metadata field, which can be 1 to 50 characters in length and must consist of letters or underscores. If you specify this parameter, you must also specify the `Value` and `Type` parameters.	author
Value	string	No	The value of the metadata field.	Tim
Type	string	No	The method for obtaining the value of the metadata field. Valid values: constant: Constant. variable: Variable. custom_prompt: Large language model. regular: Regular expression. keywords: Keyword search. Valid values: constant : Constant extraction keywords : Keyword extraction custom_prompt : Large language model variable : Variable extraction regular : Regular expression	constant
Desc	string	No	The Chinese description of the metadata field. The description can be 0 to 1,000 characters in length and can contain Chinese characters, letters, digits, underscores (_), hyphens (-), periods (.), and colons (:). The default value is empty.	Author name
EnableLlm	boolean	No	If enabled, the metadata field and its value participate in the LLM answer generation process along with the content of text chunks. Valid values: true: Enabled. false: Disabled. The default value is false. Valid values: true : Enabled false : Disabled	false
EnableSearch	boolean	No	If enabled, the metadata field and its value participate in the knowledge base retrieval process along with the content of text chunks. Valid values: true: Enabled. false: Disabled. The default value is false. Valid values: true : Enabled false : Disabled	false
enableHeaders	boolean	No	Specifies whether to use the first row of all .xlsx and .xls files as the table header and append it to each text chunk, preventing the LLM from treating the header as a regular data row. We recommend enabling this feature only when all imported files are in .xlsx or .xls format and contain a header. Otherwise, you do not need to enable it. Valid values: true: Enabled. false: Disabled. If you do not specify this parameter, this feature is disabled by default. Valid values: true : Enabled false : Disabled	false
chunkMode	string	No	Enables custom chunking and specifies the chunking policy. For more information, see Knowledge bases. Possible values (only one value can be specified at a time): length: Chunks by length. The text is strictly chunked according to the `ChunkSize` and `OverlapSize` you specify. If you do not specify these two parameters, the system uses the default values (`ChunkSize` is 500 and `OverlapSize` is 100). Chunking by length does not support `Separator` (it is ignored even if specified). page: Chunks by page. If `ChunkSize` is specified, it is also considered during chunking (if not specified, the default value 500 is used). Chunking by page does not support `OverlapSize` or `Separator` (they are ignored even if specified). h1: Chunks by level-1 heading. If `ChunkSize` is specified, it is also considered during chunking (if not specified, the default value 500 is used). Chunking by level-1 heading does not support `OverlapSize` or `Separator` (they are ignored even if specified). h2: Chunks by level-2 heading. If `ChunkSize` is specified, it is also considered during chunking (if not specified, the default value 500 is used). Chunking by level-2 heading does not support `OverlapSize` or `Separator` (they are ignored even if specified). regex: Chunks by regular expression. In this case, you must specify the `Separator` parameter. If `ChunkSize` is specified, it is also considered during chunking (if not specified, the default value 500 is used). Chunking by regular expression does not support `OverlapSize` (it is ignored even if specified). If you do not specify this parameter, smart chunking is used by default. Valid values: regex : Chunks by regular expression length : Chunks by length h1 : Chunks by level-1 heading h2 : Chunks by level-2 heading page : Chunks by page	regex
EnableRewrite	boolean	No	Specifies whether to enable multi-turn conversation rewriting. Valid values: true: Enabled. false: Disabled. If you do not specify this parameter, this feature is enabled by default. Valid values: true : Enabled false : Disabled	true
CreateIndexType	string	No	This parameter is not available yet. Do not specify it.	standard
pipelineCommercialType	string	No	The edition type of the knowledge base. Valid values: standard: Standard Edition enterprise: Ultimate Edition	standard
pipelineCommercialCu	integer	No	Specifies the number of RCUs for the knowledge base (required only when pipelineCommercialType is set to enterprise). Valid range: [1-200].	1
pipelineRetrieveRateLimitStrategy	string	No	The rate limiting policy for the knowledge base dependency chain (required only when pipelineCommercialType is set to enterprise). Value: downgrade: Degrades the service (switches to a lightweight retrieval chain). If you do not specify this parameter, the default value downgrade is used.	downgrade
datasourceCode	string	No	The data source code. This parameter is required when creating a data query knowledge base and is used together with table and database. We recommend using the new parameter connectId, which you can obtain from the data connector card on the Data Connections page. The current parameter is still compatible but will no longer be maintained. This operation does not support associating custom databases. Use the Alibaba Cloud Model Studio console to create them.	260xxx
table	string	No	The name of the data table. This parameter is required when creating a data query knowledge base. The data table must exist in the data source specified by connectId or datasourceCode.	lance
database	string	No	The name of the database. This parameter is required when creating a data query knowledge base. The database must exist in the data source specified by datasourceCode.	database_a6eacabe6
knowledgeType	string	No	The specific knowledge type, which further indicates the type of data processed by the knowledge base. This parameter and knowledgeScene must be provided or omitted together. They cannot be set separately. If both are omitted, the system uses the default configuration based on structureType. Setting constraints: The value of this parameter must match the structureType you select and determines the valid values of knowledgeScene. Valid values: document: Document search. Must be used together with structureType: unstructured. table: Data query. Must be used together with structureType: structured. image: Image Q&A. Must be used together with structureType: structured. multimedia: Audio and video search. Must be used together with structureType: unstructured.	document
knowledgeScene	string	No	The specific usage scenario of the knowledge base. This parameter and knowledgeType must be provided or omitted together. They cannot be set separately. If both are omitted, the system uses the default configuration based on structureType. Setting constraints: The value of this parameter depends entirely on the knowledgeType you set. Values and linkage relationships: When knowledgeType is document, knowledgeScene can be set to basic_document_qa (basic document Q&A), visual_document_qa (illustrated replies), lite_document_qa (fast Q&A), or visual_perception_qa (visual understanding). When knowledgeType is table, knowledgeScene is set to basic_table_qa (basic table Q&A). When knowledgeType is image, knowledgeScene is set to image_qa (image Q&A). When knowledgeType is multimedia, knowledgeScene is set to basic_multimedia_qa (audio and video search Q&A).	basic_document_qa
connectId	string	No	The connector identifier, which you can obtain from the data connector card on the Data Connections page. This parameter replaces the datasourceCode parameter. Use connectId going forward. When creating a data query knowledge base, you must also specify the table parameter.	conn_mysql_xxx_xxx
channelType	string	No	This parameter is not available yet. Do not specify it.	connector
RerankMode	string	No	Specifies the instruction intervention mode of the reranking model to determine its scoring preference. Valid values: qa: (Default) Q&A mode. The model tends to assign higher scores to candidates that can directly answer the query. We recommend using this mode in Q&A scenarios. similar: Similarity mode. The model tends to assign higher scores to candidates that are highly consistent with the query content. We recommend using this mode in matching and retrieval scenarios. custom: Custom mode. The ranking behavior of the model is determined by the instructions in the rerank_instruct parameter. Valid values: similar: Similarity mode. : similar: Similarity mode. custom: Custom mode. : custom: Custom mode. qa: (Default) Q&A mode. : qa: (Default) Q&A mode.	qa
RerankInstruct	string	No	Provides a natural language instruction to fine-tune the behavior of the reranking model. This parameter takes effect only when rerank_mode is set to "custom".

Response elements

Element	Type	Description	Example
	object	Schema of Response
Code	string	Error status code
Data	object	The business data returned when the request is successful.
Id	string	The knowledge base ID, also known as `IndexId`. It is the unique identifier of the created knowledge base. Keep this value safe. It will be used for all subsequent API operations related to this knowledge base.	jkurxhxxxx
Message	string	Error message
RequestId	string	Request ID	17204B98-xxxx-4F9A--2446A84821CA
Status	string	The status code returned by the interface.	"200"
Success	boolean	Indicates whether the request is successful. Possible values: true: Successful false: Failed	true

Examples

Success response

JSON format

{
  "Code": "",
  "Data": {
    "Id": "jkurxhxxxx"
  },
  "Message": "",
  "RequestId": "17204B98-xxxx-4F9A--2446A84821CA",
  "Status": "\"200\"",
  "Success": true
}

Error codes

Visit the Error Center to view more error codes.

Release notes

For more information, see Change details.