DOCSEARCHbyAlgolia
Submit Docs

Hyper-RAG

repository·main·Indexed 43 days ago

https://github.com/imoonlab/hyper-rag

A hypergraph-driven Retrieval-Augmented Generation (RAG) method designed to capture complex, higher-order correlations in domain-specific knowledge to mitigate LLM hallucinations. It includes a full-stack Web UI built with React and FastAPI, featuring hypergraph visualization, document parsing for PDF/DOCX/TXT/Markdown, and a CRUD interface for managing vertices and hyperedges.

Tokens
7.7K
Snippets
30
Records
37
Agent score
55%

What's inside Hyper-RAG

  1. Explore HyperRAG Web UI Features

    main

    The Web UI provides several modules for interacting with the HyperRAG system:

    • Retrieval QA (Chat): An intelligent dialogue interface supporting three query modes: hyper, hyper-lite, and naive. It includes conversation history management.
    • Hypergraph Visualization (Graph): An interactive visualization tool using AntV G6 that supports node/hyperedge details, dynamic layouts, and zooming.
    • HypergraphDB Management (DB): A CRUD interface for managing Vertices and Hyperedges, including neighbor queries and relationship analysis.
    • Document Parsing (Files): A drag-and-drop interface for uploading PDF, DOCX, TXT, and Markdown files. It features real-time embedding progress monitoring via WebSockets.
    • System Settings: Configuration for LLM models (OpenAI and compatible APIs), embedding models, and database connections.
    • API Documentation: Interactive documentation provided by FastAPI.

  2. Monitor Real-time Progress via WebSockets

    main

    The HyperRAG Web UI uses WebSockets to provide real-time feedback for long-running tasks. This is primarily used for:

    • Log Monitoring: Real-time system logs.
    • Document Processing: Tracking the progress of file uploads and the embedding process.
    • System Status: Updates on the overall system state.

  3. Configure LLM and Embedding APIs

    main

    Before running Hyper-RAG, you must configure your LLM and Embedding API credentials.

    1. Copy the template file config_temp.py to my_config.py in the root directory.
    2. Edit my_config.py to set your LLM_BASE_URL, LLM_API_KEY, LLM_MODEL, EMB_BASE_URL, EMB_API_KEY, EMB_MODEL, and EMB_DIM.
    LLM_BASE_URL = "Yours xxx"
LLM_API_KEY = "Yours xxx"
LLM_MODEL = "gpt-4o-mini"

EMB_BASE_URL = "Yours xxx"
EMB_API_KEY = "Yours xxx"
EMB_MODEL = "text-embedding-3-small"
EMB_DIM = 1536

  6. Run the backend server in production mode

    main

    To run the backend server in the background (production-style) using nohup, first ensure your virtual environment is activated, then use fastapi run. This command redirects both standard output and error to server.log.

    source .venv/bin/activate
nohup fastapi run main.py > server.log 2>&1 &

  8. Install Hyper-RAG

    main

    To use Hyper-RAG, clone the repository and install the required Python dependencies using pip.

    # Clone this project
git clone https://github.com/iMoonLab/Hyper-RAG.git

# Access
cd Hyper-RAG

# Install dependencies
pip install -r requirements.txt
    git clone https://github.com/iMoonLab/Hyper-RAG.git
cd Hyper-RAG
pip install -r requirements.txt

  9. Deploy Hyper-RAG Web UI with Docker

    main

    You can deploy the Hyper-RAG Web-UI (including frontend, backend, and optional Nginx) using Docker Compose.

    1. Navigate to the web-ui directory.
    2. Run docker-compose up.
    3. Access the application at http://localhost:5000.
    cd web-ui
docker-compose up

  10. Deploy Hyper-RAG Web UI using Docker Compose

    main

    The recommended way to deploy the Hyper-RAG Web UI is using Docker Compose. This orchestrates both the Backend (FastAPI on port 8000) and the Frontend (React/Koa on port 5000) services.

    Navigate to the web-ui directory before running these commands.

    # Build and start all services
docker-compose up --build

# Run in background (detached mode)
docker-compose up -d --build

# Stop services
docker-compose down

  11. Build and run Hyper-RAG services individually

    main

    If you do not want to use Docker Compose, you can build and run the backend and frontend containers separately.

    Backend

    Builds the hyperrag-backend image and runs it with a volume mount for data persistence on port 8000.

    Frontend

    Builds the hyperrag-frontend image and runs it on port 5000.

    # Backend
cd backend
docker build -t hyperrag-backend .
docker run -p 8000:8000 -v $(pwd)/data:/app/data hyperrag-backend

# Frontend
cd frontend
docker build -t hyperrag-frontend .
docker run -p 5000:5000 hyperrag-frontend

  12. Run the backend server in development mode

    main

    To start the FastAPI backend server in development mode with auto-reload enabled, use the fastapi dev command. The server will typically start at http://127.0.0.1:8000 and you can access the interactive API documentation at http://127.0.0.1:8000/docs.

    fastapi dev main.py