---
sidebar_position: 0
slug: /
---

# Get started
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import APITable from '@site/src/components/APITable';

RAGFlow is an open-source RAG (Retrieval-Augmented Generation) engine based on deep document understanding. When integrated with LLMs, it is capable of providing truthful question-answering capabilities, backed by well-founded citations from various complex formatted data.

This quick start guide describes a general process from:

- Starting up a local RAGFlow server, 
- Creating a dataset, 
- Intervening with file parsing, to 
- Establishing an AI chat based on your datasets.

:::danger IMPORTANT
We officially support x86 CPU and Nvidia GPU, and this document offers instructions on deploying RAGFlow using Docker on x86 platforms. While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM.

If you are on an ARM platform, follow [this guide](./develop/build_docker_image.mdx) to build a RAGFlow Docker image.
:::

## Prerequisites

- CPU &ge; 4 cores (x86);
- RAM &ge; 16 GB;
- Disk &ge; 50 GB;
- Docker &ge; 24.0.0 & Docker Compose &ge; v2.26.1.
- [gVisor](https://gvisor.dev/docs/user_guide/install/): Required only if you intend to use the code executor ([sandbox](https://github.com/infiniflow/ragflow/tree/main/sandbox)) feature of RAGFlow.

:::tip NOTE
If you have not installed Docker on your local machine (Windows, Mac, or Linux), see [Install Docker Engine](https://docs.docker.com/engine/install/).
:::

## Start up the server

This section provides instructions on setting up the RAGFlow server on Linux. If you are on a different operating system, no worries. Most steps are alike.

1. Ensure `vm.max_map_count` &ge; 262144.

<details>
  <summary>Expand to show details:</summary>

   `vm.max_map_count`. This value sets the maximum number of memory map areas a process may have. Its default value is 65530. While most applications require fewer than a thousand maps, reducing this value can result in abnormal behaviors, and the system will throw out-of-memory errors when a process reaches the limitation.

   RAGFlow v0.23.1 uses Elasticsearch or [Infinity](https://github.com/infiniflow/infinity) for multiple recall. Setting the value of `vm.max_map_count` correctly is crucial to the proper functioning of the Elasticsearch component.

<Tabs
  defaultValue="linux"
  values={[
    {label: 'Linux', value: 'linux'},
    {label: 'macOS', value: 'macos'},
    {label: 'Windows', value: 'windows'},
  ]}>
  <TabItem value="linux">
   1.1. Check the value of `vm.max_map_count`:

   ```bash
   $ sysctl vm.max_map_count
   ```

   1.2. Reset `vm.max_map_count` to a value at least 262144 if it is not.

   ```bash
   $ sudo sysctl -w vm.max_map_count=262144
   ```

   :::caution WARNING
   This change will be reset after a system reboot. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception.
   :::
   
   1.3. 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
   ```
  </TabItem>
  <TabItem value="macos">
   If you are on macOS with Docker Desktop, run the following command to update `vm.max_map_count`:

   ```bash
   docker run --rm --privileged --pid=host alpine sysctl -w vm.max_map_count=262144
   ```

   :::caution WARNING
   This change will be reset after a system reboot. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception.
   :::

   To make your change persistent, create a file with proper settings:

   1.1. Create a file:

   ```shell
   sudo nano /Library/LaunchDaemons/com.user.vmmaxmap.plist
   ```

   1.2. Open the file:

   ```shell
   sudo launchctl load /Library/LaunchDaemons/com.user.vmmaxmap.plist
   ```

   1.3. Add settings:

   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
       <key>Label</key>
       <string>com.user.vmmaxmap</string>
       <key>ProgramArguments</key>
       <array>
           <string>/usr/sbin/sysctl</string>
           <string>-w</string>
           <string>vm.max_map_count=262144</string>
       </array>
       <key>RunAtLoad</key>
       <true/>
   </dict>
   </plist>
   ```

   1.4. After saving the file, load the new daemon:

   ```shell
   sudo launchctl load /Library/LaunchDaemons/com.user.vmmaxmap.plist
   ```

   :::note
   If the above steps do not work, consider using [this workaround](https://github.com/docker/for-mac/issues/7047#issuecomment-1791912053), which employs a container and does not require manual editing of the macOS settings.
   :::

  </TabItem>
  <TabItem value="windows">

   #### If you are on Windows with Docker Desktop, then you *must* use docker-machine to set `vm.max_map_count`:

   ```bash
   $ docker-machine ssh
   $ sudo sysctl -w vm.max_map_count=262144
   ```
   #### If you are on Windows with Docker Desktop WSL 2 backend, then use docker-desktop to set `vm.max_map_count`:

   1.1. Run the following in WSL: 
   ```bash
   $ wsl -d docker-desktop -u root
   $ sysctl -w vm.max_map_count=262144
   ```

   :::caution WARNING
   This change will be reset after you restart Docker. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception.
   :::

   1.2. If you prefer not to run those commands every time you restart Docker, you can update your `%USERPROFILE%.wslconfig` as follows to keep your change permanent and global for all WSL distributions:

   ```bash
   [wsl2]
   kernelCommandLine = "sysctl.vm.max_map_count=262144"
   ```
   *This causes all WSL2 virtual machines to have that setting assigned when they start.*

   :::note
   If you are on Windows 11 or Windows 10 version 22H2, and have installed the Microsoft Store version of WSL, you can also update the **/etc/sysctl.conf** within the docker-desktop WSL distribution to keep your change permanent:

   ```bash
   $ wsl -d docker-desktop -u root
   $ vi /etc/sysctl.conf
   ```

   ```bash
   # Append a line, which reads: 
   vm.max_map_count = 262144
   ```
   :::
  </TabItem>
</Tabs>

</details>

2. Clone the repo:

   ```bash
   $ git clone https://github.com/infiniflow/ragflow.git
   $ cd ragflow/docker
   $ git checkout -f v0.23.1
   ```

3. Use the pre-built Docker images and start up the server:

   ```bash
   # Use CPU for DeepDoc tasks:
   $ docker compose -f docker-compose.yml up -d
   ```

   ```mdx-code-block
   <APITable>
   ```

   | RAGFlow image tag   | Image size (GB) | Stable?                  |
   | ------------------- | --------------- | ------------------------ |
   | v0.23.1             | &approx;2       | Stable release           |
   | nightly             | &approx;2       | _Unstable_ nightly build |

   ```mdx-code-block
   </APITable>
   ```

   :::tip NOTE
   The image size shown refers to the size of the *downloaded* Docker image, which is compressed. When Docker runs the image, it unpacks it, resulting in significantly greater disk usage. A Docker image will expand to around 7 GB once unpacked.
   :::

4. Check the server status after having the server up and running:

   ```bash
   $ docker logs -f docker-ragflow-cpu-1
   ```

   _The following output confirms a successful launch of the system:_

   ```bash
        ____   ___    ______ ______ __
       / __ \ /   |  / ____// ____// /____  _      __
      / /_/ // /| | / / __ / /_   / // __ \| | /| / /
     / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ /
    /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/
   
    * Running on all addresses (0.0.0.0)
   ```

   :::danger IMPORTANT
   If you skip this confirmation step and directly log in to RAGFlow, your browser may prompt a `network anomaly` error because, at that moment, your RAGFlow may not be fully initialized.
   :::  

5. In your web browser, enter the IP address of your server and log in to RAGFlow.

   :::caution WARNING
   With the default settings, you only need to enter `http://IP_OF_YOUR_MACHINE` (**sans** port number) as the default HTTP serving port `80` can be omitted when using the default configurations.
   :::

## Configure LLMs

RAGFlow is a RAG engine and needs to work with an LLM to offer grounded, hallucination-free question-answering capabilities. RAGFlow supports most mainstream LLMs. For a complete list of supported models, please refer to [Supported Models](./references/supported_models.mdx).

:::note 
RAGFlow also supports deploying LLMs locally using Ollama, Xinference, or LocalAI, but this part is not covered in this quick start guide. 
:::

To add and configure an LLM: 

1. Click on your logo on the top right of the page **>** **Model providers**.

2. Click on the desired LLM and update the API key accordingly.

3. Click **System Model Settings** to select the default models: 

   - Chat model, 
   - Embedding model, 
   - Image-to-text model,
   - and more.

> Some models, such as the image-to-text model **qwen-vl-max**, are subsidiary to a specific LLM. And you may need to update your API key to access these models. 

## Create your first dataset

You are allowed to upload files to a dataset in RAGFlow and parse them into datasets. A dataset is virtually a collection of datasets. Question answering in RAGFlow can be based on a particular dataset or multiple datasets. File formats that RAGFlow supports include documents (PDF, DOC, DOCX, TXT, MD, MDX), tables (CSV, XLSX, XLS), pictures (JPEG, JPG, PNG, TIF, GIF), and slides (PPT, PPTX).

To create your first dataset:

1. Click the **Dataset** tab in the top middle of the page **>** **Create dataset**.

2. Input the name of your dataset and click **OK** to confirm your changes.

   _You are taken to the **Configuration** page of your dataset._

   ![dataset configuration](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/configure_knowledge_base.jpg)

3. RAGFlow offers multiple chunk templates that cater to different document layouts and file formats. Select the embedding model and chunking method (template) for your dataset. 

   :::danger IMPORTANT 
   Once you have selected an embedding model and used it to parse a file, you are no longer allowed to change it. The obvious reason is that we must ensure that all files in a specific dataset are parsed using the *same* embedding model (ensure that they are being compared in the same embedding space). 
   :::

   _You are taken to the **Dataset** page of your dataset._

4. Click **+ Add file** **>** **Local files** to start uploading a particular file to the dataset. 

5. In the uploaded file entry, click the play button to start file parsing:

   ![parse file](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/parse_file.jpg)

   :::caution NOTE 
   - If your file parsing gets stuck at below 1%, see [this FAQ](./faq.mdx#why-does-my-document-parsing-stall-at-under-one-percent).
   - If your file parsing gets stuck at near completion, see [this FAQ](./faq.mdx#why-does-my-pdf-parsing-stall-near-completion-while-the-log-does-not-show-any-error)
   :::

## Intervene with file parsing

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:_

   ![chunks](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/file_chunks.jpg)

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:

   ![update chunk](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/add_keyword_question.jpg)

   :::caution NOTE
   You can add keywords or questions to a file chunk to improve its ranking for queries containing those keywords. This action increases its keyword weight and can improve its position in search list.
   :::

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

   ![retrieval test](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/retrieval_test.jpg)

## Set up an AI chat

Conversations in RAGFlow are based on a particular dataset or multiple datasets. Once you have created your dataset and finished file parsing, you can go ahead and start an AI conversation.

1. Click the **Chat** tab in the middle top of the page **>** **Create chat** to create a chat assistant.
2. Click the created chat app to enter its configuration page.
   > RAGFlow offer 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 **Chat setting** on the right of the configuration page:

   - Name your assistant and specify your datasets.
   - **Empty response**:
     - If you wish to *confine* RAGFlow's answers to your datasets, 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 datasets, leave it blank, which may give rise to hallucinations.

3. Update **System prompt** or leave it as is for the beginning.

4. Select a chat model in the **Model** dropdown list.

5. Now, let's start the show:

   ![chat_thermal_solution](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/chat_thermal_solution.jpg)


:::tip NOTE
RAGFlow also offers HTTP and Python APIs for you to integrate RAGFlow's capabilities into your applications. Read the following documents for more information:

- [Acquire a RAGFlow API key](./develop/acquire_ragflow_api_key.md)
- [HTTP API reference](./references/http_api_reference.md)
- [Python API reference](./references/python_api_reference.md)
:::