Skip to main content
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Knowledge base

CreateIndex

Creates a knowledge base, either an unstructured knowledge base based on documents or audio/video, or a structured knowledge base for data queries or image-based Q&A.

Operation description

  • Permission requirements:
    • Resource Access Management (RAM) user: Obtain API permissions for Alibaba Cloud Model Studio first (you can use the AliyunBailianDataFullAccess policy, which includes the sfm:CreateIndex permission required by this operation), and join a workspace before invoking this operation.
    • Alibaba Cloud account: Has permissions by default and can invoke this operation directly.
  • Calling method: Use the latest Alibaba Cloud Model Studio SDK. The SDK has encapsulated the complex signature calculation logic and simplifies the invocation procedure.
  • What to do next: This operation only performs initialization of the knowledge base creation job. After invoking this operation, you must invoke the SubmitIndexJob operation to complete the creation (otherwise, you will get an empty knowledge base). For code examples, refer to Knowledge Base API Guide.
  • Idempotence: This operation does not have idempotence. Repeated invocations may create multiple knowledge bases with the same name. Implement idempotent invocations by querying first and then creating.
Rate limit: This operation is subject to rate limiting. 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:CreateIndex

create

*All Resource

*

NoneNone

Request syntax 

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

Path Parameters

Parameter

Type

Required

Description

Example

WorkspaceId

string

Yes

The workspace ID, which specifies the workspace in which to create the knowledge base. For more information, see How to use workspaces.

llm-3z7uw7fwz0vexxxx

Request parameters

Parameter

Type

Required

Description

Example

Name

string

Yes

The knowledge base name. The name must be 1 to 20 characters in length and can contain Chinese characters, letters, digits, underscores (_), hyphens (-), periods (.), and colons (:).

EnterpriseHelpDocLibrary.

StructureType

string

Yes

The knowledge base type.

Valid values:

  • unstructured: A document search or audio/video knowledge base. The default scenario for document search type is basic document Q&A.

The knowledge base type cannot be changed after creation.

Valid values:

  • unstructured :

    unstructured

unstructured

EmbeddingModelName

string

No

  • e embedding model used by the knowledge base. The embedding model transforms the original input prompt and knowledge text into numerical vectors for similarity comparison. The default text-embedding-v2 model (cannot be changed) supports Chinese, English, and multiple other languages, and performs normalization on vector results. For more information, see Vectorization. Valid values:

  • text-embedding-v2

Default value: empty, which uses the text-embedding-v2 model.

text-embedding-v4

RerankModelName

string

No

The reranking model used by the knowledge base. The reranking model is an external scoring system that calculates the similarity score between the user query and each text chunk in the knowledge base, sorts them in descending order, and returns the top K text chunks with the highest scores. Valid values:

  • gte-rerank-hybrid: official reranking.

  • gte-rerank: gte-rerank reranking.

Default value: empty, which uses gte-rerank-hybrid.

If you only need semantic reranking, use gte-rerank. If you need both semantic reranking and text matching features to ensure relevance, use gte-rerank-hybrid.

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 similarity scores exceeding this value are recalled. This parameter filters the text chunks returned by the reranking model. Value range: [0.01-1.00].

If not specified, the default value is 0.01.

0.20

ChunkSize

integer

No

The chunk size, which specifies the maximum number of characters per text chunk. When this length is exceeded, the text is likely to be truncated.

Value range: [1-6000]. If not specified, the default value is 500.

If ChunkSize is set to a value less than 100, you must also set OverlapSize. You can also leave both parameters unspecified, and the system uses default values.

128

OverlapSize

integer

No

The chunk overlap size, which specifies the number of overlapping characters between the current text chunk and the previous text chunk. Value range: [0-1024].

If not specified, the default value is 100.

OverlapSize must be less than ChunkSize. Otherwise, chunking exceptions occur.

16

Separator

string

No

This parameter is not available. Do not pass this parameter.

(?<=。)

SourceType

string

No

This parameter is required in the latest SDK. Otherwise, calling the SubmitIndexJob operation returns an error: Required parameter(data_sources) missing or invalid.

The data source type. Valid values:

  • DATA_CENTER_CATEGORY: Category type. Imports all files under specified categories in Application Data. Multiple categories can be imported simultaneously.

  • DATA_CENTER_FILE: File type. Imports specified files from Application Data. Multiple files can be imported simultaneously.

If this parameter is set to DATA_CENTER_CATEGORY, you must specify the CategoryIds parameter. If this parameter is set 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 pass the empty category ID in CategoryIds.

Valid values:

  • DATA_CENTER_CATEGORY :

    category type.

  • DATA_CENTER_FILE :

    file type.

DATA_CENTER_FILE

DocumentIds

array

No

The list of files to import when creating the knowledge base. Specify file IDs here. We recommend importing no more than 10,000 files. For remaining files, call the SubmitIndexAddDocumentsJob operation to continue importing.

string

No

The file ID, which is the FileId returned by the AddFile operation, or obtained by clicking the ID icon next to the file name on the Files tab of Application Data.

file_9a65732555b54d5ea10796ca5742ba22_xxxxxxxx

CategoryIds

array

No

The list of category IDs to import when creating the knowledge base. All files under the specified categories are imported. We recommend importing no more than 500 files. For remaining files, call the SubmitIndexAddDocumentsJob operation to continue importing.

string

No

The category ID, which is the CategoryId returned by the AddCategory operation, or obtained by clicking the ID icon next to the category name on the Files tab of Application Data.

ca_hiu2383nfxxxx

TableIds

array

No

This parameter is not available. Do not pass this parameter.

string

No

SinkType

string

Yes

The vector storage type of the knowledge base. For more information, see Knowledge base. Valid values:

  • BUILT_IN: 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, select ADB.

If you have not used ADB storage on Alibaba Cloud Model Studio before, go to the Create Knowledge Base page, select ADB-PG as the vector storage type, and complete authorization as prompted. If you pass ADB, you must specify the SinkInstanceId and SinkRegion parameters.

Valid values:

  • BUILT_IN :

    BUILT_IN

  • ADB :

    ADB

BUILT_IN

SinkInstanceId

string

No

The AnalyticDB for PostgreSQL instance ID (required only when SinkType is set to ADB). Obtain this ID from the AnalyticDB for PostgreSQL instance list page.

gp-bp32109xxxx

SinkRegion

string

No

The region of the AnalyticDB for PostgreSQL instance (required only when SinkType is set to ADB). Call DescribeRegions to obtain the list of regions.

cn-hangzhou

Columns

array<object>

No

This parameter is not available. Do not pass this parameter.

object

No

This parameter is not available. Do not pass this parameter.

Column

string

No

This parameter is not available. Do not pass this parameter.

school

IsRecall

boolean

No

This parameter is not available. Do not pass this parameter.

true

IsSearch

boolean

No

This parameter is not available. Do not pass this parameter.

true

Name

string

No

This parameter is not available. Do not pass this parameter.

School.

Type

string

No

This parameter is not available. Do not pass this parameter.

string

Description

string

No

The knowledge base description. The description can be up to 1000 characters in length. Default value: empty.

The enterprise help document library includes important materials such as company policies and product catalogs.

metaExtractColumns

array<object>

No

The metadata extraction configuration. Metadata is a set of additional attributes related to unstructured data content. These attributes are integrated into text chunks as key-value pairs. For more information, see Knowledge base.

object

No

Key

string

No

The metadata field. The field must be 1 to 50 characters in length and can contain only letters and underscores. If this parameter is specified, you must also specify the Value and Type parameters.

author

Value

string

No

The value of the metadata field.

Tim

Type

string

No

The extraction method for 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 up to 1000 characters in length and can contain Chinese characters, letters, digits, underscores (_), hyphens (-), periods (.), and colons (:). Default value: empty.

AuthorName.

EnableLlm

boolean

No

Specifies whether this metadata field and its value participate in the large language model's answer generation process along with the text chunk content. Valid values:

  • true: Enabled.

  • false: Disabled.

Default value: false.

Valid values:

  • true :

    enabled.

  • false :

    disabled.

false

EnableSearch

boolean

No

Specifies whether this metadata field and its value participate in knowledge base retrieval along with the text chunk content. Valid values:

  • true: Enabled.

  • false: Disabled.

Default value: false.

Valid values:

  • true :

    enabled.

  • false :

    disabled.

false

enableHeaders

boolean

No

Specifies whether to treat the first row of all xlsx and xls files as headers and concatenate them into each text chunk, preventing the large language model from treating headers as regular data rows.

Enable this feature only when all imported files are in .xlsx or .xls format and contain headers. Otherwise, do not enable it.

Valid values:

  • true: Enabled.

  • false: Disabled.

If not specified, this feature is disabled by default.

Valid values:

  • true :

    enabled.

  • false :

    disabled.

false

chunkMode

string

No

This parameter is not available. Do not pass this parameter.

Valid values:

  • regex :

    chunk by regular expression.

  • length :

    chunk by length.

  • h1 :

    chunk by first-level headings.

  • h2 :

    chunk by second-level headings.

  • page :

    chunk by page.

regex

EnableRewrite

boolean

No

Specifies whether to enable multi-turn conversation rewriting. Valid values:

  • true: Enabled.

  • false: Disabled.

If not specified, this feature is enabled by default.

Valid values:

  • true :

    enabled.

  • false :

    disabled.

true

CreateIndexType

string

No

This parameter is not available. Do not pass this parameter.

standard

pipelineCommercialType

string

No

This parameter is not available. Do not pass this parameter.

standard

pipelineCommercialCu

integer

No

This parameter is not available. Do not pass this parameter.

1

pipelineRetrieveRateLimitStrategy

string

No

This parameter is not available. Do not pass this parameter.

downgrade

knowledgeType

string

No

The data source code. Required when creating a data query knowledge base. Used together with the table and database parameters.

  • This operation does not support associating custom databases. Use the Alibaba Cloud Model Studio console to create them.

260xxx

RerankMode

string

No

The data table name. Required when creating a data query knowledge base.

The data table must exist in the data source specified by connectId or datasourceCode.

Valid values:

  • similar: 相似模式。 :

    similar: 相似模式。

  • custom: 自定义模式。 :

    custom: 自定义模式。

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

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

  • similar: :

    similar: Similarity mode.

  • custom: :

    custom: Custom mode.

  • :

    qa: (Default) Q&A mode.

lance

RerankInstruct

string

No

The database name. Required when creating a data query knowledge base.

The database must exist in the data source specified by datasourceCode.

database_a6eacabe6

No

This parameter is not available. Do not pass this parameter.

document

No

This parameter is not available. Do not pass this parameter.

basic_document_qa

No

This parameter is not available. Do not pass this parameter.

conn_mysql_xxx_xxx

No

connector

No

This parameter is not available. Do not pass this parameter. [_single.params.RerankMode.enum.similar: 相似模式。]similar: Similarity mode. [_single.params.RerankMode.enum.custom: 自定义模式。]custom: Custom mode. [_single.params.RerankMode.enum.qa:（默认值） 问答模式。]qa: (Default) Q&A mode. [parameters.33.schema.enumValueTitles.similar: 相似模式。]similar: Similarity mode. [parameters.33.schema.enumValueTitles.custom: 自定义模式。]custom: Custom mode. [parameters.33.schema.enumValueTitles.qa:（默认值） 问答模式。]qa: (Default) Q&A mode.

Valid values:

  • similar: 相似模式。 :

    similar: 相似模式。

  • custom: 自定义模式。 :

    custom: 自定义模式。

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

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

qa

No

This parameter is not available. Do not pass this parameter.

Response elements

Element

Type

Description

Example

object

Schema of Response

Code

string

The error status code.

Data

object

The business data returned when the request succeeds.

Id

string

The knowledge base ID, also known as IndexId. This is the unique identifier of the created knowledge base.

Store this value properly. It is required for all subsequent API operations related to this knowledge base.

jkurxhxxxx

Message

string

The error message.

RequestId

string

The request ID.

17204B98-xxxx-4F9A--2446A84821CA

Status

string

The status code returned by the operation.

"200"

Success

boolean

Indicates whether the request was successful. Valid 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

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Application Calling
Application components
Assistant API (Deprecated)
More