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

Important

Console access restrictions: Only users who created Alibaba Cloud Model Studio applications in the Singapore region before April 21, 2025 can access the Application Development tab.

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 restrictions: Only users who created Alibaba Cloud Model Studio applications in the Singapore region 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 answer domain-specific questions accurately.

For example, when a user sends "Please help me pick the best camera phone from Alibaba Cloud Model Studio, within a budget of 3,000 yuan" in the chat interface, the AI assistant cannot provide accurate product recommendations due to the lack of a relevant knowledge base.

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

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

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

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 the Knowledge Base page 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).
  
  For example, enter the prompt title # Knowledge Base, and the body as Please remember the following materials {Knowledge Base 1/result}, they may be helpful for answering questions.
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, 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.
- 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.
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.
  - 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.
    
    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.
    
    Cloud import: Import existing files from 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
    
    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.
    
    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:
    
    In the Entity Description input box, enter date information, extract only the year, then click OK.
    
    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:
    
    Set the regular expression value to 《.*?》.
    
    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.
    
    Scope: This setting applies only to XLSX and XLS table files in the knowledge base, and it treats the first row of each file as the header. It does not apply to non-table formats such as PDF, Word, or Markdown. The setting takes effect when the knowledge base is created (during document chunking) and, like the chunking strategy, cannot be changed after the knowledge base is created.
    
    Processing logic: The knowledge base chunks table files by data row: each row other than the first (header) row becomes a separate chunk. When this setting is enabled, the header row is automatically appended to every data-row chunk, so that each chunk carries both the column names (header) and the row data. This lets the LLM interpret each field correctly based on its column name, and the header row is no longer processed as a regular data row, which avoids semantic confusion during retrieval and Q&A.
    
    You do not need to enable this setting if the knowledge base contains files in other formats, such as PDF, or if the table files do not contain a header row.
    
    Chunking method
    
    Select smart chunking (recommended).
    
    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.
    
    Chunk title: In addition to its body content, each chunk carries a title that is shown in the chunk list, used to identify the chunk, and included in retrieval. The knowledge base generates the chunk title automatically during intelligent document parsing, based on the heading hierarchy it detects. It has two forms: a short title (title, the nearest heading the chunk belongs to) and a hierarchical title (hier_title, the full path from the top-level heading down to the current heading, with levels joined by |>, for example Heading 1|>Heading 2). Therefore, the clearer a document's heading structure is (such as PDF, Word, or Markdown files with well-formed section headings), the more complete the generated chunk titles are; for table-like files that are split by data rows and usually lack a textual heading hierarchy (such as Excel), the chunk title depends on whether a heading hierarchy is detected during parsing, and may be empty when none is detected. You can also edit the chunk title manually in chunk management.
    
    Note: After a knowledge base is created, you cannot change the document chunking settings. An inappropriate chunking strategy may reduce retrieval and recall performance.
    
    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 (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 for are fixed and cannot be modified:
    
    Official Vector (text-embedding-v2): 1,536 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.
  - Data source integration: You can upload local XLS or XLSX files.
    Data query 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.
    
    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 .
    
    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.
    
    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 (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 for are fixed and cannot be modified:
    
    Official Vector (text-embedding-v2): 1,536 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.
  - 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.
    Image Q&A creation
    Select data: Specify a data source (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 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.
    
    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.
    
    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.
You can select a use case based on your requirements, such as Basic document Q&A, Rich-text Reply.

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 set up automatic updates by integrating OSS, FC, and the 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 runs the function in FC.
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.

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

Not supported.
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 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.

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:
- Document search: Up to 5
- Data query: Up to 5
- Image Q&A: Up to 1
The total limit across multiple knowledge base types is 11.

Billing

Using the knowledge base feature is free, but you may be charged for calling an Alibaba Cloud Model Studio application that uses it.

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 input token count for the LLM, increasing model inference fees. For more information, see Billable Items and Pricing. Note: You are not charged if you only use the Retrieve API for retrieval and do not use an Alibaba Cloud Model Studio application to generate a response.
Management and O&M	Free of charge.

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 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 image links, display them in full using markdown format.

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.

In the chat test interface, after entering a prompt, the AI response returns only plain text content without any images.

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.
The field Type supports string, double, long, datetime, and image_url. After configuration, you can upload xlsx or xls format files (no larger than 20 MB) in the Import Data area.
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

On the Alibaba Cloud Model Studio knowledge base data preview page, the Model Studio Phone data shows Import Successful. The structured data table contains three columns: Model (string), Description (string), and Image (image_url). In the sample data row, the model is Model Studio X1, the description field contains screen (6.7-inch 1440x3200 pixels 120Hz), storage (256GB+12GB RAM), battery (5000mAh), camera (Ultra-sensing quad camera), and reference price 4,599–4,999 yuan, with the image column being the corresponding image resource URL.

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

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)

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

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

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