MaxKB Beginner's Guide: Build Your Exclusive AI Knowledge Base Assistant from Scratch

Have you ever dreamed of having an AI chatbot that answers only questions related to your specific field of knowledge? An intelligent customer service that answers product questions for customers 24/7, or an internal assistant providing information retrieval for company employees? MaxKB is a powerful and open-source tool that can help you easily realize this vision.

This article is a beginner-friendly, extremely detailed guide. It will walk you through the installation and configuration of MaxKB, delve into how to create and optimize your knowledge base, and finally, dissect its most powerful "Advanced Application" feature, so you can truly master this powerful tool.

I. Installing MaxKB: Three Simple Steps, Even Beginners Can Do It

For beginners, server environment configuration is often the first hurdle. Don't worry, we'll use Baota Panel (also known as BT Panel) to simplify everything.

1. Prepare the Docker Environment Log in to your Baota Panel, find and click docker in the left menu bar. If this is your first time using it, the system will prompt you to install Docker. This is a fully automatic process; you just need to click confirm, make a cup of tea, and wait for it to complete the installation.

2. Execute the Installation Command Once the Docker environment is ready, click Terminal on the left side of the panel. This will open a command input window. Copy the following command, paste it in, and press Enter.

docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/var/lib/postgresql/data -v ~/.python-packages:/opt/maxkb/app/sandbox/python-packages registry.fit2cloud.com/maxkb/maxkb

What does this command do?

• docker run: This tells Docker to run a new container.
• -d: Runs the container quietly in the background.
• --name=maxkb: Gives your container a name called maxkb for easy management.
• --restart=always: Ensures that the container will automatically run even after the server restarts.
• -p 8080:8080: Maps the server's 8080 port to the container's 8080 port, allowing us to access MaxKB.
• -v ...: This is the most important step. It saves the data inside the container (such as the database and Python packages) to your local server, so that your data will not be lost even if the container is deleted.

3. Verify Installation Wait for the command to finish executing. Return to the docker management interface of the Baota Panel and click Container List. If you can see a container named maxkb and its status is "Running," then congratulations, MaxKB has been successfully installed and started!

II. Configure Nginx Reverse Proxy: Make Access More Professional

By default, you need to access MaxKB through an address like http://your_server_IP:8080, which is inconvenient to remember and not professional enough. Let's configure it so that you can access it through your own domain name (e.g., ai.xxx.com).

1. Create a Website In the Websites section of the Baota Panel, click Add Site. Create a purely static website, fill in the domain name you have prepared (e.g., ai.xxx.com), and the root directory will be automatically generated (e.g., /www/wwwroot/ai.xxx.com). Just create it. After successful creation, enter the root directory of the website (/www/wwwroot/ai.xxx.com) and manually create an empty folder named ui inside.

2. Modify the Nginx Configuration File Return to the website list, click Settings on the right side of the website you just created, and switch to the Configuration File tab. Find the line root /www/wwwroot/ai.xxx.com; and paste the following configuration code that we have prepared for you directly below it:

   # CORS Cross-Origin Settings
   add_header Access-Control-Allow-Origin '*' always;
   add_header Access-Control-Allow-Methods 'GET,POST,OPTIONS' always;
   add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,Access-Token,Token,formhash,shebei,token' always;
   # Handle OPTIONS preflight requests
   if ($request_method = 'OPTIONS') {
       return 204;
   }
   
   # Rule 1: Prioritize static UI resources, reverse proxy if not found
   location ^~ /ui/ {
       add_header Cache-Control "public, max-age=2592000, immutable";
       proxy_hide_header Content-Disposition; 
       try_files $uri $uri/ @backend_proxy;
   }
   
   # Rule 2: Capture all other api requests
   location / {     
     # Directly jump to the named location for proxying
     try_files $uri @backend_proxy;
   }
   
   location @backend_proxy {
       proxy_pass http://127.0.0.1:8080;
       proxy_set_header Host $http_host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Real-Port $remote_port;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Forwarded-Host $host;
       proxy_set_header X-Forwarded-Port $server_port;
       proxy_set_header REMOTE-HOST $remote_addr;
       
       proxy_connect_timeout 60s;
       proxy_send_timeout 600s;
       proxy_read_timeout 600s;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection $connection_upgrade;
   }

   After pasting, click Save.

3. Add Docker Volume Mapping (Crucial Step) The purpose of this step is to allow Nginx to directly access the front-end interface files inside the MaxKB container, realizing static and dynamic separation, which can greatly speed up page loading.

   • Go to Baota Panel docker -> Containers -> find the maxkb container -> click Manage -> Edit Container.
   • Click More Settings, click to view, and find the Mount/Mapping section.
   • Click Local Directory and add a new mapping rule:
     • Local Directory: Enter /www/wwwroot/ai.xxx.com/ui (which is the ui folder you created in step 1).
     • Container Directory: Enter /opt/maxkb/app/ui/dist/ui (this is the fixed path of the UI files inside the MaxKB container, just copy and paste it).
   • Scroll to the bottom of the page and click Save. The container will automatically restart to apply the new settings.

   Everything is ready! Now, open your browser and enter your domain name http://ai.xxx.com/ui. You should be able to see the MaxKB login interface.

III. Using a Custom Vector Model: m3e-base

What is a vector model? Simply put, it's like a "translator" that translates our text (like your documents and user questions) into mathematical language (vectors) that computers can understand. Only with accurate translation can the computer accurately find the most relevant content in your knowledge base.

Although MaxKB comes with a built-in vector model, we can replace it with a model that is better at processing Chinese, such as m3e-base.

1. Download Model Files: Visit the Hugging Face model page https://huggingface.co/moka-ai/m3e-base/tree/main and download all the files you see on the page to your computer.
2. Create and Upload the Model on the Server:
   • In the Files management of the Baota Panel, enter the / root directory, and then create the /opt/maxkb/model directories in sequence.
   • (Optional but Recommended) Return to the terminal and execute the command cd /opt/maxkb && docker cp maxkb:/opt/maxkb/model . to copy the default model from inside the container as a backup.
   • In the /opt/maxkb/model directory, create a new folder according to this hierarchy models--moka-ai--m3e-base, and then upload all the m3e-base model files you downloaded in the first step to this newly created m3e-base folder.

If you find it too troublesome to download the models one by one, you can directly use the script to download them. You must ensure that the server has Python 3.8+ and git tools installed, and then execute the following commands in sequence.

git clone https://github.com/LetheSec/HuggingFace-Download-Accelerator.git
cd  HuggingFace-Download-Accelerator
python3  hf_download.py --model moka-ai/m3e-base --save_dir  m3e-base
# After downloading, copy the `models--moka-ai--m3e-base` folder to the `/opt/maxkb/models` directory.

If your machine has a higher configuration, you can also use the m3e-small model, which will have better results. Just change all the base characters in the above example to small.

3. Mount the Model Directory to the Container: Similar to the previous step, edit the maxkb container again and add a new volume mapping:

   • Local Directory: /opt/maxkb/model
   • Container Directory: /opt/maxkb/model Save and wait for the container to restart.

4. Add a New Model in the MaxKB Backend: Log in to MaxKB, go to System Settings -> Model Settings -> Add Model, and select Local Model.

   • Model Name: You can name it anything, such as m3e.
   • Model Type: Be sure to select Vector Model.
   • Base Model and Model Directory: Fill in the absolute path of the model you uploaded: /opt/maxkb/model/models--moka-ai--m3e-base. To avoid errors, it is recommended to directly copy and paste this path. Click Save. If there are no errors, it means the addition was successful! If there is an error, 99% of the time it is because the path you entered does not match the actual path on the server. Please double-check it. Successful result:

IV. Add DeepSeek Large Language Model

If the vector model is the "librarian" helping you find information, then the large language model (LLM) is the "expert" who reads the information and organizes the language to answer your questions. Here we add a cost-effective DeepSeek model.

In Model Settings, click Add Model, select DeepSeek. Fill in a custom name (such as deepseek-chat), select the deepseek-chat model, and then fill in the API Key obtained from the DeepSeek website.

V. Creating a Knowledge Base and Important Considerations

This is the most critical part. The quality of the knowledge base directly determines the "intelligence" of your AI assistant.

1. Be Sure to Select the Correct Vector Model When Creating: Click Knowledge Base -> New Knowledge Base. In the creation interface, the most important step is the selection of the Vector Model. Please select the m3e that we just added. Once the knowledge base is created and the document is imported, if you want to change the model, it means that all the documents have to be deleted and redone, which is very time-consuming!

2. Knowledge Base Upload Rules:

   • Rule 1: Small Files, Upload in Batches. Although the system prompts that you can upload large files, unless your server is a "Tianhe-2," be sure to manually split large documents (such as a file larger than 20MB) into multiple small files. It is also best to control the number of files uploaded at one time to within 5, otherwise the next step of previewing may fail, causing it to be impossible to import.
   • Rule 2: Ignore "Fake Failures" and Check the Real Progress. When you upload a slightly larger file and start importing, the front-end page may display a red Failure prompt due to waiting timeout. Don't panic! This is usually a false alarm! The back-end vectorization task is actually still running diligently. You can ignore this prompt and go directly to the file list page of the knowledge base, where the real processing progress will be displayed. Of course, the best strategy is to follow the first rule and avoid this problem from the source.
   • Rule 3: Enable "Hybrid Retrieval". In the settings of the knowledge base, it is strongly recommended to enable "Hybrid Retrieval." It will use both semantic (understanding like a human) and keyword (like traditional search) methods to search, which can greatly increase the probability of finding the correct information.

VI. Creating Advanced Applications: Giving Your AI a "Brain"

Advanced Applications are the essence of MaxKB. They allow you to design the AI's workflow like building blocks. After entering the editing interface, you will see a flowchart canvas.

Operational Iron Rules:

1. Any modification to the canvas must be clicked Save in the upper right corner.
2. After saving, you must click Publish for your changes to take effect in the chat window.

Core Concepts: Nodes and Variables

• Nodes: Each block on the canvas is a "node," representing a function, such as "Start" or "Knowledge Base Retrieval." Each node has a Chinese name in the upper left corner, which we can modify.
• Variables: Nodes pass information to each other through "variables." The format of variables is fixed: \{\{Node Name.Output Variable Name\}\}.
  • Example: \{\{Start.question\}\} means: find the node named Start and get the value of an output variable named question. In the default process, this value is the question entered by the user. Similarly, \{\{Knowledge Base Retrieval.data\}\} is to get the knowledge fragments found by the Knowledge Base Retrieval node.

Detailed Explanation of the Default Process

1. Start: This is the starting point. When the user enters a sentence, this node packages it into a variable named question.
2. Knowledge Base Retrieval: This is the "librarian." Its "Retrieval Question" field needs to be filled with \{\{Start.question\}\}, telling it to search for information in the knowledge base based on the user's question. The information it finds will be packaged into the data variable.
3. Judge: This is the "traffic police." It directs the flow of the process according to the conditions. For example, it can determine whether Knowledge Base Retrieval.data is empty. If it finds information, it will take the IF branch; if it doesn't find it, it will take the ELSE branch.
4. AI Dialogue: This is the "expert." Its most important setting is the Prompt, which is the instruction given to the AI.

An excellent prompt template:

You are a professional customer service representative of XX company. Please strictly answer the user's [Question] based on the [Known Information] below. Do not use any of your own knowledge or fabricate anything. If there is no answer in the [Known Information], reply: "Sorry, I have not found relevant information about your question."

[Known Information]:
\{\{Knowledge Base Retrieval.data\}\}

[Question]:
\{\{Start.question\}\}

This template clearly tells the AI its role, the source of information, the basis for answering, and the standard reply when no answer is found.

Gameplay Upgrade: Using the "Function" Component

Suppose you want to automatically add a timestamp to each answer, what should you do? The "Function" node can help you achieve this!

Practical: Add a Timestamp to the AI's Answer

1. Add a Node: After the "AI Dialogue" node, drag a "Function" node from the component list on the right and connect them with the mouse.

2. Write Code: Click the "Function" node to set it up. In the code editor, paste the following Python code:

   import datetime
   
   # This is the fixed function entry point, ai_answer is the input parameter name we defined ourselves.
   def process(ai_answer: str) -> dict:
       # Get the AI's original answer
       # The variable name ai_answer can be chosen by yourself, but it must be consistent with the input parameter settings below.
       
       # Get the current Beijing time and format it
       beijing_time = datetime.datetime.utcnow() + datetime.timedelta(hours=8)
       time_str = beijing_time.strftime("%Y-%m-%d %H:%M:%S")
       
       # Concatenate the original answer and timestamp into a new text
       final_response = f"{ai_answer}\n\n---\n*This answer was generated by AI on {time_str}*"
       
       # Return the processing result in dictionary form
       # "response_with_timestamp" will become the output variable name of this function node
       return {"response_with_timestamp": final_response}

3. Configure Input Parameters: In the "Input Parameters" section of the function node, click "Add," fill in ai_answer for the parameter name (consistent with the code), and fill in \{\{AI Dialogue.answer\}\} for the parameter value. This step tells the function where its input data comes from.

4. Use Function Output: After this function is executed, it will generate a new variable named response_with_timestamp. Now, in the final "End" node of the process, change the value of its answer field from the original \{\{AI Dialogue.answer\}\} to \{\{Function.response_with_timestamp\}\}.

More functions can be found on the maxkb official forum: https://bbs.fit2cloud.com/t/topic/11004 More advanced application gameplay can be found in the forum post: https://bbs.fit2cloud.com/t/topic/7753

Through the above steps, you have successfully customized the AI's output! The power of MaxKB lies in this. Through the free combination of these nodes, you can create intelligent applications that meet various complex needs.