mirror of
https://github.com/infiniflow/ragflow.git
synced 2025-12-08 20:42:30 +08:00
Reorganized docs for docusaurus publish (#860)
### What problem does this PR solve? _Briefly describe what this PR aims to solve. Include background context that will help reviewers understand the purpose of the PR._ ### Type of change - [x] Documentation Update
This commit is contained in:
writinwaters
8
docs/guides/_category_.json
Normal file
8
docs/guides/_category_.json
Normal file
@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "User Guides",
|
||||
"position": 2,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "RAGFlow User Guides"
|
||||
}
|
||||
}
|
||||
137
docs/guides/configure_knowledge_base.md
Normal file
137
docs/guides/configure_knowledge_base.md
Normal file
@ -0,0 +1,137 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
slug: /configure_knowledge_base
|
||||
---
|
||||
|
||||
# Configure a knowledge base
|
||||
|
||||
Knowledge base, hallucination-free chat, and file management are three pillars of RAGFlow. RAGFlow's AI chats are based on knowledge bases. Each of RAGFlow's knowledge bases serves as a knowledge source, *parsing* files uploaded from your local machine and file references generated in **File Management** into the real 'knowledge' for future AI chats. This guide demonstrates some basic usages of the knowledge base feature, covering the following topics:
|
||||
|
||||
- Create a knowledge base
|
||||
- Configure a knowledge base
|
||||
- Search for a knowledge base
|
||||
- Delete a knowledge base
|
||||
|
||||
## Create knowledge base
|
||||
|
||||
With multiple knowledge bases, you can build more flexible, diversified question answering. To create your first knowledge base:
|
||||
|
||||
|
||||
|
||||
_Each time a knowledge base is created, a folder with the same name is generated in the **root/.knowledgebase** directory._
|
||||
|
||||
## Configure knowledge base
|
||||
|
||||
The following screen shot shows the configuration page of a knowledge base. A proper configuration of your knowledge base is crucial for future AI chats. For example, choosing the wrong embedding model or chunk method would cause unexpected semantic loss or mismatched answers in chats.
|
||||
|
||||
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- Select chunk method
|
||||
- Select embedding model
|
||||
- Upload file
|
||||
- Parse file
|
||||
- Intervene with file parsing results
|
||||
- Run retrieval testing
|
||||
|
||||
### Select chunk method
|
||||
|
||||
RAGFlow offers multiple chunking template to facilitate chunking files of different layouts and ensure semantic integrity. In **Chunk method**, you can choose the default template that suits the layouts and formats of your files. The following table shows the descriptions and the compatible file formats of each supported chunk template:
|
||||
|
||||
| **Template** | Description | File format |
|
||||
| ------------ | ------------------------------------------------------------ | ---------------------------------------------------- |
|
||||
| General | Files are consecutively chunked based on a preset chunk token number. | DOCX, EXCEL, PPT, PDF, TXT, JPEG, JPG, PNG, TIF, GIF |
|
||||
| Q&A | | EXCEL, CSV/TXT |
|
||||
| Manual | | PDF |
|
||||
| Table | | EXCEL, CSV/TXT |
|
||||
| Paper | | PDF |
|
||||
| Book | | DOCX, PDF, TXT |
|
||||
| Laws | | DOCX, PDF, TXT |
|
||||
| Presentation | | PDF, PPTX |
|
||||
| Picture | | JPEG, JPG, PNG, TIF, GIF |
|
||||
| One | The entire document is chunked as one. | DOCX, EXCEL, PDF, TXT |
|
||||
|
||||
You can also change the chunk template for a particular file on the **Datasets** page.
|
||||
|
||||
|
||||
|
||||
### Select embedding model
|
||||
|
||||
An embedding model builds vector index on file chunks. Once you have chosen an embedding model and used it to parse a file, you are no longer allowed to change it. To switch to a different embedding model, you *must* deletes all completed file chunks in the knowledge base. The obvious reason is that we must *ensure* that all files in a specific knowledge base are parsed using the *same* embedding model (ensure that they are compared in the same embedding space).
|
||||
|
||||
The following embedding models can be deployed locally:
|
||||
|
||||
- BAAI/bge-base-en-v1.5
|
||||
- BAAI/bge-large-en-v1.5
|
||||
- BAAI/bge-small-en-v1.5
|
||||
- BAAI/bge-small-zh-v1.5
|
||||
- jinaai/jina-embeddings-v2-base-en
|
||||
- jinaai/jina-embeddings-v2-small-en
|
||||
- nomic-ai/nomic-embed-text-v1.5
|
||||
- sentence-transformers/all-MiniLM-L6-v2
|
||||
- maidalun1020/bce-embedding-base_v1
|
||||
|
||||
### Upload file
|
||||
|
||||
- RAGFlow's **File Management** allows you to link a file to multiple knowledge bases, in which case each target knowledge base holds a reference to the file.
|
||||
- In **Knowledge Base**, you are also given the option of uploading a single file or a folder of files (bulk upload) from your local machine to a knowledge base, in which case the knowledge base holds file copies.
|
||||
|
||||
While uploading files directly to a knowledge base seems more convenient, we *highly* recommend uploading files to **File Management** and then linking them to the target knowledge bases. This way, you can avoid permanently deleting files uploaded to the knowledge base.
|
||||
|
||||
### Parse file
|
||||
|
||||
File parsing is a crucial topic in knowledge base configuration. The meaning of file parsing in RAGFlow is twofold: chunking files based on file layout and building embedding and full-text (keyword) indexes on these chunks. After having selected the chunk method and embedding model, you can start parsing an file:
|
||||
|
||||
|
||||
|
||||
- Click the play button next to **UNSTART** to start file parsing.
|
||||
- Click the red-cross icon and then refresh, if your file parsing stalls for a long time.
|
||||
- As shown above, RAGFlow allows you to use a different chunk method for a particular file, offering flexibility beyond the default method.
|
||||
- As shown above, RAGFlow allows you to enable or disable individual files, offering finer control over knowledge base-based AI chats.
|
||||
|
||||
### Intervene with file parsing results
|
||||
|
||||
RAGFlow features visibility and explainability, allowing you to view the chunking results and intervene where necessary. To do so:
|
||||
|
||||
1. Click on the file that completes file parsing to view the chunking results:
|
||||
|
||||
_You are taken to the **Chunk** page:_
|
||||
|
||||
|
||||
|
||||
2. Hover over each snapshot for a quick view of each chunk.
|
||||
|
||||
3. Double click the chunked texts to add keywords or make *manual* changes where necessary:
|
||||
|
||||
|
||||
|
||||
4. In Retrieval testing, ask a quick question in **Test text** to double check if your configurations work:
|
||||
|
||||
_As you can tell from the following, RAGFlow responds with truthful citations._
|
||||
|
||||
|
||||
|
||||
### Run retrieval testing
|
||||
|
||||
RAGFlow uses multiple recall of both full-text search and vector search in its chats. Prior to setting up an AI chat, consider adjusting the following parameters to ensure that the intended information always turns up in answers:
|
||||
|
||||
- Similarity threshold: Chunks with similarities below the threshold will be filtered. Defaultly set to 0.2.
|
||||
- Vector similarity weight: The percentage by which vector similarity contributes to the overall score. Defaultly set to 0.3.
|
||||
|
||||
|
||||
|
||||
## Search for knowledge base
|
||||
|
||||
As of RAGFlow v0.6.0, the search feature is still in a rudimentary form, supporting only knowledge base search by name.
|
||||
|
||||
|
||||
|
||||
## Delete knowledge base
|
||||
|
||||
You are allowed to delete a knowledge base. Hover your mouse over the three dot of the intended knowledge base card and the **Delete** option appears. Once you delete a knowledge base, the associated folder under **root/.knowledge** directory is AUTOMATICALLY REMOVED. The consequence is:
|
||||
|
||||
- The files uploaded directly to the knowledge base are gone;
|
||||
- The file references, which you created from within **File Management**, are gone, but the associated files still exist in **File Management**.
|
||||
|
||||
|
||||
75
docs/guides/deploy_local_llm.md
Normal file
75
docs/guides/deploy_local_llm.md
Normal file
@ -0,0 +1,75 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
slug: /deploy_local_llm
|
||||
---
|
||||
|
||||
# Deploy a local LLM
|
||||
|
||||
RAGFlow supports deploying LLMs locally using Ollama or Xinference.
|
||||
|
||||
## Ollama
|
||||
|
||||
One-click deployment of local LLMs, that is [Ollama](https://github.com/ollama/ollama).
|
||||
|
||||
### Install
|
||||
|
||||
- [Ollama on Linux](https://github.com/ollama/ollama/blob/main/docs/linux.md)
|
||||
- [Ollama Windows Preview](https://github.com/ollama/ollama/blob/main/docs/windows.md)
|
||||
- [Docker](https://hub.docker.com/r/ollama/ollama)
|
||||
|
||||
### Launch Ollama
|
||||
|
||||
Decide which LLM you want to deploy ([here's a list for supported LLM](https://ollama.com/library)), say, **mistral**:
|
||||
```bash
|
||||
$ ollama run mistral
|
||||
```
|
||||
Or,
|
||||
```bash
|
||||
$ docker exec -it ollama ollama run mistral
|
||||
```
|
||||
|
||||
### Use Ollama in RAGFlow
|
||||
|
||||
- Go to 'Settings > Model Providers > Models to be added > Ollama'.
|
||||
|
||||
|
||||
|
||||
> Base URL: Enter the base URL where the Ollama service is accessible, like, `http://<your-ollama-endpoint-domain>:11434`.
|
||||
|
||||
- Use Ollama Models.
|
||||
|
||||
|
||||
|
||||
## Xinference
|
||||
|
||||
Xorbits Inference([Xinference](https://github.com/xorbitsai/inference)) empowers you to unleash the full potential of cutting-edge AI models.
|
||||
|
||||
### Install
|
||||
|
||||
- [pip install "xinference[all]"](https://inference.readthedocs.io/en/latest/getting_started/installation.html)
|
||||
- [Docker](https://inference.readthedocs.io/en/latest/getting_started/using_docker_image.html)
|
||||
|
||||
To start a local instance of Xinference, run the following command:
|
||||
```bash
|
||||
$ xinference-local --host 0.0.0.0 --port 9997
|
||||
```
|
||||
### Launch Xinference
|
||||
|
||||
Decide which LLM you want to deploy ([here's a list for supported LLM](https://inference.readthedocs.io/en/latest/models/builtin/)), say, **mistral**.
|
||||
Execute the following command to launch the model, remember to replace ${quantization} with your chosen quantization method from the options listed above:
|
||||
```bash
|
||||
$ xinference launch -u mistral --model-name mistral-v0.1 --size-in-billions 7 --model-format pytorch --quantization ${quantization}
|
||||
```
|
||||
|
||||
### Use Xinference in RAGFlow
|
||||
|
||||
- Go to 'Settings > Model Providers > Models to be added > Xinference'.
|
||||
|
||||
|
||||
|
||||
> Base URL: Enter the base URL where the Xinference service is accessible, like, `http://<your-xinference-endpoint-domain>:9997/v1`.
|
||||
|
||||
- Use Xinference Models.
|
||||
|
||||
|
||||
|
||||
25
docs/guides/llm_api_key_setup.md
Normal file
25
docs/guides/llm_api_key_setup.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
slug: /llm_api_key_setup
|
||||
---
|
||||
|
||||
# Set your LLM API key
|
||||
|
||||
You have two ways to input your LLM API key.
|
||||
|
||||
## Before Starting The System
|
||||
|
||||
In **user_default_llm** of [service_conf.yaml](./docker/service_conf.yaml), you need to specify LLM factory and your own _API_KEY_.
|
||||
RagFlow supports the flowing LLM factory, and with more coming in the pipeline:
|
||||
|
||||
> [OpenAI](https://platform.openai.com/login?launch), [Tongyi-Qianwen](https://dashscope.console.aliyun.com/model),
|
||||
> [ZHIPU-AI](https://open.bigmodel.cn/), [Moonshot](https://platform.moonshot.cn/docs)
|
||||
|
||||
After sign in these LLM suppliers, create your own API-Key, they all have a certain amount of free quota.
|
||||
|
||||
## After Starting The System
|
||||
|
||||
You can also set API-Key in **User Setting** as following:
|
||||
|
||||
|
||||
|
||||
84
docs/guides/manage_files.md
Normal file
84
docs/guides/manage_files.md
Normal file
@ -0,0 +1,84 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
slug: /manage_files
|
||||
---
|
||||
|
||||
# Manage files
|
||||
|
||||
Knowledge base, hallucination-free chat, and file management are three pillars of RAGFlow. RAGFlow's file management allows you to upload files individually or in bulk. You can then link an uploaded file to multiple target knowledge bases. This guide showcases some basic usages of the file management feature.
|
||||
|
||||
## Create folder
|
||||
|
||||
RAGFlow's file management allows you to establish your file system with nested folder structures. To create a folder in the root directory of RAGFlow:
|
||||
|
||||
|
||||
|
||||
> Each knowledge base in RAGFlow has a corresponding folder under the **root/.knowledgebase** directory. You are not allowed to create a subfolder within it.
|
||||
|
||||
## Upload file
|
||||
|
||||
RAGFlow's file management supports file uploads from your local machine, allowing both individual and bulk uploads:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Preview file
|
||||
|
||||
RAGFlow's file management supports previewing files in the following formats:
|
||||
|
||||
- Documents (PDF, DOCS)
|
||||
- Tables (XLSX)
|
||||
- Pictures (JPEG, JPG, PNG, TIF, GIF)
|
||||
|
||||
|
||||
|
||||
## Link file to knowledge bases
|
||||
|
||||
RAGFlow's file management allows you to *link* an uploaded file to multiple knowledge bases, creating a file reference in each target knowledge base. Therefore, deleting a file in your file management will AUTOMATICALLY REMOVE all related file references across the knowledge bases.
|
||||
|
||||
|
||||
|
||||
You can link your file to one knowledge base or multiple knowledge bases at one time:
|
||||
|
||||
|
||||
|
||||
## Move file to specified folder
|
||||
|
||||
As of RAGFlow v0.6.0, this feature is *not* available.
|
||||
|
||||
## Search files or folders
|
||||
|
||||
As of RAGFlow v0.6.0, the search feature is still in a rudimentary form, supporting only file and folder search in the current directory by name (files or folders in the child directory will not be retrieved).
|
||||
|
||||
|
||||
|
||||
## Rename file or folder
|
||||
|
||||
RAGFlow's file management allows you to rename a file or folder:
|
||||
|
||||
|
||||
|
||||
|
||||
## Delete files or folders
|
||||
|
||||
RAGFlow's file management allows you to delete files or folders individually or in bulk.
|
||||
|
||||
To delete a file or folder:
|
||||
|
||||
|
||||
|
||||
To bulk delete files or folders:
|
||||
|
||||
|
||||
|
||||
> - You are not allowed to delete the **root/.knowledgebase** folder.
|
||||
> - Deleting files that have been linked to knowledge bases will AUTOMATICALLY REMOVE all associated file references across the knowledge bases.
|
||||
|
||||
## Download uploaded file
|
||||
|
||||
RAGFlow's file management allows you to download an uploaded file:
|
||||
|
||||
|
||||
|
||||
> As of RAGFlow v0.6.0, bulk download is not supported, nor can you download an entire folder.
|
||||
71
docs/guides/max_map_count.md
Normal file
71
docs/guides/max_map_count.md
Normal file
@ -0,0 +1,71 @@
|
||||
---
|
||||
sidebar_position: 7
|
||||
slug: /max_map_count
|
||||
---
|
||||
|
||||
# Update vm.max_map_count
|
||||
|
||||
## Linux
|
||||
|
||||
To check the value of `vm.max_map_count`:
|
||||
|
||||
```bash
|
||||
$ sysctl vm.max_map_count
|
||||
```
|
||||
|
||||
Reset `vm.max_map_count` to a value at least 262144 if it is not.
|
||||
|
||||
```bash
|
||||
# In this case, we set it to 262144:
|
||||
$ sudo sysctl -w vm.max_map_count=262144
|
||||
```
|
||||
|
||||
This change will be reset after a system reboot. To ensure your change remains permanent, add or update the `vm.max_map_count` value in **/etc/sysctl.conf** accordingly:
|
||||
|
||||
```bash
|
||||
vm.max_map_count=262144
|
||||
```
|
||||
|
||||
## Mac
|
||||
|
||||
```bash
|
||||
$ screen ~/Library/Containers/com.docker.docker/Data/vms/0/tty
|
||||
$ sysctl -w vm.max_map_count=262144
|
||||
```
|
||||
To exit the screen session, type Ctrl a d.
|
||||
|
||||
## Windows and macOS with Docker Desktop
|
||||
|
||||
The vm.max_map_count setting must be set via docker-machine:
|
||||
|
||||
```bash
|
||||
$ docker-machine ssh
|
||||
$ sudo sysctl -w vm.max_map_count=262144
|
||||
```
|
||||
|
||||
## Windows with Docker Desktop WSL 2 backend
|
||||
|
||||
To manually set it every time you reboot, you must run the following commands in a command prompt or PowerShell window every time you restart Docker:
|
||||
|
||||
```bash
|
||||
$ wsl -d docker-desktop -u root
|
||||
$ sysctl -w vm.max_map_count=262144
|
||||
```
|
||||
If you are on these versions of WSL and you do not want to have to run those commands every time you restart Docker, you can globally change every WSL distribution with this setting by modifying your %USERPROFILE%\.wslconfig as follows:
|
||||
|
||||
```bash
|
||||
[wsl2]
|
||||
kernelCommandLine = "sysctl.vm.max_map_count=262144"
|
||||
```
|
||||
This will cause all WSL2 VMs to have that setting assigned when they start.
|
||||
|
||||
If you are on Windows 11, or Windows 10 version 22H2 and have installed the Microsoft Store version of WSL, you can modify the /etc/sysctl.conf within the "docker-desktop" WSL distribution, perhaps with commands like this:
|
||||
|
||||
```bash
|
||||
$ wsl -d docker-desktop -u root
|
||||
$ vi /etc/sysctl.conf
|
||||
```
|
||||
and appending a line which reads:
|
||||
```bash
|
||||
vm.max_map_count = 262144
|
||||
```
|
||||
59
docs/guides/start_chat.md
Normal file
59
docs/guides/start_chat.md
Normal file
@ -0,0 +1,59 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
slug: /start_chat
|
||||
---
|
||||
|
||||
# Start an AI chat
|
||||
|
||||
Knowledge base, hallucination-free chat, and file management are three pillars of RAGFlow. Chats in RAGFlow are based on a particular knowledge base or multiple knowledge bases. Once you have created your knowledge base and finished file parsing, you can go ahead and start an AI conversation.
|
||||
|
||||
## Start an AI chat
|
||||
|
||||
You start an AI conversation by creating an assistant.
|
||||
|
||||
1. Click the **Chat** tab in the middle top of the page **>** **Create an assistant** to show the **Chat Configuration** dialogue *of your next dialogue*.
|
||||
|
||||
> RAGFlow offers you the flexibility of choosing a different chat model for each dialogue, while allowing you to set the default models in **System Model Settings**.
|
||||
|
||||
2. Update **Assistant Setting**:
|
||||
|
||||
- **Assistant name** is the name of your chat assistant. Each assistant corresponds to a dialogue with a unique combination of knowledge bases, prompts, hybrid search configurations, and large model settings.
|
||||
- **Empty response**:
|
||||
- If you wish to *confine* RAGFlow's answers to your knowledge bases, leave a response here. Then when it doesn't retrieve an answer, it *uniformly* responds with what you set here.
|
||||
- If you wish RAGFlow to *improvise* when it doesn't retrieve an answer from your knowledge bases, leave it blank, which may give rise to hallucinations.
|
||||
- **Show Quote**: This is a key feature of RAGFlow and enabled by default. RAGFlow does not work like a black box. instead, it clearly shows the sources of information that its responses are based on.
|
||||
- Select the corresponding knowledge bases. You can select one or multiple knowledge bases, but ensure that they use the same embedding model, otherwise an error would occur.
|
||||
|
||||
3. Update **Prompt Engine**:
|
||||
|
||||
- In **System**, you fill in the prompts for your LLM, you can also leave the default prompt as-is for the beginning.
|
||||
- **Similarity threshold** sets the similarity "bar" for each chunk of text. The default is 0.2. Text chunks with lower similarity scores are filtered out of the final response.
|
||||
- **Vector similarity weight** is set to 0.3 by default. RAGFlow uses a hybrid score system, combining keyword similarity and vector similarity, for evaluating the relevance of different text chunks. This value sets the weight assigned to the vector similarity component in the hybrid score.
|
||||
- **Top N** determines the *maximum* number of chunks to feed to the LLM. In other words, even if more chunks are retrieved, only the top N chunks are provided as input.
|
||||
- **Variable**:
|
||||
|
||||
4. Update **Model Setting**:
|
||||
|
||||
- In **Model**: you select the chat model. Though you have selected the default chat model in **System Model Settings**, RAGFlow allows you to choose an alternative chat model for your dialogue.
|
||||
- **Freedom** refers to the level that the LLM improvises. From **Improvise**, **Precise**, to **Balance**, each freedom level corresponds to a unique combination of **Temperature**, **Top P**, **Presence Penalty**, and **Frequency Penalty**.
|
||||
- **Temperature**: Level of the prediction randomness of the LLM. The higher the value, the more creative the LLM is.
|
||||
- **Top P** is also known as "nucleus sampling". See [here](https://en.wikipedia.org/wiki/Top-p_sampling) for more information.
|
||||
- **Max Tokens**: The maximum length of the LLM's responses. Note that the responses may be curtailed if this value is set too low.
|
||||
|
||||
5. Now, let's start the show:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Update settings of an existing dialogue
|
||||
|
||||
Hover over an intended dialogue **>** **Edit** to show the chat configuration dialogue:
|
||||
|
||||
|
||||
|
||||
## Integrate chat capabilities into your application
|
||||
|
||||
RAGFlow also offers conversation APIs. Hover over your dialogue **>** **Chat Bot API** to integrate RAGFlow's chat capabilities into your application:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user