DOCSEARCHbyAlgolia
Submit Docs

MiniRAG Documentation

repository·main·Indexed 24 days ago

https://github.com/hkuds/minirag

A lightweight RAG framework designed for Small Language Models (SLMs) using heterogeneous graph indexing and topology-enhanced retrieval. It features a FastAPI-based server with support for Ollama, LoLLMs, OpenAI, and Azure OpenAI backends, and provides an Ollama-compatible interface for integration with frontends like Open WebUI. The framework includes tools for document ingestion, REST API querying, and a dedicated dataset, LiHua-World, for RAG testing.

Tokens
7K
Snippets
12
Records
32
Agent score
84%

What's inside MiniRAG

  1. Overview of the LiHua-World Dataset

    main

    LiHua-World is a dataset specifically designed for local Retrieval-Augmented Generation (RAG) scenarios. It consists of one year of chat logs from a virtual user named 'LiHua', covering various aspects of daily life such as social interaction, fitness training, entertainment, and life affairs.

    The dataset includes three types of questions:

    • Single-hop questions
    • Multi-hop questions
    • Summary questions

    Each question is paired with a manually annotated answer and supporting evidence.

  3. MiniRAG Project Structure

    main

    The repository is organized as follows:

    • minirag/: The core library containing implementation details:
      • kg/: Knowledge Graph implementations (e.g., neo4j_impl.py, oracle_impl.py).
      • base.py, llm.py, minirag.py, etc.: Core logic for LLM interaction, storage, and operations.
    • reproduce/: Contains scripts for reproducing the research results (Step_0_index.py, Step_1_QA.py).
    • dataset/: Directory for storing datasets, including the LiHua-World benchmark.
    • main.py: Entry point for initializing MiniRAG via code.
    ├── dataset
│   └── LiHua-World
│       ├── README.md
│       ├── README_CN.md
│       ├── data
│       │   ├── LiHuaWorld.zip
│       └── qa
│           ├── query_set.csv
│           └── query_set.json
├── minirag
│   ├── kg
│   │   ├── __init__.py
│   │   ├── neo4j_impl.py
│   │   └── oracle_impl.py
│   ├── __init__.py
│   ├── base.py
│   ├── exceptions.py
│   ├── llm.py
│   ├── minirag.py
│   ├── operate.py
│   ├── prompt.py
│   ├── storage.py
│   └── utils.py
├── reproduce
│   ├── Step_0_index.py
│   └── Step_1_QA.py
├── LICENSE
├── main.py
├── README.md
├── README_CN.md
├── requirements.txt
└── setup.py

  4. Understand the LiHua-World Dataset structure

    main

    LiHua-World is a dataset designed for local RAG (Retrieval-Augmented Generation) testing, containing one year of chat records from a virtual user. The dataset is organized into three main components:

    1. Original Chat Records (/data): Chronological chat messages including timestamps, senders, content, and message types.
    2. Q&A Data (/qa): Used for testing RAG performance. It includes:
      • query_set.csv: Questions, standard answers, and evidence.
      • query_set.json: The JSON version of the query set.
      • Question types covered: Single-hop, Multi-hop, and Summary.
    3. Metadata: Contains user information, conversation participants, and the time range (January 2026 to December 2026).

  5. MiniRAG Code Structure

    main

    The repository is organized as follows:

    • minirag/: Core framework implementation.
      • kg/: Knowledge Graph implementations (e.g., neo4j_impl.py, oracle_impl.py).
      • base.py, llm.py, minirag.py, operate.py, prompt.py, storage.py, utils.py: Core logic components.
    • reproduce/: Scripts for reproducing results (Step_0_index.py, Step_1_QA.py).
    • dataset/: Contains datasets like LiHua-World.
    • main.py: Entry point for initializing MiniRAG.

  6. What is MiniRAG?

    main

    MiniRAG is a minimalist Retrieval-Augmented Generation (RAG) framework designed to enable Small Language Models (SLMs) to achieve high performance in resource-constrained scenarios.

    It achieves this through two key technical innovations:

    1. Semantic-aware Heterogeneous Graph Indexing: Combines text chunks and named entities into a unified structure, reducing reliance on complex semantic understanding.
    2. Lightweight Topology-enhanced Retrieval: Utilizes graph structures for efficient knowledge discovery without requiring advanced linguistic capabilities.

    MiniRAG is optimized for efficiency and effectiveness on edge devices, requiring only approximately 25% of the storage space compared to LLM-based methods while maintaining comparable performance.

  7. What is MiniRAG and how does it work?

    main

    MiniRAG is a lightweight Retrieval-Augmented Generation (RAG) framework designed to enable Small Language Models (SLMs) to achieve high performance in resource-constrained or on-device scenarios.

    Core Mechanisms

    • Semantic-aware Heterogeneous Graph Indexing: Combines text chunks and named entities into a unified structure. This reduces the heavy reliance on complex semantic understanding typically required by larger models.
    • Lightweight Topology-enhanced Retrieval: Uses graph structures to facilitate efficient knowledge discovery without requiring advanced language capabilities.

    Key Benefits

    • Efficiency: Achieves performance comparable to LLM-based methods while using only approximately 25% of the storage space.
    • Simplicity: Optimized for extreme simplicity and efficiency, making it suitable for deployment on devices with limited resources.

  8. LiHua-World Dataset Structure

    main

    The dataset is organized into three main components:

    1. Raw Chat Logs (./data): Chronologically organized chat messages. Messages are grouped into folders representing one week of chat history. Each message contains a timestamp, sender, content, and message type.
    2. QA Data (/qa): Contains the test queries. Available as query_set.csv (containing questions, standard answers, and evidence) or query_set.json.
    3. Metadata: Includes user information, the time range (January to December 2026), and a list of dialogue participants.

  9. LiHua-World Dataset

    main

    LiHua-World is a benchmark dataset specifically designed for on-device RAG scenarios. It contains one year of chat records from a virtual user named LiHua. The dataset includes three types of questions:

    • Single-hop
    • Multi-hop
    • Summary

    Each question is paired with manually annotated answers and supporting documents.

  10. Automatic Document Vectorization via --input-dir

    main

    When starting a server with the --input-dir parameter, MiniRAG enables automatic document processing.

    How it works:

    1. The system checks the database for existing vectorized content.
    2. It only vectorizes new documents found in the input directory that are not already in the database.
    3. This intelligent caching prevents unnecessary re-vectorization, reduces startup time, and preserves resources.

    Configuration:

    • --input-dir: Enables automatic processing of files in this directory at startup.
    • --working-dir: Specifies where the vectorized documents database is stored.

  11. Quick Start with MiniRAG

    main

    To run a complete RAG workflow (indexing and QA) using the provided reproduction scripts, follow these steps:

    1. Prepare the dataset: Download your desired knowledge base dataset and place it in the ./dataset directory.
      • Note: The LiHua-World dataset is already available at ./dataset/LiHua-World/data/ as LiHuaWorld.zip.
    2. Run Indexing: Execute the indexing script to build the heterogeneous graph index:
      python ./reproduce/Step_0_index.py
    3. Run QA: Execute the QA script to perform retrieval and generation:
      python ./reproduce/Step_1_QA.py

    Alternatively, you can initialize MiniRAG directly using the code in main.py.

    python ./reproduce/Step_0_index.py
python ./reproduce/Step_1_QA.py

  12. Configure MiniRAG backend services

    main

    Before running the MiniRAG server, ensure your LLM and embedding backend services are running. MiniRAG allows mixing different bindings (e.g., using Ollama for embeddings and OpenAI for the LLM).

    LoLLMs

    • Default connection: http://localhost:9600
    • Use --llm-binding-host or --embedding-binding-host to change the host/port.

    Ollama

    • Default connection: http://localhost:11434
    • Requires environment variables (LLM_BINDING=ollama, LLM_BINDING_HOST, LLM_MODEL) or command line arguments (--llm-binding=ollama, --llm-binding-host, --llm-model).
    • Note: The default MAX_TOKENS (num_ctx) for Ollama is 32768. If you encounter GPU memory issues, set this to a lower value.

    OpenAI Alike

    • Requires environment variables (LLM_BINDING=ollama, LLM_BINDING_HOST, LLM_MODEL, LLM_BINDING_API_KEY) or command line arguments (--llm-binding=ollama, --llm-binding-host, --llm-model, --llm-binding-api-key).
    • Default connection: https://api.openai.com/v1.

    Azure OpenAI

    • Requires setting environment variables for azure_openai binding:
      • LLM_BINDING=azure_openai
      • LLM_BINDING_HOST (the endpoint)
      • LLM_MODEL
      • LLM_BINDING_API_KEY