> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/knowledge-base/km-basic-settings.md).

# Create a Knowledge Base: Basic Settings

## Basic Settings <a href="#basic-settings" id="basic-settings"></a>

### General Information <a href="#general-info" id="general-info"></a>

You can define the name of the knowledge base and add a description on the following page:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-54f12e2752ebeaec380a1b6a733f6924f051901b%2Fimage%20(162)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

#### Retrieved Chunks <a href="#retrieval-chunk" id="retrieval-chunk"></a>

The number of retrieved chunks represents the maximum number of data chunks the AI assistant will reference when answering. The system default is "12", meaning the AI assistant will retrieve the 12 most relevant chunks for each response.

You can increase or decrease the number of retrieved chunks to adjust the amount of information the AI assistant references when answering.

#### Force the Full Retrieval Range <a href="#force-full-retrieval-range" id="force-full-retrieval-range"></a>

When an AI assistant in Agent mode queries a knowledge base, the model decides how many chunks to retrieve. It may use fewer than the "Maximum Retrieved Chunks" setting. When you select <mark style="color:blue;">Force Full Retrieval Range</mark>, the system ignores the model's chosen count and supplies all results within the "Maximum Retrieved Chunks" range to the model.

This option is off by default. Find it under the AI assistant's <mark style="color:blue;">Settings</mark> → <mark style="color:blue;">Advanced Settings</mark> → <mark style="color:blue;">Knowledge Base Settings</mark>, below the <mark style="color:blue;">Maximum Retrieved Chunks</mark> field.

**When to enable it:**

* Your knowledge base contains long tables, such as plan comparisons, price lists, or specification tables, that are split into multiple chunks and require more chunks to answer fully
* Answers often cover only part of the information even though search tests find the other relevant chunks

**Trade-offs:**

* The model reads more chunks for each response, so response times may increase
* More chunks may include content that is less relevant to the question

{% hint style="info" %}
The actual number of chunks supplied is determined by "Maximum Retrieved Chunks." Keep it within the on-screen recommended range of 5–15, compare answers to the same questions before and after enabling the option, and then decide whether to keep it.
{% endhint %}

**Use case:** Sales assistant Ann notices that the "Implementation Consultation Assistant" sometimes lists only some plans when answering comparison questions. She enables "Force Full Retrieval Range" in the assistant's advanced settings and saves. She then asks in Internal Chat, "Using the plan comparison table, list the differences in features and quotas for each plan." After querying the knowledge base, the assistant presents the differences in a table.

{% stepper %}
{% step %}
Open <mark style="color:blue;">AI Assistants</mark>, click the edit icon beside the assistant you want to adjust, and open the <mark style="color:blue;">Settings</mark> tab.
{% endstep %}

{% step %}
In the left menu, click <mark style="color:blue;">Advanced Settings</mark>. In <mark style="color:blue;">Knowledge Base Settings</mark>, select <mark style="color:blue;">Force Full Retrieval Range</mark>.
{% endstep %}

{% step %}
Click <mark style="color:blue;">Save</mark> at the bottom right.
{% endstep %}

{% step %}
Switch to the <mark style="color:blue;">Conversation Platforms</mark> tab. Under <mark style="color:blue;">Internal Chat</mark>, click <mark style="color:blue;">Go to Chat</mark>, ask the question that previously received an incomplete answer, and compare the responses.
{% endstep %}
{% endstepper %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-657587a867164209f0854a690adb2045a9d81cb8%2Fagent-full-retrieval-range-setting.png?alt=media" alt="Knowledge Base Settings in AI assistant Advanced Settings with Force Full Retrieval Range selected and Maximum Retrieved Chunks set to 12"><figcaption><p>Select Force Full Retrieval Range under Knowledge Base Settings in Advanced Settings</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a7165323351509e378fc4747aafdd5997406059e%2Fagent-full-retrieval-range-chat.png?alt=media" alt="In Internal Chat, the Implementation Consultation Assistant uses the knowledge base and lists the plans&#x27; feature differences in a table"><figcaption><p>Ask in Internal Chat; the assistant queries the knowledge base and presents plan differences in a table</p></figcaption></figure>

{% hint style="warning" %}
If answer quality does not improve or responses become noticeably slower, clear the option and save to let the model choose how many chunks to use again.
{% endhint %}

#### Similarity Threshold <a href="#similarity-cutoff" id="similarity-cutoff"></a>

The similarity threshold excludes chunks that are not sufficiently relevant to the question. Chunks with a similarity score below the threshold will not be retrieved. Enter a value from `0` to `1` in increments of `0.01`. Leave it blank or set it to `0` to disable filtering.

{% hint style="warning" %}
A higher threshold narrows the retrieval results, but it may also exclude useful content. Make small adjustments each time and compare the search results using the same set of questions.
{% endhint %}

**Use case:** Customer service manager Ching notices that search tests for "return conditions" occasionally include unrelated delivery information. She first records the original retrieval results, then raises the similarity threshold and saves the setting. Finally, she tests again using the same question. If the return policy chunk still appears while the delivery information is excluded, she can keep this setting.

{% stepper %}
{% step %}
Go to <mark style="color:blue;">Knowledge Bases</mark> and click "Edit" on the right of the knowledge base you want to adjust.
{% endstep %}

{% step %}
Switch to <mark style="color:blue;">Retrieval Settings</mark>.
{% endstep %}

{% step %}
Enter a value in "Similarity Threshold (0–1)."
{% endstep %}

{% step %}
Click "Save," then use [Search Test](/maiagent-user-guide/en/build/knowledge-base/test-search-result.md) to retest the original question.
{% endstep %}
{% endstepper %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1f92b9392f40154090184d986cdae610b3ad7d56%2Fknowledge-base-similarity-threshold-prod.png?alt=media" alt="Similarity Threshold field in the knowledge base retrieval settings"><figcaption><p>Adjust the similarity threshold in Retrieval Settings</p></figcaption></figure>

### What Is a Parser? <a href="#what-is-parser" id="what-is-parser"></a>

A parser enables the system to "understand" the content in uploaded documents, making it searchable, editable, or convertible to other formats.

#### Document Parsers <a href="#document-parser" id="document-parser"></a>

When uploading PDF, Word, or other documents, you can choose from the following four parsers (the default for PDF, Word, and PPT is <mark style="color:blue;">Auto Detect (Default)</mark>; other formats default to MaiAgent Parser):

* **MaiAgent Parser**: Low cost, fast speed, suitable for plain text documents, supports 22 formats
* **MaiAgent Parser (Online)**: Uses LLM, can OCR-parse text in images, supports 20 formats
* **MaiAgent Parser (Offline)**: OCR + AI semantic understanding of images, best structure preservation, deployable on-premises, supports 20 formats
* **Vision Parser**: AI visual understanding, best image parsing results, supports 7 formats

{% hint style="info" %}
When uploading PDF, Word, or PPT files, the default value in the <mark style="color:blue;">Parser</mark> menu is <mark style="color:blue;">Auto Detect (Default)</mark>. After upload, the system selects a parser based on the file structure. Scanned files, PDFs with many image pages, Word files with embedded images, and PowerPoint files may use MaiAgent Parser (Online), MaiAgent Parser (Offline), or Vision Parser instead, and credits are charged according to that parser's pricing. The parser ultimately used appears in the <mark style="color:blue;">Parser</mark> column of the document list. If you later switch to a parser that has not previously been used for the file, the system reparses it and charges credits according to the new parser's pricing; credits charged for the previous parse are not refunded. MaiAgent Parser (Online) charges by the actual number of billable pages, and every reparse incurs another charge. To choose the parser and its pricing yourself, specify a parser when uploading. For pricing details, see [Technical Manual - Auto Detect (Default) and Parsing Charges](https://docs.maiagent.ai/tech/quickstart/parser#auto-detect-and-billing).
{% endhint %}

#### Speech-to-Text Parsers <a href="#speech-to-text-parser" id="speech-to-text-parser"></a>

When uploading audio files, you can choose from the following four speech-to-text parsers:

* **Azure Speech**: Real-time transcription with high accuracy
* **Whisper (Groq)**: Fastest speed, low cost
* **Whisper (OpenAI)**: Stable and reliable cloud solution
* **Whisper (Offline)**: Fully local deployment, free with data privacy protection

After audio parsing is complete, you can view the transcript via "View Document" and download the transcript file in TXT or SRT format.

{% hint style="info" %}
For a detailed comparison of each parser, refer to: [Technical Manual - Parser Tools](https://docs.maiagent.ai/tech/quickstart/parser)
{% endhint %}

If issues occur during data parsing, you can click the \[Re-parse] icon to have the parser reprocess the data.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b1c70f5112f57c1c727a73031f12536b2942a475%2F%E6%88%AA%E5%9C%96%202025-04-25%20%E4%B8%8A%E5%8D%8810.58.20.png?alt=media" alt=""><figcaption></figcaption></figure>

#### How to Adjust Documents with Complex Layouts <a href="#complex-layout-documents" id="complex-layout-documents"></a>

For documents such as product catalogs and specification sheets that contain two-column layouts, tables spanning multiple pages, and images, correct parsing does not guarantee that complete content will be retrieved for every question. We recommend checking each stage in order: parsing results → retrieval results → response results.

1. **Choose a parser suited to the content first**: Use the default parser for plain-text documents. When fields and table structures must be preserved, prioritize comparing the results from MaiAgent Parser (Offline). If the questions focus on labels in images, the appearance of parts, or relationships between images and text, compare the results from Vision Parser.
2. **Inspect the parsed Markdown**: Open "<mark style="color:blue;">View Document</mark>" on the document page and confirm that the reading order of the left and right columns, table titles, column names, row data, and image descriptions remain in the same section. If content is interleaved or missing at this stage, switch parsers and parse the document again. If necessary, convert the source document to a single-column layout, or save important tables separately as `.xlsx`, `.csv`, or Markdown files and upload them.
3. **Run search tests with representative questions**: Test the product name, exact fields in tables, and questions that require comparisons across rows. Confirm that the required data appears in the retrieved chunks. If the correct chunk falls outside the retrieval range, gradually increase the number of "Retrieved Chunks" and compare the results. Increasing the number of chunks also introduces more irrelevant content, so we do not recommend setting it to the maximum immediately.
4. **Make each chunk independently understandable**: If a table is split, add the product name, specification category, field names, and units to each section. For data that requires highly complete responses, you can also create an FAQ that organizes frequently asked comparison questions into complete question-and-answer pairs.
5. **Confirm the purpose of images**: A Parser can recognize text or visual semantics in images, but this does not guarantee that responses will automatically display the original images. If users must see an image, confirm that the parsed Markdown retains it and that the chunk containing the image is retrieved. Also test how it is displayed in the actual conversation channel being used. If you only need specification details from an image, include the key text, figure number, and image description in the document.

{% hint style="info" %}
Adjust only one setting at a time and rerun the [search test](/maiagent-user-guide/en/build/knowledge-base/test-search-result.md) with the same set of questions. This lets you determine whether the improvement comes from the parser, document content, or retrieval settings.
{% endhint %}

### Retrieval Model Settings <a href="#retrieval-model-settings" id="retrieval-model-settings"></a>

In the knowledge base settings, you can select the Embedding model and Reranker model you want to use.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-f2edcb10e65032ef8a72460780cddb6098e9ef98%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-18%20162323.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Embedding Model <a href="#embedding-model" id="embedding-model"></a>

Embedding is like translating human language into a "numerical language" that AI can understand, enabling computers to comprehend the true meaning of text. This process is called "vectorization." Different Embedding models have different characteristics, such as the languages they handle best and the deployment environments they support. Different model settings in the knowledge base can be used to adjust the vectorization results when documents are uploaded. You can choose the most suitable Embedding model for different scenarios.

You can freely choose from multiple Embedding models:

{% hint style="info" %}
For details on Embedding model differences, refer to: [Technical Manual - Embedding Models](https://docs.maiagent.ai/tech/quickstart/embedding#maiagent-zhi-yuan-de-embedding-mo-xing)
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b09e35c2979ba0975859ec2f9aad856413671c21%2Fimage%20(184).png?alt=media" alt=""><figcaption></figcaption></figure>

#### Reranker Model <a href="#reranker-model" id="reranker-model"></a>

A Reranker acts like a professional judge that re-evaluates which data best answers the customer's question from the initial search results. What is the difference between using a Reranker and not using one?

When a customer asks: "What tent is suitable for beginners? Budget under 8,000"

**Without Reranker:**

```
AI may respond:
"We have tents at various price points. Products at 8,000 include..."
(May mention advanced models, not targeted enough for beginner needs)
```

**With Reranker:**

```
AI responds:
"Here are some specially recommended tents under 8,000 for beginners..."
(Precisely targeted for beginners + budget + product recommendations)
```

When search result reranking is enabled, the AI assistant will re-sort the retrieved knowledge base chunks and respond based on the most relevant documents.

{% hint style="info" %}
For details on the Reranker model, refer to: [Technical Manual - Reranker Models](https://docs.maiagent.ai/tech/quickstart/reranker#maiagent-ti-gong-de-reranker-mo-xing)
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-f2edcb10e65032ef8a72460780cddb6098e9ef98%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-18%20162323.png?alt=media" alt=""><figcaption></figcaption></figure>

In summary, using Embedding combined with Reranker enables the AI assistant to understand the knowledge you provide, review content importance after retrieving chunks, and respond using the knowledge most relevant to the question.

***

### Associated AI Assistants <a href="#link-ai-agent" id="link-ai-agent"></a>

#### Multiple AI Assistants Sharing a Knowledge Base <a href="#multiple-agents-share-knowledge-base" id="multiple-agents-share-knowledge-base"></a>

Associating AI assistants means authorizing specific AI assistants to use this knowledge base. If you have two AI assistants:

* **Product Customer Service AI**
* **Order Customer Service AI**

When both need to answer return-related questions, you can associate both AI assistants under the "<mark style="color:blue;">Return Policy</mark>" knowledge base settings:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-050bc6e9b49de8ecd69ccc5d0719df2d8c5326fa%2Fplayma%20(2)%20(2).png?alt=media" alt=""><figcaption><p>Diagram of associating multiple AI assistants</p></figcaption></figure>

1. Select the AI assistants to associate

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-6d98094fcf1ad0c07772079cd71f5fe7af41e558%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-18%20170201.png?alt=media" alt=""><figcaption></figcaption></figure>

2. Click to add the AI assistant

After adding, it will appear in the selected AI assistants area. Click "Save" in the bottom-right corner to complete the association.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-fd3512cefd3322b580b117c929ffaad7d3dd5ded%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-19%20102309%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

Once associated, both AI assistants can share the "<mark style="color:blue;">Return Policy</mark>" knowledge base and respond based on the same content. For ongoing maintenance, you only need to **update one knowledge base** to ensure the AI assistants use the latest data.

#### One AI Assistant Using Multiple Knowledge Bases <a href="#one-agent-multiple-knowledge-bases" id="one-agent-multiple-knowledge-bases"></a>

In addition to sharing knowledge bases, a single AI assistant can also use multiple knowledge bases.

1. Go to the AI assistant page, select the AI assistant you want to configure, and click Settings

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-6b214953a8896226337054ea6d5afe4a5e4e7ebf%2Fimage%20(197).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-88c68e4bc4d8d3d06b484412c99830e620e59695%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-19%20105727%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>

2. Go to Model Settings and click "Select Knowledge Base"

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-493bafadb0a2a44fcf1eddbdccd7318ab181719d%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-19%20105930.png?alt=media" alt=""><figcaption></figcaption></figure>

3. Select the knowledge bases to use and click Confirm. The selected knowledge bases will appear in the list

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0f01116b66369c0080fc66acad7da442565bc6c0%2Fimage%20(200).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-4a63d4c894ab6f05bf8e923f527278338450dd1f%2Fimage%20(201).png?alt=media" alt=""><figcaption></figcaption></figure></div>

4. Finally, click "Save" and the AI assistant will be able to use multiple knowledge bases


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/knowledge-base/km-basic-settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.