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

A knowledge base supplements an LLM with private data and up-to-date information. Using retrieval-augmented generation (RAG), the LLM improves answer accuracy by first retrieving relevant content from the knowledge base before generating a response.

Important

The knowledge base feature is available only in the China (Beijing) region, not in other regions such as Singapore and Germany (Frankfurt).

Application without a dedicated knowledge base

Without a dedicated knowledge base, an LLM cannot answer domain-specific questions accurately.

Application with a dedicated knowledge base

With a dedicated knowledge base, an LLM can answer domain-specific questions accurately.

Supported models

The following models can be used with a knowledge base. Configure Qwen to use a knowledge base

Pre-built models

Custom models

Qwen-QwQ/Long/Max/Plus/Turbo/Coder/Deep-Research
QwenVL-Max/Plus/Flash/OCR
Qwen open-source version (such as Qwen3, Qwen2.5, and Qwen2)
Third-party text generation models (such as DeepSeek-R1, DeepSeek-V3.1, abab6.5s, Llama3.1, and Yi-Large)

These models are fine-tuned from the following base models.

Qwen-Plus/Turbo
QwenVL-Max/Plus
Qwen open-source version (such as Qwen3, Qwen2.5, and Qwen2)

For an up-to-date list of available models, see the Application Management page when creating an application.

How it works

A knowledge base enables semantic search on your private data or files. It finds semantically similar content, even with few or no keyword matches.

Learn more about retrieval-augmented generation in the Alibaba Cloud large language model ACA Course.

Quick start

This quickstart shows how to build a no-code LLM Q&A application to answer domain-specific questions, using "Alibaba Cloud Model Studio phones" as an example.

1. Build a knowledge base

Go to Knowledge Base. select Standard Edition or Ultimate Edition and click Create Knowledge Base.
Enter a Name and Description, leave the other settings at their default values, and click Next Step.
Select the Default Category and upload the Alibaba Cloud Model Studio Phone Series Product Introduction.docx file. Click Next Step, and then click Complete.

2. Integrate with business applications

After you create a knowledge base, you can associate it with an Alibaba Cloud Model Studio application or an external application within the same workspace to process retrieval requests.

Agent application

Go to the App Center page, find your agent application, click Configure on its card, and select a model for the application.

Click the + icon next to Document Knowledge Base to add the knowledge base that you just created. You can keep the default values for the similarity threshold and weight.

(Optional) Similarity threshold: Filter retrieval results

A knowledge base uses semantic search to find conceptually relevant text in your private data or files, even without matching keywords.

For example, a user submits the following query: Which Alibaba Cloud phone is best for photography?

The actual answer (for example, "Qwen Vivid 7...") does not contain any keywords from the query.

In the table below, keyword similarity is calculated using the Jaccard index, and semantic similarity is the cosine similarity calculated by the text-embedding-v4 model.

Retrieved text	Keyword similarity	Semantic similarity
Qwen Vivid 7: A new experience in smart photography	0	0.43
Alibaba Cloud Model Studio Ace Ultra: The choice for gamers	0.17	0.32
Alibaba Cloud Model Studio Flex Fold+: A new era of foldable screens	0.25	0.24

Similarity threshold: Only text with a semantic similarity score higher than this value is retrieved. Setting this threshold too high can cause relevant text to be filtered out.

(Optional) Weight: Influence retrieval order from multiple knowledge bases

When an agent application is associated with multiple knowledge bases, you can assign a weight to each based on the importance of the information source. During multi-source retrieval, if chunks from different knowledge bases have the same similarity score, the system prioritizes chunks from the knowledge base with the higher weight.

Key limitation: The weight only takes effect between knowledge bases of the same type. For example, the weight of a document search knowledge base does not affect the retrieval order of a data query knowledge base, and vice versa.
How it works: The system first calculates the relevance of the user query to the content in each knowledge base to identify the most relevant chunks. It then multiplies the similarity score of each chunk by the weight of its corresponding knowledge base. After reranking based on these weighted scores, the results are provided to the LLM as context, ensuring that chunks with higher weighted scores are prioritized in the final answer.

In the input box on the right, enter a question. The LLM then uses the knowledge base to generate an answer.
For example: "Help me choose the Alibaba Cloud Model Studio phone with the best camera for under 3,000 CNY."

Workflow application

Go to the App Center page, find your workflow application, and click Configure on its card. Drag a Knowledge Base node onto the canvas and connect it after the Start node.
Configure the Knowledge Base node:
1. Input: From the Value drop-down list to the right of the content variable, select Built-in Variable. The drop-down list has a tree structure; you may need to expand the "Built-in Variable" group to select the query variable.
2. Select Knowledge Base: You can select a knowledge base for the node in one of two ways.
  - Select a fixed knowledge base: Select the knowledge base that you created in the previous step from the drop-down menu. Use this method when the same knowledge base is required for every call.
  - Dynamic Selection: Configure the CodeList variable to dynamically specify a knowledge base based on the output of an upstream node. This is suitable for scenarios where you need to retrieve different knowledge bases based on different inputs.
3. Set TopK (Optional): This setting determines the number of chunks returned to downstream nodes, which are typically LLM nodes.
  Increasing this value usually improves the accuracy of the LLM's answers but also increases the LLM's input token consumption.
Drag an LLM node onto the canvas and connect it after the Knowledge Base node and before the End node.
Configure the LLM node:
1. From the Model configuration list, select a model for the node.
2. In the Prompt, enter a prompt that instructs the LLM to use the knowledge base. Enter "/" to insert the result variable (which represents the results returned from the knowledge base retrieval).
Configure the End node: Enter / and select to output the result from the LLM.
Click Test in the upper-right corner of the page. In the input box on the right, enter a question. The LLM will use the knowledge base to generate an answer.
For example: "Help me choose the Alibaba Cloud Model Studio phone with the best camera for under 3,000 CNY."

External application

In addition to building applications within Alibaba Cloud Model Studio, you can use the Model Studio SDK to retrieve data from a knowledge base for external AI applications.

For detailed integration steps, see the Knowledge Base API Guide.

3. Optimize RAG performance (Optional)

If you receive incomplete or inaccurate results from the Q&A process, see RAG performance optimization.

How-to

On the knowledge base page, you can view and manage all knowledge bases in the current workspace.

Knowledge base ID: The ID of each knowledge base, used for API calls.

Create a knowledge base

After you click Create Knowledge Base, first select an edition (Standard Edition: CNY 0.03/hour; Enterprise Edition: CNY 0.2/hour), and then create the knowledge base in three steps: provide basic information and select a knowledge base type, configure a data source, and set index parameters.

On the knowledge base page, click Create Knowledge Base.

Basic information

Select a Knowledge Base Type based on your use case. A single knowledge base supports only one type. If you select the document search type, you must also select a use case: Basic document Q&A, Rich-text Reply, visual understanding (rich-text documents), or Rapid Q&A.

Basic document Q&A: Ideal for semantic search on plain-text documents.
Rich-text Reply: Ideal for use cases that require responses containing both text and images.
Visual understanding (rich-text documents): Uses a multimodal embedding model to visually understand and index rich-text documents, such as PDFs and images, while preserving the original layout. This is suitable for documents with complex layouts, charts, or formulas. It supports three query modes: text, image, and a combination of text and image.
Rapid Q&A: Optimized for retrieval speed, this use case is ideal for highly structured or simple document types, such as FAQs and product specification sheets, providing a fast, low-latency Q&A experience. The index configuration is the same as for Basic document Q&A, but the backend retrieval strategy is optimized for low-latency scenarios. It supports only text queries and does not accept image input.

If you select visual understanding, the embedding model is automatically set to qwen3-vl-embedding and cannot be changed.

The knowledge base type cannot be changed after the knowledge base is created.

Document search

Use cases:
- Ideal for retrieving information from unstructured data, such as internal corporate documents and product manuals. Unstructured data is information that is not organized in a predefined data model or schema and can include text, tables, and images.
- If your files contain images that you want the application to include in its responses, select document search.
Select data connector: Select a data connector. If you have not created one, see Data connectors.

Data source: You can upload local files or import them from Object Storage Service (OSS).

Document search creation

Select data: Specify a data source (files or content) for the knowledge base. The system imports the source content into the knowledge base for retrieval. You can use local upload or cloud import (by selecting an existing category or file).
- Local upload: Upload files directly from your computer. Expand the collapsible panel below to learn how to select a parsing method.
  Parsing methods
  Configure the parsing strategy based on your needs. If you are unsure which option to choose, we recommend using the default settings. For details about Intelligent Document Parsing, LLM Parsing, and Digital Parsing, see Document understanding.
  Digital Parsing: Does not parse illustrations or charts in files. This is the fastest parsing method. A 10- to 20-page plain-text document is typically parsed within a few seconds to 1 minute.
  Intelligent Document Parsing: Recognizes and extracts text from illustrations in your files to generate text summaries. These summaries, along with other non-image content, are then chunked and vectorized for retrieval. This method is relatively fast. A 10- to 20-page document with illustrations typically takes 1 to 5 minutes to parse.
  LLM Parsing: Enables applications that use the Qwen-VL model to answer questions about the content of illustrations and charts in your files. To enable the recognition and understanding of this content, select LLM Parsing. Because this method calls an LLM for deep understanding, a 10- to 20-page document with charts typically takes 2 to 10 minutes to parse.
  Qwen-VL parsing: Designed specifically for image files. You can specify a Qwen-VL model and provide a prompt to guide the recognition and extraction of the image layout and elements. A single image is typically parsed within a few seconds to 1 minute.
  Audio and video parsing: Performs speech recognition, video frame extraction (for videos only), and scene analysis (for videos only) on the file. All audio and visual information is structurally aligned on a timeline. The parsing time is proportional to the file duration. A 30-minute audio file takes about 5 to 15 minutes, while a 1-hour video (including scene analysis) takes about 15 to 60 minutes.
  Speech recognition: Converts speech to text using Speech-to-Text. Music and natural ambient sounds, such as horns, bells, or thunder, are not supported.
  Video frame extraction: Extracts representative frames from a video and generates corresponding text descriptions.
  Scene analysis (must be manually enabled): Analyzes video content to locate specific events, marks them with timestamps, and generates corresponding text descriptions. Enabling this option significantly increases parsing time.
- Cloud import: Import existing files from an Alibaba Cloud Model Studio data connector or Object Storage Service (OSS).

Index configuration: Defines how imported data is processed and stored, which directly affects retrieval performance.

Among the following settings, only vector storage with AnalyticDB for PostgreSQL (ADB-PG) may incur fees. All other settings are free.

Metadata extraction

Metadata consists of additional attributes for unstructured data, which are integrated into chunks as key-value pairs.

Purpose: Metadata provides important context for chunks and can significantly improve the accuracy of knowledge base retrieval. For example, consider a knowledge base that contains thousands of product introduction files where the file name is the product name. When a user searches for "functional overview of Product A," if the body of every file contains "functional overview" but none mention "Product A," the knowledge base might retrieve many irrelevant chunks. However, if you add the product name as metadata to all chunks, the knowledge base can accurately filter for chunks that are related to "Product A" and also contain "functional overview." This improves retrieval accuracy and reduces the LLM's input token consumption.
Usage: When you call an application using an API, you can specify metadata in the metadata_filter request parameter. When the application retrieves information from the knowledge base, it first filters for relevant files based on the specified metadata.
Note: You cannot configure metadata extraction after a knowledge base is created.

Metadata configuration

In the example diagram below, the metadata for all chunks from this file contains five custom attributes: date (all years that appear in the file), reference (all references that appear in the file), filename (the name of the file), keywords (keywords that appear in the file), and author (the file's author information).

Enable Metadata extraction, and then click Settings to attach uniform or personalized metadata to all files in the knowledge base. During chunking, the metadata for each file is integrated into its respective chunks. The following figure shows the metadata template used in the preceding example:

New metadata template

Value extraction methods

Constant: Attaches a fixed attribute to all files in the knowledge base.
As shown in the preceding example, if all files in the knowledge base have the same author, you can set a constant for a field named author.
Variable: Attaches a variable attribute to each file in the knowledge base. The currently supported attributes are file_name and cat_name. If you select file_name, Alibaba Cloud Model Studio attaches the name of the file to its metadata, as shown in the preceding example. If you select cat_name, Alibaba Cloud Model Studio attaches the name of the category that contains the file to the file's metadata.
LLM: The system matches the file content against the configured Entity Description rule, extracts the relevant information, and attaches it as a metadata attribute.
As shown in the metadata template in the preceding example, to extract all years that appear in each file as file attributes, you can configure an LLM field named date. The entity description is configured as follows:
RegEx: The system matches the text content of each file in the knowledge base against the specified regular expression. Content that matches the expression is extracted and added as an attribute to the file's metadata.
As shown in the meta information template in the example above, if you need to extract all references that appear in each file (assuming that a reference is any text that starts with '《' and ends with '》'), you can configure a regular expression field named reference. The regular expression is configured as follows:
Keyword search: The system searches each file for preset keywords and adds the matched keywords as attributes to the file's metadata.
For example, in the metadata template in the preceding example, the preset keywords are:
Because the file contains only the keywords "financing," "industry," "green," and "capital," the system extracts only these four keywords as the value for the file's keywords attribute.

Used for Retrieval: If enabled, the metadata field and value are used for knowledge base retrieval along with the chunk content. If disabled, only the chunk content is used for retrieval.

Used for Model Reply: If enabled, the metadata field and value are provided to the LLM as input for response generation along with the chunk content. If disabled, only the chunk content is provided to the LLM for response generation.

Excel header assembly

When enabled, the knowledge base treats the first row of all XLSX and XLS files as the header and automatically appends it to each chunk (data row). This prevents the LLM from misinterpreting the header as a regular data row.

You do not need to enable this setting if the knowledge base contains files in other formats, such as PDF.

Chunking method

Select smart chunking (recommended) or a custom chunking method. If Intelligent Splitting fails to correctly process the content, you can adjust some of its strategies.

Purpose: A knowledge base splits files into chunks and converts them into vectors using an embedding model. The chunks and vectors are then stored as key-value pairs in a vector database. After the knowledge base is created, you can view or edit the specific content (text and images) of each chunk.

Note: After a knowledge base is created, you cannot change the document chunking settings. An inappropriate chunking strategy may reduce retrieval and recall performance.

Intelligent Splitting: This is the default chunking strategy and provides the best retrieval results for most files based on internal evaluations.
How it works: When you use Intelligent Splitting, the knowledge base first splits a file into paragraphs based on built-in sentence delimiters, and then creates chunks from these paragraphs. During this process, the knowledge base maintains the semantic integrity of each part and avoids unnecessary splits. However, chunks that exceed the maximum segment length are truncated.
Split by Length: This method is suitable for scenarios with strict token limits, such as when you use models with a small context window.
Segment overlap length: The number of overlapping characters between adjacent chunks. We recommend that you set this value to 10% to 25% of the maximum segment length. This preserves the semantic relationship between chunks and improves multi-chunk retrieval quality. Note that this parameter must be smaller than the maximum segment length. Otherwise, chunking errors may occur.
Example
Sample text:
```
Alibaba Cloud Model Studio knowledge base provides multiple file processing methods. You can choose the most suitable method as needed.
```
Possible chunking result (maximum segment length = 20):
- Chunk 1: "Alibaba Cloud Model Studio knowledge base provides multiple f"
- Chunk 2: "ile processing methods. You can choose the most suitable method as needed."

Split by Page: This method is suitable for files where each page covers an independent topic. It ensures that content from different pages is not mixed into the same chunk. Chunks that exceed the maximum segment length are truncated.

Example

Sample Markdown text:

Page 1

Page 2

# Create a knowledge base
The Alibaba Cloud Model Studio knowledge base provides multiple document processing methods. You can choose the most suitable method as needed.

## Smart chunking
- Uses the system's built-in chunking strategy.
- Evaluations show it provides the best retrieval results for most documents.

## Custom chunking
- If smart chunking does not work as expected, you can adjust some of its strategies.

Possible chunking result:

Chunk 1: "Create a knowledge base ... provides the best retrieval results for most documents."
Chunk 2: "Custom chunking ... adjust some of its strategies."

Chunk by heading: This method is suitable for files where independent topics are separated by headings. It ensures that content under different headings of the same level is not mixed into the same chunk. Chunks that exceed the maximum segment length are truncated.

Example

Sample Markdown text:

Page 1

Page 2

# Create a knowledge base
The Alibaba Cloud Model Studio knowledge base provides multiple document processing methods. You can choose the most suitable method as needed.

## Smart chunking
- Uses the system's built-in chunking strategy.
- Evaluations show it provides the best retrieval results for most documents.

## Custom chunking
- If smart chunking does not work as expected, you can adjust some of its strategies.

Possible chunking result (chunking by level-1 headings):

Chunk 1: "Create a knowledge base ... adjust some of its strategies.

Possible chunking result (chunking by level-2 headings):

Chunk 1: "Create a knowledge base ... choose the most suitable method as needed."
Chunk 2: "Smart chunking ... provides the best retrieval results for most documents."
Chunk 3: "Custom chunking ... adjust some of its strategies."

Split by Regular Expression: The system splits the text in the knowledge base based on the specified regular expression. For example, to maintain sentence integrity, you can use the regular expression (?<=\.) to split the file by periods. If the number of characters in a text chunk exceeds the Maximum segment length, the chunk is forcibly truncated.
Example
Sample text:
```
Alibaba Cloud Model Studio knowledge base provides multiple file processing methods. You can choose the most suitable method as needed.
```
Possible splitting results (Regular expression: (?<=。)):
- Chunk 1: "Alibaba Cloud Model Studio knowledge base provides multiple file processing methods."
- Chunk 2: "You can choose the most suitable method as needed."
By Symbol: Chunks the file based on selected punctuation marks. Chunks that exceed the maximum segment length are truncated.

Multi-turn conversation rewriting

When enabled, this feature uses a dedicated model to rewrite the user's query by incorporating conversation history. This process creates a complete, standalone query for knowledge base retrieval.

graph TD; A[Query] --> C{Rewrite Model}; B[History] --> C; C --> D[Rewritten Query]; D --> E[KB Retrieval]

Embedding model

An embedding model converts the original input prompt and knowledge text into numerical vectors so the system can calculate semantic similarity. The default Official Vector v4 (text-embedding-v4) model is a comprehensive upgrade over the Official Vector v3 (text-embedding-v3) model, offering improvements in language support, code snippet vectorization performance, and customizable vector dimensions. It is suitable for most scenarios. For more information, see Text and multimodal vectorization.

The vector dimensions for each embedding model are fixed and cannot be modified:

text-embedding-v4: 512 dimensions
text-embedding-v3: 512 dimensions
qwen3-vl-embedding: Automatically enabled when the visual understanding use case is selected. It supports generating vectors for images and rich-text documents after visual understanding.

graph TD; subgraph Input; A[Prompt] --> C{Embedding Model} --> D[Prompt Vector]; end; subgraph Knowledge Base; B[Knowledge] --> C --> E[Knowledge Vector]; end; D --> F((Similarity)); E --> F

Reranking model

A reranking model is external to the knowledge base. It reranks the candidate chunks from the initial vector retrieval and returns the top K chunks with the highest similarity scores. The recommended official reranker, qwen3-rerank (hybrid), considers both semantic relevance and text-matching features (such as BM25 scores) to better handle queries that require precise keyword hits. If you only need semantic ranking, select qwen3-rerank.

graph TD; A[Vector Retrieval] --> B{Candidates}; B --> C[Reranker]; C --> D[Top K Results]

Reranking model mode

When you create a knowledge base, you can select one of the following three modes for the reranking model:

Q&A mode (default): Scores based on the "Q&A relevance" between the query and the candidate chunks. This mode is suitable for scenarios where users ask a complete question and expect to find the answer within a chunk.
Similarity mode: Scores based on the "semantic similarity" between the query and the candidate chunks. This mode is suitable for scenarios where the query and the chunks have a similar style of expression.
Custom advanced mode: Allows you to enter a natural language instruction of up to 200 characters to influence the reranking process. This mode is suitable for scenarios with special ranking requirements.

Warning

You can select a reranking model mode only when you create a knowledge base. You cannot change it after creation. Before you configure this setting, note the following limitations:

Knowledge base type limitation: This feature is applicable only to document search, Data Query, and audio/video search knowledge bases. It is not supported for Image Q&A knowledge bases.
Use case limitation: This feature is supported only for the Basic document Q&A and Rich-text Reply use cases. It is not supported for the visual understanding (rich-text documents) and Rapid Q&A use cases.

Similarity threshold

This threshold sets the minimum similarity score required for a chunk to be recalled from the reranking model's results.

Note

This is the default similarity threshold for the knowledge base. When you associate the knowledge base with a specific Alibaba Cloud Model Studio application, you can set a separate threshold for that application, which overrides the knowledge base's default threshold.

Lowering this threshold recalls more chunks but may include less relevant content. Conversely, raising it recalls fewer chunks and may cause relevant ones to be discarded if set too high.

You can use hit testing to fine-tune the similarity threshold to balance recall and precision.

graph TD; A[Reranked Results] --> B{Filter by Threshold}; B --> |Keep| C[Final Results]; B --> |Discard| D[Discarded]

Maximum recall count

The system retrieves chunks related to the input from all associated knowledge bases, reranks them using a reranking model, and selects the top K most relevant chunks to add to the LLM input as context. This K value is the maximum recall count (up to 20), and it determines the number of chunks the reranking model provides to the LLM for context.

Increasing this value can improve the LLM's response accuracy but also increases the LLM's input token consumption.

Vector storage

Select a vector database to store text vectors. The Built-in vector database is sufficient for basic knowledge base operations. For advanced capabilities such as database management, auditing, or monitoring, we recommend AnalyticDB for PostgreSQL (ADB-PG).

When you purchase an AnalyticDB for PostgreSQL (ADB-PG) instance, you must enable Vector Engine Optimization. Otherwise, Alibaba Cloud Model Studio cannot use the instance.

Visual understanding creation

When you select the visual understanding (rich-text documents) use case, the knowledge base uses a multimodal embedding model to visually understand documents and preserve the original layout information, instead of using traditional chunking methods.

File format restrictions

In the file upload area of the Select data tab, hover over View format requirements to view the requirements.

Index configuration differences

The index configuration for the visual understanding use case differs from that for Basic document Q&A:

Embedding model: The qwen3-vl-embedding model is automatically selected and cannot be changed after creation.
Multi-turn conversation rewriting: Can be enabled or disabled.
Similarity threshold: The default is 0.20.
Final maximum recall count: The default is 5.
Chunking method: Visual understanding does not use traditional chunking methods such as smart chunking or custom chunking. Instead, it understands the entire document page based on visual indexing.

Editing restrictions

The embedding model (qwen3-vl-embedding) and vector storage type (built-in) cannot be changed after creation.
You can change the knowledge base edition only once per day.

Data query
- Use cases:
  - Ideal for building Q&A systems based on structured data (data organized according to a predefined table schema), such as assistants for querying FAQs, product data, or personnel information.
  - If your data consists of complete FAQ question-and-answer pairs, select Data Query. For example, if an Excel file contains two columns, Question and Answer, a Data Query knowledge base can use the Question column for retrieval and the Answer column as context for the LLM's response.
    This column-specific processing is unavailable in the document search knowledge base type.
  - You can import multiple Excel files, but their table schemas must be identical.
- Select data connector: Select a data connector. If you have not created one, see Data connectors.
- Data source integration: You can upload local XLS or XLSX files or import data from Alibaba Cloud RDS.
  Data query creation
  1. Select data: Specify a data source (files or content) for the knowledge base. The system imports the source content into the knowledge base for retrieval. You can use local upload, cloud import (select an existing data table from a data connector), or Import from RDS.
    Note
    The data source cannot be changed after you create the knowledge base. A single knowledge base supports only one data source.
    Local upload: Upload data tables in XLS or XLSX format from your computer. The first row must be the table header.
    Cloud import (select data table): Select an existing data table from an Alibaba Cloud Model Studio data connector.
    Import from RDS (connect to database): The data table is stored in Alibaba Cloud RDS. For instructions, see Integrate MySQL data into a knowledge base.
  2. Index configuration: Defines how imported data is processed and stored, which directly affects retrieval performance.
    Among the following settings, only vector storage with AnalyticDB for PostgreSQL (ADB-PG) may incur fees. All other settings are free.
    Retrieval and reply settings
    Used for Retrieval: If enabled, the knowledge base performs retrieval on this column.
    Used for Model Reply: If enabled, retrieval results from this column are provided to the LLM as context for response generation. For example, if you enable Used for Retrieval for the "Name," "Gender," "Position," and "Age" columns, but enable Used for Model Reply only for the "Name" and "Position" columns, the knowledge base retrieves from all four columns. However, only the content from the "Name" and "Position" columns of the retrieved data is provided to the LLM as context for its response.
    As shown in the following figure, because the "Age" column is not enabled for model responses, the LLM associated with this knowledge base cannot answer the question "What is Zhang San's age?".
    Multi-turn conversation rewriting
    When enabled, this feature uses a dedicated model to rewrite the user's query by incorporating conversation history. This process creates a complete, standalone query for knowledge base retrieval.
    graph TD; A[Query] --> C{Rewrite Model}; B[History] --> C; C --> D[Rewritten Query]; D --> E[KB Retrieval]
    Embedding model
    An embedding model converts the original input prompt and knowledge text into numerical vectors so the system can calculate semantic similarity. The default Official Vector v4 (text-embedding-v4) model is a comprehensive upgrade over the Official Vector v3 (text-embedding-v3) model, offering improvements in language support, code snippet vectorization performance, and customizable vector dimensions. It is suitable for most scenarios. For more information, see Text and multimodal vectorization.
    The vector dimensions for each embedding model are fixed and cannot be modified:
    text-embedding-v4: 512 dimensions
    text-embedding-v3: 512 dimensions
    qwen3-vl-embedding: Automatically enabled when the visual understanding use case is selected. It supports generating vectors for images and rich-text documents after visual understanding.
    graph TD; subgraph Input; A[Prompt] --> C{Embedding Model} --> D[Prompt Vector]; end; subgraph Knowledge Base; B[Knowledge] --> C --> E[Knowledge Vector]; end; D --> F((Similarity)); E --> F
    Reranking model
    A reranking model is external to the knowledge base. It reranks the candidate chunks from the initial vector retrieval and returns the top K chunks with the highest similarity scores. The recommended official reranker, qwen3-rerank (hybrid), considers both semantic relevance and text-matching features (such as BM25 scores) to better handle queries that require precise keyword hits. If you only need semantic ranking, select qwen3-rerank.
    graph TD; A[Vector Retrieval] --> B{Candidates}; B --> C[Reranker]; C --> D[Top K Results]
    Reranking model mode
    When you create a knowledge base, you can select one of the following three modes for the reranking model:
    Q&A mode (default): Scores based on the "Q&A relevance" between the query and the candidate chunks. This mode is suitable for scenarios where users ask a complete question and expect to find the answer within a chunk.
    Similarity mode: Scores based on the "semantic similarity" between the query and the candidate chunks. This mode is suitable for scenarios where the query and the chunks have a similar style of expression.
    Custom advanced mode: Allows you to enter a natural language instruction of up to 200 characters to influence the reranking process. This mode is suitable for scenarios with special ranking requirements.
    Warning
    You can select a reranking model mode only when you create a knowledge base. You cannot change it after creation. Before you configure this setting, note the following limitations:
    Knowledge base type limitation: This feature is applicable only to document search, Data Query, and audio/video search knowledge bases. It is not supported for Image Q&A knowledge bases.
    Use case limitation: This feature is supported only for the Basic document Q&A and Rich-text Reply use cases. It is not supported for the visual understanding (rich-text documents) and Rapid Q&A use cases.
    Similarity threshold
    This threshold sets the minimum similarity score required for a chunk to be recalled from the reranking model's results.
    Note
    This is the default similarity threshold for the knowledge base. When you associate the knowledge base with a specific Alibaba Cloud Model Studio application, you can set a separate threshold for that application, which overrides the knowledge base's default threshold.
    Lowering this threshold recalls more chunks but may include less relevant content. Conversely, raising it recalls fewer chunks and may cause relevant ones to be discarded if set too high.
    You can use hit testing to fine-tune the similarity threshold to balance recall and precision.
    graph TD; A[Reranked Results] --> B{Filter by Threshold}; B --> |Keep| C[Final Results]; B --> |Discard| D[Discarded]
    Maximum recall count
    The system retrieves chunks related to the input from all associated knowledge bases, reranks them using a reranking model, and selects the top K most relevant chunks to add to the LLM input as context. This K value is the maximum recall count (up to 20), and it determines the number of chunks the reranking model provides to the LLM for context.
    Increasing this value can improve the LLM's response accuracy but also increases the LLM's input token consumption.
    Vector storage
    Select a vector database to store text vectors. The Built-in vector database is sufficient for basic knowledge base operations. For advanced capabilities such as database management, auditing, or monitoring, we recommend AnalyticDB for PostgreSQL (ADB-PG).
    When you purchase an AnalyticDB for PostgreSQL (ADB-PG) instance, you must enable Vector Engine Optimization. Otherwise, Alibaba Cloud Model Studio cannot use the instance.
Image Q&A
- Use cases:
  - Ideal for building multimodal retrieval applications that support search-by-image and search-by-image-plus-text, such as product discovery assistants or visual Q&A assistants.
- Select data connector: Select a data connector. To create one, see Data connectors.
- Data source integration: You can upload local XLS or XLSX files or import data from Alibaba Cloud RDS.
  XLS and XLSX files or RDS data tables must contain publicly accessible image URLs to build image indexes. For details, see the creation instructions below.
  Image Q&A creation
  1. Select data: Specify a data source (files or content) to import into the knowledge base for retrieval. You can use local upload, cloud import (select an existing data table from a data connector), or Import from RDS.
    Note
    The data source cannot be changed after creation, and a single knowledge base supports only one data source.
    Local upload: Upload data tables in XLS or XLSX format directly from your computer.
    Note
    Field requirement: The data table must contain at least one field of the type image_url to generate the image index.
    Build process: The knowledge base accesses the image URL in the image_url field, extracts visual features, and converts them into vectors for storage.
    Retrieval process: The knowledge base compares the vector generated from the user's uploaded image with the stored image vectors and returns the most relevant records.
    Cloud import (select a data table): Select an existing data table from your application data in Alibaba Cloud Model Studio.
    Import from RDS (connect to database): The data table is stored in Alibaba Cloud RDS. For instructions, see Integrate MySQL data into a knowledge base.
  2. Index configuration: Defines how imported data is processed and stored, which directly affects retrieval performance.
    Among the following settings, only vector storage with AnalyticDB for PostgreSQL (ADB-PG) may incur fees. All other settings are free.
    Retrieval and reply settings
    Used for Retrieval: If enabled, the knowledge base performs retrieval on this column.
    Used for Model Reply: If enabled, retrieval results from this column are provided to the LLM as context for response generation. For example, if you enable Used for Retrieval for the "Name," "Gender," "Position," and "Age" columns, but enable Used for Model Reply only for the "Name" and "Position" columns, the knowledge base retrieves from all four columns. However, only the content from the "Name" and "Position" columns of the retrieved data is provided to the LLM as context for its response.
    As shown in the following figure, because the "Age" column is not enabled for model responses, the LLM associated with this knowledge base cannot answer the question "What is Zhang San's age?".
    Multi-turn conversation rewriting
    When enabled, this feature uses a dedicated model to rewrite the user's query by incorporating conversation history. This process creates a complete, standalone query for knowledge base retrieval.
    graph TD; A[Query] --> C{Rewrite Model}; B[History] --> C; C --> D[Rewritten Query]; D --> E[KB Retrieval]
    Embedding model
    An embedding model converts original input prompts, knowledge text, and images into numerical vectors to enable similarity comparisons. For more information, see Text and multimodal vectorization.
    qwen2.5-vl-embedding: Represents single-modal or mixed-modal inputs as a unified vector, suitable for cross-modal retrieval and image search. For example, if you input an image of a shirt with the text "find a similar style that looks younger," the model can fuse the image and text instructions into a single vector for understanding.
    multimodal-embedding-v1: Generates separate vectors for each input part (image and text).
    qwen3-vl-embedding: An upgraded version of qwen2.5-vl-embedding that further improves image-text fusion understanding and cross-modal retrieval accuracy.
    Reranking model
    A reranking model is external to the knowledge base. It reranks the candidate chunks from the initial vector retrieval and returns the top K chunks with the highest similarity scores. The recommended official reranker, qwen3-rerank (hybrid), considers both semantic relevance and text-matching features (such as BM25 scores) to better handle queries that require precise keyword hits. If you only need semantic ranking, select qwen3-rerank.
    graph TD; A[Vector Retrieval] --> B{Candidates}; B --> C[Reranker]; C --> D[Top K Results]
    Reranking model mode
    When you create a knowledge base, you can select one of the following three modes for the reranking model:
    Q&A mode (default): Scores based on the "Q&A relevance" between the query and the candidate chunks. This mode is suitable for scenarios where users ask a complete question and expect to find the answer within a chunk.
    Similarity mode: Scores based on the "semantic similarity" between the query and the candidate chunks. This mode is suitable for scenarios where the query and the chunks have a similar style of expression.
    Custom advanced mode: Allows you to enter a natural language instruction of up to 200 characters to influence the reranking process. This mode is suitable for scenarios with special ranking requirements.
    Warning
    You can select a reranking model mode only when you create a knowledge base. You cannot change it after creation. Before you configure this setting, note the following limitations:
    Knowledge base type limitation: This feature is applicable only to document search, Data Query, and audio/video search knowledge bases. It is not supported for Image Q&A knowledge bases.
    Use case limitation: This feature is supported only for the Basic document Q&A and Rich-text Reply use cases. It is not supported for the visual understanding (rich-text documents) and Rapid Q&A use cases.
    Similarity threshold
    This threshold sets the minimum similarity score required for a chunk to be recalled from the reranking model's results.
    Note
    This is the default similarity threshold for the knowledge base. When you associate the knowledge base with a specific Alibaba Cloud Model Studio application, you can set a separate threshold for that application, which overrides the knowledge base's default threshold.
    Lowering this threshold recalls more chunks but may include less relevant content. Conversely, raising it recalls fewer chunks and may cause relevant ones to be discarded if set too high.
    You can use hit testing to fine-tune the similarity threshold to balance recall and precision.
    graph TD; A[Reranked Results] --> B{Filter by Threshold}; B --> |Keep| C[Final Results]; B --> |Discard| D[Discarded]
    Maximum recall count
    The system retrieves chunks related to the input from all associated knowledge bases, reranks them using a reranking model, and selects the top K most relevant chunks to add to the LLM input as context. This K value is the maximum recall count (up to 20), and it determines the number of chunks the reranking model provides to the LLM for context.
    Increasing this value can improve the LLM's response accuracy but also increases the LLM's input token consumption.
    Vector storage
    Select a vector database to store text vectors. The Built-in vector database is sufficient for basic knowledge base operations. For advanced capabilities such as database management, auditing, or monitoring, we recommend AnalyticDB for PostgreSQL (ADB-PG).
    When you purchase an AnalyticDB for PostgreSQL (ADB-PG) instance, you must enable Vector Engine Optimization. Otherwise, Alibaba Cloud Model Studio cannot use the instance.
Audio/video search
- Use cases:
  - Build intelligent retrieval and Q&A applications based on audio and video content for use cases such as live replay Q&A, course assistants, and customer service quality inspection.
  - Repurpose multimodal content by retrieving audio and video clips from the knowledge base based on text requirements to generate scripts, subtitles, or editing suggestions.
- Select data connector: Select a data connector. To create one, see Data connectors.
- Data source integration: Upload audio and video files locally or import them from Object Storage Service (OSS). Supported audio formats: MP3, WAV, AAC, FLAC, OGG, M4A, and WMA. Supported video formats: MP4, AVI, MOV, MKV, FLV, and WMV.
  Audio/video search creation
  1. Select data: Specify a data source that contains audio and video files for the knowledge base. The system imports these files into the knowledge base for retrieval. You can use two methods: local upload and cloud import (by selecting an existing category or parsed files).
    Local upload: Directly upload and parse audio and video files from your computer. Expand the collapsible panel below to see the specific options for the parsing method.
    Parsing methods
    Audio and video parsing: The system performs speech recognition, video frame extraction (for videos only), and scene analysis (for videos only) on the files. All audio and visual information is then structurally aligned on a timeline. The parsing time is proportional to the file duration. A 30-minute audio file takes about 5 to 15 minutes, while a 1-hour video (including scene analysis) takes about 15 to 60 minutes.
    Speech recognition: This feature uses Speech-to-Text to convert speech into text. It does not support recognizing music or ambient sounds such as horns, bells, or thunder.
    Video frame extraction: Extracts representative frames from a video and generates corresponding text descriptions.
    Scene analysis (must be manually enabled): Analyzes video content to locate specific events, marks them with timestamps, and generates corresponding text descriptions. Enabling this option significantly increases parsing time.
    Cloud import: Import and parse audio and video files from an Alibaba Cloud Model Studio data connector or Object Storage Service (OSS).
  2. Index configuration: Defines how imported audio and video files are processed and stored. This configuration directly affects retrieval performance.
    Among the following settings, only vector storage with AnalyticDB for PostgreSQL (ADB-PG) may incur fees. All other settings are free.
    Chunking method
    The system splits text parsed from audio and video files into semantically complete chunks, converts each chunk into a vector using an embedding model, and stores the resulting chunks and vectors as key-value pairs in a vector database.
    Intelligent Splitting: The knowledge base first splits the text sequence into paragraphs based on built-in sentence delimiters and then creates chunks from these paragraphs. During this process, it maintains semantic integrity and minimizes unnecessary truncation. However, if a chunk exceeds the maximum segment length, the system truncates it.
    Metadata extraction
    Metadata consists of additional attributes related to audio and video files, which are attached to chunks as key-value pairs.
    Purpose: Metadata provides important context for chunks and can significantly improve retrieval accuracy. For example, consider an audio/video knowledge base with thousands of programming training videos (including Python, Java, and C++). When searching for Python basic syntax, if many courses contain the phrase basic syntax, the query might also retrieve irrelevant chunks from Java or C++ courses. By adding programming language type as metadata to the chunks of the corresponding videos, the knowledge base can accurately filter for chunks that both satisfy the programming language type=Python condition and contain basic syntax. This improves retrieval accuracy and reduces the model's input token consumption.
    Usage: When you call an application using an API, you can use the metadata_filter request parameter to specify metadata for filtering. The application then retrieves only the files that match the specified metadata.
    Note: You cannot configure metadata extraction after a knowledge base is created.
    Metadata configuration
    As shown in the figure, the metadata for this video file (including all its chunks) includes three custom attributes: teacher (the training video instructor), filename (the file name), and keywords (keywords that appear in the video).
    Enable Metadata extraction, and then click Settings to add uniform or personalized metadata to all files in the knowledge base. During chunking, each file's metadata is integrated into its respective chunks. The following figure shows the metadata template used in the example above:
    New metadata template
    Value extraction methods
    Constant: Attaches a fixed attribute to all audio and video files in the knowledge base.
    As shown in the preceding example, if all course videos in the knowledge base are taught by the same instructor, you can set a constant field named teacher and assign the instructor's name as the value for all videos.
    Variable: Attaches a variable attribute to each audio and video file in the knowledge base. Currently supported attributes are file_name and cat_name. If you select file_name, Alibaba Cloud Model Studio adds the file's name to its metadata (as shown in the preceding example). If you select cat_name, it adds the name of the file's category to its metadata.
    Keyword search: The system searches each audio and video file for preset keywords and adds the matched keywords as attributes to that file's metadata.
    For example, in the metadata template from the preceding example, the preset keywords are:
    Because only the keyword "Python" appeared in this audio/video file, the system only extracted "Python" as the value for the file's keywords attribute.
    Used for Retrieval: If enabled, metadata fields and values are used for knowledge base retrieval along with the chunk content. If disabled, only the chunk content is used for retrieval.
    Used for Model Reply: If enabled, metadata fields and values are provided to the LLM as input for response generation along with the chunk content. If disabled, only the chunk content is provided to the LLM for response generation.
    Multi-turn conversation rewriting
    When enabled, this feature uses a dedicated model to rewrite the user's query by incorporating conversation history. This process creates a complete, standalone query for knowledge base retrieval.
    graph TD; A[Query] --> C{Rewrite Model}; B[History] --> C; C --> D[Rewritten Query]; D --> E[KB Retrieval]
    Embedding model
    An embedding model is used to convert the original input prompt and chunks into numerical vectors to calculate their semantic similarity. The default Official Vector v4 (text-embedding-v4) model is a comprehensive upgrade over the Official Vector v3 (text-embedding-v3) model, offering improvements in language support, code snippet vectorization performance, and customizable vector dimensions. It is suitable for most scenarios. For more information, see Text and multimodal vectorization.
    The vector dimensions for each embedding model are fixed and cannot be modified:
    text-embedding-v4: 512 dimensions
    text-embedding-v3: 512 dimensions
    graph TD; subgraph Input; A[Prompt] --> C{Embedding Model} --> D[Prompt Vector]; end; subgraph Knowledge Base; B[Knowledge] --> C --> E[Knowledge Vector]; end; D --> F((Similarity)); E --> F
    Reranking model
    A reranking model is external to the knowledge base. It reranks the candidate chunks from the initial vector retrieval and returns the top K chunks with the highest similarity scores. The recommended official reranker, qwen3-rerank (hybrid), considers both semantic relevance and text-matching features (such as BM25 scores) to better handle queries that require precise keyword hits. If you only need semantic ranking, select qwen3-rerank.
    graph TD; A[Vector Retrieval] --> B{Candidates}; B --> C[Reranker]; C --> D[Top K Results]
    Reranking model mode
    When you create a knowledge base, you can select one of the following three modes for the reranking model:
    Q&A mode (default): Scores based on the "Q&A relevance" between the query and the candidate chunks. This mode is suitable for scenarios where users ask a complete question and expect to find the answer within a chunk.
    Similarity mode: Scores based on the "semantic similarity" between the query and the candidate chunks. This mode is suitable for scenarios where the query and the chunks have a similar style of expression.
    Custom advanced mode: Allows you to enter a natural language instruction of up to 200 characters to influence the reranking process. This mode is suitable for scenarios with special ranking requirements.
    Warning
    You can select a reranking model mode only when you create a knowledge base. You cannot change it after creation. Before you configure this setting, note the following limitations:
    Knowledge base type limitation: This feature is applicable only to document search, Data Query, and audio/video search knowledge bases. It is not supported for Image Q&A knowledge bases.
    Use case limitation: This feature is supported only for the Basic document Q&A and Rich-text Reply use cases. It is not supported for the visual understanding (rich-text documents) and Rapid Q&A use cases.
    Similarity threshold
    This threshold sets the minimum similarity score required for a chunk to be recalled from the reranking model's results.
    Note
    This is the default similarity threshold for the knowledge base. When you associate the knowledge base with a specific Alibaba Cloud Model Studio application, you can set a separate threshold for that application, which overrides the knowledge base's default threshold.
    Lowering this threshold recalls more chunks but may include less relevant content. Conversely, raising it recalls fewer chunks and may cause relevant ones to be discarded if set too high.
    You can use hit testing to fine-tune the similarity threshold to balance recall and precision.
    graph TD; A[Reranked Results] --> B{Filter by Threshold}; B --> |Keep| C[Final Results]; B --> |Discard| D[Discarded]
    Maximum recall count
    The system retrieves chunks related to the input from all associated knowledge bases, reranks them using a reranking model, and selects the top K most relevant chunks to add to the LLM input as context. This K value is the maximum recall count (up to 20), and it determines the number of chunks the reranking model provides to the LLM for context.
    Increasing this value can improve the LLM's response accuracy but also increases the LLM's input token consumption.
    Vector storage
    Select a vector database to store text vectors. The Built-in vector database is sufficient for basic knowledge base operations. For advanced capabilities such as database management, auditing, or monitoring, we recommend AnalyticDB for PostgreSQL (ADB-PG).
    When you purchase an AnalyticDB for PostgreSQL (ADB-PG) instance, you must enable Vector Engine Optimization. Otherwise, Alibaba Cloud Model Studio cannot use the instance.

You can select a use case based on your requirements, such as Basic document Q&A, Rich-text Reply, visual understanding (rich-text documents), or Rapid Q&A (for highly structured or simple document types with well-defined tasks, providing an extremely low-latency Q&A experience).

During peak hours, knowledge base creation can take several hours, depending on the data volume.

Update a knowledge base

Changes to a knowledge base are synchronized in real time with all referencing applications.

Document search

Automatic update (recommended)
You can use OSS to manage files and FC to listen for file change events. This setup automatically synchronizes your knowledge base. For more information, see Automate your AI knowledge base updates.
Manual update
On the Knowledge Base page, find the knowledge base that you want to update and click View Details on its card.
- To add new files: Click Upload Data and select existing files from the data connector.
- To delete a file: Find the file that you want to remove and click Delete to its right.
- To modify file content: In-place updates and overwrite uploads are not supported. You must first delete the old version of the file from the knowledge base, and then import the new version.
  Note: Failing to delete the old version may cause outdated content to appear in responses.
- Manage chunks: If you need to correct individual chunks or if key information is missing after parsing, you can edit chunks directly without re-uploading the entire file.
  - View chunks: On the knowledge base details page, you can view a list of all chunks in the current knowledge base. You can filter by document or search for chunk content.
  - Edit a chunk: You can directly modify the text content of a chunk that was parsed incorrectly or contains errors. Changes take effect immediately for future retrievals.
  - Add a chunk: If the chunking strategy missed a key piece of information from a file, you can manually add a new chunk. When adding a chunk, you must select the parent document and enter the chunk content (up to 6,000 characters). For image Q&A knowledge bases, you can also upload an associated image when you add a chunk.
  - Delete a chunk: You can individually delete chunks that contain incorrect or duplicate information without affecting the retrieval of other chunks from the same document.
  Note
  The supported chunk operations vary by knowledge base type. Editing a chunk (updating content) is supported for all knowledge base types. For adding and deleting chunks, document search, data query, and image Q&A knowledge bases support both operations. For audio and video search knowledge bases, only deleting chunks is supported. Chunk operations affect only the retrieval results of the knowledge base and do not modify the source files in data management.

Data query and image Q&A

Note: The details page for an image Q&A knowledge base does not have a direct Upload Data button. Click the View Data Source link to open the data connector details page and update the data.

Automatic update (recommended)
If you use an RDS database or a self-managed MySQL database to manage your knowledge data, your knowledge base synchronizes automatically. Synchronization typically takes minutes but can extend to hours during peak periods. For more information, see Integrate MySQL data into a knowledge base.
Manual update
If the data source for your knowledge base is a data table in Application Data, you must update it manually in two steps.
1. Step 1: Update the data table
  Go to the Application Data tab. In the left pane, select the target data table and click Upload Data.
  - To insert new data: Select Incremental Upload as the import type. You must upload an Excel file that contains only the header row and the new data rows.
    The file header must match the current table schema. You can click Download Template to get a template file with the standard header, and then add your new data to it.
  - To delete data: Select Upload and Overwrite as the import type. You must upload an Excel file that contains the header row and only the data records you want to keep.
    To get the full dataset, click the icon to download the data in XLSX format.
  - To modify data: Select Upload and Overwrite as the import type. You must upload an Excel file that contains the header row and the full, modified dataset.
2. Step 2: Synchronize the changes with the knowledge base
  Return to the Knowledge Base list, find the target knowledge base, and click View Details on its card. Click the icon in the upper-left corner of the data table and confirm the prompt to synchronize the data table's latest content with the knowledge base.
  You must repeat these steps for each manual update.

Audio and video search

Automatic update
Not supported.
Manual update
On the Knowledge Base page, find the knowledge base that you want to update and click View Details on its card.
- To add new files: Click Upload Data and select existing files from Application Data.
- To delete a file: Find the file that you want to remove and click Delete to its right.
  This action removes the file only from the knowledge base. It does not delete the source file in Application Data .
- To modify file content: In-place updates and overwrite uploads are not supported. You must first delete the old version of the file from the knowledge base, and then import the new version.
  Note: Failing to delete the old version may cause outdated content to appear in responses.

Edit knowledge base

After creating a knowledge base, you can only modify its knowledge base name, knowledge base description, and similarity threshold. To change any other settings, you must delete and recreate the knowledge base. This operation is available only in the console and does not have a corresponding API.

Procedure: On the Knowledge Base page, find the target knowledge base, click the icon on its card, and then click Edit. Note: You can modify a knowledge base's configuration only once per calendar day. Subsequent attempts will be silently rejected.

Delete a knowledge base

Warning

This action is irreversible.

Before deleting a knowledge base, we recommend disassociating it from all published Model Studio applications.

You can still delete a knowledge base associated with unpublished applications.

Procedure

For each published application associated with the knowledge base:
1. On the App Center page, find the application associated with the knowledge base and click Configure.
2. In the list of knowledge bases, remove the knowledge base. Click Publish in the upper-right corner of the page and republish the application as prompted.
On the Knowledge Base page, find the target knowledge base, click the icon on its card, and then click Delete.

Change configuration

The Enterprise Edition uses RCUs to ensure high retrieval performance at high QPS and supports greater storage capacity. The Standard Edition is suitable for development, testing, or low-concurrency scenarios.

Note

You can switch between the Standard Edition and the Enterprise Edition, and modify the RCU count for the Enterprise Edition.

You can change the configuration of a knowledge base only once per calendar day.

RCU: A Retrieval Compute Unit (RCU) is a measure of retrieval concurrency for a knowledge base. 1 RCU supports up to approximately 50 QPS for online retrieval. A higher RCU count supports greater concurrency.

Note:
- If an Enterprise Edition knowledge base uses platform storage, you must reduce its used storage space to below 80 GB before you can downgrade it to the Standard Edition.
  You can free up storage space by deleting files or data from the knowledge base.
Procedure:
1. On the Knowledge Base page, find the knowledge base to reconfigure. Click the icon on its card, and then click Edit.
2. In the dialog box, select an action based on the current edition:
  - Standard Edition: Select Upgrade.
  - Enterprise Edition: Select Downgrade or Change RCU Count.
3. Follow the on-screen instructions to complete the process. The new configuration takes effect immediately after you click OK.

Hit testing

Use hit testing to verify that your knowledge base provides accurate context for your AI application. This process involves simulating user queries, evaluating retrieval results, and fine-tuning the similarity threshold.

The reranking model in hit testing supports three modes: Q&A mode (default), designed for queries that do not perfectly match document content; similarity mode, ideal for queries that are highly similar to document content; and custom advanced mode. The ranking scores for the same query can vary significantly depending on the selected mode. For example, the same text segment might score 47% in Q&A mode but up to 69% in similarity mode.

With hit testing, you can:

Verify that the knowledge base provides effective context to your AI application
Fine-tune the similarity threshold to balance recall rate and accuracy
Identify content gaps or quality issues in your knowledge base

Use cases

Scenario 1: Querying product pricing

Test input: "How much does your Model Studio phone cost?"
Expected result: Retrieve relevant text segments that contain price information.

Scenario 2: Troubleshooting a technical issue

Test input: "What should I do if my device can't connect to Wi-Fi?"
Expected result: Retrieve relevant text segments about troubleshooting Wi-Fi connection issues.

Scenario 3: Retrieval with visual understanding

A visual understanding knowledge base supports three query modes: text-only, image-only, and image+text.
Mode 1 (text-only): Enter "Object Storage Service" to retrieve relevant segments from documents and images.
Mode 2 (image-only): Upload a product screenshot. The system uses visual understanding to match semantically similar segments.
Mode 3 (image+text): Upload an image and enter descriptive text. This combined query can improve retrieval relevance.

Scenario 4: Express Q&A

An Express Q&A knowledge base supports text-only queries (image input is not supported) and is ideal for fast retrieval from structured documents:
Test input: "What is the price of the Qwen Pro 8?"
Expected result: Quickly retrieve relevant FAQ segments that include price information.

Procedure

On the knowledge base page, click Hit Test on the target knowledge base's card.
In the test interface, enter a question—ideally a common one from your users—and review the retrieval results.
- Retrieval results: This section displays the current test's retrieval results, sorted by similarity in descending order. Click any text segment to view its content.
- Icon: For an image Q&A knowledge base, the system first converts the input image into a vector and retrieves relevant segments. It then sends these segments along with the question to an LLM to generate an answer. For document search, data query, or audio/video search knowledge bases, the system does not use the uploaded image for retrieval. However, a document search knowledge base configured for "visual understanding" does use the image for retrieval, supporting text-only, image-only, and image+text query modes. This combined query can improve retrieval relevance.
Verify that the relevant text segments are retrieved. If not, adjust the similarity threshold and repeat the previous step.
Click View Recall History to compare the retrieval performance across different threshold settings.

Rerank configuration

Where you configure reranking depends on how you call the knowledge base. Incorrect settings can prevent the feature from working or cause unexpected charges.

Legacy agent and workflow applications
On the application page, find the mounted knowledge base and click the Debug button to its right. On the page that appears, configure the Re-ranking Strategy switch.
Important
Configurations set within an application override those in the knowledge base itself.
New agent applications
1. On the knowledge base card, click Hit Test.
2. For Select Sorting Model, select Do Not Use Model.
3. Click Save.

Important

New agent applications call the knowledge base as a standard tool, so they use the knowledge base's own settings by default.

OpenAPI
- Console: Configurations made on the Edit or Hit Test page of the knowledge base.
- API: See Retrieve from knowledge base for parameter settings.
Important
Priority: API parameter settings override configurations made on the console page.

Logs and monitoring

For details about knowledge base retrieval call logs, field descriptions, SQL examples, and monitoring boundaries, see Knowledge base logs and monitoring.

Quotas and limits

For information about supported data sources, capacity, and other limits for a knowledge base, see Knowledge base quotas and limits.
The following limits apply when you associate knowledge bases with a Model Studio application:
- New agent application (Agent 2.0):
  - You can associate an unlimited number of knowledge bases of any type.
- Workflow application / legacy agent application (Agent 1.0):
  - Document search: Up to 5
  - Data query: Up to 5
  - Image Q&A: Up to 1
  - Audio and video search: Up to 5 (for legacy agent applications) / Not supported (for workflow applications)
  The total limit across multiple knowledge base types is 16 for legacy agent applications and 11 for workflow applications.

Billing

Knowledge bases use a pay-as-you-go model. Usage for each billable item is calculated hourly, and fees are automatically deducted from your Alibaba Cloud account. To prevent service interruptions from an overdue payment, ensure you maintain a sufficient account balance. You can add funds in Billing and Costs.

Billable item	Description
Specification fee	The fee for the actual runtime of a `Standard` or `Enterprise` knowledge base. For pricing details, see Knowledge base billing. Configuration changes trigger segmented billing based on the time of the change.
Embedding and rerank model call fees	You are charged for calling embedding and rerank models when creating, updating, or retrieving from a knowledge base. Billing is based on input token usage. For pricing, see the Model Call Billing page.

To view your bill, see Bill Details.

API reference

See the API directory (Knowledge Base) for a complete list of knowledge base APIs and their parameters.
See the Knowledge Base API guide for detailed usage and code examples.

FAQ

Building a knowledge base

Q: Can I delete a file or data table from Application Data after importing it into a knowledge base?
- For document search and audio/video search knowledge bases: Yes. Files in a knowledge base are independent of their source in Application Data. Deleting the source file does not affect the imported data.
- For data query and Image Q&A knowledge bases: No. Deleting the source data will break features like data synchronization and knowledge base viewing.
Q: What should I do if a knowledge base API call returns the BailianIndexServiceNotOpen error code?
The BailianIndexServiceNotOpen error code means you have not activated the Model Studio knowledge base service. Log in to the Model Studio console, go to the Data > Knowledge Base page, and click Activate Now to activate the service. Then, try the API call again.

Handling images and multimodal content

Q: My file contains illustrations that I want a Model Studio application to include in its responses. What should I do?

Document search

Method 1 (For agent applications only)

When you create a knowledge base, set the Knowledge Base Type to document search and the With Illustrations to With Illustrations.
When you select With Illustrations, the knowledge base extracts summaries from the illustrations in the file. The large language model then decides whether to insert an image based on the summary's relevance to the user's question.
Important
Do not select electronic document parsing when you upload documents. This parsing method does not recognize images, which prevents the With Illustrations feature from working correctly.
When you create or edit an agent application, select the Qwen-Plus or Qwen-Plus-Latest model (testing shows these models provide the best performance). Click the + button to the right of Document Knowledge Base and add the knowledge base you created in the previous step.
Note
The recall length must be shorter than the document length. If it is longer, the system returns the entire document and bypasses the With Illustrations logic.
Note: The "With Illustrations" and "Show Answer Source" features cannot be enabled simultaneously.
Actual Q&A result:

Method 2 (For agent and workflow applications)

Upload the image to a publicly accessible location and obtain its full URL. We recommend using OSS. For instructions, see Upload an image to OSS and use its file URL.

Insert the full URL into the file. Relative paths are not supported. Do not embed image files directly in the document (for example, by copying and pasting or by inserting a local image from a menu). You must reference images using their publicly accessible URLs.

If an image fails to display, ensure the URL in the chunk is complete. Remove any extra spaces or special characters that might cause parsing errors. You can edit the chunk directly to make these corrections.

Example of correctly referencing an image in a file

Sample prompt template

Actual Q&A result

# Knowledge Base
Please remember the following materials. They may be helpful for answering questions.
${documents}

# Requirements
If there are images, please display them.

Example of incorrectly referencing an image in a file

Sample prompt template

Actual Q&A result

# Knowledge Base
Please remember the following materials. They may be helpful for answering questions.
${documents}

# Requirements
If there are images, please display them.

Explanation: When you embed an image directly in a file, the Model Studio application does not display the image in its response.

Image Q&A

Upload the image to a publicly accessible location and obtain its full URL. We recommend using OSS. For instructions, see Upload an image to OSS and use its file URL.
On the Table tab, create a new data table and add a field of type image_url to store the full image URL.
Note
- The image_url field does not support relative paths.
- A single image_url field cannot store multiple image URLs. To associate a record with multiple images, create a separate image_url field for each one, such as image_1 and image_2.
- Each image referenced by an image_url field must be 3 MB or smaller. If an image exceeds this limit, knowledge base creation will fail.
- You cannot add or modify fields of type image_url after a data table is created. Therefore, you must include all required image fields during the initial table schema design.
When you create a knowledge base, set the Knowledge Base Type to Image Q&A.
When you create or edit an agent application, click the + button to the right of Image (Image Q&A knowledge base), add the knowledge base that you created, and then change the prompt template to:
```
# Knowledge Base
Please remember the following materials. They may be helpful for answering questions.
${documents}

# Requirements
If there are images, please display them.
```

Ask a question in the input box on the right side of the page.

For example: "Briefly introduce the Bailian X1 phone."

Example of correctly referencing an image

Sample prompt template

User prompt and Model Studio application response

# Knowledge Base
Please remember the following materials. They may be helpful for answering questions.
${documents}

# Requirements
If there are images, please display them.

Permissions and security

Q: What should I do if I get a "Missing permissions for this module" error when managing a knowledge base?
By default, RAM users cannot perform write operations such as creating, updating, or deleting knowledge bases. An Alibaba Cloud account must grant them the required page permissions, which must be either Administrator permissions or include at least both the Application Data-Actions and Knowledge Base-Actions permissions.
Q: Is a knowledge base private? Can other organizations or users access it?
A knowledge base is private to its workspace and can be accessed and managed only by members of that workspace.
Q: Will Alibaba Cloud use the knowledge bases in my account to answer other users' questions?
Alibaba Cloud is committed to data privacy and will not use your knowledge base data for model training or to answer other users' questions. For more information, see the Compliance & Privacy Statement.

Migration and export

Q: How do I export a knowledge base to my local machine?
One-click export is not currently supported. As a workaround, you can call the ListChunks API and write a script to retrieve document and chunk data in batches.

Q: How do I choose between a Long-Context LLM and RAG?

Both long-context large language models (like Qwen-Long) and RAG enhance output with external information, but they have distinct strengths. A long-context LLM analyzes the entire input, making it superior for tasks that require deep comprehension or summarization of long documents. However, this method is more computationally expensive. RAG, by contrast, uses efficient retrieval to pinpoint only the most relevant information. This makes it ideal for factual Q&A because it provides specific, current answers without processing the entire context.

Tutorials

Use Alibaba Cloud Model Studio to quickly build an online knowledge base Q&A application that answers user questions 24/7:

Supported models

How it works

Quick start

1. Build a knowledge base

2. Integrate with business applications

Agent application

Workflow application

External application

3. Optimize RAG performance (Optional)

How-to

Create a knowledge base

Metadata extraction

Excel header assembly

Chunking method

Multi-turn conversation rewriting

Embedding model

Reranking model

Similarity threshold

Maximum recall count

Vector storage

File format restrictions

Index configuration differences

Editing restrictions

Retrieval and reply settings

Multi-turn conversation rewriting

Embedding model

Reranking model

Similarity threshold

Maximum recall count

Vector storage

Retrieval and reply settings

Multi-turn conversation rewriting

Embedding model

Reranking model

Similarity threshold

Maximum recall count

Vector storage

Chunking method

Metadata extraction

Multi-turn conversation rewriting

Embedding model

Reranking model

Similarity threshold

Maximum recall count

Vector storage

Update a knowledge base

Document search

Data query and image Q&A

Audio and video search

Edit knowledge base

Delete a knowledge base

Change configuration

Hit testing

Use cases

Procedure

Rerank configuration

Logs and monitoring

Quotas and limits

Billing

API reference

FAQ

Building a knowledge base

Handling images and multimodal content

Document search

Image Q&A

Permissions and security

Migration and export

More

Tutorials