Knowledge base - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

Large language models (LLMs) lack private and real-time knowledge, which can be solved by Retrieval-Augmented Generation (RAG). RAG retrieves information from external sources based on user input to enhance the accuracy of LLM responses. Model Studio provides the knowledge base feature that uses RAG capabilities to retrieve private and real-time knowledge.

Important

Only users who created Model Studio applications before April 21, 2025 can access the Applications tab and use all its features, including applications (Agent application, Workflow application, Agent orchestration application), components (Prompt, Plug-in), data (Knowledge base, Application data) and related APIs.

Application without a private knowledge base

Without a private knowledge base, the LLM cannot accurately answer questions about "Bailian phone".

Application with a private knowledge base

With a private knowledge base, the LLM can provide accurate answers to questions about "Bailian phone".

Supported formats

The knowledge base currently supports the following document formats as knowledge sources: pdf, docx, doc, txt, markdown, pptx, ppt, xlsx, xls, png, jpg, jpeg, bmp, and gif. This list may be incomplete. Refer to the description on the Data Import page.

You can import data from local uploads, Alibaba Cloud Object Storage Service (OSS), or Alibaba Cloud ApsaraDB RDS (data sources outside Alibaba Cloud such as online webpages, GitHub, and Notion are not currently supported).

Supported models

You can use knowledge bases in applications that use the following models.

Qwen-Max/Plus/Turbo
Open source Qwen2.5
Open source Qwen2
Currently, the DeepSeek models are not available. Stay tuned for future updates.

The above list is not exhaustive and may change at any time. For the actual information, refer to the models that can be selected when editing models in My Applications.

Create and use a knowledge base

Step 1: Import data

Before creating a knowledge base, import your documents into Model Studio as knowledge sources.

Note

Use API: You can use API to import unstructured data. To import structured data, you must use the console. To automatically update a structured knowledge base, you can build it based on an ApsaraDB RDS data table.
Import from RDS: If you want to build a knowledge base based on an RDS data table, see Create a knowledge base.

The Model Studio console supports importing Unstructured Data and Structured Data. Unstructured Data is not organized based on predefined table structure, while Structured Data is organized based on a predefined table structure.

Select Unstructured Data for:

Documents in formats such as PDF, DOCX, DOC, TXT, Markdown, PPTX, PPT, PNG, JPG, JPEG, BMP, or GIF.
Multiple XLSX or XLS documents, but their table structures may be different.
Importing documents from Object Storage Service (OSS).

Select Structured Data for:

Multiple XLSX or XLS documents with identical table structures.
Documents in XLSX or XLS format that will be used for FAQ scenarios. For example, an Excel document contains two columns: question and answer. A structured knowledge base allows you to limit Question column for retrieval, and Answer column for reference. Unstructured knowledge base can hardly achieve this effect.

Unstructured data

Go to the Application Data page and select the Unstructured Data tab.
Under Category Management on the left, select the desired category for data import.
Select the default category or click to create a new one. Each workspace can have up to 500 categories.
Each workspace can have up to 100,000 documents.
Click Import Data to go to the Import Data page.
For Import Method, select Upload Local File or OSS.
If you are importing data from OSS for the first time, you must first complete authorization as prompted and add the bailian-datahub-access tag to the desired bucket. For more information, see Import data from OSS.
Model Studio does not support OSS buckets in the following classes: Archive, Cold Archive, and Deep Cold Archive. Buckets with content encryption and private buckets are supported.
Model Studio cannot access files in the root directory of OSS. Select an existing sub-directory under the bucket or create a new sub-directory.
For Document Recoognition, the default is Intelligent Document Parsing (currently cannot be changed). However, you can configure parsing rules for different document formats through Data Parsing Settings for better effect.
Data Parsing Settings
On the Application Data page, you can configure parsing strategies. If you are not sure, just maintain the default settings.
Digital Parsing: Cannot parse illustrations and charts in documents.
Intelligent Parsing: The parser can extract texts from illustrations and generates summaries. These summaries, along with non-image content in the document, are chunked and embedded for knowledge base retrieval.
LLM Parsing: Agent applications using Qwen VL supports questions about the illustrations and charts in documents. If you requires understanding illustrations and charts in documents, select LLM Parsing.
(Optional) Configure Tags for documents.
When calling applications through API, you can specify tags in the request parameter tags. When the application retrieves the knowledge base, it first filters documents based on tags, thereby improving efficiency. For agent applications, you can also set tags when editing the application in the console (Knowledge Bas > + Knowledge Base > Advanced Configuration > Filter by Tag).
Click Confirm. The system will begin parsing and importing the documents. This may take some time.
Document parsing converts uploaded documents into a format that Model Studio can process. During peak periods, it may take longer time.
After parsing and importing are complete, click Details to the right of the corresponding document to view the imported document.
You can view documents imported within 90 days. Your documents will not be deleted after this period, but you cannot view them.

Structured data

Go to the Application Data page and select the Structured Data tab.

Create a new data table or select an existing one.

Each workspace can have up to 1,000 data tables, and each table can have up to 100,000 rows (including the header). Exceeding this limit will result in a failed import, so you may need to split the data in advance.

Create a new data table

Click to create a data table.

Enter a Table Name.

Configure the table structure by selecting Upload Excel File or Custom Header.

Option	Description
Upload Excel File	Model Studio will automatically identify the header in the uploaded document to create the data table structure accordingly. Then, it will import the remaining content as data records into the table.
Custom Header	Column Name and Type are required. Description is optional. Important Once the data table is created, you cannot modify the Column Name, Description, or Type. Make sure the table schema matches the schema of the data to be imported. For example, if the data table to be imported has 2 columns, the structure here must also have 2 fields with corresponding column names. Click New Columns or Delete in the Actions column to adjust the fields.

Upload your documents.
1. Click to select and upload documents (XLSX or XLS format).
  The documents must have a header that matches the structure of the data table. Otherwise, the import will fail.
2. Then, click Preview to view the imported data.
Click Confirm. The new data table will appear under Table Management on the left.

Select an existing data table

Select an existing data table under Table Management on the left and click Import Data.

For Import Type, select Upload and Overwrite or Incremental Upload.
You can click Download Template to download a blank document with the table header. Then, insert data to the template and upload it directly.
Click to select and upload documents (XLSX or XLS format).
The documents must have a header that matches the structure of the data table. Otherwise, the import will fail.
Then, click Preview to view the imported data.

Step 2: Create a knowledge base

Note

Maximum number: Each Alibaba Cloud account can create up to 5 knowledge bases associated with ApsaraDB RDS, with no other limitations.
For RAM user: If your RAM user needs to use the full functionality of knowledge bases, you must first grant data permissions to it (AliyunBailianDataFullAccess). If you are not familiar with the concept of RAM user, read Permissions first.

Console

Go to the Knowledge Base page. Click Create Knowledge Base.

Enter a Name and Description. For Data Type, select Unstructured Data or Structured Data.

After the knowledge base is created, the data type cannot be changed. A single knowledge base cannot support both unstructured and structured data.

Unstructured data

Configure the knowledge base.

Parameter

Description

Configuration Mode

You can select Recommended, which is based on Model Studio's best practices. If you select Custom, you can configure parameters for retrieval and recall.

After the knowledge base is created, all parameters in Configuration Mode, except for Similarity Threshold, cannot be changed.

Custom parameter settings

Multi-round Conversation Rewriting: When enabled, Model Studio will automatically adjust the original prompt based on the context to improve retrieval effectiveness.

Embedding Model: Converts the original prompt and knowledge text into numerical vectors for similarity comparison. The default DashScope text-embedding-v2 model (currently cannot be changed) model supports multiple languages, including English and Chinese, and normalizes the embedding results.

Rank Model: An external scoring system that calculates similarity scores between user querys and each text chunk in the knowledge base, sorts them in descending order, and returns the top K text chunks with the highest scores. For semantic ranking, select GTE-ReRank. For semantic ranking and text matching features, select Official Ranking (recommended).

Similarity Threshold: The minimum similarity score required for recalled chunks, used to filter the chunks returned by the Rank model. Lowering this threshold may recall more chunks, including less relevant ones. Increasing it reduces the number of recalled chunks, and may discard relevant ones.

Click Next Step to select documents to import.
If you have already imported documents, directly select them here. Otherwise, you must first go to the Unstructured Data and import the documents.
- Select Category: Import all documents under this category. You can select multiple categories.
- Select File: Select the files you want to import.
  You can select up to 50 documents at a time. Each document can be up to 100 MB in size or contain up to 1,000 pages. If a document exceeds these limits, you need to split it into multiple documents before importing.

Click Next Step to configure the Data Processing strategy.

Parameter	Description
Metadata Extraction (Optional)	Metadata is a series of additional attributes related to the content of unstructured documents, integrated into the chunks as key-value pairs. Role of metadata: Metadata provides context for documents, significantly enhancing the precision of knowledge base retrieval. For example, search for "Feature Overview of Product A" in the knowledge base. If all documents include "Feature Overview" but none mention "Product A", the knowledge base may recall numerous unrelated chunks. However, if you associate product name as metadata with all documents and their related chunks, the knowledge base can accurately filter out chunks related to "Product A" and containing "Feature Overview", thereby improving retrieval accuracy and reducing input token consumption. How to use: When calling applications through API, specify `metadata_filter` in the request. When retrieving from the knowledge base, the application will first filter relevant documents based on the metadata. Note: You cannot configure Metadata Extraction again after the knowledge base is created. Configure Metadata Extraction The example below shows the metadata of a document, containing 5 custom attributes: `date` (all years in the document), `reference` (all references in the document), `filename` (the document name), `keywords` (keywords in the document), and `author` (the author information). Enable Metadata Extraction, then click Meta Information Settings to attach uniform or personalized metadata to all documents in the knowledge base. The following image shows a metadata template as an example: Description of the metadata template Value: Constant: Attaches a fixed attribute to all documents in the knowledge base. For example, if all documents in the knowledge base share the same author, you can set `author` to constant. Variable: Attaches a variable attribute to each document in the knowledge base. Valid values: `file_name`: Attaches the name of the document to its metadata. `cat_name`: Attaches the category name where the document is located to the metadata. LLM: Matches the text content of each document in the knowledge base based on the Entity Description you specify. The system automatically recognizes and extracts relevant information from the document, then attach this information to the metadata. For example, to extract all years that appear in each document as a document attribute, set an LLM field named `date` and configure the following Entity Description: Regular: Matches the text content of each document in the knowledge base based on the regular expression you specify. Content that matches the expression is extracted and attached to the metadata. For example, to extract all references that appear in each document, assuming the references are enclosed in double quotation marks (""), set a regular field named `reference` and configure the following regular expression: Search by Keyword: The system searches for preset keywords in each document and add the found keywords to the metadata. For example, set the following keywords: Used for Retrieval: When enabled, the metadata field and value are used for knowledge base retrieval along with the chunks. When disabled, only the chunks are used for retrieval, the metadata field and value are not. Used for Model Reply: When enabled, the metadata field and value are used for response generation along with the chunks. When disabled, only the chunks are used for generation, the metadata field and value are not.

Table Header Assemble for Excel Files (Optional)	We recommend that you enable this when all imported documents are of the xlsx or xls formats and contain table headers. When enabled, the knowledge base considers the first rows of all xlsx or xls documents as headers. The headers are then appended to all chunks (rows). This prevents the LLM from mistakenly processing headers as ordinary data rows.
Document Splitting	Select Intelligent Splitting (recommended) or Custom Splitting. Role of document splitting: The knowledge base splits your documents into chunks and converts these chunks into vectors through the embedding model. The chunks and vectors are then stored in a vector database as key-value pairs. View the content of each chunk in the knowledge base. Note: You cannot configure Document Splitting after the knowledge base is created. An inappropriate splitting strategy may reduce retrieval and recall performance. Check text chunk quality. Intelligent Splitting: Uses the built-in chunking strategy, evaluated to deliver the best retrieval performance for most documents. Custom Splitting: If intelligent splitting does not work properly, you can customize the document splitting strategy. Configure custom splitting When using Custom Splitting, the knowledge base will first split the document into several paragraphs based on the selected Clause Identifier. Then, it create text chunks based on these paragraphs. During the splitting and chunking process, the knowledge base will try to maintain semantic integrity of each part, reduce unnecessary splitting and chunking, while trying to meet your requirements for Estimated Segment Length and Segment Overlap Length. Clause Identifier: Split the document into paragraphs according to the selected punctuation marks. You can select multiple marks, with an "OR" relationship. Custom sentence identifiers are not currently supported. Estimated Segment Length: The maximum number of characters in each chunk. Excessive texts will be truncated. Segment Overlap Length: The number of overlapping characters between two consecutive chunks. We recommend 10% to 25% of the estimated segment length to maintain semantic relevance between text chunks, which improves the recall quality. This value must be less than the Estimated Segment Length, otherwise it will cause chunking anomalies.

Structured data

Configure the knowledge base.

Parameter

Description

Configuration Mode

You can select Recommended, which is based on Model Studio's best practices. If you select Custom, you can configure parameters for retrieval and recall.

After the knowledge base is created, all parameters in Configuration Mode, except for Similarity Threshold, cannot be changed.

Custom parameter settings

Multi-round Conversation Rewriting: When enabled, Model Studio will automatically adjust the original prompt based on the context to improve retrieval effectiveness.

Click Next Step to select Data Source of structured data.

If you import structured data on the Structured Data tab, you will need to manually synchronize updates to the knowledge base.

If you import structured data through ApsaraDB RDS, data updates in the RDS table will be automatically synchronized to the knowledge base (generally within seconds, but slight delays may occur during peak periods).

Data Source	Description
Application Data	Select the table you want to import from Application Data. If no table is available, you must first import your table to Application Data.
Associate RDS	Synchronize data from specific data tables in the RDS instance to your knowledge base. Instance limitations: Only RDS instances with MySQL Engine (no version restrictions) are supported. PostgreSQL and other engines are not supported. No restrictions on instance regions. Only Basic Edition and High-availability Edition are supported. Database proxy is not supported. Database and table limitations: The knowledge base has no limit on the amount of data in the associated RDS database and data table, but the size of each row must be less than 10 MB. DDL operations on the source table are not recommended after creating the knowledge base (For example, DROP TABLE, RENAME TABLE, TRUNCATE TABLE, ADD COLUMN, DROP COLUMN), because they may cause data synchronization failures between RDS and the knowledge base. For more information, see DDL operations. To ensure the knowledge base can import data from RDS, you need to configure whitelist for the RDS instance. You must add all OP addresses of DTS and Model Studio to the whitelist of your RDS instance. Otherwise, the indexing will fail.

Click Next Step to configure the index. Index Configuration cannot be changed after the knowledge base is created.

Parameter	Description
Used for Retrieval	When enabled, the knowledge base is allowed to search within this column's data.
Used for Model Reply	When enabled, the retrieval results from this column will be used as references for the LLM. In the example below, Used for Retrieval is enabled for "Name", "Sex", "Position", and "Age". Used for Model Reply is enabled for "Name" and "Position." The knowledge base will search across all column data, but only provide the "Name" and "Position" columns to the LLM as references. Because "Age" is not used for reply, the model cannot answer questions about Zhang's age.

Click Import.

API

We recommend that you use the latest version of GenAI Service Platform to call the following APIs. You can debug the APIs online and generate code samples in multiple languages, such as Java and Node.js.

Important

RAM users must first obtain data permissions

Alibaba Cloud accounts do not need authorization and can skip this note. If you are not familiar with concepts such as Alibaba Cloud account and RAM user, read Permissions first.

Before your RAM user calls the following APIs (CreateIndex, SubmitIndexJob, and others), make sure that the user has the AliyunBailianDataFullAccess system policy and belongs to at least one Model Studio workspace. For more information, see Grant data permissions to a RAM user.

Take the following steps to create a unstructured knowledge base:

You cannot use API to create structured databases. Use the console instead.

Call CreateIndex.
The returned Data.Id is the knowledge base ID. Keep this value safe because it will be used for all subsequent API operations related to the knowledge base.
- In the StructureType field, specify the data structure type used to create the knowledge base. For unstructured data, enter "unstructured".
- In the RerankModelName field, specify the ranking model name. For official ranking, enter "gte-rerank-hybrid".
  The rerank model is used to reorder the knowledge text results recalled from the knowledge base based on semantic relevance. Official Reranking is recommended.
- In the SinkType field, specify the vector storage type for the knowledge base.
  The built-in vector database can meet basic needs. For advanced features such as management, auditing, and monitoring, use ADB-PG (AnalyticDB for PostgreSQL).
  - To specify the Built-in vector database, enter "BUILT_IN".
  - To specify ADB-PG database, enter "ADB".
The previous CreateIndex only initializes the knowledge base construction. You need to call SubmitIndexJob to complete the process. Otherwise, you will get an empty knowledge base. The task takes some time. To query the task status, call GetIndexJobStatus. If Data.Status in the response is "COMPLETED", the knowledge base creation is complete.

After the knowledge base is created, you can associate it with your agent or workflow applications under the same workspace in My Applications. If you use API to call your application, you can pass the knowledge base ID through the rag_options parameter.

Also, you can call the Retrieve operation to retrieve from the knowledge base directly without using applications.

Step 3: (Optional) Test the knowledge base

Hit Test is used to evaluate the semantic retrieval performance of a knowledge base under a given Similarity Threshold, for example, to check whether chunks are correctly recalled. The test helps determine whether further adjustment of the similarity threshold is needed to ensure that the LLM can obtain valid knowledge from the knowledge base. To perform a hit test, expand Hit Test (Optional) and take the steps.

Similarity Threshold: The minimum similarity score required for recalled chunks, used to filter the chunks returned by the ranking model. Lowering this threshold may recall more chunks, including less relevant ones. Increasing it reduces the number of recalled chunks, and may discard relevant ones.

Important

RAM users must first obtain data permissions

Alibaba Cloud accounts do not need authorization and can skip this note. If you are not familiar with concepts such as Alibaba Cloud account and RAM user, read Permissions first.

Before hit testing, make sure that the user has the AliyunBailianDataFullAccess system policy and belongs to at least one Model Studio workspace. For more information, see Grant data permissions to a RAM user.

Hit Testing (Optional)

Recommended steps
Design test cases that can cover common questions. Choose an appropriate similarity threshold based on the use scenario of the knowledge base and the quality of the documents. Perform the hit test and view the recall results of the knowledge base. Adjust the similarity threshold of your knowledge base according to the recall results..

Console

Go to the Knowledge Base page, click Hit Test on the right side of the desired knowledge base.
Modify the Similarity Threshold and then enter keywords in the input box. Click Test to start the test.
In the Recall Result section, view the hit situation of the keywords (sorted in descending order of similarity value). Click each chunk to view the corresponding chunk content.
Click View Recall History to view the recall history of the keywords.

API

Important

RAM users must first obtain data permissions

Alibaba Cloud accounts do not need authorization and can skip this note. If you are not familiar with concepts such as Alibaba Cloud account and RAM user, read Permissions first.

Before your RAM user calls the following API (Retrieve), make sure that the user has the AliyunBailianDataFullAccess system policy and belongs to at least one Model Studio workspace. For more information, see Grant data permissions to a RAM user.

We recommend that you use the latest version of GenAI Service Platform to call Retrieve. You can debug the APIs online and generate code samples in multiple languages, such as Java and Node.js.

Before you call this operation, make sure that your knowledge base is created and is not deleted.

We recommend that you set appropriate timeout and retry policy for requests if large-scale data retrieval is required.

The RerankMinScore parameter specifies the similarity threshold. This value is used to filter recalled text chunks, meaning only text chunks with similarity scores larger than this value (0.2 by default) will be recalled. Increasing this value will reduce the number of recalled text chunks.

Step 4: Use the knowledge base

Now you can associate your created knowledge base with agent or workflow applications under the same workspace in My Applications. If you use API to call your application, you can pass the knowledge base ID through the rag_options parameter. Both applications support multiple (up to 5) knowledge bases simultaneously based on the multi-channel recall strategy. Currently, custom retrieval order is not supported.

Multi-channel recall strategy: If the application is associated with three knowledge bases, the system retrieves chunks related to the input from these bases, ranks them with the Rank model, and selects the top K most relevant ones as the reference for the LLM.

Also, you can call the Retrieve operation to retrieve from the knowledge base directly without using applications.

Agent application

Scenario

This is an example of a Q&A agent application based on a knowledge base. The knowledge base effectively provides private and the latest information for the LLM. Such an application is suitable in scenarios such as personal assistants, customer service, and technical support.

Use a knowledge base in an agent application

Go to My Applications and click Manage on the desired agent application card. Enable Knowledge Base Retrieval Augmentation. The corresponding prompt is automatically filled in Prompt. Click Configure Knowledge Base and add one or more knowledge bases.

Retrieve Configuration (Optional)

Changes to Retrieve Configuration only affect the current application.

Assembly Strategy: Used to balance the comprehensiveness and performance of knowledge base recall results. You can choose By Recall Quantity or Intelligent Assembly.

Choose By Recall Quantity in scenarios with clear requirements for the amount of input information. Choose Intelligent Assembly to maximize the use of input space.

By Recall Quantity: You can configure both Number of Recalled Chunks and Maximum Length of Assembly. The system first splices the recalled chunks based on the number of recalled chunks, and then checks the overall length. If it exceeds the maximum length, the chunks are truncated.
Intelligent Assembly: You can configure only Maximum Length of Assembly. While ensuring the maximum length, the system recalls as many related chunks as possible.

Parameter	Description
Number of Recalled Chunks	The K value in the multi-channel recall strategy (Up to 20). It specifies the quantity of text chunks that the Rank model passes to the LLM. The value must not exceed the maximum length. Increasing the K value can enhance the precision of LLM responses at the cost of increased token consumption.
Maximum Length of Assembly	The upper limit of the assembled reference for the LLM. The chunks are truncated if excessing the limit and the excess part will be discarded. Increasing this value usually improves the coverage of the knowledge base, recalling more chunks that may be related to the user query, but it also increases the response delay for each question and answer.

Response Range Setting: Controls the knowledge source referenced when the application responds, you can include or exclude the influence of the general knowledge of the LLM.

Knowledge Range Judgement: Choose Search Threshold or Search Threshold + LLM Judgement.
If you choose Search Threshold, the search is based only on the similarity threshold. This method does not work well if the input keywords cannot precisely match the chunks in semantic terms. Instead, you can choose Search Threshold + LLM Judgement. The potential chunks are first filtered based on the similarity threshold, and then an LLM analyzes the relevance to further improve the accuracy.
Set Judgment Prompt: The rules used by the LLM to determine the relevance between the user input and the recalled chunks.

Not Processed in Knowledge Base: Choose LLM Knowledge or Fixed Reply.

Knowledge Base + LLM Knowledge

Knowledge Base Only

The response integrates the knowledge retrieved from the knowledge base and the general knowledge of the LLM.

The application's answers will be strictly based on knowledge retrieved from the knowledge base.

Show Source: When enabled, all referenced sources are displayed in the response, but this increases the output token consumption.
For example, the application references multiple different knowledge bases.
After enabling Show Source, the application will provide all sources referenced, down to document names or data table names.

Workflow application

Scenario

This is an example of a Q&A workflow application based on a knowledge base. The execution logic of the process is: First, perform knowledge retrieval in the knowledge base based on user query. The recalled chunks are then passed into the LLM node along with the query for answer generation.

Use a knowledge base in a workflow application

Go to My Applications and click Manage on the desired workflow application card.

Configure upstream node: Create a Knowledge Base node and connect it to the Start node.
Select query variable: In the Input dropdown list of the Knowledge Base node, select query.
For Q&A workflow applications, the sys.query variable of the Start node is usually selected as the query variable.
Select Knowledge Base: In the Select Knowledge Base dropdown list, select the knowledge base to be referenced.
(Optionl) Adjust topK: The K value of the multi-channel recall strategy. It specifies the quantity of text chunks that the Rank model passes to the LLM. The value must not exceed the maximum length. Increasing the K value can enhance the precision of LLM responses at the cost of increased token consumption.
Configure downstream node: Create an LLM node and set it as the downstream node of the Knowledge Base node. In the Prompt of the large model node, guide the LLM to refer to the knowledge base.
```
System Prompt:
# Knowledge base
Remember the following materials that may help you answer questions:${Retrieval_xxxx.result}

User Prompt
${sys.query}
```
Enter / to replace {{Retrieval_xxxx.result}} and {{sys.query}} to the actual variables in your workflow.
Click Test or Publish. When the user asks a question, if the knowledge base node matches related chunks, the chunks are filled into the system variable sys.query to assist the LLM node in generating a response. If no related chunks are matched, the LLM node directly respond to the system variable sys.query.

Manage and maintain knowledge base

View knowledge base

Console

View the full list of knowledge bases under a workspace, search for a specific knowledge base, and view the basic information, configuration, and content of a specified knowledge base.

Go to the Knowledge Base page, where you can:
- View knowledge base list: View all knowledge bases in the current workspace and their information, including the number of knowledge entries and the last updated time.
- Search for a knowledge base: Enter a name in the search box, then click to search for it. Fuzzy search is supported.
- View knowledge base ID: Hover over next to a knowledge base. Click to copy the ID.
Click View on the right side of desired knowledge base.
- For an unstructured knowledge base, on this page you can:
  - View knowledge list: The page displays the full list of documents imported into the knowledge base, along with their size, status, import time, and other information.
  - Search for a document: Exact search by document name and filter results by status.
  - View document chunks: Uploaded documents are stored as chunks. Click View Chunks button to the right of the document, and you can:
    - View all chunks in the document.
      You cannot view the historical version of chunks.
    - Modify the content of chunks.
      After you click save, the original content becomes invalid, and the new content is used for knowledge base retrieval.
    - Enable or disable specific chunks.
      The knowledge base cannot search in disabled chunks.
  - Manage tags: Add or remove tags.
  - View metadata: View the metadata of the documents.
    After the knowledge base is created, metadata cannot be modified.
- For a structured knowledge base, on this page you can:
  - View the schema and data of the data table: The page displays the schema of the current knowledge base, including all column names, and fully presents the imported structured data.
  - View the index of the data table: Click View Index at the top right of the data table. Index configuration cannot be modified.

API

Important

RAM users must first obtain data permissions

Alibaba Cloud accounts do not need authorization and can skip this note. If you are not familiar with concepts such as Alibaba Cloud account and RAM user, read Permissions first.

Before your RAM user calls the following APIs (ListIndices and ListChunks), make sure that the user has the AliyunBailianDataFullAccess system policy and belongs to at least one Model Studio workspace. For more information, see Grant data permissions to a RAM user.

View the list of knowledge bases
Call the ListIndices operation to obtain a list of knowledge bases in a specified workspace. This operation provides details on each knowledge base, including their configuration statuses.
View the chunk list of a specified knowledge base
Call the ListChunks operation to query detailed information on all text chunks within a document in an unstructured knowledge base. The operation queries detailed information on all text chunks of a structured knowledge base.
Before you call this operation, make sure that your knowledge base is created and is not deleted.

Modify knowledge base

After creating a knowledge base, you can customize and modify basic information and some configurations. You cannot use API to edit knowledge bases.

Go to the Knowledge Base Index page.
Click Modify on the right side of the desired knowledge base to enter the Modify Knowledge Base page, where you can modify the Name, Description, and Similarity Threshold.

Update knowledge base

You can update the knowledge base by supplementing private knowledge, introducing the latest information, and removing outdated information. Regular updates help maintain the accuracy and timeliness of the knowledge base. When the content of a knowledge base no longer shows the latest situation or contains errors, it should be updated as soon as possible.

Console

Unstructured knowledge base

Update documents
To add or delete documents, you can directly add or delete the document as described below. If you want to modify the content of existing documents in the knowledge base, delete the old version first, and then import the new version.
- Import document: Go to the Knowledge Base page, click View on the right side of the desired knowledge base. Then, click Import Data. If the new document is already uploaded to Application Data, you can directly select it here. Otherwise, upload the document first.
- Delete document: On the knowledge base details page, click Delete in the Actions column of the desired document. This operation will not delete the data imported in Step 1.
  Click Batch Manage to delete one or more documents at a time.
- Manage chunks (Optional): If you need to disable, enable, or modify the chunks of imported documents, you can click View Chunks on the right side of the document to manage the chunks.
  - You can not Add new chunks.
  - View all chunks of the document.
    You cannot view the historical version of chunks.
  - Modify the content of chunks.
    After you click save, the original content becomes invalid, and the new content is used for knowledge base retrieval.
  - Enable or Disable specific chunks.
    The knowledge base cannot search in disabled chunks.
- Update document tags (Optional): Click Tag in the Actions column.
Synchronize changes
Your document updates and content modifications to the knowledge base take effect automatically in real time.
Reference knowledge base
Your changes take effect automatically in real time to all applications associated with the knowledge base.

Structured knowledge base

If you import structured data from ApsaraDB RDS, skip the following content. Data updates in the RDS table are automatically synchronized to the knowledge base usually within seconds. But slight delays may occur during peak request periods.

Update data table
A structured knowledge base can be associated to a single data table in Application Data. To insert new entries, import a document with the table header and new data. To update or delete existing entries, import a document with the table header and full, updated data. Each table can contain up to 10,000 rows, including the table header. Exceeding this limit will result in a failed import, so you may need to split the data in advance.
If you do not have a complete copy of data, you can first download the full data to your local device. Modify it and import again. Go to Application Data, select the Structured Data tab. Select the desired data table and click to download the full data of this table in xlsx format to your local device.
- Import Data
  1. Go to Application Data, select the Structured Data tab.
  2. Select the desired data table then click Import Data.
  3. Select Incremental Upload (add data based on existing data) or Upload and Overwrite (overwrite all data in the table with the new data).
  4. Click to select and upload the document.
    The document must have a table header that matches the header structure of the current data table. Otherwise, the import will fail.
    You can click Download Template to download a blank document with the table header. Then, insert data to the template and upload it directly.
  5. After successful upload, click Preview to view the imported data. Then, click Confirm.
- Manage chunks (Currently not supported)
Apply changes
Go to the Knowledge Base page, click View on the right side of the knowledge base that needs updating. Click the icon at the top left of the data table, then click Confirm to synchronize the latest data from the imported data table to the knowledge base.
If you update the data in the data table associated with the knowledge base on the Structured Data tab of Application Data in the future, repeat the above steps for synchronization. The console does not support automatic synchronization.
Reference knowledge base
Your changes take effect automatically in real time to all applications associated with the knowledge base.

API

Important

RAM users must first obtain data permissions

Alibaba Cloud accounts do not need authorization and can skip this note. If you are not familiar with concepts such as Alibaba Cloud account and RAM user, read Permissions first.

Before your RAM user calls the following APIs (SubmitIndexAddDocumentsJob and DeleteIndexDocument), make sure that the user has the AliyunBailianDataFullAccess system policy and belongs to at least one Model Studio workspace. For more information, see Grant data permissions to a RAM user.

Add documents to the knowledge base
You cannot use APIs to manage structured knowledge bases. Use the console instead.
To add new documents to an existing knowledge base, use the SubmitIndexAddDocumentsJob interface.
Before you call this operation, make sure that your knowledge base is created and is not deleted. That is, the primary key ID of the knowledge base IndexId is valid.
Call AddFile first to upload documents and obtain the FileId with ListIndexDocuments.
- Task execution may take some time. Call GetIndexJobStatus to check the status of the task. When the task is done, the Data.Status parameter in the return is COMPLETED.
- The document list (Documents) in the return contains all the documents you added this time, and you can check whether each document was imported.
- You can also call ListIndexDocuments to retrieve the list of documents and their import status for a knowledge base.
Delete documents from the knowledge base
To delete specific documents from the knowledge base, invoke the DeleteIndexDocument interface.
Only documents with a status of INSERT_ERROR or FINISH can be deleted.
You must specify the document ID FileId of the document to be deleted.

You may encounter the following questions when using the above APIs.

Question	Answer
Do I have to call the above APIs in a specific order?	Whether you need to call the APIs in order depends on your business needs and update strategy. Below is an example of a possible API call order when updating the knowledge base: First, call AddFile to import documents to Application Data. Then, call SubmitIndexAddDocumentsJob to create a document addition task, synchronizing the new version of the document to the knowledge base. Next, call GetIndexJobStatus to poll and confirm that the document addition task has completed. Finally, call DeleteIndexDocument to delete the old version of the document.
Is it necessary to call DeleteIndexDocument and delete the old version of the document?	Whether you need to call this interface to delete old documents depends on your specific update strategy. If you need to ensure that the documents in the knowledge base are always up-to-date and old knowledge is no longer applicable, then you should delete old versions to avoid old knowledge being incorrectly retrieved.
Does Model Studio support recording and viewing API logs for the above operations?	The Model Studio knowledge base feature does not currently integrate API log recording and query functionality. Therefore, you need to integrate logging mechanisms and verification logic in your own program to ensure the integrity of knowledge.

Delete knowledge base

If you no longer need a knowledge base, you can delete it. This operation will not delete the data already imported in Step 1.

Console

Before deleting a knowledge base, dissociate all it from all applications in the console. Otherwise, deletion will fail.
1. Go to My Applications, find the application, and click Manage.
2. Deselect the knowledge base.
Go to the Knowledge Base page, click Delete to the right of the knowledge base.

API

Important

RAM users must first obtain data permissions

Alibaba Cloud accounts do not need authorization and can skip this note. If you are not familiar with concepts such as Alibaba Cloud account and RAM user, read Permissions first.

Before your RAM user calls the following API (DeleteIndex), make sure that the user has the AliyunBailianDataFullAccess system policy and belongs to at least one Model Studio workspace. For more information, see Grant data permissions to a RAM user.

We recommend that you use the latest version of GenAI Service Platform to call DeleteIndex. You can debug the APIs online and generate code samples in multiple languages, such as Java and Node.js.

Before deleting a knowledge base, dissociate all it from all applications in the console. Otherwise, deletion will fail. For instructions, see the Console tab.

Billing details

The knowledge base feature is free. However, when you call applications associated with knowledge bases, fees may occur.

Step	Billing
Import data	Free.
Create knowledge base	Free.
Test knowledge base	Free.
Use knowledge base	When calling applications, the chunks recalled from the knowledge bases increases the input token count. This may result in an increase of model inference fees. Note: If you are only retrieving from knowledge bases by calling Retrieve, no fees will be incurred.
Manage and maintain knowledge bases	Free.

API reference

For a complete list of knowledge base APIs and parameters, see API Catalog (Knowledge index). We recommend that you use the latest version of GenAI Service Platform. You can debug the APIs online and generate code samples in multiple languages, such as Java and Node.js.

Important

RAM users must first obtain data permissions

Alibaba Cloud accounts do not need authorization and can skip this note. If you are not familiar with concepts such as Alibaba Cloud account and RAM user, read Permissions first.

Before your RAM user calls APIs to import data, create knowledge base, or retrieve knowledge base, make sure that the user has the AliyunBailianDataFullAccess system policy and belongs to at least one Model Studio workspace. For more information, see Grant data permissions to a RAM user.

Related operations:

Use API to import data: Import your original document from local storage or OSS to Model Studio as the knowledge source of knowledge bases.
The API does not support structured data. Use the console instead.
Use API to create knowledge base.
The API does not support structured knowledge base. Use the console instead.
Use API to retrieve from knowledge base, use one of the following methods:
- When calling an application, pass the knowledge base ID in rag_options.
- Without using applications, call Retrieve directly.
Use API to update knowledge base.
To implement automatic update of structured knowledge base, associate it with RDS data table.

FAQ

How to configure whitelist for an RDS instance?

Public cloud

To set up a whitelist for an RDS instance, follow these steps:

Go to the RDS Console, choose Instances in the left-side navigation pane, then click the RDS instance containing the data table.
Click Database Connection in the left-side navigation pane, and click Configure Whitelist next to Public Endpoint. If your RDS instance has not enabled public access, click Apply for Public Endpoint and follow the guidance to enable it.
Click Create Whitelist and add all the following public IP addresses of DTS and Model Studio knowledge base to the whitelist group. Otherwise, data synchronization failures may occur:
- All of DTS public IP addresses in the Singapore region, see: DTS IP Address segments.
- The public IP address of Model Studio knowledge base: 47.245.110.18.
Click OK, and the whitelist takes effect.

Does Model Studio support automatic update for knowledge bases?

Yes, and the implementation method depends on the data format.

Unstructured data

Implement automatic update by integrating OSS, Function Compute (FC), and the knowledge index API in the following steps:

Create a bucket: Go to the OSS console and create a bucket to store your documents.
Create a knowledge base: Create a unstructured knowledge base in Model Studio.

Create a custom function: On FC, set up a function to handle document change events, such as additions and deletions. For more information Create a web function. This function calls Model Studio APIs to update knowledge bases from OSS. When using the APIs, you may want to ask the following questions:

Question	Answer
Do I have to call the above APIs in a specific order?	Whether you need to call the APIs in order depends on your business needs and update strategy. Below is an example of a possible API call order when updating the knowledge base: First, call AddFile to import documents to Application Data. Then, call SubmitIndexAddDocumentsJob to create a document addition task, synchronizing the new version of the document to the knowledge base. Next, call GetIndexJobStatus to poll and confirm that the document addition task has completed. Finally, call DeleteIndexDocument to delete the old version of the document.
Is it necessary to call DeleteIndexDocument and delete the old version of the document?	Whether you need to call this interface to delete old documents depends on your specific update strategy. If you need to ensure that the documents in the knowledge base are always up-to-date and old knowledge is no longer applicable, then you should delete old versions to avoid old knowledge being incorrectly retrieved.
Does Model Studio support recording and viewing API logs for the above operations?	The Model Studio knowledge base feature does not currently integrate API log recording and query functionality. Therefore, you need to integrate logging mechanisms and verification logic in your own program to ensure the integrity of knowledge.

Create an OSS trigger: Associate the custom function from the previous step with an OSS Trigger on FC. When a document change event occurs, such as a new upload to OSS, the trigger prompts FC to execute the relevant function. For more information, see Triggers.

Structured data

Associate the Data Source of your knowledge base with ApsaraDB RDS to enable automatic updates. For more information, see Data Source in Step 2: Create a knowledge base.

When using a RAM user (or RAM role), I encounter an sfm:Retrieve error during hit testing.

Go to the RAM console with the Alibaba Cloud account and grant the AliyunBailianDataFullAccess system policy for your RAM user (or RAM role). For instructions, see Grant data permissions to a RAM user.

Is my knowledge base private? Can other companies or users access it?

Your knowledge base is exclusive to your current workspace. It is not available to the public.

Will Model Studio use the knowledge base under my account to answer questions from other users?

Model Studio will not use the knowledge base under your account to answer questions from other users.

If I can only upload unstructured documents, how can I organize document content to improve retrieval performance?

We recommend that you use file formats such as txt or md, which are more easily parsed. Organize the document content with distinct titles and paragraphs, and use lists and numbering to structure information, emphasizing keywords and concepts.

Can I download the knowledge bases to my local devices?

Downloading knowledge bases is not currently supported.

Can I delete documents or data tables in Application Data without affecting the knowledge bases?

Unstructured data can be deleted, because the copies in Application Data and the knowledge base are independent. However, you cannot delete structured data. Otherwise, the structured knowledge base cannot function properly.

How do I check text chunk quality?

Before integrating the knowledge base with your application, we recommend that you manually inspect the chunks for quality. During your evaluation, pay attention to the following common issues:

Excessively short chunks	Excessively long chunks	Clear semantic truncation
Chunks that are too short may result in a loss of meaning, preventing accurate matches.	Chunks that are too long can introduce irrelevant information, diminishing the precision of matches.	Improper chunking can lead to incomplete information retrieval.

How does Model Studio handle DDL operations on the RDS source table, such as DROP TABLE, RENAME TABLE, TRUNCATE TABLE, ADD COLUMN, and DROP COLUMN?

DROP TABLE: Deleting the source table does not automatically remove data from the knowledge base. To delete the knowledge base, you must do so manually, see Delete knowledge base. If a new table with the same name is created, the new table resumes automatic synchronization with the knowledge base, but only through incremental synchronization, capturing new data changes.
RENAME TABLE, ADD COLUMN, DROP COLUMN: Modifying the name of the source table causes the synchronization to stop. If the original table name is restored, synchronization will resume, again only through incremental synchronization. During the interim, no data changes will be synchronized. Note that field changes in the source table will not update the knowledge base. As a result, newly added fields are not retrievable in the knowledge base. To avoid these issues, consider creating a new knowledge base when altering the source table.
TRUNCATE TABLE: Truncating the source table does not delete corresponding data in the knowledge base.

What should I do if the NotSupportFormat/BlankDocError/Document too large error occurs?

Error	Description
NotSupportFormat	The format of your document is not supported. Use a supported format and try again.
BlankDocError	The document may be empty. Check whether it is complete and correct. Then, try again.
Document too large	The document si too large or the number of rows exceeds the limit. Split the document or table and try again.

RAG optimization

If you encounter issues such as incomplete knowledge recall or inaccurate content while using the RAG feature of Model Studio, see Optimize RAG performance.