Knowledge base

A knowledge base supplements a large language model with private data and current information. Using retrieval-augmented generation (RAG), the model retrieves relevant content from the knowledge base to generate more accurate answers. Important

Console restrictions: Only International Edition users who created applications before April 21, 2025 can access the Application Development tab, as shown in the following figure.
This tab contains the following features: Applications ( agent application and workflow application), Components ( prompt engineering and plug-in), and Data ( knowledge base and application data). These are all preview features. Use them with caution in production environments.
API call limits: Only International Edition users who created applications before April 21, 2025 , can call the application data, knowledge base, and prompt engineering APIs.

Application without a dedicated knowledge base Without a dedicated knowledge base, an LLM cannot accurately answer domain-specific questions.	Application with a dedicated knowledge base With a dedicated knowledge base, an LLM can accurately answer domain-specific questions.

Supported models

The following models are compatible with a knowledge base. Configuring a knowledge base for Qwen

Qwen-Max/Plus/Turbo
QwenVL-Max/Plus
Qwen open-source version (e.g., Qwen2.5)

This list is subject to change. For the latest list, refer to the models available on the Application Management page when creating an application.

Quick start

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

1. Build a knowledge base

Go to the Knowledge Base page. Click Create Knowledge Base . Then, enter a Name and Description , leave the other settings as default, 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 link it to 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 the target agent application, click Configure on its card, and select a model for the application.
Click the + button to the right of Document to add the knowledge base you created in the previous step. You can use the default similarity threshold and weight.
(Optional) Similarity threshold: Filter retrieval results A knowledge base uses semantic search to find text in your private data or files that is relevant to a user's query, even if the keywords are completely different.
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 the retrieval order for multiple knowledge bases When an agent application is linked to multiple knowledge bases, you can assign a weight to each one based on the information source's importance. During multi-channel recall, if chunks retrieved 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 and filters for the most relevant chunks. It then multiplies the similarity score of these chunks by the weight of their corresponding knowledge base. After weighted reranking, the system provides the results to the LLM as context. Chunks with higher weighted scores are more likely to be used in the final answer.

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."

Workflow application

Go to the App Center page, find the target 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: In the Value drop-down list to the right of the content variable, select Built-in Variable. Expand the "Built-in Variable" group to select the query variable.
2. Select Knowledge Base: The Knowledge Base node supports the following selection methods.
  - 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 Introduction : Configure the CodeList variable to dynamically specify which knowledge bases to use based on the output of upstream nodes. Use this method to retrieve from different knowledge bases based on varying inputs.
3. Set TopK (Optional): Determines the number of knowledge 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. In the Model configuration list, select a model for the node.
2. In the Prompt field, enter a prompt that instructs the LLM to use the knowledge base. Enter / to insert the result variable, which represents the result returned by the knowledge base retrieval.
Configure the End node: Enter / and select to set the LLM's response as the final output.
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 in Alibaba Cloud Model Studio, you can use the retrieval capabilities of a knowledge base through the Model Studio SDK to provide retrieval services for external AI applications.

For detailed steps, see the Knowledge Base API Guide.

3. Optimize RAG performance (Optional)

If Q&A results are inaccurate or incomplete, see RAG performance optimization.

Operations

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

Knowledge base ID: The ID on each knowledge base card, used for API calls and other scenarios.

Create a knowledge base

Click Create Knowledge Base, follow the three-step process: provide basic information and select a knowledge base type, configure a data source, and set indexing parameters.

On the knowledge base page, click Create Knowledge Base.
Provide basic information
Select a Knowledge Base Type based on your application scenario. 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.
- Basic document Q&A: Ideal for semantic retrieval of plain-text documents.
- Rich-text Reply: Ideal for scenarios requiring responses that contain both text and images.
The knowledge base type cannot be changed after creation.
- Document search (for retrieval scenarios)
  - Use cases:
    - Suitable for retrieving unstructured data, such as internal corporate documents and product manuals. Unstructured data is not organized in a predefined table schema and can include text, tables, and images.
    - If your files contain images that you want your Alibaba Cloud Model Studio application to include in its responses, select document search.
  - Data source: You can upload local files or import them from Object Storage Service (OSS).
    Creation (document search)
    1. Select data: Specify a data source, which can include files or content, to import 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 (custom settings) Configure the parsing strategy as needed. If you are unsure which to choose, we recommend using the default settings.
        Digital Parsing: Does not support parsing illustrations or charts in files.
        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.
        LLM Parsing: Applications that use the Qwen-VL model can answer questions about the content of illustrations and charts in your files. To recognize and understand this content, select LLM Parsing.
        Qwen-VL parsing: This method is designed 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.
        /Set the table width to 60% of the screen/
        #tb1 {
        width: 60%;
        }
      - Cloud import: Import existing files from Object Storage Service (OSS).
    2. Index configuration: Define how imported data is processed and stored, which directly affects retrieval performance.
      Only vector storage with AnalyticDB for PostgreSQL (ADB-PG) may incur fees. All other configurations are free.
      Metadata extraction
      Metadata consists of additional attributes related to unstructured data. These attributes are integrated into chunks as key-value pairs.
      - Purpose: Metadata provides important context for chunks and can significantly improve retrieval accuracy. For example, consider a knowledge base that contains thousands of product introduction files where the file name is the product name. If a user searches for "functional overview of Product A," and 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 input token consumption for the model.
      - Usage: When you call an application via 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 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 templateValue 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 text content of each file in the knowledge base against the configured Entity Description rule to automatically identify and extract relevant information, which is then attached as attributes to the file's metadata.
        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, to extract all references that appear in each file (assuming the references start with 《 and end 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. Include in Retrieval: When enabled, the metadata fields and values are included in the knowledge base retrieval along with the chunk content. When disabled, only the chunk content is included in the retrieval.
      Include in Model Response: When enabled, the metadata fields and values are provided to the LLM to generate a response along with the chunk content. When disabled, only the chunk content is provided to the LLM to generate a response.
      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).
      Purpose: A knowledge base splits files into chunks and converts these chunks into vectors using an embedding model. The chunks and vectors are then stored as key-value pairs in a vector database. After creation, you can view or edit the specific content (text and images) of each chunk. Note: Once a knowledge base is created, the document chunking settings can no longer be changed. An inappropriate chunking strategy may reduce retrieval and recall performance.
      Multi-turn conversation rewriting
      When this feature is enabled, the system uses a dedicated lightweight model to rewrite the user's current query into a new, standalone query with complete context by incorporating the conversation history. This new query is then used for knowledge base retrieval.
      Embedding model
      An embedding model converts source prompts and knowledge text into numerical vectors to calculate their semantic similarity. The default Official Vector (text-embedding-v2) model supports multiple languages in addition to Chinese and English and normalizes the resulting vectors. This setting cannot be changed.
      The vector dimensions generated by (cannot be modified):
      - Official Vector (text-embedding-v2): 1,536 dimensions
      - qwen3 multimodal embedding (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.
      Reranking model
      A reranking model is external to the knowledge base. It reranks candidate chunks from the initial vector search 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.
      Similarity threshold
      This threshold sets the minimum similarity score for recalling a chunk from the results returned by the reranking model. Only chunks with scores exceeding this value are recalled. 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 also set a separate threshold for that application, which overrides the knowledge base's default threshold.
      Lowering this threshold is expected to recall more chunks but may include less relevant content. Raising it reduces the number of recalled chunks. If set too high, the knowledge base may discard relevant chunks.
      You can use hit testing to fine-tune the similarity threshold to balance recall and precision.
      Maximum recall count
      Suppose an Alibaba Cloud Model Studio application is associated with three knowledge bases: A1, A2, and A3. The system retrieves chunks related to the original input from these bases, reranks them by using a reranking model, and selects the top K most relevant chunks to include in the LLM's input tokens as context. This K value is the maximum recall count (up to 20), which determines the number of chunks the reranking model provides to the LLM as context.
      Increasing this value can improve the LLM's response accuracy but also increases input token consumption for the LLM.
      Vector storage
      Select a vector database to store text vectors. The Built-in vector database meets the basic functional needs of a knowledge base. For advanced features like database management, auditing, or monitoring, we recommend selecting AnalyticDB for PostgreSQL (ADB-PG). When you purchase an ADB-PG instance, you must enable Vector Engine Optimization. Otherwise, Alibaba Cloud Model Studio cannot use the instance. Creation (visual understanding) When you select the visual understanding (rich text document) use case, the system uses a multimodal embedding model to visually understand the document, preserving the original layout information instead of using a traditional chunking method.
    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 multimodal embedding (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 multimodal 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 (for Chatbot or NL2SQL scenarios)
  - 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 is difficult to achieve with a document search knowledge base.
    - You can import multiple Excel files, but their table schemas must be identical.
  - Data source integration: You can upload local XLS or XLSX files.
    Creation (Data Query)
    1. Select data: Specify the data source, which can include files or content, to import into the knowledge base for retrieval. You can use local upload or cloud import.
      Note
      The data source of a knowledge base cannot be changed after creation. A 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 .
    2. Index configuration: Define how imported data is processed and stored, which directly affects retrieval performance.
      Only vector storage with AnalyticDB for PostgreSQL (ADB-PG) may incur fees. All other configurations are free.
      Include in Retrieval/Include in Model Response
      - Used for Retrieval: When enabled, this option allows the knowledge base to perform retrieval on this column.
      - Used for Model Reply : When enabled, retrieval results from this column are provided to the LLM as context. 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 the knowledge base still cannot answer the question "What is Zhang San's age?".
      Multi-turn conversation rewriting
      When this feature is enabled, the system uses a dedicated lightweight model to rewrite the user's current query into a new, standalone query with complete context by incorporating the conversation history. This new query is then used for knowledge base retrieval.
      Embedding model
      An embedding model converts source prompts and knowledge text into numerical vectors to calculate their semantic similarity. The default Official Vector (text-embedding-v2) model supports multiple languages in addition to Chinese and English and normalizes the resulting vectors. This setting cannot be changed.
      The vector dimensions generated by (cannot be modified):
      - Official Vector (text-embedding-v2): 1,536 dimensions
      - qwen3 multimodal embedding (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.
      Reranking model
      A reranking model is external to the knowledge base. It reranks candidate chunks from the initial vector search 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.
      Similarity threshold
      This threshold sets the minimum similarity score for recalling a chunk from the results returned by the reranking model. Only chunks with scores exceeding this value are recalled. 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 also set a separate threshold for that application, which overrides the knowledge base's default threshold.
      Lowering this threshold is expected to recall more chunks but may include less relevant content. Raising it reduces the number of recalled chunks. If set too high, the knowledge base may discard relevant chunks.
      You can use hit testing to fine-tune the similarity threshold to balance recall and precision.
      Maximum recall count
      Suppose an Alibaba Cloud Model Studio application is associated with three knowledge bases: A1, A2, and A3. The system retrieves chunks related to the original input from these bases, reranks them by using a reranking model, and selects the top K most relevant chunks to include in the LLM's input tokens as context. This K value is the maximum recall count (up to 20), which determines the number of chunks the reranking model provides to the LLM as context.
      Increasing this value can improve the LLM's response accuracy but also increases input token consumption for the LLM.
      Vector storage
      Select a vector database to store text vectors. The Built-in vector database meets the basic functional needs of a knowledge base. For advanced features like database management, auditing, or monitoring, we recommend selecting AnalyticDB for PostgreSQL (ADB-PG).
      When you purchase an ADB-PG instance, you must enable Vector Engine Optimization. Otherwise, Alibaba Cloud Model Studio cannot use the instance.
- Image Q&A (for search-by-image scenarios)
  - 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.
  - Data source integration: You can upload local XLS or XLSX files.
    XLS and XLSX files must contain publicly accessible image URLs to build image indexes. For details, see the creation instructions below. Creation (Image Q&A)
    1. Select data: Specify a data source, which can include files or content, to import into the knowledge base for retrieval. You can use local upload or cloud import (select an existing data table from a data connector).
      Note
      The data source cannot be changed after creation, and a 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 image_url field 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.
    2. Index configuration: Define how imported data is processed and stored, which directly affects retrieval performance.
      Only vector storage with AnalyticDB for PostgreSQL (ADB-PG) may incur fees. All other configurations are free.
      Include in Retrieval/Include in Model Response
      - Used for Retrieval: When enabled, this option allows the knowledge base to perform retrieval on this column.
      - Used for Model Reply : When enabled, retrieval results from this column are provided to the LLM as context. 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 the knowledge base still cannot answer the question "What is Zhang San's age?".
      Multi-turn conversation rewriting
      When this feature is enabled, the system uses a dedicated lightweight model to rewrite the user's current query into a new, standalone query with complete context by incorporating the conversation history. This new query is then used for knowledge base 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 multimodal embedding (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 (multimodal-embedding-v1): Generates a separate vector for each input part (image and text).
      - qwen3 multimodal embedding (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 candidate chunks from the initial vector search 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.
      Similarity threshold
      This threshold sets the minimum similarity score for recalling a chunk from the results returned by the reranking model. Only chunks with scores exceeding this value are recalled. 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 also set a separate threshold for that application, which overrides the knowledge base's default threshold.
      Lowering this threshold is expected to recall more chunks but may include less relevant content. Raising it reduces the number of recalled chunks. If set too high, the knowledge base may discard relevant chunks.
      You can use hit testing to fine-tune the similarity threshold to balance recall and precision.
      Maximum recall count
      Suppose an Alibaba Cloud Model Studio application is associated with three knowledge bases: A1, A2, and A3. The system retrieves chunks related to the original input from these bases, reranks them by using a reranking model, and selects the top K most relevant chunks to include in the LLM's input tokens as context. This K value is the maximum recall count (up to 20), which determines the number of chunks the reranking model provides to the LLM as context.
      Increasing this value can improve the LLM's response accuracy but also increases input token consumption for the LLM.
      Vector storage
      Select a vector database to store text vectors. The Built-in vector database meets the basic functional needs of a knowledge base. For advanced features like database management, auditing, or monitoring, we recommend selecting AnalyticDB for PostgreSQL (ADB-PG).
      When you purchase an 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: Basic document Q&A , Rich-text Reply.

During peak request periods, creation can take several hours, depending on the data volume.

Update a knowledge base

Changes to a knowledge base synchronize in real time with all applications that use it.

Document search

Automatic update (recommended)
You can set up automatic updates by integrating the OSS, FC, and Model Studio knowledge base APIs. Follow these steps:
1. Create a bucket: Go to the OSS console and create an OSS bucket to store your source files.
2. Create a knowledge base: Create an unstructured knowledge base to store your private content.
3. Create a user-defined function: Go to the FC console and create a function to handle file change events, such as file creation and deletion. For more information, see Create a function. The function calls the relevant APIs from the Knowledge Base API Guide to synchronize your knowledge base with file changes in OSS.
4. Create an OSS trigger : In FC, associate an OSS trigger with the user-defined function that you created in the previous step. When a file change event occurs, such as a new file being uploaded to OSS, the trigger activates and runs the function in FC.
Manual update
On the Knowledge Base page, find the knowledge base 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 you want to remove and click Delete to its right.
- To modify file content: To modify file content, first delete the old version from the knowledge base, then import the updated version. In-place updates and overwrites are not supported.
  Note: Failure to remove the old version can lead to outdated search results.

Data query and image Q and 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 navigate to the data connector details page and update the data.

Automatic update
Not supported.
Manual update
If the data source for your knowledge base is a data table in Application Data, follow these two steps for manual updates.
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: Set the import type to Incremental Upload . Upload an Excel file that contains only the header row and the new data rows.
    The header row of the file must match the current table schema. You can click Download Template to get a standard template file, and then add your new data to it.
  - To delete data: Set the import type to Upload and Overwrite . Upload an Excel file that contains the header row and the latest full dataset, with the unwanted records removed.
    To get the full dataset, click the icon to download the data in XLSX format.
  - To modify data: Set the import type to Upload and Overwrite . Upload an Excel file that contains the header row and the full, modified dataset.
2. Step 2: Synchronize 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 then confirm the prompt to synchronize 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 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 you want to remove and click Delete to its right.
  This action only removes the file from the knowledge base; the source file in Application Data is not affected.
- To modify file content: To modify file content, first delete the old version from the knowledge base, then import the updated version. In-place updates and overwrites are not supported.
  Note: Failure to remove the old version can lead to outdated search results.

Edit knowledge base

After you create a knowledge base, you can modify only its knowledge base name , knowledge base description , and similarity threshold . To modify other configurations, you must delete and recreate the knowledge base. You can perform this operation only in the console, as there is no corresponding API.

Procedure: On the Knowledge Base page, find the 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. Further attempts on the same day are silently rejected, and no error message is displayed.

Delete a knowledge base

Warning

This action cannot be undone. Proceed with caution.

Before you delete a knowledge base, disassociate it from all published Model Studio applications. You can still delete a knowledge base that is associated with unpublished applications. Procedure

For each published application associated with the knowledge base:
1. On the My Applications page, find the associated application and click Configure.
2. Remove the knowledge base from the list, and then click Publish in the upper-right corner to republish the application.
On the Knowledge Base page, find the knowledge base that you want to delete, click the icon on its card, and then click Delete.

Change configuration

The Enterprise Edition uses RCUs for high retrieval performance at high QPS and supports a larger 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. You can also modify the RCU count for the Enterprise Edition.

You can change the configuration of a Knowledge Base only once per calendar day.

RCU: An RCU (Retrieval Compute Unit) is a measure of retrieval concurrency for a Knowledge Base. 1 RCU supports up to approximately 50 QPS for online retrieval. Higher RCU counts support greater concurrency.

Note:
- If an Enterprise Edition Knowledge Base uses platform storage, you must reduce its storage usage 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. 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. By simulating user queries, you can evaluate the retrieval results and fine-tune 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 for your AI application
Fine-tune the similarity threshold to balance the recall rate and accuracy
Identify content gaps or quality issues in your knowledge base

Scenarios

Scenario 1: Querying product pricing

HELPCODEESCAPE-plaintext
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

HELPCODEESCAPE-plaintext
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

HELPCODEESCAPE-plaintext
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 similarity.

Scenario 4: Express Q&A

HELPCODEESCAPE-plaintext
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, find the target knowledge base and click Hit Test on its 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 retrieval results from the current test, 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 records. It then sends these records along with the question to an LLM to generate an answer. Document search, data query knowledge bases do 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 similarity.
Verify that the retrieved text segments are correct. If not, adjust the similarity threshold and repeat the previous step.
Click View Recall History to compare the retrieval performance across different threshold settings.

Quotas and limits

See Knowledge base quotas and limits for information on supported data sources, capacity, and other limits.
The following limits apply when you associate knowledge bases with a Model Studio application:
- Document search: Up to 5
- Data query: Up to 5
- Image Q&A: Up to 1
You can associate multiple types of knowledge bases, with a total limit of 11.

Billing

The knowledge base feature itself is free, but you may be charged for calling an Alibaba Cloud Model Studio application that uses a knowledge base.

Step	Billing
Build a knowledge base	Free of charge.
Integrate with business applications	When you call an Alibaba Cloud Model Studio application, text chunks retrieved from the knowledge base increase the large language model's input token count, which can increase model inference (call) fees. For details, see Billable Items and Pricing. ** Note: You are not charged if you only call the Retrieve API to retrieve from a knowledge base and do not use an Alibaba Cloud Model Studio application to generate a response.
Management and O&M	Free of charge.

API reference

For a complete list of knowledge base APIs and their parameters, see the API Directory (Knowledge Base).
For detailed instructions and code examples for these APIs, refer to the Knowledge Base API Guide.

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 knowledge bases: Yes. Files in Application Data and files imported into a knowledge base are independent. Deleting a source file in Application Data does not affect the imported file.
For data query and Image Q&A knowledge bases: No. Deleting the source data causes features like data synchronization and knowledge base viewing to fail.

Handling images and multimodal content

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

Document search

Method 1 (For agent applications only)

When you create a knowledge base, select document search as the Knowledge Base Type and With Illustrations as the use case.
When you select With Illustrations, the knowledge base extracts summaries from the illustrations in the file. The large language model (LLM) 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 cannot extract image content, 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 (these models are recommended for optimal performance). Click the + button to the right of Document Knowledge Base, and add the knowledge base that you created in the previous step.
Note
The configured recall length must be less than the actual document length. If the recall length is greater than the document length, the system returns the entire document and bypasses the logic for the With Illustrations feature.
Note: The "With Illustrations" and "Show Answer Source" features cannot be enabled simultaneously.
Actual Q&A result:

Method 2 (For agent applications and workflow applications)

Upload an image to a publicly accessible location and get its full URL. We recommend using OSS. For instructions, see Upload an image to OSS and use its file URL.
Insert the full URL of the image into the file. Relative paths are not supported. Do not embed image files directly in a document (for example, by copying and pasting or inserting a local image from a menu). You must reference images using their publicly accessible URLs.
If an image fails to display even after following these instructions, verify that the URL in the chunk is complete. Check for and remove any extra spaces or special characters that could cause parsing errors. You can edit the chunk directly to make corrections. <b>Example of correctly referencing an image in a file** Sample prompt template Actual Q&A result

plaintext

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

plaintext

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

# Requirements
If there are images, please display them.

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

Image Q&A

Upload an image to a publicly accessible location and get 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 URL of the image.
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 image, such as image_1 and image_2.
- Each image referenced by an image_url field must be no larger than 3 MB. If this limit is exceeded, the knowledge base creation fails.
- After a data table is created, you cannot add new fields of type image_url or change the type of an existing field to image_url. You must include all required image fields when you first design the table schema.
When you create a knowledge base, select Image Q&A as the Knowledge Base Type.
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 in the previous step, and then change the prompt template to:
```
HELPCODEESCAPE-plaintext
# 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.
For example: "Briefly introduce the Model Studio X1 phone." Example of correctly referencing an image Sample prompt template User prompt and the result from the Model Studio application

plaintext

# 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: I received a "Missing permissions for this module" error when trying to manage a knowledge base. What should I do? By default, a RAM user cannot perform write operations such as creating, updating, or deleting a knowledge base. An Alibaba Cloud account must grant the RAM user page permissions for Administrator or, at a minimum, for both Application Data-Operations and Knowledge Base-Operations.
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 details, see our Compliance & Privacy Statement.

Migration and export

Q: How do I export a knowledge base to my local machine? Alternatively, you can write a script that calls the ListChunks API to retrieve the document and chunk data in batches.

Knowledge base ​

Supported models ​

Quick start ​

1. Build a knowledge base ​

2. Integrate with business applications ​

Agent application ​

Workflow application ​

External application ​

3. Optimize RAG performance (Optional) ​

Operations ​

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 ​

Include in Retrieval/Include in Model Response ​

Multi-turn conversation rewriting ​

Embedding model ​

Reranking model ​

Similarity threshold ​

Maximum recall count ​

Vector storage ​

Include in Retrieval/Include in Model Response ​

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 and A ​

Audio and video search ​

Edit knowledge base ​

Delete a knowledge base ​

Change configuration ​

Hit testing ​

Scenarios ​

Procedure ​

​

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 ​

Knowledge base

Supported models

Quick start

1. Build a knowledge base

2. Integrate with business applications

Agent application

Workflow application

External application

3. Optimize RAG performance (Optional)

Operations

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

Include in Retrieval/Include in Model Response

Multi-turn conversation rewriting

Embedding model

Reranking model

Similarity threshold

Maximum recall count

Vector storage

Include in Retrieval/Include in Model Response

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 and A

Audio and video search

Edit knowledge base

Delete a knowledge base

Change configuration

Hit testing

Scenarios

Procedure

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